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.

repo_name: lazytadpole/codenamesilverfish

license: mit


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.


code:
file
----

File manipulation command.

This command is dedicated to file and path manipulation requiring access to the
filesystem.

For other path manipulation, handling only syntactic aspects, have a look at
:command:`cmake_path` command.

.. note::

  The sub-commands `RELATIVE_PATH`_, `TO_CMAKE_PATH`_ and `TO_NATIVE_PATH`_ has
  been superseded, respectively, by sub-commands
  :ref:`RELATIVE_PATH <cmake_path-RELATIVE_PATH>`,
  :ref:`CONVERT ... TO_CMAKE_PATH_LIST <cmake_path-TO_CMAKE_PATH_LIST>` and
  :ref:`CONVERT ... TO_NATIVE_PATH_LIST <cmake_path-TO_NATIVE_PATH_LIST>` of
  :command:`cmake_path` command.

Synopsis
^^^^^^^^

.. parsed-literal::

  `Reading`_
    file(`READ`_ <filename> <out-var> [...])
    file(`STRINGS`_ <filename> <out-var> [...])
    file(`\<HASH\>`_ <filename> <out-var>)
    file(`TIMESTAMP`_ <filename> <out-var> [...])
    file(`GET_RUNTIME_DEPENDENCIES`_ [...])

  `Writing`_
    file({`WRITE`_ | `APPEND`_} <filename> <content>...)
    file({`TOUCH`_ | `TOUCH_NOCREATE`_} <file>...)
    file(`GENERATE`_ OUTPUT <output-file> [...])
    file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...])

  `Filesystem`_
    file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] <globbing-expr>...)
    file(`MAKE_DIRECTORY`_ <directories>...)
    file({`REMOVE`_ | `REMOVE_RECURSE`_ } <files>...)
    file(`RENAME`_ <oldname> <newname> [...])
    file(`COPY_FILE`_ <oldname> <newname> [...])
    file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
    file(`SIZE`_ <filename> <out-var>)
    file(`READ_SYMLINK`_ <linkname> <out-var>)
    file(`CREATE_LINK`_ <original> <linkname> [...])
    file(`CHMOD`_ <files>... <directories>... PERMISSIONS <permissions>... [...])
    file(`CHMOD_RECURSE`_ <files>... <directories>... PERMISSIONS <permissions>... [...])

  `Path Conversion`_
    file(`REAL_PATH`_ <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
    file(`RELATIVE_PATH`_ <out-var> <directory> <file>)
    file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>)

  `Transfer`_
    file(`DOWNLOAD`_ <url> [<file>] [...])
    file(`UPLOAD`_ <file> <url> [...])

  `Locking`_
    file(`LOCK`_ <path> [...])

  `Archiving`_
    file(`ARCHIVE_CREATE`_ OUTPUT <archive> PATHS <paths>... [...])
    file(`ARCHIVE_EXTRACT`_ INPUT <archive> [...])

Reading
^^^^^^^

.. signature::
  file(READ <filename> <variable>
       [OFFSET <offset>] [LIMIT <max-in>] [HEX])

  Read content from a file called ``<filename>`` and store it in a
  ``<variable>``.  Optionally start from the given ``<offset>`` and
  read at most ``<max-in>`` bytes.  The ``HEX`` option causes data to
  be converted to a hexadecimal representation (useful for binary data).
  If the ``HEX`` option is specified, letters in the output
  (``a`` through ``f``) are in lowercase.

.. signature::
  file(STRINGS <filename> <variable> <options>...)

  Parse a list of ASCII strings from ``<filename>`` and store it in
  ``<variable>``.  Binary data in the file are ignored.  Carriage return
  (``\r``, CR) characters are ignored.  The options are:

    ``LENGTH_MAXIMUM <max-len>``
      Consider only strings of at most a given length.

    ``LENGTH_MINIMUM <min-len>``
      Consider only strings of at least a given length.

    ``LIMIT_COUNT <max-num>``
      Limit the number of distinct strings to be extracted.

    ``LIMIT_INPUT <max-in>``
      Limit the number of input bytes to read from the file.

    ``LIMIT_OUTPUT <max-out>``
      Limit the number of total bytes to store in the ``<variable>``.

    ``NEWLINE_CONSUME``
      Treat newline characters (``\n``, LF) as part of string content
      instead of terminating at them.

    ``NO_HEX_CONVERSION``
      Intel Hex and Motorola S-record files are automatically converted to
      binary while reading unless this option is given.

    ``REGEX <regex>``
      Consider only strings that match the given regular expression,
      as described under :ref:`string(REGEX) <Regex Specification>`.

      .. versionchanged:: 3.29
        Capture groups from the last match in the file are stored in
        :variable:`CMAKE_MATCH_<n>`, similar to
        :command:`string(REGEX MATCHALL)`.  See policy :policy:`CMP0159`.

    ``ENCODING <encoding-type>``
      .. versionadded:: 3.1

      Consider strings of a given encoding.  Currently supported encodings are:
      ``UTF-8``, ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE``.
      If the ``ENCODING`` option is not provided and the file
      has a Byte Order Mark, the ``ENCODING`` option will be defaulted
      to respect the Byte Order Mark.

  .. versionadded:: 3.2
    Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings.

  For example, the code

  .. code-block:: cmake

    file(STRINGS myfile.txt myfile)

  stores a list in the variable ``myfile`` in which each item is a line
  from the input file.

.. signature::
  file(<HASH> <filename> <variable>)
  :target: <HASH>

  Compute a cryptographic hash of the content of ``<filename>`` and
  store it in a ``<variable>``.  The supported ``<HASH>`` algorithm names
  are those listed by the :command:`string(<HASH>)` command.

