code:
list
----

Operations on :ref:`semicolon-separated lists <CMake Language Lists>`.

Synopsis
^^^^^^^^

.. parsed-literal::

  `Reading`_
    list(`LENGTH`_ <list> <out-var>)
    list(`GET`_ <list> <element index> [<index> ...] <out-var>)
    list(`JOIN`_ <list> <glue> <out-var>)
    list(`SUBLIST`_ <list> <begin> <length> <out-var>)

  `Search`_
    list(`FIND`_ <list> <value> <out-var>)

  `Modification`_
    list(`APPEND`_ <list> [<element>...])
    list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>)
    list(`INSERT`_ <list> <index> [<element>...])
    list(`POP_BACK`_ <list> [<out-var>...])
    list(`POP_FRONT`_ <list> [<out-var>...])
    list(`PREPEND`_ <list> [<element>...])
    list(`REMOVE_ITEM`_ <list> <value>...)
    list(`REMOVE_AT`_ <list> <index>...)
    list(`REMOVE_DUPLICATES`_ <list>)
    list(`TRANSFORM`_ <list> <ACTION> [...])

  `Ordering`_
    list(`REVERSE`_ <list>)
    list(`SORT`_ <list> [...])

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

The list subcommands :cref:`APPEND`, :cref:`INSERT`, :cref:`FILTER`,
:cref:`PREPEND`, :cref:`POP_BACK`, :cref:`POP_FRONT`, :cref:`REMOVE_AT`,
:cref:`REMOVE_ITEM`, :cref:`REMOVE_DUPLICATES`, :cref:`REVERSE` and
:cref:`SORT` may create new values for the list within the current CMake
variable scope.  Similar to the :command:`set` command, the ``list`` command
creates new variable values in the current scope, even if the list itself is
actually defined in a parent scope.  To propagate the results of these
operations upwards, use :command:`set` with ``PARENT_SCOPE``,
:command:`set` with ``CACHE INTERNAL``, or some other means of value
propagation.

.. note::

  A list in cmake is a ``;`` separated group of strings.  To create a
  list, the :command:`set` command can be used.  For example,
  ``set(var a b c d e)`` creates a list with ``a;b;c;d;e``, and
  ``set(var "a b c d e")`` creates a string or a list with one item in it.
  (Note that macro arguments are not variables, and therefore cannot be used
  in ``LIST`` commands.)

  Individual elements may not contain an unequal number of ``[`` and ``]``
  characters, and may not end in a backslash (``\``).
  See :ref:`semicolon-separated lists <CMake Language Lists>` for details.

.. note::

  When specifying index values, if ``<element index>`` is 0 or greater, it
  is indexed from the beginning of the list, with 0 representing the
  first list element.  If ``<element index>`` is -1 or lesser, it is indexed
  from the end of the list, with -1 representing the last list element.
  Be careful when counting with negative indices: they do not start from
  0.  -0 is equivalent to 0, the first list element.

Reading
^^^^^^^

.. signature::
  list(LENGTH <list> <output variable>)

  Returns the list's length.

.. signature::
  list(GET <list> <element index> [<element index> ...] <output variable>)

  Returns the list of elements specified by indices from the list.

.. signature:: list(JOIN <list> <glue> <output variable>)

  .. versionadded:: 3.12

  Returns a string joining all list's elements using the glue string.
  To join multiple strings, which are not part of a list,
  use :command:`string(JOIN)`.

.. signature::
  list(SUBLIST <list> <begin> <length> <output variable>)

  .. versionadded:: 3.12

  Returns a sublist of the given list.
  If ``<length>`` is 0, an empty list will be returned.
  If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then
  the remaining elements of the list starting at ``<begin>`` will be returned.

Search
^^^^^^

.. signature::
  list(FIND <list> <value> <output variable>)

  Returns the index of the element specified in the list
  or ``-1`` if it wasn't found.

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

.. signature::
  list(APPEND <list> [<element> ...])

  Appends elements to the list. If no variable named ``<list>`` exists in the
  current scope its value is treated as empty and the elements are appended to
  that empty list.

.. signature::
  list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)

.. versionadded:: 3.6

Includes or removes items from the list that match the mode's pattern.
In ``REGEX`` mode, items will be matched against the given regular expression.

For more information on regular expressions look under
:ref:`string(REGEX) <Regex Specification>`.

.. signature::
  list(INSERT <list> <element_index> <element> [<element> ...])

  Inserts elements to the list to the specified index. It is an
  error to specify an out-of-range index. Valid indexes are 0 to `N`
  where `N` is the length of the list, inclusive. An empty list
  has length 0. If no variable named ``<list>`` exists in the
  current scope its value is treated as empty and the elements are
  inserted in that empty list.

.. signature::
  list(POP_BACK <list> [<out-var>...])

  .. versionadded:: 3.15

  If no variable name is given, removes exactly one element. Otherwise,
  with `N` variable names provided, assign the last `N` elements' values
  to the given variables and then remove the last `N` values from
  ``<list>``.

.. signature::
  list(POP_FRONT <list> [<out-var>...])

  .. versionadded:: 3.15

  If no variable name is given, removes exactly one element. Otherwise,
  with `N` variable names provided, assign the first `N` elements' values
  to the given variables and then remove the first `N` values from
  ``<list>``.

.. signature::
  list(PREPEND <list> [<element> ...])

  .. versionadded:: 3.15

  Insert elements to the 0th position in the list. If no variable named
  ``<list>`` exists in the current scope its value is treated as empty and
  the elements are prepended to that empty list.

.. signature::
  list(REMOVE_ITEM <list> <value> [<value> ...])

  Removes all instances of the given items from the list.

.. signature::
  list(REMOVE_AT <list> <index> [<index> ...])

  Removes items at given indices from the list.

.. signature::
  list(REMOVE_DUPLICATES <list>)

  Removes duplicated items in the list. The relative order of items
  is preserved, but if duplicates are encountered,
  only the first instance is preserved.

.. signature::
  list(TRANSFORM <list> <ACTION> [<SELECTOR>]
       [OUTPUT_VARIABLE <output variable>])

  .. versionadded:: 3.12

  Transforms the list by applying an ``<ACTION>`` to all or, by specifying a
  ``<SELECTOR>``, to the selected elements of the list, storing the result
  in-place or in the specified output variable.

  .. note::

    The ``TRANSFORM`` sub-command does not change the number of elements in the
    list. If a ``<SELECTOR>`` is specified, only some elements will be changed,
    the other ones will remain the same as before the transformation.

  ``<ACTION>`` specifies the action to apply to the elements of the list.
  The actions have exactly the same semantics as sub-commands of the
  :command:`string` command.  ``<ACTION>`` must be one of the following:

    :command:`APPEND <string(APPEND)>`, :command:`PREPEND <string(PREPEND)>`
      Append, prepend specified value to each element of the list.

      .. signature::
        list(TRANSFORM <list> (APPEND|PREPEND) <value> ...)
        :target: TRANSFORM_APPEND

    :command:`TOLOWER <string(TOLOWER)>`, :command:`TOUPPER <string(TOUPPER)>`
      Convert each element of the list to lower, upper characters.

      .. signature::
        list(TRANSFORM <list> (TOLOWER|TOUPPER) ...)
        :target: TRANSFORM_TOLOWER

    :command:`STRIP <string(STRIP)>`
      Remove leading and trailing spaces from each element of the list.

      .. signature::
        list(TRANSFORM <list> STRIP ...)
        :target: TRANSFORM_STRIP

    :command:`GENEX_STRIP <string(GENEX_STRIP)>`
      Strip any
      :manual:`generator expressions <cmake-generator-expressions(7)>`
      from each element of the list.

      .. signature::
        list(TRANSFORM <list> GENEX_STRIP ...)
        :target: TRANSFORM_GENEX_STRIP

    :command:`REPLACE <string(REGEX REPLACE)>`:
      Match the regular expression as many times as possible and substitute
      the replacement expression for the match for each element of the list
      (same semantic as :command:`string(REGEX REPLACE)`).

      .. signature::
        list(TRANSFORM <list> REPLACE <regular_expression>
                                      <replace_expression> ...)
        :target: TRANSFORM_REPLACE

  ``<SELECTOR>`` determines which elements of the list will be transformed.
  Only one type of selector can be specified at a time.
  When given, ``<SELECTOR>`` must be one of the following:

    ``AT``
      Specify a list of indexes.

      .. code-block:: cmake

        list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)

    ``FOR``
      Specify a range with, optionally,
      an increment used to iterate over the range.

      .. code-block:: cmake

        list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)

    ``REGEX``
      Specify a regular expression.
      Only elements matching the regular expression will be transformed.

      .. code-block:: cmake

        list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)

Ordering
^^^^^^^^

.. signature::
  list(REVERSE <list>)

  Reverses the contents of the list in-place.

.. signature::
  list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])

  Sorts the list in-place alphabetically.

  .. versionadded:: 3.13
    Added the ``COMPARE``, ``CASE``, and ``ORDER`` options.

  .. versionadded:: 3.18
    Added the ``COMPARE NATURAL`` option.

  Use the ``COMPARE`` keyword to select the comparison method for sorting.
  The ``<compare>`` option should be one of:

    ``STRING``
      Sorts a list of strings alphabetically.
      This is the default behavior if the ``COMPARE`` option is not given.

    ``FILE_BASENAME``
      Sorts a list of pathnames of files by their basenames.

    ``NATURAL``
      Sorts a list of strings using natural order
      (see ``strverscmp(3)`` manual), i.e. such that contiguous digits
      are compared as whole numbers.
      For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1`
      will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL``
      comparison is selected where it will be sorted as
      `1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison.

  Use the ``CASE`` keyword to select a case sensitive or case insensitive
  sort mode.  The ``<case>`` option should be one of:

    ``SENSITIVE``
      List items are sorted in a case-sensitive manner.
      This is the default behavior if the ``CASE`` option is not given.

    ``INSENSITIVE``
      List items are sorted case insensitively.  The order of
      items which differ only by upper/lowercase is not specified.

  To control the sort order, the ``ORDER`` keyword can be given.
  The ``<order>`` option should be one of:

    ``ASCENDING``
      Sorts the list in ascending order.
      This is the default behavior when the ``ORDER`` option is not given.

    ``DESCENDING``
      Sorts the list in descending order.


