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``.

repo_name: lazytadpole/codenamesilverfish

license: mit


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.


code:
CPack RPM Generator
-------------------

The built in (binary) CPack RPM generator (Unix only)

Variables specific to CPack RPM generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

The CPack RPM generator has specific features which are controlled by the specifics
:variable:`!CPACK_RPM_XXX` variables.

:variable:`!CPACK_RPM_<COMPONENT>_XXXX` variables may be used in order to have
**component-specific** values.  Note however that ``<COMPONENT>`` refers to the
**grouping name** written in upper case. It may be either a component name or
a component GROUP name. Usually, those variables correspond to RPM spec file
entities. One may find information about spec files here
https://rpm.org/documentation.

.. versionchanged:: 3.6

 `<COMPONENT>` part of variables is preferred to be in upper case (e.g. if
 component is named ``foo`` then use :variable:`!CPACK_RPM_FOO_XXXX` variable
 name format) as is with other :variable:`!CPACK_<COMPONENT>_XXXX` variables.
 For the purposes of back compatibility (CMake/CPack version 3.5 and lower)
 support for same cased component (e.g. ``fOo`` would be used as
 :variable:`!CPACK_RPM_fOo_XXXX`) is still supported for variables defined in
 older versions of CMake/CPack but is not guaranteed for variables that
 will be added in the future. For the sake of back compatibility same cased
 component variables also override upper cased versions where both are
 present.

Here are some CPack RPM generator wiki resources that are here for historic
reasons and are no longer maintained but may still prove useful:

 - https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/Configuration
 - https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/PackageGenerators#rpm-unix-only

List of CPack RPM generator specific variables:

.. variable:: CPACK_RPM_COMPONENT_INSTALL

 Enable component packaging for CPack RPM generator

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

 If enabled (``ON``) multiple packages are generated. By default
 a single package containing files of all components is generated.

.. variable:: CPACK_RPM_PACKAGE_SUMMARY
              CPACK_RPM_<component>_PACKAGE_SUMMARY

 The RPM package summary.

 :Mandatory: Yes
 :Default: :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`

 .. versionadded:: 3.2
  Per-component :variable:`!CPACK_RPM_<component>_PACKAGE_SUMMARY` variables.

.. variable:: CPACK_RPM_PACKAGE_NAME
              CPACK_RPM_<component>_PACKAGE_NAME

 The RPM package name.

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

 .. versionadded:: 3.5
  Per-component :variable:`!CPACK_RPM_<component>_PACKAGE_NAME` variables.

.. variable:: CPACK_RPM_FILE_NAME
              CPACK_RPM_<component>_FILE_NAME

 .. versionadded:: 3.6

 Package file name.

 :Mandatory: Yes
 :Default: ``<CPACK_PACKAGE_FILE_NAME>[-<component>].rpm`` with spaces
               replaced by '-'

 This may be set to:

 ``RPM-DEFAULT``
    Tell ``rpmbuild`` to automatically generate the package file name.

 ``<file-name>[.rpm]``
   Use the given file name.

   .. versionchanged:: 3.29

     The ``.rpm`` suffix will be automatically added if missing.
     Previously the suffix was required.

 .. note::

   By using user provided spec file, rpm macro extensions such as for
   generating ``debuginfo`` packages or by simply using multiple components more
   than one rpm file may be generated, either from a single spec file or from
   multiple spec files (each component execution produces its own spec file).
   In such cases duplicate file names may occur as a result of this variable
   setting or spec file content structure. Duplicate files get overwritten
   and it is up to the packager to set the variables in a manner that will
   prevent such errors.

.. variable:: CPACK_RPM_MAIN_COMPONENT

 .. versionadded:: 3.8

 Main component that is packaged without component suffix.

 :Mandatory: No
 :Default:

 This variable can be set to any component or group name so that component or
 group rpm package is generated without component suffix in filename and
 package name.

.. variable:: CPACK_RPM_PACKAGE_EPOCH

 .. versionadded:: 3.10

 The RPM package epoch

 :Mandatory: No
 :Default:

 Optional number that should be incremented when changing versioning schemas
 or fixing mistakes in the version numbers of older packages.

.. variable:: CPACK_RPM_PACKAGE_VERSION

 The RPM package version.

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

.. variable:: CPACK_RPM_PACKAGE_ARCHITECTURE
              CPACK_RPM_<component>_PACKAGE_ARCHITECTURE

 The RPM package architecture.

 :Mandatory: Yes
 :Default: Native architecture output by ``uname -m``

 This may be set to ``noarch`` if you know you are building a ``noarch`` package.

 .. versionadded:: 3.3
  Per-component :variable:`!CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variables.

.. variable:: CPACK_RPM_PACKAGE_RELEASE

 The RPM package release.

 :Mandatory: Yes
 :Default: 1

 This is the numbering of the RPM package itself, i.e. the version of the
 packaging and not the version of the content (see
 :variable:`CPACK_RPM_PACKAGE_VERSION`). One may change the default value if
 the previous packaging was buggy and/or you want to put here a fancy Linux
 distro specific numbering.

.. note::

 This is the string that goes into the RPM ``Release:`` field. Some distros
 (e.g. Fedora, CentOS) require ``1%{?dist}`` format and not just a number.
 ``%{?dist}`` part can be added by setting :variable:`CPACK_RPM_PACKAGE_RELEASE_DIST`.

.. variable:: CPACK_RPM_PACKAGE_RELEASE_DIST

 .. versionadded:: 3.6

 The dist tag that is added  RPM ``Release:`` field.

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

 This is the reported ``%{dist}`` tag from the current distribution or empty
 ``%{dist}`` if RPM macro is not set. If this variable is set then RPM
 ``Release:`` field value is set to ``${CPACK_RPM_PACKAGE_RELEASE}%{?dist}``.

.. variable:: CPACK_RPM_PACKAGE_LICENSE

 The RPM package license policy.

 :Mandatory: Yes
 :Default: "unknown"

.. variable:: CPACK_RPM_PACKAGE_GROUP
              CPACK_RPM_<component>_PACKAGE_GROUP

 The RPM package group.

 :Mandatory: Yes
 :Default: "unknown"

 .. versionadded:: 3.5
  Per-component :variable:`!CPACK_RPM_<component>_PACKAGE_GROUP` variables.

.. variable:: CPACK_RPM_PACKAGE_VENDOR

 The RPM package vendor.

 :Mandatory: Yes
 :Default: CPACK_PACKAGE_VENDOR if set or "unknown"

.. variable:: CPACK_RPM_PACKAGE_URL
              CPACK_RPM_<component>_PACKAGE_URL

 The projects URL.

 :Mandatory: No
 :Default: :variable:`CMAKE_PROJECT_HOMEPAGE_URL`

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

