code:
add_executable
--------------

.. only:: html

  .. contents::

Add an executable to the project using the specified source files.

Normal Executables
^^^^^^^^^^^^^^^^^^

.. signature::
  add_executable(<name> <options>... <sources>...)
  :target: normal

  Add an executable target called ``<name>`` to be built from the source
  files listed in the command invocation.

  The options are:

  ``WIN32``
    Set the :prop_tgt:`WIN32_EXECUTABLE` target property automatically.
    See documentation of that target property for details.

  ``MACOSX_BUNDLE``
    Set the :prop_tgt:`MACOSX_BUNDLE` target property automatically.
    See documentation of that target property for details.

  ``EXCLUDE_FROM_ALL``
    Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
    See documentation of that target property for details.

The ``<name>`` corresponds to the logical target name and must be globally
unique within a project.  The actual file name of the executable built is
constructed based on conventions of the native platform (such as
``<name>.exe`` or just ``<name>``).

.. versionadded:: 3.1
  Source arguments to ``add_executable`` may use "generator expressions" with
  the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
  manual for available expressions.

.. versionadded:: 3.11
  The source files can be omitted if they are added later using
  :command:`target_sources`.

By default the executable file will be created in the build tree
directory corresponding to the source tree directory in which the
command was invoked.  See documentation of the
:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target property to change this
location.  See documentation of the :prop_tgt:`OUTPUT_NAME` target property
to change the ``<name>`` part of the final file name.

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

See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.

Imported Executables
^^^^^^^^^^^^^^^^^^^^

.. signature::
  add_executable(<name> IMPORTED [GLOBAL])
  :target: IMPORTED

  Add an :ref:`IMPORTED executable target <Imported Targets>` to reference
  an executable file located outside the project.  The target name may be
  referenced like any target built within the project, except that by
  default it is visible only in the directory in which it is created,
  and below.

  The options are:

  ``GLOBAL``
    Make the target name globally visible.

No rules are generated to build imported targets, and the :prop_tgt:`IMPORTED`
target property is ``True``.  Imported executables are useful for convenient
reference from commands like :command:`add_custom_command`.

Details about the imported executable are specified by setting properties
whose names begin in ``IMPORTED_``.  The most important such property is
:prop_tgt:`IMPORTED_LOCATION` (and its per-configuration version
:prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the location of
the main executable file on disk.  See documentation of the ``IMPORTED_*``
properties for more information.

Alias Executables
^^^^^^^^^^^^^^^^^

.. signature::
  add_executable(<name> ALIAS <target>)
  :target: ALIAS

  Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
  be used to refer to ``<target>`` in subsequent commands.  The ``<name>``
  does not appear in the generated buildsystem as a make target.  The
  ``<target>`` may not be an ``ALIAS``.

.. versionadded:: 3.11
  An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`

.. versionadded:: 3.18
  An ``ALIAS`` can target a non-``GLOBAL`` Imported Target. Such alias is
  scoped to the directory in which it is created and subdirectories.
  The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
  alias is global or not.

``ALIAS`` targets can be used as targets to read properties
from, executables for custom commands and custom targets.  They can also be
tested for existence with the regular :command:`if(TARGET)` subcommand.
The ``<name>`` may not be used to modify properties of ``<target>``, that
is, it may not be used as the operand of :command:`set_property`,
:command:`set_target_properties`, :command:`target_link_libraries` etc.
An ``ALIAS`` target may not be installed or exported.

See Also
^^^^^^^^

* :command:`add_library`


code:
add_library
-----------

.. only:: html

   .. contents::

Add a library to the project using the specified source files.

Normal Libraries
^^^^^^^^^^^^^^^^

.. signature::
  add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...)
  :target: normal

  Add a library target called ``<name>`` to be built from the source files
  listed in the command invocation.

  The optional ``<type>`` specifies the type of library to be created:

  ``STATIC``
    An archive of object files for use when linking other targets.

  ``SHARED``
    A dynamic library that may be linked by other targets and loaded
    at runtime.

  ``MODULE``
    A plugin that may not be linked by other targets, but may be
    dynamically loaded at runtime using dlopen-like functionality.

  If no ``<type>`` is given the default is ``STATIC`` or ``SHARED``
  based on the value of the :variable:`BUILD_SHARED_LIBS` variable.

  The options are:

  ``EXCLUDE_FROM_ALL``
    Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
    See documentation of that target property for details.

The ``<name>`` corresponds to the logical target name and must be globally
unique within a project.  The actual file name of the library built is
constructed based on conventions of the native platform (such as
``lib<name>.a`` or ``<name>.lib``).

.. versionadded:: 3.1
  Source arguments to ``add_library`` may use "generator expressions" with
  the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
  manual for available expressions.

.. versionadded:: 3.11
  The source files can be omitted if they are added later using
  :command:`target_sources`.

For ``SHARED`` and ``MODULE`` libraries the
:prop_tgt:`POSITION_INDEPENDENT_CODE` target
property is set to ``ON`` automatically.
A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
target property to create an macOS Framework.

.. versionadded:: 3.8
  A ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK`
  target property to create a static Framework.

If a library does not export any symbols, it must not be declared as a
``SHARED`` library.  For example, a Windows resource DLL or a managed C++/CLI
DLL that exports no unmanaged symbols would need to be a ``MODULE`` library.
This is because CMake expects a ``SHARED`` library to always have an
associated import library on Windows.

By default the library file will be created in the build tree directory
corresponding to the source tree directory in which the command was
invoked.  See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and
:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties to change this
location.  See documentation of the :prop_tgt:`OUTPUT_NAME` target
property to change the ``<name>`` part of the final file name.

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

See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.

Object Libraries
^^^^^^^^^^^^^^^^

.. signature::
  add_library(<name> OBJECT <sources>...)
  :target: OBJECT

  Add an :ref:`Object Library <Object Libraries>` to compile source files
  without archiving or linking their object files into a library.

Other targets created by ``add_library`` or :command:`add_executable`
may reference the objects using an expression of the
form :genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>` as a source, where
``objlib`` is the object library name.  For example:

.. code-block:: cmake

  add_library(... $<TARGET_OBJECTS:objlib> ...)
  add_executable(... $<TARGET_OBJECTS:objlib> ...)

will include objlib's object files in a library and an executable
along with those compiled from their own sources.  Object libraries
may contain only sources that compile, header files, and other files
that would not affect linking of a normal library (e.g. ``.txt``).
They may contain custom commands generating such sources, but not
``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands.  Some native build
systems (such as Xcode) may not like targets that have only object files, so
consider adding at least one real source file to any target that references
:genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>`.

.. versionadded:: 3.12
  Object libraries can be linked to with :command:`target_link_libraries`.

Interface Libraries
^^^^^^^^^^^^^^^^^^^

.. signature::
  add_library(<name> INTERFACE)
  :target: INTERFACE

  Add an :ref:`Interface Library <Interface Libraries>` target that may
  specify usage requirements for dependents but does not compile sources
  and does not produce a library artifact on disk.

  An interface library with no source files is not included as a target
  in the generated buildsystem.  However, it may have
  properties set on it and it may be installed and exported.
  Typically, ``INTERFACE_*`` properties are populated on an interface
  target using the commands:

  * :command:`set_property`,
  * :command:`target_link_libraries(INTERFACE)`,
  * :command:`target_link_options(INTERFACE)`,
  * :command:`target_include_directories(INTERFACE)`,
  * :command:`target_compile_options(INTERFACE)`,
  * :command:`target_compile_definitions(INTERFACE)`, and
  * :command:`target_sources(INTERFACE)`,

  and then it is used as an argument to :command:`target_link_libraries`
  like any other target.

  .. versionadded:: 3.15
    An interface library can have :prop_tgt:`PUBLIC_HEADER` and
    :prop_tgt:`PRIVATE_HEADER` properties.  The headers specified by those
    properties can be installed using the :command:`install(TARGETS)` command.

.. signature::
  add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] <sources>...)
  :target: INTERFACE-with-sources

  .. versionadded:: 3.19

  Add an :ref:`Interface Library <Interface Libraries>` target with
  source files (in addition to usage requirements and properties as
  documented by the :command:`above signature <add_library(INTERFACE)>`).
  Source files may be listed directly in the ``add_library`` call
  or added later by calls to :command:`target_sources` with the
  ``PRIVATE`` or ``PUBLIC`` keywords.

  If an interface library has source files (i.e. the :prop_tgt:`SOURCES`
  target property is set), or header sets (i.e. the :prop_tgt:`HEADER_SETS`
  target property is set), it will appear in the generated buildsystem
  as a build target much like a target defined by the
  :command:`add_custom_target` command.  It does not compile any sources,
  but does contain build rules for custom commands created by the
  :command:`add_custom_command` command.

  The options are:

  ``EXCLUDE_FROM_ALL``
    Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
    See documentation of that target property for details.

  .. note::
    In most command signatures where the ``INTERFACE`` keyword appears,
    the items listed after it only become part of that target's usage
    requirements and are not part of the target's own settings.  However,
    in this signature of ``add_library``, the ``INTERFACE`` keyword refers
    to the library type only.  Sources listed after it in the ``add_library``
    call are ``PRIVATE`` to the interface library and do not appear in its
    :prop_tgt:`INTERFACE_SOURCES` target property.

.. _`add_library imported libraries`:

Imported Libraries
^^^^^^^^^^^^^^^^^^

.. signature::
  add_library(<name> <type> IMPORTED [GLOBAL])
  :target: IMPORTED

  Add an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
  The target name may be referenced like any target built within the project,
  except that by default it is visible only in the directory in which it is
  created, and below.

  The ``<type>`` must be one of:

  ``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
    References a library file located outside the project.  The
    :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration
    variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the
    location of the main library file on disk:

    * For a ``SHARED`` library on most non-Windows platforms, the main library
      file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic
      loaders.  If the referenced library file has a ``SONAME`` (or on macOS,
      has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field
      should be set in the :prop_tgt:`IMPORTED_SONAME` target property.
      If the referenced library file does not have a ``SONAME``, but the
      platform supports it, then  the :prop_tgt:`IMPORTED_NO_SONAME` target
      property should be set.

    * For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB`
      target property (or its per-configuration variant
      :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the
      DLL import library file (``.lib`` or ``.dll.a``) on disk, and the
      ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime
      library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS`
      generator expression).

    Additional usage requirements may be specified in ``INTERFACE_*``
    properties.

    An ``UNKNOWN`` library type is typically only used in the implementation
    of :ref:`Find Modules`.  It allows the path to an imported library
    (often found using the :command:`find_library` command) to be used
    without having to know what type of library it is.  This is especially
    useful on Windows where a static library and a DLL's import library
    both have the same file extension.

  ``OBJECT``
    References a set of object files located outside the project.
    The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration
    variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of
    object files on disk.
    Additional usage requirements may be specified in ``INTERFACE_*``
    properties.

  ``INTERFACE``
    Does not reference any library or object files on disk, but may
    specify usage requirements in ``INTERFACE_*`` properties.

  The options are:

  ``GLOBAL``
    Make the target name globally visible.