code:
load_cache
----------

Load in the values from another project's CMake cache.

.. code-block:: cmake

  load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)

Reads the cache and store the requested entries in variables with their
name prefixed with the given prefix.  This only reads the values, and
does not create entries in the local project's cache.

.. code-block:: cmake

  load_cache(pathToBuildDirectory [EXCLUDE entry1...]
             [INCLUDE_INTERNALS entry1...])

Loads in the values from another cache and store them in the local
project's cache as internal entries.  This is useful for a project
that depends on another project built in a different tree.  ``EXCLUDE``
option can be used to provide a list of entries to be excluded.
``INCLUDE_INTERNALS`` can be used to provide a list of internal entries to
be included.  Normally, no internal entries are brought in.  Use of
this form of the command is strongly discouraged, but it is provided
for backward compatibility.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
load_command
------------

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

Load a command into a running CMake.

.. code-block:: cmake

  load_command(COMMAND_NAME <loc1> [loc2 ...])

The given locations are searched for a library whose name is
cmCOMMAND_NAME.  If found, it is loaded as a module and the command is
added to the set of available CMake commands.  Usually,
:command:`try_compile` is used before this command to compile the
module.  If the command is successfully loaded a variable named

.. code-block:: cmake

  CMAKE_LOADED_COMMAND_<COMMAND_NAME>

will be set to the full path of the module that was loaded.  Otherwise
the variable will not be set.


code:
macro
-----

Start recording a macro for later invocation as a command

.. code-block:: cmake

  macro(<name> [<arg1> ...])
    <commands>
  endmacro()

Defines a macro named ``<name>`` that takes arguments named
``<arg1>``, ... Commands listed after macro, but before the
matching :command:`endmacro()`, are not executed until the macro
is invoked.

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

See the :command:`cmake_policy()` command documentation for the behavior
of policies inside macros.

See the :ref:`Macro vs Function` section below for differences
between CMake macros and :command:`functions <function>`.

Invocation
^^^^^^^^^^

The macro invocation is case-insensitive. A macro defined as

.. code-block:: cmake

  macro(foo)
    <commands>
  endmacro()

can be invoked through any of

.. code-block:: cmake

  foo()
  Foo()
  FOO()
  cmake_language(CALL foo)

and so on. However, it is strongly recommended to stay with the
case chosen in the macro definition.  Typically macros use
all-lowercase names.

.. versionadded:: 3.18
  The :command:`cmake_language(CALL ...)` command can also be used to
  invoke the macro.

Arguments
^^^^^^^^^

When a macro is invoked, the commands recorded in the macro are
first modified by replacing formal parameters (``${arg1}``, ...)
with the arguments passed, and then invoked as normal commands.

In addition to referencing the formal parameters you can reference the
values ``${ARGC}`` which will be set to the number of arguments passed
into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``,
...  which will have the actual values of the arguments passed in.
This facilitates creating macros with optional arguments.

