code:
target_link_libraries
---------------------

.. only:: html

   .. contents::

Specify libraries or flags to use when linking a given target and/or
its dependents.  :ref:`Usage requirements <Target Usage Requirements>`
from linked library targets will be propagated.  Usage requirements
of a target's dependencies affect compilation of its own sources.

Overview
^^^^^^^^

This command has several signatures as detailed in subsections below.
All of them have the general form

.. code-block:: cmake

  target_link_libraries(<target> ... <item>... ...)

The named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
:ref:`ALIAS target <Alias Targets>`.  If policy :policy:`CMP0079` is not
set to ``NEW`` then the target must have been created in the current
directory.  Repeated calls for the same ``<target>`` append items in
the order called.

.. versionadded:: 3.13
  The ``<target>`` doesn't have to be defined in the same directory as the
  ``target_link_libraries`` call.

Each ``<item>`` may be:

* **A library target name**: The generated link line will have the
  full path to the linkable library file associated with the target.
  The buildsystem will have a dependency to re-link ``<target>`` if
  the library file changes.

  The named target must be created by :command:`add_library` within
  the project or as an :ref:`IMPORTED library <Imported Targets>`.
  If it is created within the project an ordering dependency will
  automatically be added in the build system to make sure the named
  library target is up-to-date before the ``<target>`` links.

  If an imported library has the :prop_tgt:`IMPORTED_NO_SONAME`
  target property set, CMake may ask the linker to search for
  the library instead of using the full path
  (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``).

  The full path to the target's artifact will be quoted/escaped for
  the shell automatically.

* **A full path to a library file**: The generated link line will
  normally preserve the full path to the file. The buildsystem will
  have a dependency to re-link ``<target>`` if the library file changes.

  There are some cases where CMake may ask the linker to search for
  the library (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such
  as when a shared library is detected to have no ``SONAME`` field.
  See policy :policy:`CMP0060` for discussion of another case.

  If the library file is in a macOS framework, the ``Headers`` directory
  of the framework will also be processed as a
  :ref:`usage requirement <Target Usage Requirements>`.  This has the same
  effect as passing the framework directory as an include directory.

  .. versionadded:: 3.28

    The library file may point to a ``.xcframework`` folder on Apple platforms.
    If it does, the target will get the selected library's ``Headers``
    directory as a usage requirement.

  .. versionadded:: 3.8
    On :ref:`Visual Studio Generators` for VS 2010 and above, library files
    ending in ``.targets`` will be treated as MSBuild targets files and
    imported into generated project files.  This is not supported by other
    generators.

  The full path to the library file will be quoted/escaped for
  the shell automatically.

* **A plain library name**: The generated link line will ask the linker
  to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``).

  The library name/flag is treated as a command-line string fragment and
  will be used with no extra quoting or escaping.

* **A link flag**: Item names starting with ``-``, but not ``-l`` or
  ``-framework``, are treated as linker flags.  Note that such flags will
  be treated like any other library link item for purposes of transitive
  dependencies, so they are generally safe to specify only as private link
  items that will not propagate to dependents.

  Link flags specified here are inserted into the link command in the same
  place as the link libraries. This might not be correct, depending on
  the linker. Use the :prop_tgt:`LINK_OPTIONS` target property or
  :command:`target_link_options` command to add link
  flags explicitly. The flags will then be placed at the toolchain-defined
  flag position in the link command.

  .. versionadded:: 3.13
    :prop_tgt:`LINK_OPTIONS` target property and :command:`target_link_options`
    command.  For earlier versions of CMake, use :prop_tgt:`LINK_FLAGS`
    property instead.

  The link flag is treated as a command-line string fragment and
  will be used with no extra quoting or escaping.

* **A generator expression**: A ``$<...>`` :manual:`generator expression
  <cmake-generator-expressions(7)>` may evaluate to any of the above
  items or to a :ref:`semicolon-separated list <CMake Language Lists>` of them.
  If the ``...`` contains any ``;`` characters, e.g. after evaluation
  of a ``${list}`` variable, be sure to use an explicitly quoted
  argument ``"$<...>"`` so that this command receives it as a
  single ``<item>``.

  Additionally, a generator expression may be used as a fragment of
  any of the above items, e.g. ``foo$<1:_d>``.

  Note that generator expressions will not be used in OLD handling of
  policy :policy:`CMP0003` or policy :policy:`CMP0004`.

