code:
CPack External Generator
------------------------

.. versionadded:: 3.13

CPack provides many generators to create packages for a variety of platforms
and packaging systems. The intention is for CMake/CPack to be a complete
end-to-end solution for building and packaging a software project. However, it
may not always be possible to use CPack for the entire packaging process, due
to either technical limitations or policies that require the use of certain
tools. For this reason, CPack provides the "External" generator, which allows
external packaging software to take advantage of some of the functionality
provided by CPack, such as component installation and the dependency graph.

Integration with External Packaging Tools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The CPack External generator generates a ``.json`` file containing the
CPack internal metadata, which gives external software information
on how to package the software. External packaging software may itself
invoke CPack, consume the generated metadata,
install and package files as required.

Alternatively CPack can invoke an external packaging software
through an optional custom CMake script in
:variable:`CPACK_EXTERNAL_PACKAGE_SCRIPT` instead.

Staging of installation files may also optionally be
taken care of by the generator when enabled through the
:variable:`CPACK_EXTERNAL_ENABLE_STAGING` variable.

JSON Format
^^^^^^^^^^^

The JSON metadata file contains a list of CPack components and component groups,
the various options passed to :command:`cpack_add_component` and
:command:`cpack_add_component_group`, the dependencies between the components
and component groups, and various other options passed to CPack.