Furthermore, ``${ARGV}`` holds the list of all arguments given to the
macro and ``${ARGN}`` holds the list of arguments past the last expected
argument.
Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined
behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only
way to ensure that ``${ARGV#}`` was passed to the function as an extra
argument.

.. _`Macro vs Function`:

Macro vs Function
^^^^^^^^^^^^^^^^^

The ``macro`` command is very similar to the :command:`function` command.
Nonetheless, there are a few important differences.

In a function, ``ARGN``, ``ARGC``, ``ARGV`` and ``ARGV0``, ``ARGV1``, ...
are true variables in the usual CMake sense.  In a macro, they are not,
they are string replacements much like the C preprocessor would do
with a macro.  This has a number of consequences, as explained in
the :ref:`Argument Caveats` section below.

Another difference between macros and functions is the control flow.
A function is executed by transferring control from the calling
statement to the function body.  A macro is executed as if the macro
body were pasted in place of the calling statement.  This has the
consequence that a :command:`return()` in a macro body does not
just terminate execution of the macro; rather, control is returned
from the scope of the macro call.  To avoid confusion, it is recommended
to avoid :command:`return()` in macros altogether.

Unlike a function, the :variable:`CMAKE_CURRENT_FUNCTION`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` variables are not
set for a macro.

.. _`Argument Caveats`:

Argument Caveats
^^^^^^^^^^^^^^^^

Since ``ARGN``, ``ARGC``, ``ARGV``, ``ARGV0`` etc. are not variables,
you will NOT be able to use commands like

.. code-block:: cmake

 if(ARGV1) # ARGV1 is not a variable
 if(DEFINED ARGV2) # ARGV2 is not a variable
 if(ARGC GREATER 2) # ARGC is not a variable
 foreach(loop_var IN LISTS ARGN) # ARGN is not a variable

In the first case, you can use ``if(${ARGV1})``.  In the second and
third case, the proper way to check if an optional variable was
passed to the macro is to use ``if(${ARGC} GREATER 2)``.  In the
last case, you can use ``foreach(loop_var ${ARGN})`` but this will
skip empty arguments.  If you need to include them, you can use

.. code-block:: cmake

 set(list_var "${ARGN}")
 foreach(loop_var IN LISTS list_var)

Note that if you have a variable with the same name in the scope from
which the macro is called, using unreferenced names will use the
existing variable instead of the arguments. For example:

.. code-block:: cmake

 macro(bar)
   foreach(arg IN LISTS ARGN)
     <commands>
   endforeach()
 endmacro()

 function(foo)
   bar(x y z)
 endfunction()

 foo(a b c)

Will loop over ``a;b;c`` and not over ``x;y;z`` as one might have expected.
If you want true CMake variables and/or better CMake scope control you
should look at the function command.

See Also
^^^^^^^^

* :command:`cmake_parse_arguments`
* :command:`endmacro`


code:
make_directory
--------------

.. deprecated:: 3.0

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

.. code-block:: cmake

  make_directory(directory)

Creates the specified directory.  Full paths should be given.  Any
parent directories that do not exist will also be created.  Use with
care.


code:
mark_as_advanced
----------------

Mark cmake cached variables as advanced.

.. code-block:: cmake

  mark_as_advanced([CLEAR|FORCE] <var1> ...)

Sets the advanced/non-advanced state of the named
cached variables.

An advanced variable will not be displayed in any
of the cmake GUIs unless the ``show advanced`` option is on.
In script mode, the advanced/non-advanced state has no effect.

If the keyword ``CLEAR`` is given
then advanced variables are changed back to unadvanced.
If the keyword ``FORCE`` is given
then the variables are made advanced.
If neither ``FORCE`` nor ``CLEAR`` is specified,
new values will be marked as advanced, but if a
variable already has an advanced/non-advanced state,
it will not be changed.

.. versionchanged:: 3.17
  Variables passed to this command which are not already in the cache
  are ignored. See policy :policy:`CMP0102`.


code:
math
----

Evaluate a mathematical expression.

.. code-block:: cmake

  math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])

Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the
resulting value.  The result of the expression must be representable as a
64-bit signed integer. Floating point inputs are invalid e.g. ``1.1 * 10``.
Non-integer results e.g. ``3 / 2`` are truncated.

The mathematical expression must be given as a string (i.e. enclosed in
double quotation marks). An example is ``"5 * (10 + 13)"``.
Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``,
``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning
as in C code.

.. versionadded:: 3.13
  Hexadecimal numbers are recognized when prefixed with ``0x``, as in C code.

.. versionadded:: 3.13
  The result is formatted according to the option ``OUTPUT_FORMAT``,
  where ``<format>`` is one of

  ``HEXADECIMAL``
    Hexadecimal notation as in C code, i. e. starting with "0x".
  ``DECIMAL``
    Decimal notation. Which is also used if no ``OUTPUT_FORMAT`` option
    is specified.

For example

.. code-block:: cmake

  math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL)      # value is set to "1000"
  math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL)  # value is set to "0x3e8"


code:
message
-------

Log a message.

Synopsis
^^^^^^^^

.. parsed-literal::

  `General messages`_
    message([<mode>] "message text" ...)

  `Reporting checks`_
    message(<checkState> "message text" ...)

  `Configure Log`_
    message(CONFIGURE_LOG <text>...)

General messages
^^^^^^^^^^^^^^^^

.. code-block:: cmake

  message([<mode>] "message text" ...)

Record the specified message text in the log.  If more than one message
string is given, they are concatenated into a single message with no
separator between the strings.

The optional ``<mode>`` keyword determines the type of message, which
influences the way the message is handled:

``FATAL_ERROR``
  CMake Error, stop processing and generation.

  The :manual:`cmake(1)` executable will return a non-zero
  :ref:`exit code <CMake Exit Code>`.

``SEND_ERROR``
  CMake Error, continue processing, but skip generation.

``WARNING``
  CMake Warning, continue processing.

``AUTHOR_WARNING``
  CMake Warning (dev), continue processing.

``DEPRECATION``
  CMake Deprecation Error or Warning if variable
  :variable:`CMAKE_ERROR_DEPRECATED` or :variable:`CMAKE_WARN_DEPRECATED`
  is enabled, respectively, else no message.

(none) or ``NOTICE``
  Important message printed to stderr to attract user's attention.

``STATUS``
  The main interesting messages that project users might be interested in.
  Ideally these should be concise, no more than a single line, but still
  informative.

``VERBOSE``
  Detailed informational messages intended for project users.  These messages
  should provide additional details that won't be of interest in most cases,
  but which may be useful to those building the project when they want deeper
  insight into what's happening.

``DEBUG``
  Detailed informational messages intended for developers working on the
  project itself as opposed to users who just want to build it.  These messages
  will not typically be of interest to other users building the project and
  will often be closely related to internal implementation details.

``TRACE``
  Fine-grained messages with very low-level implementation details.  Messages
  using this log level would normally only be temporary and would expect to be
  removed before releasing the project, packaging up the files, etc.

.. versionadded:: 3.15
  Added the ``NOTICE``, ``VERBOSE``, ``DEBUG``, and ``TRACE`` levels.

The CMake command-line tool displays ``STATUS`` to ``TRACE`` messages on stdout
with the message preceded by two hyphens and a space.  All other message types
are sent to stderr and are not prefixed with hyphens.  The
:manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area.
The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE``
messages one at a time on a status line and other messages in an
interactive pop-up box.  The :option:`--log-level <cmake --log-level>`
command-line option to each of these tools can be used to control which
messages will be shown.

.. versionadded:: 3.17
  To make a log level persist between CMake runs, the
  :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead.
  Note that the command line option takes precedence over the cache variable.

.. versionadded:: 3.16
  Messages of log levels ``NOTICE`` and below will have each line preceded
  by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to
  a single string by concatenating its list items).  For ``STATUS`` to ``TRACE``
  messages, this indenting content will be inserted after the hyphens.

.. versionadded:: 3.17
  Messages of log levels ``NOTICE`` and below can also have each line preceded
  with context of the form ``[some.context.example]``.  The content between the
  square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT`
  list variable to a dot-separated string.  The message context will always
  appear before any indenting content but after any automatically added leading
  hyphens. By default, message context is not shown, it has to be explicitly
  enabled by giving the :option:`cmake --log-context`
  command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW`
  variable to true.  See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for
  usage examples.

CMake Warning and Error message text displays using a simple markup
language.  Non-indented text is formatted in line-wrapped paragraphs
delimited by newlines.  Indented text is considered pre-formatted.

Reporting checks
^^^^^^^^^^^^^^^^

.. versionadded:: 3.17

A common pattern in CMake output is a message indicating the start of some
sort of check, followed by another message reporting the result of that check.
For example:

.. code-block:: cmake

  message(STATUS "Looking for someheader.h")
  #... do the checks, set checkSuccess with the result
  if(checkSuccess)
    message(STATUS "Looking for someheader.h - found")
  else()
    message(STATUS "Looking for someheader.h - not found")
  endif()

This can be more robustly and conveniently expressed using the ``CHECK_...``
keyword form of the ``message()`` command:

.. code-block:: cmake

  message(<checkState> "message" ...)

where ``<checkState>`` must be one of the following:

  ``CHECK_START``
    Record a concise message about the check about to be performed.

  ``CHECK_PASS``
    Record a successful result for a check.

  ``CHECK_FAIL``
    Record an unsuccessful result for a check.

When recording a check result, the command repeats the message from the most
recently started check for which no result has yet been reported, then some
separator characters and then the message text provided after the
``CHECK_PASS`` or ``CHECK_FAIL`` keyword.  Check messages are always reported
at ``STATUS`` log level.

Checks may be nested and every ``CHECK_START`` should have exactly one
matching ``CHECK_PASS`` or ``CHECK_FAIL``.
The :variable:`CMAKE_MESSAGE_INDENT` variable can also be used to add
indenting to nested checks if desired.  For example:

.. code-block:: cmake

  message(CHECK_START "Finding my things")
  list(APPEND CMAKE_MESSAGE_INDENT "  ")
  unset(missingComponents)

  message(CHECK_START "Finding partA")
  # ... do check, assume we find A
  message(CHECK_PASS "found")

  message(CHECK_START "Finding partB")
  # ... do check, assume we don't find B
  list(APPEND missingComponents B)
  message(CHECK_FAIL "not found")

  list(POP_BACK CMAKE_MESSAGE_INDENT)
  if(missingComponents)
    message(CHECK_FAIL "missing components: ${missingComponents}")
  else()
    message(CHECK_PASS "all components found")
  endif()

Output from the above would appear something like the following::

  -- Finding my things
  --   Finding partA
  --   Finding partA - found
  --   Finding partB
  --   Finding partB - not found
  -- Finding my things - missing components: B

Configure Log
^^^^^^^^^^^^^

.. versionadded:: 3.26

.. code-block:: cmake

  message(CONFIGURE_LOG <text>...)

Record a :ref:`configure-log message event <message configure-log event>`
with the specified ``<text>``.  By convention, if the text contains more
than one line, the first line should be a summary of the event.

This mode is intended to record the details of a system inspection check
or other one-time operation guarded by a cache entry, but that is not
performed using :command:`try_compile` or :command:`try_run`, which
automatically log their details.  Projects should avoid calling it every
time CMake runs.  For example:

.. code-block:: cmake

  if (NOT DEFINED MY_CHECK_RESULT)
    # Print check summary in configure output.
    message(CHECK_START "My Check")

    # ... perform system inspection, e.g., with execute_process ...

    # Cache the result so we do not run the check again.
    set(MY_CHECK_RESULT "${MY_CHECK_RESULT}" CACHE INTERNAL "My Check")

    # Record the check details in the cmake-configure-log.
    message(CONFIGURE_LOG
      "My Check Result: ${MY_CHECK_RESULT}\n"
      "${details}"
    )

    # Print check result in configure output.
    if(MY_CHECK_RESULT)
      message(CHECK_PASS "passed")
    else()
      message(CHECK_FAIL "failed")
    endif()
  endif()

If no project is currently being configured, such as in
:ref:`cmake -P <Script Processing Mode>` script mode,
this command does nothing.

See Also
^^^^^^^^

* :command:`cmake_language(GET_MESSAGE_LOG_LEVEL)`


code:
option
------

Provide a boolean option that the user can optionally select.

.. code-block:: cmake

  option(<variable> "<help_text>" [value])

If no initial ``<value>`` is provided, boolean ``OFF`` is the default value.
If ``<variable>`` is already set as a normal or cache variable,
then the command does nothing (see policy :policy:`CMP0077`).

For options that depend on the values of other options, see
the module help for :module:`CMakeDependentOption`.

In CMake project mode, a boolean cache variable is created with the option
value. In CMake script mode, a boolean variable is set with the option value.


code:
output_required_files
---------------------

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

Approximate C preprocessor dependency scanning.

This command exists only because ancient CMake versions provided it.
CMake handles preprocessor dependency scanning automatically using a
more advanced scanner.

.. code-block:: cmake

  output_required_files(srcfile outputfile)

Outputs a list of all the source files that are required by the
specified ``srcfile``.  This list is written into ``outputfile``.  This is
similar to writing out the dependencies for ``srcfile`` except that it
jumps from ``.h`` files into ``.cxx``, ``.c`` and ``.cpp`` files if possible.


code:
project
-------

Set the name of the project.

Synopsis
^^^^^^^^

.. code-block:: cmake

 project(<PROJECT-NAME> [<language-name>...])
 project(<PROJECT-NAME>
         [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
         [DESCRIPTION <project-description-string>]
         [HOMEPAGE_URL <url-string>]
         [LANGUAGES <language-name>...])

Sets the name of the project, and stores it in the variable
:variable:`PROJECT_NAME`. When called from the top-level
``CMakeLists.txt`` also stores the project name in the
variable :variable:`CMAKE_PROJECT_NAME`.

Also sets the variables:

:variable:`PROJECT_SOURCE_DIR`, :variable:`<PROJECT-NAME>_SOURCE_DIR`
  Absolute path to the source directory for the project.

:variable:`PROJECT_BINARY_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR`
  Absolute path to the binary directory for the project.

:variable:`PROJECT_IS_TOP_LEVEL`, :variable:`<PROJECT-NAME>_IS_TOP_LEVEL`
  .. versionadded:: 3.21

  Boolean value indicating whether the project is top-level.

Further variables are set by the optional arguments described in the following.
If any of these arguments is not used, then the corresponding variables are
set to the empty string.

Options
^^^^^^^

The options are:

``VERSION <version>``
  Optional; may not be used unless policy :policy:`CMP0048` is
  set to ``NEW``.

  Takes a ``<version>`` argument composed of non-negative integer components,
  i.e. ``<major>[.<minor>[.<patch>[.<tweak>]]]``,
  and sets the variables

  * :variable:`PROJECT_VERSION`,
    :variable:`<PROJECT-NAME>_VERSION`
  * :variable:`PROJECT_VERSION_MAJOR`,
    :variable:`<PROJECT-NAME>_VERSION_MAJOR`
  * :variable:`PROJECT_VERSION_MINOR`,
    :variable:`<PROJECT-NAME>_VERSION_MINOR`
  * :variable:`PROJECT_VERSION_PATCH`,
    :variable:`<PROJECT-NAME>_VERSION_PATCH`
  * :variable:`PROJECT_VERSION_TWEAK`,
    :variable:`<PROJECT-NAME>_VERSION_TWEAK`.

  .. versionadded:: 3.12
    When the ``project()`` command is called from the top-level
    ``CMakeLists.txt``, then the version is also stored in the variable
    :variable:`CMAKE_PROJECT_VERSION`.

``DESCRIPTION <project-description-string>``
  .. versionadded:: 3.9

  Optional.
  Sets the variables

  * :variable:`PROJECT_DESCRIPTION`, :variable:`<PROJECT-NAME>_DESCRIPTION`

  to ``<project-description-string>``.
  It is recommended that this description is a relatively short string,
  usually no more than a few words.

  When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
  then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`.

  .. versionadded:: 3.12
    Added the ``<PROJECT-NAME>_DESCRIPTION`` variable.

``HOMEPAGE_URL <url-string>``
  .. versionadded:: 3.12

  Optional.
  Sets the variables

  * :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL`

  to ``<url-string>``, which should be the canonical home URL for the project.

  When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
  then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`.

``LANGUAGES <language-name>...``
  Optional.
  Can also be specified without ``LANGUAGES`` keyword per the first, short signature.

  Selects which programming languages are needed to build the project.

.. include:: SUPPORTED_LANGUAGES.txt

By default ``C`` and ``CXX`` are enabled if no language options are given.
Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages,
to skip enabling any languages.

The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL``
options are intended for use as default values in package metadata and documentation.

.. _`Code Injection`:

Code Injection
^^^^^^^^^^^^^^

A number of variables can be defined by the user to specify files to include
at different points during the execution of the ``project()`` command.
The following outlines the steps performed during a ``project()`` call:

* .. versionadded:: 3.15
    For every ``project()`` call regardless of the project
    name, include the file named by :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`,
    if set.

* .. versionadded:: 3.17
    If the ``project()`` command specifies ``<PROJECT-NAME>`` as its project
    name, include the file named by
    :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, if set.

* Set the various project-specific variables detailed in the `Synopsis`_
  and `Options`_ sections above.

* For the very first ``project()`` call only:

  * If :variable:`CMAKE_TOOLCHAIN_FILE` is set, read it at least once.
    It may be read multiple times and it may also be read again when
    enabling languages later (see below).

  * Set the variables describing the host and target platforms.
    Language-specific variables might or might not be set at this point.
    On the first run, the only language-specific variables that might be
    defined are those a toolchain file may have set. On subsequent runs,
    language-specific variables cached from a previous run may be set.

  * .. versionadded:: 3.24
      Include each file listed in :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES`,
      if set. The variable is ignored by CMake thereafter.

* Enable any languages specified in the call, or the default languages if
  none were provided. The toolchain file may be re-read when enabling a
  language for the first time.

* .. versionadded:: 3.15
    For every ``project()`` call regardless of the project
    name, include the file named by :variable:`CMAKE_PROJECT_INCLUDE`,
    if set.

* If the ``project()`` command specifies ``<PROJECT-NAME>`` as its project
  name, include the file named by
  :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, if set.

Usage
^^^^^

The top-level ``CMakeLists.txt`` file for a project must contain a
literal, direct call to the ``project()`` command; loading one
through the :command:`include` command is not sufficient.  If no such
call exists, CMake will issue a warning and pretend there is a
``project(Project)`` at the top to enable the default languages
(``C`` and ``CXX``).

.. note::
  Call the ``project()`` command near the top of the top-level
  ``CMakeLists.txt``, but *after* calling :command:`cmake_minimum_required`.
  It is important to establish version and policy settings before invoking
  other commands whose behavior they may affect and for this reason the
  ``project()`` command will issue a warning if this order is not kept.
  See also policy :policy:`CMP0000`.


code:
qt_wrap_cpp
-----------

.. deprecated:: 3.14

  This command was originally added to support Qt 3 before the
  :command:`add_custom_command()` command was sufficiently mature.  The
  :module:`FindQt4` module provides the ``qt4_wrap_cpp()`` macro, which
  should be used instead for Qt 4 projects.  For projects using Qt 5 or
  later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides
  `qt5_wrap_cpp() <https://doc.qt.io/qt-5/qtcore-cmake-qt5-wrap-cpp.html>`_).

