code:
dnl Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
dnl file Copyright.txt or https://cmake.org/licensing for details.

AC_DEFUN([CMAKE_FIND_BINARY],
[AC_ARG_VAR([CMAKE_BINARY], [path to the cmake binary])dnl

if test "x$ac_cv_env_CMAKE_BINARY_set" != "xset"; then
    AC_PATH_TOOL([CMAKE_BINARY], [cmake])dnl
fi
])dnl

# $1: package name
# $2: language (e.g. C/CXX/Fortran)
# $3: The compiler ID, defaults to GNU.
#     Possible values are: GNU, Intel, Clang, SunPro, HP, XL, VisualAge, PGI,
#     PathScale, Cray, SCO, MSVC, LCC
# $4: optional extra arguments to cmake, e.g. "-DCMAKE_SIZEOF_VOID_P=8"
# $5: optional path to cmake binary
AC_DEFUN([CMAKE_FIND_PACKAGE], [
AC_REQUIRE([CMAKE_FIND_BINARY])dnl

AC_ARG_VAR([$1][_][$2][FLAGS], [$2 compiler flags for $1. This overrides the cmake output])dnl
AC_ARG_VAR([$1][_LIBS], [linker flags for $1. This overrides the cmake output])dnl

failed=false
AC_MSG_CHECKING([for $1])
if test -z "${$1[]_$2[]FLAGS}"; then
    $1[]_$2[]FLAGS=`$CMAKE_BINARY --find-package "-DNAME=$1" "-DCOMPILER_ID=m4_default([$3], [GNU])" "-DLANGUAGE=$2" -DMODE=COMPILE $4` || failed=true
fi
if test -z "${$1[]_LIBS}"; then
    $1[]_LIBS=`$CMAKE_BINARY --find-package "-DNAME=$1" "-DCOMPILER_ID=m4_default([$3], [GNU])" "-DLANGUAGE=$2" -DMODE=LINK $4` || failed=true
fi

if $failed; then
    unset $1[]_$2[]FLAGS
    unset $1[]_LIBS

    AC_MSG_RESULT([no])
    $6
else
    AC_MSG_RESULT([yes])
    $5
fi[]dnl
])


code:
# bash completion for cmake(1)                             -*- shell-script -*-

_cmake()
{
    local cur prev words cword split=false
    if type -t _init_completion >/dev/null; then
        _init_completion -n = || return
    else
        # manual initialization for older bash completion versions
        COMPREPLY=()
        cur="${COMP_WORDS[COMP_CWORD]}"
        prev="${COMP_WORDS[COMP_CWORD-1]}"
    fi

    # Workaround for options like -DCMAKE_BUILD_TYPE=Release
    local prefix=
    if [[ $cur == -D* ]]; then
        prev=-D
        prefix=-D
        cur="${cur#-D}"
    elif [[ $cur == -U* ]]; then
        prev=-U
        prefix=-U
        cur="${cur#-U}"
    fi

    case "$prev" in
        -D)
            if [[ $cur == *=* ]]; then
            # complete values for variables
                local var type value
                var="${cur%%[:=]*}"
                value="${cur#*=}"

                if [[ $cur == CMAKE_BUILD_TYPE* ]]; then # most widely used case
                    COMPREPLY=( $( compgen -W 'Debug Release RelWithDebInfo
                        MinSizeRel' -- "$value" ) )
                    return
                fi

                if [[ $cur == *:* ]]; then
                    type="${cur#*:}"
                    type="${type%%=*}"
                else # get type from cache if it's not set explicitly
                    type=$( cmake -LA -N 2>/dev/null | grep "$var:" \
                        2>/dev/null )
                    type="${type#*:}"
                    type="${type%%=*}"
                fi
                case "$type" in
                    FILEPATH)
                        cur="$value"
                        _filedir
                        return
                        ;;
                    PATH)
                        cur="$value"
                        _filedir -d
                        return
                        ;;
                    BOOL)
                        COMPREPLY=( $( compgen -W 'ON OFF TRUE FALSE' -- \
                            "$value" ) )
                        return
                        ;;
                    STRING|INTERNAL)
                        # no completion available
                        return
                        ;;
                esac
            elif [[ $cur == *:* ]]; then
            # complete types
                local type="${cur#*:}"
                COMPREPLY=( $( compgen -W 'FILEPATH PATH STRING BOOL INTERNAL'\
                    -S = -- "$type" ) )
                compopt -o nospace
            else
            # complete variable names
                COMPREPLY=( $( compgen -W '$( cmake -LA -N 2>/dev/null |
                    tail -n +2 | cut -f1 -d: )' -P "$prefix" -- "$cur" ) )
                compopt -o nospace
            fi
            return
            ;;
        -U)
            COMPREPLY=( $( compgen -W '$( cmake -LA -N | tail -n +2 |
                cut -f1 -d: )' -P "$prefix" -- "$cur" ) )
            return
            ;;
    esac

    _split_longopt && split=true

    case "$prev" in
        -C|-P|--graphviz|--system-information)
            _filedir
            return
            ;;
        --build)
            # Seed the reply with non-directory arguments that we know are
            # allowed to follow --build. _filedir will then prepend any valid
            # directory matches to these.
            COMPREPLY=( $( compgen -W "--preset --list-presets" -- "$cur" ) )
            _filedir -d
            return
            ;;
        --install|--open)
            _filedir -d
            return
            ;;
        -E)
            COMPREPLY=( $( compgen -W "$( cmake -E help |& sed -n \
                '/^  [^ ]/{s|^  \([^ ]\{1,\}\) .*$|\1|;p}' 2>/dev/null )" \
                -- "$cur" ) )
            return
            ;;
        -G)
            local IFS=$'\n'
            local quoted
            printf -v quoted %q "$cur"
            COMPREPLY=( $( compgen -W '$( cmake --help 2>/dev/null | sed -n \
                -e "1,/^Generators/d" \
                -e "/^  *[^ =]/{s|^ *\([^=]*[^ =]\).*$|\1|;s| |\\\\ |g;p}" \
                2>/dev/null )' -- "$quoted" ) )
            return
            ;;
        --loglevel)
            COMPREPLY=( $(compgen -W 'error warning notice status verbose debug trace' -- $cur ) )
            ;;
        --help-command)
            COMPREPLY=( $( compgen -W '$( cmake --help-command-list 2>/dev/null|
                grep -v "^cmake version " )' -- "$cur" ) )
            return
            ;;
        --help-manual)
            COMPREPLY=( $( compgen -W '$( cmake --help-manual-list 2>/dev/null|
                grep -v "^cmake version " | sed -e "s/([0-9])$//" )' -- "$cur" ) )
            return
            ;;
        --help-module)
            COMPREPLY=( $( compgen -W '$( cmake --help-module-list 2>/dev/null|
                grep -v "^cmake version " )' -- "$cur" ) )
            return
            ;;
         --help-policy)
            COMPREPLY=( $( compgen -W '$( cmake --help-policy-list 2>/dev/null |
                grep -v "^cmake version " )' -- "$cur" ) )
            return
            ;;
         --help-property)
            COMPREPLY=( $( compgen -W '$( cmake --help-property-list \
                2>/dev/null | grep -v "^cmake version " )' -- "$cur" ) )
            return
            ;;
         --help-variable)
            COMPREPLY=( $( compgen -W '$( cmake --help-variable-list \
                2>/dev/null | grep -v "^cmake version " )' -- "$cur" ) )
            return
            ;;
        --list-presets)
            local IFS=$'\n'
            local quoted
            printf -v quoted %q "$cur"

            if [[ ! "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
                COMPREPLY=( $( compgen -W "configure${IFS}build${IFS}test${IFS}all" -- "$quoted" ) )
            fi
            return
            ;;
         --preset)
            local IFS=$'\n'
            local quoted
            printf -v quoted %q "$cur"

            local build_or_configure="configure"
            if [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
                build_or_configure="build"
            fi

            local presets=$( cmake --list-presets="$build_or_configure" 2>/dev/null |
                grep -o "^  \".*\"" | sed \
                -e "s/^  //g" \
                -e "s/\"//g" \
                -e 's/ /\\\\ /g' )
            COMPREPLY=( $( compgen -W "$presets" -- "$quoted" ) )
            return
            ;;
    esac

    $split && return

    if [[ "$cur" == -* ]]; then
        COMPREPLY=( $(compgen -W '$( _parse_help "$1" --help )' -- ${cur}) )
        [[ $COMPREPLY == *= ]] && compopt -o nospace
        [[ $COMPREPLY ]] && return
    fi

    _filedir
} &&
complete -F _cmake cmake

# ex: ts=4 sw=4 et filetype=sh

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
# bash completion for cpack(1)                             -*- shell-script -*-

_cpack()
{
    local cur prev words cword
    if type -t _init_completion >/dev/null; then
        _init_completion -n = || return
    else
        # manual initialization for older bash completion versions
        COMPREPLY=()
        cur="${COMP_WORDS[COMP_CWORD]}"
        prev="${COMP_WORDS[COMP_CWORD-1]}"
    fi

    case "$prev" in
        -G)
            COMPREPLY=( $( compgen -W '$( cpack --help 2>/dev/null |
                sed -e "1,/^Generators/d" -e "s|^ *\([^ ]*\) .*$|\1|" \
                2>/dev/null )' -- "$cur" ) )
            return
            ;;
        -C)
            COMPREPLY=( $( compgen -W 'Debug Release RelWithDebInfo
                MinSizeRel' -- "$cur" ) )
            return
            ;;
        -D)
            [[ $cur == *=* ]] && return # no completion for values
            COMPREPLY=( $( compgen -W '$( cpack --help-variable-list \
                2>/dev/null | grep -v "^cpack version " )' -S = -- "$cur" ) )
            compopt -o nospace
            return
            ;;
        -P|-R|--vendor)
            # argument required but no completions available
            return
            ;;
        -B)
            _filedir -d
            return
            ;;
        --config)
            _filedir
            return
            ;;
        --help-command)
            COMPREPLY=( $( compgen -W '$( cpack --help-command-list 2>/dev/null|
                grep -v "^cpack version " )' -- "$cur" ) )
            return
            ;;
        --help-manual)
            COMPREPLY=( $( compgen -W '$( cpack --help-manual-list 2>/dev/null|
                grep -v "^cpack version " | sed -e "s/([0-9])$//" )' -- "$cur" ) )
            return
            ;;
        --help-module)
            COMPREPLY=( $( compgen -W '$( cpack --help-module-list 2>/dev/null|
                grep -v "^cpack version " )' -- "$cur" ) )
            return
            ;;
        --help-policy)
            COMPREPLY=( $( compgen -W '$( cpack --help-policy-list 2>/dev/null |
                grep -v "^cpack version " )' -- "$cur" ) )
            return
            ;;
        --help-property)
            COMPREPLY=( $( compgen -W '$( cpack --help-property-list \
                2>/dev/null | grep -v "^cpack version " )' -- "$cur" ) )
            return
            ;;
        --help-variable)
            COMPREPLY=( $( compgen -W '$( cpack --help-variable-list \
                2>/dev/null | grep -v "^cpack version " )' -- "$cur" ) )
            return
            ;;
    esac

    if [[ "$cur" == -* ]]; then
        COMPREPLY=( $(compgen -W '$( _parse_help "$1" --help )' -- ${cur}) )
        [[ $COMPREPLY == *= ]] && compopt -o nospace
        [[ $COMPREPLY ]] && return
    fi

    _filedir
} &&
complete -F _cpack cpack

