code:
try_compile
-----------

.. only:: html

   .. contents::

Try building some code.

.. _`Try Compiling Whole Projects`:

Try Compiling Whole Projects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  try_compile(<compileResultVar> PROJECT <projectName>
              SOURCE_DIR <srcdir>
              [BINARY_DIR <bindir>]
              [TARGET <targetName>]
              [LOG_DESCRIPTION <text>]
              [NO_CACHE]
              [NO_LOG]
              [CMAKE_FLAGS <flags>...]
              [OUTPUT_VARIABLE <var>])

.. versionadded:: 3.25

Try building a project.  Build success returns ``TRUE`` and build failure
returns ``FALSE`` in ``<compileResultVar>``.

In this form, ``<srcdir>`` should contain a complete CMake project with a
``CMakeLists.txt`` file and all sources.  The ``<bindir>`` and ``<srcdir>``
will not be deleted after this command is run.  Specify ``<targetName>`` to
build a specific target instead of the ``all`` or ``ALL_BUILD`` target.  See
below for the meaning of other options.

.. versionchanged:: 3.24
  CMake variables describing platform settings, and those listed by the
  :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable, are propagated
  into the project's build configuration.  See policy :policy:`CMP0137`.
  Previously this was only done by the
  :ref:`source file <Try Compiling Source Files>` signature.

.. versionadded:: 3.26
  This command records a
  :ref:`configure-log try_compile event <try_compile configure-log event>`
  if the ``NO_LOG`` option is not specified.

This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.

.. code-block:: cmake

  try_compile(<compileResultVar> <bindir> <srcdir>
              <projectName> [<targetName>]
              [CMAKE_FLAGS <flags>...]
              [OUTPUT_VARIABLE <var>])

.. _`Try Compiling Source Files`:

Try Compiling Source Files
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  try_compile(<compileResultVar>
              [SOURCES_TYPE <type>]
              <SOURCES <srcfile...>                 |
               SOURCE_FROM_CONTENT <name> <content> |
               SOURCE_FROM_VAR <name> <var>         |
               SOURCE_FROM_FILE <name> <path>       >...
              [LOG_DESCRIPTION <text>]
              [NO_CACHE]
              [NO_LOG]
              [CMAKE_FLAGS <flags>...]
              [COMPILE_DEFINITIONS <defs>...]
              [LINK_OPTIONS <options>...]
              [LINK_LIBRARIES <libs>...]
              [LINKER_LANGUAGE <lang>]
              [OUTPUT_VARIABLE <var>]
              [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
              [<LANG>_STANDARD <std>]
              [<LANG>_STANDARD_REQUIRED <bool>]
              [<LANG>_EXTENSIONS <bool>]
              )

.. versionadded:: 3.25

Try building an executable or static library from one or more source files
(which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE`
variable). Build success returns ``TRUE`` and build failure returns ``FALSE``
in ``<compileResultVar>``.

In this form, one or more source files must be provided. Additionally, one of
``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords.

If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to
``EXECUTABLE``, the sources must include a definition for ``main`` and CMake
will create a ``CMakeLists.txt`` file to build the source(s) as an executable.
If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``,
a static library will be built instead and no definition for ``main`` is
required.  For an executable, the generated ``CMakeLists.txt`` file would
contain something like the following:

.. code-block:: cmake

  add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
  include_directories(${INCLUDE_DIRECTORIES})
  link_directories(${LINK_DIRECTORIES})
  add_executable(cmTryCompileExec <srcfile>...)
  target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
  target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})

CMake automatically generates, for each ``try_compile`` operation, a
unique directory under ``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch``
with an unspecified name.  These directories are cleaned automatically unless
:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to :program:`cmake`.
Such directories from previous runs are also unconditionally cleaned at the
beginning of any :program:`cmake` execution.

This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.

.. code-block:: cmake

  try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...>
              [CMAKE_FLAGS <flags>...]
              [COMPILE_DEFINITIONS <defs>...]
              [LINK_OPTIONS <options>...]
              [LINK_LIBRARIES <libs>...]
              [OUTPUT_VARIABLE <var>]
              [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
              [<LANG>_STANDARD <std>]
              [<LANG>_STANDARD_REQUIRED <bool>]
              [<LANG>_EXTENSIONS <bool>]
              )

In this version, ``try_compile`` will use ``<bindir>/CMakeFiles/CMakeTmp`` for
its operation, and all such files will be cleaned automatically.
For debugging, :option:`--debug-trycompile <cmake --debug-trycompile>` can be
passed to :program:`cmake` to avoid this clean.  However, multiple sequential
``try_compile`` operations, if given the same ``<bindir>``, will reuse this
single output directory, such that you can only debug one such ``try_compile``
call at a time.  Use of the newer signature is recommended to simplify
debugging of multiple ``try_compile`` operations.

.. _`try_compile Options`:

Options
^^^^^^^

The options for the above signatures are:

``CMAKE_FLAGS <flags>...``
  Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed
  to the :manual:`cmake(1)` command-line used to drive the test build.
  The above example shows how values for variables
  ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
  are used.

``COMPILE_DEFINITIONS <defs>...``
  Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions`
  in the generated test project.

``COPY_FILE <fileName>``
  Copy the built executable or static library to the given ``<fileName>``.

``COPY_FILE_ERROR <var>``
  Use after ``COPY_FILE`` to capture into variable ``<var>`` any error
  message encountered while trying to copy the file.

``LINK_LIBRARIES <libs>...``
  Specify libraries to be linked in the generated project.
  The list of libraries may refer to system libraries and to
  :ref:`Imported Targets <Imported Targets>` from the calling project.

  If this option is specified, any ``-DLINK_LIBRARIES=...`` value
  given to the ``CMAKE_FLAGS`` option will be ignored.

  .. versionadded:: 3.29
    Alias targets to imported libraries are also supported.

``LINK_OPTIONS <options>...``
  .. versionadded:: 3.14

  Specify link step options to pass to :command:`target_link_options` or to
  set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
  project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.

``LINKER_LANGUAGE <lang>```
  .. versionadded:: 3.29

  Specify the :prop_tgt:`LINKER_LANGUAGE` target property of the generated
  project.  When using multiple source files with different languages, set
  this to the language of the source file containing the program entry point,
  e.g., ``main``.

``LOG_DESCRIPTION <text>``
  .. versionadded:: 3.26

  Specify a non-empty text description of the purpose of the check.
  This is recorded in the :manual:`cmake-configure-log(7)` entry.

``NO_CACHE``
  .. versionadded:: 3.25

  The result will be stored in a normal variable rather than a cache entry.

  The result variable is normally cached so that a simple pattern can be used
  to avoid repeating the test on subsequent executions of CMake:

  .. code-block:: cmake

    if(NOT DEFINED RESULTVAR)
      # ...(check-specific setup code)...
      try_compile(RESULTVAR ...)
      # ...(check-specific logging and cleanup code)...
    endif()

  If the guard variable and result variable are not the same (for example, if
  the test is part of a larger inspection), ``NO_CACHE`` may be useful to avoid
  leaking the intermediate result variable into the cache.

``NO_LOG``
  .. versionadded:: 3.26

  Do not record a :manual:`cmake-configure-log(7)` entry for this call.

``OUTPUT_VARIABLE <var>``
  Store the output from the build process in the given variable.

``SOURCE_FROM_CONTENT <name> <content>``
  .. versionadded:: 3.25

  Write ``<content>`` to a file named ``<name>`` in the operation directory.
  This can be used to bypass the need to separately write a source file when
  the contents of the file are dynamically specified. The specified ``<name>``
  is not allowed to contain path components.

  ``SOURCE_FROM_CONTENT`` may be specified multiple times.

``SOURCE_FROM_FILE <name> <path>``
  .. versionadded:: 3.25

  Copy ``<path>`` to a file named ``<name>`` in the operation directory. This
  can be used to consolidate files into the operation directory, which may be
  useful if a source which already exists (i.e. as a stand-alone file in a
  project's source repository) needs to refer to other file(s) created by
  ``SOURCE_FROM_*``. (Otherwise, ``SOURCES`` is usually more convenient.) The
  specified ``<name>`` is not allowed to contain path components.

``SOURCE_FROM_VAR <name> <var>``
  .. versionadded:: 3.25

  Write the contents of ``<var>`` to a file named ``<name>`` in the operation
  directory. This is the same as ``SOURCE_FROM_CONTENT``, but takes the
  contents from the specified CMake variable, rather than directly, which may
  be useful when passing arguments through a function which wraps
  ``try_compile``. The specified ``<name>`` is not allowed to contain path
  components.

  ``SOURCE_FROM_VAR`` may be specified multiple times.

``SOURCES_TYPE <type>``
  .. versionadded:: 3.28

  Sources may be classified using the ``SOURCES_TYPE`` argument. Once
  specified, all subsequent sources specified will be treated as that type
  until another ``SOURCES_TYPE`` is given. Available types are:

  ``NORMAL``
    Sources are not added to any ``FILE_SET`` in the generated project.

  ``CXX_MODULE``
    .. versionadded:: 3.28

    Sources are added to a ``FILE_SET`` of type ``CXX_MODULES`` in the
    generated project.

  The default type of sources is ``NORMAL``.

``<LANG>_STANDARD <std>``
  .. versionadded:: 3.8

  Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`,
  :prop_tgt:`OBJC_STANDARD`, :prop_tgt:`OBJCXX_STANDARD`,
  or :prop_tgt:`CUDA_STANDARD` target property of the generated project.

``<LANG>_STANDARD_REQUIRED <bool>``
  .. versionadded:: 3.8

  Specify the :prop_tgt:`C_STANDARD_REQUIRED`,
  :prop_tgt:`CXX_STANDARD_REQUIRED`, :prop_tgt:`OBJC_STANDARD_REQUIRED`,
  :prop_tgt:`OBJCXX_STANDARD_REQUIRED`,or :prop_tgt:`CUDA_STANDARD_REQUIRED`
  target property of the generated project.

``<LANG>_EXTENSIONS <bool>``
  .. versionadded:: 3.8

  Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_EXTENSIONS`,
  :prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`,
  or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project.

Other Behavior Settings
^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.4
  If set, the following variables are passed in to the generated
  try_compile CMakeLists.txt to initialize compile target properties with
  default values:

  * :variable:`CMAKE_CUDA_RUNTIME_LIBRARY`
  * :variable:`CMAKE_ENABLE_EXPORTS`
  * :variable:`CMAKE_LINK_SEARCH_START_STATIC`
  * :variable:`CMAKE_LINK_SEARCH_END_STATIC`
  * :variable:`CMAKE_MSVC_RUNTIME_LIBRARY`
  * :variable:`CMAKE_POSITION_INDEPENDENT_CODE`
  * :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY`

  If :policy:`CMP0056` is set to ``NEW``, then
  :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well.

.. versionchanged:: 3.14
  If :policy:`CMP0083` is set to ``NEW``, then in order to obtain correct
  behavior at link time, the ``check_pie_supported()`` command from the
  :module:`CheckPIESupported` module must be called before using the
  ``try_compile`` command.

The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated
through to the generated test project.

Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build
configuration:

* For multi-config generators, this selects which configuration to build.

* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in
  the test project.

.. versionadded:: 3.6
  Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify
  the type of target used for the source file signature.

.. versionadded:: 3.6
  Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify
  variables that must be propagated into the test project.  This variable is
  meant for use only in toolchain files and is only honored by the
  ``try_compile()`` command for the source files form, not when given a whole
  project.

.. versionchanged:: 3.8
  If :policy:`CMP0067` is set to ``NEW``, or any of the ``<LANG>_STANDARD``,
  ``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_EXTENSIONS`` options are used,
  then the language standard variables are honored:

  * :variable:`CMAKE_C_STANDARD`
  * :variable:`CMAKE_C_STANDARD_REQUIRED`
  * :variable:`CMAKE_C_EXTENSIONS`
  * :variable:`CMAKE_CXX_STANDARD`
  * :variable:`CMAKE_CXX_STANDARD_REQUIRED`
  * :variable:`CMAKE_CXX_EXTENSIONS`
  * :variable:`CMAKE_OBJC_STANDARD`
  * :variable:`CMAKE_OBJC_STANDARD_REQUIRED`
  * :variable:`CMAKE_OBJC_EXTENSIONS`
  * :variable:`CMAKE_OBJCXX_STANDARD`
  * :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED`
  * :variable:`CMAKE_OBJCXX_EXTENSIONS`
  * :variable:`CMAKE_CUDA_STANDARD`
  * :variable:`CMAKE_CUDA_STANDARD_REQUIRED`
  * :variable:`CMAKE_CUDA_EXTENSIONS`

  Their values are used to set the corresponding target properties in
  the generated project (unless overridden by an explicit option).

.. versionchanged:: 3.14
  For the :generator:`Green Hills MULTI` generator, the GHS toolset and target
  system customization cache variables are also propagated into the test
  project.

.. versionadded:: 3.24
  The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be
  set to disable passing platform variables into the test project.

.. versionadded:: 3.25
  If :policy:`CMP0141` is set to ``NEW``, one can use
  :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify the MSVC debug
  information format.

See Also
^^^^^^^^

* :command:`try_run`


code:
try_run
-------

.. only:: html

   .. contents::

Try compiling and then running some code.

Try Compiling and Running Source Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  try_run(<runResultVar> <compileResultVar>
          [SOURCES_TYPE <type>]
          <SOURCES <srcfile...>                 |
           SOURCE_FROM_CONTENT <name> <content> |
           SOURCE_FROM_VAR <name> <var>         |
           SOURCE_FROM_FILE <name> <path>       >...
          [LOG_DESCRIPTION <text>]
          [NO_CACHE]
          [NO_LOG]
          [CMAKE_FLAGS <flags>...]
          [COMPILE_DEFINITIONS <defs>...]
          [LINK_OPTIONS <options>...]
          [LINK_LIBRARIES <libs>...]
          [COMPILE_OUTPUT_VARIABLE <var>]
          [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
          [<LANG>_STANDARD <std>]
          [<LANG>_STANDARD_REQUIRED <bool>]
          [<LANG>_EXTENSIONS <bool>]
          [RUN_OUTPUT_VARIABLE <var>]
          [RUN_OUTPUT_STDOUT_VARIABLE <var>]
          [RUN_OUTPUT_STDERR_VARIABLE <var>]
          [WORKING_DIRECTORY <var>]
          [ARGS <args>...]
          )

.. versionadded:: 3.25

Try building an executable from one or more source files.  Build success
returns ``TRUE`` and build failure returns ``FALSE`` in ``<compileResultVar>``.
If the build succeeds, this runs the executable and stores the exit code in
``<runResultVar>``.  If the executable was built, but failed to run, then
``<runResultVar>`` will be set to ``FAILED_TO_RUN``.  See command
:command:`try_compile` for documentation of options common to both commands,
and for information on how the test project is constructed to build the source
file.

One or more source files must be provided. Additionally, one of ``SOURCES``
and/or ``SOURCE_FROM_*`` must precede other keywords.

.. versionadded:: 3.26
  This command records a
  :ref:`configure-log try_run event <try_run configure-log event>`
  if the ``NO_LOG`` option is not specified.

This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.

.. code-block:: cmake

  try_run(<runResultVar> <compileResultVar>
          <bindir> <srcfile|SOURCES srcfile...>
          [CMAKE_FLAGS <flags>...]
          [COMPILE_DEFINITIONS <defs>...]
          [LINK_OPTIONS <options>...]
          [LINK_LIBRARIES <libs>...]
          [LINKER_LANGUAGE <lang>]
          [COMPILE_OUTPUT_VARIABLE <var>]
          [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
          [<LANG>_STANDARD <std>]
          [<LANG>_STANDARD_REQUIRED <bool>]
          [<LANG>_EXTENSIONS <bool>]
          [RUN_OUTPUT_VARIABLE <var>]
          [OUTPUT_VARIABLE <var>]
          [WORKING_DIRECTORY <var>]
          [ARGS <args>...]
          )

.. _`try_run Options`:

Options
^^^^^^^

The options specific to ``try_run`` are:

``COMPILE_OUTPUT_VARIABLE <var>``
  Report the compile step build output in a given variable.

``OUTPUT_VARIABLE <var>``
  Report the compile build output and the output from running the executable
  in the given variable.  This option exists for legacy reasons and is only
  supported by the old ``try_run`` signature.
  Prefer ``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead.

``RUN_OUTPUT_VARIABLE <var>``
  Report the output from running the executable in a given variable.

``RUN_OUTPUT_STDOUT_VARIABLE <var>``
  .. versionadded:: 3.25

  Report the output of stdout from running the executable in a given variable.

``RUN_OUTPUT_STDERR_VARIABLE <var>``
  .. versionadded:: 3.25

  Report the output of stderr from running the executable in a given variable.

``WORKING_DIRECTORY <var>``
  .. versionadded:: 3.20

  Run the executable in the given directory. If no ``WORKING_DIRECTORY`` is
  specified, the executable will run in ``<bindir>`` or the current build
  directory.

``ARGS <args>...``
  Additional arguments to pass to the executable when running it.

Other Behavior Settings
^^^^^^^^^^^^^^^^^^^^^^^

Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build
configuration:

* For multi-config generators, this selects which configuration to build.

* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in
  the test project.

Behavior when Cross Compiling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.3
  Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled binaries.

When cross compiling, the executable compiled in the first step
usually cannot be run on the build host.  The ``try_run`` command checks
the :variable:`CMAKE_CROSSCOMPILING` variable to detect whether CMake is in
cross-compiling mode.  If that is the case, it will still try to compile
the executable, but it will not try to run the executable unless the
:variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable is set.  Instead it
will create cache variables which must be filled by the user or by
presetting them in some CMake script file to the values the executable
would have produced if it had been run on its actual target platform.
These cache entries are:

``<runResultVar>``
  Exit code if the executable were to be run on the target platform.

``<runResultVar>__TRYRUN_OUTPUT``
  Output from stdout and stderr if the executable were to be run on
  the target platform.  This is created only if the
  ``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` option was used.

In order to make cross compiling your project easier, use ``try_run``
only if really required.  If you use ``try_run``, use the
``RUN_OUTPUT_STDOUT_VARIABLE``, ``RUN_OUTPUT_STDERR_VARIABLE``,
``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` options only if really
required.  Using them will require that when cross-compiling, the cache
variables will have to be set manually to the output of the executable.
You can also "guard" the calls to ``try_run`` with an :command:`if`
block checking the :variable:`CMAKE_CROSSCOMPILING` variable and
provide an easy-to-preset alternative for this case.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
unset
-----

Unset a variable, cache variable, or environment variable.

Unset Normal Variable or Cache Entry
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  unset(<variable> [CACHE | PARENT_SCOPE])

Removes a normal variable from the current scope, causing it
to become undefined.  If ``CACHE`` is present, then a cache variable
is removed instead of a normal variable.

If ``PARENT_SCOPE`` is present then the variable is removed from the scope
above the current scope.  See the same option in the :command:`set` command
for further details.

.. include:: UNSET_NOTE.txt

Unset Environment Variable
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  unset(ENV{<variable>})

Removes ``<variable>`` from the currently available
:manual:`Environment Variables <cmake-env-variables(7)>`.
Subsequent calls of ``$ENV{<variable>}`` will return the empty string.

This command affects only the current CMake process, not the process
from which CMake was called, nor the system environment at large,
nor the environment of subsequent build or test processes.

See Also
^^^^^^^^

* :command:`set`


code:
use_mangled_mesa
----------------

Disallowed since version 3.0.  See CMake Policy :policy:`CMP0030`.

Copy mesa headers for use in combination with system GL.

.. code-block:: cmake

  use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)

The path to mesa includes, should contain ``gl_mangle.h``.  The mesa
headers are copied to the specified output directory.  This allows
mangled mesa headers to override other GL headers by being added to
the include directory path earlier.


code:
utility_source
--------------

Disallowed since version 3.0.  See CMake Policy :policy:`CMP0034`.

Specify the source tree of a third-party utility.

.. code-block:: cmake

  utility_source(cache_entry executable_name
                 path_to_source [file1 file2 ...])

When a third-party utility's source is included in the distribution,
this command specifies its location and name.  The cache entry will
not be set unless the ``path_to_source`` and all listed files exist.  It
is assumed that the source tree of the utility will have been built
before it is needed.

When cross compiling CMake will print a warning if a ``utility_source()``
command is executed, because in many cases it is used to build an
executable which is executed later on.  This doesn't work when cross
compiling, since the executable can run only on their target platform.
So in this case the cache entry has to be adjusted manually so it
points to an executable which is runnable on the build host.


code:
variable_requires
-----------------

Disallowed since version 3.0.  See CMake Policy :policy:`CMP0035`.

Use the :command:`if` command instead.

Assert satisfaction of an option's required variables.

.. code-block:: cmake

  variable_requires(TEST_VARIABLE RESULT_VARIABLE
                    REQUIRED_VARIABLE1
                    REQUIRED_VARIABLE2 ...)

The first argument (``TEST_VARIABLE``) is the name of the variable to be
tested, if that variable is false nothing else is done.  If
``TEST_VARIABLE`` is true, then the next argument (``RESULT_VARIABLE``)
is a variable that is set to true if all the required variables are set.
The rest of the arguments are variables that must be true or not set
to ``NOTFOUND`` to avoid an error.  If any are not true, an error is
reported.


code:
variable_watch
--------------

Watch the CMake variable for change.

.. code-block:: cmake

  variable_watch(<variable> [<command>])

If the specified ``<variable>`` changes and no ``<command>`` is given,
a message will be printed to inform about the change.

If ``<command>`` is given, this command will be executed instead.
The command will receive the following arguments:
``COMMAND(<variable> <access> <value> <current_list_file> <stack>)``

``<variable>``
 Name of the variable being accessed.

``<access>``
 One of ``READ_ACCESS``, ``UNKNOWN_READ_ACCESS``, ``MODIFIED_ACCESS``,
 ``UNKNOWN_MODIFIED_ACCESS``, or ``REMOVED_ACCESS``.  The ``UNKNOWN_``
 values are only used when the variable has never been set.  Once set,
 they are never used again during the same CMake run, even if the
 variable is later unset.

``<value>``
 The value of the variable.  On a modification, this is the new
 (modified) value of the variable.  On removal, the value is empty.

``<current_list_file>``
 Full path to the file doing the access.

``<stack>``
 List of absolute paths of all files currently on the stack of file
 inclusion, with the bottom-most file first and the currently
 processed file (that is, ``current_list_file``) last.

Note that for some accesses such as :command:`list(APPEND)`, the watcher
is executed twice, first with a read access and then with a write one.
Also note that an :command:`if(DEFINED)` query on the variable does not
register as an access and the watcher is not executed.

Only non-cache variables can be watched using this command.  Access to
cache variables is never watched.  However, the existence of a cache
variable ``var`` causes accesses to the non-cache variable ``var`` to
not use the ``UNKNOWN_`` prefix, even if a non-cache variable ``var``
has never existed.


code:
while
-----

Evaluate a group of commands while a condition is true

.. code-block:: cmake

  while(<condition>)
    <commands>
  endwhile()

All commands between while and the matching :command:`endwhile` are recorded
without being invoked.  Once the :command:`endwhile` is evaluated, the
recorded list of commands is invoked as long as the ``<condition>`` is true.

The ``<condition>`` has the same syntax and is evaluated using the same logic
as described at length for the :command:`if` command.

The commands :command:`break` and :command:`continue` provide means to
escape from the normal control flow.

Per legacy, the :command:`endwhile` command admits
an optional ``<condition>`` argument.
If used, it must be a verbatim repeat of the argument of the opening
``while`` command.

See Also
^^^^^^^^

* :command:`break`
* :command:`continue`
* :command:`foreach`
* :command:`endwhile`


code:
write_file
----------

.. deprecated:: 3.0

  Use the :command:`file(WRITE)` command instead.

.. code-block:: cmake

  write_file(filename "message to write"... [APPEND])

The first argument is the file name, the rest of the arguments are
messages to write.  If the argument ``APPEND`` is specified, then the
message will be appended.

NOTE 1: :command:`file(WRITE)`  and :command:`file(APPEND)`  do exactly
the same as this one but add some more functionality.

NOTE 2: When using ``write_file`` the produced file cannot be used as an
input to CMake (CONFIGURE_FILE, source file ...) because it will lead
to an infinite loop.  Use :command:`configure_file` if you want to
generate input files to CMake.


code:
CPack Archive Generator
-----------------------

CPack generator for packaging files into an archive, which can have
any of the following formats:

  - 7Z - 7zip - (``.7z``)
  - TBZ2 (``.tar.bz2``)
  - TGZ (``.tar.gz``)
  - TXZ (``.tar.xz``)
  - TZ (``.tar.Z``)
  - TZST (``.tar.zst``)
  - ZIP (``.zip``)

.. versionadded:: 3.1
  7Z and TXZ formats support.

.. versionadded:: 3.16
  TZST format support.

When this generator is called from ``CPackSourceConfig.cmake`` (or through
the ``package_source`` target), then the generated archive will contain all
files in the project directory, except those specified in
:variable:`CPACK_SOURCE_IGNORE_FILES`.  The following is one example of
packaging all source files of a project:

.. code-block:: cmake

  set(CPACK_SOURCE_GENERATOR "TGZ")
  set(CPACK_SOURCE_IGNORE_FILES
    \\.git/
    build/
    ".*~$"
  )
  set(CPACK_VERBATIM_VARIABLES YES)
  include(CPack)

When this generator is called from ``CPackConfig.cmake`` (or through the
``package`` target), then the generated archive will contain all files
that have been installed via CMake's :command:`install` command (and the
deprecated commands :command:`install_files`, :command:`install_programs`,
and :command:`install_targets`).

Variables specific to CPack Archive generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. variable:: CPACK_ARCHIVE_FILE_NAME
              CPACK_ARCHIVE_<component>_FILE_NAME

  Package file name without extension.

  :Default: The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
   replaced by '-'.

  The extension is determined from the archive format (see list above) and
  automatically appended to the file name. Note that ``<component>`` is all
  uppercase in the variable name.

  .. versionadded:: 3.9
    Per-component :variable:`!CPACK_ARCHIVE_<component>_FILE_NAME` variables.

.. variable:: CPACK_ARCHIVE_FILE_EXTENSION

  .. versionadded:: 3.25

  Package file extension.

  :Default: Default values are given in the list above.

.. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL

  Enable component packaging.

  :Default: ``OFF``

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

Variables used by CPack Archive generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These variables are used by the Archive generator, but are also available to
CPack generators which are essentially archives at their core. These include:

- :cpack_gen:`CPack Cygwin Generator`
- :cpack_gen:`CPack FreeBSD Generator`

.. variable:: CPACK_ARCHIVE_THREADS

  The number of threads to use when performing the compression.

  .. versionadded:: 3.18

  :Default: ``1``

  If set to ``0``, the number of available cores on the machine will be used instead.
  The default is ``1`` which limits compression to a single thread. Note that
  not all compression modes support threading in all environments. Currently,
  only the XZ compression may support it.

  See also the :variable:`CPACK_THREADS` variable.

  .. versionadded:: 3.21

    Official CMake binaries available on ``cmake.org`` now ship
    with a ``liblzma`` that supports parallel compression.
    Older versions did not.


code:
CPack Bundle Generator
----------------------

CPack Bundle generator (macOS) specific options

Variables specific to CPack Bundle generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Installers built on macOS using the Bundle generator use the
aforementioned DragNDrop (``CPACK_DMG_xxx``) variables, plus the following
Bundle-specific parameters (``CPACK_BUNDLE_xxx``).

.. variable:: CPACK_BUNDLE_NAME

 The name of the generated bundle. This appears in the macOS Finder as the
 bundle name. Required.

.. variable:: CPACK_BUNDLE_PLIST

 Path to an macOS Property List (``.plist``) file that will be used
 for the generated bundle. This
 assumes that the caller has generated or specified their own ``Info.plist``
 file. Required.

.. variable:: CPACK_BUNDLE_ICON

 Path to an macOS icon file that will be used as the icon for the generated
 bundle. This is the icon that appears in the macOS Finder for the bundle, and
 in the macOS dock when the bundle is opened. Required.

.. variable:: CPACK_BUNDLE_STARTUP_COMMAND

 Path to a startup script. This is a path to an executable or script that
 will be run whenever an end-user double-clicks the generated bundle in the
 macOS Finder. Optional.

.. variable:: CPACK_BUNDLE_APPLE_CERT_APP

 .. versionadded:: 3.2

 The name of your Apple supplied code signing certificate for the application.
 The name usually takes the form ``Developer ID Application: [Name]`` or
 ``3rd Party Mac Developer Application: [Name]``. If this variable is not set
 the application will not be signed.

.. variable:: CPACK_BUNDLE_APPLE_ENTITLEMENTS

 .. versionadded:: 3.2

 The name of the Property List (``.plist``) file that contains your Apple
 entitlements for sandboxing your application. This file is required
 for submission to the macOS App Store.

.. variable:: CPACK_BUNDLE_APPLE_CODESIGN_FILES

 .. versionadded:: 3.2

 A list of additional files that you wish to be signed. You do not need to
 list the main application folder, or the main executable. You should
 list any frameworks and plugins that are included in your app bundle.

.. variable:: CPACK_BUNDLE_APPLE_CODESIGN_PARAMETER

 .. versionadded:: 3.3

 Additional parameter that will passed to ``codesign``.
 Default value: ``--deep -f``

.. variable:: CPACK_COMMAND_CODESIGN

 .. versionadded:: 3.2

 Path to the ``codesign(1)`` command used to sign applications with an
 Apple cert. This variable can be used to override the automatically
 detected command (or specify its location if the auto-detection fails
 to find it).


code:
CPack Cygwin Generator
----------------------

Cygwin CPack generator (Cygwin).

Variables affecting the CPack Cygwin generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

Variables specific to CPack Cygwin generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The
following variable is specific to installers build on and/or for
Cygwin:

.. variable:: CPACK_CYGWIN_PATCH_NUMBER

 The Cygwin patch number.  FIXME: This documentation is incomplete.

.. variable:: CPACK_CYGWIN_PATCH_FILE

 The Cygwin patch file.  FIXME: This documentation is incomplete.

.. variable:: CPACK_CYGWIN_BUILD_SCRIPT

 The Cygwin build script.  FIXME: This documentation is incomplete.


code:
CPack DEB Generator
-------------------

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

Variables specific to CPack Debian (DEB) generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

The CPack DEB generator should work on any Linux host but it will produce
better deb package when Debian specific tools ``dpkg-xxx`` are usable on
the build system.

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

:variable:`!CPACK_DEBIAN_<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.

Here are some CPack DEB 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#deb-unix-only

List of CPack DEB generator specific variables:

.. variable:: CPACK_DEB_COMPONENT_INSTALL

 Enable component packaging for CPackDEB

 :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_DEBIAN_PACKAGE_NAME
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME

 Set Package control field (variable is automatically transformed to lower
 case).

 :Mandatory: Yes
 :Default:

   - :variable:`CPACK_PACKAGE_NAME` for non-component based
     installations
   - :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with ``-<COMPONENT>``
     for component-based installations.

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

 See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source

.. variable:: CPACK_DEBIAN_FILE_NAME
              CPACK_DEBIAN_<COMPONENT>_FILE_NAME

 .. versionadded:: 3.6

 Package file name.

 :Mandatory: Yes
 :Default: ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb``

 This may be set to:

 ``DEB-DEFAULT``
   Tell CPack to automatically generate the package file name in deb format::

     <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb

   This setting recommended as the preferred behavior, but for backward
   compatibility with the CPack DEB generator in CMake prior to version 3.6,
   this is not the default.   Without this, duplicate names may occur.
   Duplicate files get overwritten and it is up to the packager to set
   the variables in a manner that will prevent such errors.

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

   .. versionchanged:: 3.29

     The ``.deb`` suffix will be automatically added if the file name does
     not end in ``.deb`` or ``.ipk``.  Previously the suffix was required.

 ``<file-name>.ipk``
   .. versionadded:: 3.10

   Use the given file name.
   The ``.ipk`` suffix is used by the OPKG packaging system.

.. variable:: CPACK_DEBIAN_PACKAGE_EPOCH

 .. versionadded:: 3.10

 The Debian package epoch

 :Mandatory: No
 :Default: None

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

.. variable:: CPACK_DEBIAN_PACKAGE_VERSION

 The Debian package version

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

 This variable may contain only alphanumerics (A-Za-z0-9) and the characters
 . + - ~ (full stop, plus, hyphen, tilde) and should start with a digit. If
 :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` is not set then hyphens are not
 allowed.

 .. note::

   For backward compatibility with CMake 3.9 and lower a failed test of this
   variable's content is not a hard error when both
   :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` and
   :variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables are not set. An author
   warning is reported instead.

.. variable:: CPACK_DEBIAN_PACKAGE_RELEASE

 .. versionadded:: 3.6

 The Debian package release - Debian revision number.

 :Mandatory: No
 :Default: None

 This is the numbering of the DEB package itself, i.e. the version of the
 packaging and not the version of the content (see
 :variable:`CPACK_DEBIAN_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.

.. variable:: CPACK_DEBIAN_PACKAGE_ARCHITECTURE
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE

 The Debian package architecture

 :Mandatory: Yes
 :Default: Output of ``dpkg --print-architecture`` (or ``i386``
   if ``dpkg`` is not found)

 .. versionadded:: 3.6
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE` variables.

.. variable:: CPACK_DEBIAN_PACKAGE_DEPENDS
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS

 Sets the Debian dependencies of this package.

 :Mandatory: No
 :Default:

   - An empty string for non-component based installations
   - :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS` for component-based
     installations.

 .. versionadded:: 3.3
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` variables.

 .. note::

   If :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` or
   more specifically :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`
   is set for this component, the discovered dependencies will be appended
   to :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` instead of
   :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS`. If
   :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` is an empty string,
   only the automatically discovered dependencies will be set for this
   component.

 Example:

 .. code-block:: cmake

   set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)")

.. variable:: CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS

 .. versionadded:: 3.6

 Sets inter-component dependencies if listed with
 :variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_DEBIAN_PACKAGE_MAINTAINER

 The Debian package maintainer

 :Mandatory: Yes
 :Default: :variable:`!CPACK_PACKAGE_CONTACT`

.. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION
              CPACK_DEBIAN_<COMPONENT>_DESCRIPTION

 The Debian package description

 :Mandatory: Yes
 :Default:

   - :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` (component
     based installers only) if set, or :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set, or
   - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` (component
     based installers only) if set, or :variable:`CPACK_PACKAGE_DESCRIPTION` if set, or
   - content of the file specified in :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` if set

 If after that description is not set, :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` going to be
 used if set. Otherwise, :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` will be added as the first
 line of description as defined in `Debian Policy Manual`_.

 .. versionadded:: 3.3
  Per-component :variable:`!CPACK_COMPONENT_<compName>_DESCRIPTION` variables.

 .. versionadded:: 3.16
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` variables.

 .. versionadded:: 3.16
  The :variable:`!CPACK_PACKAGE_DESCRIPTION_FILE` variable.

.. _Debian Policy Manual: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description

.. variable:: CPACK_DEBIAN_PACKAGE_SECTION
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION

 Set Section control field e.g. admin, devel, doc, ...

 :Mandatory: Yes
 :Default: ``devel``

 .. versionadded:: 3.5
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION` variables.

 See https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections

.. variable:: CPACK_DEBIAN_ARCHIVE_TYPE

 .. versionadded:: 3.7

 .. deprecated:: 3.14

 The archive format used for creating the Debian package.

 :Mandatory: Yes
 :Default: ``gnutar``

 Possible value is: ``gnutar``

 .. note::

   This variable previously defaulted to the ``paxr`` value, but ``dpkg``
   has never supported that tar format. For backwards compatibility the
   ``paxr`` value will be mapped to ``gnutar`` and a deprecation message
   will be emitted.

.. variable:: CPACK_DEBIAN_COMPRESSION_TYPE

 .. versionadded:: 3.1

 The compression used for creating the Debian package.

 :Mandatory: Yes
 :Default: ``gzip``

 Possible values are:

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

  ``xz``
    XZ Utils compression

  ``bzip2``
    bzip2 Burrows–Wheeler algorithm

  ``gzip``
    GNU Gzip compression

  ``zstd``
    .. versionadded:: 3.22

    Zstandard compression

.. variable:: CPACK_DEBIAN_PACKAGE_PRIORITY
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY

 Set Priority control field e.g. required, important, standard, optional,
 extra

 :Mandatory: Yes
 :Default: ``optional``

 .. versionadded:: 3.5
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY` variables.

 See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities

.. variable:: CPACK_DEBIAN_PACKAGE_HOMEPAGE

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

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

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

 .. note::

   The content of this field is a simple URL without any surrounding
   characters such as <>.

.. variable:: CPACK_DEBIAN_PACKAGE_SHLIBDEPS
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS

 May be set to ON in order to use ``dpkg-shlibdeps`` to generate
 better package dependency list.

 :Mandatory: No
 :Default:

   - :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` if set or
   - ``OFF``

 .. note::

   You may need set :variable:`CMAKE_INSTALL_RPATH` to an appropriate value
   if you use this feature, because if you don't ``dpkg-shlibdeps``
   may fail to find your own shared libs.
   See https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling

 .. note::

   You can also set :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS`
   to an appropriate value if you use this feature, in order to please
   ``dpkg-shlibdeps``. However, you should only do this for private
   shared libraries that could not get resolved otherwise.

 .. versionadded:: 3.3
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS` variables.

 .. versionadded:: 3.6
  Correct handling of ``$ORIGIN`` in :variable:`CMAKE_INSTALL_RPATH`.

.. variable:: CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS

 .. versionadded:: 3.20

 May be set to a list of directories that will be given to ``dpkg-shlibdeps``
 via its ``-l`` option. These will be searched by ``dpkg-shlibdeps`` in order
 to find private shared library dependencies.

 :Mandatory: No
 :Default: None

 .. note::

   You should prefer to set :variable:`CMAKE_INSTALL_RPATH` to an appropriate
   value if you use ``dpkg-shlibdeps``. The current option is really only
   needed for private shared library dependencies.

.. variable:: CPACK_DEBIAN_PACKAGE_DEBUG

 May be set when invoking cpack in order to trace debug information
 during the CPack DEB generator run.

 :Mandatory: No
 :Default: None

.. variable:: CPACK_DEBIAN_PACKAGE_PREDEPENDS
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS

 Sets the `Pre-Depends` field of the Debian package.
 Like :variable:`Depends <CPACK_DEBIAN_PACKAGE_DEPENDS>`, except that it
 also forces ``dpkg`` to complete installation of the packages named
 before even starting the installation of the package which declares the
 pre-dependency.

 :Mandatory: No
 :Default:

   - An empty string for non-component based installations
   - :variable:`CPACK_DEBIAN_PACKAGE_PREDEPENDS` for component-based
     installations.

 .. versionadded:: 3.4
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS` variables.

 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps

.. variable:: CPACK_DEBIAN_PACKAGE_ENHANCES
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES

 Sets the ``Enhances`` field of the Debian package.
 Similar to :variable:`Suggests <CPACK_DEBIAN_PACKAGE_SUGGESTS>` but works
 in the opposite direction: declares that a package can enhance the
 functionality of another package.

 :Mandatory: No
 :Default:

   - An empty string for non-component based installations
   - :variable:`CPACK_DEBIAN_PACKAGE_ENHANCES` for component-based
     installations.

 .. versionadded:: 3.4
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES` variables.

 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps

.. variable:: CPACK_DEBIAN_PACKAGE_BREAKS
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS

 Sets the ``Breaks`` field of the Debian package.
 When a binary package (P) declares that it breaks other packages (B),
 ``dpkg`` will not allow the package (P) which declares ``Breaks`` be
 **unpacked** unless the packages that will be broken (B) are deconfigured
 first.
 As long as the package (P) is configured, the previously deconfigured
 packages (B) cannot be reconfigured again.

 :Mandatory: No
 :Default:

   - An empty string for non-component based installations
   - :variable:`CPACK_DEBIAN_PACKAGE_BREAKS` for component-based
     installations.

 .. versionadded:: 3.4
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS` variables.

 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks

.. variable:: CPACK_DEBIAN_PACKAGE_CONFLICTS
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS

 Sets the `Conflicts` field of the Debian package.
 When one binary package declares a conflict with another using a `Conflicts`
 field, ``dpkg`` will not allow them to be unpacked on the system at
 the same time.

 :Mandatory: No
 :Default:

   - An empty string for non-component based installations
   - :variable:`CPACK_DEBIAN_PACKAGE_CONFLICTS` for component-based
     installations.

 .. versionadded:: 3.4
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS` variables.

 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts

 .. note::

   This is a stronger restriction than
   :variable:`Breaks <CPACK_DEBIAN_PACKAGE_BREAKS>`, which prevents the
   broken package from being configured while the breaking package is in
   the "Unpacked" state but allows both packages to be unpacked at the same
   time.

.. variable:: CPACK_DEBIAN_PACKAGE_PROVIDES
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES

 Sets the `Provides` field of the Debian package.
 A virtual package is one which appears in the `Provides` control field of
 another package.

 :Mandatory: No
 :Default:

   - An empty string for non-component based installations
   - :variable:`CPACK_DEBIAN_PACKAGE_PROVIDES` for component-based
     installations.

 .. versionadded:: 3.4
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES` variables.

 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual

.. variable:: CPACK_DEBIAN_PACKAGE_REPLACES
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES

 Sets the `Replaces` field of the Debian package.
 Packages can declare in their control file that they should overwrite
 files in certain other packages, or completely replace other packages.

 :Mandatory: No
 :Default:

   - An empty string for non-component based installations
   - :variable:`CPACK_DEBIAN_PACKAGE_REPLACES` for component-based
     installations.

 .. versionadded:: 3.4
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES` variables.

 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps

.. variable:: CPACK_DEBIAN_PACKAGE_RECOMMENDS
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS

 Sets the ``Recommends`` field of the Debian package.
 Allows packages to declare a strong, but not absolute, dependency on other
 packages.

 :Mandatory: No
 :Default:

   - An empty string for non-component based installations
   - :variable:`CPACK_DEBIAN_PACKAGE_RECOMMENDS` for component-based
     installations.

 .. versionadded:: 3.4
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS` variables.

 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps

.. variable:: CPACK_DEBIAN_PACKAGE_SUGGESTS
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS

 Sets the `Suggests` field of the Debian package.
 Allows packages to declare a suggested package install grouping.

 :Mandatory: No
 :Default:

   - An empty string for non-component based installations
   - :variable:`CPACK_DEBIAN_PACKAGE_SUGGESTS` for component-based
     installations.

 .. versionadded:: 3.4
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS` variables.

 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps

.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS

 .. versionadded:: 3.6

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

 Allows to generate shlibs control file automatically. Compatibility is defined by
 :variable:`CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY` variable value.

 .. note::

   Libraries are only considered if they have both library name and version
   set. This can be done by setting SOVERSION property with
   :command:`set_target_properties` command.

.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY

 .. versionadded:: 3.6

 Compatibility policy for auto-generated shlibs control file.

 :Mandatory: No
 :Default: ``=``

 Defines compatibility policy for auto-generated shlibs control file.
 Possible values: ``=``, ``>=``

 See https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps

.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA

 This variable allow advanced user to add custom script to the
 control.tar.gz.
 Typical usage is for conffiles, postinst, postrm, prerm.

 :Mandatory: No
 :Default: None

 Usage:

 .. code-block:: cmake

  set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
      "${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm")

 .. versionadded:: 3.4
  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA` variables.

.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION

 .. versionadded:: 3.4

 This variable indicates if the Debian policy on control files should be
 strictly followed.

 :Mandatory: No
 :Default: ``FALSE``

 Usage:

 .. code-block:: cmake

  set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE)

 This overrides the permissions on the original files, following the rules
 set by Debian policy
 https://www.debian.org/doc/debian-policy/ch-files.html#s-permissions-owners

 .. note::

  The original permissions of the files will be used in the final
  package unless this variable is set to ``TRUE``.
  In particular, the scripts should have the proper executable
  flag prior to the generation of the package.