No rules are generated to build imported targets, and the :prop_tgt:`IMPORTED`
target property is ``True``.  Imported libraries are useful for convenient
reference from commands like :command:`target_link_libraries`.

Details about the imported library are specified by setting properties whose
names begin in ``IMPORTED_`` and ``INTERFACE_``.  See documentation of
such properties for more information.

Alias Libraries
^^^^^^^^^^^^^^^

.. signature::
  add_library(<name> ALIAS <target>)
  :target: ALIAS

  Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
  used to refer to ``<target>`` in subsequent commands.  The ``<name>`` does
  not appear in the generated buildsystem as a make target.  The ``<target>``
  may not be an ``ALIAS``.

.. versionadded:: 3.11
  An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`

.. versionadded:: 3.18
  An ``ALIAS`` can target a non-``GLOBAL`` Imported Target. Such alias is
  scoped to the directory in which it is created and below.
  The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
  alias is global or not.

``ALIAS`` targets can be used as linkable targets and as targets to
read properties from.  They can also be tested for existence with the
regular :command:`if(TARGET)` subcommand.  The ``<name>`` may not be used
to modify properties of ``<target>``, that is, it may not be used as the
operand of :command:`set_property`, :command:`set_target_properties`,
:command:`target_link_libraries` etc.  An ``ALIAS`` target may not be
installed or exported.

See Also
^^^^^^^^

* :command:`add_executable`

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
add_link_options
----------------

.. versionadded:: 3.13

Add options to the link step for executable, shared library or module
library targets in the current directory and below that are added after
this command is invoked.

.. code-block:: cmake

  add_link_options(<option> ...)

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

.. note::

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

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

.. include:: DEVICE_LINK_OPTIONS.txt

.. include:: OPTIONS_SHELL.txt

.. include:: LINK_OPTIONS_LINKER.txt

See Also
^^^^^^^^

* :command:`link_libraries`
* :command:`target_link_libraries`
* :command:`target_link_options`

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


code:
add_subdirectory
----------------

Add a subdirectory to the build.

.. code-block:: cmake

  add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM])

Adds a subdirectory to the build.  The ``source_dir`` specifies the
directory in which the source ``CMakeLists.txt`` and code files are
located.  If it is a relative path, it will be evaluated with respect
to the current directory (the typical usage), but it may also be an
absolute path.  The ``binary_dir`` specifies the directory in which to
place the output files.  If it is a relative path, it will be evaluated
with respect to the current output directory, but it may also be an
absolute path.  If ``binary_dir`` is not specified, the value of
``source_dir``, before expanding any relative path, will be used (the
typical usage).  The ``CMakeLists.txt`` file in the specified source
directory will be processed immediately by CMake before processing in
the current input file continues beyond this command.

If the ``EXCLUDE_FROM_ALL`` argument is provided then targets in the
subdirectory will not be included in the ``ALL`` target of the parent
directory by default, and will be excluded from IDE project files.
Users must explicitly build targets in the subdirectory.  This is
meant for use when the subdirectory contains a separate part of the
project that is useful but not necessary, such as a set of examples.
Typically the subdirectory should contain its own :command:`project`
command invocation so that a full build system will be generated in the
subdirectory (such as a Visual Studio IDE solution file).  Note that
inter-target dependencies supersede this exclusion.  If a target built by
the parent project depends on a target in the subdirectory, the dependee
target will be included in the parent project build system to satisfy
the dependency.

.. versionadded:: 3.25
  If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory
  property of the subdirectory will be set to true.  This property is
  used to initialize the :prop_tgt:`SYSTEM` property of each non-imported
  target created in that subdirectory.


code:
add_test
--------

Add a test to the project to be run by :manual:`ctest(1)`.

.. code-block:: cmake

  add_test(NAME <name> COMMAND <command> [<arg>...]
           [CONFIGURATIONS <config>...]
           [WORKING_DIRECTORY <dir>]
           [COMMAND_EXPAND_LISTS])

Adds a test called ``<name>``.  The test name may contain arbitrary
characters, expressed as a :ref:`Quoted Argument` or :ref:`Bracket Argument`
if necessary.  See policy :policy:`CMP0110`.

CMake only generates tests if the :command:`enable_testing` command has been
invoked.  The :module:`CTest` module invokes ``enable_testing`` automatically
unless ``BUILD_TESTING`` is set to ``OFF``.

Tests added with the ``add_test(NAME)`` signature support using
:manual:`generator expressions <cmake-generator-expressions(7)>`
in test properties set by :command:`set_property(TEST)` or
:command:`set_tests_properties`. Test properties may only be set in the
directory the test is created in.

``add_test`` options are:

``COMMAND``
  Specify the test command-line.

  If ``<command>`` specifies an executable target created by
  :command:`add_executable`:

  * It will automatically be replaced by the location of the executable
    created at build time.

  * .. versionadded:: 3.3

      The target's :prop_tgt:`CROSSCOMPILING_EMULATOR`, if set, will be
      used to run the command on the host::

        <emulator> <command>

      .. versionchanged:: 3.29

        The emulator is used only when
        :variable:`cross-compiling <CMAKE_CROSSCOMPILING>`.
        See policy :policy:`CMP0158`.

  * .. versionadded:: 3.29

      The target's :prop_tgt:`TEST_LAUNCHER`, if set, will be
      used to launch the command::

        <launcher> <command>

      If the :prop_tgt:`CROSSCOMPILING_EMULATOR` is also set, both are used::

        <launcher> <emulator> <command>

  The command may be specified using
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

``CONFIGURATIONS``
  Restrict execution of the test only to the named configurations.

``WORKING_DIRECTORY``
  Set the test property :prop_test:`WORKING_DIRECTORY` in which to execute the
  test. If not specified, the test will be run in
  :variable:`CMAKE_CURRENT_BINARY_DIR`. The working directory may be specified
  using :manual:`generator expressions <cmake-generator-expressions(7)>`.

``COMMAND_EXPAND_LISTS``
  .. versionadded:: 3.16

  Lists in ``COMMAND`` arguments will be expanded, including those created with
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

If the test command exits with code ``0`` the test passes. Non-zero exit code
is a "failed" test. The test property :prop_test:`WILL_FAIL` inverts this
logic. Note that system-level test failures such as segmentation faults or
heap errors will still fail the test even if ``WILL_FALL`` is true. Output
written to stdout or stderr is captured by :manual:`ctest(1)` and only
affects the pass/fail status via the :prop_test:`PASS_REGULAR_EXPRESSION`,
:prop_test:`FAIL_REGULAR_EXPRESSION`, or :prop_test:`SKIP_REGULAR_EXPRESSION`
test properties.

.. versionadded:: 3.16
  Added :prop_test:`SKIP_REGULAR_EXPRESSION` property.

Example usage:

.. code-block:: cmake

  add_test(NAME mytest
           COMMAND testDriver --config $<CONFIG>
                              --exe $<TARGET_FILE:myexe>)

This creates a test ``mytest`` whose command runs a ``testDriver`` tool
passing the configuration name and the full path to the executable
file produced by target ``myexe``.

---------------------------------------------------------------------

The command syntax above is recommended over the older, less flexible form:

.. code-block:: cmake

  add_test(<name> <command> [<arg>...])

Add a test called ``<name>`` with the given command-line.

Unlike the above ``NAME`` signature, target names are not supported
in the command-line.  Furthermore, tests added with this signature do not
support :manual:`generator expressions <cmake-generator-expressions(7)>`
in the command-line or test properties.


code:
aux_source_directory
--------------------

Find all source files in a directory.

.. code-block:: cmake

  aux_source_directory(<dir> <variable>)

Collects the names of all the source files in the specified directory
and stores the list in the ``<variable>`` provided.  This command is
intended to be used by projects that use explicit template
instantiation.  Template instantiation files can be stored in a
``Templates`` subdirectory and collected automatically using this
command to avoid manually listing all instantiations.

It is tempting to use this command to avoid writing the list of source
files for a library or executable target.  While this seems to work,
there is no way for CMake to generate a build system that knows when a
new source file has been added.  Normally the generated build system
knows when it needs to rerun CMake because the ``CMakeLists.txt`` file is
modified to add a new source.  When the source is just added to the
directory without modifying this file, one would have to manually
rerun CMake to generate a build system incorporating the new file.


code:
block
-----

.. versionadded:: 3.25

Evaluate a group of commands with a dedicated variable and/or policy scope.

.. code-block:: cmake

  block([SCOPE_FOR [POLICIES] [VARIABLES] ] [PROPAGATE <var-name>...])
    <commands>
  endblock()

All commands between ``block()`` and the matching :command:`endblock` are
recorded without being invoked.  Once the :command:`endblock` is evaluated, the
recorded list of commands is invoked inside the requested scopes, then the
scopes created by the ``block()`` command are removed.

``SCOPE_FOR``
  Specify which scopes must be created.

  ``POLICIES``
    Create a new policy scope. This is equivalent to
    :command:`cmake_policy(PUSH)` with an automatic
    :command:`cmake_policy(POP)` when leaving the block scope.

  ``VARIABLES``
    Create a new variable scope.

  If ``SCOPE_FOR`` is not specified, this is equivalent to:

  .. code-block:: cmake

    block(SCOPE_FOR VARIABLES POLICIES)

``PROPAGATE``
  When a variable scope is created by the :command:`block` command, this
  option sets or unsets the specified variables in the parent scope. This is
  equivalent to :command:`set(PARENT_SCOPE)` or :command:`unset(PARENT_SCOPE)`
  commands.

  .. code-block:: cmake

    set(var1 "INIT1")
    set(var2 "INIT2")

    block(PROPAGATE var1 var2)
      set(var1 "VALUE1")
      unset(var2)
    endblock()

    # Now var1 holds VALUE1, and var2 is unset

  This option is only allowed when a variable scope is created. An error will
  be raised in the other cases.

When the ``block()`` is inside a :command:`foreach` or :command:`while`
command, the :command:`break` and :command:`continue` commands can be used
inside the block.

.. code-block:: cmake

  while(TRUE)
    block()
       ...
       # the break() command will terminate the while() command
       break()
    endblock()
  endwhile()

See Also
^^^^^^^^

* :command:`endblock`
* :command:`return`
* :command:`cmake_policy`


code:
break
-----

Break from an enclosing foreach or while loop.

.. code-block:: cmake

  break()

Breaks from an enclosing :command:`foreach` or :command:`while` loop.

See also the :command:`continue` command.


code:
build_command
-------------

Get a command line to build the current project.
This is mainly intended for internal use by the :module:`CTest` module.

.. code-block:: cmake

  build_command(<variable>
                [CONFIGURATION <config>]
                [PARALLEL_LEVEL <parallel>]
                [TARGET <target>]
                [PROJECT_NAME <projname>] # legacy, causes warning
               )

Sets the given ``<variable>`` to a command-line string of the form::

 <cmake> --build . [--config <config>] [--parallel <parallel>] [--target <target>...] [-- -i]

where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line
tool, and ``<config>``, ``<parallel>`` and ``<target>`` are the values
provided to the ``CONFIGURATION``, ``PARALLEL_LEVEL`` and ``TARGET``
options, if any.  The trailing ``-- -i`` option is added for
:ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to
``NEW``.

When invoked, this :option:`cmake --build` command line will launch the
underlying build system tool.

.. versionadded:: 3.21
  The ``PARALLEL_LEVEL`` argument can be used to set the
  :option:`--parallel <cmake--build --parallel>` flag.

.. code-block:: cmake

  build_command(<cachevariable> <makecommand>)

This second signature is deprecated, but still available for backwards
compatibility.  Use the first signature instead.

It sets the given ``<cachevariable>`` to a command-line string as
above but without the :option:`--target <cmake--build --target>` option.
The ``<makecommand>`` is ignored but should be the full path to
devenv, nmake, make or one of the end user build tools
for legacy invocations.

.. note::
 In CMake versions prior to 3.0 this command returned a command
 line that directly invokes the native build tool for the current
 generator.  Their implementation of the ``PROJECT_NAME`` option
 had no useful effects, so CMake now warns on use of the option.


code:
build_name
----------

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

Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead.

.. code-block:: cmake

  build_name(variable)

Sets the specified variable to a string representing the platform and
compiler settings.  These values are now available through the
:variable:`CMAKE_SYSTEM` and
:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` variables.