The JSON's root object will always provide two fields:
``formatVersionMajor`` and ``formatVersionMinor``, which are always integers
that describe the output format of the generator. Backwards-compatible changes
to the output format (for example, adding a new field that didn't exist before)
cause the minor version to be incremented, and backwards-incompatible changes
(for example, deleting a field or changing its meaning) cause the major version
to be incremented and the minor version reset to 0. The format version is
always of the format ``major.minor``. In other words, it always has exactly two
parts, separated by a period.

You can request one or more specific versions of the output format as described
below with :variable:`CPACK_EXTERNAL_REQUESTED_VERSIONS`. The output format will
have a major version that exactly matches the requested major version, and a
minor version that is greater than or equal to the requested minor version. If
no version is requested with :variable:`CPACK_EXTERNAL_REQUESTED_VERSIONS`, the
latest known major version is used by default. Currently, the only supported
format is 1.0, which is described below.

Version 1.0
***********

In addition to the standard format fields, format version 1.0 provides the
following fields in the root:

``components``
  The ``components`` field is an object with component names as the keys and
  objects describing the components as the values. The component objects have
  the following fields:

  ``name``
    The name of the component. This is always the same as the key in the
    ``components`` object.

  ``displayName``
    The value of the ``DISPLAY_NAME`` field passed to
    :command:`cpack_add_component`.

  ``description``
    The value of the ``DESCRIPTION`` field passed to
    :command:`cpack_add_component`.

  ``isHidden``
    True if ``HIDDEN`` was passed to :command:`cpack_add_component`, false if
    it was not.

  ``isRequired``
    True if ``REQUIRED`` was passed to :command:`cpack_add_component`, false if
    it was not.

  ``isDisabledByDefault``
    True if ``DISABLED`` was passed to :command:`cpack_add_component`, false if
    it was not.

  ``group``
    Only present if ``GROUP`` was passed to :command:`cpack_add_component`. If
    so, this field is a string value containing the component's group.

  ``dependencies``
    An array of components the component depends on. This contains the values
    in the ``DEPENDS`` argument passed to :command:`cpack_add_component`. If no
    ``DEPENDS`` argument was passed, this is an empty list.

  ``installationTypes``
    An array of installation types the component is part of. This contains the
    values in the ``INSTALL_TYPES`` argument passed to
    :command:`cpack_add_component`. If no ``INSTALL_TYPES`` argument was
    passed, this is an empty list.

  ``isDownloaded``
    True if ``DOWNLOADED`` was passed to :command:`cpack_add_component`, false
    if it was not.

  ``archiveFile``
    The name of the archive file passed with the ``ARCHIVE_FILE`` argument to
    :command:`cpack_add_component`. If no ``ARCHIVE_FILE`` argument was passed,
    this is an empty string.

``componentGroups``
  The ``componentGroups`` field is an object with component group names as the
  keys and objects describing the component groups as the values. The component
  group objects have the following fields:

  ``name``
    The name of the component group. This is always the same as the key in the
    ``componentGroups`` object.

  ``displayName``
    The value of the ``DISPLAY_NAME`` field passed to
    :command:`cpack_add_component_group`.

  ``description``
    The value of the ``DESCRIPTION`` field passed to
    :command:`cpack_add_component_group`.

  ``parentGroup``
    Only present if ``PARENT_GROUP`` was passed to
    :command:`cpack_add_component_group`. If so, this field is a string value
    containing the component group's parent group.

  ``isExpandedByDefault``
    True if ``EXPANDED`` was passed to :command:`cpack_add_component_group`,
    false if it was not.

  ``isBold``
    True if ``BOLD_TITLE`` was passed to :command:`cpack_add_component_group`,
    false if it was not.

  ``components``
    An array of names of components that are direct members of the group
    (components that have this group as their ``GROUP``). Components of
    subgroups are not included.

  ``subgroups``
    An array of names of component groups that are subgroups of the group
    (groups that have this group as their ``PARENT_GROUP``).

``installationTypes``
  The ``installationTypes`` field is an object with installation type names as
  the keys and objects describing the installation types as the values. The
  installation type objects have the following fields:

  ``name``
    The name of the installation type. This is always the same as the key in
    the ``installationTypes`` object.

  ``displayName``
    The value of the ``DISPLAY_NAME`` field passed to
    :command:`cpack_add_install_type`.

  ``index``
    The integer index of the installation type in the list.

``projects``
  The ``projects`` field is an array of objects describing CMake projects which
  comprise the CPack project. The values in this field are derived from
  :variable:`CPACK_INSTALL_CMAKE_PROJECTS`. In most cases, this will be only a
  single project. The project objects have the following fields:

  ``projectName``
    The project name passed to :variable:`CPACK_INSTALL_CMAKE_PROJECTS`.

  ``component``
    The name of the component or component set which comprises the project.

  ``directory``
    The build directory of the CMake project. This is the directory which
    contains the ``cmake_install.cmake`` script.

  ``subDirectory``
    The subdirectory to install the project into inside the CPack package.

``packageName``
  The package name given in :variable:`CPACK_PACKAGE_NAME`. Only present if
  this option is set.

``packageVersion``
  The package version given in :variable:`CPACK_PACKAGE_VERSION`. Only present
  if this option is set.

``packageDescriptionFile``
  The package description file given in
  :variable:`CPACK_PACKAGE_DESCRIPTION_FILE`. Only present if this option is
  set.

``packageDescriptionSummary``
  The package description summary given in
  :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. Only present if this option is
  set.

``buildConfig``
  The build configuration given to CPack with the :option:`cpack -C` option.
  Only present if this option is set.

``defaultDirectoryPermissions``
  The default directory permissions given in
  :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. Only present if this
  option is set.

``setDestdir``
  True if :variable:`CPACK_SET_DESTDIR` is true, false if it is not.

``packagingInstallPrefix``
  The install prefix given in :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. Only
  present if :variable:`CPACK_SET_DESTDIR` is true.

``stripFiles``
  True if :variable:`CPACK_STRIP_FILES` is true, false if it is not.

``warnOnAbsoluteInstallDestination``
  True if :variable:`CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION` is true, false
  if it is not.

``errorOnAbsoluteInstallDestination``
  True if :variable:`CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` is true,
  false if it is not.

Variables specific to CPack External generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. variable:: CPACK_EXTERNAL_REQUESTED_VERSIONS

  This variable is used to request a specific version of the CPack External
  generator. It is a list of ``major.minor`` values, separated by semicolons.

  If this variable is set to a non-empty value, the CPack External generator
  will iterate through each item in the list to search for a version that it
  knows how to generate. Requested versions should be listed in order of
  descending preference by the client software, as the first matching version
  in the list will be generated.

  The generator knows how to generate the version if it has a versioned
  generator whose major version exactly matches the requested major version,
  and whose minor version is greater than or equal to the requested minor
  version. For example, if ``CPACK_EXTERNAL_REQUESTED_VERSIONS`` contains 1.0, and
  the CPack External generator knows how to generate 1.1, it will generate 1.1.
  If the generator doesn't know how to generate a version in the list, it skips
  the version and looks at the next one. If it doesn't know how to generate any
  of the requested versions, an error is thrown.

  If this variable is not set, or is empty, the CPack External generator will
  generate the highest major and minor version that it knows how to generate.

  If an invalid version is encountered in ``CPACK_EXTERNAL_REQUESTED_VERSIONS`` (one
  that doesn't match ``major.minor``, where ``major`` and ``minor`` are
  integers), it is ignored.

.. variable:: CPACK_EXTERNAL_ENABLE_STAGING

  This variable can be set to true to enable optional installation
  into a temporary staging area which can then be picked up
  and packaged by an external packaging tool.
  The top level directory used by CPack for the current packaging
  task is contained in ``CPACK_TOPLEVEL_DIRECTORY``.
  It is automatically cleaned up on each run before packaging is initiated
  and can be used for custom temporary files required by
  the external packaging tool.
  It also contains the staging area ``CPACK_TEMPORARY_DIRECTORY``
  into which CPack performs the installation when staging is enabled.

.. variable:: CPACK_EXTERNAL_PACKAGE_SCRIPT

  This variable can optionally specify the full path to
  a CMake script file to be run as part of the CPack invocation.
  It is invoked after (optional) staging took place and may
  run an external packaging tool. The script has access to
  the variables defined by the CPack config file.

.. variable:: CPACK_EXTERNAL_BUILT_PACKAGES

  .. versionadded:: 3.19

  The ``CPACK_EXTERNAL_PACKAGE_SCRIPT`` script may set this list variable to the
  full paths of generated package files.  CPack will copy these files from the
  staging directory back to the top build directory and possibly produce
  checksum files if the :variable:`CPACK_PACKAGE_CHECKSUM` is set.


code:
CPack FreeBSD Generator
-----------------------

.. versionadded:: 3.10

The built in (binary) CPack FreeBSD (pkg) generator (Unix only)

Variables affecting the CPack FreeBSD (pkg) generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- .. versionadded:: 3.18
    :variable:`CPACK_ARCHIVE_THREADS`

Variables specific to CPack FreeBSD (pkg) generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The CPack FreeBSD generator may be used to create pkg(8) packages -- these may
be used on FreeBSD, DragonflyBSD, NetBSD, OpenBSD, but also on Linux or OSX,
depending on the installed package-management tools -- using :module:`CPack`.

The CPack FreeBSD generator is a :module:`CPack` generator and uses the
:variable:`!CPACK_XXX` variables used by :module:`CPack`. It tries to reuse packaging
information that may already be specified for Debian packages for the
:cpack_gen:`CPack DEB Generator`. It also tries to reuse RPM packaging
information when Debian does not specify.

The CPack FreeBSD generator should work on any host with libpkg installed. The
packages it produces are specific to the host architecture and ABI.

The CPack FreeBSD generator sets package-metadata through
:variable:`!CPACK_FREEBSD_XXX` variables. The CPack FreeBSD generator, unlike the
CPack Deb generator, does not specially support componentized packages; a
single package is created from all the software artifacts created through
CMake.

All of the variables can be set specifically for FreeBSD packaging in
the CPackConfig file or in CMakeLists.txt, but most of them have defaults
that use general settings (e.g. :variable:`CMAKE_PROJECT_NAME`) or Debian-specific
variables when those make sense (e.g. the homepage of an upstream project
is usually unchanged by the flavor of packaging). When there is no Debian
information to fall back on, but the RPM packaging has it, fall back to
the RPM information (e.g. package license).

.. variable:: CPACK_FREEBSD_PACKAGE_NAME

  Sets the package name (in the package manifest, but also affects the
  output filename).

  :Mandatory: Yes
  :Default:

    - :variable:`CPACK_PACKAGE_NAME` (this is always set by CPack itself,
      based on CMAKE_PROJECT_NAME).

.. variable:: CPACK_FREEBSD_PACKAGE_COMMENT

  Sets the package comment. This is the short description displayed by
  pkg(8) in standard "pkg info" output.

  :Mandatory: Yes
  :Default:

    - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set
      by CPack itself, if nothing else sets it explicitly).

