code:
cmake_policy
------------

Manage CMake Policy settings.  See the :manual:`cmake-policies(7)`
manual for defined policies.

As CMake evolves it is sometimes necessary to change existing behavior
in order to fix bugs or improve implementations of existing features.
The CMake Policy mechanism is designed to help keep existing projects
building as new versions of CMake introduce changes in behavior.  Each
new policy (behavioral change) is given an identifier of the form
``CMP<NNNN>`` where ``<NNNN>`` is an integer index.  Documentation
associated with each policy describes the ``OLD`` and ``NEW`` behavior
and the reason the policy was introduced.  Projects may set each policy
to select the desired behavior.  When CMake needs to know which behavior
to use it checks for a setting specified by the project.  If no
setting is available the ``OLD`` behavior is assumed and a warning is
produced requesting that the policy be set.

Setting Policies by CMake Version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
behavior.  While setting policies individually is supported, we
encourage projects to set policies based on CMake versions:

.. signature:: cmake_policy(VERSION <min>[...<max>])
  :target: VERSION

.. versionadded:: 3.12
  The optional ``<max>`` version.

``<min>`` and the optional ``<max>`` are each CMake versions of the form
``major.minor[.patch[.tweak]]``, and the ``...`` is literal.  The ``<min>``
version must be at least ``2.4`` and at most the running version of CMake.
The ``<max>`` version, if specified, must be at least the ``<min>`` version
but may exceed the running version of CMake.  If the running version of
CMake is older than 3.12, the extra ``...`` dots will be seen as version
component separators, resulting in the ``...<max>`` part being ignored and
preserving the pre-3.12 behavior of basing policies on ``<min>``.

This specifies that the current CMake code is written for the given
range of CMake versions.  All policies known to the running version of CMake
and introduced in the ``<min>`` (or ``<max>``, if specified) version
or earlier will be set to use ``NEW`` behavior.  All policies
introduced in later versions will be unset (unless the
:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default).
This effectively requests behavior preferred as of a given CMake
version and tells newer CMake versions to warn about their new policies.

Note that the :command:`cmake_minimum_required(VERSION)`
command implicitly calls ``cmake_policy(VERSION)`` too.

.. include:: DEPRECATED_POLICY_VERSIONS.txt

Setting Policies Explicitly
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. signature:: cmake_policy(SET CMP<NNNN> NEW|OLD)
  :target: SET

Tell CMake to use the ``OLD`` or ``NEW`` behavior for a given policy.
Projects depending on the old behavior of a given policy may silence a
policy warning by setting the policy state to ``OLD``.  Alternatively
one may fix the project to work with the new behavior and set the
policy state to ``NEW``.

.. include:: ../policy/DEPRECATED.txt

Checking Policy Settings
^^^^^^^^^^^^^^^^^^^^^^^^

.. signature:: cmake_policy(GET CMP<NNNN> <variable>)
  :target: GET

Check whether a given policy is set to ``OLD`` or ``NEW`` behavior.
The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the
policy is set, and empty otherwise.

CMake Policy Stack
^^^^^^^^^^^^^^^^^^

CMake keeps policy settings on a stack, so changes made by the
``cmake_policy`` command affect only the top of the stack.  A new entry on
the policy stack is managed automatically for each subdirectory to
protect its parents and siblings.  CMake also manages a new entry for
scripts loaded by :command:`include` and :command:`find_package` commands
except when invoked with the ``NO_POLICY_SCOPE`` option
(see also policy :policy:`CMP0011`).
The ``cmake_policy`` command provides an interface to manage custom
entries on the policy stack:

.. signature:: cmake_policy(PUSH)
  :target: PUSH

  Create a new entry on the policy stack.

.. signature:: cmake_policy(POP)
  :target: POP

  Remove the last policy stack entry created with ``cmake_policy(PUSH)``.

Each ``PUSH`` must have a matching ``POP`` to erase any changes.
This is useful to make temporary changes to policy settings.
Calls to the :command:`cmake_minimum_required(VERSION)`,
:command:`cmake_policy(VERSION)`, or :command:`cmake_policy(SET)` commands
influence only the current top of the policy stack.

.. versionadded:: 3.25
  The :command:`block(SCOPE_FOR POLICIES)` command offers a more flexible
  and more secure way to manage the policy stack. The pop action is done
  automatically when leaving the block scope, so there is no need to
  precede each :command:`return` with a call to :command:`cmake_policy(POP)`.

  .. code-block:: cmake

    # stack management with cmake_policy()
    function(my_func)
      cmake_policy(PUSH)
      cmake_policy(SET ...)
      if (<cond1>)
        ...
        cmake_policy(POP)
        return()
      elseif(<cond2>)
        ...
        cmake_policy(POP)
        return()
      endif()
      ...
      cmake_policy(POP)
    endfunction()

    # stack management with block()/endblock()
    function(my_func)
      block(SCOPE_FOR POLICIES)
        cmake_policy(SET ...)
        if (<cond1>)
          ...
          return()
        elseif(<cond2>)
          ...
          return()
        endif()
        ...
      endblock()
    endfunction()

Commands created by the :command:`function` and :command:`macro`
commands record policy settings when they are created and
use the pre-record policies when they are invoked.  If the function or
macro implementation sets policies, the changes automatically
propagate up through callers until they reach the closest nested
policy stack entry.

See Also
^^^^^^^^

* :command:`cmake_minimum_required`


code:
configure_file
--------------

.. only:: html

   .. contents::

Copy a file to another location and modify its contents.

.. code-block:: cmake

  configure_file(<input> <output>
                 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
                  FILE_PERMISSIONS <permissions>...]
                 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
                 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

Copies an ``<input>`` file to an ``<output>`` file while performing
`transformations`_ of the input file content.

If the input file is modified the build system will re-run CMake to
re-configure the file and generate the build system again.
The generated file is modified and its timestamp updated on subsequent
cmake runs only if its content is changed.

Options
^^^^^^^

The options are:

``<input>``
  Path to the input file.  A relative path is treated with respect to
  the value of :variable:`CMAKE_CURRENT_SOURCE_DIR`.  The input path
  must be a file, not a directory.

``<output>``
  Path to the output file or directory.  A relative path is treated
  with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
  If the path names an existing directory the output file is placed
  in that directory with the same file name as the input file.
  If the path contains non-existent directories, they are created.

``NO_SOURCE_PERMISSIONS``
  .. versionadded:: 3.19

  Do not transfer the permissions of the input file to the output file.
  The copied file permissions default to the standard 644 value
  (-rw-r--r--).

``USE_SOURCE_PERMISSIONS``
  .. versionadded:: 3.20

  Transfer the permissions of the input file to the output file.
  This is already the default behavior if none of the three permissions-related
  keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS``
  or ``FILE_PERMISSIONS``).  The ``USE_SOURCE_PERMISSIONS`` keyword mostly
  serves as a way of making the intended behavior clearer at the call site.

``FILE_PERMISSIONS <permissions>...``
  .. versionadded:: 3.20

  Ignore the input file's permissions and use the specified ``<permissions>``
  for the output file instead.

``COPYONLY``
  Copy the file without replacing any variable references or other
  content.  This option may not be used with ``NEWLINE_STYLE``.

``ESCAPE_QUOTES``
  Escape any substituted quotes with backslashes (C-style).

``@ONLY``
  Restrict variable replacement to references of the form ``@VAR@``.
  This is useful for configuring scripts that use ``${VAR}`` syntax.

``NEWLINE_STYLE <style>``
  Specify the newline style for the output file.  Specify
  ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
  ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
  This option may not be used with ``COPYONLY``.