# ex: ts=4 sw=4 et filetype=sh


code:
# bash completion for ctest(1)                             -*- shell-script -*-

_ctest()
{
    local cur prev words cword
    if type -t _init_completion >/dev/null; then
        _init_completion -n = || return
    else
        # manual initialization for older bash completion versions
        COMPREPLY=()
        cur="${COMP_WORDS[COMP_CWORD]}"
        prev="${COMP_WORDS[COMP_CWORD-1]}"
    fi

    case "$prev" in
        -C|--build-config)
            COMPREPLY=( $( compgen -W 'Debug Release RelWithDebInfo
                MinSizeRel' -- "$cur" ) )
            return
            ;;
        -j|--parallel)
            COMPREPLY=( $( compgen -W "{1..$(( $(_ncpus)*2 ))}" -- "$cur" ) )
            return
            ;;
        -O|--output-log|-A|--add-notes|--extra-submit)
            _filedir
            return
            ;;
        -L|--label-regex|-LE|--label-exclude)
            COMPREPLY=( $( compgen -W '$( ctest --print-labels 2>/dev/null |
                grep "^  " 2>/dev/null | cut -d" " -f 3 )' -- "$cur" ) )
            return
            ;;
        --track|-I|--tests-information|--max-width|--timeout|--stop-time)
            # argument required but no completions available
            return
            ;;
        -R|--tests-regex|-E|--exclude-regex)
            COMPREPLY=( $( compgen -W '$( ctest -N 2>/dev/null |
                grep "^  Test" 2>/dev/null | cut -d: -f 2 )' -- "$cur" ) )
            return
            ;;
        -D|--dashboard)
            if [[ $cur == @(Experimental|Nightly|Continuous)* ]]; then
                local model action
                action=${cur#@(Experimental|Nightly|Continuous)}
                model=${cur%"$action"}
                COMPREPLY=( $( compgen -W 'Start Update Configure Build Test
                    Coverage Submit MemCheck' -P "$model" -- "$action" ) )
            else
                COMPREPLY=( $( compgen -W 'Experimental Nightly Continuous' \
                -- "$cur" ) )
                compopt -o nospace
            fi
            return
            ;;
        -M|--test-model)
            COMPREPLY=( $( compgen -W 'Experimental Nightly Continuous' -- \
                "$cur" ) )
            return
            ;;
        -T|--test-action)
            COMPREPLY=( $( compgen -W 'Start Update Configure Build Test
                Coverage Submit MemCheck' -- "$cur" ) )
            return
            ;;
        -S|--script|-SP|--script-new-process)
            _filedir '@(cmake|ctest)'
            return
            ;;
        --interactive-debug-mode)
            COMPREPLY=( $( compgen -W '0 1' -- "$cur" ) )
            return
            ;;

        --help-command)
            COMPREPLY=( $( compgen -W '$( ctest --help-command-list 2>/dev/null|
                grep -v "^ctest version " )' -- "$cur" ) )
            return
            ;;
        --help-manual)
            COMPREPLY=( $( compgen -W '$( ctest --help-manual-list 2>/dev/null|
                grep -v "^ctest version " | sed -e "s/([0-9])$//" )' -- "$cur" ) )
            return
            ;;
        --help-module)
            COMPREPLY=( $( compgen -W '$( ctest --help-module-list 2>/dev/null|
                grep -v "^ctest version " )' -- "$cur" ) )
            return
            ;;
        --help-policy)
            COMPREPLY=( $( compgen -W '$( ctest --help-policy-list 2>/dev/null |
                grep -v "^ctest version " )' -- "$cur" ) )
            return
            ;;
        --help-property)
            COMPREPLY=( $( compgen -W '$( ctest --help-property-list \
                2>/dev/null | grep -v "^ctest version " )' -- "$cur" ) )
            return
            ;;
        --help-variable)
            COMPREPLY=( $( compgen -W '$( ctest --help-variable-list \
                2>/dev/null | grep -v "^ctest version " )' -- "$cur" ) )
            return
            ;;
         --preset)
            local IFS=$'\n'
            local quoted
            printf -v quoted %q "$cur"
            COMPREPLY=( $( compgen -W '$( ctest --list-presets 2>/dev/null |
                grep -o "^  \".*\"" | sed \
                -e "s/^  //g" \
                -e "s/\"//g" \
                -e "s/ /\\\\ /g" )' -- "$quoted" ) )
            return
            ;;
    esac

    if [[ "$cur" == -* ]]; then
        COMPREPLY=( $(compgen -W '$( _parse_help "$1" --help )' -- ${cur}) )
        [[ $COMPREPLY == *= ]] && compopt -o nospace
        [[ $COMPREPLY ]] && return
    fi

    _filedir
} &&
complete -F _ctest ctest

# ex: ts=4 sw=4 et filetype=sh