.. variable:: CPACK_FREEBSD_PACKAGE_DESCRIPTION

  Sets the package description. This is the long description of the package,
  given by "pkg info" with a specific package as argument.

  :Mandatory: Yes
  :Default:

    - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` (this may be set already
      for Debian packaging, so it is used as a fallback).
    - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set
      by CPack itself, if nothing else sets it explicitly).
    - :variable:`PROJECT_DESCRIPTION` (this can be set with the ``DESCRIPTION``
      parameter for :command:`project`).

.. variable:: CPACK_FREEBSD_PACKAGE_WWW

  The URL of the web site for this package, preferably (when applicable) the
  site from which the original source can be obtained and any additional
  upstream documentation or information may be found.

  :Mandatory: Yes
  :Default:

   - :variable:`CPACK_PACKAGE_HOMEPAGE_URL`, or if that is not set,
   - :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already
     for Debian packaging, so it is used as a fallback).

  .. versionadded:: 3.12
    The :variable:`!CPACK_PACKAGE_HOMEPAGE_URL` variable.

.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE

  The license, or licenses, which apply to this software package. This must
  be one or more license-identifiers that pkg recognizes as acceptable license
  identifiers (e.g. "GPLv2").

  :Mandatory: Yes
  :Default:

    - :variable:`CPACK_RPM_PACKAGE_LICENSE`

.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE_LOGIC

  This variable is only of importance if there is more than one license.
  The default is "single", which is only applicable to a single license.
  Other acceptable values are determined by pkg -- those are "dual" or "multi" --
  meaning choice (OR) or simultaneous (AND) application of the licenses.

  :Mandatory: No
  :Default: single

.. variable:: CPACK_FREEBSD_PACKAGE_MAINTAINER

  The FreeBSD maintainer (e.g. ``kde@freebsd.org``) of this package.

  :Mandatory: Yes
  :Default: none

.. variable:: CPACK_FREEBSD_PACKAGE_ORIGIN

  The origin (ports label) of this package; for packages built by CPack
  outside of the ports system this is of less importance. The default
  puts the package somewhere under ``misc/``, as a stopgap.

  :Mandatory: Yes
  :Default: ``misc/<package name>``

.. variable:: CPACK_FREEBSD_PACKAGE_CATEGORIES

  The ports categories where this package lives (if it were to be built
  from ports). If none is set a single category is determined based on
  the package origin.

  :Mandatory: Yes
  :Default: derived from ``ORIGIN``

.. variable:: CPACK_FREEBSD_PACKAGE_DEPS

  A list of package origins that should be added as package dependencies.
  These are in the form ``<category>/<packagename>``, e.g. ``x11/libkonq``.
  No version information needs to be provided (this is not included
  in the manifest).

  :Mandatory: No
  :Default: empty

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
CPack IFW Generator
-------------------

.. versionadded:: 3.1

Configure and run the Qt Installer Framework to generate a Qt installer.

.. only:: html

  .. contents::

Overview
^^^^^^^^

This :manual:`cpack generator <cpack-generators(7)>` generates
configuration and meta information for the `Qt Installer Framework
<https://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW),
and runs QtIFW tools to generate a Qt installer.

QtIFW provides tools and utilities to create installers for
the platforms supported by `Qt <https://www.qt.io>`_: Linux,
Microsoft Windows, and macOS.

To make use of this generator, QtIFW needs to be installed.
The :module:`CPackIFW` module looks for the location of the
QtIFW command-line utilities, and defines several commands to
control the behavior of this generator. See `Hints for Finding QtIFW`_.

Variables
^^^^^^^^^

You can use the following variables to change the behavior of the CPack ``IFW``
generator.