Transformations
^^^^^^^^^^^^^^^

:ref:`Variables <CMake Language Variables>` referenced in the input
file content as ``@VAR@``, ``${VAR}``, ``$CACHE{VAR}``, and
:ref:`environment variables <CMake Language Environment Variables>`
referenced as ``$ENV{VAR}``, will each be replaced with the current value
of the variable, or the empty string if the variable is not defined.
Furthermore, input lines of the form

.. code-block:: c

  #cmakedefine VAR ...

will be replaced with either

.. code-block:: c

  #define VAR ...

or

.. code-block:: c

  /* #undef VAR */

depending on whether ``VAR`` is set in CMake to any value not considered
a false constant by the :command:`if` command.  The "..." content on the
line after the variable name, if any, is processed as above.

Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form
``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1``
rather than being assigned the value ``...``. Therefore, input lines of the form

.. code-block:: c

  #cmakedefine01 VAR

will be replaced with either

.. code-block:: c

  #define VAR 0

or

.. code-block:: c

  #define VAR 1

Input lines of the form ``#cmakedefine01 VAR ...`` will expand
as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 1``,
which may lead to undefined behavior.

.. versionadded:: 3.10
  The result lines (with the exception of the ``#undef`` comments) can be
  indented using spaces and/or tabs between the ``#`` character
  and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace
  indentation will be preserved in the output lines:

  .. code-block:: c

    #  cmakedefine VAR
    #  cmakedefine01 VAR

  will be replaced, if ``VAR`` is defined, with

  .. code-block:: c

    #  define VAR
    #  define VAR 1

Example
^^^^^^^

Consider a source tree containing a ``foo.h.in`` file:

.. code-block:: c

  #cmakedefine FOO_ENABLE
  #cmakedefine FOO_STRING "@FOO_STRING@"

An adjacent ``CMakeLists.txt`` may use ``configure_file`` to
configure the header:

.. code-block:: cmake

  option(FOO_ENABLE "Enable Foo" ON)
  if(FOO_ENABLE)
    set(FOO_STRING "foo")
  endif()
  configure_file(foo.h.in foo.h @ONLY)

This creates a ``foo.h`` in the build directory corresponding to
this source directory.  If the ``FOO_ENABLE`` option is on, the
configured file will contain:

.. code-block:: c

  #define FOO_ENABLE
  #define FOO_STRING "foo"

Otherwise it will contain:

.. code-block:: c

  /* #undef FOO_ENABLE */
  /* #undef FOO_STRING */

One may then use the :command:`target_include_directories` command to
specify the output directory as an include directory:

.. code-block:: cmake

  target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}")

so that sources may include the header as ``#include <foo.h>``.

See Also
^^^^^^^^

* :command:`file(GENERATE)`

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
continue
--------

.. versionadded:: 3.2

Continue to the top of enclosing foreach or while loop.

.. code-block:: cmake

  continue()

The ``continue()`` command allows a cmake script to abort the rest of the
current iteration of a :command:`foreach` or :command:`while` loop, and start
at the top of the next iteration.

See also the :command:`break` command.


code:
create_test_sourcelist
----------------------

Create a test driver program that links together many small tests into a
single executable.  This is useful when building static executables with
large libraries to shrink the total required size.

.. signature::
  create_test_sourcelist(<sourceListName> <driverName> <test>... <options>...)
  :target: original

  Generate a test driver source file from a list of individual test sources
  and provide a combined list of sources that can be built as an executable.

  The options are:

  ``<sourceListName>``
    The name of a variable in which to store the list of source files needed
    to build the test driver.  The list will contain the ``<test>...`` sources
    and the generated ``<driverName>`` source.

    .. versionchanged:: 3.29

      The test driver source is listed by absolute path in the build tree.
      Previously it was listed only as ``<driverName>``.

  ``<driverName>``
    Name of the test driver source file to be generated into the build tree.
    The source file will contain a ``main()`` program entry point that
    dispatches to whatever test is named on the command line.

  ``<test>...``
    Test source files to be added to the driver binary.  Each test source
    file must have a function in it that is the same name as the file with the
    extension removed.  For example, a ``foo.cxx`` test source might contain:

    .. code-block:: c++

      int foo(int argc, char** argv)

  ``EXTRA_INCLUDE <header>``
    Specify a header file to ``#include`` in the generated test driver source.

  ``FUNCTION <function>``
    Specify a function to be called with pointers to ``argc`` and ``argv``.
    The function may be provided in the ``EXTRA_INCLUDE`` header:

    .. code-block:: c++

      void function(int* pargc, char*** pargv)

    This can be used to add extra command line processing to each test.

Additionally, some CMake variables affect test driver generation:

.. variable:: CMAKE_TESTDRIVER_BEFORE_TESTMAIN

  Code to be placed directly before calling each test's function.

.. variable:: CMAKE_TESTDRIVER_AFTER_TESTMAIN

  Code to be placed directly after the call to each test's function.


code:
ctest_build
-----------

Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.

.. code-block:: cmake

  ctest_build([BUILD <build-dir>] [APPEND]
              [CONFIGURATION <config>]
              [PARALLEL_LEVEL <parallel>]
              [FLAGS <flags>]
              [PROJECT_NAME <project-name>]
              [TARGET <target-name>]
              [NUMBER_ERRORS <num-err-var>]
              [NUMBER_WARNINGS <num-warn-var>]
              [RETURN_VALUE <result-var>]
              [CAPTURE_CMAKE_ERROR <result-var>]
              )

Build the project and store results in ``Build.xml``
for submission with the :command:`ctest_submit` command.

The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly
specify the build command line.  Otherwise the build command line is
computed automatically based on the options given.

The options are:

``BUILD <build-dir>``
  Specify the top-level build directory.  If not given, the
  :variable:`CTEST_BINARY_DIRECTORY` variable is used.

``APPEND``
  Mark ``Build.xml`` for append to results previously submitted to a
  dashboard server since the last :command:`ctest_start` call.
  Append semantics are defined by the dashboard server in use.
  This does *not* cause results to be appended to a ``.xml`` file
  produced by a previous call to this command.

``CONFIGURATION <config>``
  Specify the build configuration (e.g. ``Debug``).  If not
  specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
  Otherwise the :option:`-C \<cfg\> <ctest -C>` option given to the
  :manual:`ctest(1)` command will be used, if any.

``PARALLEL_LEVEL <parallel>``
  .. versionadded:: 3.21

  Specify the parallel level of the underlying build system.  If not
  specified, the :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment
  variable will be checked.

``FLAGS <flags>``
  Pass additional arguments to the underlying build command.
  If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
  This can, e.g., be used to trigger a parallel build using the
  ``-j`` option of ``make``. See the :module:`ProcessorCount` module
  for an example.

``PROJECT_NAME <project-name>``
  Ignored since CMake 3.0.

  .. versionchanged:: 3.14
    This value is no longer required.

``TARGET <target-name>``
  Specify the name of a target to build.  If not specified the
  ``CTEST_BUILD_TARGET`` variable will be checked.  Otherwise the
  default target will be built.  This is the "all" target
  (called ``ALL_BUILD`` in :ref:`Visual Studio Generators`).

``NUMBER_ERRORS <num-err-var>``
  Store the number of build errors detected in the given variable.

``NUMBER_WARNINGS <num-warn-var>``
  Store the number of build warnings detected in the given variable.

``RETURN_VALUE <result-var>``
  Store the return value of the native build tool in the given variable.

``CAPTURE_CMAKE_ERROR <result-var>``
  .. versionadded:: 3.7

  Store in the ``<result-var>`` variable -1 if there are any errors running
  the command and prevent ctest from returning non-zero if an error occurs.