.. signature::
  file(TIMESTAMP <filename> <variable> [<format>] [UTC])

  Compute a string representation of the modification time of ``<filename>``
  and store it in ``<variable>``.  Should the command be unable to obtain a
  timestamp variable will be set to the empty string ("").

  See the :command:`string(TIMESTAMP)` command for documentation of
  the ``<format>`` and ``UTC`` options.

.. signature::
  file(GET_RUNTIME_DEPENDENCIES [...])

  .. versionadded:: 3.16

  Recursively get the list of libraries depended on by the given files:

  .. code-block:: cmake

    file(GET_RUNTIME_DEPENDENCIES
      [RESOLVED_DEPENDENCIES_VAR <deps_var>]
      [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
      [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
      [EXECUTABLES <executable_files>...]
      [LIBRARIES <library_files>...]
      [MODULES <module_files>...]
      [DIRECTORIES <directories>...]
      [BUNDLE_EXECUTABLE <bundle_executable_file>]
      [PRE_INCLUDE_REGEXES <regexes>...]
      [PRE_EXCLUDE_REGEXES <regexes>...]
      [POST_INCLUDE_REGEXES <regexes>...]
      [POST_EXCLUDE_REGEXES <regexes>...]
      [POST_INCLUDE_FILES <files>...]
      [POST_EXCLUDE_FILES <files>...]
      )

  Please note that this sub-command is not intended to be used in project mode.
  It is intended for use at install time, either from code generated by the
  :command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by
  the project via :command:`install(CODE)` or :command:`install(SCRIPT)`.
  For example:

  .. code-block:: cmake

    install(CODE [[
      file(GET_RUNTIME_DEPENDENCIES
        # ...
        )
      ]])

  The arguments are as follows:

    ``RESOLVED_DEPENDENCIES_VAR <deps_var>``
      Name of the variable in which to store the list of resolved dependencies.

    ``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>``
      Name of the variable in which to store the list of unresolved
      dependencies. If this variable is not specified, and there are any
      unresolved dependencies, an error is issued.

    ``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>``
      Variable prefix in which to store conflicting dependency information.
      Dependencies are conflicting if two files with the same name are found in
      two different directories. The list of filenames that conflict are stored
      in ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list
      of paths that were found for that filename are stored in
      ``<conflicting_deps_prefix>_<filename>``.

    ``EXECUTABLES <executable_files>...``
      List of executable files to read for dependencies. These are executables
      that are typically created with :command:`add_executable`, but they do
      not have to be created by CMake. On Apple platforms, the paths to these
      files determine the value of ``@executable_path`` when recursively
      resolving the libraries. Specifying any kind of library (``STATIC``,
      ``MODULE``, or ``SHARED``) here will result in undefined behavior.

    ``LIBRARIES <library_files>...``
      List of library files to read for dependencies. These are libraries that
      are typically created with :command:`add_library(SHARED)`, but they do
      not have to be created by CMake. Specifying ``STATIC`` libraries,
      ``MODULE`` libraries, or executables here will result in undefined
      behavior.

    ``MODULES <module_files>...``
      List of loadable module files to read for dependencies. These are modules
      that are typically created with :command:`add_library(MODULE)`, but they
      do not have to be created by CMake. They are typically used by calling
      ``dlopen()`` at runtime rather than linked at link time with ``ld -l``.
      Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables
      here will result in undefined behavior.

    ``DIRECTORIES <directories>...``
      List of additional directories to search for dependencies. On Linux
      platforms, these directories are searched if the dependency is not found
      in any of the other usual paths. If it is found in such a directory, a
      warning is issued, because it means that the file is incomplete (it does
      not list all of the directories that contain its dependencies).
      On Windows platforms, these directories are searched if the dependency
      is not found in any of the other search paths, but no warning is issued,
      because searching other paths is a normal part of Windows dependency
      resolution. On Apple platforms, this argument has no effect.

    ``BUNDLE_EXECUTABLE <bundle_executable_file>``
      Executable to treat as the "bundle executable" when resolving libraries.
      On Apple platforms, this argument determines the value of
      ``@executable_path`` when recursively resolving libraries for
      ``LIBRARIES`` and ``MODULES`` files. It has no effect on ``EXECUTABLES``
      files. On other platforms, it has no effect. This is typically (but not
      always) one of the executables in the ``EXECUTABLES`` argument which
      designates the "main" executable of the package.

  The following arguments specify filters for including or excluding libraries
  to be resolved. See below for a full description of how they work.

    ``PRE_INCLUDE_REGEXES <regexes>...``
      List of pre-include regexes through which to filter the names of
      not-yet-resolved dependencies.

    ``PRE_EXCLUDE_REGEXES <regexes>...``
      List of pre-exclude regexes through which to filter the names of
      not-yet-resolved dependencies.

    ``POST_INCLUDE_REGEXES <regexes>...``
      List of post-include regexes through which to filter the names of
      resolved dependencies.

    ``POST_EXCLUDE_REGEXES <regexes>...``
      List of post-exclude regexes through which to filter the names of
      resolved dependencies.

    ``POST_INCLUDE_FILES <files>...``
      .. versionadded:: 3.21

      List of post-include filenames through which to filter the names of
      resolved dependencies. Symlinks are resolved when attempting to match
      these filenames.

    ``POST_EXCLUDE_FILES <files>...``
      .. versionadded:: 3.21

      List of post-exclude filenames through which to filter the names of
      resolved dependencies. Symlinks are resolved when attempting to match
      these filenames.

  These arguments can be used to exclude unwanted system libraries when
  resolving the dependencies, or to include libraries from a specific
  directory. The filtering works as follows:

  1. If the not-yet-resolved dependency matches any of the
     ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency
     resolution proceeds to step 4.

  2. If the not-yet-resolved dependency matches any of the
     ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency.

  3. Otherwise, dependency resolution proceeds.

  4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according
     to the linking rules of the platform (see below).

  5. If the dependency is found, and its full path matches one of the
     ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added
     to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)``
     recursively resolves that library's own dependencies. Otherwise, resolution
     proceeds to step 6.

  6. If the dependency is found, but its full path matches one of the
     ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the
     resolved dependencies, and dependency resolution stops for that dependency.

  7. If the dependency is found, and its full path does not match either
     ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``,
     or ``POST_EXCLUDE_FILES``, the full path is added to the resolved
     dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)``  recursively resolves
     that library's own dependencies.

  Different platforms have different rules for how dependencies are resolved.
  These specifics are described here.

  On Linux platforms, library resolution works as follows:

  1. If the depending file does not have any ``RUNPATH`` entries, and the
     library exists in one of the depending file's ``RPATH`` entries, or its
     parents', in that order, the dependency is resolved to that file.
  2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the
     library exists in one of those entries, the dependency is resolved to that
     file.
  3. Otherwise, if the library exists in one of the directories listed by
     ``ldconfig``, the dependency is resolved to that file.
  4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries,
     the dependency is resolved to that file. In this case, a warning is
     issued, because finding a file in one of the ``DIRECTORIES`` means that
     the depending file is not complete (it does not list all the directories
     from which it pulls dependencies).

  5. Otherwise, the dependency is unresolved.

  On Windows platforms, library resolution works as follows:

  1. DLL dependency names are converted to lowercase for matching filters.
     Windows DLL names are case-insensitive, and some linkers mangle the
     case of the DLL dependency names.  However, this makes it more difficult
     for ``PRE_INCLUDE_REGEXES``, ``PRE_EXCLUDE_REGEXES``,
     ``POST_INCLUDE_REGEXES``, and ``POST_EXCLUDE_REGEXES`` to properly
     filter DLL names - every regex would have to check for both uppercase
     and lowercase letters.  For example:

     .. code-block:: cmake

       file(GET_RUNTIME_DEPENDENCIES
         # ...
         PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
         )

     Converting the DLL name to lowercase allows the regexes to only match
     lowercase names, thus simplifying the regex. For example:

     .. code-block:: cmake

       file(GET_RUNTIME_DEPENDENCIES
         # ...
         PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
         )

     This regex will match ``mylibrary.dll`` regardless of how it is cased,
     either on disk or in the depending file. (For example, it will match
     ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.)

     .. versionchanged:: 3.27

       The conversion to lowercase only applies while matching filters.
       Results reported after filtering case-preserve each DLL name as it is
       found on disk, if resolved, and otherwise as it is referenced by the
       dependent binary.

       Prior to CMake 3.27, the results were reported with lowercase DLL
       file names, but the directory portion retained its casing.

  2. (**Not yet implemented**) If the depending file is a Windows Store app,
     and the dependency is listed as a dependency in the application's package
     manifest, the dependency is resolved to that file.

  3. Otherwise, if the library exists in the same directory as the depending
     file, the dependency is resolved to that file.

  4. Otherwise, if the library exists in either the operating system's
     ``system32`` directory or the ``Windows`` directory, in that order, the
     dependency is resolved to that file.

  5. Otherwise, if the library exists in one of the directories specified by
     ``DIRECTORIES``, in the order they are listed, the dependency is resolved
     to that file. In this case, a warning is not issued, because searching
     other directories is a normal part of Windows library resolution.

  6. Otherwise, the dependency is unresolved.

  On Apple platforms, library resolution works as follows:

  1. If the dependency starts with ``@executable_path/``, and an
     ``EXECUTABLES`` argument is in the process of being resolved, and
     replacing ``@executable_path/`` with the directory of the executable
     yields an existing file, the dependency is resolved to that file.

  2. Otherwise, if the dependency starts with ``@executable_path/``, and there
     is a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/``
     with the directory of the bundle executable yields an existing file, the
     dependency is resolved to that file.

  3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing
     ``@loader_path/`` with the directory of the depending file yields an
     existing file, the dependency is resolved to that file.

  4. Otherwise, if the dependency starts with ``@rpath/``, and replacing
     ``@rpath/`` with one of the ``RPATH`` entries of the depending file
     yields an existing file, the dependency is resolved to that file.
     Note that ``RPATH`` entries that start with ``@executable_path/`` or
     ``@loader_path/`` also have these items replaced with the appropriate
     path.

  5. Otherwise, if the dependency is an absolute file that exists,
     the dependency is resolved to that file.

  6. Otherwise, the dependency is unresolved.

  This function accepts several variables that determine which tool is used for
  dependency resolution:

  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM

    Determines which operating system and executable format the files are built
    for. This could be one of several values:

    * ``linux+elf``
    * ``windows+pe``
    * ``macos+macho``

    If this variable is not specified, it is determined automatically by system
    introspection.

  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL

    Determines the tool to use for dependency resolution. It could be one of
    several values, depending on the value of
    :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`:

    ================================================= =============================================
       ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM``       ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL``
    ================================================= =============================================
    ``linux+elf``                                     ``objdump``
    ``windows+pe``                                    ``objdump`` or ``dumpbin``
    ``macos+macho``                                   ``otool``
    ================================================= =============================================

    If this variable is not specified, it is determined automatically by system
    introspection.

  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND

    Determines the path to the tool to use for dependency resolution. This is
    the actual path to ``objdump``, ``dumpbin``, or ``otool``.

    If this variable is not specified, it is determined by the value of
    ``CMAKE_OBJDUMP`` if set, else by system introspection.

    .. versionadded:: 3.18
      Use ``CMAKE_OBJDUMP`` if set.

Writing
^^^^^^^

.. signature::
  file(WRITE <filename> <content>...)
  file(APPEND <filename> <content>...)

  Write ``<content>`` into a file called ``<filename>``.  If the file does
  not exist, it will be created.  If the file already exists, ``WRITE``
  mode will overwrite it and ``APPEND`` mode will append to the end.
  Any directories in the path specified by ``<filename>`` that do not
  exist will be created.

  If the file is a build input, use the :command:`configure_file` command
  to update the file only when its content changes.

.. signature::
  file(TOUCH <files>...)
  file(TOUCH_NOCREATE <files>...)

  .. versionadded:: 3.12

  Create a file with no content if it does not yet exist. If the file already
  exists, its access and/or modification will be updated to the time when the
  function call is executed.

  Use ``TOUCH_NOCREATE`` to touch a file if it exists but not create it.
  If a file does not exist it will be silently ignored.

  With ``TOUCH`` and ``TOUCH_NOCREATE``, the contents of an existing file
  will not be modified.

.. signature::
  file(GENERATE [...])

  Generate an output file for each build configuration supported by the current
  :manual:`CMake Generator <cmake-generators(7)>`.  Evaluate
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  from the input content to produce the output content.

  .. code-block:: cmake

    file(GENERATE OUTPUT <output-file>
         <INPUT <input-file>|CONTENT <content>>
         [CONDITION <expression>] [TARGET <target>]
         [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
          FILE_PERMISSIONS <permissions>...]
         [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

  The options are:

    ``CONDITION <condition>``
      Generate the output file for a particular configuration only if
      the condition is true.  The condition must be either ``0`` or ``1``
      after evaluating generator expressions.

    ``CONTENT <content>``
      Use the content given explicitly as input.

    ``INPUT <input-file>``
      Use the content from a given file as input.

      .. versionchanged:: 3.10
        A relative path is treated with respect to the value of
        :variable:`CMAKE_CURRENT_SOURCE_DIR`.  See policy :policy:`CMP0070`.

    ``OUTPUT <output-file>``
      Specify the output file name to generate.  Use generator expressions
      such as :genex:`$<CONFIG>` to specify a configuration-specific
      output file name.  Multiple configurations may generate the same output
      file only if the generated content is identical.  Otherwise, the
      ``<output-file>`` must evaluate to an unique name for each configuration.

      .. versionchanged:: 3.10
        A relative path (after evaluating generator expressions) is treated
        with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
        See policy :policy:`CMP0070`.

    ``TARGET <target>``
      .. versionadded:: 3.19

      Specify which target to use when evaluating generator expressions that
      require a target for evaluation (e.g.
      :genex:`$<COMPILE_FEATURES:...>`,
      :genex:`$<TARGET_PROPERTY:prop>`).

    ``NO_SOURCE_PERMISSIONS``
      .. versionadded:: 3.20

      The generated file permissions default to the standard 644 value
      (-rw-r--r--).

    ``USE_SOURCE_PERMISSIONS``
      .. versionadded:: 3.20

      Transfer the file permissions of the ``INPUT`` file to the generated
      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. It is an error to
      specify this option without ``INPUT``.

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

      Use the specified permissions for the generated file.

    ``NEWLINE_STYLE <style>``
      .. versionadded:: 3.20

      Specify the newline style for the generated file.  Specify
      ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
      ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.

  Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
  ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
  Generated files are modified and their timestamp updated on subsequent cmake
  runs only if their content is changed.

  Note also that ``file(GENERATE)`` does not create the output file until the
  generation phase. The output file will not yet have been written when the
  ``file(GENERATE)`` command returns, it is written only after processing all
  of a project's ``CMakeLists.txt`` files.

.. signature::
  file(CONFIGURE OUTPUT <output-file>
       CONTENT <content>
       [ESCAPE_QUOTES] [@ONLY]
       [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
  :target: CONFIGURE

  .. versionadded:: 3.18

  Generate an output file using the input given by ``CONTENT`` and substitute
  variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The
  substitution rules behave the same as the :command:`configure_file` command.
  In order to match :command:`configure_file`'s behavior, generator expressions
  are not supported for both ``OUTPUT`` and ``CONTENT``.

  The arguments are:

    ``OUTPUT <output-file>``
      Specify the output file name to generate. A relative path is treated with
      respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
      ``<output-file>`` does not support generator expressions.

    ``CONTENT <content>``
      Use the content given explicitly as input.
      ``<content>`` does not support generator expressions.

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

Filesystem
^^^^^^^^^^

.. signature::
  file(GLOB <variable>
       [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
       <globbing-expressions>...)
  file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
       [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
       <globbing-expressions>...)

  Generate a list of files that match the ``<globbing-expressions>`` and
  store it into the ``<variable>``.  Globbing expressions are similar to
  regular expressions, but much simpler.  If ``RELATIVE`` flag is
  specified, the results will be returned as relative paths to the given
  path.

  .. versionchanged:: 3.6
    The results will be ordered lexicographically.

  On Windows and macOS, globbing is case-insensitive even if the underlying
  filesystem is case-sensitive (both filenames and globbing expressions are
  converted to lowercase before matching).  On other platforms, globbing is
  case-sensitive.

  .. versionadded:: 3.3
    By default ``GLOB`` lists directories. Directories are omitted in the
    result if ``LIST_DIRECTORIES`` is set to false.

  .. versionadded:: 3.12
    If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic
    to the main build system check target to rerun the flagged ``GLOB``
    commands at build time. If any of the outputs change, CMake will regenerate
    the build system.

  .. note::
    We do not recommend using GLOB to collect a list of source files from
    your source tree.  If no CMakeLists.txt file changes when a source is
    added or removed then the generated build system cannot know when to
    ask CMake to regenerate.
    The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or
    if a new generator is added in the future that cannot support it, projects
    using it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there
    is still a cost to perform the check on every rebuild.

  Examples of globbing expressions include:

  ============== ======================================================
  ``*.cxx``      match all files with extension ``cxx``
  ``*.vt?``      match all files with extension ``vta``, ..., ``vtz``
  ``f[3-5].txt`` match files ``f3.txt``, ``f4.txt``, ``f5.txt``
  ============== ======================================================

  The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the
  matched directory and match the files.  Subdirectories that are symlinks
  are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
  :policy:`CMP0009` is not set to ``NEW``.

  .. versionadded:: 3.3
    By default ``GLOB_RECURSE`` omits directories from result list. Setting
    ``LIST_DIRECTORIES`` to true adds directories to result list.
    If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to
    ``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories.

  Examples of recursive globbing include:

  ============== ======================================================
  ``/dir/*.py``  match all python files in ``/dir`` and subdirectories
  ============== ======================================================

.. signature::
  file(MAKE_DIRECTORY <directories>...)

  Create the given directories and their parents as needed.

.. signature::
  file(REMOVE <files>...)
  file(REMOVE_RECURSE <files>...)

  Remove the given files.  The ``REMOVE_RECURSE`` mode will remove the given
  files and directories, including non-empty directories. No error is emitted
  if a given file does not exist.  Relative input paths are evaluated with
  respect to the current source directory.

  .. versionchanged:: 3.15
    Empty input paths are ignored with a warning.  Previous versions of CMake
    interpreted empty strings as a relative path with respect to the current
    directory and removed its contents.

.. signature::
  file(RENAME <oldname> <newname> [RESULT <result>] [NO_REPLACE])

  Move a file or directory within a filesystem from ``<oldname>`` to
  ``<newname>``, replacing the destination atomically.

  The options are:

    ``RESULT <result>``
      .. versionadded:: 3.21

      Set ``<result>`` variable to ``0`` on success or an error message
      otherwise. If ``RESULT`` is not specified and the operation fails,
      an error is emitted.

    ``NO_REPLACE``
      .. versionadded:: 3.21

      If the ``<newname>`` path already exists, do not replace it.
      If ``RESULT <result>`` is used, the result variable will be
      set to ``NO_REPLACE``.  Otherwise, an error is emitted.

.. signature::
  file(COPY_FILE <oldname> <newname>
       [RESULT <result>]
       [ONLY_IF_DIFFERENT]
       [INPUT_MAY_BE_RECENT])

  .. versionadded:: 3.21

  Copy a file from ``<oldname>`` to ``<newname>``. Directories are not
  supported. Symlinks are ignored and ``<oldfile>``'s content is read and
  written to ``<newname>`` as a new file.

  The options are:

    ``RESULT <result>``
      Set ``<result>`` variable to ``0`` on success or an error message
      otherwise.  If ``RESULT`` is not specified and the operation fails,
      an error is emitted.

    ``ONLY_IF_DIFFERENT``
      If the ``<newname>`` path already exists, do not replace it if the file's
      contents are already the same as ``<oldname>`` (this avoids updating
      ``<newname>``'s timestamp).

    ``INPUT_MAY_BE_RECENT``
      .. versionadded:: 3.26

      Tell CMake that the input file may have been recently created.  This is
      meaningful only on Windows, where files may be inaccessible for a short
      time after they are created.  With this option, if permission is denied,
      CMake will retry reading the input a few times.

  This sub-command has some similarities to :command:`configure_file`
  with the ``COPYONLY`` option.  An important difference is that
  :command:`configure_file` creates a dependency on the source file,
  so CMake will be re-run if it changes. The ``file(COPY_FILE)``
  sub-command does not create such a dependency.

  See also the :command:`file(COPY)` sub-command just below which provides
  further file-copying capabilities.

.. signature::
  file(COPY [...])
  file(INSTALL [...])

  The ``COPY`` signature copies files, directories, and symlinks to a
  destination folder.  Relative input paths are evaluated with respect
  to the current source directory, and a relative destination is
  evaluated with respect to the current build directory.  Copying
  preserves input file timestamps, and optimizes out a file if it exists
  at the destination with the same timestamp.  Copying preserves input
  permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
  are given (default is ``USE_SOURCE_PERMISSIONS``).

  .. code-block:: cmake

    file(<COPY|INSTALL> <files>... DESTINATION <dir>
         [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
         [FILE_PERMISSIONS <permissions>...]
         [DIRECTORY_PERMISSIONS <permissions>...]
         [FOLLOW_SYMLINK_CHAIN]
         [FILES_MATCHING]
         [[PATTERN <pattern> | REGEX <regex>]
          [EXCLUDE] [PERMISSIONS <permissions>...]] [...])

  .. note::

    For a simple file copying operation, the :command:`file(COPY_FILE)`
    sub-command just above may be easier to use.

  .. versionadded:: 3.15
    If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve
    the symlinks at the paths given until a real file is found, and install
    a corresponding symlink in the destination for each symlink encountered.
    For each symlink that is installed, the resolution is stripped of the
    directory, leaving only the filename, meaning that the new symlink points
    to a file in the same directory as the symlink. This feature is useful on
    some Unix systems, where libraries are installed as a chain of symlinks
    with version numbers, with less specific versions pointing to more specific
    versions. ``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and
    the library itself into the destination directory. For example, if you have
    the following directory structure:

      * ``/opt/foo/lib/libfoo.so.1.2.3``
      * ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3``
      * ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2``
      * ``/opt/foo/lib/libfoo.so -> libfoo.so.1``

    and you do:

    .. code-block:: cmake

      file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)

    This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into
    ``lib``.

  See the :command:`install(DIRECTORY)` command for documentation of
  permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
  ``EXCLUDE`` options.  Copying directories preserves the structure
  of their content even if options are used to select a subset of
  files.

  The ``INSTALL`` signature differs slightly from ``COPY``: it prints
  status messages, and ``NO_SOURCE_PERMISSIONS`` is default. Installation
  scripts generated by the :command:`install` command use this signature
  (with some undocumented options for internal use).

  .. versionchanged:: 3.22

    The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
    default copying behavior of :command:`file(INSTALL)`.

.. signature::
  file(SIZE <filename> <variable>)

  .. versionadded:: 3.14

  Determine the file size of the ``<filename>`` and put the result in
  ``<variable>`` variable. Requires that ``<filename>`` is a valid path
  pointing to a file and is readable.

.. signature::
  file(READ_SYMLINK <linkname> <variable>)

  .. versionadded:: 3.14

  Query the symlink ``<linkname>`` and stores the path it points to
  in the result ``<variable>``.  If ``<linkname>`` does not exist
  or is not a symlink, CMake issues a fatal error.

  Note that this command returns the raw symlink path and does not resolve
  a relative path.  The following is an example of how to ensure that an
  absolute path is obtained:

  .. code-block:: cmake

    set(linkname "/path/to/foo.sym")
    file(READ_SYMLINK "${linkname}" result)
    if(NOT IS_ABSOLUTE "${result}")
      get_filename_component(dir "${linkname}" DIRECTORY)
      set(result "${dir}/${result}")
    endif()

.. signature::
  file(CREATE_LINK <original> <linkname>
       [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])

  .. versionadded:: 3.14

  Create a link ``<linkname>`` that points to ``<original>``.
  It will be a hard link by default, but providing the ``SYMBOLIC`` option
  results in a symbolic link instead.  Hard links require that ``original``
  exists and is a file, not a directory.  If ``<linkname>`` already exists,
  it will be overwritten.

  The ``<result>`` variable, if specified, receives the status of the
  operation.  It is set to ``0`` upon success or an error message otherwise.
  If ``RESULT`` is not specified and the operation fails, a fatal error is
  emitted.

  Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if
  creating the link fails.  It can be useful for handling situations such as
  ``<original>`` and ``<linkname>`` being on different drives or mount points,
  which would make them unable to support a hard link.

.. signature::
  file(CHMOD <files>... <directories>...
       [PERMISSIONS <permissions>...]
       [FILE_PERMISSIONS <permissions>...]
       [DIRECTORY_PERMISSIONS <permissions>...])

  .. versionadded:: 3.19

  Set the permissions for the ``<files>...`` and ``<directories>...``
  specified. Valid permissions are  ``OWNER_READ``, ``OWNER_WRITE``,
  ``OWNER_EXECUTE``, ``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``,
  ``WORLD_READ``, ``WORLD_WRITE``, ``WORLD_EXECUTE``, ``SETUID``, ``SETGID``.

  Valid combination of keywords are:

    ``PERMISSIONS``
      All items are changed.

    ``FILE_PERMISSIONS``
      Only files are changed.

    ``DIRECTORY_PERMISSIONS``
      Only directories are changed.

    ``PERMISSIONS`` and ``FILE_PERMISSIONS``
      ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files.

    ``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
      ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories.

    ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
      Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for
      directories.

.. signature::
  file(CHMOD_RECURSE <files>... <directories>...
       [PERMISSIONS <permissions>...]
       [FILE_PERMISSIONS <permissions>...]
       [DIRECTORY_PERMISSIONS <permissions>...])

  .. versionadded:: 3.19

  Same as :cref:`CHMOD`, but change the permissions of files and directories
  present in the ``<directories>...`` recursively.

Path Conversion
^^^^^^^^^^^^^^^

.. signature::
  file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])

  .. versionadded:: 3.19

  Compute the absolute path to an existing file or directory with symlinks
  resolved.  The options are:

    ``BASE_DIRECTORY <dir>``
      If the provided ``<path>`` is a relative path, it is evaluated relative
      to the given base directory ``<dir>``. If no base directory is provided,
      the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`.

    ``EXPAND_TILDE``
      .. versionadded:: 3.21

      If the ``<path>`` is ``~`` or starts with ``~/``, the ``~`` is replaced
      by the user's home directory.  The path to the home directory is obtained
      from environment variables.  On Windows, the ``USERPROFILE`` environment
      variable is used, falling back to the ``HOME`` environment variable
      if ``USERPROFILE`` is not defined.  On all other platforms, only ``HOME``
      is used.

  .. versionchanged:: 3.28

    All symlinks are resolved before collapsing ``../`` components.
    See policy :policy:`CMP0152`.

