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.

.. versionadded:: 3.30 The generator is now available on non-Windows hosts, but requires Wine to run the Inno Setup tools.

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