* A ``debug``, ``optimized``, or ``general`` keyword immediately followed
  by another ``<item>``.  The item following such a keyword will be used
  only for the corresponding build configuration.  The ``debug`` keyword
  corresponds to the ``Debug`` configuration (or to configurations named
  in the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set).
  The ``optimized`` keyword corresponds to all other configurations.  The
  ``general`` keyword corresponds to all configurations, and is purely
  optional.  Higher granularity may be achieved for per-configuration
  rules by creating and linking to
  :ref:`IMPORTED library targets <Imported Targets>`.
  These keywords are interpreted immediately by this command and therefore
  have no special meaning when produced by a generator expression.

Items containing ``::``, such as ``Foo::Bar``, are assumed to be
:ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library
target names and will cause an error if no such target exists.
See policy :policy:`CMP0028`.

See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.

Libraries for a Target and/or its Dependents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  target_link_libraries(<target>
                        <PRIVATE|PUBLIC|INTERFACE> <item>...
                       [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)

The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE``
:ref:`scope <Target Usage Requirements>` keywords can be used to
specify both the link dependencies and the link interface in one command.

Libraries and targets following ``PUBLIC`` are linked to, and are made
part of the link interface.  Libraries and targets following ``PRIVATE``
are linked to, but are not made part of the link interface.  Libraries
following ``INTERFACE`` are appended to the link interface and are not
used for linking ``<target>``.

Libraries for both a Target and its Dependents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  target_link_libraries(<target> <item>...)

Library dependencies are transitive by default with this signature.
When this target is linked into another target then the libraries
linked to this target will appear on the link line for the other
target too.  This transitive "link interface" is stored in the
:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property and may be overridden
by setting the property directly.  When :policy:`CMP0022` is not set to
``NEW``, transitive linking is built in but may be overridden by the
:prop_tgt:`LINK_INTERFACE_LIBRARIES` property.  Calls to other signatures
of this command may set the property making any libraries linked
exclusively by this signature private.

Libraries for a Target and/or its Dependents (Legacy)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  target_link_libraries(<target>
                        <LINK_PRIVATE|LINK_PUBLIC> <lib>...
                       [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)

The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
the link dependencies and the link interface in one command.

This signature is for compatibility only.  Prefer the ``PUBLIC`` or
``PRIVATE`` keywords instead.

Libraries and targets following ``LINK_PUBLIC`` are linked to, and are
made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`.  If policy
:policy:`CMP0022` is not ``NEW``, they are also made part of the
:prop_tgt:`LINK_INTERFACE_LIBRARIES`.  Libraries and targets following
``LINK_PRIVATE`` are linked to, but are not made part of the
:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`).

Libraries for Dependents Only (Legacy)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)

The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the
:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them
for linking.  If policy :policy:`CMP0022` is not ``NEW``, then this mode
also appends libraries to the :prop_tgt:`LINK_INTERFACE_LIBRARIES` and its
per-configuration equivalent.

This signature is for compatibility only.  Prefer the ``INTERFACE`` mode
instead.

Libraries specified as ``debug`` are wrapped in a generator expression to
correspond to debug builds.  If policy :policy:`CMP0022` is
not ``NEW``, the libraries are also appended to the
:prop_tgt:`LINK_INTERFACE_LIBRARIES_DEBUG <LINK_INTERFACE_LIBRARIES_<CONFIG>>`
property (or to the properties corresponding to configurations listed in
the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set).
Libraries specified as ``optimized`` are appended to the
:prop_tgt:`INTERFACE_LINK_LIBRARIES` property.  If policy :policy:`CMP0022`
is not ``NEW``, they are also appended to the
:prop_tgt:`LINK_INTERFACE_LIBRARIES` property.  Libraries specified as
``general`` (or without any keyword) are treated as if specified for both
``debug`` and ``optimized``.

Linking Object Libraries
^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.12

:ref:`Object Libraries` may be used as the ``<target>`` (first) argument
of ``target_link_libraries`` to specify dependencies of their sources
on other libraries.  For example, the code

.. code-block:: cmake

  add_library(A SHARED a.c)
  target_compile_definitions(A PUBLIC A)

  add_library(obj OBJECT obj.c)
  target_compile_definitions(obj PUBLIC OBJ)
  target_link_libraries(obj PUBLIC A)