code:
.. versionchanged:: 3.27

  Compatibility with versions of CMake older than 3.5 is deprecated.
  Calls to :command:`cmake_minimum_required(VERSION)` or
  :command:`cmake_policy(VERSION)` that do not specify at least
  3.5 as their policy version (optionally via ``...<max>``)
  will produce a deprecation warning in CMake 3.27 and above.

.. versionchanged:: 3.19

  Compatibility with versions of CMake older than 2.8.12 is deprecated.
  Calls to :command:`cmake_minimum_required(VERSION)` or
  :command:`cmake_policy(VERSION)` that do not specify at least
  2.8.12 as their policy version (optionally via ``...<max>``)
  will produce a deprecation warning in CMake 3.19 and above.


code:
Host And Device Specific Link Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.18
  When a device link step is involved, which is controlled by
  :prop_tgt:`CUDA_SEPARABLE_COMPILATION` and
  :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`,
  the raw options will be delivered to the host and device link steps (wrapped in
  ``-Xcompiler`` or equivalent for device link). Options wrapped with
  :genex:`$<DEVICE_LINK:...>` generator expression will be used
  only for the device link step. Options wrapped with :genex:`$<HOST_LINK:...>`
  generator expression will be used only for the host link step.


code:
A short-hand signature is:

.. parsed-literal::

   |FIND_XXX| (<VAR> name1 [path1 path2 ...])

The general signature is:

.. parsed-literal::

   |FIND_XXX| (
             <VAR>
             name | |NAMES|
             [HINTS [path | ENV var]... ]
             [PATHS [path | ENV var]... ]
             [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
             [PATH_SUFFIXES suffix1 [suffix2 ...]]
             [VALIDATOR function]
             [DOC "cache documentation string"]
             [NO_CACHE]
             [REQUIRED]
             [NO_DEFAULT_PATH]
             [NO_PACKAGE_ROOT_PATH]
             [NO_CMAKE_PATH]
             [NO_CMAKE_ENVIRONMENT_PATH]
             [NO_SYSTEM_ENVIRONMENT_PATH]
             [NO_CMAKE_SYSTEM_PATH]
             [NO_CMAKE_INSTALL_PREFIX]
             [CMAKE_FIND_ROOT_PATH_BOTH |
              ONLY_CMAKE_FIND_ROOT_PATH |
              NO_CMAKE_FIND_ROOT_PATH]
            )

This command is used to find a |SEARCH_XXX_DESC|.
A cache entry, or a normal variable if ``NO_CACHE`` is specified,
named by ``<VAR>`` is created to store the result of this command.
If the |SEARCH_XXX| is found the result is stored in the variable
and the search will not be repeated unless the variable is cleared.
If nothing is found, the result will be ``<VAR>-NOTFOUND``.

Options include:

``NAMES``
  Specify one or more possible names for the |SEARCH_XXX|.

  When using this to specify names with and without a version
  suffix, we recommend specifying the unversioned name first
  so that locally-built packages can be found before those
  provided by distributions.

``HINTS``, ``PATHS``
  Specify directories to search in addition to the default locations.
  The ``ENV var`` sub-option reads paths from a system environment
  variable.

  .. versionchanged:: 3.24
    On ``Windows`` platform, it is possible to include registry queries as part
    of the directories, using a :ref:`dedicated syntax <Find Using Windows Registry>`.
    Such specifications will be ignored on all other platforms.

``REGISTRY_VIEW``
  .. versionadded:: 3.24

  .. include:: FIND_XXX_REGISTRY_VIEW.txt

``PATH_SUFFIXES``
  Specify additional subdirectories to check below each directory
  location otherwise considered.

``VALIDATOR``
  .. versionadded:: 3.25

  Specify a :command:`function` to be called for each candidate item found
  (a :command:`macro` cannot be provided, that will result in an error).
  Two arguments will be passed to the validator function: the name of a
  result variable, and the absolute path to the candidate item.  The item
  will be accepted and the search will end unless the function sets the
  value in the result variable to false in the calling scope.  The result
  variable will hold a true value when the validator function is entered.

  .. parsed-literal::

     function(my_check validator_result_var item)
       if(NOT item MATCHES ...)
         set(${validator_result_var} FALSE PARENT_SCOPE)
       endif()
     endfunction()

     |FIND_XXX| (result NAMES ... VALIDATOR my_check)

  Note that if a cached result is used, the search is skipped and any
  ``VALIDATOR`` is ignored.  The cached result is not required to pass the
  validation function.

``DOC``
  Specify the documentation string for the ``<VAR>`` cache entry.

``NO_CACHE``
  .. versionadded:: 3.21

  The result of the search will be stored in a normal variable rather than
  a cache entry.

  .. note::

    If the variable is already set before the call (as a normal or cache
    variable) then the search will not occur.

  .. warning::

    This option should be used with caution because it can greatly increase
    the cost of repeated configure steps.

``REQUIRED``
  .. versionadded:: 3.18

  Stop processing with an error message if nothing is found, otherwise
  the search will be attempted again the next time |FIND_XXX| is invoked
  with the same variable.

If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
added to the search.
If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:

.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace::
   |prefix_XXX_SUBDIR| for each ``<prefix>`` in the
   :variable:`<PackageName>_ROOT` CMake variable and the
   :envvar:`<PackageName>_ROOT` environment variable if
   called from within a find module loaded by
   :command:`find_package(<PackageName>)`

.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
   |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`

.. |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
   |prefix_XXX_SUBDIR| for each ``<prefix>`` in :envvar:`CMAKE_PREFIX_PATH`

.. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace::
   |prefix_XXX_SUBDIR| for each ``<prefix>/[s]bin`` in ``PATH``, and
   |entry_XXX_SUBDIR| for other entries in ``PATH``

.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
   |prefix_XXX_SUBDIR| for each ``<prefix>`` in
   :variable:`CMAKE_SYSTEM_PREFIX_PATH`

1. If called from within a find module or any other script loaded by a call to
   :command:`find_package(<PackageName>)`, search prefixes unique to the
   current package being found.  See policy :policy:`CMP0074`.

   .. versionadded:: 3.12

   Specifically, search paths specified by the following variables, in order:

   a. :variable:`<PackageName>_ROOT` CMake variable,
      where ``<PackageName>`` is the case-preserved package name.

   b. :variable:`<PACKAGENAME>_ROOT` CMake variable,
      where ``<PACKAGENAME>`` is the upper-cased package name.
      See policy :policy:`CMP0144`.

      .. versionadded:: 3.27

   c. :envvar:`<PackageName>_ROOT` environment variable,
      where ``<PackageName>`` is the case-preserved package name.

   d. :envvar:`<PACKAGENAME>_ROOT` environment variable,
      where ``<PACKAGENAME>`` is the upper-cased package name.
      See policy :policy:`CMP0144`.

      .. versionadded:: 3.27

   The package root variables are maintained as a stack, so if called from
   nested find modules or config packages, root paths from the parent's find
   module or config package will be searched after paths from the current
   module or package.  In other words, the search order would be
   ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
   ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
   This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
   the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.

   * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|

2. Search paths specified in cmake-specific cache variables.
   These are intended to be used on the command line with a ``-DVAR=value``.
   The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
   This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
   :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``.

   * |CMAKE_PREFIX_PATH_XXX|
   * |CMAKE_XXX_PATH|
   * |CMAKE_XXX_MAC_PATH|

3. Search paths specified in cmake-specific environment variables.
   These are intended to be set in the user's shell configuration,
   and therefore use the host's native path separator
   (``;`` on Windows and ``:`` on UNIX).
   This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or
   by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``.

   * |ENV_CMAKE_PREFIX_PATH_XXX|
   * |ENV_CMAKE_XXX_PATH|
   * |ENV_CMAKE_XXX_MAC_PATH|

4. Search the paths specified by the ``HINTS`` option.
   These should be paths computed by system introspection, such as a
   hint provided by the location of another item already found.
   Hard-coded guesses should be specified with the ``PATHS`` option.

5. Search the standard system environment variables.
   This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by
   setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``.

   * |SYSTEM_ENVIRONMENT_PATH_XXX|

   |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|

