cmake/Help/cpack_gen/innosetup.rst

CPack Inno Setup Generator
--------------------------

.. versionadded:: 3.27

Inno Setup is a free installer for Windows programs by Jordan Russell and
Martijn Laan (https://jrsoftware.org/isinfo.php).

This documentation explains Inno Setup generator specific options.

The generator provides a lot of options like components. Unfortunately, not
all features (e.g. component dependencies) are currently supported by
Inno Setup and they're ignored by the generator for now.

CPack requires Inno Setup 6 or greater and only works on Windows.

Variables specific to CPack Inno Setup generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can use the following variables to change the behavior of the CPack
``INNOSETUP`` generator:


General
"""""""

None of the following variables is required to be set for the Inno Setup
generator to work. If a variable is marked as mandatory below but not set,
its default value is taken.

The variables can also contain Inno Setup constants like ``{app}``. Please
refer to the documentation of Inno Setup for more information.

If you're asked to provide the path to any file, you can always give an
absolute path or in most cases the relative path from the top-level directory
where all files being installed by an :command:`install` instruction reside.

CPack tries to escape quotes and other special characters for you. However,
using special characters could cause problems.

The following variable simplifies the usage of Inno Setup in CMake:

.. variable:: CPACK_INNOSETUP_USE_CMAKE_BOOL_FORMAT

 Inno Setup only uses ``yes`` or ``no`` as boolean formats meanwhile CMake
 uses a lot of alternative formats like ``ON`` or ``OFF``. Having this option
 turned on enables an automatic conversion.

 Consider the following example:

 .. code-block:: cmake

  set(CMAKE_INNOSETUP_SETUP_AllowNoIcons OFF)

 If this option is turned on, the following line will be created in the output
 script: ``AllowNoIcons=no``.
 Else, the following erroneous line will be created: ``AllowNoIcons=OFF``

 The conversion is enabled in every Inno Setup specific variable.

 :Mandatory: Yes
 :Default: ``ON``


Setup Specific Variables
""""""""""""""""""""""""

.. variable:: CPACK_INNOSETUP_ARCHITECTURE

 One of ``x86``, ``x64``, ``arm64`` or ``ia64``. This variable specifies the
 target architecture of the installer. This also affects the Program Files
 folder or registry keys being used.

 CPack tries to determine the correct value with a try compile (see
 :variable:`CMAKE_SIZEOF_VOID_P`), but this option can be manually specified
 too (especially when using ``ia64`` or cross-platform compilation).

 :Mandatory: Yes
 :Default: Either ``x86`` or ``x64`` depending on the results of the try-compile

.. variable:: CPACK_INNOSETUP_INSTALL_ROOT

 If you don't want the installer to create the installation directory under
 Program Files, you've to specify the installation root here.

 The full directory of the installation will be:
 ``${CPACK_INNOSETUP_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY}``.

 :Mandatory: Yes
 :Default: ``{autopf}``

.. variable:: CPACK_INNOSETUP_ALLOW_CUSTOM_DIRECTORY

 If turned on, the installer allows the user to change the installation
 directory providing an extra wizard page.

 :Mandatory: Yes
 :Default: ``ON``

.. variable:: CPACK_INNOSETUP_PROGRAM_MENU_FOLDER

 The initial name of the start menu folder being created.

 If this variable is set to ``.``, then no separate folder is created,
 application shortcuts will appear in the top-level start menu folder.

 :Mandatory: Yes
 :Default: The value of :variable:`CPACK_PACKAGE_NAME`

.. variable:: CPACK_INNOSETUP_LANGUAGES

 A :ref:`semicolon-separated list <CMake Language Lists>` of languages you want
 Inno Setup to include.

 Currently available: ``armenian``, ``brazilianPortuguese``, ``bulgarian``,
 ``catalan``, ``corsican``, ``czech``, ``danish``, ``dutch``, ``english``,
 ``finnish``, ``french``, ``german``, ``hebrew``, ``icelandic``, ``italian``,
 ``japanese``, ``norwegian``, ``polish``, ``portuguese``, ``russian``,
 ``slovak``, ``slovenian``, ``spanish``, ``turkish`` and ``ukrainian``.
 This list might differ depending on the version of Inno Setup.

 :Mandatory: Yes
 :Default: ``english``

.. variable:: CPACK_INNOSETUP_IGNORE_LICENSE_PAGE

 If you don't specify a license file using
 :variable:`CPACK_RESOURCE_FILE_LICENSE`, CPack uses a file for demonstration
 purposes. If you want the installer to ignore license files at all, you can
 enable this option.

 :Mandatory: Yes
 :Default: ``OFF``

.. variable:: CPACK_INNOSETUP_IGNORE_README_PAGE

 If you don't specify a readme file using
 :variable:`CPACK_RESOURCE_FILE_README`, CPack uses a file for demonstration
 purposes. If you want the installer to ignore readme files at all, you can
 enable this option. Make sure the option is disabled when using
 a custom readme file.

 :Mandatory: Yes
 :Default: ``ON``

.. variable:: CPACK_INNOSETUP_PASSWORD

 Enables password protection and file encryption with the given password.

 :Mandatory: No

.. variable:: CPACK_INNOSETUP_USE_MODERN_WIZARD

 Enables the modern look and feel provided by Inno Setup. If this option is
 turned off, the classic style is used instead. Images and icon files are
 also affected.

 :Mandatory: Yes
 :Default: ``OFF`` because of compatibility reasons

.. variable:: CPACK_INNOSETUP_ICON_FILE

 The path to a custom installer ``.ico`` file.

 Use :variable:`CPACK_PACKAGE_ICON` to customize the bitmap file being shown
 in the wizard.

 :Mandatory: No

.. variable:: CPACK_INNOSETUP_SETUP_<directive>

 This group allows adapting any of the ``[Setup]`` section directives provided
 by Inno Setup where ``directive`` is its name.

 Here are some examples:

 .. code-block:: cmake

  set(CPACK_INNOSETUP_SETUP_WizardSmallImageFile "my_bitmap.bmp")
  set(CPACK_INNOSETUP_SETUP_AllowNoIcons OFF) # This requires CPACK_INNOSETUP_USE_CMAKE_BOOL_FORMAT to be on

 All of these variables have higher priority than the others.
 Consider the following example:

 .. code-block:: cmake

  set(CPACK_INNOSETUP_SETUP_Password "admin")
  set(CPACK_INNOSETUP_PASSWORD "secret")

 The password will be ``admin`` at the end because ``CPACK_INNOSETUP_PASSWORD``
 has less priority than ``CPACK_INNOSETUP_SETUP_Password``.

 :Mandatory: No


File Specific Variables
"""""""""""""""""""""""

Although all files being installed by an :command:`install` instruction are
automatically processed and added to the installer, there are some variables
to customize the installation process.

Before using executables (only ``.exe`` or ``.com``) in shortcuts
(e.g. :variable:`CPACK_CREATE_DESKTOP_LINKS`) or ``[Run]`` entries, you've to
add the raw file name (without path and extension) to
:variable:`CPACK_PACKAGE_EXECUTABLES` and create a start menu shortcut
for them.

If you have two files with the same raw name (e.g. ``a/executable.exe`` and
``b/executable.com``), an entry in the section is created twice. This will
result in undefined behavior and is not recommended.

.. variable:: CPACK_INNOSETUP_CUSTOM_INSTALL_INSTRUCTIONS

 This variable should contain a
 :ref:`semicolon-separated list <CMake Language Lists>` of pairs ``path``,
 ``instruction`` and can be used to customize the install command being
 automatically created for each file or directory.

 CPack creates the following Inno Setup instruction for every file...

 .. code-block::

  Source: "absolute\path\to\my_file.txt"; DestDir: "{app}"; Flags: ignoreversion

 ...and the following line for every directory:

 .. code-block::

  Name: "{app}\my_folder"

 You might want to change the destination directory or the flags of
 ``my_file.txt``. Since we can also provide a relative path, the line you'd
 like to have, is the following:

 .. code-block::

  Source: "my_file.txt"; DestDir: "{userdocs}"; Flags: ignoreversion uninsneveruninstall

 You would do this by using ``my_file.txt`` as ``path`` and
 ``Source: "my_file.txt"; DestDir: "{userdocs}"; Flags: ignoreversion uninsneveruninstall``
 as ``instruction``.

 You've to take care of the `escaping problem <https://cmake.org/cmake/help/book/mastering-cmake/chapter/Packaging%20With%20CPack.html#adding-custom-cpack-options>`_.
 So the CMake command would be:

 .. code-block:: cmake

  set(CPACK_INNOSETUP_CUSTOM_INSTALL_INSTRUCTIONS "my_file.txt;Source: \\\"my_file.txt\\\"\\; DestDir: \\\"{userdocs}\\\"\\; Flags: ignoreversion uninsneveruninstall")

 To improve readability, you should go around the escaping problem by using
 :variable:`CPACK_VERBATIM_VARIABLES` or by placing the instruction into a
 separate CPack project config file.

 If you customize the install instruction of a specific file, you lose the
 connection to its component. To go around, manually add
 ``Components: <component>``. You also need to add its shortcuts and ``[Run]``
 entries by yourself in a custom section, since the executable won't be found
 anymore by :variable:`CPACK_PACKAGE_EXECUTABLES`.

 Here's another example (Note: You've to go around the escaping problem for
 the example to work):

 .. code-block:: cmake

  set(CPACK_INNOSETUP_CUSTOM_INSTALL_INSTRUCTIONS
      "component1/my_folder" "Name: \"{userdocs}\\my_folder\"\; Components: component1"
      "component2/my_folder2/my_file.txt" "Source: \"component2\\my_folder2\\my_file.txt\"\; DestDir: \"{app}\\my_folder2\\my_file.txt\"\; Flags: ignoreversion uninsneveruninstall\; Components: component2")

 :Mandatory: No

.. variable:: CPACK_INNOSETUP_MENU_LINKS

 This variable should contain a
 :ref:`semicolon-separated list <CMake Language Lists>` of pairs ``link``,
 ``link name`` and can be used to add shortcuts into the start menu folder
 beside those of the executables (see :variable:`CPACK_PACKAGE_EXECUTABLES`).
 While ``link name`` is the label, ``link`` can be a URL or a path relative to
 the installation directory.

 Here's an example:

 .. code-block:: cmake

  set(CPACK_INNOSETUP_MENU_LINKS
      "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html"
      "CMake Help" "https://cmake.org" "CMake Web Site")

 :Mandatory: No

.. variable:: CPACK_INNOSETUP_CREATE_UNINSTALL_LINK

 If this option is turned on, a shortcut to the application's uninstaller is
 automatically added to the start menu folder.

 :Mandatory: Yes
 :Default: ``OFF``

.. variable:: CPACK_INNOSETUP_RUN_EXECUTABLES

 A :ref:`semicolon-separated list <CMake Language Lists>` of executables being
 specified in :variable:`CPACK_PACKAGE_EXECUTABLES` which the user can run
 when the installer finishes.

 They're internally added to the ``[Run]`` section.

 :Mandatory: No


Components Specific Variables
"""""""""""""""""""""""""""""

The generator supports components and also downloaded components. However,
there are some features of components that aren't supported yet (especially
component dependencies). These variables are ignored for now.