compiles ``obj.c`` with ``-DA -DOBJ`` and establishes usage requirements
for ``obj`` that propagate to its dependents.

Normal libraries and executables may link to :ref:`Object Libraries`
to get their objects and usage requirements.  Continuing the above
example, the code

.. code-block:: cmake

  add_library(B SHARED b.c)
  target_link_libraries(B PUBLIC obj)

compiles ``b.c`` with ``-DA -DOBJ``, creates shared library ``B``
with object files from ``b.c`` and ``obj.c``, and links ``B`` to ``A``.
Furthermore, the code

.. code-block:: cmake

  add_executable(main main.c)
  target_link_libraries(main B)

compiles ``main.c`` with ``-DA -DOBJ`` and links executable ``main``
to ``B`` and ``A``.  The object library's usage requirements are
propagated transitively through ``B``, but its object files are not.

:ref:`Object Libraries` may "link" to other object libraries to get
usage requirements, but since they do not have a link step nothing
is done with their object files.  Continuing from the above example,
the code:

.. code-block:: cmake

  add_library(obj2 OBJECT obj2.c)
  target_link_libraries(obj2 PUBLIC obj)

  add_executable(main2 main2.c)
  target_link_libraries(main2 obj2)

compiles ``obj2.c`` with ``-DA -DOBJ``, creates executable ``main2``
with object files from ``main2.c`` and ``obj2.c``, and links ``main2``
to ``A``.

In other words, when :ref:`Object Libraries` appear in a target's
:prop_tgt:`INTERFACE_LINK_LIBRARIES` property they will be
treated as :ref:`Interface Libraries`, but when they appear in
a target's :prop_tgt:`LINK_LIBRARIES` property their object files
will be included in the link too.

.. _`Linking Object Libraries via $<TARGET_OBJECTS>`:

Linking Object Libraries via ``$<TARGET_OBJECTS>``
""""""""""""""""""""""""""""""""""""""""""""""""""

.. versionadded:: 3.21

The object files associated with an object library may be referenced
by the :genex:`$<TARGET_OBJECTS>` generator expression.  Such object
files are placed on the link line *before* all libraries, regardless
of their relative order.  Additionally, an ordering dependency will be
added to the build system to make sure the object library is up-to-date
before the dependent target links.  For example, the code

.. code-block:: cmake

  add_library(obj3 OBJECT obj3.c)
  target_compile_definitions(obj3 PUBLIC OBJ3)

  add_executable(main3 main3.c)
  target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3)

links executable ``main3`` with object files from ``main3.c``
and ``obj3.c`` followed by the ``a3`` and ``b3`` libraries.
``main3.c`` is *not* compiled with usage requirements from ``obj3``,
such as ``-DOBJ3``.

This approach can be used to achieve transitive inclusion of object
files in link lines as usage requirements.  Continuing the above
example, the code

.. code-block:: cmake

  add_library(iface_obj3 INTERFACE)
  target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>)

creates an interface library ``iface_obj3`` that forwards the ``obj3``
usage requirements and adds the ``obj3`` object files to dependents'
link lines.  The code

.. code-block:: cmake

  add_executable(use_obj3 use_obj3.c)
  target_link_libraries(use_obj3 PRIVATE iface_obj3)

compiles ``use_obj3.c`` with ``-DOBJ3`` and links executable ``use_obj3``
with object files from ``use_obj3.c`` and ``obj3.c``.

This also works transitively through a static library.  Since a static
library does not link, it does not consume the object files from
object libraries referenced this way.  Instead, the object files
become transitive link dependencies of the static library.
Continuing the above example, the code

.. code-block:: cmake

  add_library(static3 STATIC static3.c)
  target_link_libraries(static3 PRIVATE iface_obj3)

  add_executable(use_static3 use_static3.c)
  target_link_libraries(use_static3 PRIVATE static3)

compiles ``static3.c`` with ``-DOBJ3`` and creates ``libstatic3.a``
using only its own object file.  ``use_static3.c`` is compiled *without*
``-DOBJ3`` because the usage requirement is not transitive through
the private dependency of ``static3``.  However, the link dependencies
of ``static3`` are propagated, including the ``iface_obj3`` reference
to ``$<TARGET_OBJECTS:obj3>``.  The ``use_static3`` executable is
created with object files from ``use_static3.c`` and ``obj3.c``, and
linked to library ``libstatic3.a``.