6. Search cmake variables defined in the Platform files
   for the current system.  The searching of ``CMAKE_INSTALL_PREFIX`` and
   ``CMAKE_STAGING_PREFIX`` can be
   skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the
   :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE``. All these locations
   can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the
   :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``.

   * |CMAKE_SYSTEM_PREFIX_PATH_XXX|
   * |CMAKE_SYSTEM_XXX_PATH|
   * |CMAKE_SYSTEM_XXX_MAC_PATH|

   The platform paths that these variables contain are locations that
   typically include installed software. An example being ``/usr/local`` for
   UNIX based platforms.

7. Search the paths specified by the PATHS option
   or in the short-hand version of the command.
   These are typically hard-coded guesses.

The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
:variable:`CMAKE_SYSTEM_IGNORE_PATH` and
:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
of the above locations to be ignored.

.. versionadded:: 3.16
  Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable
  various search locations.

.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name

On macOS the :variable:`CMAKE_FIND_FRAMEWORK` and
:variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of
preference between Apple-style and unix-style package components.

.. include:: FIND_XXX_ROOT.txt
.. include:: FIND_XXX_ORDER.txt


code:
The default search order is designed to be most-specific to
least-specific for common use cases.
Projects may override the order by simply calling the command
multiple times and using the ``NO_*`` options:

.. parsed-literal::

   |FIND_XXX| (|FIND_ARGS_XXX| PATHS paths... NO_DEFAULT_PATH)
   |FIND_XXX| (|FIND_ARGS_XXX|)

Once one of the calls succeeds the result variable will be set
and stored in the cache so that no call will search again.


code:
Specify which registry views must be queried. This option is only meaningful
on ``Windows`` platforms and will be ignored on other ones. When not
specified, the |FIND_XXX_REGISTRY_VIEW_DEFAULT| view is used when the
:policy:`CMP0134` policy is ``NEW``. Refer to :policy:`CMP0134` for the
default view when the policy is ``OLD``.

``64``
  Query the 64-bit registry. On 32-bit Windows, it always returns the string
  ``/REGISTRY-NOTFOUND``.

``32``
  Query the 32-bit registry.

``64_32``
  Query both views (``64`` and ``32``) and generate a path for each.

``32_64``
  Query both views (``32`` and ``64``) and generate a path for each.

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

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

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

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

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

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


code:
The CMake variable :variable:`CMAKE_FIND_ROOT_PATH` specifies one or more
directories to be prepended to all other search directories.  This
effectively "re-roots" the entire search under given locations.
Paths which are descendants of the :variable:`CMAKE_STAGING_PREFIX` are excluded
from this re-rooting, because that variable is always a path on the host system.
By default the :variable:`CMAKE_FIND_ROOT_PATH` is empty.

The :variable:`CMAKE_SYSROOT` variable can also be used to specify exactly one
directory to use as a prefix.  Setting :variable:`CMAKE_SYSROOT` also has other
effects.  See the documentation for that variable for more.

These variables are especially useful when cross-compiling to
point to the root directory of the target environment and CMake will
search there too.  By default at first the directories listed in
:variable:`CMAKE_FIND_ROOT_PATH` are searched, then the :variable:`CMAKE_SYSROOT`
directory is searched, and then the non-rooted directories will be
searched.  The default behavior can be adjusted by setting
|CMAKE_FIND_ROOT_PATH_MODE_XXX|.  This behavior can be manually
overridden on a per-call basis using options:

``CMAKE_FIND_ROOT_PATH_BOTH``
  Search in the order described above.

``NO_CMAKE_FIND_ROOT_PATH``
  Do not use the :variable:`CMAKE_FIND_ROOT_PATH` variable.

``ONLY_CMAKE_FIND_ROOT_PATH``
  Search only the re-rooted directories and directories below
  :variable:`CMAKE_STAGING_PREFIX`.


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

Arguments to |command_name| may use generator expressions
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.  |more_see_also|