CPack will change a component's name in Inno Setup if it has a parent group
for technical reasons. Consider using ``group\component`` as component name in
Inno Setup scripts if you have the component ``component`` and its parent
group ``group``.

Here are some additional variables for components:

.. variable::  CPACK_INNOSETUP_<compName>_INSTALL_DIRECTORY

 If you don't want the component ``compName`` to be installed under ``{app}``,
 you've to specify its installation directory here.

 :Mandatory: No

.. variable:: CPACK_INNOSETUP_VERIFY_DOWNLOADS

 This option only affects downloaded components.

 If this option is turned on, the hashes of the downloaded archives are
 calculated during compile and
 download time. The installer will only proceed if they match.

 :Mandatory: Yes
 :Default: ``ON``


Compilation and Scripting Specific Variables
""""""""""""""""""""""""""""""""""""""""""""

.. variable:: CPACK_INNOSETUP_EXECUTABLE

 The filename of the Inno Setup Script Compiler command.

 :Mandatory: Yes
 :Default: ``ISCC``

.. variable:: CPACK_INNOSETUP_EXECUTABLE_ARGUMENTS

 A :ref:`semicolon-separated list <CMake Language Lists>` of extra
 command-line options for the Inno Setup Script Compiler command.

 For example: ``/Qp;/Smysigntool=$p``

 Take care of the `escaping problem <https://cmake.org/cmake/help/book/mastering-cmake/chapter/Packaging%20With%20CPack.html#adding-custom-cpack-options>`_.

 :Mandatory: No