When using this approach, it is the project's responsibility to avoid
linking multiple dependent binaries to ``iface_obj3``, because they will
all get the ``obj3`` object files on their link lines.

.. note::

  Referencing :genex:`$<TARGET_OBJECTS>` in ``target_link_libraries``
  calls worked in versions of CMake prior to 3.21 for some cases,
  but was not fully supported:

  * It did not place the object files before libraries on link lines.
  * It did not add an ordering dependency on the object library.
  * It did not work in Xcode with multiple architectures.

Cyclic Dependencies of Static Libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The library dependency graph is normally acyclic (a DAG), but in the case
of mutually-dependent ``STATIC`` libraries CMake allows the graph to
contain cycles (strongly connected components).  When another target links
to one of the libraries, CMake repeats the entire connected component.
For example, the code

.. code-block:: cmake

  add_library(A STATIC a.c)
  add_library(B STATIC b.c)
  target_link_libraries(A B)
  target_link_libraries(B A)
  add_executable(main main.c)
  target_link_libraries(main A)

links ``main`` to ``A B A B``.  While one repetition is usually
sufficient, pathological object file and symbol arrangements can require
more.  One may handle such cases by using the
:prop_tgt:`LINK_INTERFACE_MULTIPLICITY` target property or by manually
repeating the component in the last ``target_link_libraries`` call.
However, if two archives are really so interdependent they should probably
be combined into a single archive, perhaps by using :ref:`Object Libraries`.

Creating Relocatable Packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt

See Also
^^^^^^^^

* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`


code:
target_link_options
-------------------

.. versionadded:: 3.13

Add options to the link step for an executable, shared library or module
library target.

.. code-block:: cmake

  target_link_options(<target> [BEFORE]
    <INTERFACE|PUBLIC|PRIVATE> [items1...]
    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

The named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
:ref:`ALIAS target <Alias Targets>`.

This command can be used to add any link options, but alternative commands
exist to add libraries (:command:`target_link_libraries` or
:command:`link_libraries`).  See documentation of the
:prop_dir:`directory <LINK_OPTIONS>` and
:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties.

.. note::

  This command cannot be used to add options for static library targets,
  since they do not use a linker.  To add archiver or MSVC librarian flags,
  see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.

If ``BEFORE`` is specified, the content will be prepended to the property
instead of being appended.

The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`LINK_OPTIONS`
property of ``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``.
The following arguments specify link options.  Repeated calls for the same
``<target>`` append items in the order called.

.. note::
  :ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.

.. |command_name| replace:: ``target_link_options``
.. include:: GENEX_NOTE.txt

.. include:: DEVICE_LINK_OPTIONS.txt

.. include:: OPTIONS_SHELL.txt

.. include:: LINK_OPTIONS_LINKER.txt

See Also
^^^^^^^^

* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_precompile_headers`
* :command:`target_sources`

* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
  add language-wide flags passed to all invocations of the compiler.
  This includes invocations that drive compiling and those that drive linking.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
target_precompile_headers
-------------------------

.. versionadded:: 3.16

Add a list of header files to precompile.

Precompiling header files can speed up compilation by creating a partially
processed version of some header files, and then using that version during
compilations rather than repeatedly parsing the original headers.

Main Form
^^^^^^^^^

.. code-block:: cmake

  target_precompile_headers(<target>
    <INTERFACE|PUBLIC|PRIVATE> [header1...]
    [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])

The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<target>``.
The named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
:ref:`ALIAS target <Alias Targets>`.

The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`PRECOMPILE_HEADERS`
property of ``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>``
(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items).
Repeated calls for the same ``<target>`` will append items in the order called.

Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets
that will be :command:`exported <install(EXPORT)>`, or they should at least use
the :genex:`$<BUILD_INTERFACE:...>` generator expression to prevent precompile
headers from appearing in an installed exported target.  Consumers of a target
should typically be in control of what precompile headers they use, not have
precompile headers forced on them by the targets being consumed (since
precompile headers are not typically usage requirements).  A notable exception
to this is where an :ref:`interface library <Interface Libraries>` is created
to define a commonly used set of precompile headers in one place and then other
targets link to that interface library privately.  In this case, the interface
library exists specifically to propagate the precompile headers to its
consumers and the consumer is effectively still in control, since it decides
whether to link to the interface library or not.