Manually create Qt Wrappers.

.. code-block:: cmake

  qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)

Produces moc files for all the .h files listed in the SourceLists.  The
moc files will be added to the library using the ``DestName`` source list.

Consider updating the project to use the :prop_tgt:`AUTOMOC` target property
instead for a more automated way of invoking the ``moc`` tool.


code:
qt_wrap_ui
----------

.. deprecated:: 3.14

  This command was originally added to support Qt 3 before the
  :command:`add_custom_command()` command was sufficiently mature.  The
  :module:`FindQt4` module provides the ``qt4_wrap_ui()`` macro, which
  should be used instead for Qt 4 projects.  For projects using Qt 5 or
  later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides
  ``qt5_wrap_ui()``).

Manually create Qt user interfaces Wrappers.

.. code-block:: cmake

  qt_wrap_ui(resultingLibraryName HeadersDestName
             SourcesDestName SourceLists ...)

Produces .h and .cxx files for all the .ui files listed in the
``SourceLists``.  The .h files will be added to the library using the
``HeadersDestNamesource`` list.  The .cxx files will be added to the
library using the ``SourcesDestNamesource`` list.

Consider updating the project to use the :prop_tgt:`AUTOUIC` target property
instead for a more automated way of invoking the ``uic`` tool.


code:
remove
------

.. deprecated:: 3.0

  Use the :command:`list(REMOVE_ITEM)` command instead.

.. code-block:: cmake

  remove(VAR VALUE VALUE ...)

Removes ``VALUE`` from the variable ``VAR``.  This is typically used to
remove entries from a vector (e.g.  semicolon separated list).  ``VALUE``
is expanded.


code:
remove_definitions
------------------

Remove -D define flags added by :command:`add_definitions`.

.. code-block:: cmake

  remove_definitions(-DFOO -DBAR ...)

Removes flags (added by :command:`add_definitions`) from the compiler
command line for sources in the current directory and below.


code:
return
------

Return from a file, directory or function.

.. code-block:: cmake

  return([PROPAGATE <var-name>...])

When this command is encountered in an included file (via :command:`include` or
:command:`find_package`), it causes processing of the current file to stop
and control is returned to the including file.  If it is encountered in a
file which is not included by another file, e.g. a ``CMakeLists.txt``,
deferred calls scheduled by :command:`cmake_language(DEFER)` are invoked and
control is returned to the parent directory if there is one.

If ``return()`` is called in a function, control is returned to the caller
of that function.  Note that a :command:`macro`, unlike a :command:`function`,
is expanded in place and therefore cannot handle ``return()``.

Policy :policy:`CMP0140` controls the behavior regarding the arguments of the
command.  All arguments are ignored unless that policy is set to ``NEW``.

``PROPAGATE``
  .. versionadded:: 3.25

  This option sets or unsets the specified variables in the parent directory or
  function caller scope. This is equivalent to :command:`set(PARENT_SCOPE)` or
  :command:`unset(PARENT_SCOPE)` commands, except for the way it interacts
  with the :command:`block` command, as described below.

  The ``PROPAGATE`` option can be very useful in conjunction with the
  :command:`block` command.  A ``return`` will propagate the
  specified variables through any enclosing block scopes created by the
  :command:`block` commands.  Inside a function, this ensures the variables
  are propagated to the function's caller, regardless of any blocks within
  the function.  If not inside a function, it ensures the variables are
  propagated to the parent file or directory scope. For example:

  .. code-block:: cmake
    :caption: CMakeLists.txt

    cmake_minimum_required(VERSION 3.25)
    project(example)

    set(var1 "top-value")

    block(SCOPE_FOR VARIABLES)
      add_subdirectory(subDir)
      # var1 has the value "block-nested"
    endblock()

    # var1 has the value "top-value"

  .. code-block:: cmake
    :caption: subDir/CMakeLists.txt

    function(multi_scopes result_var1 result_var2)
      block(SCOPE_FOR VARIABLES)
        # This would only propagate out of the immediate block, not to
        # the caller of the function.
        #set(${result_var1} "new-value" PARENT_SCOPE)
        #unset(${result_var2} PARENT_SCOPE)

        # This propagates the variables through the enclosing block and
        # out to the caller of the function.
        set(${result_var1} "new-value")
        unset(${result_var2})
        return(PROPAGATE ${result_var1} ${result_var2})
      endblock()
    endfunction()

    set(var1 "some-value")
    set(var2 "another-value")

    multi_scopes(var1 var2)
    # Now var1 will hold "new-value" and var2 will be unset

    block(SCOPE_FOR VARIABLES)
      # This return() will set var1 in the directory scope that included us
      # via add_subdirectory(). The surrounding block() here does not limit
      # propagation to the current file, but the block() in the parent
      # directory scope does prevent propagation going any further.
      set(var1 "block-nested")
      return(PROPAGATE var1)
    endblock()

See Also
^^^^^^^^

* :command:`block`
* :command:`function`


code:
separate_arguments
------------------

Parse command-line arguments into a semicolon-separated list.

.. code-block:: cmake

  separate_arguments(<variable> <mode> [PROGRAM [SEPARATE_ARGS]] <args>)

Parses a space-separated string ``<args>`` into a list of items,
and stores this list in semicolon-separated standard form in ``<variable>``.

This function is intended for parsing command-line arguments.
The entire command line must be passed as one string in the
argument ``<args>``.

The exact parsing rules depend on the operating system.
They are specified by the ``<mode>`` argument which must
be one of the following keywords:

``UNIX_COMMAND``
  Arguments are separated by unquoted whitespace.
  Both single-quote and double-quote pairs are respected.
  A backslash escapes the next literal character (``\"`` is ``"``);
  there are no special escapes (``\n`` is just ``n``).

``WINDOWS_COMMAND``
  A Windows command-line is parsed using the same
  syntax the runtime library uses to construct argv at startup.  It
  separates arguments by whitespace that is not double-quoted.
  Backslashes are literal unless they precede double-quotes.  See the
  MSDN article `Parsing C Command-Line Arguments`_ for details.

``NATIVE_COMMAND``
  .. versionadded:: 3.9

  Proceeds as in ``WINDOWS_COMMAND`` mode if the host system is Windows.
  Otherwise proceeds as in ``UNIX_COMMAND`` mode.

``PROGRAM``
  .. versionadded:: 3.19

  The first item in ``<args>`` is assumed to be an executable and will be
  searched in the system search path or left as a full path. If not found,
  ``<variable>`` will be empty. Otherwise, ``<variable>`` is a list of 2
  elements:

    0. Absolute path of the program
    1. Any command-line arguments present in ``<args>`` as a string

  For example:

  .. code-block:: cmake

    separate_arguments (out UNIX_COMMAND PROGRAM "cc -c main.c")

  * First element of the list: ``/path/to/cc``
  * Second element of the list: ``" -c main.c"``

``SEPARATE_ARGS``
  When this sub-option of ``PROGRAM`` option is specified, command-line
  arguments will be split as well and stored in ``<variable>``.

  For example:

  .. code-block:: cmake

    separate_arguments (out UNIX_COMMAND PROGRAM SEPARATE_ARGS "cc -c main.c")

  The contents of ``out`` will be: ``/path/to/cc;-c;main.c``

.. _`Parsing C Command-Line Arguments`: https://learn.microsoft.com/en-us/cpp/c-language/parsing-c-command-line-arguments

.. code-block:: cmake

  separate_arguments(<var>)

Convert the value of ``<var>`` to a semi-colon separated list.  All
spaces are replaced with ';'.  This helps with generating command
lines.


code:
set
---

Set a normal, cache, or environment variable to a given value.
See the :ref:`cmake-language(7) variables <CMake Language Variables>`
documentation for the scopes and interaction of normal variables
and cache entries.