code:
cmake_file_api
--------------

.. versionadded:: 3.27

Enables interacting with the :manual:`CMake file API <cmake-file-api(7)>`.

.. signature::
  cmake_file_api(QUERY ...)

  The ``QUERY`` subcommand adds a file API query for the current CMake
  invocation.

  .. code-block:: cmake

    cmake_file_api(
      QUERY
      API_VERSION <version>
      [CODEMODEL <versions>...]
      [CACHE <versions>...]
      [CMAKEFILES <versions>...]
      [TOOLCHAINS <versions>...]
    )

  The ``API_VERSION`` must always be given.  Currently, the only supported
  value for ``<version>`` is 1.  See :ref:`file-api v1` for details of the
  reply content and location.

  Each of the optional keywords ``CODEMODEL``, ``CACHE``, ``CMAKEFILES`` and
  ``TOOLCHAINS`` correspond to one of the object kinds that can be requested
  by the project.  The ``configureLog`` object kind cannot be set with this
  command, since it must be set before CMake starts reading the top level
  ``CMakeLists.txt`` file.

  For each of the optional keywords, the ``<versions>`` list must contain one
  or more version values of the form ``major`` or ``major.minor``, where
  ``major`` and ``minor`` are integers.  Projects should list the versions they
  accept in their preferred order, as only the first supported value from the
  list will be selected.  The command will ignore versions with a ``major``
  version higher than any major version it supports for that object kind.
  It will raise an error if it encounters an invalid version number, or if none
  of the requested versions is supported.

  For each type of object kind requested, a query equivalent to a shared,
  stateless query will be added internally.  No query file will be created in
  the file system.  The reply *will* be written to the file system at
  generation time.

  It is not an error to add a query for the same thing more than once, whether
  from query files or from multiple calls to ``cmake_file_api(QUERY)``.
  The final set of queries will be a merged combination of all queries
  specified on disk and queries submitted by the project.

Example
^^^^^^^

A project may want to use replies from the file API at build time to implement
some form of verification task.  Instead of relying on something outside of
CMake to create a query file, the project can use ``cmake_file_api(QUERY)``
to request the required information for the current run.  It can then create
a custom command to run at build time, knowing that the requested information
should always be available.

.. code-block:: cmake

  cmake_file_api(
    QUERY
    API_VERSION 1
    CODEMODEL 2.3
    TOOLCHAINS 1
  )

  add_custom_target(verify_project
    COMMAND ${CMAKE_COMMAND}
      -D BUILD_DIR=${CMAKE_BINARY_DIR}
      -D CONFIG=$<CONFIG>
      -P ${CMAKE_CURRENT_SOURCE_DIR}/verify_project.cmake
  )


code:
cmake_host_system_information
-----------------------------

Query various host system information.

Synopsis
^^^^^^^^

.. parsed-literal::

  `Query host system specific information`_
    cmake_host_system_information(RESULT <variable> QUERY <key> ...)

  `Query Windows registry`_
    cmake_host_system_information(RESULT <variable> QUERY WINDOWS_REGISTRY <key> ...)

Query host system specific information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  cmake_host_system_information(RESULT <variable> QUERY <key> ...)

Queries system information of the host system on which cmake runs.
One or more ``<key>`` can be provided to select the information to be
queried.  The list of queried values is stored in ``<variable>``.

``<key>`` can be one of the following values:

``NUMBER_OF_LOGICAL_CORES``
  Number of logical cores

``NUMBER_OF_PHYSICAL_CORES``
  Number of physical cores

``HOSTNAME``
  Hostname

``FQDN``
  Fully qualified domain name