.. variable:: CPACK_RPM_PACKAGE_DESCRIPTION
              CPACK_RPM_<component>_PACKAGE_DESCRIPTION

 RPM package description.

 :Mandatory: Yes
 :Default:

   - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION`
     (component based installers only) if set,
   - :variable:`CPACK_PACKAGE_DESCRIPTION_FILE`
     if set, or
   - ``no package description available``

 .. versionadded:: 3.2
  Per-component :variable:`!CPACK_RPM_<component>_PACKAGE_DESCRIPTION` variables.

.. variable:: CPACK_RPM_COMPRESSION_TYPE

 RPM compression type.

 :Mandatory: No
 :Default: (system default)

 May be used to override RPM compression type to be used to build the
 RPM. For example some Linux distribution now default to ``lzma`` or ``xz``
 compression whereas older cannot use such RPM. Using this one can enforce
 compression type to be used.

 Possible values are:

  ``lzma``
    Lempel–Ziv–Markov chain algorithm

  ``xz``
    XZ Utils compression

  ``bzip2``
    bzip2 Burrows–Wheeler algorithm

  ``gzip``
    GNU Gzip compression

.. variable:: CPACK_RPM_PACKAGE_AUTOREQ
              CPACK_RPM_<component>_PACKAGE_AUTOREQ

 RPM spec autoreq field.

 :Mandatory: No
 :Default:

 May be used to enable (``1``, ``yes``) or disable (``0``, ``no``) automatic
 shared libraries dependency detection. Dependencies are added to requires list.

 .. note::

   By default automatic dependency detection is enabled by rpm generator.

.. variable:: CPACK_RPM_PACKAGE_AUTOPROV
              CPACK_RPM_<component>_PACKAGE_AUTOPROV

 RPM spec autoprov field.

 :Mandatory: No
 :Default:

 May be used to enable (``1``, ``yes``) or disable (``0``, ``no``)
 automatic listing of shared libraries that are provided by the package.
 Shared libraries are added to provides list.

 .. note::

   By default automatic provides detection is enabled by rpm generator.

.. variable:: CPACK_RPM_PACKAGE_AUTOREQPROV
              CPACK_RPM_<component>_PACKAGE_AUTOREQPROV

 RPM spec autoreqprov field.

 :Mandatory: No
 :Default:

 Variable enables/disables autoreq and autoprov at the same time.
 See :variable:`CPACK_RPM_PACKAGE_AUTOREQ` and
 :variable:`CPACK_RPM_PACKAGE_AUTOPROV` for more details.

 .. note::

   By default automatic detection feature is enabled by rpm.

.. variable:: CPACK_RPM_PACKAGE_REQUIRES
              CPACK_RPM_<component>_PACKAGE_REQUIRES

 RPM spec requires field.

 :Mandatory: No
 :Default:

 May be used to set RPM dependencies (requires). Note that you must enclose
 the complete requires string between quotes, for example:

 .. code-block:: cmake

  set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")

 The required package list of an RPM file could be printed with::

  rpm -qp --requires file.rpm

.. variable:: CPACK_RPM_PACKAGE_CONFLICTS
              CPACK_RPM_<component>_PACKAGE_CONFLICTS

 RPM spec conflicts field.

 :Mandatory: No
 :Default:

 May be used to set negative RPM dependencies (conflicts). Note that you must
 enclose the complete requires string between quotes, for example:

 .. code-block:: cmake

  set(CPACK_RPM_PACKAGE_CONFLICTS "libxml2")

 The conflicting package list of an RPM file could be printed with::

  rpm -qp --conflicts file.rpm

.. variable:: CPACK_RPM_PACKAGE_REQUIRES_PRE
              CPACK_RPM_<component>_PACKAGE_REQUIRES_PRE

 .. versionadded:: 3.2

 RPM spec requires(pre) field.

 :Mandatory: No
 :Default:

 May be used to set RPM preinstall dependencies (requires(pre)). Note that
 you must enclose the complete requires string between quotes, for example:

 .. code-block:: cmake

  set(CPACK_RPM_PACKAGE_REQUIRES_PRE "shadow-utils, initscripts")

.. variable:: CPACK_RPM_PACKAGE_REQUIRES_POST
              CPACK_RPM_<component>_PACKAGE_REQUIRES_POST

 .. versionadded:: 3.2

 RPM spec requires(post) field.

 :Mandatory: No
 :Default:

 May be used to set RPM postinstall dependencies (requires(post)). Note that
 you must enclose the complete requires string between quotes, for example:

 .. code-block:: cmake

  set(CPACK_RPM_PACKAGE_REQUIRES_POST "shadow-utils, initscripts")

.. variable:: CPACK_RPM_PACKAGE_REQUIRES_POSTUN
              CPACK_RPM_<component>_PACKAGE_REQUIRES_POSTUN

 .. versionadded:: 3.2

 RPM spec requires(postun) field.

 :Mandatory: No
 :Default:

 May be used to set RPM postuninstall dependencies (requires(postun)). Note
 that you must enclose the complete requires string between quotes, for
 example:

 .. code-block:: cmake

  set(CPACK_RPM_PACKAGE_REQUIRES_POSTUN "shadow-utils, initscripts")

.. variable:: CPACK_RPM_PACKAGE_REQUIRES_PREUN
              CPACK_RPM_<component>_PACKAGE_REQUIRES_PREUN

 .. versionadded:: 3.2

 RPM spec requires(preun) field.

 :Mandatory: No
 :Default:

 May be used to set RPM preuninstall dependencies (requires(preun)). Note that
 you must enclose the complete requires string between quotes, for example:

 .. code-block:: cmake

  set(CPACK_RPM_PACKAGE_REQUIRES_PREUN "shadow-utils, initscripts")

.. variable:: CPACK_RPM_PACKAGE_SUGGESTS
              CPACK_RPM_<component>_PACKAGE_SUGGESTS

 RPM spec suggest field.

 :Mandatory: No
 :Default:

 May be used to set weak RPM dependencies (suggests). If ``rpmbuild`` doesn't
 support the ``Suggests`` tag, CPack will emit a warning and ignore this
 variable. Note that you must enclose the complete requires string between
 quotes.

.. variable:: CPACK_RPM_PACKAGE_PROVIDES
              CPACK_RPM_<component>_PACKAGE_PROVIDES

 RPM spec provides field.

 :Mandatory: No
 :Default:

 May be used to set RPM dependencies (provides). The provided package list
 of an RPM file could be printed with::

  rpm -qp --provides file.rpm

.. variable:: CPACK_RPM_PACKAGE_OBSOLETES
              CPACK_RPM_<component>_PACKAGE_OBSOLETES

 RPM spec obsoletes field.

 :Mandatory: No
 :Default:

 May be used to set RPM packages that are obsoleted by this one.

.. variable:: CPACK_RPM_PACKAGE_RELOCATABLE

 build a relocatable RPM.

 :Mandatory: No
 :Default: CPACK_PACKAGE_RELOCATABLE

 If this variable is set to TRUE or ON, the CPack RPM generator will try
 to build a relocatable RPM package. A relocatable RPM may
 be installed using::

  rpm --prefix or --relocate

 in order to install it at an alternate place see rpm(8). Note that
 currently this may fail if :variable:`CPACK_SET_DESTDIR` is set to ``ON``. If
 :variable:`CPACK_SET_DESTDIR` is set then you will get a warning message but
 if there is file installed with absolute path you'll get unexpected behavior.

.. variable:: CPACK_RPM_SPEC_INSTALL_POST

 .. deprecated:: 2.8.12 Use :variable:`CPACK_RPM_SPEC_MORE_DEFINE` instead.

 :Mandatory: No
 :Default:

 May be used to override the ``__spec_install_post`` section within the
 generated spec file.  This affects the install step during package creation,
 not during package installation.  For adding operations to be performed
 during package installation, use
 :variable:`CPACK_RPM_POST_INSTALL_SCRIPT_FILE` instead.

.. variable:: CPACK_RPM_SPEC_MORE_DEFINE

 RPM extended spec definitions lines.

 :Mandatory: No
 :Default:

 May be used to add any ``%define`` lines to the generated spec file.  An
 example of its use is to prevent stripping of executables (but note that
 this may also disable other default post install processing):

 .. code-block:: cmake

   set(CPACK_RPM_SPEC_MORE_DEFINE "%define __spec_install_post /bin/true")

.. variable:: CPACK_RPM_PACKAGE_DEBUG

 Toggle CPack RPM generator debug output.

 :Mandatory: No
 :Default:

 May be set when invoking cpack in order to trace debug information
 during CPack RPM run. For example you may launch CPack like this::

  cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM

.. variable:: CPACK_RPM_USER_BINARY_SPECFILE
              CPACK_RPM_<componentName>_USER_BINARY_SPECFILE

 A user provided spec file.

 :Mandatory: No
 :Default:

 May be set by the user in order to specify a USER binary spec file
 to be used by the CPack RPM generator instead of generating the file.
 The specified file will be processed by configure_file( @ONLY).

.. variable:: CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE

 Spec file template.

 :Mandatory: No
 :Default:

 If set CPack will generate a template for USER specified binary
 spec file and stop with an error. For example launch CPack like this::

  cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM

 The user may then use this file in order to hand-craft is own
 binary spec file which may be used with
 :variable:`CPACK_RPM_USER_BINARY_SPECFILE`.

.. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
              CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
              CPACK_RPM_PRE_TRANS_SCRIPT_FILE

 Path to file containing pre install/uninstall/transaction script.

 :Mandatory: No
 :Default:

 May be used to embed a pre installation/uninstallation/transaction script in the spec file.
 The referred script file (or both) will be read and directly
 put after the ``%pre`` or ``%preun`` section
 If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
 script for each component can be overridden with
 :variable:`!CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE`,
 :variable:`!CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE`, and
 :variable:`!CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE`
 One may verify which scriptlet has been included with::

  rpm -qp --scripts  package.rpm

 .. versionadded:: 3.18
  The :variable:`!CPACK_RPM_PRE_TRANS_SCRIPT_FILE` variable.

.. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE
              CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
              CPACK_RPM_POST_TRANS_SCRIPT_FILE

 Path to file containing post install/uninstall/transaction script.

 :Mandatory: No
 :Default:

 May be used to embed a post installation/uninstallation/transaction script in the spec file.
 The referred script file (or both) will be read and directly
 put after the ``%post`` or ``%postun`` section.
 If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
 script for each component can be overridden with
 :variable:`!CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE`,
 :variable:`!CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE`, and
 :variable:`!CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE`
 One may verify which scriptlet has been included with::

  rpm -qp --scripts  package.rpm

 .. versionadded:: 3.18
  The :variable:`!CPACK_RPM_POST_TRANS_SCRIPT_FILE` variable.

.. variable:: CPACK_RPM_USER_FILELIST
              CPACK_RPM_<COMPONENT>_USER_FILELIST

 :Mandatory: No
 :Default:

 May be used to explicitly specify ``%(<directive>)`` file line
 in the spec file. Like ``%config(noreplace)`` or any other directive
 that be found in the ``%files`` section. Since
 the CPack RPM generator is generating the list of files (and directories) the
 user specified files of the :variable:`!CPACK_RPM_<COMPONENT>_USER_FILELIST` list will
 be removed from the generated list. If referring to directories do
 not add a trailing slash.

 .. versionadded:: 3.8
  You can have multiple directives per line, as in
  ``%attr(600,root,root) %config(noreplace)``.

.. variable:: CPACK_RPM_CHANGELOG_FILE

 RPM changelog file.

 :Mandatory: No
 :Default:

 May be used to embed a changelog in the spec file.
 The referred file will be read and directly put after the ``%changelog``
 section.

.. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST

 list of path to be excluded.

 :Mandatory: No
 :Default:
  The following paths are excluded by default:
    - ``/etc``
    - ``/etc/init.d``
    - ``/usr``
    - ``/usr/bin``
    - ``/usr/include``
    - ``/usr/lib``
    - ``/usr/libx32``
    - ``/usr/lib64``
    - ``/usr/share``
    - ``/usr/share/aclocal``
    - ``/usr/share/doc``

 May be used to exclude path (directories or files) from the auto-generated
 list of paths discovered by CPack RPM. The default value contains a
 reasonable set of values if the variable is not defined by the user. If the
 variable is defined by the user then the CPack RPM generator will NOT any of
 the default path. If you want to add some path to the default list then you
 can use :variable:`CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION` variable.

 .. versionadded:: 3.10
  Added ``/usr/share/aclocal`` to the default list of excludes.

.. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION

 additional list of path to be excluded.

 :Mandatory: No
 :Default:

 May be used to add more exclude path (directories or files) from the initial
 default list of excluded paths. See
 :variable:`CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST`.

.. variable:: CPACK_RPM_RELOCATION_PATHS

 .. versionadded:: 3.2

 Packages relocation paths list.

 :Mandatory: No
 :Default:

 May be used to specify more than one relocation path per relocatable RPM.
 Variable contains a list of relocation paths that if relative are prefixed
 by the value of :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` or by the
 value of :variable:`CPACK_PACKAGING_INSTALL_PREFIX` if the component version
 is not provided.
 Variable is not component based as its content can be used to set a different
 path prefix for e.g. binary dir and documentation dir at the same time.
 Only prefixes that are required by a certain component are added to that
 component - component must contain at least one file/directory/symbolic link
 with :variable:`CPACK_RPM_RELOCATION_PATHS` prefix for a certain relocation
 path to be added. Package will not contain any relocation paths if there are
 no files/directories/symbolic links on any of the provided prefix locations.
 Packages that either do not contain any relocation paths or contain
 files/directories/symbolic links that are outside relocation paths print
 out an :command:`AUTHOR_WARNING <message>` that RPM will be partially relocatable.