Debug
"""""

.. variable:: CPACK_IFW_VERBOSE

 .. versionadded:: 3.3

 Set to ``ON`` to enable addition debug output.
 By default is ``OFF``.

Package
"""""""

.. variable:: CPACK_IFW_PACKAGE_TITLE

 Name of the installer as displayed on the title bar.
 If not specified, it defaults to :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`.

.. variable:: CPACK_IFW_PACKAGE_PUBLISHER

 Publisher of the software (as shown in the Windows Control Panel).
 If not specified, it defaults to :variable:`CPACK_PACKAGE_VENDOR`.

.. variable:: CPACK_IFW_PRODUCT_URL

 URL to a page that contains product information on your web site.

.. variable:: CPACK_IFW_PACKAGE_ICON

 Filename for a custom installer icon. It must be an absolute path.
 This should be a ``.icns`` file on macOS and a ``.ico`` file on Windows.
 It is ignored on other platforms.

.. variable:: CPACK_IFW_PACKAGE_WINDOW_ICON

 Filename for a custom window icon in PNG format for the Installer
 application. It must be an absolute path.

.. variable:: CPACK_IFW_PACKAGE_LOGO

 Filename for a logo image in PNG format, used as ``QWizard::LogoPixmap``.
 It must be an absolute path.

.. variable:: CPACK_IFW_PACKAGE_WATERMARK

 .. versionadded:: 3.8

 Filename for a watermark image in PNG format, used as
 ``QWizard::WatermarkPixmap``. It must be an absolute path.

.. variable:: CPACK_IFW_PACKAGE_BANNER

 .. versionadded:: 3.8

 Filename for a banner image in PNG format, used as ``QWizard::BannerPixmap``.
 It must be an absolute path.

.. variable:: CPACK_IFW_PACKAGE_BACKGROUND

 .. versionadded:: 3.8

 Filename for a background image in PNG format, used as
 ``QWizard::BackgroundPixmap`` (only used by ``MacStyle``). It must be an
 absolute path.

.. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE

 .. versionadded:: 3.8

 Wizard style to be used (``Modern``, ``Mac``, ``Aero`` or ``Classic``).

.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH

 .. versionadded:: 3.8

 Default width of the wizard in pixels. Setting a banner image will override
 this.

.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT

 .. versionadded:: 3.8

 Default height of the wizard in pixels. Setting a watermark image will
 override this.

.. variable:: CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST

 .. versionadded:: 3.20

 Set to ``OFF`` if the widget listing installer pages on the left side of the
 wizard should not be shown.

 It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or
 later.

.. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR

 .. versionadded:: 3.8

 Color of the titles and subtitles (takes an HTML color code, such as
 ``#88FF33``).

.. variable:: CPACK_IFW_PACKAGE_STYLE_SHEET

 .. versionadded:: 3.15

 Filename for a stylesheet. It must be an absolute path.

.. variable:: CPACK_IFW_TARGET_DIRECTORY

 Default target directory for installation.
 If :variable:`CPACK_PACKAGE_INSTALL_DIRECTORY` is set, this defaults to
 ``@ApplicationsDir@/${CPACK_PACKAGE_INSTALL_DIRECTORY}``. If that variable
 isn't set either, the default used is ``@RootDir@/usr/local``.
 Predefined variables of the form ``@...@`` are expanded by the
 `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_.

.. variable:: CPACK_IFW_ADMIN_TARGET_DIRECTORY

 Default target directory for installation with administrator rights.

 You can use predefined variables.

.. variable:: CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR

 .. versionadded:: 3.11

 Set to ``OFF`` if the target directory should not be deleted when uninstalling.

 Is ``ON`` by default

.. variable:: CPACK_IFW_PACKAGE_GROUP

 The group, which will be used to configure the root package.

.. variable:: CPACK_IFW_PACKAGE_NAME

 The root package name, which will be used if the configuration group is not
 specified.

.. variable:: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY

 .. versionadded:: 3.3

 Name of the default program group for the product in the Windows Start menu.
 If not specified, it defaults to :variable:`CPACK_IFW_PACKAGE_NAME`.

.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME

 .. versionadded:: 3.3

 Filename of the generated maintenance tool.
 The platform-specific executable file extension will be appended.

 If not specified, QtIFW provides a default name (``maintenancetool``).

.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE

 .. versionadded:: 3.3

 Filename for the configuration of the generated maintenance tool.

 If not specified, QtIFW uses a default file name (``maintenancetool.ini``).

.. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS

 .. versionadded:: 3.3

 Set to ``ON`` if the installation path can contain non-ASCII characters.
 Only supported for QtIFW 2.0 and later. Older QtIFW versions will always
 allow non-ASCII characters.

.. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH

 .. versionadded:: 3.3

 Set to ``OFF`` if the installation path cannot contain space characters.

 Is ``ON`` for QtIFW less 2.0 tools.

.. variable:: CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE

 .. versionadded:: 3.23

 Set to ``ON`` if command line interface features should be disabled.
 It is ``OFF`` by default and will only have an effect if using QtIFW 4.0 or
 later.

.. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT

 .. versionadded:: 3.3

 Filename for a custom installer control script.

.. variable:: CPACK_IFW_PACKAGE_RESOURCES

 .. versionadded:: 3.7

 List of additional resources (``.qrc`` files) to include in the installer
 binary. They should be specified as absolute paths and no two resource files
 can have the same file name.

 You can use the :command:`cpack_ifw_add_package_resources` command to resolve
 relative paths.

.. variable:: CPACK_IFW_PACKAGE_FILE_EXTENSION

 .. versionadded:: 3.10

 The target binary extension.

 On Linux, the name of the target binary is automatically extended with
 ``.run``, if you do not specify the extension.

 On Windows, the target is created as an application with the extension
 ``.exe``, which is automatically added, if not supplied.

 On Mac, the target is created as an DMG disk image with the extension
 ``.dmg``, which is automatically added, if not supplied.

.. variable:: CPACK_IFW_REPOSITORIES_ALL

 The list of remote repositories.

 The default value of this variable is computed by CPack and contains
 all repositories added with :command:`cpack_ifw_add_repository`
 or updated with :command:`cpack_ifw_update_repository`.

.. variable:: CPACK_IFW_DOWNLOAD_ALL

 If this is ``ON``, all components will be downloaded. If not set, the
 behavior is determined by whether :command:`cpack_configure_downloads` has
 been called with the ``ALL`` option or not.

.. variable:: CPACK_IFW_PACKAGE_PRODUCT_IMAGES

 .. versionadded:: 3.23

 A list of images to be shown on the ``PerformInstallationPage``. These
 must be absolute paths and the images must be in PNG format.

 This feature is available for QtIFW 4.0.0 and later.

.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM

 .. versionadded:: 3.23

 Command executed after the installer is finished, if the user accepts the
 action. Provide the full path to the application, as found when installed.
 This typically means the path should begin with the QtIFW predefined variable
 ``@TargetDir@``.

 This feature is available for QtIFW 4.0.0 and later.

.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS

 .. versionadded:: 3.23

 List of arguments passed to the program specified in
 :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`.

 This feature is available for QtIFW 4.0.0 and later.

.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION

 .. versionadded:: 3.23

 Text shown next to the check box for running the program after the
 installation. If :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM` is set but no
 description is provided, QtIFW will use a default message like
 ``Run <Name> now``.

 This feature is available for QtIFW 4.0.0 and later.

.. variable:: CPACK_IFW_PACKAGE_SIGNING_IDENTITY

 .. versionadded:: 3.23

 Allows specifying a code signing identity to be used for signing the generated
 app bundle. Only available on macOS, ignored on other platforms.

.. variable:: CPACK_IFW_ARCHIVE_FORMAT

 .. versionadded:: 3.23

 Set the format used when packaging new component data archives. If you omit
 this option, the ``7z`` format will be used as a default. Supported formats:

 * 7z
 * zip
 * tar.gz
 * tar.bz2
 * tar.xz

 .. note::

  If the Qt Installer Framework tools were built without libarchive support,
  only ``7z`` format is supported.

 This feature is available for QtIFW 4.2.0 and later.

.. variable:: CPACK_IFW_ARCHIVE_COMPRESSION

 .. versionadded:: 3.23

 Archive compression level. The allowable values are:

  * 0 (*No compression*)
  * 1 (*Fastest compression*)
  * 3 (*Fast compression*)
  * 5 (*Normal compression*)
  * 7 (*Maximum compression*)
  * 9 (*Ultra compression*)

 If this variable is not set, QtIFW will use a default compression level,
 which will typically be 5 (*Normal compression*).

 .. note::

  Some formats do not support all the possible values. For example ``zip``
  compression only supports values from 1 to 7.

 This feature is available for QtIFW 4.2.0 and later.

Components
""""""""""

.. variable:: CPACK_IFW_RESOLVE_DUPLICATE_NAMES

 Resolve duplicate names when installing components with groups.

.. variable:: CPACK_IFW_PACKAGES_DIRECTORIES

 Additional prepared packages directories that will be used to resolve
 dependent components.

.. variable:: CPACK_IFW_REPOSITORIES_DIRECTORIES

 .. versionadded:: 3.10

 Additional prepared repository directories that will be used to resolve and
 repack dependent components.

 This feature is available for QtIFW 3.1 and later.