.. variable:: CPACK_DEBIAN_PACKAGE_SOURCE
              CPACK_DEBIAN_<COMPONENT>_PACKAGE_SOURCE

 .. versionadded:: 3.5

 Sets the ``Source`` field of the binary Debian package.
 When the binary package name is not the same as the source package name
 (in particular when several components/binaries are generated from one
 source) the source from which the binary has been generated should be
 indicated with the field ``Source``.

 :Mandatory: No
 :Default:

   - An empty string for non-component based installations
   - :variable:`CPACK_DEBIAN_PACKAGE_SOURCE` for component-based
     installations.

 See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source

 .. note::

   This value is not interpreted. It is possible to pass an optional
   revision number of the referenced source package as well.

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

.. versionadded:: 3.13

Dbgsym packages contain debug symbols for debugging packaged binaries.

Dbgsym packaging has its own set of variables:

.. variable:: CPACK_DEBIAN_DEBUGINFO_PACKAGE
              CPACK_DEBIAN_<component>_DEBUGINFO_PACKAGE

 Enable generation of dbgsym .ddeb package(s).

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

.. note::

 Setting this also strips the ELF files in the generated non-dbgsym package,
 which results in debuginfo only being available in the dbgsym package.

.. 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 DEB generator, so will not contain debug symbols and
 a dbgsym package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`.

Building Debian packages on Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.10

To communicate UNIX file permissions from the install stage
to the CPack DEB generator the ``cmake_mode_t`` NTFS
alternate data stream (ADT) is used.

When a filesystem without ADT support is used only owner read/write
permissions can be preserved.

Reproducible packages
^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.13

The environment variable :envvar:`!SOURCE_DATE_EPOCH` may be set to a UNIX
timestamp, defined as the number of seconds, excluding leap seconds,
since 01 Jan 1970 00:00:00 UTC.  If set, the CPack DEB generator will
use its value for timestamps in the package.


code:
CPack DragNDrop Generator
-------------------------

The DragNDrop CPack generator (macOS) creates a DMG image.

Variables specific to CPack DragNDrop generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following variables are specific to the DragNDrop installers built
on macOS:

.. variable:: CPACK_DMG_VOLUME_NAME

 The volume name of the generated disk image.

 :Default: :variable:`CPACK_PACKAGE_FILE_NAME`

.. variable:: CPACK_DMG_FORMAT

 The disk image format.

 :Default: ``UDZO``

 Common values are ``UDRO`` (UDIF read-only), ``UDZO`` (UDIF
 zlib-compressed) or ``UDBZ`` (UDIF bzip2-compressed). Refer to ``hdiutil(1)`` for
 more information on other available formats.

.. variable:: CPACK_DMG_DS_STORE

 Path to a custom ``.DS_Store`` file. This ``.DS_Store`` file can be used to
 specify the Finder window position/geometry and layout (such as hidden
 toolbars, placement of the icons etc.). This file has to be generated by
 the Finder (either manually or through AppleScript) using a normal folder
 from which the ``.DS_Store`` file can then be extracted.

.. variable:: CPACK_DMG_DS_STORE_SETUP_SCRIPT

 .. versionadded:: 3.5

 Path to a custom AppleScript file.  This AppleScript is used to generate
 a ``.DS_Store`` file which specifies the Finder window position/geometry and
 layout (such as hidden toolbars, placement of the icons etc.).
 By specifying a custom AppleScript there is no need to use
 ``CPACK_DMG_DS_STORE``, as the ``.DS_Store`` that is generated by the AppleScript
 will be packaged.

.. variable:: CPACK_DMG_BACKGROUND_IMAGE

 :Default:

 Path to an image file to be used as the background.  This file will be
 copied to ``.background``/``background.<ext>``, where ``<ext>`` is the original image file
 extension.  The background image is installed into the image before
 ``CPACK_DMG_DS_STORE_SETUP_SCRIPT`` is executed or ``CPACK_DMG_DS_STORE`` is
 installed.  By default no background image is set.

.. variable:: CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK

 .. versionadded:: 3.6

 Default behavior is to include a symlink to ``/Applications`` in the DMG.
 Set this option to ``ON`` to avoid adding the symlink.

.. variable:: CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE

 .. versionadded:: 3.23

 :Default: ``OFF``

 Control whether :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a
 non-default value, is used as the license agreement provided when
 mounting the DMG.  If :variable:`!CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` is
 not set, :manual:`cpack(1)` defaults to off.

 In a CMake project that uses the :module:`CPack` module to generate
 ``CPackConfig.cmake``, :variable:`!CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`
 must be explicitly enabled by the project to activate the SLA.
 See policy :policy:`CMP0133`.

 .. note::

  This option was added in response to macOS 12.0's deprecation of
  the ``hdiutil udifrez`` command to make its use optional.
  CPack 3.22 and below always use :variable:`CPACK_RESOURCE_FILE_LICENSE`,
  if set to a non-default value, as the DMG license.

.. variable:: CPACK_DMG_SLA_DIR

  .. versionadded:: 3.5

  Directory where license and menu files for different languages are stored.
  Setting this causes CPack to look for a ``<language>.menu.txt`` and
  ``<language>.license.txt`` or ``<language>.license.rtf`` file for every
  language defined in :variable:`CPACK_DMG_SLA_LANGUAGES`.  If both this variable and
  :variable:`CPACK_RESOURCE_FILE_LICENSE` are set, CPack will only look for the menu
  files and use the same license file for all languages.  If both
  ``<language>.license.txt`` and ``<language>.license.rtf`` exist, the ``.txt``
  file will be used.

  .. versionadded:: 3.17
    RTF support.

.. variable:: CPACK_DMG_SLA_LANGUAGES

  .. versionadded:: 3.5

  Languages for which a license agreement is provided when mounting the
  generated DMG. A menu file consists of 9 lines of text. The first line is
  is the name of the language itself, uppercase, in English (e.g. German).
  The other lines are translations of the following strings:

  - Agree
  - Disagree
  - Print
  - Save...
  - You agree to the terms of the License Agreement when you click the
    "Agree" button.
  - Software License Agreement
  - This text cannot be saved. The disk may be full or locked, or the file
    may be locked.
  - Unable to print. Make sure you have selected a printer.

  For every language in this list, CPack will try to find files
  ``<language>.menu.txt`` and ``<language>.license.txt`` in the directory
  specified by the :variable:`CPACK_DMG_SLA_DIR` variable.

.. variable:: CPACK_DMG_<component>_FILE_NAME

 .. versionadded:: 3.17

 File name when packaging ``<component>`` as its own DMG
 (:variable:`CPACK_COMPONENTS_GROUPING` set to ``IGNORE``).

 :Default: ``CPACK_PACKAGE_FILE_NAME-<component>``

.. variable:: CPACK_DMG_FILESYSTEM

 .. versionadded:: 3.21

 :Default: ``HFS+``

 The filesystem format. Common values are ``APFS`` and ``HFS+``.
 See ``man hdiutil`` for a full list of supported formats.

.. variable:: CPACK_COMMAND_HDIUTIL

 Path to the ``hdiutil(1)`` command used to operate on disk image files 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_COMMAND_SETFILE

 Path to the ``SetFile(1)`` command used to set extended attributes on files and
 directories 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_COMMAND_REZ

 Path to the ``Rez(1)`` command used to compile resources 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).


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

.. versionadded:: 3.13

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

.. variable:: CPACK_EXTERNAL_REQUESTED_VERSIONS

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

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

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

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

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

.. variable:: CPACK_EXTERNAL_ENABLE_STAGING

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

.. variable:: CPACK_EXTERNAL_PACKAGE_SCRIPT

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

.. variable:: CPACK_EXTERNAL_BUILT_PACKAGES

  .. versionadded:: 3.19

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


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

.. versionadded:: 3.10

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

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

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

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

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

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

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

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

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

.. variable:: CPACK_FREEBSD_PACKAGE_NAME

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

  :Mandatory: Yes
  :Default:

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

.. variable:: CPACK_FREEBSD_PACKAGE_COMMENT

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

  :Mandatory: Yes
  :Default:

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

.. variable:: CPACK_FREEBSD_PACKAGE_DESCRIPTION

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

  :Mandatory: Yes
  :Default:

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

.. variable:: CPACK_FREEBSD_PACKAGE_WWW

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

  :Mandatory: Yes
  :Default:

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

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

.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE

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

  :Mandatory: Yes
  :Default:

    - :variable:`CPACK_RPM_PACKAGE_LICENSE`

.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE_LOGIC

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

  :Mandatory: No
  :Default: single

.. variable:: CPACK_FREEBSD_PACKAGE_MAINTAINER

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

  :Mandatory: Yes
  :Default: none

.. variable:: CPACK_FREEBSD_PACKAGE_ORIGIN

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

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

.. variable:: CPACK_FREEBSD_PACKAGE_CATEGORIES

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

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

.. variable:: CPACK_FREEBSD_PACKAGE_DEPS

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

  :Mandatory: No
  :Default: empty


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

.. versionadded:: 3.1

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

.. only:: html

  .. contents::

Overview
^^^^^^^^

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

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

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

Variables
^^^^^^^^^

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

Debug
"""""

.. variable:: CPACK_IFW_VERBOSE

 .. versionadded:: 3.3

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

Package
"""""""

.. variable:: CPACK_IFW_PACKAGE_TITLE

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

.. variable:: CPACK_IFW_PACKAGE_PUBLISHER

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

.. variable:: CPACK_IFW_PRODUCT_URL

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

.. variable:: CPACK_IFW_PACKAGE_ICON

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

.. variable:: CPACK_IFW_PACKAGE_WINDOW_ICON

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

.. variable:: CPACK_IFW_PACKAGE_LOGO

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

.. variable:: CPACK_IFW_PACKAGE_WATERMARK

 .. versionadded:: 3.8

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

.. variable:: CPACK_IFW_PACKAGE_BANNER

 .. versionadded:: 3.8

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

.. variable:: CPACK_IFW_PACKAGE_BACKGROUND

 .. versionadded:: 3.8

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

.. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE

 .. versionadded:: 3.8

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

.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH

 .. versionadded:: 3.8

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

.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT

 .. versionadded:: 3.8

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

.. variable:: CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST

 .. versionadded:: 3.20

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

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

.. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR

 .. versionadded:: 3.8

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

.. variable:: CPACK_IFW_PACKAGE_STYLE_SHEET

 .. versionadded:: 3.15

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

.. variable:: CPACK_IFW_TARGET_DIRECTORY

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

.. variable:: CPACK_IFW_ADMIN_TARGET_DIRECTORY

 Default target directory for installation with administrator rights.

 You can use predefined variables.

.. variable:: CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR

 .. versionadded:: 3.11

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

 Is ``ON`` by default

.. variable:: CPACK_IFW_PACKAGE_GROUP

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

.. variable:: CPACK_IFW_PACKAGE_NAME

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

.. variable:: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY

 .. versionadded:: 3.3

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

.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME

 .. versionadded:: 3.3

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

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

.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE

 .. versionadded:: 3.3

 Filename for the configuration of the generated maintenance tool.

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

.. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS

 .. versionadded:: 3.3

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

.. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH

 .. versionadded:: 3.3

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

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

.. variable:: CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE

 .. versionadded:: 3.23

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

.. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT

 .. versionadded:: 3.3

 Filename for a custom installer control script.

.. variable:: CPACK_IFW_PACKAGE_RESOURCES

 .. versionadded:: 3.7

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

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

.. variable:: CPACK_IFW_PACKAGE_FILE_EXTENSION

 .. versionadded:: 3.10

 The target binary extension.

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

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

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

.. variable:: CPACK_IFW_REPOSITORIES_ALL

 The list of remote repositories.

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

.. variable:: CPACK_IFW_DOWNLOAD_ALL

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

.. variable:: CPACK_IFW_PACKAGE_PRODUCT_IMAGES

 .. versionadded:: 3.23

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

 This feature is available for QtIFW 4.0.0 and later.

.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM

 .. versionadded:: 3.23

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

 This feature is available for QtIFW 4.0.0 and later.

.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS

 .. versionadded:: 3.23

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

 This feature is available for QtIFW 4.0.0 and later.

.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION

 .. versionadded:: 3.23

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

 This feature is available for QtIFW 4.0.0 and later.

.. variable:: CPACK_IFW_PACKAGE_SIGNING_IDENTITY

 .. versionadded:: 3.23

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

.. variable:: CPACK_IFW_ARCHIVE_FORMAT

 .. versionadded:: 3.23

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

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

 .. note::

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

 This feature is available for QtIFW 4.2.0 and later.

.. variable:: CPACK_IFW_ARCHIVE_COMPRESSION

 .. versionadded:: 3.23

 Archive compression level. The allowable values are:

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

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

 .. note::

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

 This feature is available for QtIFW 4.2.0 and later.

Components
""""""""""

.. variable:: CPACK_IFW_RESOLVE_DUPLICATE_NAMES

 Resolve duplicate names when installing components with groups.

.. variable:: CPACK_IFW_PACKAGES_DIRECTORIES

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

.. variable:: CPACK_IFW_REPOSITORIES_DIRECTORIES

 .. versionadded:: 3.10

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

 This feature is available for QtIFW 3.1 and later.

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

.. variable:: CPACK_IFW_FRAMEWORK_VERSION

 .. versionadded:: 3.3

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

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

.. variable:: CPACK_IFW_ARCHIVEGEN_EXECUTABLE

 .. versionadded:: 3.19

 The path to ``archivegen``.

.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE

 The path to ``binarycreator``.

.. variable:: CPACK_IFW_REPOGEN_EXECUTABLE

 The path to ``repogen``.

.. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE

 The path to ``installerbase``.

.. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE

 The path to ``devtool``.

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

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

.. variable:: CPACK_IFW_ROOT

  .. versionadded:: 3.9

  CMake variable

.. envvar:: CPACK_IFW_ROOT

  .. versionadded:: 3.9

  Environment variable

.. variable:: QTIFWDIR

  CMake variable

.. envvar:: QTIFWDIR

  Environment variable

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

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

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

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

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

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

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

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

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

.. versionadded:: 3.9

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

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

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

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

For example:

.. code-block:: cmake

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

See Also
^^^^^^^^

Qt Installer Framework Manual:

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

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

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

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

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