``QUIET``
  .. versionadded:: 3.3

  Suppress any CTest-specific non-error output that would have been
  printed to the console otherwise.  The summary of warnings / errors,
  as well as the output from the native build tool is unaffected by
  this option.


code:
ctest_configure
---------------

Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`.

.. code-block:: cmake

  ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
                  [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
                  [CAPTURE_CMAKE_ERROR <result-var>])

Configure the project build tree and record results in ``Configure.xml``
for submission with the :command:`ctest_submit` command.

The options are:

``BUILD <build-dir>``
  Specify the top-level build directory.  If not given, the
  :variable:`CTEST_BINARY_DIRECTORY` variable is used.

``SOURCE <source-dir>``
  Specify the source directory.  If not given, the
  :variable:`CTEST_SOURCE_DIRECTORY` variable is used.

``APPEND``
  Mark ``Configure.xml`` for append to results previously submitted to a
  dashboard server since the last :command:`ctest_start` call.
  Append semantics are defined by the dashboard server in use.
  This does *not* cause results to be appended to a ``.xml`` file
  produced by a previous call to this command.

``OPTIONS <options>``
  Specify command-line arguments to pass to the configuration tool.

``RETURN_VALUE <result-var>``
  Store in the ``<result-var>`` variable the return value of the native
  configuration tool.

``CAPTURE_CMAKE_ERROR <result-var>``
  .. versionadded:: 3.7

  Store in the ``<result-var>`` variable -1 if there are any errors running
  the command and prevent ctest from returning non-zero if an error occurs.

``QUIET``
  .. versionadded:: 3.3

  Suppress any CTest-specific non-error messages that would have
  otherwise been printed to the console.  Output from the underlying
  configure command is not affected.


code:
ctest_coverage
--------------

Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.

.. code-block:: cmake

  ctest_coverage([BUILD <build-dir>] [APPEND]
                 [LABELS <label>...]
                 [RETURN_VALUE <result-var>]
                 [CAPTURE_CMAKE_ERROR <result-var>]
                 [QUIET]
                 )

Collect coverage tool results and stores them in ``Coverage.xml``
for submission with the :command:`ctest_submit` command.

The options are:

``BUILD <build-dir>``
  Specify the top-level build directory.  If not given, the
  :variable:`CTEST_BINARY_DIRECTORY` variable is used.

``APPEND``
  Mark ``Coverage.xml`` for append to results previously submitted to a
  dashboard server since the last :command:`ctest_start` call.
  Append semantics are defined by the dashboard server in use.
  This does *not* cause results to be appended to a ``.xml`` file
  produced by a previous call to this command.

``LABELS``
  Filter the coverage report to include only source files labeled
  with at least one of the labels specified.

``RETURN_VALUE <result-var>``
  Store in the ``<result-var>`` variable ``0`` if coverage tools
  ran without error and non-zero otherwise.

``CAPTURE_CMAKE_ERROR <result-var>``
  .. versionadded:: 3.7

  Store in the ``<result-var>`` variable -1 if there are any errors running
  the command and prevent ctest from returning non-zero if an error occurs.

``QUIET``
  .. versionadded:: 3.3

  Suppress any CTest-specific non-error output that would have been
  printed to the console otherwise.  The summary indicating how many
  lines of code were covered is unaffected by this option.


code:
ctest_empty_binary_directory
----------------------------

empties the binary directory

.. code-block:: cmake

  ctest_empty_binary_directory(<directory>)

Removes a binary directory.  This command will perform some checks
prior to deleting the directory in an attempt to avoid malicious or
accidental directory deletion.


code:
ctest_memcheck
--------------

Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.

.. code-block:: cmake

  ctest_memcheck([BUILD <build-dir>] [APPEND]
                 [START <start-number>]
                 [END <end-number>]
                 [STRIDE <stride-number>]
                 [EXCLUDE <exclude-regex>]
                 [INCLUDE <include-regex>]
                 [EXCLUDE_LABEL <label-exclude-regex>]
                 [INCLUDE_LABEL <label-include-regex>]
                 [EXCLUDE_FIXTURE <regex>]
                 [EXCLUDE_FIXTURE_SETUP <regex>]
                 [EXCLUDE_FIXTURE_CLEANUP <regex>]
                 [PARALLEL_LEVEL <level>]
                 [RESOURCE_SPEC_FILE <file>]
                 [TEST_LOAD <threshold>]
                 [SCHEDULE_RANDOM <ON|OFF>]
                 [STOP_ON_FAILURE]
                 [STOP_TIME <time-of-day>]
                 [RETURN_VALUE <result-var>]
                 [CAPTURE_CMAKE_ERROR <result-var>]
                 [REPEAT <mode>:<n>]
                 [OUTPUT_JUNIT <file>]
                 [DEFECT_COUNT <defect-count-var>]
                 [QUIET]
                 )

Run tests with a dynamic analysis tool and store results in
``MemCheck.xml`` for submission with the :command:`ctest_submit`
command.

Most options are the same as those for the :command:`ctest_test` command.

The options unique to this command are:

``DEFECT_COUNT <defect-count-var>``
  .. versionadded:: 3.8

  Store in the ``<defect-count-var>`` the number of defects found.


code:
ctest_read_custom_files
-----------------------

read CTestCustom files.

.. code-block:: cmake

  ctest_read_custom_files(<directory>...)

Read all the CTestCustom.ctest or CTestCustom.cmake files from the
given directory.

By default, invoking :manual:`ctest(1)` without a script will read custom
files from the binary directory.


code:
ctest_run_script
----------------

runs a :option:`ctest -S` script

.. code-block:: cmake

  ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
              script_file_name2 ... [RETURN_VALUE var])

Runs a script or scripts much like if it was run from :option:`ctest -S`.
If no argument is provided then the current script is run using the current
settings of the variables.  If ``NEW_PROCESS`` is specified then each
script will be run in a separate process.If ``RETURN_VALUE`` is specified
the return value of the last script run will be put into ``var``.


code:
ctest_sleep
-----------

sleeps for some amount of time

.. code-block:: cmake

  ctest_sleep(<seconds>)

Sleep for given number of seconds.

.. code-block:: cmake

  ctest_sleep(<time1> <duration> <time2>)

Sleep for t=(time1 + duration - time2) seconds if t > 0.


code:
ctest_start
-----------

Starts the testing for a given model

.. code-block:: cmake

  ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])

  ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])

Starts the testing for a given model.  The command should be called
after the binary directory is initialized.

The parameters are as follows:

``<model>``
  Set the dashboard model. Must be one of ``Experimental``, ``Continuous``, or
  ``Nightly``. This parameter is required unless ``APPEND`` is specified.

``<source>``
  Set the source directory. If not specified, the value of
  :variable:`CTEST_SOURCE_DIRECTORY` is used instead.

``<binary>``
  Set the binary directory. If not specified, the value of
  :variable:`CTEST_BINARY_DIRECTORY` is used instead.

``GROUP <group>``
  If ``GROUP`` is used, the submissions will go to the specified group on the
  CDash server. If no ``GROUP`` is specified, the name of the model is used by
  default.

  .. versionchanged:: 3.16
    This replaces the deprecated option ``TRACK``. Despite the name
    change its behavior is unchanged.

``APPEND``
  If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new
  one based on the current time stamp. If you use ``APPEND``, you can omit the
  ``<model>`` and ``GROUP <group>`` parameters, because they will be read from
  the generated ``TAG`` file. For example:

  .. code-block:: cmake

    ctest_start(Experimental GROUP GroupExperimental)

  Later, in another :option:`ctest -S` script:

  .. code-block:: cmake

    ctest_start(APPEND)

  When the second script runs ``ctest_start(APPEND)``, it will read the
  ``Experimental`` model and ``GroupExperimental`` group from the ``TAG`` file
  generated by the first ``ctest_start()`` command. Please note that if you
  call ``ctest_start(APPEND)`` and specify a different model or group than
  in the first ``ctest_start()`` command, a warning will be issued, and the
  new model and group will be used.

``QUIET``
  .. versionadded:: 3.3

  If ``QUIET`` is used, CTest will suppress any non-error messages that it
  otherwise would have printed to the console.

The parameters for ``ctest_start()`` can be issued in any order, with the
exception that ``<model>``, ``<source>``, and ``<binary>`` have to appear
in that order with respect to each other. The following are all valid and
equivalent:

.. code-block:: cmake

  ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)

  ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)

  ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)

However, for the sake of readability, it is recommended that you order your
parameters in the order listed at the top of this page.

If the :variable:`CTEST_CHECKOUT_COMMAND` variable (or the
:variable:`CTEST_CVS_CHECKOUT` variable) is set, its content is treated as
command-line.  The command is invoked with the current working directory set
to the parent of the source directory, even if the source directory already
exists.  This can be used to create the source tree from a version control
repository.


code:
ctest_submit
------------

Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.

.. code-block:: cmake

  ctest_submit([PARTS <part>...] [FILES <file>...]
               [SUBMIT_URL <url>]
               [BUILD_ID <result-var>]
               [HTTPHEADER <header>]
               [RETRY_COUNT <count>]
               [RETRY_DELAY <delay>]
               [RETURN_VALUE <result-var>]
               [CAPTURE_CMAKE_ERROR <result-var>]
               [QUIET]
               )

Submit results to a dashboard server.
By default all available parts are submitted.

The options are:

``PARTS <part>...``
  Specify a subset of parts to submit.  Valid part names are::

    Start      = nothing
    Update     = ctest_update results, in Update.xml
    Configure  = ctest_configure results, in Configure.xml
    Build      = ctest_build results, in Build.xml
    Test       = ctest_test results, in Test.xml
    Coverage   = ctest_coverage results, in Coverage.xml
    MemCheck   = ctest_memcheck results, in DynamicAnalysis.xml and
                 DynamicAnalysis-Test.xml
    Notes      = Files listed by CTEST_NOTES_FILES, in Notes.xml
    ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
    Upload     = Files prepared for upload by ctest_upload(), in Upload.xml
    Submit     = nothing
    Done       = Build is complete, in Done.xml

``FILES <file>...``
  Specify an explicit list of specific files to be submitted.
  Each individual file must exist at the time of the call.

``SUBMIT_URL <url>``
  .. versionadded:: 3.14

  The ``http`` or ``https`` URL of the dashboard server to send the submission
  to.  If not given, the :variable:`CTEST_SUBMIT_URL` variable is used.

``BUILD_ID <result-var>``
  .. versionadded:: 3.15

  Store in the ``<result-var>`` variable the ID assigned to this build by
  CDash.

``HTTPHEADER <HTTP-header>``
  .. versionadded:: 3.9

  Specify HTTP header to be included in the request to CDash during submission.
  For example, CDash can be configured to only accept submissions from
  authenticated clients. In this case, you should provide a bearer token in your
  header:

  .. code-block:: cmake

    ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")

  This suboption can be repeated several times for multiple headers.

``RETRY_COUNT <count>``
  Specify how many times to retry a timed-out submission.

``RETRY_DELAY <delay>``
  Specify how long (in seconds) to wait after a timed-out submission
  before attempting to re-submit.

``RETURN_VALUE <result-var>``
  Store in the ``<result-var>`` variable ``0`` for success and
  non-zero on failure.

``CAPTURE_CMAKE_ERROR <result-var>``
  .. versionadded:: 3.13

  Store in the ``<result-var>`` variable -1 if there are any errors running
  the command and prevent ctest from returning non-zero if an error occurs.

``QUIET``
  .. versionadded:: 3.3

  Suppress all non-error messages that would have otherwise been
  printed to the console.

Submit to CDash Upload API
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.2

.. code-block:: cmake

  ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
               [SUBMIT_URL <url>]
               [BUILD_ID <result-var>]
               [HTTPHEADER <header>]
               [RETRY_COUNT <count>]
               [RETRY_DELAY <delay>]
               [RETURN_VALUE <result-var>]
               [QUIET])

This second signature is used to upload files to CDash via the CDash
file upload API. The API first sends a request to upload to CDash along
with a content hash of the file. If CDash does not already have the file,
then it is uploaded. Along with the file, a CDash type string is specified
to tell CDash which handler to use to process the data.

This signature interprets options in the same way as the first one.

.. versionadded:: 3.8
  Added the ``RETRY_COUNT``, ``RETRY_DELAY``, ``QUIET`` options.

.. versionadded:: 3.9
  Added the ``HTTPHEADER`` option.

.. versionadded:: 3.13
  Added the ``RETURN_VALUE`` option.

.. versionadded:: 3.14
  Added the ``SUBMIT_URL`` option.

.. versionadded:: 3.15
  Added the ``BUILD_ID`` option.


code:
ctest_test
----------

Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.

.. code-block:: cmake

  ctest_test([BUILD <build-dir>] [APPEND]
             [START <start-number>]
             [END <end-number>]
             [STRIDE <stride-number>]
             [EXCLUDE <exclude-regex>]
             [INCLUDE <include-regex>]
             [EXCLUDE_LABEL <label-exclude-regex>]
             [INCLUDE_LABEL <label-include-regex>]
             [EXCLUDE_FROM_FILE <filename>]
             [INCLUDE_FROM_FILE <filename>]
             [EXCLUDE_FIXTURE <regex>]
             [EXCLUDE_FIXTURE_SETUP <regex>]
             [EXCLUDE_FIXTURE_CLEANUP <regex>]
             [PARALLEL_LEVEL <level>]
             [RESOURCE_SPEC_FILE <file>]
             [TEST_LOAD <threshold>]
             [SCHEDULE_RANDOM <ON|OFF>]
             [STOP_ON_FAILURE]
             [STOP_TIME <time-of-day>]
             [RETURN_VALUE <result-var>]
             [CAPTURE_CMAKE_ERROR <result-var>]
             [REPEAT <mode>:<n>]
             [OUTPUT_JUNIT <file>]
             [QUIET]
             )

..
   NOTE If updating the argument list here, please also update the argument
   list documentation for :command:`ctest_memcheck` as well.

Run tests in the project build tree and store results in
``Test.xml`` for submission with the :command:`ctest_submit` command.

The options are:

``BUILD <build-dir>``
  Specify the top-level build directory.  If not given, the
  :variable:`CTEST_BINARY_DIRECTORY` variable is used.

``APPEND``
  Mark ``Test.xml`` for append to results previously submitted to a
  dashboard server since the last :command:`ctest_start` call.
  Append semantics are defined by the dashboard server in use.
  This does *not* cause results to be appended to a ``.xml`` file
  produced by a previous call to this command.

``START <start-number>``
  Specify the beginning of a range of test numbers.

``END <end-number>``
  Specify the end of a range of test numbers.

``STRIDE <stride-number>``
  Specify the stride by which to step across a range of test numbers.

``EXCLUDE <exclude-regex>``
  Specify a regular expression matching test names to exclude.

``INCLUDE <include-regex>``
  Specify a regular expression matching test names to include.
  Tests not matching this expression are excluded.

``EXCLUDE_LABEL <label-exclude-regex>``
  Specify a regular expression matching test labels to exclude.

``INCLUDE_LABEL <label-include-regex>``
  Specify a regular expression matching test labels to include.
  Tests not matching this expression are excluded.

``EXCLUDE_FROM_FILE <filename>``
  .. versionadded:: 3.29

  Do NOT run tests listed with their exact name in the given file.

``INCLUDE_FROM_FILE <filename>``
  .. versionadded:: 3.29

  Only run the tests listed with their exact name in the given file.

``EXCLUDE_FIXTURE <regex>``
  .. versionadded:: 3.7

  If a test in the set of tests to be executed requires a particular fixture,
  that fixture's setup and cleanup tests would normally be added to the test
  set automatically. This option prevents adding setup or cleanup tests for
  fixtures matching the ``<regex>``. Note that all other fixture behavior is
  retained, including test dependencies and skipping tests that have fixture
  setup tests that fail.

``EXCLUDE_FIXTURE_SETUP <regex>``
  .. versionadded:: 3.7

  Same as ``EXCLUDE_FIXTURE`` except only matching setup tests are excluded.

``EXCLUDE_FIXTURE_CLEANUP <regex>``
  .. versionadded:: 3.7

  Same as ``EXCLUDE_FIXTURE`` except only matching cleanup tests are excluded.

``PARALLEL_LEVEL <level>``
  Specify a positive number representing the number of tests to
  be run in parallel.

``RESOURCE_SPEC_FILE <file>``
  .. versionadded:: 3.16

  Specify a
  :ref:`resource specification file <ctest-resource-specification-file>`. See
  :ref:`ctest-resource-allocation` for more information.

``TEST_LOAD <threshold>``
  .. versionadded:: 3.4

  While running tests in parallel, try not to start tests when they
  may cause the CPU load to pass above a given threshold.  If not
  specified the :variable:`CTEST_TEST_LOAD` variable will be checked,
  and then the :option:`--test-load <ctest --test-load>` command-line
  argument to :manual:`ctest(1)`. See also the ``TestLoad`` setting
  in the :ref:`CTest Test Step`.

``REPEAT <mode>:<n>``
  .. versionadded:: 3.17

  Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times.
  The modes are:

  ``UNTIL_FAIL``
    Require each test to run ``<n>`` times without failing in order to pass.
    This is useful in finding sporadic failures in test cases.

  ``UNTIL_PASS``
    Allow each test to run up to ``<n>`` times in order to pass.
    Repeats tests if they fail for any reason.
    This is useful in tolerating sporadic failures in test cases.

  ``AFTER_TIMEOUT``
    Allow each test to run up to ``<n>`` times in order to pass.
    Repeats tests only if they timeout.
    This is useful in tolerating sporadic timeouts in test cases
    on busy machines.

``SCHEDULE_RANDOM <ON|OFF>``
  Launch tests in a random order.  This may be useful for detecting
  implicit test dependencies.

``STOP_ON_FAILURE``
  .. versionadded:: 3.18

  Stop the execution of the tests once one has failed.

``STOP_TIME <time-of-day>``
  Specify a time of day at which the tests should all stop running.

``RETURN_VALUE <result-var>``
  Store in the ``<result-var>`` variable ``0`` if all tests passed.
  Store non-zero if anything went wrong.

``CAPTURE_CMAKE_ERROR <result-var>``
  .. versionadded:: 3.7

  Store in the ``<result-var>`` variable -1 if there are any errors running
  the command and prevent ctest from returning non-zero if an error occurs.

``OUTPUT_JUNIT <file>``
  .. versionadded:: 3.21

  Write test results to ``<file>`` in JUnit XML format. If ``<file>`` is a
  relative path, it will be placed in the build directory. If ``<file>``
  already exists, it will be overwritten. Note that the resulting JUnit XML
  file is **not** uploaded to CDash because it would be redundant with
  CTest's ``Test.xml`` file.

``QUIET``
  .. versionadded:: 3.3

  Suppress any CTest-specific non-error messages that would have otherwise
  been printed to the console.  Output from the underlying test command is not
  affected.  Summary info detailing the percentage of passing tests is also
  unaffected by the ``QUIET`` option.

See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`,
:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and
:variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables, along with their
corresponding :manual:`ctest(1)` command line options
:option:`--test-output-size-passed <ctest --test-output-size-passed>`,
:option:`--test-output-size-failed <ctest --test-output-size-failed>`, and
:option:`--test-output-truncation <ctest --test-output-truncation>`.