QtIFW Tools
"""""""""""

.. variable:: CPACK_IFW_FRAMEWORK_VERSION

 .. versionadded:: 3.3

 The version of the QtIFW tools that will be used. This variable is set
 by the :module:`CPackIFW` module.

The following variables provide the locations of the QtIFW
command-line tools as discovered by the :module:`CPackIFW` module.
These variables are cached, and may be configured if needed.

.. variable:: CPACK_IFW_ARCHIVEGEN_EXECUTABLE

 .. versionadded:: 3.19

 The path to ``archivegen``.

.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE

 The path to ``binarycreator``.

.. variable:: CPACK_IFW_REPOGEN_EXECUTABLE

 The path to ``repogen``.

.. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE

 The path to ``installerbase``.

.. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE

 The path to ``devtool``.

Hints for Finding QtIFW
"""""""""""""""""""""""

Generally, the CPack ``IFW`` generator automatically finds QtIFW tools.
The following (in order of precedence) can also be set to augment the
locations normally searched by :command:`find_program`:

.. variable:: CPACK_IFW_ROOT

  .. versionadded:: 3.9

  CMake variable

.. envvar:: CPACK_IFW_ROOT

  .. versionadded:: 3.9

  Environment variable

.. variable:: QTIFWDIR

  CMake variable

.. envvar:: QTIFWDIR

  Environment variable

.. note::
  The specified path should not contain ``bin`` at the end
  (for example: ``D:\\DevTools\\QtIFW2.0.5``).

Other Settings
^^^^^^^^^^^^^^