``TOTAL_VIRTUAL_MEMORY``
  Total virtual memory in MiB [#mebibytes]_

``AVAILABLE_VIRTUAL_MEMORY``
  Available virtual memory in MiB [#mebibytes]_

``TOTAL_PHYSICAL_MEMORY``
  Total physical memory in MiB [#mebibytes]_

``AVAILABLE_PHYSICAL_MEMORY``
  Available physical memory in MiB [#mebibytes]_

``IS_64BIT``
  .. versionadded:: 3.10

  One if processor is 64Bit

``HAS_FPU``
  .. versionadded:: 3.10

  One if processor has floating point unit

``HAS_MMX``
  .. versionadded:: 3.10

  One if processor supports MMX instructions

``HAS_MMX_PLUS``
  .. versionadded:: 3.10

  One if processor supports Ext. MMX instructions

``HAS_SSE``
  .. versionadded:: 3.10

  One if processor supports SSE instructions

``HAS_SSE2``
  .. versionadded:: 3.10

  One if processor supports SSE2 instructions

``HAS_SSE_FP``
  .. versionadded:: 3.10

  One if processor supports SSE FP instructions

``HAS_SSE_MMX``
  .. versionadded:: 3.10

  One if processor supports SSE MMX instructions

``HAS_AMD_3DNOW``
  .. versionadded:: 3.10

  One if processor supports 3DNow instructions

``HAS_AMD_3DNOW_PLUS``
  .. versionadded:: 3.10

  One if processor supports 3DNow+ instructions

``HAS_IA64``
  .. versionadded:: 3.10

  One if IA64 processor emulating x86

``HAS_SERIAL_NUMBER``
  .. versionadded:: 3.10

  One if processor has serial number

``PROCESSOR_SERIAL_NUMBER``
  .. versionadded:: 3.10

  Processor serial number

``PROCESSOR_NAME``
  .. versionadded:: 3.10

  Human readable processor name

``PROCESSOR_DESCRIPTION``
  .. versionadded:: 3.10

  Human readable full processor description

``OS_NAME``
  .. versionadded:: 3.10

  See :variable:`CMAKE_HOST_SYSTEM_NAME`

``OS_RELEASE``
  .. versionadded:: 3.10

  The OS sub-type e.g. on Windows ``Professional``

``OS_VERSION``
  .. versionadded:: 3.10

  The OS build ID

``OS_PLATFORM``
  .. versionadded:: 3.10

  See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`

``MSYSTEM_PREFIX``
  .. versionadded:: 3.28

  Available only on Windows hosts.  In a MSYS or MinGW development
  environment that sets the ``MSYSTEM`` environment variable, this
  is its installation prefix.  Otherwise, this is the empty string.

``DISTRIB_INFO``
  .. versionadded:: 3.22

  Read :file:`/etc/os-release` file and define the given ``<variable>``
  into a list of read variables

``DISTRIB_<name>``
  .. versionadded:: 3.22

  Get the ``<name>`` variable (see `man 5 os-release`_) if it exists in the
  :file:`/etc/os-release` file

  Example:

  .. code-block:: cmake

      cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME)
      message(STATUS "${PRETTY_NAME}")

      cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO)

      foreach(VAR IN LISTS DISTRO)
        message(STATUS "${VAR}=`${${VAR}}`")
      endforeach()

  Output::

    -- Ubuntu 20.04.2 LTS
    -- DISTRO_BUG_REPORT_URL=`https://bugs.launchpad.net/ubuntu/`
    -- DISTRO_HOME_URL=`https://www.ubuntu.com/`
    -- DISTRO_ID=`ubuntu`
    -- DISTRO_ID_LIKE=`debian`
    -- DISTRO_NAME=`Ubuntu`
    -- DISTRO_PRETTY_NAME=`Ubuntu 20.04.2 LTS`
    -- DISTRO_PRIVACY_POLICY_URL=`https://www.ubuntu.com/legal/terms-and-policies/privacy-policy`
    -- DISTRO_SUPPORT_URL=`https://help.ubuntu.com/`
    -- DISTRO_UBUNTU_CODENAME=`focal`
    -- DISTRO_VERSION=`20.04.2 LTS (Focal Fossa)`
    -- DISTRO_VERSION_CODENAME=`focal`
    -- DISTRO_VERSION_ID=`20.04`

If :file:`/etc/os-release` file is not found, the command tries to gather OS
identification via fallback scripts.  The fallback script can use `various
distribution-specific files`_ to collect OS identification data and map it
into `man 5 os-release`_ variables.

Fallback Interface Variables
""""""""""""""""""""""""""""

.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS

  In addition to the scripts shipped with CMake, a user may append full
  paths to his script(s) to the this list.  The script filename has the
  following format: ``NNN-<name>.cmake``, where ``NNN`` is three digits
  used to apply collected scripts in a specific order.

.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname>

  Variables collected by the user provided fallback script
  ought to be assigned to CMake variables using this naming
  convention.  Example, the ``ID`` variable from the manual becomes
  ``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID``.

.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT

  The fallback script ought to store names of all assigned
  ``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname>`` variables in this list.

Example:

.. code-block:: cmake

  # Try to detect some old distribution
  # See also
  # - http://linuxmafia.com/faq/Admin/release-files.html
  #
  if(NOT EXISTS "${CMAKE_SYSROOT}/etc/foobar-release")
    return()
  endif()
  # Get the first string only
  file(
      STRINGS "${CMAKE_SYSROOT}/etc/foobar-release" CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT
      LIMIT_COUNT 1
    )
  #
  # Example:
  #
  #   Foobar distribution release 1.2.3 (server)
  #
  if(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT MATCHES "Foobar distribution release ([0-9\.]+) .*")
    set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME Foobar)
    set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME "${CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT}")
    set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID foobar)
    set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION ${CMAKE_MATCH_1})
    set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID ${CMAKE_MATCH_1})
    list(
        APPEND CMAKE_GET_OS_RELEASE_FALLBACK_RESULT
        CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME
        CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME
        CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID
        CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION
        CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID
      )
  endif()
  unset(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT)

.. rubric:: Footnotes

.. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes.

.. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/latest/os-release.html
.. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html

.. _Query Windows registry:

Query Windows registry
^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.24

::

  cmake_host_system_information(RESULT <variable>
                                QUERY WINDOWS_REGISTRY <key> [VALUE_NAMES|SUBKEYS|VALUE <name>]
                                [VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
                                [SEPARATOR <separator>]
                                [ERROR_VARIABLE <result>])

Performs query operations on local computer registry subkey. Returns a list of
subkeys or value names that are located under the specified subkey in the
registry or the data of the specified value name. The result of the queried
entity is stored in ``<variable>``.

.. note::

  Querying registry for any other platforms than ``Windows``, including
  ``CYGWIN``, will always returns an empty string and sets an error message in
  the variable specified with sub-option ``ERROR_VARIABLE``.

``<key>`` specify the full path of a subkey on the local computer. The
``<key>`` must include a valid root key. Valid root keys for the local computer
are:

* ``HKLM`` or ``HKEY_LOCAL_MACHINE``
* ``HKCU`` or ``HKEY_CURRENT_USER``
* ``HKCR`` or ``HKEY_CLASSES_ROOT``
* ``HKU`` or ``HKEY_USERS``
* ``HKCC`` or ``HKEY_CURRENT_CONFIG``

And, optionally, the path to a subkey under the specified root key. The path
separator can be the slash or the backslash. ``<key>`` is not case sensitive.
For example:

.. code-block:: cmake

  cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM")
  cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
  cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKCU\\SOFTWARE\\Kitware")

``VALUE_NAMES``
  Request the list of value names defined under ``<key>``. If a default value
  is defined, it will be identified with the special name ``(default)``.

``SUBKEYS``
  Request the list of subkeys defined under ``<key>``.

``VALUE <name>``
  Request the data stored in value named ``<name>``. If ``VALUE`` is not
  specified or argument is the special name ``(default)``, the content of the
  default value, if any, will be returned.

  .. code-block:: cmake

     # query default value for HKLM/SOFTWARE/Kitware key
     cmake_host_system_information(RESULT result
                                   QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")

     # query default value for HKLM/SOFTWARE/Kitware key using special value name
     cmake_host_system_information(RESULT result
                                   QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware"
                                   VALUE "(default)")

  Supported types are:

  * ``REG_SZ``.
  * ``REG_EXPAND_SZ``. The returned data is expanded.
  * ``REG_MULTI_SZ``. The returned is expressed as a CMake list. See also
    ``SEPARATOR`` sub-option.
  * ``REG_DWORD``.
  * ``REG_QWORD``.

  For all other types, an empty string is returned.

``VIEW``
  Specify which registry views must be queried. When not specified, ``BOTH``
  view is used.

  ``64``
    Query the 64bit registry. On ``32bit Windows``, returns always an empty
    string.

  ``32``
    Query the 32bit registry.

  ``64_32``
    For ``VALUE`` sub-option or default value, query the registry using view
    ``64``, and if the request failed, query the registry using view ``32``.
    For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``64``
    and ``32``) and merge the results (sorted and duplicates removed).

  ``32_64``
    For ``VALUE`` sub-option or default value, query the registry using view
    ``32``, and if the request failed, query the registry using view ``64``.
    For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``32``
    and ``64``) and merge the results (sorted and duplicates removed).

  ``HOST``
    Query the registry matching the architecture of the host: ``64`` on ``64bit
    Windows`` and ``32`` on ``32bit Windows``.

  ``TARGET``
    Query the registry matching the architecture specified by
    :variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to
    ``HOST`` view.

  ``BOTH``
    Query both views (``32`` and ``64``). The order depends of the following
    rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the
    following view depending of the content of this variable:

    * ``8``: ``64_32``
    * ``4``: ``32_64``

    If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on
    architecture of the host:

    * ``64bit``: ``64_32``
    * ``32bit``: ``32``

``SEPARATOR``
  Specify the separator character for ``REG_MULTI_SZ`` type. When not
  specified, the character ``\0`` is used.

``ERROR_VARIABLE <result>``
  Returns any error raised during query operation. In case of success, the
  variable holds an empty string.


code:
cmake_language
--------------

.. versionadded:: 3.18

Call meta-operations on CMake commands.

Synopsis
^^^^^^^^

.. parsed-literal::

  cmake_language(`CALL`_ <command> [<arg>...])
  cmake_language(`EVAL`_ CODE <code>...)
  cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...])
  cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...)
  cmake_language(`GET_MESSAGE_LOG_LEVEL`_ <out-var>)
  cmake_language(`EXIT`_ <exit-code>)

Introduction
^^^^^^^^^^^^

This command will call meta-operations on built-in CMake commands or
those created via the :command:`macro` or :command:`function` commands.

``cmake_language`` does not introduce a new variable or policy scope.

Calling Commands
^^^^^^^^^^^^^^^^

.. signature::
  cmake_language(CALL <command> [<arg>...])

  Calls the named ``<command>`` with the given arguments (if any).
  For example, the code:

  .. code-block:: cmake

    set(message_command "message")
    cmake_language(CALL ${message_command} STATUS "Hello World!")

  is equivalent to

  .. code-block:: cmake

    message(STATUS "Hello World!")

  .. note::
    To ensure consistency of the code, the following commands are not allowed:

    * ``if`` / ``elseif`` / ``else`` / ``endif``
    * ``block`` / ``endblock``
    * ``while`` / ``endwhile``
    * ``foreach`` / ``endforeach``
    * ``function`` / ``endfunction``
    * ``macro`` / ``endmacro``

Evaluating Code
^^^^^^^^^^^^^^^

.. signature::
  cmake_language(EVAL CODE <code>...)
  :target: EVAL

  Evaluates the ``<code>...`` as CMake code.

  For example, the code:

  .. code-block:: cmake

    set(A TRUE)
    set(B TRUE)
    set(C TRUE)
    set(condition "(A AND B) OR C")

    cmake_language(EVAL CODE "
      if (${condition})
        message(STATUS TRUE)
      else()
        message(STATUS FALSE)
      endif()"
    )

  is equivalent to

  .. code-block:: cmake

    set(A TRUE)
    set(B TRUE)
    set(C TRUE)
    set(condition "(A AND B) OR C")

    file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
      if (${condition})
        message(STATUS TRUE)
      else()
        message(STATUS FALSE)
      endif()"
    )

    include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)

Deferring Calls
^^^^^^^^^^^^^^^

.. versionadded:: 3.19

.. signature::
  cmake_language(DEFER <options>... CALL <command> [<arg>...])

  Schedules a call to the named ``<command>`` with the given arguments (if any)
  to occur at a later time.  By default, deferred calls are executed as if
  written at the end of the current directory's ``CMakeLists.txt`` file,
  except that they run even after a :command:`return` call.  Variable
  references in arguments are evaluated at the time the deferred call is
  executed.

  The options are:

  ``DIRECTORY <dir>``
    Schedule the call for the end of the given directory instead of the
    current directory.  The ``<dir>`` may reference either a source
    directory or its corresponding binary directory.  Relative paths are
    treated as relative to the current source directory.

    The given directory must be known to CMake, being either the top-level
    directory or one added by :command:`add_subdirectory`.  Furthermore,
    the given directory must not yet be finished processing.  This means
    it can be the current directory or one of its ancestors.

  ``ID <id>``
    Specify an identification for the deferred call.
    The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``.
    The ``<id>`` may begin with an underscore (``_``) only if it was generated
    automatically by an earlier call that used ``ID_VAR`` to get the id.

  ``ID_VAR <var>``
    Specify a variable in which to store the identification for the
    deferred call.  If ``ID <id>`` is not given, a new identification
    will be generated and the generated id will start with an underscore (``_``).

  The currently scheduled list of deferred calls may be retrieved:

  .. code-block:: cmake

    cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)

  This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
  Lists>` of deferred call ids.  The ids are for the directory scope in which
  the calls have been deferred to (i.e. where they will be executed), which can
  be different to the scope in which they were created.  The ``DIRECTORY``
  option can be used to specify the scope for which to retrieve the call ids.
  If that option is not given, the call ids for the current directory scope
  will be returned.

  Details of a specific call may be retrieved from its id:

  .. code-block:: cmake

    cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)

  This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
  Lists>` in which the first element is the name of the command to be
  called, and the remaining elements are its unevaluated arguments (any
  contained ``;`` characters are included literally and cannot be distinguished
  from multiple arguments).  If multiple calls are scheduled with the same id,
  this retrieves the first one.  If no call is scheduled with the given id in
  the specified ``DIRECTORY`` scope (or the current directory scope if no
  ``DIRECTORY`` option is given), this stores an empty string in the variable.

  Deferred calls may be canceled by their id:

  .. code-block:: cmake

    cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)

  This cancels all deferred calls matching any of the given ids in the specified
  ``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option
  is given).  Unknown ids are silently ignored.

Deferred Call Examples
""""""""""""""""""""""

For example, the code:

.. code-block:: cmake

  cmake_language(DEFER CALL message "${deferred_message}")
  cmake_language(DEFER ID_VAR id CALL message "Canceled Message")
  cmake_language(DEFER CANCEL_CALL ${id})
  message("Immediate Message")
  set(deferred_message "Deferred Message")

prints::

  Immediate Message
  Deferred Message

The ``Canceled Message`` is never printed because its command is
canceled.  The ``deferred_message`` variable reference is not evaluated
until the call site, so it can be set after the deferred call is scheduled.

In order to evaluate variable references immediately when scheduling a
deferred call, wrap it using ``cmake_language(EVAL)``.  However, note that
arguments will be re-evaluated in the deferred call, though that can be
avoided by using bracket arguments.  For example:

.. code-block:: cmake

  set(deferred_message "Deferred Message 1")
  set(re_evaluated [[${deferred_message}]])
  cmake_language(EVAL CODE "
    cmake_language(DEFER CALL message [[${deferred_message}]])
    cmake_language(DEFER CALL message \"${re_evaluated}\")
  ")
  message("Immediate Message")
  set(deferred_message "Deferred Message 2")

also prints::

  Immediate Message
  Deferred Message 1
  Deferred Message 2

.. _dependency_providers:

Dependency Providers
^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.24

.. note:: A high-level introduction to this feature can be found in the
          :ref:`Using Dependencies Guide <dependency_providers_overview>`.

.. signature::
  cmake_language(SET_DEPENDENCY_PROVIDER <command>
                 SUPPORTED_METHODS <methods>...)

  When a call is made to :command:`find_package` or
  :command:`FetchContent_MakeAvailable`, the call may be forwarded to a
  dependency provider which then has the opportunity to fulfill the request.
  If the request is for one of the ``<methods>`` specified when the provider
  was set, CMake calls the provider's ``<command>`` with a set of
  method-specific arguments.  If the provider does not fulfill the request,
  or if the provider doesn't support the request's method, or no provider
  is set, the built-in :command:`find_package` or
  :command:`FetchContent_MakeAvailable` implementation is used to fulfill
  the request in the usual way.

  One or more of the following values can be specified for the ``<methods>``
  when setting the provider:

  ``FIND_PACKAGE``
    The provider command accepts :command:`find_package` requests.

  ``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
    The provider command accepts :command:`FetchContent_MakeAvailable`
    requests.  It expects each dependency to be fed to the provider command
    one at a time, not the whole list in one go.

  Only one provider can be set at any point in time.  If a provider is already
  set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new
  provider replaces the previously set one.  The specified ``<command>`` must
  already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called.
  As a special case, providing an empty string for the ``<command>`` and no
  ``<methods>`` will discard any previously set provider.

  The dependency provider can only be set while processing one of the files
  specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable.
  Thus, dependency providers can only be set as part of the first call to
  :command:`project`.  Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
  outside of that context will result in an error.

  .. note::
    The choice of dependency provider should always be under the user's control.
    As a convenience, a project may choose to provide a file that users can
    list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but
    the use of such a file should always be the user's choice.

Provider commands
"""""""""""""""""

Providers define a single ``<command>`` to accept requests.  The name of
the command should be specific to that provider, not something overly
generic that another provider might also use.  This enables users to compose
different providers in their own custom provider.  The recommended form is
``xxx_provide_dependency()``, where ``xxx`` is the provider-specific part
(e.g. ``vcpkg_provide_dependency()``, ``conan_provide_dependency()``,
``ourcompany_provide_dependency()``, and so on).

.. code-block:: cmake

  xxx_provide_dependency(<method> [<method-specific-args>...])

Because some methods expect certain variables to be set in the calling scope,
the provider command should typically be implemented as a macro rather than a
function.  This ensures it does not introduce a new variable scope.

The arguments CMake passes to the dependency provider depend on the type of
request.  The first argument is always the method, and it will only ever
be one of the ``<methods>`` that was specified when setting the provider.

``FIND_PACKAGE``
  The ``<method-specific-args>`` will be everything passed to the
  :command:`find_package` call that requested the dependency.  The first of
  these ``<method-specific-args>`` will therefore always be the name of the
  dependency.  Dependency names are case-sensitive for this method because
  :command:`find_package` treats them case-sensitively too.

  If the provider command fulfills the request, it must set the same variable
  that :command:`find_package` expects to be set.  For a dependency named
  ``depName``, the provider must set ``depName_FOUND`` to true if it fulfilled
  the request.  If the provider returns without setting this variable, CMake
  will assume the request was not fulfilled and will fall back to the
  built-in implementation.

  If the provider needs to call the built-in :command:`find_package`
  implementation as part of its processing, it can do so by including the
  ``BYPASS_PROVIDER`` keyword as one of the arguments.

``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
  The ``<method-specific-args>`` will be everything passed to the
  :command:`FetchContent_Declare` call that corresponds to the requested
  dependency, with the following exceptions:

  * If ``SOURCE_DIR`` or ``BINARY_DIR`` were not part of the original
    declared arguments, they will be added with their default values.
  * If :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` is set to ``NEVER``,
    any ``FIND_PACKAGE_ARGS`` will be omitted.
  * The ``OVERRIDE_FIND_PACKAGE`` keyword is always omitted.

  The first of the ``<method-specific-args>`` will always be the name of the
  dependency.  Dependency names are case-insensitive for this method because
  :module:`FetchContent` also treats them case-insensitively.

  If the provider fulfills the request, it should call
  :command:`FetchContent_SetPopulated`, passing the name of the dependency as
  the first argument.  The ``SOURCE_DIR`` and ``BINARY_DIR`` arguments to that
  command should only be given if the provider makes the dependency's source
  and build directories available in exactly the same way as the built-in
  :command:`FetchContent_MakeAvailable` command.

  If the provider returns without calling :command:`FetchContent_SetPopulated`
  for the named dependency, CMake will assume the request was not fulfilled
  and will fall back to the built-in implementation.

  Note that empty arguments may be significant for this method (e.g. an empty
  string following a ``GIT_SUBMODULES`` keyword).  Therefore, if forwarding
  these arguments on to another command, extra care must be taken to avoid such
  arguments being silently dropped.

  If ``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` is set, then the
  dependency provider will never see requests for the ``<depName>`` dependency
  for this method. When the user sets such a variable, they are explicitly
  overriding where to get that dependency from and are taking on the
  responsibility that their overriding version meets any requirements for that
  dependency and is compatible with whatever else in the project uses it.
  Depending on the value of :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE`
  and whether the ``OVERRIDE_FIND_PACKAGE`` option was given to
  :command:`FetchContent_Declare`, having
  ``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` set may also prevent the
  dependency provider from seeing requests for a ``find_package(depName)``
  call too.

Provider Examples
"""""""""""""""""

This first example only intercepts :command:`find_package` calls.  The
provider command runs an external tool which copies the relevant artifacts
into a provider-specific directory, if that tool knows about the dependency.
It then relies on the built-in implementation to then find those artifacts.
:command:`FetchContent_MakeAvailable` calls would not go through the provider.

.. code-block:: cmake
  :caption: mycomp_provider.cmake

  # Always ensure we have the policy settings this provider expects
  cmake_minimum_required(VERSION 3.24)

  set(MYCOMP_PROVIDER_INSTALL_DIR ${CMAKE_BINARY_DIR}/mycomp_packages
    CACHE PATH "The directory this provider installs packages to"
  )
  # Tell the built-in implementation to look in our area first, unless
  # the find_package() call uses NO_..._PATH options to exclude it
  list(APPEND CMAKE_MODULE_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}/cmake)
  list(APPEND CMAKE_PREFIX_PATH ${MYCOMP_PROVIDER_INSTALL_DIR})

  macro(mycomp_provide_dependency method package_name)
    execute_process(
      COMMAND some_tool ${package_name} --installdir ${MYCOMP_PROVIDER_INSTALL_DIR}
      COMMAND_ERROR_IS_FATAL ANY
    )
  endmacro()

  cmake_language(
    SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
    SUPPORTED_METHODS FIND_PACKAGE
  )

The user would then typically use the above file like so::

  cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ...

The next example demonstrates a provider that accepts both methods, but
only handles one specific dependency.  It enforces providing Google Test
using :module:`FetchContent`, but leaves all other dependencies to be
fulfilled by CMake's built-in implementation.  It accepts a few different
names, which demonstrates one way of working around projects that hard-code
an unusual or undesirable way of adding this particular dependency to the
build.  The example also demonstrates how to use the :command:`list` command
to preserve variables that may be overwritten by a call to
:command:`FetchContent_MakeAvailable`.

.. code-block:: cmake
  :caption: mycomp_provider.cmake

  cmake_minimum_required(VERSION 3.24)

  # Because we declare this very early, it will take precedence over any
  # details the project might declare later for the same thing
  include(FetchContent)
  FetchContent_Declare(
    googletest
    GIT_REPOSITORY https://github.com/google/googletest.git
    GIT_TAG        e2239ee6043f73722e7aa812a459f54a28552929 # release-1.11.0
  )

  # Both FIND_PACKAGE and FETCHCONTENT_MAKEAVAILABLE_SERIAL methods provide
  # the package or dependency name as the first method-specific argument.
  macro(mycomp_provide_dependency method dep_name)
    if("${dep_name}" MATCHES "^(gtest|googletest)$")
      # Save our current command arguments in case we are called recursively
      list(APPEND mycomp_provider_args ${method} ${dep_name})

      # This will forward to the built-in FetchContent implementation,
      # which detects a recursive call for the same thing and avoids calling
      # the provider again if dep_name is the same as the current call.
      FetchContent_MakeAvailable(googletest)

      # Restore our command arguments
      list(POP_BACK mycomp_provider_args dep_name method)

      # Tell the caller we fulfilled the request
      if("${method}" STREQUAL "FIND_PACKAGE")
        # We need to set this if we got here from a find_package() call
        # since we used a different method to fulfill the request.
        # This example assumes projects only use the gtest targets,
        # not any of the variables the FindGTest module may define.
        set(${dep_name}_FOUND TRUE)
      elseif(NOT "${dep_name}" STREQUAL "googletest")
        # We used the same method, but were given a different name to the
        # one we populated with. Tell the caller about the name it used.
        FetchContent_SetPopulated(${dep_name}
          SOURCE_DIR "${googletest_SOURCE_DIR}"
          BINARY_DIR "${googletest_BINARY_DIR}"
        )
      endif()
    endif()
  endmacro()

  cmake_language(
    SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
    SUPPORTED_METHODS
      FIND_PACKAGE
      FETCHCONTENT_MAKEAVAILABLE_SERIAL
  )

The final example demonstrates how to modify arguments to a
:command:`find_package` call.  It forces all such calls to have the
``QUIET`` keyword.  It uses the ``BYPASS_PROVIDER`` keyword to prevent
calling the provider command recursively for the same dependency.

.. code-block:: cmake
  :caption: mycomp_provider.cmake

  cmake_minimum_required(VERSION 3.24)

  macro(mycomp_provide_dependency method)
    find_package(${ARGN} BYPASS_PROVIDER QUIET)
  endmacro()

  cmake_language(
    SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
    SUPPORTED_METHODS FIND_PACKAGE
  )

Getting current message log level
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.25

.. _query_message_log_level:

.. signature::
  cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)

  Writes the current :command:`message` logging level
  into the given ``<output_variable>``.

  See :command:`message` for the possible logging levels.

  The current message logging level can be set either using the
  :option:`--log-level <cmake --log-level>`
  command line option of the :manual:`cmake(1)` program or using
  the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable.

  If both the command line option and the variable are set, the command line
  option takes precedence. If neither are set, the default logging level
  is returned.

Terminating Scripts
^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.29

.. signature::
  cmake_language(EXIT <exit-code>)

  Terminate the current :option:`cmake -P` script and exit with ``<exit-code>``.

  This command works only in :ref:`script mode <Script Processing Mode>`.

  The ``<exit-code>`` should be non-negative.
  If ``<exit-code>`` is negative then the behavior
  is unspecified (e.g., on Windows the error code -1
  becomes ``0xffffffff``, and on Linux it becomes ``255``).


code:
cmake_minimum_required
----------------------

Require a minimum version of cmake.

.. code-block:: cmake

  cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR])

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

Sets the minimum required version of cmake for a project.
Also updates the policy settings as explained below.

``<min>`` and the optional ``<policy_max>`` are each CMake versions of the
form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal.

If the running version of CMake is lower than the ``<min>`` required
version it will stop processing the project and report an error.
The optional ``<policy_max>`` version, if specified, must be at least the
``<min>`` version and affects policy settings as described in `Policy Settings`_.
If the running version of CMake is older than 3.12, the extra ``...``
dots will be seen as version component separators, resulting in the
``...<max>`` part being ignored and preserving the pre-3.12 behavior
of basing policies on ``<min>``.

This command will set the value of the
:variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable to ``<min>``.

The ``FATAL_ERROR`` option is accepted but ignored by CMake 2.6 and
higher.  It should be specified so CMake versions 2.4 and lower fail
with an error instead of just a warning.

.. note::
  Call the ``cmake_minimum_required()`` command at the beginning of
  the top-level ``CMakeLists.txt`` file even before calling the
  :command:`project` command.  It is important to establish version
  and policy settings before invoking other commands whose behavior
  they may affect.  See also policy :policy:`CMP0000`.

  Calling ``cmake_minimum_required()`` inside a :command:`function`
  limits some effects to the function scope when invoked.  For example,
  the :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable won't be set
  in the calling scope.  Functions do not introduce their own policy
  scope though, so policy settings of the caller *will* be affected
  (see below).  Due to this mix of things that do and do not affect the
  calling scope, calling ``cmake_minimum_required()`` inside a function
  is generally discouraged.

.. _`Policy Settings`:

Policy Settings
^^^^^^^^^^^^^^^

The ``cmake_minimum_required(VERSION)`` command implicitly invokes the
:command:`cmake_policy(VERSION)` command to specify that the current
project code is written for the given range of CMake versions.
All policies known to the running version of CMake and introduced
in the ``<min>`` (or ``<max>``, if specified) version or earlier will
be set to use ``NEW`` behavior.  All policies introduced in later
versions will be unset.  This effectively requests behavior preferred
as of a given CMake version and tells newer CMake versions to warn
about their new policies.

When a ``<min>`` version higher than 2.4 is specified the command
implicitly invokes

.. code-block:: cmake

  cmake_policy(VERSION <min>[...<max>])

which sets CMake policies based on the range of versions specified.
When a ``<min>`` version 2.4 or lower is given the command implicitly
invokes

.. code-block:: cmake

  cmake_policy(VERSION 2.4[...<max>])

which enables compatibility features for CMake 2.4 and lower.

.. include:: DEPRECATED_POLICY_VERSIONS.txt

See Also
^^^^^^^^

* :command:`cmake_policy`


code:
cmake_parse_arguments
---------------------

Parse function or macro arguments.

.. code-block:: cmake

  cmake_parse_arguments(<prefix> <options> <one_value_keywords>
                        <multi_value_keywords> <args>...)

  cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
                        <one_value_keywords> <multi_value_keywords>)

.. versionadded:: 3.5
  This command is implemented natively.  Previously, it has been defined in the
  module :module:`CMakeParseArguments`.

This command is for use in macros or functions.
It processes the arguments given to that macro or function,
and defines a set of variables which hold the values of the
respective options.

The first signature reads processes arguments passed in the ``<args>...``.
This may be used in either a :command:`macro` or a :command:`function`.

.. versionadded:: 3.7
  The ``PARSE_ARGV`` signature is only for use in a :command:`function`
  body.  In this case the arguments that are parsed come from the
  ``ARGV#`` variables of the calling function.  The parsing starts with
  the ``<N>``-th argument, where ``<N>`` is an unsigned integer.
  This allows for the values to have special characters like ``;`` in them.

The ``<options>`` argument contains all options for the respective macro,
i.e.  keywords which can be used when calling the macro without any value
following, like e.g.  the ``OPTIONAL`` keyword of the :command:`install`
command.

The ``<one_value_keywords>`` argument contains all keywords for this macro
which are followed by one value, like e.g. ``DESTINATION`` keyword of the
:command:`install` command.

The ``<multi_value_keywords>`` argument contains all keywords for this
macro which can be followed by more than one value, like e.g. the
``TARGETS`` or ``FILES`` keywords of the :command:`install` command.

.. versionchanged:: 3.5
  All keywords shall be unique. I.e. every keyword shall only be specified
  once in either ``<options>``, ``<one_value_keywords>`` or
  ``<multi_value_keywords>``. A warning will be emitted if uniqueness is
  violated.

When done, ``cmake_parse_arguments`` will consider for each of the
keywords listed in ``<options>``, ``<one_value_keywords>`` and
``<multi_value_keywords>`` a variable composed of the given ``<prefix>``
followed by ``"_"`` and the name of the respective keyword.  These
variables will then hold the respective value from the argument list
or be undefined if the associated option could not be found.
For the ``<options>`` keywords, these will always be defined,
to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not.

All remaining arguments are collected in a variable
``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments
were recognized. This can be checked afterwards to see
whether your macro was called with unrecognized parameters.

.. versionadded:: 3.15
   ``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no
   values at all are collected in a variable
   ``<prefix>_KEYWORDS_MISSING_VALUES`` that will be undefined if all keywords
   received values. This can be checked to see if there were keywords without
   any values given.

Consider the following example macro, ``my_install()``, which takes similar
arguments to the real :command:`install` command:

.. code-block:: cmake

   macro(my_install)
       set(options OPTIONAL FAST)
       set(oneValueArgs DESTINATION RENAME)
       set(multiValueArgs TARGETS CONFIGURATIONS)
       cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
                             "${multiValueArgs}" ${ARGN} )

       # ...