.. _`Additional Test Measurements`:

Additional Test Measurements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

CTest can parse the output of your tests for extra measurements to report
to CDash.

When run as a :ref:`Dashboard Client`, CTest will include these custom
measurements in the ``Test.xml`` file that gets uploaded to CDash.

Check the `CDash test measurement documentation
<https://github.com/Kitware/CDash/blob/master/docs/test_measurements.md>`_
for more information on the types of test measurements that CDash recognizes.

.. versionadded: 3.22
  CTest can parse custom measurements from tags named
  ``<CTestMeasurement>`` or ``<CTestMeasurementFile>``. The older names
  ``<DartMeasurement>`` and ``<DartMeasurementFile>`` are still supported.

The following example demonstrates how to output a variety of custom test
measurements.

.. code-block:: c++

   std::cout <<
     "<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>"
     << std::endl;

   std::cout <<
     "<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>"
     << std::endl;

   std::cout <<
     "<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</CTestMeasurement>"
     << std::endl;

   std::cout <<
     "<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" <<
     "line 1.\n" <<
     "  \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" <<
     "line 3. Not bold or indented...\n" <<
     "</CTestMeasurement>" << std::endl;

Image Measurements
""""""""""""""""""

The following example demonstrates how to upload test images to CDash.

.. code-block:: c++

   std::cout <<
     "<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" <<
     "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl;

   std::cout <<
     "<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" <<
     "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl;

   std::cout <<
     "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\">" <<
     "/dir/to/img.png</CTestMeasurementFile>"
     << std::endl;