Online installer
""""""""""""""""

By default, this generator generates an *offline installer*. This means
that all packaged files are fully contained in the installer executable.

In contrast, an *online installer* will download some or all components from
a remote server.

The ``DOWNLOADED`` option in the :command:`cpack_add_component` command
specifies that a component is to be downloaded. Alternatively, the ``ALL``
option in the :command:`cpack_configure_downloads` command specifies that
`all` components are to be be downloaded.

The :command:`cpack_ifw_add_repository` command and the
:variable:`CPACK_IFW_DOWNLOAD_ALL` variable allow for more specific
configuration.

When there are online components, CPack will write them to archive files.
The help page of the :module:`CPackComponent` module, especially the section
on the :command:`cpack_configure_downloads` function, explains how to make
these files accessible from a download URL.

Internationalization
""""""""""""""""""""

.. versionadded:: 3.9

Some variables and command arguments support internationalization via
CMake script. This is an optional feature.

Installers created by QtIFW tools have built-in support for
internationalization and many phrases are localized to many languages,
but this does not apply to the description of your components and groups.

Localization of the description of your components and groups is useful for
users of your installers.

A localized variable or argument can contain a single default value, and
after that a set of pairs with the name of the locale and the localized value.

For example:

.. code-block:: cmake

   set(LOCALIZABLE_VARIABLE "Default value"
     en "English value"
     en_US "American value"
     en_GB "Great Britain value"
     )

See Also
^^^^^^^^

Qt Installer Framework Manual:

* Index page:
  https://doc.qt.io/qtinstallerframework/index.html

* Component Scripting:
  https://doc.qt.io/qtinstallerframework/scripting.html

* Predefined Variables:
  https://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables

* Promoting Updates:
  https://doc.qt.io/qtinstallerframework/ifw-updates.html

Download Qt Installer Framework for your platform from Qt site:
 https://download.qt.io/official_releases/qt-installer-framework


code:
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


code:
CPack NSIS Generator
--------------------

CPack Nullsoft Scriptable Install System (NSIS) generator specific options.

.. versionchanged:: 3.22
 The NSIS generator requires NSIS 3.03 or newer.

Variables specific to CPack NSIS generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following variables are specific to the graphical installers built
on Windows Nullsoft Scriptable Install System.

.. variable:: CPACK_NSIS_INSTALL_ROOT

 The default installation directory presented to the end user by the NSIS
 installer is under this root dir. The full directory presented to the end
 user is: ``${CPACK_NSIS_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY}``

.. variable:: CPACK_NSIS_MUI_ICON

 An icon filename.  The name of a ``*.ico`` file used as the main icon for the
 generated install program.

.. variable:: CPACK_NSIS_MUI_UNIICON

 An icon filename.  The name of a ``*.ico`` file used as the main icon for the
 generated uninstall program.

.. variable:: CPACK_NSIS_INSTALLER_MUI_ICON_CODE

 undocumented.

.. variable:: CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP

 .. versionadded:: 3.5

 The filename of a bitmap to use as the NSIS ``MUI_WELCOMEFINISHPAGE_BITMAP``.

.. variable:: CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP

 .. versionadded:: 3.5

 The filename of a bitmap to use as the NSIS ``MUI_UNWELCOMEFINISHPAGE_BITMAP``.

.. variable:: CPACK_NSIS_EXTRA_PREINSTALL_COMMANDS

 Extra NSIS commands that will be added to the beginning of the install
 Section, before your install tree is available on the target system.

.. variable:: CPACK_NSIS_EXTRA_INSTALL_COMMANDS

 Extra NSIS commands that will be added to the end of the install Section,
 after your install tree is available on the target system.

.. variable:: CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS

 Extra NSIS commands that will be added to the uninstall Section, before
 your install tree is removed from the target system.

.. variable:: CPACK_NSIS_COMPRESSOR

 The arguments that will be passed to the NSIS `SetCompressor` command.

.. variable:: CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL

 Ask about uninstalling previous versions first.  If this is set to ``ON``,
 then an installer will look for previous installed versions and if one is
 found, ask the user whether to uninstall it before proceeding with the
 install.

.. variable:: CPACK_NSIS_MODIFY_PATH

 Modify ``PATH`` toggle.  If this is set to ``ON``, then an extra page will appear
 in the installer that will allow the user to choose whether the program
 directory should be added to the system ``PATH`` variable.

.. variable:: CPACK_NSIS_DISPLAY_NAME

 The display name string that appears in the Windows `Apps & features`
 in `Control Panel`

.. variable:: CPACK_NSIS_PACKAGE_NAME

 The title displayed at the top of the installer.

.. variable:: CPACK_NSIS_INSTALLED_ICON_NAME

 A path to the executable that contains the installer icon.

.. variable:: CPACK_NSIS_HELP_LINK

 URL to a web site providing assistance in installing your application.

.. variable:: CPACK_NSIS_URL_INFO_ABOUT

 URL to a web site providing more information about your application.

.. variable:: CPACK_NSIS_CONTACT

 Contact information for questions and comments about the installation
 process.

.. variable:: CPACK_NSIS_<compName>_INSTALL_DIRECTORY

 .. versionadded:: 3.7

 Custom install directory for the specified component ``<compName>`` instead
 of ``$INSTDIR``.

.. variable:: CPACK_NSIS_CREATE_ICONS_EXTRA

 Additional NSIS commands for creating `Start Menu` shortcuts.

.. variable:: CPACK_NSIS_DELETE_ICONS_EXTRA

 Additional NSIS commands to uninstall `Start Menu` shortcuts.

.. variable:: CPACK_NSIS_EXECUTABLES_DIRECTORY

 Creating NSIS `Start Menu` links assumes that they are in ``bin`` unless this
 variable is set.  For example, you would set this to ``exec`` if your
 executables are in an exec directory.

.. variable:: CPACK_NSIS_MUI_FINISHPAGE_RUN

 Specify an executable to add an option to run on the finish page of the
 NSIS installer.

.. variable:: CPACK_NSIS_MENU_LINKS

 Specify links in ``[application]`` menu.  This should contain a list of pair
 ``link`` ``link name``. The link may be a URL or a path relative to
 installation prefix.  Like::

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

.. variable:: CPACK_NSIS_UNINSTALL_NAME

 .. versionadded:: 3.17

 Specify the name of the program to uninstall the version.
 Default is ``Uninstall``.

.. variable:: CPACK_NSIS_WELCOME_TITLE

  .. versionadded:: 3.17

  The title to display on the top of the page for the welcome page.

.. variable:: CPACK_NSIS_WELCOME_TITLE_3LINES

 .. versionadded:: 3.17

 Display the title in the welcome page on 3 lines instead of 2.

.. variable:: CPACK_NSIS_FINISH_TITLE

 .. versionadded:: 3.17

 The title to display on the top of the page for the finish page.

.. variable:: CPACK_NSIS_FINISH_TITLE_3LINES

 .. versionadded:: 3.17

 Display the title in the finish page on 3 lines instead of 2.

.. variable:: CPACK_NSIS_MUI_HEADERIMAGE

 .. versionadded:: 3.17

 The image to display on the header of installers pages.

.. variable:: CPACK_NSIS_MANIFEST_DPI_AWARE

 .. versionadded:: 3.18

 If set, declares that the installer is DPI-aware.

.. variable:: CPACK_NSIS_BRANDING_TEXT

 .. versionadded:: 3.20

 If set, updates the text at the bottom of the install window.
 To set the string to blank, use a space (" ").

.. variable:: CPACK_NSIS_BRANDING_TEXT_TRIM_POSITION

 .. versionadded:: 3.20

 If set, trim down the size of the control to the size of the branding text string.
 Allowed values for this variable are ``LEFT``, ``CENTER`` or ``RIGHT``.
 If not specified, the default behavior is ``LEFT``.

.. variable:: CPACK_NSIS_EXECUTABLE

 .. versionadded:: 3.21

 If set, specify the name of the NSIS executable. Default is ``makensis``.

.. variable:: CPACK_NSIS_IGNORE_LICENSE_PAGE

 .. versionadded:: 3.22

 If set, do not display the page containing the license during installation.

.. variable:: CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS

 .. versionadded:: 3.25

 This variable is a :ref:`semicolon-separated list <CMake Language Lists>` of
 arguments to prepend to the nsis script to run.
 If the arguments do not start with a ``/`` or a ``-``, it will add one
 automatically to the corresponding arguments.
 The command that will be run is::

    makensis.exe <preArgs>... "nsisFileName.nsi" <postArgs>...

 where ``<preArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS``
 and ``<postArgs>...``  is constructed from ``CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS``.

.. variable:: CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS

 .. versionadded:: 3.25

 This variable is a :ref:`semicolon-separated list <CMake Language Lists>` of
 arguments to append to the nsis script to run.
 If the arguments do not start with a ``/`` or a ``-``, it will add one
 automatically to the corresponding arguments.
 The command that will be run is::

    makensis.exe <preArgs>... "nsisFileName.nsi" <postArgs>...

 where ``<preArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS``
 and ``<postArgs>...``  is constructed from ``CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS``.


code:
CPack NuGet Generator
---------------------

.. versionadded:: 3.12

When build a NuGet package there is no direct way to control an output
filename due a lack of the corresponding CLI option of NuGet, so there
is no :variable:`!CPACK_NUGET_PACKAGE_FILE_NAME` variable. To form the output filename
NuGet uses the package name and the version according to its built-in rules.

Also, be aware that including a top level directory
(:variable:`CPACK_INCLUDE_TOPLEVEL_DIRECTORY`) is ignored by this generator.

Variables specific to CPack NuGet generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The CPack NuGet generator may be used to create NuGet packages using
:module:`CPack`. The CPack NuGet generator is a :module:`CPack` generator thus
it uses the :variable:`!CPACK_XXX` variables used by :module:`CPack`.

The CPack NuGet generator has specific features which are controlled by the
specifics :variable:`!CPACK_NUGET_XXX` variables. In the "one per group" mode
(see :variable:`CPACK_COMPONENTS_GROUPING`), ``<compName>`` placeholder
in the variables below would contain a group name (uppercased and turned into
a "C" identifier).

List of CPack NuGet generator specific variables:

.. variable:: CPACK_NUGET_COMPONENT_INSTALL

 Enable component packaging for CPack NuGet generator

 :Mandatory: No
 :Default: ``OFF``

.. variable:: CPACK_NUGET_PACKAGE_NAME
              CPACK_NUGET_<compName>_PACKAGE_NAME

 The NUGET package name. ``CPACK_NUGET_PACKAGE_NAME`` is used as the
 package ``id`` on nuget.org_

 :Mandatory: Yes
 :Default: :variable:`CPACK_PACKAGE_NAME`

.. variable:: CPACK_NUGET_PACKAGE_VERSION
              CPACK_NUGET_<compName>_PACKAGE_VERSION

 The NuGet package version.

 :Mandatory: Yes
 :Default: :variable:`CPACK_PACKAGE_VERSION`

.. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION
              CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION

 A long description of the package for UI display.

 :Mandatory: Yes
 :Default:

    - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION`,
    - :variable:`!CPACK_COMPONENT_GROUP_<groupName>_DESCRIPTION`,
    - :variable:`CPACK_PACKAGE_DESCRIPTION`

.. variable:: CPACK_NUGET_PACKAGE_AUTHORS
              CPACK_NUGET_<compName>_PACKAGE_AUTHORS

 A comma-separated list of packages authors, matching the profile names
 on nuget.org_. These are displayed in the NuGet Gallery on
 nuget.org_ and are used to cross-reference packages by the same
 authors.

 :Mandatory: Yes
 :Default: :variable:`CPACK_PACKAGE_VENDOR`

.. variable:: CPACK_NUGET_PACKAGE_TITLE
              CPACK_NUGET_<compName>_PACKAGE_TITLE

 A human-friendly title of the package, typically used in UI displays
 as on nuget.org_ and the Package Manager in Visual Studio. If not
 specified, the package ID is used.

 :Mandatory: No
 :Default:

    - :variable:`CPACK_COMPONENT_<compName>_DISPLAY_NAME`,
    - :variable:`!CPACK_COMPONENT_GROUP_<groupName>_DISPLAY_NAME`

.. variable:: CPACK_NUGET_PACKAGE_OWNERS
              CPACK_NUGET_<compName>_PACKAGE_OWNERS

 A comma-separated list of the package creators using profile names
 on nuget.org_. This is often the same list as in authors,
 and is ignored when uploading the package to nuget.org_.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_HOMEPAGE_URL
              CPACK_NUGET_<compName>_PACKAGE_HOMEPAGE_URL

 An URL for the package's home page, often shown in UI displays as well
 as nuget.org_.

 :Mandatory: No
 :Default: :variable:`CPACK_PACKAGE_HOMEPAGE_URL`

.. variable:: CPACK_NUGET_PACKAGE_LICENSEURL
              CPACK_NUGET_<compName>_PACKAGE_LICENSEURL

 .. deprecated:: 3.20
  Use a local license file
  (:variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`)
  or a `SPDX license identifier`_
  (:variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`) instead.

 An URL for the package's license, often shown in UI displays as well
 as on nuget.org_.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION
              CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION

 .. versionadded:: 3.20

 A Software Package Data Exchange `SPDX license identifier`_ such as
 ``MIT``, ``BSD-3-Clause``, or ``LGPL-3.0-or-later``. In the case of a
 choice of licenses or more complex restrictions, compound license
 expressions may be formed using boolean operators, for example
 ``MIT OR BSD-3-Clause``.  See the `SPDX specification`_ for guidance
 on forming complex license expressions.

 If :variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` is specified,
 :variable:`!CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` is ignored.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME
              CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME

 The package's license file in :file:`.txt` or :file:`.md` format.

 If :variable:`!CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` is specified,
 :variable:`!CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` is ignored.

 .. versionadded:: 3.20

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_ICONURL
              CPACK_NUGET_<compName>_PACKAGE_ICONURL

 .. deprecated:: 3.20
  Use a local icon file (:variable:`CPACK_NUGET_PACKAGE_ICON`) instead.

 An URL for a 64x64 image with transparency background to use as the
 icon for the package in UI display.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_REQUIRE_LICENSE_ACCEPTANCE

 When set to a true value, the user will be prompted to accept the license
 before installing the package.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_ICON
              CPACK_NUGET_<compName>_PACKAGE_ICON

 .. versionadded:: 3.20

 The filename of a 64x64 image with transparency background to use as the
 icon for the package in UI display.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION_SUMMARY
              CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION_SUMMARY

 A short description of the package for UI display. If omitted, a
 truncated version of description is used.

 :Mandatory: No
 :Default: :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`

.. variable:: CPACK_NUGET_PACKAGE_RELEASE_NOTES
              CPACK_NUGET_<compName>_PACKAGE_RELEASE_NOTES

 A description of the changes made in this release of the package,
 often used in UI like the Updates tab of the Visual Studio Package
 Manager in place of the package description.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_COPYRIGHT
              CPACK_NUGET_<compName>_PACKAGE_COPYRIGHT

 Copyright details for the package.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_LANGUAGE
              CPACK_NUGET_<compName>_PACKAGE_LANGUAGE

 .. versionadded:: 3.20

 Locale specifier for the package, for example ``en_CA``.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_TAGS
              CPACK_NUGET_<compName>_PACKAGE_TAGS

 A space-delimited list of tags and keywords that describe the
 package and aid discoverability of packages through search and
 filtering.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES
              CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES

 A list of package dependencies.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES_<dependency>_VERSION
              CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES_<dependency>_VERSION

 A `version specification`_ for the particular dependency, where
 ``<dependency>`` is an item of the dependency list (see above)
 transformed with :command:`string(MAKE_C_IDENTIFIER)` command.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_NUGET_PACKAGE_DEBUG

 Enable debug messages while executing CPack NuGet generator.

 :Mandatory: No
 :Default: ``OFF``

.. _nuget.org: https://www.nuget.org
.. _version specification: https://learn.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges
.. _SPDX license identifier: https://spdx.org/licenses
.. _SPDX specification: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions

.. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec


code:
CPack PackageMaker Generator
----------------------------

Removed.  This once generated PackageMaker installers, but the
generator has been removed since CMake 3.24.  Xcode no longer distributes
the PackageMaker tools.  Use the :cpack_gen:`CPack productbuild Generator`
instead.


code:
CPack productbuild Generator
----------------------------

.. versionadded:: 3.7

productbuild CPack generator (macOS).

Variables specific to CPack productbuild generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following variable is specific to installers built on Mac
macOS using ProductBuild:

.. variable:: CPACK_COMMAND_PRODUCTBUILD

 Path to the ``productbuild(1)`` command used to generate a product archive for
 the macOS Installer or Mac App Store.  This variable can be used to override
 the automatically detected command (or specify its location if the
 auto-detection fails to find it).

.. variable:: CPACK_PRODUCTBUILD_IDENTIFIER

 .. versionadded:: 3.23

 Set the unique (non-localized) product identifier to be associated with the
 product (i.e., ``com.kitware.cmake``). Any component product names will be
 appended to this value.

.. variable:: CPACK_PRODUCTBUILD_IDENTITY_NAME

 .. versionadded:: 3.8

 Adds a digital signature to the resulting package.

.. variable:: CPACK_PRODUCTBUILD_KEYCHAIN_PATH

 .. versionadded:: 3.8

 Specify a specific keychain to search for the signing identity.

.. variable:: CPACK_COMMAND_PKGBUILD

 Path to the ``pkgbuild(1)`` command used to generate an macOS component package
 on macOS.  This variable can be used to override the automatically detected
 command (or specify its location if the auto-detection fails to find it).

.. variable:: CPACK_PKGBUILD_IDENTITY_NAME

 .. versionadded:: 3.8

 Adds a digital signature to the resulting package.

.. variable:: CPACK_PKGBUILD_KEYCHAIN_PATH

 .. versionadded:: 3.8

 Specify a specific keychain to search for the signing identity.

.. variable:: CPACK_PREFLIGHT_<COMP>_SCRIPT

 Full path to a file that will be used as the ``preinstall`` script for the
 named ``<COMP>`` component's package, where ``<COMP>`` is the uppercased
 component name.  No ``preinstall`` script is added if this variable is not
 defined for a given component.

.. variable:: CPACK_POSTFLIGHT_<COMP>_SCRIPT

 Full path to a file that will be used as the ``postinstall`` script for the
 named ``<COMP>`` component's package, where ``<COMP>`` is the uppercased
 component name.  No ``postinstall`` script is added if this variable is not
 defined for a given component.

.. variable:: CPACK_PRODUCTBUILD_RESOURCES_DIR

 .. versionadded:: 3.9

 If specified the productbuild generator copies files from this directory
 (including subdirectories) to the ``Resources`` directory. This is done
 before the :variable:`CPACK_RESOURCE_FILE_WELCOME`,
 :variable:`CPACK_RESOURCE_FILE_README`, and
 :variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied.

.. variable:: CPACK_PRODUCTBUILD_DOMAINS

 .. versionadded:: 3.23

 This option enables more granular control over where the product may be
 installed. When it is set to true (see policy :policy:`CMP0161`), a
 ``domains`` element of the following form will be added to the
 productbuild Distribution XML:

 .. code-block:: xml

    <domains enable_anywhere="true" enable_currentUserHome="false" enable_localSystem="true"/>

 The default values are as shown above, but can be overridden with
 :variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`,
 :variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and
 :variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT`.

.. variable:: CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE

 .. versionadded:: 3.23

 May be used to override the ``enable_anywhere`` attribute in the ``domains``
 element of the Distribution XML. When set to true, the product can be
 installed at the root of any volume, including non-system volumes.

 :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
 to have any effect.

.. variable:: CPACK_PRODUCTBUILD_DOMAINS_USER

 .. versionadded:: 3.23

 May be used to override the ``enable_currentUserHome`` attribute in the
 ``domains`` element of the Distribution XML. When set to true, the product
 can be installed into the current user's home directory. Note that when
 installing into the user's home directory, the following additional
 requirements will apply:

 * The installer may not write outside the user's home directory.
 * The install will be performed as the current user rather than as ``root``.
   This may have ramifications for :variable:`CPACK_PREFLIGHT_<COMP>_SCRIPT`
   and :variable:`CPACK_POSTFLIGHT_<COMP>_SCRIPT`.
 * Administrative privileges will not be needed to perform the install.

 :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
 to have any effect.

.. variable:: CPACK_PRODUCTBUILD_DOMAINS_ROOT

 .. versionadded:: 3.23

 May be used to override the ``enable_localSystem`` attribute in the
 ``domains`` element of the Distribution XML. When set to true, the product
 can be installed in the root directory. This should normally be set to true
 unless the product should only be installed to the user's home directory.

 :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
 to have any effect.

Background Image
""""""""""""""""