Assume ``my_install()`` has been called like this:

.. code-block:: cmake

   my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)

After the ``cmake_parse_arguments`` call the macro will have set or undefined
the following variables::

   MY_INSTALL_OPTIONAL = TRUE
   MY_INSTALL_FAST = FALSE # was not used in call to my_install
   MY_INSTALL_DESTINATION = "bin"
   MY_INSTALL_RENAME <UNDEFINED> # was not used
   MY_INSTALL_TARGETS = "foo;bar"
   MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
   MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
   MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
            # No value for "CONFIGURATIONS" given

You can then continue and process these variables.

Keywords terminate lists of values, e.g. if directly after a
``one_value_keyword`` another recognized keyword follows, this is
interpreted as the beginning of the new option.  E.g.
``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in
``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL``
is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added
to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will
therefore be set to ``TRUE``.

See Also
^^^^^^^^

* :command:`function`
* :command:`macro`


code:
cmake_path
----------

.. versionadded:: 3.20

This command is for the manipulation of paths.  Only syntactic aspects of
paths are handled, there is no interaction of any kind with any underlying
file system.  The path may represent a non-existing path or even one that
is not allowed to exist on the current file system or platform.
For operations that do interact with the filesystem, see the :command:`file`
command.

.. note::

  The ``cmake_path`` command handles paths in the format of the build system
  (i.e. the host platform), not the target system.  When cross-compiling,
  if the path contains elements that are not representable on the host
  platform (e.g. a drive letter when the host is not Windows), the results
  will be unpredictable.