.. variable:: CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX

 .. versionadded:: 3.2

 Per component relocation path install prefix.

 :Mandatory: No
 :Default: :variable:`CPACK_PACKAGING_INSTALL_PREFIX`

 May be used to set per component :variable:`CPACK_PACKAGING_INSTALL_PREFIX`
 for relocatable RPM packages.

.. variable:: CPACK_RPM_NO_INSTALL_PREFIX_RELOCATION
              CPACK_RPM_NO_<COMPONENT>_INSTALL_PREFIX_RELOCATION

 .. versionadded:: 3.3

 Removal of default install prefix from relocation paths list.

 :Mandatory: No
 :Default: :variable:`CPACK_PACKAGING_INSTALL_PREFIX` or
    :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX`
    are treated as one of relocation paths

 May be used to remove :variable:`CPACK_PACKAGING_INSTALL_PREFIX` and
 :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX`
 from relocatable RPM prefix paths.

.. variable:: CPACK_RPM_ADDITIONAL_MAN_DIRS

 .. versionadded:: 3.3

 :Mandatory: No
 :Default:
  Regular expressions that are added by default were taken from ``brp-compress`` RPM macro:
    - ``/usr/man/man.*``
    - ``/usr/man/.*/man.*``
    - ``/usr/info.*``
    - ``/usr/share/man/man.*``
    - ``/usr/share/man/.*/man.*``
    - ``/usr/share/info.*``
    - ``/usr/kerberos/man.*``
    - ``/usr/X11R6/man/man.*``
    - ``/usr/lib/perl5/man/man.*``
    - ``/usr/share/doc/.*/man/man.*``
    - ``/usr/lib/.*/man/man.*``

 May be used to set additional man dirs that could potentially be compressed
 by brp-compress RPM macro. Variable content must be a list of regular
 expressions that point to directories containing man files or to man files
 directly. Note that in order to compress man pages a path must also be
 present in brp-compress RPM script and that brp-compress script must be
 added to RPM configuration by the operating system.