Signatures of this command that specify a ``<value>...`` placeholder
expect zero or more arguments.  Multiple arguments will be joined as
a :ref:`semicolon-separated list <CMake Language Lists>` to form the
actual variable value to be set.

Set Normal Variable
^^^^^^^^^^^^^^^^^^^

.. signature::
  set(<variable> <value>... [PARENT_SCOPE])
  :target: normal

  Set or unset ``<variable>`` in the current function or directory scope:

  * If at least one ``<value>...`` is given, set the variable to that value.
  * If no value is given, unset the variable.  This is equivalent to
    :command:`unset(<variable>) <unset>`.

  If the ``PARENT_SCOPE`` option is given the variable will be set in
  the scope above the current scope.  Each new directory or :command:`function`
  command creates a new scope.  A scope can also be created with the
  :command:`block` command. ``set(PARENT_SCOPE)`` will set the value
  of a variable into the parent directory, calling function, or
  encompassing scope (whichever is applicable to the case at hand).
  The previous state of the variable's value stays the same in the
  current scope (e.g., if it was undefined before, it is still undefined
  and if it had a value, it is still that value).

  The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands
  can be used as an alternate method to the :command:`set(PARENT_SCOPE)`
  and :command:`unset(PARENT_SCOPE)` commands to update the parent scope.

.. include:: UNSET_NOTE.txt

Set Cache Entry
^^^^^^^^^^^^^^^

.. signature::
  set(<variable> <value>... CACHE <type> <docstring> [FORCE])
  :target: CACHE

  Sets the given cache ``<variable>`` (cache entry).  Since cache entries
  are meant to provide user-settable values this does not overwrite
  existing cache entries by default.  Use the ``FORCE`` option to
  overwrite existing entries.

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

    ``BOOL``
      Boolean ``ON/OFF`` value.
      :manual:`cmake-gui(1)` offers a checkbox.

    ``FILEPATH``
      Path to a file on disk.
      :manual:`cmake-gui(1)` offers a file dialog.

    ``PATH``
      Path to a directory on disk.
      :manual:`cmake-gui(1)` offers a file dialog.

    ``STRING``
      A line of text.
      :manual:`cmake-gui(1)` offers a text field or a drop-down selection
      if the :prop_cache:`STRINGS` cache entry property is set.

    ``INTERNAL``
      A line of text.
      :manual:`cmake-gui(1)` does not show internal entries.
      They may be used to store variables persistently across runs.
      Use of this type implies ``FORCE``.

  The ``<docstring>`` must be specified as a line of text
  providing a quick summary of the option
  for presentation to :manual:`cmake-gui(1)` users.

  If the cache entry does not exist prior to the call or the ``FORCE``
  option is given then the cache entry will be set to the given value.

  .. note::

    The content of the cache variable will not be directly accessible
    if a normal variable of the same name already exists
    (see :ref:`rules of variable evaluation <CMake Language Variables>`).
    If policy :policy:`CMP0126` is set to ``OLD``, any normal variable
    binding in the current scope will be removed.

  It is possible for the cache entry to exist prior to the call but
  have no type set if it was created on the :manual:`cmake(1)` command
  line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option
  without specifying a type.  In this case the ``set`` command will add the
  type.  Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
  and the ``<value>`` provided on the command line is a relative path,
  then the ``set`` command will treat the path as relative to the
  current working directory and convert it to an absolute path.

Set Environment Variable
^^^^^^^^^^^^^^^^^^^^^^^^

.. signature::
  set(ENV{<variable>} [<value>])
  :target: ENV

  Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
  to the given value.
  Subsequent calls of ``$ENV{<variable>}`` will return this new value.

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

  If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is
  an empty string, then this command will clear any existing value of the
  environment variable.

  Arguments after ``<value>`` are ignored. If extra arguments are found,
  then an author warning is issued.

See Also
^^^^^^^^

* :command:`unset`


code:
set_directory_properties
------------------------

Set properties of the current directory and subdirectories.

.. code-block:: cmake

  set_directory_properties(PROPERTIES <prop1> <value1> [<prop2> <value2>] ...)

Sets properties of the current directory and its subdirectories in key-value
pairs.

See also the :command:`set_property(DIRECTORY)` command.

See :ref:`Directory Properties` for the list of properties known to CMake
and their individual documentation for the behavior of each property.

See Also
^^^^^^^^

* :command:`define_property`
* :command:`get_directory_property`
* the more general :command:`set_property` command


code:
set_property
------------

Set a named property in a given scope.

.. code-block:: cmake

  set_property(<GLOBAL                      |
                DIRECTORY [<dir>]           |
                TARGET    [<target1> ...]   |
                SOURCE    [<src1> ...]
                          [DIRECTORY <dirs> ...]
                          [TARGET_DIRECTORY <targets> ...] |
                INSTALL   [<file1> ...]     |
                TEST      [<test1> ...]
                          [DIRECTORY <dir>] |
                CACHE     [<entry1> ...]    >
               [APPEND] [APPEND_STRING]
               PROPERTY <name> [<value1> ...])

Sets one property on zero or more objects of a scope.

The first argument determines the scope in which the property is set.
It must be one of the following:

``GLOBAL``
  Scope is unique and does not accept a name.

``DIRECTORY``
  Scope defaults to the current directory but other directories
  (already processed by CMake) may be named by full or relative path.
  Relative paths are treated as relative to the current source directory.
  See also the :command:`set_directory_properties` command.

  .. versionadded:: 3.19
    ``<dir>`` may reference a binary directory.

``TARGET``
  Scope may name zero or more existing targets.
  See also the :command:`set_target_properties` command.

  :ref:`Alias Targets` do not support setting target properties.

``SOURCE``
  Scope may name zero or more source files.  By default, source file properties
  are only visible to targets added in the same directory (``CMakeLists.txt``).

  .. versionadded:: 3.18
    Visibility can be set in other directory scopes using one or both of the
    following sub-options:

    ``DIRECTORY <dirs>...``
      The source file property will be set in each of the ``<dirs>``
      directories' scopes.  CMake must already know about
      each of these directories, either by having added them through a call to
      :command:`add_subdirectory` or it being the top level source directory.
      Relative paths are treated as relative to the current source directory.

      .. versionadded:: 3.19
        ``<dirs>`` may reference a binary directory.

    ``TARGET_DIRECTORY <targets>...``
      The source file property will be set in each of the directory scopes
      where any of the specified ``<targets>`` were created (the ``<targets>``
      must therefore already exist).

  See also the :command:`set_source_files_properties` command.

``INSTALL``
  .. versionadded:: 3.1

  Scope may name zero or more installed file paths.
  These are made available to CPack to influence deployment.

  Both the property key and value may use generator expressions.
  Specific properties may apply to installed files and/or directories.

  Path components have to be separated by forward slashes,
  must be normalized and are case sensitive.

  To reference the installation prefix itself with a relative path use ``.``.

  Currently installed file properties are only defined for
  the WIX generator where the given paths are relative
  to the installation prefix.

``TEST``
  Scope is limited to the directory the command is called in. It may name zero
  or more existing tests. See also command :command:`set_tests_properties`.

  Test property values may be specified using
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  for tests created by the :command:`add_test(NAME)` signature.

  .. versionadded:: 3.28

    Visibility can be set in other directory scopes using the following sub-option:

    ``DIRECTORY <dir>``
      The test property will be set in the ``<dir>`` directory's scope. CMake must
      already know about this directory, either by having added it through a call
      to :command:`add_subdirectory` or it being the top level source directory.
      Relative paths are treated as relative to the current source directory.
      ``<dir>`` may reference a binary directory.

``CACHE``
  Scope must name zero or more existing cache entries.

The required ``PROPERTY`` option is immediately followed by the name of
the property to set.  Remaining arguments are used to compose the
property value in the form of a semicolon-separated list.

If the ``APPEND`` option is given the list is appended to any existing
property value (except that empty values are ignored and not appended).
If the ``APPEND_STRING`` option is given the string is
appended to any existing property value as string, i.e. it results in a
longer string and not a list of strings.  When using ``APPEND`` or
``APPEND_STRING`` with a property defined to support ``INHERITED``
behavior (see :command:`define_property`), no inheriting occurs when
finding the initial value to append to.  If the property is not already
directly set in the nominated scope, the command will behave as though
``APPEND`` or ``APPEND_STRING`` had not been given.

.. note::

  The :prop_sf:`GENERATED` source file property may be globally visible.
  See its documentation for details.

See Also
^^^^^^^^

* :command:`define_property`
* :command:`get_property`
* The :manual:`cmake-properties(7)` manual for a list of properties
  in each scope.


code:
set_source_files_properties
---------------------------

Source files can have properties that affect how they are built.

.. code-block:: cmake

  set_source_files_properties(<files> ...
                              [DIRECTORY <dirs> ...]
                              [TARGET_DIRECTORY <targets> ...]
                              PROPERTIES <prop1> <value1>
                              [<prop2> <value2>] ...)

Sets properties associated with source files using a key/value paired
list.

.. versionadded:: 3.18
  By default, source file properties are only visible to targets added in the
  same directory (``CMakeLists.txt``).  Visibility can be set in other directory
  scopes using one or both of the following options:

``DIRECTORY <dirs>...``
  The source file properties will be set in each of the ``<dirs>``
  directories' scopes.  CMake must already know about each of these
  source directories, either by having added them through a call to
  :command:`add_subdirectory` or it being the top level source directory.
  Relative paths are treated as relative to the current source directory.

``TARGET_DIRECTORY <targets>...``
  The source file properties will be set in each of the directory scopes
  where any of the specified ``<targets>`` were created (the ``<targets>``
  must therefore already exist).

Use :command:`get_source_file_property` to get property values.
See also the :command:`set_property(SOURCE)` command.

.. note::

  The :prop_sf:`GENERATED` source file property may be globally visible.
  See its documentation for details.

See Also
^^^^^^^^

* :command:`define_property`
* :command:`get_source_file_property`
* :ref:`Source File Properties` for the list of properties known
  to CMake


code:
set_target_properties
---------------------

Targets can have properties that affect how they are built.