.. signature::
  file(RELATIVE_PATH <variable> <directory> <file>)

  Compute the relative path from a ``<directory>`` to a ``<file>`` and
  store it in the ``<variable>``.

.. signature::
  file(TO_CMAKE_PATH "<path>" <variable>)
  file(TO_NATIVE_PATH "<path>" <variable>)

  The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style
  path with forward-slashes (``/``).  The input can be a single path or a
  system search path like ``$ENV{PATH}``.  A search path will be converted
  to a cmake-style list separated by ``;`` characters.

  The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
  path with platform-specific slashes (``\`` on Windows hosts and ``/``
  elsewhere).

  Always use double quotes around the ``<path>`` to be sure it is treated
  as a single argument to this command.

Transfer
^^^^^^^^

.. signature::
  file(DOWNLOAD <url> [<file>] <options>...)
  file(UPLOAD <file> <url> <options>...)

  The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local
  ``<file>``.  The ``UPLOAD`` mode uploads a local ``<file>`` to a given
  ``<url>``.

  .. versionadded:: 3.19
    If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not
    saved. This can be useful if you want to know if a file can be downloaded
    (for example, to check that it exists) without actually saving it anywhere.

  Options to both ``DOWNLOAD`` and ``UPLOAD`` are:

    ``INACTIVITY_TIMEOUT <seconds>``
      Terminate the operation after a period of inactivity.

    ``LOG <variable>``
      Store a human-readable log of the operation in a variable.

    ``SHOW_PROGRESS``
      Print progress information as status messages until the operation is
      complete.

    ``STATUS <variable>``
      Store the resulting status of the operation in a variable.
      The status is a ``;`` separated list of length 2.
      The first element is the numeric return value for the operation,
      and the second element is a string value for the error.
      A ``0`` numeric error means no error in the operation.

    ``TIMEOUT <seconds>``
      Terminate the operation after a given total time has elapsed.

    ``USERPWD <username>:<password>``
      .. versionadded:: 3.7

      Set username and password for operation.

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

      HTTP header for ``DOWNLOAD`` and ``UPLOAD`` operations. ``HTTPHEADER``
      can be repeated for multiple options:

      .. code-block:: cmake

        file(DOWNLOAD <url>
             HTTPHEADER "Authorization: Bearer <auth-token>"
             HTTPHEADER "UserAgent: Mozilla/5.0")

    ``NETRC <level>``
      .. versionadded:: 3.11

      Specify whether the .netrc file is to be used for operation.  If this
      option is not specified, the value of the :variable:`CMAKE_NETRC`
      variable will be used instead.

      Valid levels are:

        ``IGNORED``
          The .netrc file is ignored.
          This is the default.

        ``OPTIONAL``
          The .netrc file is optional, and information in the URL is preferred.
          The file will be scanned to find which ever information is not
          specified in the URL.

        ``REQUIRED``
          The .netrc file is required, and information in the URL is ignored.

    ``NETRC_FILE <file>``
      .. versionadded:: 3.11

      Specify an alternative .netrc file to the one in your home directory,
      if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option
      is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable
      will be used instead.

    ``TLS_VERIFY <ON|OFF>``
      Specify whether to verify the server certificate for ``https://`` URLs.
      The default is to *not* verify. If this option is not specified, the
      value of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead.

      .. versionadded:: 3.18
        Added support to ``file(UPLOAD)``.

    ``TLS_CAINFO <file>``
      Specify a custom Certificate Authority file for ``https://`` URLs.
      If this option is not specified, the value of the
      :variable:`CMAKE_TLS_CAINFO` variable will be used instead.

      .. versionadded:: 3.18
        Added support to ``file(UPLOAD)``.

  For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
  certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
  check certificates.

  Additional options to ``DOWNLOAD`` are:

    ``EXPECTED_HASH <algorithm>=<value>``
      Verify that the downloaded content hash matches the expected value, where
      ``<algorithm>`` is one of the algorithms supported by :cref:`<HASH>`.
      If the file already exists and matches the hash, the download is skipped.
      If the file already exists and does not match the hash, the file is
      downloaded again. If after download the file does not match the hash, the
      operation fails with an error. It is an error to specify this option if
      ``DOWNLOAD`` is not given a ``<file>``.

    ``EXPECTED_MD5 <value>``
      Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error
      to specify this if ``DOWNLOAD`` is not given a ``<file>``.

    ``RANGE_START <value>``
      .. versionadded:: 3.24

      Offset of the start of the range in file in bytes. Could be omitted to
      download up to the specified ``RANGE_END``.

    ``RANGE_END <value>``
      .. versionadded:: 3.24

      Offset of the end of the range in file in bytes. Could be omitted to
      download everything from the specified ``RANGE_START`` to the end of
      file.