.. variable:: CPACK_RPM_DEFAULT_USER
              CPACK_RPM_<compName>_DEFAULT_USER

 .. versionadded:: 3.6

 default user ownership of RPM content

 :Mandatory: No
 :Default: ``root``

 Value should be user name and not UID.
 Note that ``<compName>`` must be in upper-case.

.. variable:: CPACK_RPM_DEFAULT_GROUP
              CPACK_RPM_<compName>_DEFAULT_GROUP

 .. versionadded:: 3.6

 default group ownership of RPM content

 :Mandatory: No
 :Default: root

 Value should be group name and not GID.
 Note that ``<compName>`` must be in upper-case.

.. variable:: CPACK_RPM_DEFAULT_FILE_PERMISSIONS
              CPACK_RPM_<compName>_DEFAULT_FILE_PERMISSIONS

 .. versionadded:: 3.6

 default permissions used for packaged files

 :Mandatory: No
 :Default: (system default)

 Accepted values are lists with PERMISSIONS. Valid permissions
 are:

 - ``OWNER_READ``
 - ``OWNER_WRITE``
 - ``OWNER_EXECUTE``
 - ``GROUP_READ``
 - ``GROUP_WRITE``
 - ``GROUP_EXECUTE``
 - ``WORLD_READ``
 - ``WORLD_WRITE``
 - ``WORLD_EXECUTE``

 Note that ``<compName>`` must be in upper-case.

.. variable:: CPACK_RPM_DEFAULT_DIR_PERMISSIONS
              CPACK_RPM_<compName>_DEFAULT_DIR_PERMISSIONS

 .. versionadded:: 3.6

 default permissions used for packaged directories

 :Mandatory: No
 :Default: (system default)

 Accepted values are lists with PERMISSIONS. Valid permissions
 are the same as for :variable:`CPACK_RPM_DEFAULT_FILE_PERMISSIONS`.
 Note that ``<compName>`` must be in upper-case.

.. variable:: CPACK_RPM_INSTALL_WITH_EXEC

 .. versionadded:: 3.11

 force execute permissions on programs and shared libraries

 :Mandatory: No
 :Default: (system default)

 Force set owner, group and world execute permissions on programs and shared
 libraries. This can be used for creating valid rpm packages on systems such
 as Debian where shared libraries do not have execute permissions set.

.. note::

 Programs and shared libraries without execute permissions are ignored during
 separation of debug symbols from the binary for debuginfo packages.

Packaging of Symbolic Links
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.3

The CPack RPM generator supports packaging of symbolic links:

.. code-block:: cmake

  execute_process(COMMAND ${CMAKE_COMMAND}
    -E create_symlink <relative_path_location> <symlink_name>)
  install(FILES ${CMAKE_CURRENT_BINARY_DIR}/<symlink_name>
    DESTINATION <symlink_location> COMPONENT libraries)

Symbolic links will be optimized (paths will be shortened if possible)
before being added to the package or if multiple relocation paths are
detected, a post install symlink relocation script will be generated.

Symbolic links may point to locations that are not packaged by the same
package (either a different component or even not packaged at all) but
those locations will be treated as if they were a part of the package
while determining if symlink should be either created or present in a
post install script - depending on relocation paths.

.. versionchanged:: 3.6
 Symbolic links that point to locations outside packaging path produce a
 warning and are treated as non relocatable permanent symbolic links.
 Previous versions of CMake produced an error in this case.

Currently there are a few limitations though:

* For component based packaging component interdependency is not checked
  when processing symbolic links. Symbolic links pointing to content of
  a different component are treated the same way as if pointing to location
  that will not be packaged.

* Symbolic links pointing to a location through one or more intermediate
  symbolic links will not be handled differently - if the intermediate
  symbolic link(s) is also on a relocatable path, relocating it during
  package installation may cause initial symbolic link to point to an
  invalid location.

Packaging of debug information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.7

Debuginfo packages contain debug symbols and sources for debugging packaged
binaries.

Debuginfo RPM packaging has its own set of variables:

.. variable:: CPACK_RPM_DEBUGINFO_PACKAGE
              CPACK_RPM_<component>_DEBUGINFO_PACKAGE

 Enable generation of debuginfo RPM package(s).

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

.. note::

 Binaries must contain debug symbols before packaging so use either ``Debug``
 or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value.

 Additionally, if :variable:`CPACK_STRIP_FILES` is set, the files will be stripped before
 they get to the RPM generator, so will not contain debug symbols and
 a debuginfo package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`.

.. note::

 Packages generated from packages without binary files, with binary files but
 without execute permissions or without debug symbols will cause packaging
 termination.

.. variable:: CPACK_BUILD_SOURCE_DIRS

 Provides locations of root directories of source files from which binaries
 were built.

 :Mandatory: Yes if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set
 :Default:

.. note::

 For CMake project :variable:`CPACK_BUILD_SOURCE_DIRS` is set by default to
 point to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` paths.

.. note::

 Sources with path prefixes that do not fall under any location provided with
 :variable:`CPACK_BUILD_SOURCE_DIRS` will not be present in debuginfo package.

.. variable:: CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX
              CPACK_RPM_<component>_BUILD_SOURCE_DIRS_PREFIX

 Prefix of location where sources will be placed during package installation.

 :Mandatory: Yes if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set
 :Default: ``/usr/src/debug/${CPACK_PACKAGE_FILE_NAME}`` and
    for component packaging ``/usr/src/debug/${CPACK_PACKAGE_FILE_NAME}-<component>``

.. note::

 Each source path prefix is additionally suffixed by ``src_<index>`` where
 index is index of the path used from :variable:`CPACK_BUILD_SOURCE_DIRS`
 variable. This produces ``${CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX}/src_<index>``
 replacement path.
 Limitation is that replaced path part must be shorter or of equal
 length than the length of its replacement. If that is not the case either
 :variable:`CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX` variable has to be set to
 a shorter path or source directories must be placed on a longer path.

.. variable:: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS

 Directories containing sources that should be excluded from debuginfo packages.

 :Mandatory: No
 :Default:
  The following paths are excluded by default:
    - ``/usr``
    - ``/usr/src``
    - ``/usr/src/debug``

 Listed paths are owned by other RPM packages and should therefore not be
 deleted on debuginfo package uninstallation.

.. variable:: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS_ADDITION

 Paths that should be appended to :variable:`CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS`
 for exclusion.

 :Mandatory: No
 :Default:

.. variable:: CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE

 .. versionadded:: 3.8

 Create a single debuginfo package even if components packaging is set.

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

 When this variable is enabled it produces a single debuginfo package even if
 component packaging is enabled.

 When using this feature in combination with components packaging and there is
 more than one component this variable requires :variable:`CPACK_RPM_MAIN_COMPONENT`
 to be set.