.. code-block:: cmake

  set_target_properties(<targets> ...
                        PROPERTIES <prop1> <value1>
                        [<prop2> <value2>] ...)

Sets properties on targets.  The syntax for the command is to list all
the targets you want to change, and then provide the values you want to
set next.  You can use any prop value pair you want and extract it
later with the :command:`get_property` or :command:`get_target_property`
command.

:ref:`Alias Targets` do not support setting target properties.

See Also
^^^^^^^^

* :command:`define_property`
* :command:`get_target_property`
* the more general :command:`set_property` command
* :ref:`Target Properties` for the list of properties known to CMake


code:
set_tests_properties
--------------------

Set a property of the tests.

.. code-block:: cmake

  set_tests_properties(<tests>...
                       [DIRECTORY <dir>]
                       PROPERTIES <prop1> <value1>
                       [<prop2> <value2>]...)

Sets a property for the tests.  If the test is not found, CMake
will report an error.

Test property values may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>`
for tests created by the :command:`add_test(NAME)` signature.

.. versionadded:: 3.28
  Visibility can be set in other directory scopes using the following option:

  ``DIRECTORY <dir>``
    The test properties will be set in the ``<dir>`` directory's scope.
    CMake must already know about this directory, either by having added it
    through a call to :command:`add_subdirectory` or it being the top level
    source directory. Relative paths are treated as relative to the current
    source directory. ``<dir>`` may reference a binary directory.

See Also
^^^^^^^^

* :command:`add_test`
* :command:`define_property`
* the more general :command:`set_property` command
* :ref:`Test Properties` for the list of properties known to CMake


code:
site_name
---------

Set the given variable to the name of the computer.

.. code-block:: cmake

  site_name(variable)

On UNIX-like platforms, if the variable ``HOSTNAME`` is set, its value
will be executed as a command expected to print out the host name,
much like the ``hostname`` command-line tool.


code:
source_group
------------

Define a grouping for source files in IDE project generation.
There are two different signatures to create source groups.

.. code-block:: cmake

  source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
  source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])

Defines a group into which sources will be placed in project files.
This is intended to set up file tabs in Visual Studio.
The group is scoped in the directory where the command is called,
and applies to sources in targets created in that directory.

The options are:

``TREE``
 .. versionadded:: 3.8

 CMake will automatically detect, from ``<src>`` files paths, source groups
 it needs to create, to keep structure of source groups analogically to the
 actual files and directories structure in the project. Paths of ``<src>``
 files will be cut to be relative to ``<root>``. The command fails if the
 paths within ``src`` do not start with ``root``.

``PREFIX``
 .. versionadded:: 3.8

 Source group and files located directly in ``<root>`` path, will be placed
 in ``<prefix>`` source groups.

``FILES``
 Any source file specified explicitly will be placed in group
 ``<name>``.  Relative paths are interpreted with respect to the
 current source directory.

``REGULAR_EXPRESSION``
 Any source file whose name matches the regular expression will
 be placed in group ``<name>``.

If a source file matches multiple groups, the *last* group that
explicitly lists the file with ``FILES`` will be favored, if any.
If no group explicitly lists the file, the *last* group whose
regular expression matches the file will be favored.

The ``<name>`` of the group and ``<prefix>`` argument may contain forward
slashes or backslashes to specify subgroups.  Backslashes need to be escaped
appropriately:

.. code-block:: cmake

  source_group(base/subdir ...)
  source_group(outer\\inner ...)
  source_group(TREE <root> PREFIX sources\\inc ...)

.. versionadded:: 3.18
  Allow using forward slashes (``/``) to specify subgroups.

For backwards compatibility, the short-hand signature

.. code-block:: cmake

  source_group(<name> <regex>)

is equivalent to

.. code-block:: cmake

  source_group(<name> REGULAR_EXPRESSION <regex>)


code:
string
------

String operations.

Synopsis
^^^^^^^^

.. parsed-literal::

  `Search and Replace`_
    string(`FIND`_ <string> <substring> <out-var> [...])
    string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...)
    string(`REGEX MATCH`_ <match-regex> <out-var> <input>...)
    string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...)
    string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...)

  `Manipulation`_
    string(`APPEND`_ <string-var> [<input>...])
    string(`PREPEND`_ <string-var> [<input>...])
    string(`CONCAT`_ <out-var> [<input>...])
    string(`JOIN`_ <glue> <out-var> [<input>...])
    string(`TOLOWER`_ <string> <out-var>)
    string(`TOUPPER`_ <string> <out-var>)
    string(`LENGTH <LENGTH_>`_ <string> <out-var>)
    string(`SUBSTRING`_ <string> <begin> <length> <out-var>)
    string(`STRIP`_ <string> <out-var>)
    string(`GENEX_STRIP`_ <string> <out-var>)
    string(`REPEAT`_ <string> <count> <out-var>)

  `Comparison`_
    string(`COMPARE`_ <op> <string1> <string2> <out-var>)

  `Hashing`_
    string(`\<HASH\>`_ <out-var> <input>)

  `Generation`_
    string(`ASCII`_ <number>... <out-var>)
    string(`HEX`_ <string> <out-var>)
    string(`CONFIGURE`_ <string> <out-var> [...])
    string(`MAKE_C_IDENTIFIER`_ <string> <out-var>)
    string(`RANDOM`_ [<option>...] <out-var>)
    string(`TIMESTAMP`_ <out-var> [<format string>] [UTC])
    string(`UUID`_ <out-var> ...)

  `JSON`_
    string(JSON <out-var> [ERROR_VARIABLE <error-var>]
           {`GET <JSON GET_>`_ | `TYPE <JSON TYPE_>`_ | `LENGTH <JSON LENGTH_>`_ | `REMOVE <JSON REMOVE_>`_}
           <json-string> <member|index> [<member|index> ...])
    string(JSON <out-var> [ERROR_VARIABLE <error-var>]
           `MEMBER <JSON MEMBER_>`_ <json-string>
           [<member|index> ...] <index>)
    string(JSON <out-var> [ERROR_VARIABLE <error-var>]
           `SET <JSON SET_>`_ <json-string>
           <member|index> [<member|index> ...] <value>)
    string(JSON <out-var> [ERROR_VARIABLE <error-var>]
           `EQUAL <JSON EQUAL_>`_ <json-string1> <json-string2>)

Search and Replace
^^^^^^^^^^^^^^^^^^

Search and Replace With Plain Strings
"""""""""""""""""""""""""""""""""""""

.. signature::
  string(FIND <string> <substring> <output_variable> [REVERSE])

  Return the position where the given ``<substring>`` was found in
  the supplied ``<string>``.  If the ``REVERSE`` flag was used, the command
  will search for the position of the last occurrence of the specified
  ``<substring>``.  If the ``<substring>`` is not found, a position of -1 is
  returned.

  The ``string(FIND)`` subcommand treats all strings as ASCII-only characters.
  The index stored in ``<output_variable>`` will also be counted in bytes,
  so strings containing multi-byte characters may lead to unexpected results.

.. signature::
  string(REPLACE <match_string>
         <replace_string> <output_variable>
         <input> [<input>...])

  Replace all occurrences of ``<match_string>`` in the ``<input>``
  with ``<replace_string>`` and store the result in the ``<output_variable>``.

Search and Replace With Regular Expressions
"""""""""""""""""""""""""""""""""""""""""""

.. signature::
  string(REGEX MATCH <regular_expression>
         <output_variable> <input> [<input>...])

  Match the ``<regular_expression>`` once and store the match in the
  ``<output_variable>``.
  All ``<input>`` arguments are concatenated before matching.
  Regular expressions are specified in the subsection just below.

.. signature::
  string(REGEX MATCHALL <regular_expression>
         <output_variable> <input> [<input>...])

  Match the ``<regular_expression>`` as many times as possible and store the
  matches in the ``<output_variable>`` as a list.
  All ``<input>`` arguments are concatenated before matching.

.. signature::
  string(REGEX REPLACE <regular_expression>
         <replacement_expression> <output_variable>
         <input> [<input>...])

  Match the ``<regular_expression>`` as many times as possible and substitute
  the ``<replacement_expression>`` for the match in the output.
  All ``<input>`` arguments are concatenated before matching.

  The ``<replacement_expression>`` may refer to parenthesis-delimited
  subexpressions of the match using ``\1``, ``\2``, ..., ``\9``.  Note that
  two backslashes (``\\1``) are required in CMake code to get a backslash
  through argument parsing.

.. _`Regex Specification`:

Regex Specification
"""""""""""""""""""

The following characters have special meaning in regular expressions:

``^``
  Matches at beginning of input
``$``
  Matches at end of input
``.``
  Matches any single character
``\<char>``
  Matches the single character specified by ``<char>``.  Use this to
  match special regex characters, e.g. ``\.`` for a literal ``.``
  or ``\\`` for a literal backslash ``\``.  Escaping a non-special
  character is unnecessary but allowed, e.g. ``\a`` matches ``a``.
``[ ]``
  Matches any character(s) inside the brackets
``[^ ]``
  Matches any character(s) not inside the brackets
``-``
  Inside brackets, specifies an inclusive range between
  characters on either side e.g. ``[a-f]`` is ``[abcdef]``
  To match a literal ``-`` using brackets, make it the first
  or the last character e.g. ``[+*/-]`` matches basic
  mathematical operators.
``*``
  Matches preceding pattern zero or more times
``+``
  Matches preceding pattern one or more times
``?``
  Matches preceding pattern zero or once only
``|``
  Matches a pattern on either side of the ``|``
``()``
  Saves a matched subexpression, which can be referenced
  in the ``REGEX REPLACE`` operation.

  .. versionadded:: 3.9
    All regular expression-related commands, including e.g.
    :command:`if(MATCHES)`, save subgroup matches in the variables
    :variable:`CMAKE_MATCH_<n>` for ``<n>`` 0..9.

``*``, ``+`` and ``?`` have higher precedence than concatenation.  ``|``
has lower precedence than concatenation.  This means that the regular
expression ``^ab+d$`` matches ``abbd`` but not ``ababd``, and the regular
expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``.