.. versionadded:: 3.17

This group of variables controls the background image of the generated
installer.

.. variable:: CPACK_PRODUCTBUILD_BACKGROUND

 Adds a background to Distribution XML if specified. The value contains the
 path to image in ``Resources`` directory.

.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT

 Adds an ``alignment`` attribute to the background in Distribution XML.
 Refer to Apple documentation for valid values.

.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_SCALING

 Adds a ``scaling`` attribute to the background in Distribution XML.
 Refer to Apple documentation for valid values.

.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE

 Adds a ``mime-type`` attribute to the background in Distribution XML.
 The option contains MIME type of an image.

.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_UTI

 Adds an ``uti`` attribute to the background in Distribution XML.
 The option contains UTI type of an image.

.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA

 Adds a background for the Dark Aqua theme to Distribution XML if
 specified. The value contains the path to image in ``Resources``
 directory.

.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_ALIGNMENT

 Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT` option,
 but for the dark theme.

.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_SCALING

 Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_SCALING` option,
 but for the dark theme.

.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_MIME_TYPE

 Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE` option,
 but for the dark theme.

.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_UTI

 Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_UTI` option,
 but for the dark theme.

Distribution XML Template
^^^^^^^^^^^^^^^^^^^^^^^^^

CPack uses a template file to generate the ``distribution.dist`` file used
internally by this package generator. Ordinarily, CMake provides the template
file, but projects may supply their own by placing a file called
``CPack.distribution.dist.in`` in one of the directories listed in the
:variable:`CMAKE_MODULE_PATH` variable. CPack will then pick up the project's
template file instead of using its own.