.. note::

 If none of the :variable:`CPACK_RPM_<component>_DEBUGINFO_PACKAGE` variables
 is set then :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is automatically set to
 ``ON`` when :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` is set.

.. variable:: CPACK_RPM_DEBUGINFO_FILE_NAME
              CPACK_RPM_<component>_DEBUGINFO_FILE_NAME

 .. versionadded:: 3.9

 Debuginfo package file name.

 :Mandatory: No
 :Default: rpmbuild tool generated package file name

 Alternatively provided debuginfo package file name must end with ``.rpm``
 suffix and should differ from file names of other generated packages.

 Variable may contain ``@cpack_component@`` placeholder which will be
 replaced by component name if component packaging is enabled otherwise it
 deletes the placeholder.

 Setting the variable to ``RPM-DEFAULT`` may be used to explicitly set
 filename generation to default.

.. note::

 :variable:`CPACK_RPM_FILE_NAME` also supports rpmbuild tool generated package
 file name - disabled by default but can be enabled by setting the variable to
 ``RPM-DEFAULT``.

Packaging of sources (SRPM)
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.7

SRPM packaging is enabled by setting :variable:`CPACK_RPM_PACKAGE_SOURCES`
variable while usually using :variable:`CPACK_INSTALLED_DIRECTORIES` variable
to provide directory containing CMakeLists.txt and source files.

For CMake projects SRPM package would be produced by executing::

  cpack -G RPM --config ./CPackSourceConfig.cmake

.. note::

 Produced SRPM package is expected to be built with :manual:`cmake(1)` executable
 and packaged with :manual:`cpack(1)` executable so CMakeLists.txt has to be
 located in root source directory and must be able to generate binary rpm
 packages by executing :option:`cpack -G` command. The two executables as well as
 rpmbuild must also be present when generating binary rpm packages from the
 produced SRPM package.

Once the SRPM package is generated it can be used to generate binary packages
by creating a directory structure for rpm generation and executing rpmbuild
tool::

  mkdir -p build_dir/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS}
  rpmbuild --define "_topdir <path_to_build_dir>" --rebuild <SRPM_file_name>

Generated packages will be located in build_dir/RPMS directory or its sub
directories.

.. note::

 SRPM package internally uses CPack/RPM generator to generate binary packages
 so CMakeScripts.txt can decide during the SRPM to binary rpm generation step
 what content the package(s) should have as well as how they should be packaged
 (monolithic or components). CMake can decide this for e.g. by reading environment
 variables set by the package manager before starting the process of generating
 binary rpm packages. This way a single SRPM package can be used to produce
 different binary rpm packages on different platforms depending on the platform's
 packaging rules.

Source RPM packaging has its own set of variables:

.. variable:: CPACK_RPM_PACKAGE_SOURCES

 Should the content be packaged as a source rpm (default is binary rpm).

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

.. note::

 For cmake projects :variable:`CPACK_RPM_PACKAGE_SOURCES` variable is set
 to ``OFF`` in CPackConfig.cmake and ``ON`` in CPackSourceConfig.cmake
 generated files.

.. variable:: CPACK_RPM_SOURCE_PKG_BUILD_PARAMS

 Additional command-line parameters provided to :manual:`cmake(1)` executable.

 :Mandatory: No
 :Default:

.. variable:: CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX

 Packaging install prefix that would be provided in :variable:`CPACK_PACKAGING_INSTALL_PREFIX`
 variable for producing binary RPM packages.

 :Mandatory: Yes
 :Default: ``/``

.. variable:: CPACK_RPM_BUILDREQUIRES

 List of source rpm build dependencies.

 :Mandatory: No
 :Default:

 May be used to set source RPM build dependencies (BuildRequires). Note that
 you must enclose the complete build requirements string between quotes, for
 example:

 .. code-block:: cmake

  set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8")

.. variable:: CPACK_RPM_REQUIRES_EXCLUDE_FROM

 .. versionadded:: 3.22

 :Mandatory: No
 :Default:

 May be used to keep the dependency generator from scanning specific files
 or directories for dependencies.  Note that you can use a regular
 expression that matches all of the directories or files, for example:

 .. code-block:: cmake

  set(CPACK_RPM_REQUIRES_EXCLUDE_FROM "bin/libqsqloci.*\\.so.*")


code:
CPack WIX Generator
-------------------

CPack WIX generator specific options

.. versionadded:: 3.7
  Support :variable:`CPACK_COMPONENT_<compName>_DISABLED` variable.

Variables specific to CPack WIX generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following variables are specific to the installers built on
Windows using WiX.

.. variable:: CPACK_WIX_UPGRADE_GUID

 Upgrade GUID (``Product/@UpgradeCode``)

 Will be automatically generated unless explicitly provided.

 It should be explicitly set to a constant generated globally unique
 identifier (GUID) to allow your installers to replace existing
 installations that use the same GUID.

 You may for example explicitly set this variable in your
 CMakeLists.txt to the value that has been generated per default.  You
 should not use GUIDs that you did not generate yourself or which may
 belong to other projects.

 A GUID shall have the following fixed length syntax::

  XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

 (each X represents an uppercase hexadecimal digit)

.. variable:: CPACK_WIX_PRODUCT_GUID

 Product GUID (``Product/@Id``)

 Will be automatically generated unless explicitly provided.

 If explicitly provided this will set the Product Id of your installer.

 The installer will abort if it detects a pre-existing installation that
 uses the same GUID.

 The GUID shall use the syntax described for CPACK_WIX_UPGRADE_GUID.

.. variable:: CPACK_WIX_LICENSE_RTF

 RTF License File

 If CPACK_RESOURCE_FILE_LICENSE has an .rtf extension it is used as-is.

 If CPACK_RESOURCE_FILE_LICENSE has an .txt extension it is implicitly
 converted to RTF by the WIX Generator.
 The expected encoding of the .txt file is UTF-8.

 With CPACK_WIX_LICENSE_RTF you can override the license file used by the
 WIX Generator in case CPACK_RESOURCE_FILE_LICENSE is in an unsupported
 format or the .txt -> .rtf conversion does not work as expected.

.. variable:: CPACK_WIX_PRODUCT_ICON

 The Icon shown next to the program name in Add/Remove programs.

 If set, this icon is used in place of the default icon.

.. variable:: CPACK_WIX_UI_REF

 This variable allows you to override the Id of the ``<UIRef>`` element
 in the WiX template.

 The default is ``WixUI_InstallDir`` in case no CPack components have
 been defined and ``WixUI_FeatureTree`` otherwise.

.. variable:: CPACK_WIX_UI_BANNER

 The bitmap will appear at the top of all installer pages other than the
 welcome and completion dialogs.

 If set, this image will replace the default banner image.

 This image must be 493 by 58 pixels.

.. variable:: CPACK_WIX_UI_DIALOG

 Background bitmap used on the welcome and completion dialogs.

 If this variable is set, the installer will replace the default dialog
 image.

 This image must be 493 by 312 pixels.

.. variable:: CPACK_WIX_PROGRAM_MENU_FOLDER

 Start menu folder name for launcher.

 If this variable is not set, it will be initialized with CPACK_PACKAGE_NAME

 .. versionadded:: 3.16
  If this variable is set to ``.``, then application shortcuts will be
  created directly in the start menu and the uninstaller shortcut will be
  omitted.

.. variable:: CPACK_WIX_CULTURES

 Language(s) of the installer

 Languages are compiled into the WixUI extension library.  To use them,
 simply provide the name of the culture.  If you specify more than one
 culture identifier in a comma or semicolon delimited list, the first one
 that is found will be used.  You can find a list of supported languages at:
 https://wixtoolset.org/docs/v3/wixui/wixui_localization/

.. variable:: CPACK_WIX_TEMPLATE

 Template file for WiX generation

 If this variable is set, the specified template will be used to generate
 the WiX wxs file.  This should be used if further customization of the
 output is required. The template contents will override the effect of most
 ``CPACK_WIX_`` variables.

 If this variable is not set, the default MSI template included with CMake
 will be used.

.. variable:: CPACK_WIX_PATCH_FILE

 Optional list of XML files with fragments to be inserted into
 generated WiX sources.

 .. versionadded:: 3.5
  Support listing multiple patch files.

 This optional variable can be used to specify an XML file that the
 WIX generator will use to inject fragments into its generated
 source files.

 Patch files understood by the CPack WIX generator
 roughly follow this RELAX NG compact schema:

 .. code-block:: none

    start = CPackWiXPatch

    CPackWiXPatch = element CPackWiXPatch { CPackWiXFragment* }

    CPackWiXFragment = element CPackWiXFragment
    {
        attribute Id { string },
        fragmentContent*
    }

    fragmentContent = element * - CPackWiXFragment
    {
        (attribute * { text } | text | fragmentContent)*
    }

 Currently fragments can be injected into most
 Component, File, Directory and Feature elements.

 .. versionadded:: 3.3
  The following additional special Ids can be used:

  * ``#PRODUCT`` for the ``<Product>`` element.
  * ``#PRODUCTFEATURE`` for the root ``<Feature>`` element.

 .. versionadded:: 3.7
  Support patching arbitrary ``<Feature>`` elements.

 .. versionadded:: 3.9
  Allow setting additional attributes.

 The following example illustrates how this works.

 Given that the WIX generator creates the following XML element:

 .. code-block:: xml

    <Component Id="CM_CP_applications.bin.my_libapp.exe" Guid="*"/>

 The following XML patch file may be used to inject an Environment element
 into it:

 .. code-block:: xml

    <CPackWiXPatch>
      <CPackWiXFragment Id="CM_CP_applications.bin.my_libapp.exe">
        <Environment Id="MyEnvironment" Action="set"
          Name="MyVariableName" Value="MyVariableValue"/>
      </CPackWiXFragment>
    </CPackWiXPatch>

.. variable:: CPACK_WIX_EXTRA_SOURCES

 Extra WiX source files

 This variable provides an optional list of extra WiX source files (.wxs)
 that should be compiled and linked.  The full path to source files is
 required.

.. variable:: CPACK_WIX_EXTRA_OBJECTS

 Extra WiX object files or libraries

 This variable provides an optional list of extra WiX object (.wixobj)
 and/or WiX library (.wixlib) files.  The full path to objects and libraries
 is required.

.. variable:: CPACK_WIX_EXTENSIONS

 This variable provides a list of additional extensions for the WiX
 tools light and candle.

.. variable:: CPACK_WIX_<TOOL>_EXTENSIONS

 This is the tool specific version of CPACK_WIX_EXTENSIONS.
 ``<TOOL>`` can be either LIGHT or CANDLE.

.. variable:: CPACK_WIX_<TOOL>_EXTRA_FLAGS

 This list variable allows you to pass additional
 flags to the WiX tool ``<TOOL>``.

 Use it at your own risk.
 Future versions of CPack may generate flags which may be in conflict
 with your own flags.

 ``<TOOL>`` can be either LIGHT or CANDLE.

.. variable:: CPACK_WIX_CMAKE_PACKAGE_REGISTRY

 If this variable is set the generated installer will create
 an entry in the windows registry key
 ``HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>``
 The value for ``<PackageName>`` is provided by this variable.

 Assuming you also install a CMake configuration file this will
 allow other CMake projects to find your package with
 the :command:`find_package` command.

.. variable:: CPACK_WIX_PROPERTY_<PROPERTY>

 .. versionadded:: 3.1

 This variable can be used to provide a value for
 the Windows Installer property ``<PROPERTY>``

 The following list contains some example properties that can be used to
 customize information under
 "Programs and Features" (also known as "Add or Remove Programs")

 * ARPCOMMENTS - Comments
 * ARPHELPLINK - Help and support information URL
 * ARPURLINFOABOUT - General information URL
 * ARPURLUPDATEINFO - Update information URL
 * ARPHELPTELEPHONE - Help and support telephone number
 * ARPSIZE - Size (in kilobytes) of the application

.. variable:: CPACK_WIX_ROOT_FEATURE_TITLE

 .. versionadded:: 3.7

 Sets the name of the root install feature in the WIX installer. Same as
 CPACK_COMPONENT_<compName>_DISPLAY_NAME for components.

.. variable:: CPACK_WIX_ROOT_FEATURE_DESCRIPTION

 .. versionadded:: 3.7

 Sets the description of the root install feature in the WIX installer. Same as
 CPACK_COMPONENT_<compName>_DESCRIPTION for components.

.. variable:: CPACK_WIX_SKIP_PROGRAM_FOLDER

 .. versionadded:: 3.7

 If this variable is set to true, the default install location
 of the generated package will be CPACK_PACKAGE_INSTALL_DIRECTORY directly.
 The install location will not be located relatively below
 ProgramFiles or ProgramFiles64.

  .. note::
    Installers created with this feature do not take differences
    between the system on which the installer is created
    and the system on which the installer might be used into account.

    It is therefore possible that the installer e.g. might try to install
    onto a drive that is unavailable or unintended or a path that does not
    follow the localization or convention of the system on which the
    installation is performed.

.. variable:: CPACK_WIX_ROOT_FOLDER_ID

 .. versionadded:: 3.9

 This variable allows specification of a custom root folder ID.
 The generator specific ``<64>`` token can be used for
 folder IDs that come in 32-bit and 64-bit variants.
 In 32-bit builds the token will expand empty while in 64-bit builds
 it will expand to ``64``.

 When unset generated installers will default installing to
 ``ProgramFiles<64>Folder``.

.. variable:: CPACK_WIX_ROOT

 This variable can optionally be set to the root directory
 of a custom WiX Toolset installation.

 When unspecified CPack will try to locate a WiX Toolset
 installation via the ``WIX`` environment variable instead.

.. variable:: CPACK_WIX_CUSTOM_XMLNS

 .. versionadded:: 3.19

 This variable provides a list of custom namespace declarations that are necessary
 for using WiX extensions. Each declaration should be in the form name=url, where
 name is the plain namespace without the usual xmlns: prefix and url is an unquoted
 namespace url. A list of commonly known WiX schemata can be found here:
 https://wixtoolset.org/docs/v3/xsd/

.. variable:: CPACK_WIX_SKIP_WIX_UI_EXTENSION

 .. versionadded:: 3.23

 If this variable is set then the inclusion of WixUIExtensions is skipped,
 i.e. the ``-ext "WixUIExtension"`` command line is not included during
 the execution of the WiX light tool.

.. variable:: CPACK_WIX_ARCHITECTURE

 .. versionadded:: 3.24

 This variable can be optionally set to specify the target architecture
 of the installer. May for example be set to ``x64`` or ``arm64``.

 When unspecified, CPack will default to ``x64`` or ``x86``.

.. variable:: CPACK_WIX_INSTALL_SCOPE

 .. versionadded:: 3.29

 This variable can be optionally set to specify the ``InstallScope``
 of the installer:

 ``perMachine`` (default)
   Create an installer that installs for all users and requires
   administrative privileges.  Start menu entries created by the
   installer are visible to all users.

 ``perUser``
   Not yet supported. This is reserved for future use.

 ``NONE``
   Create an installer without any ``InstallScope`` attribute.

   .. deprecated:: 3.29

     This value is only for compatibility with the inconsistent behavior used
     by CPack 3.28 and older.  The resulting installer requires administrative
     privileges and installs into the system-wide ``ProgramFiles`` directory,
     but the start menu entry and uninstaller registration are created only
     for the current user.

 See https://wixtoolset.org/docs/v3/xsd/wix/package/


code:
ADSP_ROOT
---------

.. versionadded:: 3.24

.. include:: ENV_VAR.txt

The ``ADSP_ROOT`` environment variable specifies a default value
for the :variable:`CMAKE_ADSP_ROOT` variable when there is no explicit
configuration given on the first run while creating a new build tree.


code:
ASM<DIALECT>
------------

.. include:: ENV_VAR.txt

Preferred executable for compiling a specific dialect of assembly language
files. ``ASM<DIALECT>`` can be one of:

* ``ASM``
* ``ASM_NASM`` (Netwide Assembler)
* ``ASM_MASM`` (Microsoft Assembler)
* ``ASM_MARMASM`` (Microsoft ARM Assembler)
* ``ASM-ATT`` (Assembler AT&T)

Will only be used by CMake on the first configuration to determine
``ASM<DIALECT>`` compiler, after which the value for ``ASM<DIALECT>`` is stored
in the cache as
:variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`. For subsequent
configuration runs, the environment variable will be ignored in favor of
:variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`.

.. note::
  Options that are required to make the compiler work correctly can be included;
  they can not be changed.

.. code-block:: console

  $ export ASM="custom-compiler --arg1 --arg2"


code:
ASM<DIALECT>FLAGS
-----------------

.. include:: ENV_VAR.txt

Add default compilation flags to be used when compiling a specific dialect
of an assembly language.  ``ASM<DIALECT>FLAGS`` can be one of:

* ``ASMFLAGS``
* ``ASM_NASMFLAGS``
* ``ASM_MASMFLAGS``
* ``ASM_MARMASMFLAGS``
* ``ASM-ATTFLAGS``

.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``ASM<DIALECT>``
.. include:: LANG_FLAGS.txt

See also :variable:`CMAKE_ASM<DIALECT>_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.