The list of header files is used to generate a header file named
``cmake_pch.h|xx`` which is used to generate the precompiled header file
(``.pch``, ``.gch``, ``.pchi``) artifact.  The ``cmake_pch.h|xx`` header
file will be force included (``-include`` for GCC, ``/FI`` for MSVC) to
all source files, so sources do not need to have ``#include "pch.h"``.

Header file names specified with angle brackets (e.g. ``<unordered_map>``) or
explicit double quotes (escaped for the :manual:`cmake-language(7)`,
e.g. ``[["other_header.h"]]``) will be treated as is, and include directories
must be available for the compiler to find them.  Other header file names
(e.g. ``project_header.h``) are interpreted as being relative to the current
source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be
included by absolute path.  For example:

.. code-block:: cmake

  target_precompile_headers(myTarget
    PUBLIC
      project_header.h
    PRIVATE
      [["other_header.h"]]
      <unordered_map>
  )

.. |command_name| replace:: ``target_precompile_headers``
.. |more_see_also| replace:: The :genex:`$<COMPILE_LANGUAGE:...>` generator
   expression is particularly useful for specifying a language-specific header
   to precompile for only one language (e.g. ``CXX`` and not ``C``).  In this
   case, header file names that are not explicitly in double quotes or angle
   brackets must be specified by absolute path.  Also, when specifying angle
   brackets inside a generator expression, be sure to encode the closing
   ``>`` as :genex:`$<ANGLE-R>`.  For example:
.. include:: GENEX_NOTE.txt
   :start-line: 1

.. code-block:: cmake

  target_precompile_headers(mylib PRIVATE
    "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
    "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
    "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
  )

Reusing Precompile Headers
^^^^^^^^^^^^^^^^^^^^^^^^^^

The command also supports a second signature which can be used to specify that
one target reuses a precompiled header file artifact from another target
instead of generating its own:

.. code-block:: cmake

  target_precompile_headers(<target> REUSE_FROM <other_target>)

This form sets the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` property to
``<other_target>`` and adds a dependency such that ``<target>`` will depend
on ``<other_target>``.  CMake will halt with an error if the
:prop_tgt:`PRECOMPILE_HEADERS` property of ``<target>`` is already set when
the ``REUSE_FROM`` form is used.

.. note::

  The ``REUSE_FROM`` form requires the same set of compiler options,
  compiler flags and compiler definitions for both ``<target>`` and
  ``<other_target>``.  Some compilers (e.g. GCC) may issue a warning if the
  precompiled header file cannot be used (``-Winvalid-pch``).

See Also
^^^^^^^^

* To disable precompile headers for specific targets, see the
  :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property.

* To prevent precompile headers from being used when compiling a specific
  source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property.

* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_sources`


code:
target_sources
--------------

.. versionadded:: 3.1

Add sources to a target.

.. code-block:: cmake

  target_sources(<target>
    <INTERFACE|PUBLIC|PRIVATE> [items1...]
    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

Specifies sources to use when building a target and/or its dependents.
The named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` or
:command:`add_custom_target` and must not be an
:ref:`ALIAS target <Alias Targets>`.  The ``<items>`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.

.. versionadded:: 3.20
  ``<target>`` can be a custom target.

The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the :ref:`scope <Target Usage Requirements>` of the source file paths
(``<items>``) that follow them.  ``PRIVATE`` and ``PUBLIC`` items will
populate the :prop_tgt:`SOURCES` property of ``<target>``, which are used when
building the target itself. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used
when building dependents.  A target created by :command:`add_custom_target`
can only have ``PRIVATE`` scope.

Repeated calls for the same ``<target>`` append items in the order called.

.. versionadded:: 3.3
  Allow exporting targets with :prop_tgt:`INTERFACE_SOURCES`.

.. versionadded:: 3.11
  Allow setting ``INTERFACE`` items on
  :ref:`IMPORTED targets <Imported Targets>`.

.. versionchanged:: 3.13
  Relative source file paths are interpreted as being relative to the current
  source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).
  See policy :policy:`CMP0076`.

A path that begins with a generator expression is left unmodified.
When a target's :prop_tgt:`SOURCE_DIR` property differs from
:variable:`CMAKE_CURRENT_SOURCE_DIR`, use absolute paths in generator
expressions to ensure the sources are correctly assigned to the target.

.. code-block:: cmake

  # WRONG: starts with generator expression, but relative path used
  target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:dbgsrc.cpp>")

  # CORRECT: absolute path used inside the generator expression
  target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>")