Synopsis
^^^^^^^^

.. parsed-literal::

  `Conventions`_

  `Path Structure And Terminology`_

  `Normalization`_

  `Decomposition`_
    cmake_path(`GET`_ <path-var> :ref:`ROOT_NAME <GET_ROOT_NAME>` <out-var>)
    cmake_path(`GET`_ <path-var> :ref:`ROOT_DIRECTORY <GET_ROOT_DIRECTORY>` <out-var>)
    cmake_path(`GET`_ <path-var> :ref:`ROOT_PATH <GET_ROOT_PATH>` <out-var>)
    cmake_path(`GET`_ <path-var> :ref:`FILENAME <GET_FILENAME>` <out-var>)
    cmake_path(`GET`_ <path-var> :ref:`EXTENSION <GET_EXTENSION>` [LAST_ONLY] <out-var>)
    cmake_path(`GET`_ <path-var> :ref:`STEM <GET_STEM>` [LAST_ONLY] <out-var>)
    cmake_path(`GET`_ <path-var> :ref:`RELATIVE_PART <GET_RELATIVE_PART>` <out-var>)
    cmake_path(`GET`_ <path-var> :ref:`PARENT_PATH <GET_PARENT_PATH>` <out-var>)

  `Query`_
    cmake_path(`HAS_ROOT_NAME`_ <path-var> <out-var>)
    cmake_path(`HAS_ROOT_DIRECTORY`_ <path-var> <out-var>)
    cmake_path(`HAS_ROOT_PATH`_ <path-var> <out-var>)
    cmake_path(`HAS_FILENAME`_ <path-var> <out-var>)
    cmake_path(`HAS_EXTENSION`_ <path-var> <out-var>)
    cmake_path(`HAS_STEM`_ <path-var> <out-var>)
    cmake_path(`HAS_RELATIVE_PART`_ <path-var> <out-var>)
    cmake_path(`HAS_PARENT_PATH`_ <path-var> <out-var>)
    cmake_path(`IS_ABSOLUTE`_ <path-var> <out-var>)
    cmake_path(`IS_RELATIVE`_ <path-var> <out-var>)
    cmake_path(`IS_PREFIX`_ <path-var> <input> [NORMALIZE] <out-var>)
    cmake_path(`COMPARE`_ <input1> <OP> <input2> <out-var>)

  `Modification`_
    cmake_path(:ref:`SET <cmake_path-SET>` <path-var> [NORMALIZE] <input>)
    cmake_path(`APPEND`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
    cmake_path(`APPEND_STRING`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
    cmake_path(`REMOVE_FILENAME`_ <path-var> [OUTPUT_VARIABLE <out-var>])
    cmake_path(`REPLACE_FILENAME`_ <path-var> <input> [OUTPUT_VARIABLE <out-var>])
    cmake_path(`REMOVE_EXTENSION`_ <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>])
    cmake_path(`REPLACE_EXTENSION`_ <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>])

  `Generation`_
    cmake_path(`NORMAL_PATH`_ <path-var> [OUTPUT_VARIABLE <out-var>])
    cmake_path(`RELATIVE_PATH`_ <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>])
    cmake_path(`ABSOLUTE_PATH`_ <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>])

  `Native Conversion`_
    cmake_path(`NATIVE_PATH`_ <path-var> [NORMALIZE] <out-var>)
    cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST`_ <out-var> [NORMALIZE])
    cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST`_ <out-var> [NORMALIZE])

  `Hashing`_
    cmake_path(`HASH`_ <path-var> <out-var>)