code:
Handling Compiler Driver Differences
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To pass options to the linker tool, each compiler driver has its own syntax.
The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable
way, options to pass to the linker tool. ``LINKER:`` is replaced by the
appropriate driver option and ``,`` by the appropriate driver separator.
The driver prefix and driver separator are given by the values of the
:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` and
:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variables.

For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for
``Clang`` and ``-Wl,-z,defs`` for ``GNU GCC``.

The ``LINKER:`` prefix can be specified as part of a ``SHELL:`` prefix
expression.

The ``LINKER:`` prefix supports, as an alternative syntax, specification of
arguments using the ``SHELL:`` prefix and space as separator. The previous
example then becomes ``"LINKER:SHELL:-z defs"``.

.. note::

  Specifying the ``SHELL:`` prefix anywhere other than at the beginning of the
  ``LINKER:`` prefix is not supported.


code:
Option De-duplication
^^^^^^^^^^^^^^^^^^^^^

The final set of options used for a target is constructed by
accumulating options from the current target and the usage requirements of
its dependencies.  The set of options is de-duplicated to avoid repetition.

.. versionadded:: 3.12
  While beneficial for individual options, the de-duplication step can break
  up option groups.  For example, ``-option A -option B`` becomes
  ``-option A B``.  One may specify a group of options using shell-like
  quoting along with a ``SHELL:`` prefix.  The ``SHELL:`` prefix is dropped,
  and the rest of the option string is parsed using the
  :command:`separate_arguments` ``UNIX_COMMAND`` mode. For example,
  ``"SHELL:-option A" "SHELL:-option B"`` becomes ``-option A -option B``.


code:
Supported languages are ``C``, ``CXX`` (i.e.  C++), ``CSharp`` (i.e.  C#), ``CUDA``,
``OBJC`` (i.e. Objective-C), ``OBJCXX`` (i.e. Objective-C++), ``Fortran``, ``HIP``,
``ISPC``, ``Swift``, ``ASM``, ``ASM_NASM``, ``ASM_MARMASM``, ``ASM_MASM``, and ``ASM-ATT``.

  .. versionadded:: 3.8
    Added ``CSharp`` and ``CUDA`` support.

  .. versionadded:: 3.15
    Added ``Swift`` support.

  .. versionadded:: 3.16
    Added ``OBJC`` and ``OBJCXX`` support.

  .. versionadded:: 3.18
    Added ``ISPC`` support.

  .. versionadded:: 3.21
    Added ``HIP`` support.

  .. versionadded:: 3.26
    Added ``ASM_MARMASM`` support.

If enabling ``ASM``, list it last so that CMake can check whether
compilers for other languages like ``C`` work for assembly too.


code:
.. note::

  When evaluating :ref:`Variable References` of the form ``${VAR}``, CMake
  first searches for a normal variable with that name.  If no such normal
  variable exists, CMake will then search for a cache entry with that name.
  Because of this, **unsetting a normal variable can expose a cache variable
  that was previously hidden**.  To force a variable reference of the form
  ``${VAR}`` to return an empty string, use ``set(<variable> "")``, which
  clears the normal variable but leaves it defined.


code:
add_compile_definitions
-----------------------

.. versionadded:: 3.12

Add preprocessor definitions to the compilation of source files.

.. code-block:: cmake

  add_compile_definitions(<definition> ...)

Adds preprocessor definitions to the compiler command line.

The preprocessor definitions are added to the :prop_dir:`COMPILE_DEFINITIONS`
directory property for the current ``CMakeLists`` file. They are also added to
the :prop_tgt:`COMPILE_DEFINITIONS` target property for each target in the
current ``CMakeLists`` file.

Definitions are specified using the syntax ``VAR`` or ``VAR=value``.
Function-style definitions are not supported. CMake will automatically
escape the value correctly for the native build system (note that CMake
language syntax may require escapes to specify some values).

.. versionadded:: 3.26
  Any leading ``-D`` on an item will be removed.

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

See Also
^^^^^^^^

* The command :command:`target_compile_definitions` adds target-specific definitions.


code:
add_compile_options
-------------------

Add options to the compilation of source files.

.. code-block:: cmake

  add_compile_options(<option> ...)

Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property.
These options are used when compiling targets from the current
directory and below.

.. note::

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

Arguments
^^^^^^^^^

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

.. include:: OPTIONS_SHELL.txt

Example
^^^^^^^

Since different compilers support different options, a typical use of
this command is in a compiler-specific conditional clause:

.. code-block:: cmake

  if (MSVC)
      # warning level 4
      add_compile_options(/W4)
  else()
      # additional warnings
      add_compile_options(-Wall -Wextra -Wpedantic)
  endif()

To set per-language options, use the :genex:`$<COMPILE_LANGUAGE>`
or :genex:`$<COMPILE_LANGUAGE:languages>` generator expressions.

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:`add_compile_definitions`
  and :command:`include_directories`.

* The command :command:`target_compile_options` adds target-specific options.

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

* The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
  source file.

* :command:`add_link_options` adds options for linking.

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


code:
add_custom_command
------------------

Add a custom build rule to the generated build system.

There are two main signatures for ``add_custom_command``.

Generating Files
^^^^^^^^^^^^^^^^

The first signature is for adding a custom command to produce an output:

.. code-block:: cmake

  add_custom_command(OUTPUT output1 [output2 ...]
                     COMMAND command1 [ARGS] [args1...]
                     [COMMAND command2 [ARGS] [args2...] ...]
                     [MAIN_DEPENDENCY depend]
                     [DEPENDS [depends...]]
                     [BYPRODUCTS [files...]]
                     [IMPLICIT_DEPENDS <lang1> depend1
                                      [<lang2> depend2] ...]
                     [WORKING_DIRECTORY dir]
                     [COMMENT comment]
                     [DEPFILE depfile]
                     [JOB_POOL job_pool]
                     [JOB_SERVER_AWARE <bool>]
                     [VERBATIM] [APPEND] [USES_TERMINAL]
                     [COMMAND_EXPAND_LISTS]
                     [DEPENDS_EXPLICIT_ONLY])

This defines a command to generate specified ``OUTPUT`` file(s).
A target created in the same directory (``CMakeLists.txt`` file)
that specifies any output of the custom command as a source file
is given a rule to generate the file using the command at build time.

Do not list the output in more than one independent target that
may build in parallel or the instances of the rule may conflict.
Instead, use the :command:`add_custom_target` command to drive the
command and make the other targets depend on that one.  See the
`Example: Generating Files for Multiple Targets`_ below.

The options are:

``APPEND``
  Append the ``COMMAND`` and ``DEPENDS`` option values to the custom
  command for the first output specified.  There must have already
  been a previous call to this command with the same output.

  If the previous call specified the output via a generator expression,
  the output specified by the current call must match in at least one
  configuration after evaluating generator expressions.  In this case,
  the appended commands and dependencies apply to all configurations.

  The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY``
  options are currently ignored when APPEND is given, but may be
  used in the future.

``BYPRODUCTS``
  .. versionadded:: 3.2

  Specify the files the command is expected to produce but whose
  modification time may or may not be newer than the dependencies.
  If a byproduct name is a relative path it will be interpreted
  relative to the build tree directory corresponding to the
  current source directory.
  Each byproduct file will be marked with the :prop_sf:`GENERATED`
  source file property automatically.

  *See policy* :policy:`CMP0058` *for the motivation behind this feature.*

  Explicit specification of byproducts is supported by the
  :generator:`Ninja` generator to tell the ``ninja`` build tool
  how to regenerate byproducts when they are missing.  It is
  also useful when other build rules (e.g. custom commands)
  depend on the byproducts.  Ninja requires a build rule for any
  generated file on which another rule depends even if there are
  order-only dependencies to ensure the byproducts will be
  available before their dependents build.

  The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
  :prop_sf:`GENERATED` files during ``make clean``.

  .. versionadded:: 3.20
    Arguments to ``BYPRODUCTS`` may use a restricted set of
    :manual:`generator expressions <cmake-generator-expressions(7)>`.
    :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
    permitted.

  .. versionchanged:: 3.28
    In targets using :ref:`file sets`, custom command byproducts are now
    considered private unless they are listed in a non-private file set.
    See policy :policy:`CMP0154`.

``COMMAND``
  Specify the command-line(s) to execute at build time.
  If more than one ``COMMAND`` is specified they will be executed in order,
  but *not* necessarily composed into a stateful shell or batch script.
  (To run a full script, use the :command:`configure_file` command or the
  :command:`file(GENERATE)` command to create it, and then specify
  a ``COMMAND`` to launch it.)
  The optional ``ARGS`` argument is for backward compatibility and
  will be ignored.

  If ``COMMAND`` specifies an executable target name (created by the
  :command:`add_executable` command), it will automatically be replaced
  by the location of the executable created at build time if either of
  the following is true:

  * The target is not being cross-compiled (i.e. the
    :variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
  * .. versionadded:: 3.6
      The target is being cross-compiled and an emulator is provided (i.e.
      its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
      In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
      prepended to the command before the location of the target executable.

  If neither of the above conditions are met, it is assumed that the
  command name is a program to be found on the ``PATH`` at build time.

  Arguments to ``COMMAND`` may use
  :manual:`generator expressions <cmake-generator-expressions(7)>`.
  Use the :genex:`TARGET_FILE` generator expression to refer to the location
  of a target later in the command line (i.e. as a command argument rather
  than as the command to execute).

  Whenever one of the following target based generator expressions are used as
  a command to execute or is mentioned in a command argument, a target-level
  dependency will be added automatically so that the mentioned target will be
  built before any target using this custom command
  (see policy :policy:`CMP0112`).

    * ``TARGET_FILE``
    * ``TARGET_LINKER_FILE``
    * ``TARGET_SONAME_FILE``
    * ``TARGET_PDB_FILE``

  This target-level dependency does NOT add a file-level dependency that would
  cause the custom command to re-run whenever the executable is recompiled.
  List target names with the ``DEPENDS`` option to add such file-level
  dependencies.

``COMMENT``
  Display the given message before the commands are executed at
  build time.

  .. versionadded:: 3.26
    Arguments to ``COMMENT`` may use
    :manual:`generator expressions <cmake-generator-expressions(7)>`.

``DEPENDS``
  Specify files on which the command depends.  Each argument is converted
  to a dependency as follows:

  1. If the argument is the name of a target (created by the
     :command:`add_custom_target`, :command:`add_executable`, or
     :command:`add_library` command) a target-level dependency is
     created to make sure the target is built before any target
     using this custom command.  Additionally, if the target is an
     executable or library, a file-level dependency is created to
     cause the custom command to re-run whenever the target is
     recompiled.

  2. If the argument is an absolute path, a file-level dependency
     is created on that path.

  3. If the argument is the name of a source file that has been
     added to a target or on which a source file property has been set,
     a file-level dependency is created on that source file.

  4. If the argument is a relative path and it exists in the current
     source directory, a file-level dependency is created on that
     file in the current source directory.

  5. Otherwise, a file-level dependency is created on that path relative
     to the current binary directory.

  If any dependency is an ``OUTPUT`` of another custom command in the same
  directory (``CMakeLists.txt`` file), CMake automatically brings the other
  custom command into the target in which this command is built.

  .. versionadded:: 3.16
    A target-level dependency is added if any dependency is listed as
    ``BYPRODUCTS`` of a target or any of its build events in the same
    directory to ensure the byproducts will be available.

  If ``DEPENDS`` is not specified, the command will run whenever
  the ``OUTPUT`` is missing; if the command does not actually
  create the ``OUTPUT``, the rule will always run.

  .. versionadded:: 3.1
    Arguments to ``DEPENDS`` may use
    :manual:`generator expressions <cmake-generator-expressions(7)>`.

``COMMAND_EXPAND_LISTS``
  .. versionadded:: 3.8

  Lists in ``COMMAND`` arguments will be expanded, including those
  created with
  :manual:`generator expressions <cmake-generator-expressions(7)>`,
  allowing ``COMMAND`` arguments such as
  ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
  to be properly expanded.

``IMPLICIT_DEPENDS``
  Request scanning of implicit dependencies of an input file.
  The language given specifies the programming language whose
  corresponding dependency scanner should be used.
  Currently only ``C`` and ``CXX`` language scanners are supported.
  The language has to be specified for every file in the
  ``IMPLICIT_DEPENDS`` list.  Dependencies discovered from the
  scanning are added to those of the custom command at build time.
  Note that the ``IMPLICIT_DEPENDS`` option is currently supported
  only for Makefile generators and will be ignored by other generators.

  .. note::

    This option cannot be specified at the same time as ``DEPFILE`` option.

``JOB_POOL``
  .. versionadded:: 3.15

  Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
  generator. Incompatible with ``USES_TERMINAL``, which implies
  the ``console`` pool.
  Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
  an error by ninja at build time.

``JOB_SERVER_AWARE``
  .. versionadded:: 3.28

  Specify that the command is GNU Make job server aware.

  For the :generator:`Unix Makefiles`, :generator:`MSYS Makefiles`, and
  :generator:`MinGW Makefiles` generators this will add the ``+`` prefix to the
  recipe line. See the `GNU Make Documentation`_ for more information.

  This option is silently ignored by other generators.

.. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html

``MAIN_DEPENDENCY``
  Specify the primary input source file to the command.  This is
  treated just like any value given to the ``DEPENDS`` option
  but also suggests to Visual Studio generators where to hang
  the custom command. Each source file may have at most one command
  specifying it as its main dependency. A compile command (i.e. for a
  library or an executable) counts as an implicit main dependency which
  gets silently overwritten by a custom command specification.

``OUTPUT``
  Specify the output files the command is expected to produce.
  Each output file will be marked with the :prop_sf:`GENERATED`
  source file property automatically.
  If the output of the custom command is not actually created
  as a file on disk it should be marked with the :prop_sf:`SYMBOLIC`
  source file property.

  If an output file name is a relative path, its absolute path is
  determined by interpreting it relative to:

  1. the build directory corresponding to the current source directory
     (:variable:`CMAKE_CURRENT_BINARY_DIR`), or

  2. the current source directory (:variable:`CMAKE_CURRENT_SOURCE_DIR`).

  The path in the build directory is preferred unless the path in the
  source tree is mentioned as an absolute source file path elsewhere
  in the current directory.

  .. versionadded:: 3.20
    Arguments to ``OUTPUT`` may use a restricted set of
    :manual:`generator expressions <cmake-generator-expressions(7)>`.
    :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
    permitted.

  .. versionchanged:: 3.28
    In targets using :ref:`file sets`, custom command outputs are now
    considered private unless they are listed in a non-private file set.
    See policy :policy:`CMP0154`.

``USES_TERMINAL``
  .. versionadded:: 3.2

  The command will be given direct access to the terminal if possible.
  With the :generator:`Ninja` generator, this places the command in
  the ``console`` :prop_gbl:`pool <JOB_POOLS>`.

``VERBATIM``
  All arguments to the commands will be escaped properly for the
  build tool so that the invoked command receives each argument
  unchanged.  Note that one level of escapes is still used by the
  CMake language processor before add_custom_command even sees the
  arguments.  Use of ``VERBATIM`` is recommended as it enables
  correct behavior.  When ``VERBATIM`` is not given the behavior
  is platform specific because there is no protection of
  tool-specific special characters.

``WORKING_DIRECTORY``
  Execute the command with the given current working directory.
  If it is a relative path it will be interpreted relative to the
  build tree directory corresponding to the current source directory.

  .. versionadded:: 3.13
    Arguments to ``WORKING_DIRECTORY`` may use
    :manual:`generator expressions <cmake-generator-expressions(7)>`.

``DEPFILE``
  .. versionadded:: 3.7

  Specify a depfile which holds dependencies for the custom command. It is
  usually emitted by the custom command itself.  This keyword may only be used
  if the generator supports it, as detailed below.

  The expected format, compatible with what is generated by ``gcc`` with the
  option ``-M``, is independent of the generator or platform.

  The formal syntax, as specified using
  `BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with
  the regular extensions, is the following:

  .. raw:: latex

    \begin{small}

  .. productionlist:: depfile
    depfile: `rule`*
    rule: `targets` (':' (`separator` `dependencies`?)?)? `eol`
    targets: `target` (`separator` `target`)* `separator`*
    target: `pathname`
    dependencies: `dependency` (`separator` `dependency`)* `separator`*
    dependency: `pathname`
    separator: (`space` | `line_continue`)+
    line_continue: '\' `eol`
    space: ' ' | '\t'
    pathname: `character`+
    character: `std_character` | `dollar` | `hash` | `whitespace`
    std_character: <any character except '$', '#' or ' '>
    dollar: '$$'
    hash: '\#'
    whitespace: '\ '
    eol: '\r'? '\n'

  .. raw:: latex

    \end{small}

  .. note::

    As part of ``pathname``, any slash and backslash is interpreted as
    a directory separator.

  .. versionadded:: 3.7
    The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword
    was first added.

  .. versionadded:: 3.17
    Added the :generator:`Ninja Multi-Config` generator, which included
    support for the ``DEPFILE`` keyword.

  .. versionadded:: 3.20
    Added support for :ref:`Makefile Generators`.

    .. note::

      ``DEPFILE`` cannot be specified at the same time as the
      ``IMPLICIT_DEPENDS`` option for :ref:`Makefile Generators`.

  .. versionadded:: 3.21
    Added support for :ref:`Visual Studio Generators` with VS 2012 and above,
    and for the :generator:`Xcode` generator.  Support for
    :manual:`generator expressions <cmake-generator-expressions(7)>` was also
    added.

  .. versionadded:: 3.29
    The :ref:`Ninja Generators` will now incorporate the dependencies into its
    "deps log" database if the file is not listed in ``OUTPUTS`` or
    ``BYPRODUCTS``.

  Using ``DEPFILE`` with generators other than those listed above is an error.

  If the ``DEPFILE`` argument is relative, it should be relative to
  :variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the
  ``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR`.
  See policy :policy:`CMP0116`, which is always ``NEW`` for
  :ref:`Makefile Generators`, :ref:`Visual Studio Generators`,
  and the :generator:`Xcode` generator.

``DEPENDS_EXPLICIT_ONLY``

  .. versionadded:: 3.27

  Indicates that the command's ``DEPENDS`` argument represents all files
  required by the command and implicit dependencies are not required.

  Without this option, if any target uses the output of the custom command,
  CMake will consider that target's dependencies as implicit dependencies for
  the custom command in case this custom command requires files implicitly
  created by those targets.

  This option can be enabled on all custom commands by setting
  :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to ``ON``.

  Only the :ref:`Ninja Generators` actually use this information to remove
  unnecessary implicit dependencies.

  See also the :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property, which may
  provide another way for reducing the impact of target dependencies in some
  scenarios.

Examples: Generating Files
^^^^^^^^^^^^^^^^^^^^^^^^^^

Custom commands may be used to generate source files.
For example, the code:

.. code-block:: cmake

  add_custom_command(
    OUTPUT out.c
    COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
                     -o out.c
    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
    VERBATIM)
  add_library(myLib out.c)

adds a custom command to run ``someTool`` to generate ``out.c`` and then
compile the generated source as part of a library.  The generation rule
will re-run whenever ``in.txt`` changes.

.. versionadded:: 3.20
  One may use generator expressions to specify per-configuration outputs.
  For example, the code:

  .. code-block:: cmake

    add_custom_command(
      OUTPUT "out-$<CONFIG>.c"
      COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
                       -o "out-$<CONFIG>.c"
                       -c "$<CONFIG>"
      DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
      VERBATIM)
    add_library(myLib "out-$<CONFIG>.c")

  adds a custom command to run ``someTool`` to generate ``out-<config>.c``,
  where ``<config>`` is the build configuration, and then compile the generated
  source as part of a library.

Example: Generating Files for Multiple Targets
""""""""""""""""""""""""""""""""""""""""""""""

If multiple independent targets need the same custom command output,
it must be attached to a single custom target on which they all depend.
Consider the following example:

.. code-block:: cmake

  add_custom_command(
    OUTPUT table.csv
    COMMAND makeTable -i ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
                      -o table.csv
    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
    VERBATIM)
  add_custom_target(generate_table_csv DEPENDS table.csv)

  add_custom_command(
    OUTPUT foo.cxx
    COMMAND genFromTable -i table.csv -case foo -o foo.cxx
    DEPENDS table.csv           # file-level dependency
            generate_table_csv  # target-level dependency
    VERBATIM)
  add_library(foo foo.cxx)

  add_custom_command(
    OUTPUT bar.cxx
    COMMAND genFromTable -i table.csv -case bar -o bar.cxx
    DEPENDS table.csv           # file-level dependency
            generate_table_csv  # target-level dependency
    VERBATIM)
  add_library(bar bar.cxx)

Output ``foo.cxx`` is needed only by target ``foo`` and output ``bar.cxx``
is needed only by target ``bar``, but *both* targets need ``table.csv``,
transitively.  Since ``foo`` and ``bar`` are independent targets that may
build concurrently, we prevent them from racing to generate ``table.csv``
by placing its custom command in a separate target, ``generate_table_csv``.
The custom commands generating ``foo.cxx`` and ``bar.cxx`` each specify a
target-level dependency on ``generate_table_csv``, so the targets using them,
``foo`` and ``bar``, will not build until after target ``generate_table_csv``
is built.

.. _`add_custom_command(TARGET)`:

Build Events
^^^^^^^^^^^^

The second signature adds a custom command to a target such as a
library or executable.  This is useful for performing an operation
before or after building the target.  The command becomes part of the
target and will only execute when the target itself is built.  If the
target is already built, the command will not execute.

.. code-block:: cmake

  add_custom_command(TARGET <target>
                     PRE_BUILD | PRE_LINK | POST_BUILD
                     COMMAND command1 [ARGS] [args1...]
                     [COMMAND command2 [ARGS] [args2...] ...]
                     [BYPRODUCTS [files...]]
                     [WORKING_DIRECTORY dir]
                     [COMMENT comment]
                     [VERBATIM]
                     [COMMAND_EXPAND_LISTS])

This defines a new command that will be associated with building the
specified ``<target>``.  The ``<target>`` must be defined in the current
directory; targets defined in other directories may not be specified.

When the command will happen is determined by which
of the following is specified:

``PRE_BUILD``
  This option has unique behavior for the :ref:`Visual Studio Generators`.
  When using one of the Visual Studio generators, the command will run before
  any other rules are executed within the target.  With all other generators,
  this option behaves the same as ``PRE_LINK`` instead.  Because of this,
  it is recommended to avoid using ``PRE_BUILD`` except when it is known that
  a Visual Studio generator is being used.
``PRE_LINK``
  Run after sources have been compiled but before linking the binary
  or running the librarian or archiver tool of a static library.
  This is not defined for targets created by the
  :command:`add_custom_target` command.
``POST_BUILD``
  Run after all other rules within the target have been executed.

Projects should always specify one of the above three keywords when using
the ``TARGET`` form.  For backward compatibility reasons, ``POST_BUILD`` is
assumed if no such keyword is given, but projects should explicitly provide
one of the keywords to make clear the behavior they expect.

.. note::
  Because generator expressions can be used in custom commands,
  it is possible to define ``COMMAND`` lines or whole custom commands
  which evaluate to empty strings for certain configurations.
  For **Visual Studio 12 2013 (and newer)** generators these command
  lines or custom commands will be omitted for the specific
  configuration and no "empty-string-command" will be added.

  This allows adding individual build events for every configuration.

.. versionadded:: 3.21
  Support for target-dependent generator expressions.

.. versionadded:: 3.29
  The ``<target>`` may be an :ref:`ALIAS target <Alias Targets>`.

Examples: Build Events
^^^^^^^^^^^^^^^^^^^^^^

A ``POST_BUILD`` event may be used to post-process a binary after linking.
For example, the code:

.. code-block:: cmake

  add_executable(myExe myExe.c)
  add_custom_command(
    TARGET myExe POST_BUILD
    COMMAND someHasher -i "$<TARGET_FILE:myExe>"
                       -o "$<TARGET_FILE:myExe>.hash"
    VERBATIM)

will run ``someHasher`` to produce a ``.hash`` file next to the executable
after linking.

.. versionadded:: 3.20
  One may use generator expressions to specify per-configuration byproducts.
  For example, the code:

  .. code-block:: cmake

    add_library(myPlugin MODULE myPlugin.c)
    add_custom_command(
      TARGET myPlugin POST_BUILD
      COMMAND someHasher -i "$<TARGET_FILE:myPlugin>"
                         --as-code "myPlugin-hash-$<CONFIG>.c"
      BYPRODUCTS "myPlugin-hash-$<CONFIG>.c"
      VERBATIM)
    add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c")

  will run ``someHasher`` after linking ``myPlugin``, e.g. to produce a ``.c``
  file containing code to check the hash of ``myPlugin`` that the ``myExe``
  executable can use to verify it before loading.

Ninja Multi-Config
^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.20

  ``add_custom_command`` supports the :generator:`Ninja Multi-Config`
  generator's cross-config capabilities. See the generator documentation
  for more information.

See Also
^^^^^^^^

* :command:`add_custom_target`


code:
add_custom_target
-----------------

Add a target with no output so it will always be built.

.. code-block:: cmake

  add_custom_target(Name [ALL] [command1 [args1...]]
                    [COMMAND command2 [args2...] ...]
                    [DEPENDS depend depend depend ... ]
                    [BYPRODUCTS [files...]]
                    [WORKING_DIRECTORY dir]
                    [COMMENT comment]
                    [JOB_POOL job_pool]
                    [JOB_SERVER_AWARE <bool>]
                    [VERBATIM] [USES_TERMINAL]
                    [COMMAND_EXPAND_LISTS]
                    [SOURCES src1 [src2...]])

Adds a target with the given name that executes the given commands.
The target has no output file and is *always considered out of date*
even if the commands try to create a file with the name of the target.
Use the :command:`add_custom_command` command to generate a file with
dependencies.  By default nothing depends on the custom target.  Use
the :command:`add_dependencies` command to add dependencies to or
from other targets.

The options are:

``ALL``
  Indicate that this target should be added to the default build
  target so that it will be run every time (the command cannot be
  called ``ALL``).

``BYPRODUCTS``
  .. versionadded:: 3.2

  Specify the files the command is expected to produce but whose
  modification time may or may not be updated on subsequent builds.
  If a byproduct name is a relative path it will be interpreted
  relative to the build tree directory corresponding to the
  current source directory.
  Each byproduct file will be marked with the :prop_sf:`GENERATED`
  source file property automatically.

  *See policy* :policy:`CMP0058` *for the motivation behind this feature.*

  Explicit specification of byproducts is supported by the
  :generator:`Ninja` generator to tell the ``ninja`` build tool
  how to regenerate byproducts when they are missing.  It is
  also useful when other build rules (e.g. custom commands)
  depend on the byproducts.  Ninja requires a build rule for any
  generated file on which another rule depends even if there are
  order-only dependencies to ensure the byproducts will be
  available before their dependents build.

  The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
  :prop_sf:`GENERATED` files during ``make clean``.

  .. versionadded:: 3.20
    Arguments to ``BYPRODUCTS`` may use a restricted set of
    :manual:`generator expressions <cmake-generator-expressions(7)>`.
    :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
    permitted.

  .. versionchanged:: 3.28
    In custom targets using :ref:`file sets`, byproducts are now
    considered private unless they are listed in a non-private file set.
    See policy :policy:`CMP0154`.

``COMMAND``
  Specify the command-line(s) to execute at build time.
  If more than one ``COMMAND`` is specified they will be executed in order,
  but *not* necessarily composed into a stateful shell or batch script.
  (To run a full script, use the :command:`configure_file` command or the
  :command:`file(GENERATE)` command to create it, and then specify
  a ``COMMAND`` to launch it.)

  If ``COMMAND`` specifies an executable target name (created by the
  :command:`add_executable` command), it will automatically be replaced
  by the location of the executable created at build time if either of
  the following is true:

  * The target is not being cross-compiled (i.e. the
    :variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
  * .. versionadded:: 3.6
      The target is being cross-compiled and an emulator is provided (i.e.
      its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
      In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
      prepended to the command before the location of the target executable.

  If neither of the above conditions are met, it is assumed that the
  command name is a program to be found on the ``PATH`` at build time.

  Arguments to ``COMMAND`` may use
  :manual:`generator expressions <cmake-generator-expressions(7)>`.
  Use the :genex:`TARGET_FILE` generator expression to refer to the location
  of a target later in the command line (i.e. as a command argument rather
  than as the command to execute).

  Whenever one of the following target based generator expressions are used as
  a command to execute or is mentioned in a command argument, a target-level
  dependency will be added automatically so that the mentioned target will be
  built before this custom target (see policy :policy:`CMP0112`).

    * ``TARGET_FILE``
    * ``TARGET_LINKER_FILE``
    * ``TARGET_SONAME_FILE``
    * ``TARGET_PDB_FILE``

  The command and arguments are optional and if not specified an empty
  target will be created.

``COMMENT``
  Display the given message before the commands are executed at
  build time.

  .. versionadded:: 3.26
    Arguments to ``COMMENT`` may use
    :manual:`generator expressions <cmake-generator-expressions(7)>`.

``DEPENDS``
  Reference files and outputs of custom commands created with
  :command:`add_custom_command` command calls in the same directory
  (``CMakeLists.txt`` file).  They will be brought up to date when
  the target is built.

  .. versionchanged:: 3.16
    A target-level dependency is added if any dependency is a byproduct
    of a target or any of its build events in the same directory to ensure
    the byproducts will be available before this target is built.

  Use the :command:`add_dependencies` command to add dependencies
  on other targets.

``COMMAND_EXPAND_LISTS``
  .. versionadded:: 3.8

  Lists in ``COMMAND`` arguments will be expanded, including those
  created with
  :manual:`generator expressions <cmake-generator-expressions(7)>`,
  allowing ``COMMAND`` arguments such as
  ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
  to be properly expanded.

``JOB_POOL``
  .. versionadded:: 3.15

  Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
  generator. Incompatible with ``USES_TERMINAL``, which implies
  the ``console`` pool.
  Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
  an error by ninja at build time.

``JOB_SERVER_AWARE``
  .. versionadded:: 3.28

  Specify that the command is GNU Make job server aware.

  For the :generator:`Unix Makefiles`, :generator:`MSYS Makefiles`, and
  :generator:`MinGW Makefiles` generators this will add the ``+`` prefix to the
  recipe line. See the `GNU Make Documentation`_ for more information.

  This option is silently ignored by other generators.

.. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html

``SOURCES``
  Specify additional source files to be included in the custom target.
  Specified source files will be added to IDE project files for
  convenience in editing even if they have no build rules.

``VERBATIM``
  All arguments to the commands will be escaped properly for the
  build tool so that the invoked command receives each argument
  unchanged.  Note that one level of escapes is still used by the
  CMake language processor before ``add_custom_target`` even sees
  the arguments.  Use of ``VERBATIM`` is recommended as it enables
  correct behavior.  When ``VERBATIM`` is not given the behavior
  is platform specific because there is no protection of
  tool-specific special characters.

``USES_TERMINAL``
  .. versionadded:: 3.2

  The command will be given direct access to the terminal if possible.
  With the :generator:`Ninja` generator, this places the command in
  the ``console`` :prop_gbl:`pool <JOB_POOLS>`.

``WORKING_DIRECTORY``
  Execute the command with the given current working directory.
  If it is a relative path it will be interpreted relative to the
  build tree directory corresponding to the current source directory.

  .. versionadded:: 3.13
    Arguments to ``WORKING_DIRECTORY`` may use
    :manual:`generator expressions <cmake-generator-expressions(7)>`.

Ninja Multi-Config
^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.20

  ``add_custom_target`` supports the :generator:`Ninja Multi-Config`
  generator's cross-config capabilities. See the generator documentation
  for more information.

See Also
^^^^^^^^

* :command:`add_custom_command`


code:
add_definitions
---------------

Add ``-D`` define flags to the compilation of source files.

.. code-block:: cmake

  add_definitions(-DFOO -DBAR ...)

Adds definitions to the compiler command line for targets in the current
directory, whether added before or after this command is invoked, and for
the ones in sub-directories added after. This command can be used to add any
flags, but it is intended to add preprocessor definitions.

.. note::

  This command has been superseded by alternatives:

  * Use :command:`add_compile_definitions` to add preprocessor definitions.
  * Use :command:`include_directories` to add include directories.
  * Use :command:`add_compile_options` to add other options.

Flags beginning in ``-D`` or ``/D`` that look like preprocessor definitions are
automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory
property for the current directory.  Definitions with non-trivial values
may be left in the set of flags instead of being converted for reasons of
backwards compatibility.  See documentation of the
:prop_dir:`directory <COMPILE_DEFINITIONS>`,
:prop_tgt:`target <COMPILE_DEFINITIONS>`,
:prop_sf:`source file <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS``
properties for details on adding preprocessor definitions to specific
scopes and configurations.