CMake language :ref:`Escape Sequences` such as ``\t``, ``\r``, ``\n``,
and ``\\`` may be used to construct literal tabs, carriage returns,
newlines, and backslashes (respectively) to pass in a regex.  For example:

* The quoted argument ``"[ \t\r\n]"`` specifies a regex that matches
  any single whitespace character.
* The quoted argument ``"[/\\]"`` specifies a regex that matches
  a single forward slash ``/`` or backslash ``\``.
* The quoted argument ``"[A-Za-z0-9_]"`` specifies a regex that matches
  any single "word" character in the C locale.
* The quoted argument ``"\\(\\a\\+b\\)"`` specifies a regex that matches
  the exact string ``(a+b)``.  Each ``\\`` is parsed in a quoted argument
  as just ``\``, so the regex itself is actually ``\(\a\+\b\)``.  This
  can alternatively be specified in a :ref:`bracket argument` without
  having to escape the backslashes, e.g. ``[[\(\a\+\b\)]]``.

Manipulation
^^^^^^^^^^^^

.. signature::
  string(APPEND <string_variable> [<input>...])

  .. versionadded:: 3.4

  Append all the ``<input>`` arguments to the string.

.. signature::
  string(PREPEND <string_variable> [<input>...])

  .. versionadded:: 3.10

  Prepend all the ``<input>`` arguments to the string.

.. signature::
  string(CONCAT <output_variable> [<input>...])

  Concatenate all the ``<input>`` arguments together and store
  the result in the named ``<output_variable>``.

.. signature::
  string(JOIN <glue> <output_variable> [<input>...])

  .. versionadded:: 3.12

  Join all the ``<input>`` arguments together using the ``<glue>``
  string and store the result in the named ``<output_variable>``.

  To join a list's elements, prefer to use the ``JOIN`` operator
  from the :command:`list` command.  This allows for the elements to have
  special characters like ``;`` in them.

.. signature::
  string(TOLOWER <string> <output_variable>)

  Convert ``<string>`` to lower characters.

.. signature::
  string(TOUPPER <string> <output_variable>)

  Convert ``<string>`` to upper characters.

.. signature::
  string(LENGTH <string> <output_variable>)

  Store in an ``<output_variable>`` a given string's length in bytes.
  Note that this means if ``<string>`` contains multi-byte characters,
  the result stored in ``<output_variable>`` will *not* be
  the number of characters.

.. signature::
  string(SUBSTRING <string> <begin> <length> <output_variable>)

  Store in an ``<output_variable>`` a substring of a given ``<string>``.  If
  ``<length>`` is ``-1`` the remainder of the string starting at ``<begin>``
  will be returned.

  .. versionchanged:: 3.2
    If ``<string>`` is shorter than ``<length>``
    then the end of the string is used instead.
    Previous versions of CMake reported an error in this case.

  Both ``<begin>`` and ``<length>`` are counted in bytes, so care must
  be exercised if ``<string>`` could contain multi-byte characters.

.. signature::
  string(STRIP <string> <output_variable>)

  Store in an ``<output_variable>`` a substring of a given ``<string>``
  with leading and trailing spaces removed.

.. signature::
  string(GENEX_STRIP <string> <output_variable>)

  .. versionadded:: 3.1

  Strip any :manual:`generator expressions <cmake-generator-expressions(7)>`
  from the input ``<string>`` and store the result
  in the ``<output_variable>``.

.. signature::
  string(REPEAT <string> <count> <output_variable>)

  .. versionadded:: 3.15

  Produce the output string as the input ``<string>``
  repeated ``<count>`` times.

Comparison
^^^^^^^^^^

.. _COMPARE:

.. signature::
  string(COMPARE LESS <string1> <string2> <output_variable>)
  string(COMPARE GREATER <string1> <string2> <output_variable>)
  string(COMPARE EQUAL <string1> <string2> <output_variable>)
  string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
  string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
  string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)

  Compare the strings and store true or false in the ``<output_variable>``.

  .. versionadded:: 3.7
    Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options.

.. _`Supported Hash Algorithms`:

Hashing
^^^^^^^

.. signature::
  string(<HASH> <output_variable> <input>)
  :target: <HASH>

  Compute a cryptographic hash of the ``<input>`` string.
  The supported ``<HASH>`` algorithm names are:

  ``MD5``
    Message-Digest Algorithm 5, RFC 1321.
  ``SHA1``
    US Secure Hash Algorithm 1, RFC 3174.
  ``SHA224``
    US Secure Hash Algorithms, RFC 4634.
  ``SHA256``
    US Secure Hash Algorithms, RFC 4634.
  ``SHA384``
    US Secure Hash Algorithms, RFC 4634.
  ``SHA512``
    US Secure Hash Algorithms, RFC 4634.
  ``SHA3_224``
    Keccak SHA-3.
  ``SHA3_256``
    Keccak SHA-3.
  ``SHA3_384``
    Keccak SHA-3.
  ``SHA3_512``
    Keccak SHA-3.

  .. versionadded:: 3.8
    Added the ``SHA3_*`` hash algorithms.

Generation
^^^^^^^^^^

.. signature::
  string(ASCII <number> [<number> ...] <output_variable>)

  Convert all numbers into corresponding ASCII characters.

.. signature::
  string(HEX <string> <output_variable>)

  .. versionadded:: 3.18

  Convert each byte in the input ``<string>`` to its hexadecimal representation
  and store the concatenated hex digits in the ``<output_variable>``.
  Letters in the output (``a`` through ``f``) are in lowercase.

.. signature::
  string(CONFIGURE <string> <output_variable>
         [@ONLY] [ESCAPE_QUOTES])

  Transform a ``<string>`` like :command:`configure_file` transforms a file.

.. signature::
  string(MAKE_C_IDENTIFIER <string> <output_variable>)

  Convert each non-alphanumeric character in the input ``<string>`` to an
  underscore and store the result in the ``<output_variable>``.  If the first
  character of the ``<string>`` is a digit, an underscore will also be
  prepended to the result.

.. signature::
  string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
         [RANDOM_SEED <seed>] <output_variable>)

  Return a random string of given ``<length>`` consisting of
  characters from the given ``<alphabet>``.  Default length is 5 characters
  and default alphabet is all numbers and upper and lower case letters.
  If an integer ``RANDOM_SEED`` is given, its value will be used to seed the
  random number generator.

.. signature::
  string(TIMESTAMP <output_variable> [<format_string>] [UTC])

  Write a string representation of the current date
  and/or time to the ``<output_variable>``.

  If the command is unable to obtain a timestamp, the ``<output_variable>``
  will be set to the empty string ``""``.

  The optional ``UTC`` flag requests the current date/time representation to
  be in Coordinated Universal Time (UTC) rather than local time.

  The optional ``<format_string>`` may contain the following format
  specifiers:

  ``%%``
    .. versionadded:: 3.8

    A literal percent sign (%).

  ``%d``
    The day of the current month (01-31).

  ``%H``
    The hour on a 24-hour clock (00-23).

  ``%I``
    The hour on a 12-hour clock (01-12).

  ``%j``
    The day of the current year (001-366).

  ``%m``
    The month of the current year (01-12).

  ``%b``
    .. versionadded:: 3.7

    Abbreviated month name (e.g. Oct).

  ``%B``
    .. versionadded:: 3.10

    Full month name (e.g. October).

  ``%M``
    The minute of the current hour (00-59).

  ``%s``
    .. versionadded:: 3.6

    Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).

  ``%S``
    The second of the current minute.  60 represents a leap second. (00-60)

  ``%f``
    .. versionadded:: 3.23

    The microsecond of the current second (000000-999999).

  ``%U``
    The week number of the current year (00-53).

  ``%V``
    .. versionadded:: 3.22

    The ISO 8601 week number of the current year (01-53).

  ``%w``
    The day of the current week. 0 is Sunday. (0-6)

  ``%a``
    .. versionadded:: 3.7

    Abbreviated weekday name (e.g. Fri).

  ``%A``
    .. versionadded:: 3.10

    Full weekday name (e.g. Friday).

  ``%y``
    The last two digits of the current year (00-99).

  ``%Y``
    The current year.

  ``%z``
    .. versionadded:: 3.26

    The offset of the time zone from UTC, in hours and minutes,
    with format ``+hhmm`` or ``-hhmm``.

  ``%Z``
    .. versionadded:: 3.26

    The time zone name.

  Unknown format specifiers will be ignored and copied to the output
  as-is.

  If no explicit ``<format_string>`` is given, it will default to:

  ::

    %Y-%m-%dT%H:%M:%S    for local time.
    %Y-%m-%dT%H:%M:%SZ   for UTC.

  .. versionadded:: 3.8
    If the ``SOURCE_DATE_EPOCH`` environment variable is set,
    its value will be used instead of the current time.
    See https://reproducible-builds.org/specs/source-date-epoch/ for details.

.. signature::
  string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
         TYPE <MD5|SHA1> [UPPER])

  .. versionadded:: 3.1

  Create a universally unique identifier (aka GUID) as per RFC4122
  based on the hash of the combined values of ``<namespace>``
  (which itself has to be a valid UUID) and ``<name>``.
  The hash algorithm can be either ``MD5`` (Version 3 UUID) or
  ``SHA1`` (Version 5 UUID).
  A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
  where each ``x`` represents a lower case hexadecimal character.
  Where required, an uppercase representation can be requested
  with the optional ``UPPER`` flag.

.. _JSON:

JSON
^^^^

.. versionadded:: 3.19

Functionality for querying a JSON string.

.. note::
  In each of the following JSON-related subcommands, if the optional
  ``ERROR_VARIABLE`` argument is given, errors will be reported in
  ``<error-variable>`` and the ``<out-var>`` will be set to
  ``<member|index>-[<member|index>...]-NOTFOUND`` with the path elements
  up to the point where the error occurred, or just ``NOTFOUND`` if there
  is no relevant path.  If an error occurs but the ``ERROR_VARIABLE``
  option is not present, a fatal error message is generated.  If no error
  occurs, the ``<error-variable>`` will be set to ``NOTFOUND``.