.. variable:: CPACK_INNOSETUP_DEFINE_<macro>

 This group allows to add custom define directives as command-line options to
 the Inno Setup Preprocessor command. Each entry emulates a
 ``#define public <macro>`` directive. Its macro is accessible from anywhere
 (``public``), so it can also be used in extra script files.

 Macro names must not contain any special characters. Refer to the Inno Setup
 Preprocessor documentation for the detailed rules.

 Consider the following example:

 .. code-block:: cmake

  # The following line emulates: #define public MyMacro "Hello, World!"
  set(CPACK_INNOSETUP_DEFINE_MyMacro "Hello, World!")

 At this point, you can use ``MyMacro`` anywhere. For example in the following
 extra script:

 .. code-block::

  AppComments={#emit "'My Macro' has the value: " + MyMacro}

 Take care of the `escaping problem <https://cmake.org/cmake/help/book/mastering-cmake/chapter/Packaging%20With%20CPack.html#adding-custom-cpack-options>`_.

 :Mandatory: No

.. variable:: CPACK_INNOSETUP_EXTRA_SCRIPTS

 A :ref:`semicolon-separated list <CMake Language Lists>` of paths to
 additional ``.iss`` script files to be processed.

 They're internally included at the top of the output script file using a
 ``#include`` directive.

 You can add any section in your file to extend the installer (e.g. adding
 additional tasks or registry keys). Prefer using
 :variable:`CPACK_INNOSETUP_SETUP_<directive>` when extending the
 ``[Setup]`` section.

 :Mandatory: No

.. variable:: CPACK_INNOSETUP_CODE_FILES

 A :ref:`semicolon-separated list <CMake Language Lists>` of paths to
 additional Pascal files to be processed.

 This variable is actually the same as
 :variable:`CPACK_INNOSETUP_EXTRA_SCRIPTS`, except you don't have to
 add ``[Code]`` at the top of your file. Never change the current section in
 a code file. This will result in undefined behavior! Treat them as normal
 Pascal scripts instead.

 Code files are included at the very bottom of the output script.

 :Mandatory: No