Images will be displayed together in an interactive comparison mode on CDash
if they are provided with two or more of the following names.

* ``TestImage``
* ``ValidImage``
* ``BaselineImage``
* ``DifferenceImage2``

By convention, ``TestImage`` is the image generated by your test, and
``ValidImage`` (or ``BaselineImage``) is basis of comparison used to determine
if the test passed or failed.

If another image name is used it will be displayed by CDash as a static image
separate from the interactive comparison UI.

Attached Files
""""""""""""""

.. versionadded:: 3.21

The following example demonstrates how to upload non-image files to CDash.

.. code-block:: c++

   std::cout <<
     "<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" <<
     "/dir/to/data1.csv</CTestMeasurementFile>\n"                   <<
     "<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" <<
     "/dir/to/data2.csv</CTestMeasurementFile>"                     << std::endl;

If the name of the file to upload is known at configure time, you can use the
:prop_test:`ATTACHED_FILES` or :prop_test:`ATTACHED_FILES_ON_FAIL` test
properties instead.

Custom Details
""""""""""""""

.. versionadded:: 3.21

The following example demonstrates how to specify a custom value for the
``Test Details`` field displayed on CDash.

.. code-block:: c++

   std::cout <<
     "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl;

.. _`Additional Labels`:

Additional Labels
"""""""""""""""""

.. versionadded:: 3.22

The following example demonstrates how to add additional labels to a test
at runtime.

.. code-block:: c++

   std::cout <<
     "<CTestLabel>Custom Label 1</CTestLabel>\n" <<
     "<CTestLabel>Custom Label 2</CTestLabel>"   << std::endl;

Use the :prop_test:`LABELS` test property instead for labels that can be
determined at configure time.


code:
ctest_update
------------

Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.

.. code-block:: cmake

  ctest_update([SOURCE <source-dir>]
               [RETURN_VALUE <result-var>]
               [CAPTURE_CMAKE_ERROR <result-var>]
               [QUIET])

Update the source tree from version control and record results in
``Update.xml`` for submission with the :command:`ctest_submit` command.

The options are:

``SOURCE <source-dir>``
  Specify the source directory.  If not given, the
  :variable:`CTEST_SOURCE_DIRECTORY` variable is used.

``RETURN_VALUE <result-var>``
  Store in the ``<result-var>`` variable the number of files
  updated or ``-1`` on error.

``CAPTURE_CMAKE_ERROR <result-var>``
  .. versionadded:: 3.13

  Store in the ``<result-var>`` variable -1 if there are any errors running
  the command and prevent ctest from returning non-zero if an error occurs.

``QUIET``
  .. versionadded:: 3.3

  Tell CTest to suppress most non-error messages that it would
  have otherwise printed to the console.  CTest will still report
  the new revision of the repository and any conflicting files
  that were found.

The update always follows the version control branch currently checked
out in the source directory.  See the :ref:`CTest Update Step`
documentation for information about variables that change the behavior
of ``ctest_update()``.


code:
ctest_upload
------------

Upload files to a dashboard server as a :ref:`Dashboard Client`.

.. code-block:: cmake

  ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])

The options are:

``FILES <file>...``
  Specify a list of files to be sent along with the build results to the
  dashboard server.

``QUIET``
  .. versionadded:: 3.3

  Suppress any CTest-specific non-error output that would have been
  printed to the console otherwise.

``CAPTURE_CMAKE_ERROR <result-var>``
  .. versionadded:: 3.7

  Store in the ``<result-var>`` variable -1 if there are any errors running
  the command and prevent ctest from returning non-zero if an error occurs.


code:
define_property
---------------

Define and document custom properties.

.. code-block:: cmake

  define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
                   TEST | VARIABLE | CACHED_VARIABLE>
                   PROPERTY <name> [INHERITED]
                   [BRIEF_DOCS <brief-doc> [docs...]]
                   [FULL_DOCS <full-doc> [docs...]]
                   [INITIALIZE_FROM_VARIABLE <variable>])

Defines one property in a scope for use with the :command:`set_property` and
:command:`get_property` commands. It is mainly useful for defining the way
a property is initialized or inherited. Historically, the command also
associated documentation with a property, but that is no longer considered a
primary use case.

The first argument determines the kind of scope in which the property should
be used.  It must be one of the following:

::

  GLOBAL    = associated with the global namespace
  DIRECTORY = associated with one directory
  TARGET    = associated with one target
  SOURCE    = associated with one source file
  TEST      = associated with a test named with add_test
  VARIABLE  = documents a CMake language variable
  CACHED_VARIABLE = documents a CMake cache variable

Note that unlike :command:`set_property` and :command:`get_property` no
actual scope needs to be given; only the kind of scope is important.

The required ``PROPERTY`` option is immediately followed by the name of
the property being defined.

If the ``INHERITED`` option is given, then the :command:`get_property` command
will chain up to the next higher scope when the requested property is not set
in the scope given to the command.

* ``DIRECTORY`` scope chains to its parent directory's scope, continuing the
  walk up parent directories until a directory has the property set or there
  are no more parents.  If still not found at the top level directory, it
  chains to the ``GLOBAL`` scope.
* ``TARGET``, ``SOURCE`` and ``TEST`` properties chain to ``DIRECTORY`` scope,
  including further chaining up the directories, etc. as needed.

Note that this scope chaining behavior only applies to calls to
:command:`get_property`, :command:`get_directory_property`,
:command:`get_target_property`, :command:`get_source_file_property` and
:command:`get_test_property`.  There is no inheriting behavior when *setting*
properties, so using ``APPEND`` or ``APPEND_STRING`` with the
:command:`set_property` command will not consider inherited values when working
out the contents to append to.

The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be
associated with the property as its brief and full documentation.
CMake does not use this documentation other than making it available to the
project via corresponding options to the :command:`get_property` command.

.. versionchanged:: 3.23

  The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are optional.

.. versionadded:: 3.23

  The ``INITIALIZE_FROM_VARIABLE`` option specifies a variable from which the
  property should be initialized. It can only be used with target properties.
  The ``<variable>`` name must end with the property name and must not begin
  with ``CMAKE_`` or ``_CMAKE_``. The property name must contain at least one
  underscore. It is recommended that the property name have a prefix specific
  to the project.

Property Redefinition
^^^^^^^^^^^^^^^^^^^^^

Once a property is defined for a particular type of scope, it cannot be
redefined. Attempts to redefine an existing property by calling
:command:`define_property` with the same scope type and property name
will be silently ignored. Defining the same property name for two different
kinds of scope is valid.

:command:`get_property` can be used to determine whether a property is
already defined for a particular kind of scope, and if so, to examine its
definition. For example:

.. code-block:: cmake

  # Initial definition
  define_property(TARGET PROPERTY MY_NEW_PROP
    BRIEF_DOCS "My new custom property"
  )

  # Later examination
  get_property(my_new_prop_exists
    TARGET NONE
    PROPERTY MY_NEW_PROP
    DEFINED
  )

  if(my_new_prop_exists)
    get_property(my_new_prop_docs
      TARGET NONE
      PROPERTY MY_NEW_PROP
      BRIEF_DOCS
    )
    # ${my_new_prop_docs} is now set to "My new custom property"
  endif()

See Also
^^^^^^^^

* :command:`get_property`
* :command:`set_property`


code:
else
----

Starts the else portion of an if block.

.. code-block:: cmake

  else([<condition>])

See the :command:`if` command.


code:
elseif
------

Starts an elseif portion of an if block.

.. code-block:: cmake

  elseif(<condition>)

See the :command:`if` command, especially for the syntax and logic
of the ``<condition>``.


code:
enable_language
---------------

Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc)

.. code-block:: cmake

  enable_language(<lang>... [OPTIONAL])

Enables support for the named languages in CMake.  This is the same as
the :command:`project` command but does not create any of the extra
variables that are created by the project command.

.. include:: SUPPORTED_LANGUAGES.txt

This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or
indirectly through link dependencies.  It is simplest to enable all
needed languages in the top-level directory of a project.

The ``OPTIONAL`` keyword is a placeholder for future implementation and
does not currently work. Instead you can use the :module:`CheckLanguage`
module to verify support before enabling.


code:
enable_testing
--------------

Enable testing for current directory and below.

.. code-block:: cmake

  enable_testing()

Enables testing for this directory and below.

This command should be in the source directory root
because ctest expects to find a test file in the build
directory root.

This command is automatically invoked when the :module:`CTest`
module is included, except if the ``BUILD_TESTING`` option is
turned off.

See also the :command:`add_test` command.


code:
endblock
--------

.. versionadded:: 3.25

Ends a list of commands in a :command:`block` and removes the scopes
created by the :command:`block` command.

.. code-block:: cmake

  endblock()


code:
endforeach
----------

Ends a list of commands in a foreach block.

.. code-block:: cmake

  endforeach([<loop_var>])

See the :command:`foreach` command.

The optional ``<loop_var>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<loop_var>`` argument of
the opening ``foreach`` clause.


code:
endfunction
-----------

Ends a list of commands in a function block.

.. code-block:: cmake

  endfunction([<name>])

See the :command:`function` command.

The optional ``<name>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<name>`` argument
of the opening ``function`` command.


code:
endif
-----

Ends a list of commands in an if block.

.. code-block:: cmake

  endif([<condition>])

See the :command:`if` command.

The optional ``<condition>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
``if`` clause.


code:
endmacro
--------

Ends a list of commands in a macro block.

.. code-block:: cmake

  endmacro([<name>])

See the :command:`macro` command.

The optional ``<name>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<name>`` argument
of the opening ``macro`` command.


code:
endwhile
--------

Ends a list of commands in a while block.

.. code-block:: cmake

  endwhile([<condition>])

See the :command:`while` command.

The optional ``<condition>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
``while`` clause.


code:
exec_program
------------

.. versionchanged:: 3.28
  This command is available only if policy :policy:`CMP0153` is not set to ``NEW``.
  Port projects to the :command:`execute_process` command.

.. deprecated:: 3.0

  Use the :command:`execute_process` command instead.

Run an executable program during the processing of the CMakeList.txt
file.

.. code-block:: cmake

  exec_program(Executable [directory in which to run]
               [ARGS <arguments to executable>]
               [OUTPUT_VARIABLE <var>]
               [RETURN_VALUE <var>])

The executable is run in the optionally specified directory.  The
executable can include arguments if it is double quoted, but it is
better to use the optional ``ARGS`` argument to specify arguments to the
program.  This is because cmake will then be able to escape spaces in
the executable path.  An optional argument ``OUTPUT_VARIABLE`` specifies a
variable in which to store the output.  To capture the return value of
the execution, provide a ``RETURN_VALUE``.  If ``OUTPUT_VARIABLE`` is
specified, then no output will go to the stdout/stderr of the console
running cmake.


code:
execute_process
---------------

Execute one or more child processes.

.. code-block:: cmake

  execute_process(COMMAND <cmd1> [<arguments>]
                  [COMMAND <cmd2> [<arguments>]]...
                  [WORKING_DIRECTORY <directory>]
                  [TIMEOUT <seconds>]
                  [RESULT_VARIABLE <variable>]
                  [RESULTS_VARIABLE <variable>]
                  [OUTPUT_VARIABLE <variable>]
                  [ERROR_VARIABLE <variable>]
                  [INPUT_FILE <file>]
                  [OUTPUT_FILE <file>]
                  [ERROR_FILE <file>]
                  [OUTPUT_QUIET]
                  [ERROR_QUIET]
                  [COMMAND_ECHO <where>]
                  [OUTPUT_STRIP_TRAILING_WHITESPACE]
                  [ERROR_STRIP_TRAILING_WHITESPACE]
                  [ENCODING <name>]
                  [ECHO_OUTPUT_VARIABLE]
                  [ECHO_ERROR_VARIABLE]
                  [COMMAND_ERROR_IS_FATAL <ANY|LAST>])

Runs the given sequence of one or more commands.

Commands are executed concurrently as a pipeline, with the standard
output of each process piped to the standard input of the next.
A single standard error pipe is used for all processes.

``execute_process`` runs commands while CMake is configuring the project,
prior to build system generation.  Use the :command:`add_custom_target` and
:command:`add_custom_command` commands to create custom commands that run
at build time.

Options:

``COMMAND``
 A child process command line.

 CMake executes the child process using operating system APIs directly:

 * On POSIX platforms, the command line is passed to the
   child process in an ``argv[]`` style array.

 * On Windows platforms, the command line is encoded as a string such
   that child processes using ``CommandLineToArgvW`` will decode the
   original arguments.

 No intermediate shell is used, so shell operators such as ``>``
 are treated as normal arguments.
 (Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to
 redirect stdin, stdout, and stderr.)

 For **sequential execution** of multiple commands use multiple
 ``execute_process`` calls each with a single ``COMMAND`` argument.

``WORKING_DIRECTORY``
 The named directory will be set as the current working directory of
 the child processes.

``TIMEOUT``
 After the specified number of seconds (fractions allowed), all unfinished
 child processes will be terminated, and the ``RESULT_VARIABLE`` will be
 set to a string mentioning the "timeout".

``RESULT_VARIABLE``
 The variable will be set to contain the result of last child process.
 This will be an integer return code from the last child or a string
 describing an error condition.

``RESULTS_VARIABLE <variable>``
 .. versionadded:: 3.10

 The variable will be set to contain the result of all processes as a
 :ref:`semicolon-separated list <CMake Language Lists>`, in order of the
 given ``COMMAND`` arguments.  Each entry will be an integer return code
 from the corresponding child or a string describing an error condition.

``INPUT_FILE <file>``
 ``<file>`` is attached to the standard input pipe of the *first* ``COMMAND``
 process.

``OUTPUT_FILE <file>``
 ``<file>`` is attached to the standard output pipe of the *last* ``COMMAND``
 process.

``ERROR_FILE <file>``
 ``<file>`` is attached to the standard error pipe of *all* ``COMMAND``
 processes.

.. versionadded:: 3.3
  If the same ``<file>`` is named for both ``OUTPUT_FILE`` and ``ERROR_FILE``
  then it will be used for both standard output and standard error pipes.

``OUTPUT_QUIET``, ``ERROR_QUIET``
 The standard output on ``OUTPUT_VARIABLE`` or standard error on
 ``ERROR_VARIABLE`` are not connected (no variable content).
 The  ``*_FILE`` and ``ECHO_*_VARIABLE`` options are not affected.

``OUTPUT_VARIABLE``, ``ERROR_VARIABLE``
 The variable named will be set with the contents of the standard output
 and standard error pipes, respectively.  If the same variable is named
 for both pipes their output will be merged in the order produced.

``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
  .. versionadded:: 3.18

  The standard output or standard error will not be exclusively redirected to
  the specified variables.

  The output will be duplicated into the specified variables and also onto
  standard output or standard error analogous to the ``tee`` Unix command.

.. note::
  If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
  same pipe the precedence is *not specified*.
  If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will
  be shared with the corresponding pipes of the CMake process itself.

``COMMAND_ECHO <where>``
 .. versionadded:: 3.15

 The command being run will be echo'ed to ``<where>`` with ``<where>``
 being set to one of ``STDERR``, ``STDOUT`` or ``NONE``.
 See the :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable for a way
 to control the default behavior when this option is not present.

``ENCODING <name>``
 .. versionadded:: 3.8

 On Windows, the encoding that is used to decode output from the process.
 Ignored on other platforms.
 Valid encoding names are:

 ``NONE``
   Perform no decoding.  This assumes that the process output is encoded
   in the same way as CMake's internal encoding (UTF-8).
   This is the default.
 ``AUTO``
   Use the current active console's codepage or if that isn't
   available then use ANSI.
 ``ANSI``
   Use the ANSI codepage.
 ``OEM``
   Use the original equipment manufacturer (OEM) code page.
 ``UTF8`` or ``UTF-8``
   Use the UTF-8 codepage.

   .. versionadded:: 3.11
     Accept ``UTF-8`` spelling for consistency with the
     `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention.

``COMMAND_ERROR_IS_FATAL <ANY|LAST>``
  .. versionadded:: 3.19

  The option following ``COMMAND_ERROR_IS_FATAL`` determines the behavior when
  an error is encountered:

    ``ANY``
    If any of the commands in the list of commands fail, the
    ``execute_process()`` command halts with an error.

    ``LAST``
    If the last command in the list of commands fails, the
    ``execute_process()`` command halts with an error.  Commands earlier in the
    list will not cause a fatal error.


code:
export
------

Export targets or packages for outside projects to use them directly
from the current project's build tree, without installation.

See the :command:`install(EXPORT)` command to export targets from an
install tree.

Synopsis
^^^^^^^^

.. parsed-literal::

  export(`TARGETS`_ <target>... [...])
  export(`EXPORT`_ <export-name> [...])
  export(`PACKAGE`_ <PackageName>)
  export(`SETUP`_ <export-name> [...])

Exporting Targets
^^^^^^^^^^^^^^^^^

.. signature::
  export(TARGETS <target>... [...])

.. code-block:: cmake

  export(TARGETS <target>... [NAMESPACE <namespace>]
         [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]
         [CXX_MODULES_DIRECTORY <directory>])

Creates a file ``<filename>`` that may be included by outside projects to
import targets named by ``<target>...`` from the current project's build tree.
This is useful during cross-compiling to build utility executables that can
run on the host platform in one project and then import them into another
project being compiled for the target platform.

The file created by this command is specific to the build tree and
should never be installed.  See the :command:`install(EXPORT)` command to
export targets from an install tree.

The options are:

``NAMESPACE <namespace>``
  Prepend the ``<namespace>`` string to all target names written to the file.

``APPEND``
  Append to the file instead of overwriting it.  This can be used to
  incrementally export multiple targets to the same file.

``EXPORT_LINK_INTERFACE_LIBRARIES``
  Include the contents of the properties named with the pattern
  ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``
  in the export, even when policy :policy:`CMP0022` is NEW.  This is useful
  to support consumers using CMake versions older than 2.8.12.

``CXX_MODULES_DIRECTORY <directory>``
  .. versionadded:: 3.28

  Export C++ module properties to files under the given directory. Each file
  will be named according to the target's export name (without any namespace).
  These files will automatically be included from the export file.

This signature requires all targets to be listed explicitly.  If a library
target is included in the export, but a target to which it links is not
included, the behavior is unspecified.  See the :command:`export(EXPORT)` signature
to automatically export the same targets from the build tree as
:command:`install(EXPORT)` would from an install tree.

.. note::

  :ref:`Object Libraries` under :generator:`Xcode` have special handling if
  multiple architectures are listed in :variable:`CMAKE_OSX_ARCHITECTURES`.
  In this case they will be exported as :ref:`Interface Libraries` with
  no object files available to clients.  This is sufficient to satisfy
  transitive usage requirements of other targets that link to the
  object libraries in their implementation.

This command exports all :ref:`build configurations` from the build tree.
See the :variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` variable to map
configurations of dependent projects to the exported configurations.

Exporting Targets to Android.mk
"""""""""""""""""""""""""""""""

.. code-block:: cmake

  export(TARGETS <target>... ANDROID_MK <filename>)

.. versionadded:: 3.7

This signature exports cmake built targets to the android ndk build system
by creating an ``Android.mk`` file that references the prebuilt targets. The
Android NDK supports the use of prebuilt libraries, both static and shared.
This allows cmake to build the libraries of a project and make them available
to an ndk build system complete with transitive dependencies, include flags
and defines required to use the libraries. The signature takes a list of
targets and puts them in the ``Android.mk`` file specified by the
``<filename>`` given. This signature can only be used if policy
:policy:`CMP0022` is NEW for all targets given. A error will be issued if
that policy is set to OLD for one of the targets.

Exporting Targets matching install(EXPORT)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. signature::
  export(EXPORT <export-name> [...])

.. code-block:: cmake

  export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]
         [CXX_MODULES_DIRECTORY <directory>] [EXPORT_PACKAGE_DEPENDENCIES])

Creates a file ``<filename>`` that may be included by outside projects to
import targets from the current project's build tree.  This is the same
as the :command:`export(TARGETS)` signature, except that the targets are not
explicitly listed.  Instead, it exports the targets associated with
the installation export ``<export-name>``.  Target installations may be
associated with the export ``<export-name>`` using the ``EXPORT`` option
of the :command:`install(TARGETS)` command.

``EXPORT_PACKAGE_DEPENDENCIES``
  .. versionadded:: 3.29

  Specify that :command:`find_dependency` calls should be exported. See
  :command:`install(EXPORT)` for details on how this works.

Exporting Packages
^^^^^^^^^^^^^^^^^^

.. signature::
  export(PACKAGE <PackageName>)

.. code-block:: cmake

  export(PACKAGE <PackageName>)

Store the current build directory in the CMake user package registry
for package ``<PackageName>``.  The :command:`find_package` command may consider the
directory while searching for package ``<PackageName>``.  This helps dependent
projects find and use a package from the current project's build tree
without help from the user.  Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (``<PackageName>Config.cmake``) that works with the
build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package
registry.

.. versionchanged:: 3.1
  If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable
  is enabled, the ``export(PACKAGE)`` command will do nothing.

.. versionchanged:: 3.15
  By default the ``export(PACKAGE)`` command does nothing (see policy
  :policy:`CMP0090`) because populating the user package registry has effects
  outside the source and build trees.  Set the
  :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories
  to the CMake user package registry.

Configuring Exports
^^^^^^^^^^^^^^^^^^^

.. signature::
  export(SETUP <export-name> [...])

.. code-block:: cmake

  export(SETUP <export-name>
         [PACKAGE_DEPENDENCY <dep>
          [ENABLED (<bool-true>|<bool-false>|AUTO)]
          [EXTRA_ARGS <args>...]
         ] [...]
         [TARGET <target>
          [XCFRAMEWORK_LOCATION <location>]
         ] [...]
         )

.. versionadded:: 3.29

Configure the parameters of an export. The arguments are as follows:

``PACKAGE_DEPENDENCY <dep>``
  Specify a package dependency to configure. This changes how
  :command:`find_dependency` calls are written during
  :command:`export(EXPORT)` and :command:`install(EXPORT)`. ``<dep>`` is the
  name of a package to export. This argument accepts the following additional
  arguments:

  ``ENABLED``
    Manually control whether or not the dependency is exported. This accepts
    the following values:

    ``<bool-true>``
      Any value that CMake recognizes as "true". Always export the dependency,
      even if no exported targets depend on it. This can be used to manually
      add :command:`find_dependency` calls to the export.

    ``<bool-false>``
      Any value that CMake recognizes as "false". Never export the dependency,
      even if an exported target depends on it.

    ``AUTO``
      Only export the dependency if an exported target depends on it.

  ``EXTRA_ARGS <args>``
    Specify additional arguments to pass to :command:`find_dependency` after
    the ``REQUIRED`` argument.

``TARGET <target>``
  Specify a target to configure in this export. This argument accepts the
  following additional arguments:

  ``XCFRAMEWORK_LOCATION``
    Specify the location of an ``.xcframework`` which contains the library from
    this target. If specified, the generated code will check to see if the
    ``.xcframework`` exists, and if it does, it will use the ``.xcframework``
    as its imported location instead of the installed library.


code:
export_library_dependencies
---------------------------

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

Use :command:`install(EXPORT)` or :command:`export` command.

This command generates an old-style library dependencies file.
Projects requiring CMake 2.6 or later should not use the command.  Use
instead the :command:`install(EXPORT)` command to help export targets from an
installation tree and the :command:`export` command to export targets from a
build tree.

The old-style library dependencies file does not take into account
per-configuration names of libraries or the
:prop_tgt:`LINK_INTERFACE_LIBRARIES` target property.

.. code-block:: cmake

  export_library_dependencies(<file> [APPEND])

Create a file named ``<file>`` that can be included into a CMake listfile
with the INCLUDE command.  The file will contain a number of SET
commands that will set all the variables needed for library dependency
information.  This should be the last command in the top level
CMakeLists.txt file of the project.  If the ``APPEND`` option is
specified, the SET commands will be appended to the given file instead
of replacing it.