Locking
^^^^^^^

.. signature::
  file(LOCK <path> [DIRECTORY] [RELEASE]
       [GUARD <FUNCTION|FILE|PROCESS>]
       [RESULT_VARIABLE <variable>]
       [TIMEOUT <seconds>])

  .. versionadded:: 3.2

  Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and
  file ``<path>/cmake.lock`` otherwise.  The file will be locked for the scope
  defined by the ``GUARD`` option (default value is ``PROCESS``).  The
  ``RELEASE`` option can be used to unlock the file explicitly.  If the
  ``TIMEOUT`` option is not specified, CMake will wait until the lock succeeds
  or until a fatal error occurs.  If ``TIMEOUT`` is set to ``0``, locking will
  be tried once and the result will be reported immediately.  If ``TIMEOUT``
  is not ``0``, CMake will try to lock the file for the period specified by
  the ``TIMEOUT <seconds>`` value.  Any errors will be interpreted as fatal if
  there is no ``RESULT_VARIABLE`` option.  Otherwise, the result will be stored
  in ``<variable>`` and will be ``0`` on success or an error message on
  failure.

  Note that lock is advisory; there is no guarantee that other processes will
  respect this lock, i.e. lock synchronize two or more CMake instances sharing
  some modifiable resources. Similar logic applies to the ``DIRECTORY`` option;
  locking a parent directory doesn't prevent other ``LOCK`` commands from
  locking any child directory or file.

  Trying to lock the same file twice is not allowed.  Any intermediate
  directories and the file itself will be created if they not exist.  The
  ``GUARD`` and ``TIMEOUT`` options are ignored on the ``RELEASE`` operation.