The ``distribution.dist`` file is generated by performing substitutions
similar to the :command:`configure_file` command. Any variable set when
CPack runs will be available for substitution using the usual ``@...@``
form. The following variables are also set internally and made available for
substitution:

``CPACK_RESOURCE_FILE_LICENSE_NOPATH``
  Same as :variable:`CPACK_RESOURCE_FILE_LICENSE` except without the path.
  The named file will be available in the same directory as the generated
  ``distribution.dist`` file.

``CPACK_RESOURCE_FILE_README_NOPATH``
  Same as :variable:`CPACK_RESOURCE_FILE_README` except without the path.
  The named file will be available in the same directory as the generated
  ``distribution.dist`` file.

``CPACK_RESOURCE_FILE_WELCOME_NOPATH``
  Same as :variable:`CPACK_RESOURCE_FILE_WELCOME` except without the path.
  The named file will be available in the same directory as the generated
  ``distribution.dist`` file.

``CPACK_APPLE_PKG_INSTALLER_CONTENT``
  .. versionadded:: 3.23

  This contains all the XML elements that specify installer-wide options
  (including domain details), default backgrounds and the choices outline.

``CPACK_PACKAGEMAKER_CHOICES``
  .. deprecated:: 3.23

  This contains only the XML elements that specify the default backgrounds
  and the choices outline. It does not include the installer-wide options or
  any domain details. Use ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` instead.