See Also
^^^^^^^^

* The :manual:`cmake-buildsystem(7)` manual for more on defining
  buildsystem properties.


code:
add_dependencies
----------------

Add a dependency between top-level targets.

.. code-block:: cmake

  add_dependencies(<target> [<target-dependency>]...)

Makes a top-level ``<target>`` depend on other top-level targets to
ensure that they build before ``<target>`` does.  A top-level target
is one created by one of the :command:`add_executable`,
:command:`add_library`, or :command:`add_custom_target` commands
(but not targets generated by CMake like ``install``).

Dependencies added to an :ref:`imported target <Imported Targets>`
or an :ref:`interface library <Interface Libraries>` are followed
transitively in its place since the target itself does not build.

.. versionadded:: 3.3
  Allow adding dependencies to interface libraries.

See Also
^^^^^^^^

* The ``DEPENDS`` option of :command:`add_custom_target` and
  :command:`add_custom_command` commands for adding file-level
  dependencies in custom rules.

* The :prop_sf:`OBJECT_DEPENDS` source file property to add
  file-level dependencies to object files.


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

.. only:: html

  .. contents::

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

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

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

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

  The options are:

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

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

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

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

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

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

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

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

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

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

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

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

  The options are:

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

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

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

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

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

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

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

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

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

See Also
^^^^^^^^