See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.

.. _`File Sets`:

File Sets
^^^^^^^^^

.. versionadded:: 3.23

.. code-block:: cmake

  target_sources(<target>
    [<INTERFACE|PUBLIC|PRIVATE>
     [FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]...
    ]...)

Adds a file set to a target, or adds files to an existing file set. Targets
have zero or more named file sets. Each file set has a name, a type, a scope of
``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and
files within those directories. The acceptable types include:

``HEADERS``

  Sources intended to be used via a language's ``#include`` mechanism.

``CXX_MODULES``
  .. versionadded:: 3.28

  Sources which contain C++ interface module or partition units (i.e., those
  using the ``export`` keyword). This file set type may not have an
  ``INTERFACE`` scope except on ``IMPORTED`` targets.

The optional default file sets are named after their type. The target may not
be a custom target or :prop_tgt:`FRAMEWORK` target.

Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for
the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets
have their :prop_sf:`HEADER_FILE_ONLY` property set to ``TRUE``. Files in an
``INTERFACE`` or ``PUBLIC`` file set can be installed with the
:command:`install(TARGETS)` command, and exported with the
:command:`install(EXPORT)` and :command:`export` commands.

Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, or
``PRIVATE`` and accepts the following arguments:

``FILE_SET <set>``

  The name of the file set to create or add to. It must contain only letters,
  numbers and underscores. Names starting with a capital letter are reserved
  for built-in file sets predefined by CMake. The only predefined set names
  are those matching the acceptable types. All other set names must not start
  with a capital letter or
  underscore.

``TYPE <type>``

  Every file set is associated with a particular type of file. Only types
  specified above may be used and it is an error to specify anything else. As
  a special case, if the name of the file set is one of the types, the type
  does not need to be specified and the ``TYPE <type>`` arguments can be
  omitted. For all other file set names, ``TYPE`` is required.

``BASE_DIRS <dirs>...``

  An optional list of base directories of the file set. Any relative path
  is treated as relative to the current source directory
  (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). If no ``BASE_DIRS`` are
  specified when the file set is first created, the value of
  :variable:`CMAKE_CURRENT_SOURCE_DIR` is added. This argument supports
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

  No two base directories for a file set may be sub-directories of each other.
  This requirement must be met across all base directories added to a file set,
  not just those within a single call to ``target_sources()``.

``FILES <files>...``

  An optional list of files to add to the file set. Each file must be in
  one of the base directories, or a subdirectory of one of the base
  directories. This argument supports
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

  If relative paths are specified, they are considered relative to
  :variable:`CMAKE_CURRENT_SOURCE_DIR` at the time ``target_sources()`` is
  called. An exception to this is a path starting with ``$<``. Such paths
  are treated as relative to the target's source directory after evaluation
  of generator expressions.

The following target properties are set by ``target_sources(FILE_SET)``,
but they should not generally be manipulated directly:

For file sets of type ``HEADERS``:

* :prop_tgt:`HEADER_SETS`
* :prop_tgt:`INTERFACE_HEADER_SETS`
* :prop_tgt:`HEADER_SET`
* :prop_tgt:`HEADER_SET_<NAME>`
* :prop_tgt:`HEADER_DIRS`
* :prop_tgt:`HEADER_DIRS_<NAME>`

For file sets of type ``CXX_MODULES``:

* :prop_tgt:`CXX_MODULE_SETS`
* :prop_tgt:`INTERFACE_CXX_MODULE_SETS`
* :prop_tgt:`CXX_MODULE_SET`
* :prop_tgt:`CXX_MODULE_SET_<NAME>`
* :prop_tgt:`CXX_MODULE_DIRS`
* :prop_tgt:`CXX_MODULE_DIRS_<NAME>`

Target properties related to include directories are also modified by
``target_sources(FILE_SET)`` as follows:

:prop_tgt:`INCLUDE_DIRECTORIES`

  If the ``TYPE`` is ``HEADERS``, and the scope of the file set is ``PRIVATE``
  or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in
  :genex:`$<BUILD_INTERFACE>` and appended to this property.

:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`

  If the ``TYPE`` is ``HEADERS``, and the scope of the file set is
  ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are
  wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property.

See Also
^^^^^^^^

* :command:`add_executable`
* :command:`add_library`
* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`


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.


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