Archiving
^^^^^^^^^

.. signature::
  file(ARCHIVE_CREATE OUTPUT <archive>
    PATHS <paths>...
    [FORMAT <format>]
    [COMPRESSION <compression>
     [COMPRESSION_LEVEL <compression-level>]]
    [MTIME <mtime>]
    [VERBOSE])
  :target: ARCHIVE_CREATE
  :break: verbatim

  .. versionadded:: 3.18

  Creates the specified ``<archive>`` file with the files and directories
  listed in ``<paths>``.  Note that ``<paths>`` must list actual files or
  directories; wildcards are not supported.

  Use the ``FORMAT`` option to specify the archive format.  Supported values
  for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and
  ``zip``.  If ``FORMAT`` is not given, the default format is ``paxr``.

  Some archive formats allow the type of compression to be specified.
  The ``7zip`` and ``zip`` archive formats already imply a specific type of
  compression.  The other formats use no compression by default, but can be
  directed to do so with the ``COMPRESSION`` option.  Valid values for
  ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.

  .. versionadded:: 3.19
    The compression level can be specified with the ``COMPRESSION_LEVEL``
    option.  The ``<compression-level>`` should be between 0-9, with the
    default being 0.  The ``COMPRESSION`` option must be present when
    ``COMPRESSION_LEVEL`` is given.

  .. versionadded:: 3.26
    The ``<compression-level>`` of the ``Zstd`` algorithm can be set
    between 0-19.

  .. note::
    With ``FORMAT`` set to ``raw``, only one file will be compressed with the
    compression type specified by ``COMPRESSION``.

  The ``VERBOSE`` option enables verbose output for the archive operation.

  To specify the modification time recorded in tarball entries, use
  the ``MTIME`` option.