* :command:`add_library`


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

.. only:: html

   .. contents::

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

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

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

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

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

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

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

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

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

  The options are:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

.. code-block:: cmake

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

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

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

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

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

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

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

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

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

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

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

  .. versionadded:: 3.19

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

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

  The options are:

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

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

.. _`add_library imported libraries`:

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

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

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

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

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

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

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

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

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

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

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

  The options are:

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

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

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

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

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

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

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

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

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

See Also
^^^^^^^^

* :command:`add_executable`


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

.. versionadded:: 3.13

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

.. code-block:: cmake

  add_link_options(<option> ...)

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

.. note::

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

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

.. include:: DEVICE_LINK_OPTIONS.txt

.. include:: OPTIONS_SHELL.txt

.. include:: LINK_OPTIONS_LINKER.txt

See Also
^^^^^^^^

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

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


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

Add a subdirectory to the build.

.. code-block:: cmake

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

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

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

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


code:
add_test
--------

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

.. code-block:: cmake

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

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

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

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

``add_test`` options are:

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

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

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

  * .. versionadded:: 3.3

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

        <emulator> <command>

      .. versionchanged:: 3.29

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

  * .. versionadded:: 3.29

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

        <launcher> <command>

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

        <launcher> <emulator> <command>

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

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

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

``COMMAND_EXPAND_LISTS``
  .. versionadded:: 3.16

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

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

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

Example usage:

.. code-block:: cmake

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

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

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

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

.. code-block:: cmake

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

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

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


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

Find all source files in a directory.

.. code-block:: cmake

  aux_source_directory(<dir> <variable>)

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

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


code:
block
-----

.. versionadded:: 3.25

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

.. code-block:: cmake

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

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

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

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

  ``VARIABLES``
    Create a new variable scope.

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

  .. code-block:: cmake

    block(SCOPE_FOR VARIABLES POLICIES)

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

  .. code-block:: cmake

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

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

    # Now var1 holds VALUE1, and var2 is unset

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

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

.. code-block:: cmake

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

See Also
^^^^^^^^

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


code:
break
-----

Break from an enclosing foreach or while loop.

.. code-block:: cmake

  break()

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

See also the :command:`continue` command.


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

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

.. code-block:: cmake

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

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

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

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

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

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

.. code-block:: cmake

  build_command(<cachevariable> <makecommand>)

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

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

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