code:
CC
--

.. include:: ENV_VAR.txt

Preferred executable for compiling ``C`` language files. Will only be used by
CMake on the first configuration to determine ``C`` compiler, after which the
value for ``CC`` is stored in the cache as
:variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run
(including the first), the environment variable will be ignored if the
:variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.

.. note::
  Options that are required to make the compiler work correctly can be included;
  they can not be changed.

.. code-block:: console

  $ export CC="custom-compiler --arg1 --arg2"


code:
CCMAKE_COLORS
-------------

.. versionadded:: 3.18

Determines what colors are used by the CMake curses interface,
when run on a terminal that supports colors.
The syntax follows the same conventions as ``LS_COLORS``;
that is, a list of key/value pairs separated by ``:``.

Keys are a single letter corresponding to a CMake cache variable type:

- ``s``: A ``STRING``.
- ``p``: A ``FILEPATH``.
- ``c``: A value which has an associated list of choices.
- ``y``: A ``BOOL`` which has a true-like value (e.g. ``ON``, ``YES``).
- ``n``: A ``BOOL`` which has a false-like value (e.g. ``OFF``, ``NO``).

Values are an integer number that specifies what color to use.
``0`` is black (you probably don't want to use that).
Others are determined by your terminal's color support.
Most (color) terminals will support at least 8 or 16 colors.
Some will support up to 256 colors. The colors will likely match
`this chart <https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg>`_,
although the first 16 colors may match the original
`CGA color palette <https://en.wikipedia.org/wiki/Color_Graphics_Adapter#Color_palette>`_.
(Many modern terminal emulators also allow their color palette,
at least for the first 16 colors, to be configured by the user.)

Note that fairly minimal checking is done for bad colors
(although a value higher than what curses believes your terminal supports
will be silently ignored) or bad syntax.

For example::

  CCMAKE_COLORS='s=39:p=220:c=207:n=196:y=46'


code:
CFLAGS
------

.. include:: ENV_VAR.txt

Add default compilation flags to be used when compiling ``C`` files.

.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``C``
.. include:: LANG_FLAGS.txt

See also :variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.


code:
CMAKE_APPBUNDLE_PATH
--------------------

.. include:: ENV_VAR.txt

The ``CMAKE_APPBUNDLE_PATH`` environment variable may be set to a list of
directories to be searched for macOS application bundles
by the :command:`find_program` and :command:`find_package` commands.

This variable may hold a single directory or a list of directories separated
by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
variable convention on those platforms).