Conventions
^^^^^^^^^^^

The following conventions are used in this command's documentation:

``<path-var>``
  Always the name of a variable.  For commands that expect a ``<path-var>``
  as input, the variable must exist and it is expected to hold a single path.

``<input>``
  A string literal which may contain a path, path fragment, or multiple paths
  with a special separator depending on the command.  See the description of
  each command to see how this is interpreted.

``<input>...``
  Zero or more string literal arguments.

``<out-var>``
  The name of a variable into which the result of a command will be written.

.. _Path Structure And Terminology:

Path Structure And Terminology
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A path has the following structure (all components are optional, with some
constraints):

::

  root-name root-directory-separator (item-name directory-separator)* filename

``root-name``
  Identifies the root on a filesystem with multiple roots (such as ``"C:"``
  or ``"//myserver"``). It is optional.

``root-directory-separator``
  A directory separator that, if present, indicates that this path is
  absolute.  If it is missing and the first element other than the
  ``root-name`` is an ``item-name``, then the path is relative.

``item-name``
  A sequence of characters that aren't directory separators.  This name may
  identify a file, a hard link, a symbolic link, or a directory.  Two special
  cases are recognized:

    * The item name consisting of a single dot character ``.`` is a
      directory name that refers to the current directory.

    * The item name consisting of two dot characters ``..`` is a
      directory name that refers to the parent directory.

  The ``(...)*`` pattern shown above is to indicate that there can be zero
  or more item names, with multiple items separated by a
  ``directory-separator``.  The ``()*`` characters are not part of the path.

``directory-separator``
  The only recognized directory separator is a forward slash character ``/``.
  If this character is repeated, it is treated as a single directory
  separator.  In other words, ``/usr///////lib`` is the same as ``/usr/lib``.

.. _FILENAME_DEF:
.. _EXTENSION_DEF:
.. _STEM_DEF:

``filename``
  A path has a ``filename`` if it does not end with a ``directory-separator``.
  The ``filename`` is effectively the last ``item-name`` of the path, so it
  can also be a hard link, symbolic link or a directory.

  A ``filename`` can have an *extension*.  By default, the extension is
  defined as the sub-string beginning at the left-most period (including
  the period) and until the end of the ``filename``.  In commands that
  accept a ``LAST_ONLY`` keyword, ``LAST_ONLY`` changes the interpretation
  to the sub-string beginning at the right-most period.

  The following exceptions apply to the above interpretation:

    * If the first character in the ``filename`` is a period, that period is
      ignored (i.e. a ``filename`` like ``".profile"`` is treated as having
      no extension).

    * If the ``filename`` is either ``.`` or ``..``, it has no extension.

  The *stem* is the part of the ``filename`` before the extension.

Some commands refer to a ``root-path``.  This is the concatenation of
``root-name`` and ``root-directory-separator``, either or both of which can
be empty.  A ``relative-part`` refers to the full path with any ``root-path``
removed.

Creating A Path Variable
^^^^^^^^^^^^^^^^^^^^^^^^

While a path can be created with care using an ordinary :command:`set`
command, it is recommended to use :ref:`cmake_path(SET) <cmake_path-SET>`
instead, as it automatically converts the path to the required form where
required.  The :ref:`cmake_path(APPEND) <APPEND>` subcommand may
be another suitable alternative where a path needs to be constructed by
joining fragments.  The following example compares the three methods for
constructing the same path:

.. code-block:: cmake

  set(path1 "${CMAKE_CURRENT_SOURCE_DIR}/data")

  cmake_path(SET path2 "${CMAKE_CURRENT_SOURCE_DIR}/data")

  cmake_path(APPEND path3 "${CMAKE_CURRENT_SOURCE_DIR}" "data")

`Modification`_ and `Generation`_ sub-commands can either store the result
in-place, or in a separate variable named after an ``OUTPUT_VARIABLE``
keyword.  All other sub-commands store the result in a mandatory ``<out-var>``
variable.

.. _Normalization:

Normalization
^^^^^^^^^^^^^

Some sub-commands support *normalizing* a path.  The algorithm used to
normalize a path is as follows:

1. If the path is empty, stop (the normalized form of an empty path is
   also an empty path).
2. Replace each ``directory-separator``, which may consist of multiple
   separators, with a single ``/`` (``/a///b  --> /a/b``).
3. Remove each solitary period (``.``) and any immediately following
   ``directory-separator`` (``/a/./b/. --> /a/b``).
4. Remove each ``item-name`` (other than ``..``) that is immediately
   followed by a ``directory-separator`` and a ``..``, along with any
   immediately following ``directory-separator`` (``/a/b/../c --> a/c``).
5. If there is a ``root-directory``, remove any ``..`` and any
   ``directory-separators`` immediately following them.  The parent of the
   root directory is treated as still the root directory (``/../a --> /a``).
6. If the last ``item-name`` is ``..``, remove any trailing
   ``directory-separator`` (``../ --> ..``).
7. If the path is empty by this stage, add a ``dot`` (normal form of ``./``
   is ``.``).

.. _Path Decomposition:

Decomposition
^^^^^^^^^^^^^

.. _GET:
.. _GET_ROOT_NAME:
.. _GET_ROOT_DIRECTORY:
.. _GET_ROOT_PATH:
.. _GET_FILENAME:
.. _GET_EXTENSION:
.. _GET_STEM:
.. _GET_RELATIVE_PART:
.. _GET_PARENT_PATH:

The following forms of the ``GET`` subcommand each retrieve a different
component or group of components from a path.  See
`Path Structure And Terminology`_ for the meaning of each path component.

.. code-block:: cmake

  cmake_path(GET <path-var> ROOT_NAME <out-var>)
  cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
  cmake_path(GET <path-var> ROOT_PATH <out-var>)
  cmake_path(GET <path-var> FILENAME <out-var>)
  cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
  cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
  cmake_path(GET <path-var> RELATIVE_PART <out-var>)
  cmake_path(GET <path-var> PARENT_PATH <out-var>)

If a requested component is not present in the path, an empty string will be
stored in ``<out-var>``.  For example, only Windows systems have the concept
of a ``root-name``, so when the host machine is non-Windows, the ``ROOT_NAME``
subcommand will always return an empty string.

For ``PARENT_PATH``, if the `HAS_RELATIVE_PART`_ subcommand returns false,
the result is a copy of ``<path-var>``.  Note that this implies that a root
directory is considered to have a parent, with that parent being itself.
Where `HAS_RELATIVE_PART`_ returns true, the result will essentially be
``<path-var>`` with one less element.

Root examples
"""""""""""""

.. code-block:: cmake

  set(path "c:/a")

  cmake_path(GET path ROOT_NAME rootName)
  cmake_path(GET path ROOT_DIRECTORY rootDir)
  cmake_path(GET path ROOT_PATH rootPath)

  message("Root name is \"${rootName}\"")
  message("Root directory is \"${rootDir}\"")
  message("Root path is \"${rootPath}\"")

::

  Root name is "c:"
  Root directory is "/"
  Root path is "c:/"

Filename examples
"""""""""""""""""

.. code-block:: cmake

  set(path "/a/b")
  cmake_path(GET path FILENAME filename)
  message("First filename is \"${filename}\"")

  # Trailing slash means filename is empty
  set(path "/a/b/")
  cmake_path(GET path FILENAME filename)
  message("Second filename is \"${filename}\"")

::

  First filename is "b"
  Second filename is ""

Extension and stem examples
"""""""""""""""""""""""""""

.. code-block:: cmake

  set(path "name.ext1.ext2")

  cmake_path(GET path EXTENSION fullExt)
  cmake_path(GET path STEM fullStem)
  message("Full extension is \"${fullExt}\"")
  message("Full stem is \"${fullStem}\"")

  # Effect of LAST_ONLY
  cmake_path(GET path EXTENSION LAST_ONLY lastExt)
  cmake_path(GET path STEM LAST_ONLY lastStem)
  message("Last extension is \"${lastExt}\"")
  message("Last stem is \"${lastStem}\"")

  # Special cases
  set(dotPath "/a/.")
  set(dotDotPath "/a/..")
  set(someMorePath "/a/.some.more")
  cmake_path(GET dotPath EXTENSION dotExt)
  cmake_path(GET dotPath STEM dotStem)
  cmake_path(GET dotDotPath EXTENSION dotDotExt)
  cmake_path(GET dotDotPath STEM dotDotStem)
  cmake_path(GET dotMorePath EXTENSION someMoreExt)
  cmake_path(GET dotMorePath STEM someMoreStem)
  message("Dot extension is \"${dotExt}\"")
  message("Dot stem is \"${dotStem}\"")
  message("Dot-dot extension is \"${dotDotExt}\"")
  message("Dot-dot stem is \"${dotDotStem}\"")
  message(".some.more extension is \"${someMoreExt}\"")
  message(".some.more stem is \"${someMoreStem}\"")

::

  Full extension is ".ext1.ext2"
  Full stem is "name"
  Last extension is ".ext2"
  Last stem is "name.ext1"
  Dot extension is ""
  Dot stem is "."
  Dot-dot extension is ""
  Dot-dot stem is ".."
  .some.more extension is ".more"
  .some.more stem is ".some"

Relative part examples
""""""""""""""""""""""

.. code-block:: cmake

  set(path "c:/a/b")
  cmake_path(GET path RELATIVE_PART result)
  message("Relative part is \"${result}\"")

  set(path "c/d")
  cmake_path(GET path RELATIVE_PART result)
  message("Relative part is \"${result}\"")

  set(path "/")
  cmake_path(GET path RELATIVE_PART result)
  message("Relative part is \"${result}\"")

::

  Relative part is "a/b"
  Relative part is "c/d"
  Relative part is ""

Path traversal examples
"""""""""""""""""""""""

.. code-block:: cmake

  set(path "c:/a/b")
  cmake_path(GET path PARENT_PATH result)
  message("Parent path is \"${result}\"")

  set(path "c:/")
  cmake_path(GET path PARENT_PATH result)
  message("Parent path is \"${result}\"")

::

  Parent path is "c:/a"
  Parent path is "c:/"

.. _Path Query:

Query
^^^^^

Each of the ``GET`` subcommands has a corresponding ``HAS_...``
subcommand which can be used to discover whether a particular path
component is present.  See `Path Structure And Terminology`_ for the
meaning of each path component.

.. _HAS_ROOT_NAME:
.. _HAS_ROOT_DIRECTORY:
.. _HAS_ROOT_PATH:
.. _HAS_FILENAME:
.. _HAS_EXTENSION:
.. _HAS_STEM:
.. _HAS_RELATIVE_PART:
.. _HAS_PARENT_PATH:

.. code-block:: cmake

  cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
  cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
  cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
  cmake_path(HAS_FILENAME <path-var> <out-var>)
  cmake_path(HAS_EXTENSION <path-var> <out-var>)
  cmake_path(HAS_STEM <path-var> <out-var>)
  cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
  cmake_path(HAS_PARENT_PATH <path-var> <out-var>)

Each of the above follows the predictable pattern of setting ``<out-var>``
to true if the path has the associated component, or false otherwise.
Note the following special cases:

* For ``HAS_ROOT_PATH``, a true result will only be returned if at least one
  of ``root-name`` or ``root-directory`` is non-empty.

* For ``HAS_PARENT_PATH``, the root directory is also considered to have a
  parent, which will be itself.  The result is true except if the path
  consists of just a :ref:`filename <FILENAME_DEF>`.

.. _IS_ABSOLUTE:

.. code-block:: cmake

  cmake_path(IS_ABSOLUTE <path-var> <out-var>)

Sets ``<out-var>`` to true if ``<path-var>`` is absolute.  An absolute path
is a path that unambiguously identifies the location of a file without
reference to an additional starting location.  On Windows, this means the
path must have both a ``root-name`` and a ``root-directory-separator`` to be
considered absolute.  On other platforms, just a ``root-directory-separator``
is sufficient.  Note that this means on Windows, ``IS_ABSOLUTE`` can be
false while ``HAS_ROOT_DIRECTORY`` can be true.

.. _IS_RELATIVE:

.. code-block:: cmake

  cmake_path(IS_RELATIVE <path-var> <out-var>)

This will store the opposite of ``IS_ABSOLUTE`` in ``<out-var>``.

.. _IS_PREFIX:

.. code-block:: cmake

  cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)