.. signature::
  file(ARCHIVE_EXTRACT
    INPUT <archive>
    [DESTINATION <dir>]
    [PATTERNS <patterns>...]
    [LIST_ONLY]
    [VERBOSE]
    [TOUCH])
  :target: ARCHIVE_EXTRACT

  .. versionadded:: 3.18

  Extracts or lists the content of the specified ``<archive>``.

  The directory where the content of the archive will be extracted to can
  be specified using the ``DESTINATION`` option.  If the directory does not
  exist, it will be created.  If ``DESTINATION`` is not given, the current
  binary directory will be used.

  If required, you may select which files and directories to list or extract
  from the archive using the specified ``<patterns>``.  Wildcards are
  supported.  If the ``PATTERNS`` option is not given, the entire archive will
  be listed or extracted.

  ``LIST_ONLY`` will list the files in the archive rather than extract them.

  .. note::
    The working directory for this subcommand is the ``DESTINATION`` directory
    (provided or computed) except when ``LIST_ONLY`` is specified. Therefore,
    outside of script mode, it may be best to provide absolute paths to
    ``INPUT`` archives as they are unlikely to be extracted where a relative
    path works.

  .. versionadded:: 3.24
    The ``TOUCH`` option gives extracted files a current local
    timestamp instead of extracting file timestamps from the archive.

  With ``VERBOSE``, the command will produce verbose output.