See also the :variable:`CMAKE_APPBUNDLE_PATH` CMake variable.


code:
CMAKE_APPLE_SILICON_PROCESSOR
-----------------------------

.. versionadded:: 3.19.2

.. include:: ENV_VAR.txt

On Apple Silicon hosts running macOS, set this environment variable to tell
CMake what architecture to use for :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`.
The value must be either ``arm64`` or ``x86_64``.

The :variable:`CMAKE_APPLE_SILICON_PROCESSOR` normal variable, if set,
overrides this environment variable.


code:
CMAKE_BUILD_PARALLEL_LEVEL
--------------------------

.. versionadded:: 3.12

.. include:: ENV_VAR.txt

Specifies the maximum number of concurrent processes to use when building
using the ``cmake --build`` command line
:ref:`Build Tool Mode <Build Tool Mode>`.
For example, if ``CMAKE_BUILD_PARALLEL_LEVEL`` is set to 8, the
underlying build tool will execute up to 8 jobs concurrently as if
``cmake --build`` were invoked with the
:option:`--parallel 8 <cmake--build --parallel>` option.

If this variable is defined empty the native build tool's default number is
used.


code:
CMAKE_BUILD_TYPE
----------------

.. versionadded:: 3.22

.. include:: ENV_VAR.txt

The ``CMAKE_BUILD_TYPE`` environment variable specifies a default value
for the :variable:`CMAKE_BUILD_TYPE` variable when there is no explicit
configuration given on the first run while creating a new build tree.


code:
CMAKE_COLOR_DIAGNOSTICS
-----------------------

.. versionadded:: 3.24

.. include:: ENV_VAR.txt

Specifies a default value for the :variable:`CMAKE_COLOR_DIAGNOSTICS` variable
when there is no explicit value given on the first run.


code:
CMAKE_CONFIGURATION_TYPES
-------------------------

.. versionadded:: 3.22

.. include:: ENV_VAR.txt

The ``CMAKE_CONFIGURATION_TYPES`` environment variable specifies a
default value for the :variable:`CMAKE_CONFIGURATION_TYPES` variable
when there is no explicit configuration given on the first run while
creating a new build tree.


code:
CMAKE_CONFIG_TYPE
-----------------

.. include:: ENV_VAR.txt

The default build configuration for :ref:`Build Tool Mode` and
``ctest`` build handler when there is no explicit configuration given.


code:
CMAKE_CROSSCOMPILING_EMULATOR
-----------------------------

.. versionadded:: 3.28

.. include:: ENV_VAR.txt

The default value for :variable:`CMAKE_CROSSCOMPILING_EMULATOR` when there
is no explicit configuration given on the first run while creating a new
build tree.  On later runs in an existing build tree the value persists in
the cache as :variable:`CMAKE_CROSSCOMPILING_EMULATOR`.


code:
CMAKE_EXPORT_COMPILE_COMMANDS
-----------------------------

.. versionadded:: 3.17

.. include:: ENV_VAR.txt

The default value for :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` when there
is no explicit configuration given on the first run while creating a new
build tree.  On later runs in an existing build tree the value persists in
the cache as :variable:`CMAKE_EXPORT_COMPILE_COMMANDS`.