Checks if ``<path-var>`` is the prefix of ``<input>``.

When the ``NORMALIZE`` option is specified, ``<path-var>`` and ``<input>``
are :ref:`normalized <Normalization>` before the check.

.. code-block:: cmake

  set(path "/a/b/c")
  cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true
  cmake_path(IS_PREFIX path "/a/b" result)     # result = false
  cmake_path(IS_PREFIX path "/x/y/z" result)   # result = false

  set(path "/a/b")
  cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result)   # result = true

.. _Path COMPARE:
.. _COMPARE:

.. code-block:: cmake

  cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)
  cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)

Compares the lexical representations of two paths provided as string literals.
No normalization is performed on either path, except multiple consecutive
directory separators are effectively collapsed into a single separator.
Equality is determined according to the following pseudo-code logic:

::

  if(NOT <input1>.root_name() STREQUAL <input2>.root_name())
    return FALSE

  if(<input1>.has_root_directory() XOR <input2>.has_root_directory())
    return FALSE

  Return FALSE if a relative portion of <input1> is not lexicographically
  equal to the relative portion of <input2>. This comparison is performed path
  component-wise. If all of the components compare equal, then return TRUE.

.. note::
  Unlike most other ``cmake_path()`` subcommands, the ``COMPARE`` subcommand
  takes literal strings as input, not the names of variables.

.. _Path Modification:

Modification
^^^^^^^^^^^^

.. _cmake_path-SET:

.. code-block:: cmake

  cmake_path(SET <path-var> [NORMALIZE] <input>)

Assign the ``<input>`` path to ``<path-var>``.  If ``<input>`` is a native
path, it is converted into a cmake-style path with forward-slashes
(``/``). On Windows, the long filename marker is taken into account.

When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` after the conversion.

For example:

.. code-block:: cmake

  set(native_path "c:\\a\\b/..\\c")
  cmake_path(SET path "${native_path}")
  message("CMake path is \"${path}\"")

  cmake_path(SET path NORMALIZE "${native_path}")
  message("Normalized CMake path is \"${path}\"")

Output::

  CMake path is "c:/a/b/../c"
  Normalized CMake path is "c:/a/c"

.. _APPEND:

.. code-block:: cmake

  cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])

Append all the ``<input>`` arguments to the ``<path-var>`` using ``/`` as
the ``directory-separator``.  Depending on the ``<input>``, the previous
contents of ``<path-var>`` may be discarded.  For each ``<input>`` argument,
the following algorithm (pseudo-code) applies:

::

  # <path> is the contents of <path-var>

  if(<input>.is_absolute() OR
     (<input>.has_root_name() AND
      NOT <input>.root_name() STREQUAL <path>.root_name()))
    replace <path> with <input>
    return()
  endif()

  if(<input>.has_root_directory())
    remove any root-directory and the entire relative path from <path>
  elseif(<path>.has_filename() OR
         (NOT <path-var>.has_root_directory() OR <path>.is_absolute()))
    append directory-separator to <path>
  endif()

  append <input> omitting any root-name to <path>

.. _APPEND_STRING:

.. code-block:: cmake

  cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])

Append all the ``<input>`` arguments to the ``<path-var>`` without adding any
``directory-separator``.

.. _REMOVE_FILENAME:

.. code-block:: cmake

  cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])

Removes the :ref:`filename <FILENAME_DEF>` component (as returned by
:ref:`GET ... FILENAME <GET_FILENAME>`) from ``<path-var>``.  After removal,
any trailing ``directory-separator`` is left alone, if present.

If ``OUTPUT_VARIABLE`` is not given, then after this function returns,
`HAS_FILENAME`_ returns false for ``<path-var>``.

For example:

.. code-block:: cmake

  set(path "/a/b")
  cmake_path(REMOVE_FILENAME path)
  message("First path is \"${path}\"")

  # filename is now already empty, the following removes nothing
  cmake_path(REMOVE_FILENAME path)
  message("Second path is \"${result}\"")

Output::

  First path is "/a/"
  Second path is "/a/"

.. _REPLACE_FILENAME:

.. code-block:: cmake

  cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])

Replaces the :ref:`filename <FILENAME_DEF>` component from ``<path-var>``
with ``<input>``.  If ``<path-var>`` has no filename component (i.e.
`HAS_FILENAME`_ returns false), the path is unchanged.  The operation is
equivalent to the following:

.. code-block:: cmake

  cmake_path(HAS_FILENAME path has_filename)
  if(has_filename)
    cmake_path(REMOVE_FILENAME path)
    cmake_path(APPEND path input);
  endif()

.. _REMOVE_EXTENSION:

.. code-block:: cmake

  cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
                                         [OUTPUT_VARIABLE <out-var>])

Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``.

.. _REPLACE_EXTENSION:

.. code-block:: cmake

  cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
                               [OUTPUT_VARIABLE <out-var>])

Replaces the :ref:`extension <EXTENSION_DEF>` with ``<input>``.  Its effect
is equivalent to the following:

.. code-block:: cmake

  cmake_path(REMOVE_EXTENSION path)
  if(NOT "input" MATCHES "^\\.")
    cmake_path(APPEND_STRING path ".")
  endif()
  cmake_path(APPEND_STRING path "input")

.. _Path Generation:

Generation
^^^^^^^^^^

.. _NORMAL_PATH:

.. code-block:: cmake

  cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])

Normalize ``<path-var>`` according the steps described in :ref:`Normalization`.

.. _cmake_path-RELATIVE_PATH:
.. _RELATIVE_PATH:

.. code-block:: cmake

  cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
                                      [OUTPUT_VARIABLE <out-var>])

Modifies ``<path-var>`` to make it relative to the ``BASE_DIRECTORY`` argument.
If ``BASE_DIRECTORY`` is not specified, the default base directory will be
:variable:`CMAKE_CURRENT_SOURCE_DIR`.

For reference, the algorithm used to compute the relative path is the same
as that used by C++
`std::filesystem::path::lexically_relative
<https://en.cppreference.com/w/cpp/filesystem/path/lexically_normal>`_.

.. _ABSOLUTE_PATH:

.. code-block:: cmake

  cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
                                      [OUTPUT_VARIABLE <out-var>])

If ``<path-var>`` is a relative path (`IS_RELATIVE`_ is true), it is evaluated
relative to the given base directory specified by ``BASE_DIRECTORY`` option.
If ``BASE_DIRECTORY`` is not specified, the default base directory will be
:variable:`CMAKE_CURRENT_SOURCE_DIR`.

When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` after the path computation.

Because ``cmake_path()`` does not access the filesystem, symbolic links are
not resolved and any leading tilde is not expanded.  To compute a real path
with symbolic links resolved and leading tildes expanded, use the
:command:`file(REAL_PATH)` command instead.

Native Conversion
^^^^^^^^^^^^^^^^^

For commands in this section, *native* refers to the host platform, not the
target platform when cross-compiling.

.. _cmake_path-NATIVE_PATH:
.. _NATIVE_PATH:

.. code-block:: cmake

  cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)

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

When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.

.. _CONVERT:
.. _cmake_path-TO_CMAKE_PATH_LIST:
.. _TO_CMAKE_PATH_LIST:

.. code-block:: cmake

  cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])

Converts a native ``<input>`` path into a cmake-style path with forward
slashes (``/``).  On Windows hosts, the long filename marker is taken into
account.  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 (on non-Windows platforms, this essentially
means ``:`` separators are replaced with ``;``).  The result of the
conversion is stored in the ``<out-var>`` variable.

When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.

.. note::
  Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand
  takes a literal string as input, not the name of a variable.

.. _cmake_path-TO_NATIVE_PATH_LIST:
.. _TO_NATIVE_PATH_LIST:

.. code-block:: cmake

  cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])

Converts a cmake-style ``<input>`` path into a native path with
platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere).
The input can be a single path or a cmake-style list.  A list will be
converted into a native search path (``;``-separated on Windows,
``:``-separated on other platforms).  The result of the conversion is
stored in the ``<out-var>`` variable.

When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.

.. note::
  Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand
  takes a literal string as input, not the name of a variable.

For example:

.. code-block:: cmake

  set(paths "/a/b/c" "/x/y/z")
  cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths)
  message("Native path list is \"${native_paths}\"")

Output on Windows::

  Native path list is "\a\b\c;\x\y\z"

Output on all other platforms::

  Native path list is "/a/b/c:/x/y/z"

Hashing
^^^^^^^

.. _HASH:

.. code-block:: cmake

    cmake_path(HASH <path-var> <out-var>)

Compute a hash value of ``<path-var>`` such that for two paths ``p1`` and
``p2`` that compare equal (:ref:`COMPARE ... EQUAL <COMPARE>`), the hash
value of ``p1`` is equal to the hash value of ``p2``.  The path is always
:ref:`normalized <Normalization>` before the hash is computed.