code:
find_file
---------

.. |FIND_XXX| replace:: find_file
.. |NAMES| replace:: NAMES name1 [name2 ...]
.. |SEARCH_XXX| replace:: full path to a file
.. |SEARCH_XXX_DESC| replace:: full path to named file
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``

.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``

.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`

.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
   and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_INCLUDE_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`

.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
   and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
   On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
   This behavior was removed by CMake 3.28.

.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
   :variable:`CMAKE_SYSTEM_INCLUDE_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
   :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`

.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
   :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`

.. include:: FIND_XXX.txt


code:
find_library
------------

.. |FIND_XXX| replace:: find_library
.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
.. |SEARCH_XXX| replace:: library
.. |SEARCH_XXX_DESC| replace:: library
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/lib``

.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``

.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
   and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
   and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`

.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
   and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_LIBRARY_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`

.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``LIB``
   and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
   On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
   This behavior was removed by CMake 3.28.

.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
   and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
   :variable:`CMAKE_SYSTEM_LIBRARY_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
   :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`

.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
   :variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY`

.. include:: FIND_XXX.txt

When more than one value is given to the ``NAMES`` option this command by
default will consider one name at a time and search every directory
for it.  The ``NAMES_PER_DIR`` option tells this command to consider one
directory at a time and search for all names in it.

Each library name given to the ``NAMES`` option is first considered
as a library file name and then considered with platform-specific
prefixes (e.g. ``lib``) and suffixes (e.g. ``.so``).  Therefore one
may specify library file names such as ``libfoo.a`` directly.
This can be used to locate static libraries on UNIX-like systems.

If the library found is a framework, then ``<VAR>`` will be set to the full
path to the framework ``<fullPath>/A.framework``.  When a full path to a
framework is used as a library, CMake will use a ``-framework A``, and a
``-F<fullPath>`` to link the framework to the target.

.. versionadded:: 3.28

  The library found can now be a ``.xcframework`` folder.

If the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable is set all
search paths will be tested as normal, with the suffix appended, and with
all matches of ``lib/`` replaced with
``lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/``.  This variable overrides
the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS`,
:prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS`,
and :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global properties.

If the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global property is set
all search paths will be tested as normal, with ``32/`` appended, and
with all matches of ``lib/`` replaced with ``lib32/``.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.

If the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property is set
all search paths will be tested as normal, with ``x32/`` appended, and
with all matches of ``lib/`` replaced with ``libx32/``.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.

If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set
all search paths will be tested as normal, with ``64/`` appended, and
with all matches of ``lib/`` replaced with ``lib64/``.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.