code:
CMAKE_FRAMEWORK_PATH
--------------------

.. include:: ENV_VAR.txt

The ``CMAKE_FRAMEWORK_PATH`` environment variable may be set to a list of
directories to be searched for macOS frameworks by the :command:`find_library`,
:command:`find_package`, :command:`find_path` and :command:`find_file` commands.

This variable may hold a single directory or a list of directories separated
by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
variable convention on those platforms).

See also the :variable:`CMAKE_FRAMEWORK_PATH` CMake variable.


code:
CMAKE_GENERATOR
---------------

.. versionadded:: 3.15

.. include:: ENV_VAR.txt

Specifies the CMake default generator to use when no generator is supplied
with :option:`-G <cmake -G>`. If the provided value doesn't name a generator
known by CMake, the internal default is used.  Either way the resulting
generator selection is stored in the :variable:`CMAKE_GENERATOR` variable.

Some generators may be additionally configured using the environment
variables:

* :envvar:`CMAKE_GENERATOR_PLATFORM`
* :envvar:`CMAKE_GENERATOR_TOOLSET`
* :envvar:`CMAKE_GENERATOR_INSTANCE`


code:
CMAKE_GENERATOR_INSTANCE
------------------------

.. versionadded:: 3.15

.. include:: ENV_VAR.txt

Default value for :variable:`CMAKE_GENERATOR_INSTANCE` if no Cache entry is
present. This value is only applied if :envvar:`CMAKE_GENERATOR` is set.


code:
CMAKE_GENERATOR_PLATFORM
------------------------

.. versionadded:: 3.15

.. include:: ENV_VAR.txt

Default value for :variable:`CMAKE_GENERATOR_PLATFORM` if no Cache entry
is present and no value is specified by :option:`cmake -A` option.
This value is only applied if :envvar:`CMAKE_GENERATOR` is set.


code:
CMAKE_GENERATOR_TOOLSET
-----------------------

.. versionadded:: 3.15

.. include:: ENV_VAR.txt

Default value for :variable:`CMAKE_GENERATOR_TOOLSET` if no Cache entry
is present and no value is specified by :option:`cmake -T` option.
This value is only applied if :envvar:`CMAKE_GENERATOR` is set.


code:
CMAKE_INCLUDE_PATH
------------------

.. include:: ENV_VAR.txt

The ``CMAKE_INCLUDE_PATH`` environment variable may be set to a list of
directories to be searched by the :command:`find_file` and :command:`find_path` commands.

This variable may hold a single directory or a list of directories separated
by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
variable convention on those platforms).

See also the :variable:`CMAKE_INCLUDE_PATH` CMake variable.


code:
CMAKE_INSTALL_MODE
------------------

.. versionadded:: 3.22

.. include:: ENV_VAR.txt

The ``CMAKE_INSTALL_MODE`` environment variable allows users to operate
CMake in an alternate mode of :command:`file(INSTALL)` and :command:`install()`.

The default behavior for an installation is to copy a source file from a
source directory into a destination directory. This environment variable
however allows the user to override this behavior, causing CMake to create
symbolic links instead.

Usage Scenarios
^^^^^^^^^^^^^^^

Installing symbolic links rather than copying files can help in the following
ways:

* Conserving storage space because files do not have to be duplicated on disk.
* Changes to the source of the symbolic link are seen at the install
  destination without having to re-run the install step.
* Editing through the link at the install destination will modify the source
  of the link. This may be useful when dealing with CMake project hierarchies,
  i.e. using :module:`ExternalProject` and consistent source navigation and
  refactoring is desired across projects.

Allowed Values
^^^^^^^^^^^^^^

The following values are allowed for ``CMAKE_INSTALL_MODE``:

``COPY``, empty or unset
  Duplicate the file at its destination.  This is the default behavior.

``ABS_SYMLINK``
  Create an *absolute* symbolic link to the source file at the destination.
  Halt with an error if the link cannot be created.

``ABS_SYMLINK_OR_COPY``
  Like ``ABS_SYMLINK`` but fall back to silently copying if the symlink
  couldn't be created.

``REL_SYMLINK``
  Create a *relative* symbolic link to the source file at the destination.
  Halt with an error if the link cannot be created.

``REL_SYMLINK_OR_COPY``
  Like ``REL_SYMLINK`` but fall back to silently copying if the symlink
  couldn't be created.

``SYMLINK``
  Try as if through ``REL_SYMLINK`` and fall back to ``ABS_SYMLINK`` if the
  referenced file cannot be expressed using a relative path.
  Halt with an error if the link cannot be created.

``SYMLINK_OR_COPY``
  Like ``SYMLINK`` but fall back to silently copying if the symlink couldn't
  be created.

.. note::
  A symbolic link consists of a reference file path rather than contents of its
  own, hence there are two ways to express the relation, either by a *relative*
  or an *absolute* path.

When To Set The Environment Variable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For the environment variable to take effect, it must be set during the correct
build phase(s).

* If the project calls :command:`file(INSTALL)` directly, the environment
  variable must be set during the configuration phase.
* In order to apply to :command:`install()`, the environment variable must be
  set during installation.  This could be during a build if using the
  ``install`` or ``package`` build targets, or separate from the build when
  invoking an install or running :manual:`cpack <cpack(1)>` from the command
  line.
* When using :module:`ExternalProject`, it might be required during the build
  phase, since the external project's own configure, build and install steps
  will execute during the main project's build phase.

Given the above, it is recommended to set the environment variable consistently
across all phases (configure, build and install).

Caveats
^^^^^^^

Use this environment variable with caution. The following highlights some
points to be considered:

* ``CMAKE_INSTALL_MODE`` only affects files, not directories.

* Symbolic links are not available on all platforms.

* The way this environment variable interacts with the install step of
  :module:`ExternalProject` is more complex. For further details, see that
  module's documentation.

* A symbolic link ties the destination to the source in a persistent way.
  Writing to either of the two affects both file system objects.
  This is in contrast to normal install behavior which only copies files as
  they were at the time the install was performed, with no enduring
  relationship between the source and destination of the install.

* Combining ``CMAKE_INSTALL_MODE`` with :prop_tgt:`IOS_INSTALL_COMBINED` is
  not supported.

* Changing ``CMAKE_INSTALL_MODE`` from what it was on a previous run can lead
  to unexpected results.  Moving from a non-symlinking mode to a symlinking
  mode will discard any previous file at the destination, but the reverse is
  not true.  Once a symlink exists at the destination, even if you switch to a
  non-symlink mode, the symlink will continue to exist at the destination and
  will not be replaced by an actual file.


code:
CMAKE_INSTALL_PREFIX
--------------------

.. versionadded:: 3.29

.. include:: ENV_VAR.txt

The ``CMAKE_INSTALL_PREFIX`` environment variable specifies a custom default
value for the :variable:`CMAKE_INSTALL_PREFIX` variable in place of the
default values specified by CMake itself. The value specified must be an
absolute path to a directory.