.. signature::
  string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
         GET <json-string> <member|index> [<member|index> ...])
  :target: JSON GET

  Get an element from ``<json-string>`` at the location given
  by the list of ``<member|index>`` arguments.
  Array and object elements will be returned as a JSON string.
  Boolean elements will be returned as ``ON`` or ``OFF``.
  Null elements will be returned as an empty string.
  Number and string types will be returned as strings.

.. signature::
  string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
         TYPE <json-string> <member|index> [<member|index> ...])
  :target: JSON TYPE

  Get the type of an element in ``<json-string>`` at the location
  given by the list of ``<member|index>`` arguments. The ``<out-var>``
  will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``,
  ``ARRAY``, or ``OBJECT``.

.. signature::
  string(JSON <out-var> [ERROR_VARIABLE <error-var>]
         MEMBER <json-string>
         [<member|index> ...] <index>)
  :target: JSON MEMBER

  Get the name of the ``<index>``-th member in ``<json-string>``
  at the location given by the list of ``<member|index>`` arguments.
  Requires an element of object type.

.. signature::
  string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
         LENGTH <json-string> [<member|index> ...])
  :target: JSON LENGTH

  Get the length of an element in ``<json-string>`` at the location
  given by the list of ``<member|index>`` arguments.
  Requires an element of array or object type.

.. signature::
  string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
         REMOVE <json-string> <member|index> [<member|index> ...])
  :target: JSON REMOVE

  Remove an element from ``<json-string>`` at the location
  given by the list of ``<member|index>`` arguments. The JSON string
  without the removed element will be stored in ``<out-var>``.

.. signature::
  string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
         SET <json-string> <member|index> [<member|index> ...] <value>)
  :target: JSON SET

  Set an element in ``<json-string>`` at the location
  given by the list of ``<member|index>`` arguments to ``<value>``.
  The contents of ``<value>`` should be valid JSON.
  If ``<json-string>`` is an array, ``<value>`` can be appended to the end of
  the array by using a number greater or equal to the array length as the
  ``<member|index>`` argument.

.. signature::
  string(JSON <out-var> [ERROR_VARIABLE <error-var>]
         EQUAL <json-string1> <json-string2>)
  :target: JSON EQUAL

  Compare the two JSON objects given by ``<json-string1>``
  and ``<json-string2>`` for equality.  The contents of ``<json-string1>``
  and ``<json-string2>`` should be valid JSON.  The ``<out-var>``
  will be set to a true value if the JSON objects are considered equal,
  or a false value otherwise.


code:
subdir_depends
--------------

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

Does nothing.

.. code-block:: cmake

  subdir_depends(subdir dep1 dep2 ...)

Does not do anything.  This command used to help projects order
parallel builds correctly.  This functionality is now automatic.


code:
subdirs
-------

.. deprecated:: 3.0

  Use the :command:`add_subdirectory` command instead.

Add a list of subdirectories to the build.

.. code-block:: cmake

  subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
          [PREORDER] )

Add a list of subdirectories to the build.  The :command:`add_subdirectory`
command should be used instead of ``subdirs`` although ``subdirs`` will still
work.  This will cause any CMakeLists.txt files in the sub directories
to be processed by CMake.  Any directories after the ``PREORDER`` flag are
traversed first by makefile builds, the ``PREORDER`` flag has no effect on
IDE projects.  Any directories after the ``EXCLUDE_FROM_ALL`` marker will
not be included in the top level makefile or project file.  This is
useful for having CMake create makefiles or projects for a set of
examples in a project.  You would want CMake to generate makefiles or
project files for all the examples at the same time, but you would not
want them to show up in the top level project or be built each time
make is run from the top.


code:
target_compile_definitions
--------------------------

Add compile definitions to a target.

.. code-block:: cmake

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

Specifies compile definitions to use when compiling a given ``<target>``.  The
named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
:ref:`ALIAS target <Alias Targets>`.

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

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

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

Any leading ``-D`` on an item will be removed.  Empty items are ignored.
For example, the following are all equivalent:

.. code-block:: cmake

  target_compile_definitions(foo PUBLIC FOO)
  target_compile_definitions(foo PUBLIC -DFOO)  # -D removed
  target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
  target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored

Definitions may optionally have values:

.. code-block:: cmake

  target_compile_definitions(foo PUBLIC FOO=1)

Note that many compilers treat ``-DFOO`` as equivalent to ``-DFOO=1``, but
other tools may not recognize this in all circumstances (e.g. IntelliSense).

See Also
^^^^^^^^

* :command:`add_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`


code:
target_compile_features
-----------------------

.. versionadded:: 3.1

Add expected compiler features to a target.

.. code-block:: cmake

  target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])

Specifies compiler features required when compiling a given target.  If the
feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES`,
:variable:`CMAKE_CUDA_COMPILE_FEATURES`, or :variable:`CMAKE_CXX_COMPILE_FEATURES`
variables, then an error will be reported by CMake.  If the use of the feature requires
an additional compiler flag, such as ``-std=gnu++11``, the flag will be added
automatically.

The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the features.  ``PRIVATE`` and ``PUBLIC`` items will
populate the :prop_tgt:`COMPILE_FEATURES` property of ``<target>``.
``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_COMPILE_FEATURES` property of ``<target>``.
Repeated calls for the same ``<target>`` append items.

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

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

.. |command_name| replace:: ``target_compile_features``
.. |more_see_also| replace:: See the :manual:`cmake-compile-features(7)`
   manual for information on compile features and a list of supported compilers.
.. include:: GENEX_NOTE.txt
   :start-line: 1

See Also
^^^^^^^^

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


code:
target_compile_options
----------------------

Add compile options to a target.

.. code-block:: cmake

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

Adds options to the :prop_tgt:`COMPILE_OPTIONS` or
:prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. These options
are used when compiling the given ``<target>``, which must have been
created by a command such as :command:`add_executable` or
:command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`.

.. note::

  These options are not used when linking the target.
  See the :command:`target_link_options` command for that.

Arguments
^^^^^^^^^

If ``BEFORE`` is specified, the content will be prepended to the property
instead of being appended.  See policy :policy:`CMP0101` which affects
whether ``BEFORE`` will be ignored in certain cases.

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

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

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

.. include:: OPTIONS_SHELL.txt

See Also
^^^^^^^^

* This command can be used to add any options. However, for adding
  preprocessor definitions and include directories it is recommended
  to use the more specific commands :command:`target_compile_definitions`
  and :command:`target_include_directories`.

* For directory-wide settings, there is the command :command:`add_compile_options`.

* For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`.

* This command adds compile options for all languages in a target.
  Use the :genex:`COMPILE_LANGUAGE` generator expression to specify
  per-language compile options.

* :command:`target_compile_features`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`

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


code:
target_include_directories
--------------------------

Add include directories to a target.

.. code-block:: cmake

  target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]
    <INTERFACE|PUBLIC|PRIVATE> [items1...]
    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

Specifies include directories to use when compiling a given target.
The named ``<target>`` must have been created by a command such
as :command:`add_executable` or :command:`add_library` and must not be an
:ref:`ALIAS target <Alias Targets>`.

By using ``AFTER`` or ``BEFORE`` explicitly, you can select between appending
and prepending, independent of the default.

The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify
the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`INCLUDE_DIRECTORIES`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``.
The following arguments specify include directories.

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

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

If ``SYSTEM`` is specified, the compiler will be told the directories
are meant as system include directories on some platforms.  This may
have effects such as suppressing warnings or skipping the contained
headers in dependency calculations (see compiler documentation).
Additionally, system include directories are searched after normal
include directories regardless of the order specified.

If ``SYSTEM`` is used together with ``PUBLIC`` or ``INTERFACE``, the
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be
populated with the specified directories.

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

Specified include directories may be absolute paths or relative paths.
A relative path will be interpreted as relative to the current source
directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and converted to an
absolute path before storing it in the associated target property.
If the path starts with a generator expression, it will always be assumed
to be an absolute path (with one exception noted below) and will be used
unmodified.

Include directories usage requirements commonly differ between the build-tree
and the install-tree.  The :genex:`BUILD_INTERFACE` and
:genex:`INSTALL_INTERFACE` generator expressions can be used to describe
separate usage requirements based on the usage location.  Relative paths
are allowed within the :genex:`INSTALL_INTERFACE` expression and are
interpreted as relative to the installation prefix.  Relative paths should not
be used in :genex:`BUILD_INTERFACE` expressions because they will not be
converted to absolute.  For example:

.. code-block:: cmake

  target_include_directories(mylib PUBLIC
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
    $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
  )

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

.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt

See Also
^^^^^^^^

* :command:`include_directories`
* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`


code:
target_link_directories
-----------------------

.. versionadded:: 3.13

Add link directories to a target.

.. code-block:: cmake

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

Specifies the paths in which the linker should search for libraries when
linking a given target.  Each item can be an absolute or relative path,
with the latter being interpreted as relative to the current source
directory.  These items will be added to the link command.

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

The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the :ref:`scope <Target Usage Requirements>` of the items that follow
them. ``PRIVATE`` and ``PUBLIC`` items will populate the
:prop_tgt:`LINK_DIRECTORIES` property of ``<target>``.  ``PUBLIC`` and
``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
property of ``<target>`` (:ref:`IMPORTED targets <Imported Targets>` only
support ``INTERFACE`` items).
Each item specifies a link directory and will be converted to an absolute
path if necessary before adding it to the relevant property.  Repeated
calls for the same ``<target>`` append items in the order called.

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

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

.. note::

  This command is rarely necessary and should be avoided where there are
  other choices.  Prefer to pass full absolute paths to libraries where
  possible, since this ensures the correct library will always be linked.
  The :command:`find_library` command provides the full path, which can
  generally be used directly in calls to :command:`target_link_libraries`.
  Situations where a library search path may be needed include:

  - Project generators like Xcode where the user can switch target
    architecture at build time, but a full path to a library cannot
    be used because it only provides one architecture (i.e. it is not
    a universal binary).
  - Libraries may themselves have other private library dependencies
    that expect to be found via ``RPATH`` mechanisms, but some linkers
    are not able to fully decode those paths (e.g. due to the presence
    of things like ``$ORIGIN``).

See Also
^^^^^^^^

* :command:`link_directories`
* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`