Public-Mirror/gbe_fork
1
0
Fork 0
mirror of https://github.com/Detanup01/gbe_fork.git synced 2024-12-27 10:54:15 +08:00
Code Issues 1 Projects Releases Wiki Activity

add files

Browse Source
This commit is contained in:
ota 2023-12-16 20:31:59 +02:00
commit b523ab22a1
3274 changed files with 225381 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
cmake-3.27.7-linux-x86_64/bin/cmake Normal file
View File

Binary file not shown.

44
cmake-3.27.7-linux-x86_64/share/aclocal/cmake.m4 Normal file
View File

@ -0,0 +1,44 @@
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
])

12
cmake-3.27.7-linux-x86_64/share/applications/cmake-gui.desktop Normal file
View File

@ -0,0 +1,12 @@
[Desktop Entry]
Version=1.0
Name=CMake
Comment=Cross-platform buildsystem
Exec=cmake-gui %f
Icon=CMakeSetup
Terminal=false
X-MultipleArgs=false
Type=Application
Categories=Development;Building;
StartupNotify=true
MimeType=application/x-cmakecache;

202
cmake-3.27.7-linux-x86_64/share/bash-completion/completions/cmake Normal file
View File

@ -0,0 +1,202 @@
# 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

88
cmake-3.27.7-linux-x86_64/share/bash-completion/completions/cpack Normal file
View File

@ -0,0 +1,88 @@
# 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

129
cmake-3.27.7-linux-x86_64/share/bash-completion/completions/ctest Normal file
View File

@ -0,0 +1,129 @@
# 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

15
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/DEPRECATED_POLICY_VERSIONS.txt Normal file
View File

@ -0,0 +1,15 @@
.. 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.

12
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/DEVICE_LINK_OPTIONS.txt Normal file
View File

@ -0,0 +1,12 @@
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.

252
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/FIND_XXX.txt Normal file
View File

@ -0,0 +1,252 @@
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

12
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/FIND_XXX_ORDER.txt Normal file
View File

@ -0,0 +1,12 @@
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.

41
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/FIND_XXX_REGISTRY_VIEW.txt Normal file
View File

@ -0,0 +1,41 @@
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``

29
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/FIND_XXX_ROOT.txt Normal file
View File

@ -0,0 +1,29 @@
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`.

6
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/GENEX_NOTE.txt Normal file
View File

@ -0,0 +1,6 @@
.. |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|

25
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/LINK_OPTIONS_LINKER.txt Normal file
View File

@ -0,0 +1,25 @@
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.

15
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/OPTIONS_SHELL.txt Normal file
View File

@ -0,0 +1,15 @@
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``.

25
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/SUPPORTED_LANGUAGES.txt Normal file
View File

@ -0,0 +1,25 @@
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.

9
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/UNSET_NOTE.txt Normal file
View File

@ -0,0 +1,9 @@
.. 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.

33
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/add_compile_definitions.rst Normal file
View File

@ -0,0 +1,33 @@
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.

67
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/add_compile_options.rst Normal file
View File

@ -0,0 +1,67 @@
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.

577
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/add_custom_command.rst Normal file
View File

@ -0,0 +1,577 @@
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]
[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.
``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.
``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.
``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.
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 11 2012 (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 to add individual build events for every configuration.
.. versionadded:: 3.21
Support for target-dependent generator expressions.
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`

192
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/add_custom_target.rst Normal file
View File

@ -0,0 +1,192 @@
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]
[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.
``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.
``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`

38
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/add_definitions.rst Normal file
View File

@ -0,0 +1,38 @@
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.

31
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/add_dependencies.rst Normal file
View File

@ -0,0 +1,31 @@
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.

114
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/add_executable.rst Normal file
View File

@ -0,0 +1,114 @@
add_executable
--------------
.. only:: html
.. contents::
Add an executable to the project using the specified source files.
Normal Executables
^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_executable(<name> [WIN32] [MACOSX_BUNDLE]
[EXCLUDE_FROM_ALL]
[source1] [source2 ...])
Adds an executable target called ``<name>`` to be built from the source
files listed in the command invocation. 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.
If ``WIN32`` is given the property :prop_tgt:`WIN32_EXECUTABLE` will be
set on the target created. See documentation of that target property for
details.
If ``MACOSX_BUNDLE`` is given the corresponding property will be set on
the created target. See documentation of the :prop_tgt:`MACOSX_BUNDLE`
target property for details.
If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
target property for details.
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
^^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_executable(<name> IMPORTED [GLOBAL])
An :ref:`IMPORTED executable target <Imported Targets>` references an
executable file located outside the project. No rules are generated to
build it, and the :prop_tgt:`IMPORTED` target property is ``True``. The
target name has scope in the directory in which it is created and below, but
the ``GLOBAL`` option extends visibility. It may be referenced like any
target built within the project. ``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
^^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_executable(<name> ALIAS <target>)
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`

268
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/add_library.rst Normal file
View File

@ -0,0 +1,268 @@
add_library
-----------
.. only:: html
.. contents::
Add a library to the project using the specified source files.
Normal Libraries
^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_library(<name> [STATIC | SHARED | MODULE]
[EXCLUDE_FROM_ALL]
[<source>...])
Adds a library target called ``<name>`` to be built from the source files
listed in the command invocation. 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`.
``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of
library to be created. ``STATIC`` libraries are archives of object files
for use when linking other targets. ``SHARED`` libraries are linked
dynamically and loaded at runtime. ``MODULE`` libraries are plugins that
are not linked into other targets but may be loaded dynamically at runtime
using dlopen-like functionality. If no type is given explicitly the
type is ``STATIC`` or ``SHARED`` based on whether the current value of the
variable :variable:`BUILD_SHARED_LIBS` is ``ON``. 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.
If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
target property for details.
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
^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_library(<name> OBJECT [<source>...])
Creates an :ref:`Object Library <Object Libraries>`. An object library
compiles source files but does not archive or link their object files into a
library. Instead 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
^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_library(<name> INTERFACE)
Creates an :ref:`Interface Library <Interface Libraries>`.
An ``INTERFACE`` library target does not compile sources and does
not produce a library artifact on disk. 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.
An interface library created with the above signature has no source files
itself and is not included as a target in the generated buildsystem.
.. 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.
.. versionadded:: 3.19
An interface library target may be created with source files:
.. code-block:: cmake
add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
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.
.. 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
^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_library(<name> <type> IMPORTED [GLOBAL])
Creates an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
No rules are generated to build it, and the :prop_tgt:`IMPORTED` target
property is ``True``. The target name has scope in the directory in which
it is created and below, but the ``GLOBAL`` option extends visibility.
It may be referenced like any target built within the project.
``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_``.
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.
See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
for more information.
Alias Libraries
^^^^^^^^^^^^^^^
.. code-block:: cmake
add_library(<name> ALIAS <target>)
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`

44
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/add_link_options.rst Normal file
View File

@ -0,0 +1,44 @@
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.

41
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/add_subdirectory.rst Normal file
View File

@ -0,0 +1,41 @@
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.

89
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/add_test.rst Normal file
View File

@ -0,0 +1,89 @@
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.
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.

24
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/aux_source_directory.rst Normal file
View File

@ -0,0 +1,24 @@
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.

76
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/block.rst Normal file
View File

@ -0,0 +1,76 @@
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)`.
``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`

12
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/break.rst Normal file
View File

@ -0,0 +1,12 @@
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.

51
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/build_command.rst Normal file
View File

@ -0,0 +1,51 @@
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.

15
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/build_name.rst Normal file
View File

@ -0,0 +1,15 @@
build_name
----------
Disallowed since version 3.0. See CMake Policy :policy:`CMP0036`.
Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead.
.. code-block:: cmake
build_name(variable)
Sets the specified variable to a string representing the platform and
compiler settings. These values are now available through the
:variable:`CMAKE_SYSTEM` and
:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` variables.

78
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/cmake_file_api.rst Normal file
View File

@ -0,0 +1,78 @@
cmake_file_api
--------------
.. versionadded:: 3.27
Enables interacting with the :manual:`CMake file API <cmake-file-api(7)>`.
.. signature::
cmake_file_api(QUERY ...)
The ``QUERY`` subcommand adds a file API query for the current CMake
invocation.
.. code-block:: cmake
cmake_file_api(
QUERY
API_VERSION <version>
[CODEMODEL <versions>...]
[CACHE <versions>...]
[CMAKEFILES <versions>...]
[TOOLCHAINS <versions>...]
)
The ``API_VERSION`` must always be given. Currently, the only supported
value for ``<version>`` is 1. See :ref:`file-api v1` for details of the
reply content and location.
Each of the optional keywords ``CODEMODEL``, ``CACHE``, ``CMAKEFILES`` and
``TOOLCHAINS`` correspond to one of the object kinds that can be requested
by the project. The ``configureLog`` object kind cannot be set with this
command, since it must be set before CMake starts reading the top level
``CMakeLists.txt`` file.
For each of the optional keywords, the ``<versions>`` list must contain one
or more version values of the form ``major`` or ``major.minor``, where
``major`` and ``minor`` are integers. Projects should list the versions they
accept in their preferred order, as only the first supported value from the
list will be selected. The command will ignore versions with a ``major``
version higher than any major version it supports for that object kind.
It will raise an error if it encounters an invalid version number, or if none
of the requested versions is supported.
For each type of object kind requested, a query equivalent to a shared,
stateless query will be added internally. No query file will be created in
the file system. The reply *will* be written to the file system at
generation time.
It is not an error to add a query for the same thing more than once, whether
from query files or from multiple calls to ``cmake_file_api(QUERY)``.
The final set of queries will be a merged combination of all queries
specified on disk and queries submitted by the project.
Example
^^^^^^^
A project may want to use replies from the file API at build time to implement
some form of verification task. Instead of relying on something outside of
CMake to create a query file, the project can use ``cmake_file_api(QUERY)``
to request the required information for the current run. It can then create
a custom command to run at build time, knowing that the requested information
should always be available.
.. code-block:: cmake
cmake_file_api(
QUERY
API_VERSION 1
CODEMODEL 2.3
TOOLCHAINS 1
)
add_custom_target(verify_project
COMMAND ${CMAKE_COMMAND}
-D BUILD_DIR=${CMAKE_BINARY_DIR}
-D CONFIG=$<CONFIG>
-P ${CMAKE_CURRENT_SOURCE_DIR}/verify_project.cmake
)

396
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/cmake_host_system_information.rst Normal file
View File

@ -0,0 +1,396 @@
cmake_host_system_information
-----------------------------
Query various host system information.
Synopsis
^^^^^^^^
.. parsed-literal::
`Query host system specific information`_
cmake_host_system_information(RESULT <variable> QUERY <key> ...)
`Query Windows registry`_
cmake_host_system_information(RESULT <variable> QUERY WINDOWS_REGISTRY <key> ...)
Query host system specific information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
cmake_host_system_information(RESULT <variable> QUERY <key> ...)
Queries system information of the host system on which cmake runs.
One or more ``<key>`` can be provided to select the information to be
queried. The list of queried values is stored in ``<variable>``.
``<key>`` can be one of the following values:
``NUMBER_OF_LOGICAL_CORES``
Number of logical cores
``NUMBER_OF_PHYSICAL_CORES``
Number of physical cores
``HOSTNAME``
Hostname
``FQDN``
Fully qualified domain name
``TOTAL_VIRTUAL_MEMORY``
Total virtual memory in MiB [#mebibytes]_
``AVAILABLE_VIRTUAL_MEMORY``
Available virtual memory in MiB [#mebibytes]_
``TOTAL_PHYSICAL_MEMORY``
Total physical memory in MiB [#mebibytes]_
``AVAILABLE_PHYSICAL_MEMORY``
Available physical memory in MiB [#mebibytes]_
``IS_64BIT``
.. versionadded:: 3.10
One if processor is 64Bit
``HAS_FPU``
.. versionadded:: 3.10
One if processor has floating point unit
``HAS_MMX``
.. versionadded:: 3.10
One if processor supports MMX instructions
``HAS_MMX_PLUS``
.. versionadded:: 3.10
One if processor supports Ext. MMX instructions
``HAS_SSE``
.. versionadded:: 3.10
One if processor supports SSE instructions
``HAS_SSE2``
.. versionadded:: 3.10
One if processor supports SSE2 instructions
``HAS_SSE_FP``
.. versionadded:: 3.10
One if processor supports SSE FP instructions
``HAS_SSE_MMX``
.. versionadded:: 3.10
One if processor supports SSE MMX instructions
``HAS_AMD_3DNOW``
.. versionadded:: 3.10
One if processor supports 3DNow instructions
``HAS_AMD_3DNOW_PLUS``
.. versionadded:: 3.10
One if processor supports 3DNow+ instructions
``HAS_IA64``
.. versionadded:: 3.10
One if IA64 processor emulating x86
``HAS_SERIAL_NUMBER``
.. versionadded:: 3.10
One if processor has serial number
``PROCESSOR_SERIAL_NUMBER``
.. versionadded:: 3.10
Processor serial number
``PROCESSOR_NAME``
.. versionadded:: 3.10
Human readable processor name
``PROCESSOR_DESCRIPTION``
.. versionadded:: 3.10
Human readable full processor description
``OS_NAME``
.. versionadded:: 3.10
See :variable:`CMAKE_HOST_SYSTEM_NAME`
``OS_RELEASE``
.. versionadded:: 3.10
The OS sub-type e.g. on Windows ``Professional``
``OS_VERSION``
.. versionadded:: 3.10
The OS build ID
``OS_PLATFORM``
.. versionadded:: 3.10
See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`
``DISTRIB_INFO``
.. versionadded:: 3.22
Read :file:`/etc/os-release` file and define the given ``<variable>``
into a list of read variables
``DISTRIB_<name>``
.. versionadded:: 3.22
Get the ``<name>`` variable (see `man 5 os-release`_) if it exists in the
:file:`/etc/os-release` file
Example:
.. code-block:: cmake
cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME)
message(STATUS "${PRETTY_NAME}")
cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO)
foreach(VAR IN LISTS DISTRO)
message(STATUS "${VAR}=`${${VAR}}`")
endforeach()
Output::
-- Ubuntu 20.04.2 LTS
-- DISTRO_BUG_REPORT_URL=`https://bugs.launchpad.net/ubuntu/`
-- DISTRO_HOME_URL=`https://www.ubuntu.com/`
-- DISTRO_ID=`ubuntu`
-- DISTRO_ID_LIKE=`debian`
-- DISTRO_NAME=`Ubuntu`
-- DISTRO_PRETTY_NAME=`Ubuntu 20.04.2 LTS`
-- DISTRO_PRIVACY_POLICY_URL=`https://www.ubuntu.com/legal/terms-and-policies/privacy-policy`
-- DISTRO_SUPPORT_URL=`https://help.ubuntu.com/`
-- DISTRO_UBUNTU_CODENAME=`focal`
-- DISTRO_VERSION=`20.04.2 LTS (Focal Fossa)`
-- DISTRO_VERSION_CODENAME=`focal`
-- DISTRO_VERSION_ID=`20.04`
If :file:`/etc/os-release` file is not found, the command tries to gather OS
identification via fallback scripts. The fallback script can use `various
distribution-specific files`_ to collect OS identification data and map it
into `man 5 os-release`_ variables.
Fallback Interface Variables
""""""""""""""""""""""""""""
.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS
In addition to the scripts shipped with CMake, a user may append full
paths to his script(s) to the this list. The script filename has the
following format: ``NNN-<name>.cmake``, where ``NNN`` is three digits
used to apply collected scripts in a specific order.
.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname>
Variables collected by the user provided fallback script
ought to be assigned to CMake variables using this naming
convention. Example, the ``ID`` variable from the manual becomes
``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID``.
.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT
The fallback script ought to store names of all assigned
``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname>`` variables in this list.
Example:
.. code-block:: cmake
# Try to detect some old distribution
# See also
# - http://linuxmafia.com/faq/Admin/release-files.html
#
if(NOT EXISTS "${CMAKE_SYSROOT}/etc/foobar-release")
return()
endif()
# Get the first string only
file(
STRINGS "${CMAKE_SYSROOT}/etc/foobar-release" CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT
LIMIT_COUNT 1
)
#
# Example:
#
# Foobar distribution release 1.2.3 (server)
#
if(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT MATCHES "Foobar distribution release ([0-9\.]+) .*")
set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME Foobar)
set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME "${CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT}")
set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID foobar)
set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION ${CMAKE_MATCH_1})
set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID ${CMAKE_MATCH_1})
list(
APPEND CMAKE_GET_OS_RELEASE_FALLBACK_RESULT
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID
)
endif()
unset(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT)
.. rubric:: Footnotes
.. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes.
.. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/os-release.html
.. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html
.. _Query Windows registry:
Query Windows registry
^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.24
::
cmake_host_system_information(RESULT <variable>
QUERY WINDOWS_REGISTRY <key> [VALUE_NAMES|SUBKEYS|VALUE <name>]
[VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
[SEPARATOR <separator>]
[ERROR_VARIABLE <result>])
Performs query operations on local computer registry subkey. Returns a list of
subkeys or value names that are located under the specified subkey in the
registry or the data of the specified value name. The result of the queried
entity is stored in ``<variable>``.
.. note::
Querying registry for any other platforms than ``Windows``, including
``CYGWIN``, will always returns an empty string and sets an error message in
the variable specified with sub-option ``ERROR_VARIABLE``.
``<key>`` specify the full path of a subkey on the local computer. The
``<key>`` must include a valid root key. Valid root keys for the local computer
are:
* ``HKLM`` or ``HKEY_LOCAL_MACHINE``
* ``HKCU`` or ``HKEY_CURRENT_USER``
* ``HKCR`` or ``HKEY_CLASSES_ROOT``
* ``HKU`` or ``HKEY_USERS``
* ``HKCC`` or ``HKEY_CURRENT_CONFIG``
And, optionally, the path to a subkey under the specified root key. The path
separator can be the slash or the backslash. ``<key>`` is not case sensitive.
For example:
.. code-block:: cmake
cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM")
cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKCU\\SOFTWARE\\Kitware")
``VALUE_NAMES``
Request the list of value names defined under ``<key>``. If a default value
is defined, it will be identified with the special name ``(default)``.
``SUBKEYS``
Request the list of subkeys defined under ``<key>``.
``VALUE <name>``
Request the data stored in value named ``<name>``. If ``VALUE`` is not
specified or argument is the special name ``(default)``, the content of the
default value, if any, will be returned.
.. code-block:: cmake
# query default value for HKLM/SOFTWARE/Kitware key
cmake_host_system_information(RESULT result
QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
# query default value for HKLM/SOFTWARE/Kitware key using special value name
cmake_host_system_information(RESULT result
QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware"
VALUE "(default)")
Supported types are:
* ``REG_SZ``.
* ``REG_EXPAND_SZ``. The returned data is expanded.
* ``REG_MULTI_SZ``. The returned is expressed as a CMake list. See also
``SEPARATOR`` sub-option.
* ``REG_DWORD``.
* ``REG_QWORD``.
For all other types, an empty string is returned.
``VIEW``
Specify which registry views must be queried. When not specified, ``BOTH``
view is used.
``64``
Query the 64bit registry. On ``32bit Windows``, returns always an empty
string.
``32``
Query the 32bit registry.
``64_32``
For ``VALUE`` sub-option or default value, query the registry using view
``64``, and if the request failed, query the registry using view ``32``.
For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``64``
and ``32``) and merge the results (sorted and duplicates removed).
``32_64``
For ``VALUE`` sub-option or default value, query the registry using view
``32``, and if the request failed, query the registry using view ``64``.
For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``32``
and ``64``) and merge the results (sorted and duplicates removed).
``HOST``
Query the registry matching the architecture of the host: ``64`` on ``64bit
Windows`` and ``32`` on ``32bit Windows``.
``TARGET``
Query the registry matching the architecture specified by
:variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to
``HOST`` view.
``BOTH``
Query both views (``32`` and ``64``). The order depends of the following
rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the
following view depending of the content of this variable:
* ``8``: ``64_32``
* ``4``: ``32_64``
If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on
architecture of the host:
* ``64bit``: ``64_32``
* ``32bit``: ``32``
``SEPARATOR``
Specify the separator character for ``REG_MULTI_SZ`` type. When not
specified, the character ``\0`` is used.
``ERROR_VARIABLE <result>``
Returns any error raised during query operation. In case of success, the
variable holds an empty string.

508
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/cmake_language.rst Normal file
View File

@ -0,0 +1,508 @@
cmake_language
--------------
.. versionadded:: 3.18
Call meta-operations on CMake commands.
Synopsis
^^^^^^^^
.. parsed-literal::
cmake_language(`CALL`_ <command> [<arg>...])
cmake_language(`EVAL`_ CODE <code>...)
cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...])
cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...)
cmake_language(`GET_MESSAGE_LOG_LEVEL`_ <out-var>)
Introduction
^^^^^^^^^^^^
This command will call meta-operations on built-in CMake commands or
those created via the :command:`macro` or :command:`function` commands.
``cmake_language`` does not introduce a new variable or policy scope.
Calling Commands
^^^^^^^^^^^^^^^^
.. signature::
cmake_language(CALL <command> [<arg>...])
Calls the named ``<command>`` with the given arguments (if any).
For example, the code:
.. code-block:: cmake
set(message_command "message")
cmake_language(CALL ${message_command} STATUS "Hello World!")
is equivalent to
.. code-block:: cmake
message(STATUS "Hello World!")
.. note::
To ensure consistency of the code, the following commands are not allowed:
* ``if`` / ``elseif`` / ``else`` / ``endif``
* ``block`` / ``endblock``
* ``while`` / ``endwhile``
* ``foreach`` / ``endforeach``
* ``function`` / ``endfunction``
* ``macro`` / ``endmacro``
Evaluating Code
^^^^^^^^^^^^^^^
.. signature::
cmake_language(EVAL CODE <code>...)
:target: EVAL
Evaluates the ``<code>...`` as CMake code.
For example, the code:
.. code-block:: cmake
set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
cmake_language(EVAL CODE "
if (${condition})
message(STATUS TRUE)
else()
message(STATUS FALSE)
endif()"
)
is equivalent to
.. code-block:: cmake
set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
if (${condition})
message(STATUS TRUE)
else()
message(STATUS FALSE)
endif()"
)
include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
Deferring Calls
^^^^^^^^^^^^^^^
.. versionadded:: 3.19
.. signature::
cmake_language(DEFER <options>... CALL <command> [<arg>...])
Schedules a call to the named ``<command>`` with the given arguments (if any)
to occur at a later time. By default, deferred calls are executed as if
written at the end of the current directory's ``CMakeLists.txt`` file,
except that they run even after a :command:`return` call. Variable
references in arguments are evaluated at the time the deferred call is
executed.
The options are:
``DIRECTORY <dir>``
Schedule the call for the end of the given directory instead of the
current directory. The ``<dir>`` may reference either a source
directory or its corresponding binary directory. Relative paths are
treated as relative to the current source directory.
The given directory must be known to CMake, being either the top-level
directory or one added by :command:`add_subdirectory`. Furthermore,
the given directory must not yet be finished processing. This means
it can be the current directory or one of its ancestors.
``ID <id>``
Specify an identification for the deferred call.
The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``.
The ``<id>`` may begin with an underscore (``_``) only if it was generated
automatically by an earlier call that used ``ID_VAR`` to get the id.
``ID_VAR <var>``
Specify a variable in which to store the identification for the
deferred call. If ``ID <id>`` is not given, a new identification
will be generated and the generated id will start with an underscore (``_``).
The currently scheduled list of deferred calls may be retrieved:
.. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` of deferred call ids. The ids are for the directory scope in which
the calls have been deferred to (i.e. where they will be executed), which can
be different to the scope in which they were created. The ``DIRECTORY``
option can be used to specify the scope for which to retrieve the call ids.
If that option is not given, the call ids for the current directory scope
will be returned.
Details of a specific call may be retrieved from its id:
.. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` in which the first element is the name of the command to be
called, and the remaining elements are its unevaluated arguments (any
contained ``;`` characters are included literally and cannot be distinguished
from multiple arguments). If multiple calls are scheduled with the same id,
this retrieves the first one. If no call is scheduled with the given id in
the specified ``DIRECTORY`` scope (or the current directory scope if no
``DIRECTORY`` option is given), this stores an empty string in the variable.
Deferred calls may be canceled by their id:
.. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
This cancels all deferred calls matching any of the given ids in the specified
``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option
is given). Unknown ids are silently ignored.
Deferred Call Examples
""""""""""""""""""""""
For example, the code:
.. code-block:: cmake
cmake_language(DEFER CALL message "${deferred_message}")
cmake_language(DEFER ID_VAR id CALL message "Canceled Message")
cmake_language(DEFER CANCEL_CALL ${id})
message("Immediate Message")
set(deferred_message "Deferred Message")
prints::
Immediate Message
Deferred Message
The ``Cancelled Message`` is never printed because its command is
canceled. The ``deferred_message`` variable reference is not evaluated
until the call site, so it can be set after the deferred call is scheduled.
In order to evaluate variable references immediately when scheduling a
deferred call, wrap it using ``cmake_language(EVAL)``. However, note that
arguments will be re-evaluated in the deferred call, though that can be
avoided by using bracket arguments. For example:
.. code-block:: cmake
set(deferred_message "Deferred Message 1")
set(re_evaluated [[${deferred_message}]])
cmake_language(EVAL CODE "
cmake_language(DEFER CALL message [[${deferred_message}]])
cmake_language(DEFER CALL message \"${re_evaluated}\")
")
message("Immediate Message")
set(deferred_message "Deferred Message 2")
also prints::
Immediate Message
Deferred Message 1
Deferred Message 2
.. _dependency_providers:
Dependency Providers
^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.24
.. note:: A high-level introduction to this feature can be found in the
:ref:`Using Dependencies Guide <dependency_providers_overview>`.
.. signature::
cmake_language(SET_DEPENDENCY_PROVIDER <command>
SUPPORTED_METHODS <methods>...)
When a call is made to :command:`find_package` or
:command:`FetchContent_MakeAvailable`, the call may be forwarded to a
dependency provider which then has the opportunity to fulfill the request.
If the request is for one of the ``<methods>`` specified when the provider
was set, CMake calls the provider's ``<command>`` with a set of
method-specific arguments. If the provider does not fulfill the request,
or if the provider doesn't support the request's method, or no provider
is set, the built-in :command:`find_package` or
:command:`FetchContent_MakeAvailable` implementation is used to fulfill
the request in the usual way.
One or more of the following values can be specified for the ``<methods>``
when setting the provider:
``FIND_PACKAGE``
The provider command accepts :command:`find_package` requests.
``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
The provider command accepts :command:`FetchContent_MakeAvailable`
requests. It expects each dependency to be fed to the provider command
one at a time, not the whole list in one go.
Only one provider can be set at any point in time. If a provider is already
set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new
provider replaces the previously set one. The specified ``<command>`` must
already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called.
As a special case, providing an empty string for the ``<command>`` and no
``<methods>`` will discard any previously set provider.
The dependency provider can only be set while processing one of the files
specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable.
Thus, dependency providers can only be set as part of the first call to
:command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
outside of that context will result in an error.
.. note::
The choice of dependency provider should always be under the user's control.
As a convenience, a project may choose to provide a file that users can
list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but
the use of such a file should always be the user's choice.
Provider commands
"""""""""""""""""
Providers define a single ``<command>`` to accept requests. The name of
the command should be specific to that provider, not something overly
generic that another provider might also use. This enables users to compose
different providers in their own custom provider. The recommended form is
``xxx_provide_dependency()``, where ``xxx`` is the provider-specific part
(e.g. ``vcpkg_provide_dependency()``, ``conan_provide_dependency()``,
``ourcompany_provide_dependency()``, and so on).
.. code-block:: cmake
xxx_provide_dependency(<method> [<method-specific-args>...])
Because some methods expect certain variables to be set in the calling scope,
the provider command should typically be implemented as a macro rather than a
function. This ensures it does not introduce a new variable scope.
The arguments CMake passes to the dependency provider depend on the type of
request. The first argument is always the method, and it will only ever
be one of the ``<methods>`` that was specified when setting the provider.
``FIND_PACKAGE``
The ``<method-specific-args>`` will be everything passed to the
:command:`find_package` call that requested the dependency. The first of
these ``<method-specific-args>`` will therefore always be the name of the
dependency. Dependency names are case-sensitive for this method because
:command:`find_package` treats them case-sensitively too.
If the provider command fulfills the request, it must set the same variable
that :command:`find_package` expects to be set. For a dependency named
``depName``, the provider must set ``depName_FOUND`` to true if it fulfilled
the request. If the provider returns without setting this variable, CMake
will assume the request was not fulfilled and will fall back to the
built-in implementation.
If the provider needs to call the built-in :command:`find_package`
implementation as part of its processing, it can do so by including the
``BYPASS_PROVIDER`` keyword as one of the arguments.
``FETCHCONTENT_MAKEAVAILABE_SERIAL``
The ``<method-specific-args>`` will be everything passed to the
:command:`FetchContent_Declare` call that corresponds to the requested
dependency, with the following exceptions:
* If ``SOURCE_DIR`` or ``BINARY_DIR`` were not part of the original
declared arguments, they will be added with their default values.
* If :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` is set to ``NEVER``,
any ``FIND_PACKAGE_ARGS`` will be omitted.
* The ``OVERRIDE_FIND_PACKAGE`` keyword is always omitted.
The first of the ``<method-specific-args>`` will always be the name of the
dependency. Dependency names are case-insensitive for this method because
:module:`FetchContent` also treats them case-insensitively.
If the provider fulfills the request, it should call
:command:`FetchContent_SetPopulated`, passing the name of the dependency as
the first argument. The ``SOURCE_DIR`` and ``BINARY_DIR`` arguments to that
command should only be given if the provider makes the dependency's source
and build directories available in exactly the same way as the built-in
:command:`FetchContent_MakeAvailable` command.
If the provider returns without calling :command:`FetchContent_SetPopulated`
for the named dependency, CMake will assume the request was not fulfilled
and will fall back to the built-in implementation.
Note that empty arguments may be significant for this method (e.g. an empty
string following a ``GIT_SUBMODULES`` keyword). Therefore, if forwarding
these arguments on to another command, extra care must be taken to avoid such
arguments being silently dropped.
If ``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` is set, then the
dependency provider will never see requests for the ``<depName>`` dependency
for this method. When the user sets such a variable, they are explicitly
overriding where to get that dependency from and are taking on the
responsibility that their overriding version meets any requirements for that
dependency and is compatible with whatever else in the project uses it.
Depending on the value of :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE`
and whether the ``OVERRIDE_FIND_PACKAGE`` option was given to
:command:`FetchContent_Declare`, having
``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` set may also prevent the
dependency provider from seeing requests for a ``find_package(depName)``
call too.
Provider Examples
"""""""""""""""""
This first example only intercepts :command:`find_package` calls. The
provider command runs an external tool which copies the relevant artifacts
into a provider-specific directory, if that tool knows about the dependency.
It then relies on the built-in implementation to then find those artifacts.
:command:`FetchContent_MakeAvailable` calls would not go through the provider.
.. code-block:: cmake
:caption: mycomp_provider.cmake
# Always ensure we have the policy settings this provider expects
cmake_minimum_required(VERSION 3.24)
set(MYCOMP_PROVIDER_INSTALL_DIR ${CMAKE_BINARY_DIR}/mycomp_packages
CACHE PATH "The directory this provider installs packages to"
)
# Tell the built-in implementation to look in our area first, unless
# the find_package() call uses NO_..._PATH options to exclude it
list(APPEND CMAKE_MODULE_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}/cmake)
list(APPEND CMAKE_PREFIX_PATH ${MYCOMP_PROVIDER_INSTALL_DIR})
macro(mycomp_provide_dependency method package_name)
execute_process(
COMMAND some_tool ${package_name} --installdir ${MYCOMP_PROVIDER_INSTALL_DIR}
COMMAND_ERROR_IS_FATAL ANY
)
endmacro()
cmake_language(
SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
SUPPORTED_METHODS FIND_PACKAGE
)
The user would then typically use the above file like so::
cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ...
The next example demonstrates a provider that accepts both methods, but
only handles one specific dependency. It enforces providing Google Test
using :module:`FetchContent`, but leaves all other dependencies to be
fulfilled by CMake's built-in implementation. It accepts a few different
names, which demonstrates one way of working around projects that hard-code
an unusual or undesirable way of adding this particular dependency to the
build. The example also demonstrates how to use the :command:`list` command
to preserve variables that may be overwritten by a call to
:command:`FetchContent_MakeAvailable`.
.. code-block:: cmake
:caption: mycomp_provider.cmake
cmake_minimum_required(VERSION 3.24)
# Because we declare this very early, it will take precedence over any
# details the project might declare later for the same thing
include(FetchContent)
FetchContent_Declare(
googletest
GIT_REPOSITORY https://github.com/google/googletest.git
GIT_TAG e2239ee6043f73722e7aa812a459f54a28552929 # release-1.11.0
)
# Both FIND_PACKAGE and FETCHCONTENT_MAKEAVAILABLE_SERIAL methods provide
# the package or dependency name as the first method-specific argument.
macro(mycomp_provide_dependency method dep_name)
if("${dep_name}" MATCHES "^(gtest|googletest)$")
# Save our current command arguments in case we are called recursively
list(APPEND mycomp_provider_args ${method} ${dep_name})
# This will forward to the built-in FetchContent implementation,
# which detects a recursive call for the same thing and avoids calling
# the provider again if dep_name is the same as the current call.
FetchContent_MakeAvailable(googletest)
# Restore our command arguments
list(POP_BACK mycomp_provider_args dep_name method)
# Tell the caller we fulfilled the request
if("${method}" STREQUAL "FIND_PACKAGE")
# We need to set this if we got here from a find_package() call
# since we used a different method to fulfill the request.
# This example assumes projects only use the gtest targets,
# not any of the variables the FindGTest module may define.
set(${dep_name}_FOUND TRUE)
elseif(NOT "${dep_name}" STREQUAL "googletest")
# We used the same method, but were given a different name to the
# one we populated with. Tell the caller about the name it used.
FetchContent_SetPopulated(${dep_name}
SOURCE_DIR "${googletest_SOURCE_DIR}"
BINARY_DIR "${googletest_BINARY_DIR}"
)
endif()
endif()
endmacro()
cmake_language(
SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
SUPPORTED_METHODS
FIND_PACKAGE
FETCHCONTENT_MAKEAVAILABLE_SERIAL
)
The final example demonstrates how to modify arguments to a
:command:`find_package` call. It forces all such calls to have the
``QUIET`` keyword. It uses the ``BYPASS_PROVIDER`` keyword to prevent
calling the provider command recursively for the same dependency.
.. code-block:: cmake
:caption: mycomp_provider.cmake
cmake_minimum_required(VERSION 3.24)
macro(mycomp_provide_dependency method)
find_package(${ARGN} BYPASS_PROVIDER QUIET)
endmacro()
cmake_language(
SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
SUPPORTED_METHODS FIND_PACKAGE
)
Getting current message log level
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.25
.. _query_message_log_level:
.. signature::
cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)
Writes the current :command:`message` logging level
into the given ``<output_variable>``.
See :command:`message` for the possible logging levels.
The current message logging level can be set either using the
:option:`--log-level <cmake --log-level>`
command line option of the :manual:`cmake(1)` program or using
the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable.
If both the command line option and the variable are set, the command line
option takes precedence. If neither are set, the default logging level
is returned.

88
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/cmake_minimum_required.rst Normal file
View File

@ -0,0 +1,88 @@
cmake_minimum_required
----------------------
Require a minimum version of cmake.
.. code-block:: cmake
cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR])
.. versionadded:: 3.12
The optional ``<policy_max>`` version.
Sets the minimum required version of cmake for a project.
Also updates the policy settings as explained below.
``<min>`` and the optional ``<policy_max>`` are each CMake versions of the
form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal.
If the running version of CMake is lower than the ``<min>`` required
version it will stop processing the project and report an error.
The optional ``<policy_max>`` version, if specified, must be at least the
``<min>`` version and affects policy settings as described in `Policy Settings`_.
If the running version of CMake is older than 3.12, the extra ``...``
dots will be seen as version component separators, resulting in the
``...<max>`` part being ignored and preserving the pre-3.12 behavior
of basing policies on ``<min>``.
This command will set the value of the
:variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable to ``<min>``.
The ``FATAL_ERROR`` option is accepted but ignored by CMake 2.6 and
higher. It should be specified so CMake versions 2.4 and lower fail
with an error instead of just a warning.
.. note::
Call the ``cmake_minimum_required()`` command at the beginning of
the top-level ``CMakeLists.txt`` file even before calling the
:command:`project` command. It is important to establish version
and policy settings before invoking other commands whose behavior
they may affect. See also policy :policy:`CMP0000`.
Calling ``cmake_minimum_required()`` inside a :command:`function`
limits some effects to the function scope when invoked. For example,
the :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable won't be set
in the calling scope. Functions do not introduce their own policy
scope though, so policy settings of the caller *will* be affected
(see below). Due to this mix of things that do and do not affect the
calling scope, calling ``cmake_minimum_required()`` inside a function
is generally discouraged.
.. _`Policy Settings`:
Policy Settings
^^^^^^^^^^^^^^^
The ``cmake_minimum_required(VERSION)`` command implicitly invokes the
:command:`cmake_policy(VERSION)` command to specify that the current
project code is written for the given range of CMake versions.
All policies known to the running version of CMake and introduced
in the ``<min>`` (or ``<max>``, if specified) version or earlier will
be set to use ``NEW`` behavior. All policies introduced in later
versions will be unset. This effectively requests behavior preferred
as of a given CMake version and tells newer CMake versions to warn
about their new policies.
When a ``<min>`` version higher than 2.4 is specified the command
implicitly invokes
.. code-block:: cmake
cmake_policy(VERSION <min>[...<max>])
which sets CMake policies based on the range of versions specified.
When a ``<min>`` version 2.4 or lower is given the command implicitly
invokes
.. code-block:: cmake
cmake_policy(VERSION 2.4[...<max>])
which enables compatibility features for CMake 2.4 and lower.
.. include:: DEPRECATED_POLICY_VERSIONS.txt
See Also
^^^^^^^^
* :command:`cmake_policy`

121
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/cmake_parse_arguments.rst Normal file
View File

@ -0,0 +1,121 @@
cmake_parse_arguments
---------------------
Parse function or macro arguments.
.. code-block:: cmake
cmake_parse_arguments(<prefix> <options> <one_value_keywords>
<multi_value_keywords> <args>...)
cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
<one_value_keywords> <multi_value_keywords>)
.. versionadded:: 3.5
This command is implemented natively. Previously, it has been defined in the
module :module:`CMakeParseArguments`.
This command is for use in macros or functions.
It processes the arguments given to that macro or function,
and defines a set of variables which hold the values of the
respective options.
The first signature reads processes arguments passed in the ``<args>...``.
This may be used in either a :command:`macro` or a :command:`function`.
.. versionadded:: 3.7
The ``PARSE_ARGV`` signature is only for use in a :command:`function`
body. In this case the arguments that are parsed come from the
``ARGV#`` variables of the calling function. The parsing starts with
the ``<N>``-th argument, where ``<N>`` is an unsigned integer.
This allows for the values to have special characters like ``;`` in them.
The ``<options>`` argument contains all options for the respective macro,
i.e. keywords which can be used when calling the macro without any value
following, like e.g. the ``OPTIONAL`` keyword of the :command:`install`
command.
The ``<one_value_keywords>`` argument contains all keywords for this macro
which are followed by one value, like e.g. ``DESTINATION`` keyword of the
:command:`install` command.
The ``<multi_value_keywords>`` argument contains all keywords for this
macro which can be followed by more than one value, like e.g. the
``TARGETS`` or ``FILES`` keywords of the :command:`install` command.
.. versionchanged:: 3.5
All keywords shall be unique. I.e. every keyword shall only be specified
once in either ``<options>``, ``<one_value_keywords>`` or
``<multi_value_keywords>``. A warning will be emitted if uniqueness is
violated.
When done, ``cmake_parse_arguments`` will consider for each of the
keywords listed in ``<options>``, ``<one_value_keywords>`` and
``<multi_value_keywords>`` a variable composed of the given ``<prefix>``
followed by ``"_"`` and the name of the respective keyword. These
variables will then hold the respective value from the argument list
or be undefined if the associated option could not be found.
For the ``<options>`` keywords, these will always be defined,
to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not.
All remaining arguments are collected in a variable
``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments
were recognized. This can be checked afterwards to see
whether your macro was called with unrecognized parameters.
.. versionadded:: 3.15
``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no
values at all are collected in a variable
``<prefix>_KEYWORDS_MISSING_VALUES`` that will be undefined if all keywords
received values. This can be checked to see if there were keywords without
any values given.
Consider the following example macro, ``my_install()``, which takes similar
arguments to the real :command:`install` command:
.. code-block:: cmake
macro(my_install)
set(options OPTIONAL FAST)
set(oneValueArgs DESTINATION RENAME)
set(multiValueArgs TARGETS CONFIGURATIONS)
cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
"${multiValueArgs}" ${ARGN} )
# ...
Assume ``my_install()`` has been called like this:
.. code-block:: cmake
my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
After the ``cmake_parse_arguments`` call the macro will have set or undefined
the following variables::
MY_INSTALL_OPTIONAL = TRUE
MY_INSTALL_FAST = FALSE # was not used in call to my_install
MY_INSTALL_DESTINATION = "bin"
MY_INSTALL_RENAME <UNDEFINED> # was not used
MY_INSTALL_TARGETS = "foo;bar"
MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
# No value for "CONFIGURATIONS" given
You can then continue and process these variables.
Keywords terminate lists of values, e.g. if directly after a
``one_value_keyword`` another recognized keyword follows, this is
interpreted as the beginning of the new option. E.g.
``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in
``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL``
is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added
to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will
therefore be set to ``TRUE``.
See Also
^^^^^^^^
* :command:`function`
* :command:`macro`

798
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/cmake_path.rst Normal file
View File

@ -0,0 +1,798 @@
cmake_path
----------
.. versionadded:: 3.20
This command is for the manipulation of paths. Only syntactic aspects of
paths are handled, there is no interaction of any kind with any underlying
file system. The path may represent a non-existing path or even one that
is not allowed to exist on the current file system or platform.
For operations that do interact with the filesystem, see the :command:`file`
command.
.. note::
The ``cmake_path`` command handles paths in the format of the build system
(i.e. the host platform), not the target system. When cross-compiling,
if the path contains elements that are not representable on the host
platform (e.g. a drive letter when the host is not Windows), the results
will be unpredictable.
Synopsis
^^^^^^^^
.. parsed-literal::
`Conventions`_
`Path Structure And Terminology`_
`Normalization`_
`Decomposition`_
cmake_path(`GET`_ <path-var> :ref:`ROOT_NAME <GET_ROOT_NAME>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`ROOT_DIRECTORY <GET_ROOT_DIRECTORY>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`ROOT_PATH <GET_ROOT_PATH>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`FILENAME <GET_FILENAME>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`EXTENSION <GET_EXTENSION>` [LAST_ONLY] <out-var>)
cmake_path(`GET`_ <path-var> :ref:`STEM <GET_STEM>` [LAST_ONLY] <out-var>)
cmake_path(`GET`_ <path-var> :ref:`RELATIVE_PART <GET_RELATIVE_PART>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`PARENT_PATH <GET_PARENT_PATH>` <out-var>)
`Query`_
cmake_path(`HAS_ROOT_NAME`_ <path-var> <out-var>)
cmake_path(`HAS_ROOT_DIRECTORY`_ <path-var> <out-var>)
cmake_path(`HAS_ROOT_PATH`_ <path-var> <out-var>)
cmake_path(`HAS_FILENAME`_ <path-var> <out-var>)
cmake_path(`HAS_EXTENSION`_ <path-var> <out-var>)
cmake_path(`HAS_STEM`_ <path-var> <out-var>)
cmake_path(`HAS_RELATIVE_PART`_ <path-var> <out-var>)
cmake_path(`HAS_PARENT_PATH`_ <path-var> <out-var>)
cmake_path(`IS_ABSOLUTE`_ <path-var> <out-var>)
cmake_path(`IS_RELATIVE`_ <path-var> <out-var>)
cmake_path(`IS_PREFIX`_ <path-var> <input> [NORMALIZE] <out-var>)
cmake_path(`COMPARE`_ <input1> <OP> <input2> <out-var>)
`Modification`_
cmake_path(:ref:`SET <cmake_path-SET>` <path-var> [NORMALIZE] <input>)
cmake_path(`APPEND`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
cmake_path(`APPEND_STRING`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
cmake_path(`REMOVE_FILENAME`_ <path-var> [OUTPUT_VARIABLE <out-var>])
cmake_path(`REPLACE_FILENAME`_ <path-var> <input> [OUTPUT_VARIABLE <out-var>])
cmake_path(`REMOVE_EXTENSION`_ <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>])
cmake_path(`REPLACE_EXTENSION`_ <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>])
`Generation`_
cmake_path(`NORMAL_PATH`_ <path-var> [OUTPUT_VARIABLE <out-var>])
cmake_path(`RELATIVE_PATH`_ <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>])
cmake_path(`ABSOLUTE_PATH`_ <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>])
`Native Conversion`_
cmake_path(`NATIVE_PATH`_ <path-var> [NORMALIZE] <out-var>)
cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST`_ <out-var> [NORMALIZE])
cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST`_ <out-var> [NORMALIZE])
`Hashing`_
cmake_path(`HASH`_ <path-var> <out-var>)
Conventions
^^^^^^^^^^^
The following conventions are used in this command's documentation:
``<path-var>``
Always the name of a variable. For commands that expect a ``<path-var>``
as input, the variable must exist and it is expected to hold a single path.
``<input>``
A string literal which may contain a path, path fragment, or multiple paths
with a special separator depending on the command. See the description of
each command to see how this is interpreted.
``<input>...``
Zero or more string literal arguments.
``<out-var>``
The name of a variable into which the result of a command will be written.
.. _Path Structure And Terminology:
Path Structure And Terminology
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A path has the following structure (all components are optional, with some
constraints):
::
root-name root-directory-separator (item-name directory-separator)* filename
``root-name``
Identifies the root on a filesystem with multiple roots (such as ``"C:"``
or ``"//myserver"``). It is optional.
``root-directory-separator``
A directory separator that, if present, indicates that this path is
absolute. If it is missing and the first element other than the
``root-name`` is an ``item-name``, then the path is relative.
``item-name``
A sequence of characters that aren't directory separators. This name may
identify a file, a hard link, a symbolic link, or a directory. Two special
cases are recognized:
* The item name consisting of a single dot character ``.`` is a
directory name that refers to the current directory.
* The item name consisting of two dot characters ``..`` is a
directory name that refers to the parent directory.
The ``(...)*`` pattern shown above is to indicate that there can be zero
or more item names, with multiple items separated by a
``directory-separator``. The ``()*`` characters are not part of the path.
``directory-separator``
The only recognized directory separator is a forward slash character ``/``.
If this character is repeated, it is treated as a single directory
separator. In other words, ``/usr///////lib`` is the same as ``/usr/lib``.
.. _FILENAME_DEF:
.. _EXTENSION_DEF:
.. _STEM_DEF:
``filename``
A path has a ``filename`` if it does not end with a ``directory-separator``.
The ``filename`` is effectively the last ``item-name`` of the path, so it
can also be a hard link, symbolic link or a directory.
A ``filename`` can have an *extension*. By default, the extension is
defined as the sub-string beginning at the left-most period (including
the period) and until the end of the ``filename``. In commands that
accept a ``LAST_ONLY`` keyword, ``LAST_ONLY`` changes the interpretation
to the sub-string beginning at the right-most period.
The following exceptions apply to the above interpretation:
* If the first character in the ``filename`` is a period, that period is
ignored (i.e. a ``filename`` like ``".profile"`` is treated as having
no extension).
* If the ``filename`` is either ``.`` or ``..``, it has no extension.
The *stem* is the part of the ``filename`` before the extension.
Some commands refer to a ``root-path``. This is the concatenation of
``root-name`` and ``root-directory-separator``, either or both of which can
be empty. A ``relative-part`` refers to the full path with any ``root-path``
removed.
Creating A Path Variable
^^^^^^^^^^^^^^^^^^^^^^^^
While a path can be created with care using an ordinary :command:`set`
command, it is recommended to use :ref:`cmake_path(SET) <cmake_path-SET>`
instead, as it automatically converts the path to the required form where
required. The :ref:`cmake_path(APPEND) <APPEND>` subcommand may
be another suitable alternative where a path needs to be constructed by
joining fragments. The following example compares the three methods for
constructing the same path:
.. code-block:: cmake
set(path1 "${CMAKE_CURRENT_SOURCE_DIR}/data")
cmake_path(SET path2 "${CMAKE_CURRENT_SOURCE_DIR}/data")
cmake_path(APPEND path3 "${CMAKE_CURRENT_SOURCE_DIR}" "data")
`Modification`_ and `Generation`_ sub-commands can either store the result
in-place, or in a separate variable named after an ``OUTPUT_VARIABLE``
keyword. All other sub-commands store the result in a mandatory ``<out-var>``
variable.
.. _Normalization:
Normalization
^^^^^^^^^^^^^
Some sub-commands support *normalizing* a path. The algorithm used to
normalize a path is as follows:
1. If the path is empty, stop (the normalized form of an empty path is
also an empty path).
2. Replace each ``directory-separator``, which may consist of multiple
separators, with a single ``/`` (``/a///b --> /a/b``).
3. Remove each solitary period (``.``) and any immediately following
``directory-separator`` (``/a/./b/. --> /a/b``).
4. Remove each ``item-name`` (other than ``..``) that is immediately
followed by a ``directory-separator`` and a ``..``, along with any
immediately following ``directory-separator`` (``/a/b/../c --> a/c``).
5. If there is a ``root-directory``, remove any ``..`` and any
``directory-separators`` immediately following them. The parent of the
root directory is treated as still the root directory (``/../a --> /a``).
6. If the last ``item-name`` is ``..``, remove any trailing
``directory-separator`` (``../ --> ..``).
7. If the path is empty by this stage, add a ``dot`` (normal form of ``./``
is ``.``).
.. _Path Decomposition:
Decomposition
^^^^^^^^^^^^^
.. _GET:
.. _GET_ROOT_NAME:
.. _GET_ROOT_DIRECTORY:
.. _GET_ROOT_PATH:
.. _GET_FILENAME:
.. _GET_EXTENSION:
.. _GET_STEM:
.. _GET_RELATIVE_PART:
.. _GET_PARENT_PATH:
The following forms of the ``GET`` subcommand each retrieve a different
component or group of components from a path. See
`Path Structure And Terminology`_ for the meaning of each path component.
.. code-block:: cmake
cmake_path(GET <path-var> ROOT_NAME <out-var>)
cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
cmake_path(GET <path-var> ROOT_PATH <out-var>)
cmake_path(GET <path-var> FILENAME <out-var>)
cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
cmake_path(GET <path-var> RELATIVE_PART <out-var>)
cmake_path(GET <path-var> PARENT_PATH <out-var>)
If a requested component is not present in the path, an empty string will be
stored in ``<out-var>``. For example, only Windows systems have the concept
of a ``root-name``, so when the host machine is non-Windows, the ``ROOT_NAME``
subcommand will always return an empty string.
For ``PARENT_PATH``, if the `HAS_RELATIVE_PART`_ subcommand returns false,
the result is a copy of ``<path-var>``. Note that this implies that a root
directory is considered to have a parent, with that parent being itself.
Where `HAS_RELATIVE_PART`_ returns true, the result will essentially be
``<path-var>`` with one less element.
Root examples
"""""""""""""
.. code-block:: cmake
set(path "c:/a")
cmake_path(GET path ROOT_NAME rootName)
cmake_path(GET path ROOT_DIRECTORY rootDir)
cmake_path(GET path ROOT_PATH rootPath)
message("Root name is \"${rootName}\"")
message("Root directory is \"${rootDir}\"")
message("Root path is \"${rootPath}\"")
::
Root name is "c:"
Root directory is "/"
Root path is "c:/"
Filename examples
"""""""""""""""""
.. code-block:: cmake
set(path "/a/b")
cmake_path(GET path FILENAME filename)
message("First filename is \"${filename}\"")
# Trailing slash means filename is empty
set(path "/a/b/")
cmake_path(GET path FILENAME filename)
message("Second filename is \"${filename}\"")
::
First filename is "b"
Second filename is ""
Extension and stem examples
"""""""""""""""""""""""""""
.. code-block:: cmake
set(path "name.ext1.ext2")
cmake_path(GET path EXTENSION fullExt)
cmake_path(GET path STEM fullStem)
message("Full extension is \"${fullExt}\"")
message("Full stem is \"${fullStem}\"")
# Effect of LAST_ONLY
cmake_path(GET path EXTENSION LAST_ONLY lastExt)
cmake_path(GET path STEM LAST_ONLY lastStem)
message("Last extension is \"${lastExt}\"")
message("Last stem is \"${lastStem}\"")
# Special cases
set(dotPath "/a/.")
set(dotDotPath "/a/..")
set(someMorePath "/a/.some.more")
cmake_path(GET dotPath EXTENSION dotExt)
cmake_path(GET dotPath STEM dotStem)
cmake_path(GET dotDotPath EXTENSION dotDotExt)
cmake_path(GET dotDotPath STEM dotDotStem)
cmake_path(GET dotMorePath EXTENSION someMoreExt)
cmake_path(GET dotMorePath STEM someMoreStem)
message("Dot extension is \"${dotExt}\"")
message("Dot stem is \"${dotStem}\"")
message("Dot-dot extension is \"${dotDotExt}\"")
message("Dot-dot stem is \"${dotDotStem}\"")
message(".some.more extension is \"${someMoreExt}\"")
message(".some.more stem is \"${someMoreStem}\"")
::
Full extension is ".ext1.ext2"
Full stem is "name"
Last extension is ".ext2"
Last stem is "name.ext1"
Dot extension is ""
Dot stem is "."
Dot-dot extension is ""
Dot-dot stem is ".."
.some.more extension is ".more"
.some.more stem is ".some"
Relative part examples
""""""""""""""""""""""
.. code-block:: cmake
set(path "c:/a/b")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")
set(path "c/d")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")
set(path "/")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")
::
Relative part is "a/b"
Relative part is "c/d"
Relative part is ""
Path traversal examples
"""""""""""""""""""""""
.. code-block:: cmake
set(path "c:/a/b")
cmake_path(GET path PARENT_PATH result)
message("Parent path is \"${result}\"")
set(path "c:/")
cmake_path(GET path PARENT_PATH result)
message("Parent path is \"${result}\"")
::
Parent path is "c:/a"
Parent path is "c:/"
.. _Path Query:
Query
^^^^^
Each of the ``GET`` subcommands has a corresponding ``HAS_...``
subcommand which can be used to discover whether a particular path
component is present. See `Path Structure And Terminology`_ for the
meaning of each path component.
.. _HAS_ROOT_NAME:
.. _HAS_ROOT_DIRECTORY:
.. _HAS_ROOT_PATH:
.. _HAS_FILENAME:
.. _HAS_EXTENSION:
.. _HAS_STEM:
.. _HAS_RELATIVE_PART:
.. _HAS_PARENT_PATH:
.. code-block:: cmake
cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
cmake_path(HAS_FILENAME <path-var> <out-var>)
cmake_path(HAS_EXTENSION <path-var> <out-var>)
cmake_path(HAS_STEM <path-var> <out-var>)
cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
Each of the above follows the predictable pattern of setting ``<out-var>``
to true if the path has the associated component, or false otherwise.
Note the following special cases:
* For ``HAS_ROOT_PATH``, a true result will only be returned if at least one
of ``root-name`` or ``root-directory`` is non-empty.
* For ``HAS_PARENT_PATH``, the root directory is also considered to have a
parent, which will be itself. The result is true except if the path
consists of just a :ref:`filename <FILENAME_DEF>`.
.. _IS_ABSOLUTE:
.. code-block:: cmake
cmake_path(IS_ABSOLUTE <path-var> <out-var>)
Sets ``<out-var>`` to true if ``<path-var>`` is absolute. An absolute path
is a path that unambiguously identifies the location of a file without
reference to an additional starting location. On Windows, this means the
path must have both a ``root-name`` and a ``root-directory-separator`` to be
considered absolute. On other platforms, just a ``root-directory-separator``
is sufficient. Note that this means on Windows, ``IS_ABSOLUTE`` can be
false while ``HAS_ROOT_DIRECTORY`` can be true.
.. _IS_RELATIVE:
.. code-block:: cmake
cmake_path(IS_RELATIVE <path-var> <out-var>)
This will store the opposite of ``IS_ABSOLUTE`` in ``<out-var>``.
.. _IS_PREFIX:
.. code-block:: cmake
cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
Checks if ``<path-var>`` is the prefix of ``<input>``.
When the ``NORMALIZE`` option is specified, ``<path-var>`` and ``<input>``
are :ref:`normalized <Normalization>` before the check.
.. code-block:: cmake
set(path "/a/b/c")
cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true
cmake_path(IS_PREFIX path "/a/b" result) # result = false
cmake_path(IS_PREFIX path "/x/y/z" result) # result = false
set(path "/a/b")
cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true
.. _Path COMPARE:
.. _COMPARE:
.. code-block:: cmake
cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)
cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
Compares the lexical representations of two paths provided as string literals.
No normalization is performed on either path, except multiple consecutive
directory separators are effectively collapsed into a single separator.
Equality is determined according to the following pseudo-code logic:
::
if(NOT <input1>.root_name() STREQUAL <input2>.root_name())
return FALSE
if(<input1>.has_root_directory() XOR <input2>.has_root_directory())
return FALSE
Return FALSE if a relative portion of <input1> is not lexicographically
equal to the relative portion of <input2>. This comparison is performed path
component-wise. If all of the components compare equal, then return TRUE.
.. note::
Unlike most other ``cmake_path()`` subcommands, the ``COMPARE`` subcommand
takes literal strings as input, not the names of variables.
.. _Path Modification:
Modification
^^^^^^^^^^^^
.. _cmake_path-SET:
.. code-block:: cmake
cmake_path(SET <path-var> [NORMALIZE] <input>)
Assign the ``<input>`` path to ``<path-var>``. If ``<input>`` is a native
path, it is converted into a cmake-style path with forward-slashes
(``/``). On Windows, the long filename marker is taken into account.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` after the conversion.
For example:
.. code-block:: cmake
set(native_path "c:\\a\\b/..\\c")
cmake_path(SET path "${native_path}")
message("CMake path is \"${path}\"")
cmake_path(SET path NORMALIZE "${native_path}")
message("Normalized CMake path is \"${path}\"")
Output::
CMake path is "c:/a/b/../c"
Normalized CMake path is "c:/a/c"
.. _APPEND:
.. code-block:: cmake
cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
Append all the ``<input>`` arguments to the ``<path-var>`` using ``/`` as
the ``directory-separator``. Depending on the ``<input>``, the previous
contents of ``<path-var>`` may be discarded. For each ``<input>`` argument,
the following algorithm (pseudo-code) applies:
::
# <path> is the contents of <path-var>
if(<input>.is_absolute() OR
(<input>.has_root_name() AND
NOT <input>.root_name() STREQUAL <path>.root_name()))
replace <path> with <input>
return()
endif()
if(<input>.has_root_directory())
remove any root-directory and the entire relative path from <path>
elseif(<path>.has_filename() OR
(NOT <path-var>.has_root_directory() OR <path>.is_absolute()))
append directory-separator to <path>
endif()
append <input> omitting any root-name to <path>
.. _APPEND_STRING:
.. code-block:: cmake
cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
Append all the ``<input>`` arguments to the ``<path-var>`` without adding any
``directory-separator``.
.. _REMOVE_FILENAME:
.. code-block:: cmake
cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
Removes the :ref:`filename <FILENAME_DEF>` component (as returned by
:ref:`GET ... FILENAME <GET_FILENAME>`) from ``<path-var>``. After removal,
any trailing ``directory-separator`` is left alone, if present.
If ``OUTPUT_VARIABLE`` is not given, then after this function returns,
`HAS_FILENAME`_ returns false for ``<path-var>``.
For example:
.. code-block:: cmake
set(path "/a/b")
cmake_path(REMOVE_FILENAME path)
message("First path is \"${path}\"")
# filename is now already empty, the following removes nothing
cmake_path(REMOVE_FILENAME path)
message("Second path is \"${result}\"")
Output::
First path is "/a/"
Second path is "/a/"
.. _REPLACE_FILENAME:
.. code-block:: cmake
cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
Replaces the :ref:`filename <FILENAME_DEF>` component from ``<path-var>``
with ``<input>``. If ``<path-var>`` has no filename component (i.e.
`HAS_FILENAME`_ returns false), the path is unchanged. The operation is
equivalent to the following:
.. code-block:: cmake
cmake_path(HAS_FILENAME path has_filename)
if(has_filename)
cmake_path(REMOVE_FILENAME path)
cmake_path(APPEND path input);
endif()
.. _REMOVE_EXTENSION:
.. code-block:: cmake
cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
[OUTPUT_VARIABLE <out-var>])
Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``.
.. _REPLACE_EXTENSION:
.. code-block:: cmake
cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
[OUTPUT_VARIABLE <out-var>])
Replaces the :ref:`extension <EXTENSION_DEF>` with ``<input>``. Its effect
is equivalent to the following:
.. code-block:: cmake
cmake_path(REMOVE_EXTENSION path)
if(NOT "input" MATCHES "^\\.")
cmake_path(APPEND_STRING path ".")
endif()
cmake_path(APPEND_STRING path "input")
.. _Path Generation:
Generation
^^^^^^^^^^
.. _NORMAL_PATH:
.. code-block:: cmake
cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
Normalize ``<path-var>`` according the steps described in :ref:`Normalization`.
.. _cmake_path-RELATIVE_PATH:
.. _RELATIVE_PATH:
.. code-block:: cmake
cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
[OUTPUT_VARIABLE <out-var>])
Modifies ``<path-var>`` to make it relative to the ``BASE_DIRECTORY`` argument.
If ``BASE_DIRECTORY`` is not specified, the default base directory will be
:variable:`CMAKE_CURRENT_SOURCE_DIR`.
For reference, the algorithm used to compute the relative path is the same
as that used by C++
`std::filesystem::path::lexically_relative
<https://en.cppreference.com/w/cpp/filesystem/path/lexically_normal>`_.
.. _ABSOLUTE_PATH:
.. code-block:: cmake
cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
[OUTPUT_VARIABLE <out-var>])
If ``<path-var>`` is a relative path (`IS_RELATIVE`_ is true), it is evaluated
relative to the given base directory specified by ``BASE_DIRECTORY`` option.
If ``BASE_DIRECTORY`` is not specified, the default base directory will be
:variable:`CMAKE_CURRENT_SOURCE_DIR`.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` after the path computation.
Because ``cmake_path()`` does not access the filesystem, symbolic links are
not resolved and any leading tilde is not expanded. To compute a real path
with symbolic links resolved and leading tildes expanded, use the
:command:`file(REAL_PATH)` command instead.
Native Conversion
^^^^^^^^^^^^^^^^^
For commands in this section, *native* refers to the host platform, not the
target platform when cross-compiling.
.. _cmake_path-NATIVE_PATH:
.. _NATIVE_PATH:
.. code-block:: cmake
cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
Converts a cmake-style ``<path-var>`` into a native path with
platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere).
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.
.. _CONVERT:
.. _cmake_path-TO_CMAKE_PATH_LIST:
.. _TO_CMAKE_PATH_LIST:
.. code-block:: cmake
cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
Converts a native ``<input>`` path into a cmake-style path with forward
slashes (``/``). On Windows hosts, the long filename marker is taken into
account. The input can be a single path or a system search path like
``$ENV{PATH}``. A search path will be converted to a cmake-style list
separated by ``;`` characters (on non-Windows platforms, this essentially
means ``:`` separators are replaced with ``;``). The result of the
conversion is stored in the ``<out-var>`` variable.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.
.. note::
Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand
takes a literal string as input, not the name of a variable.
.. _cmake_path-TO_NATIVE_PATH_LIST:
.. _TO_NATIVE_PATH_LIST:
.. code-block:: cmake
cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
Converts a cmake-style ``<input>`` path into a native path with
platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere).
The input can be a single path or a cmake-style list. A list will be
converted into a native search path (``;``-separated on Windows,
``:``-separated on other platforms). The result of the conversion is
stored in the ``<out-var>`` variable.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.
.. note::
Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand
takes a literal string as input, not the name of a variable.
For example:
.. code-block:: cmake
set(paths "/a/b/c" "/x/y/z")
cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths)
message("Native path list is \"${native_paths}\"")
Output on Windows::
Native path list is "\a\b\c;\x\y\z"
Output on all other platforms::
Native path list is "/a/b/c:/x/y/z"
Hashing
^^^^^^^
.. _HASH:
.. code-block:: cmake
cmake_path(HASH <path-var> <out-var>)
Compute a hash value of ``<path-var>`` such that for two paths ``p1`` and
``p2`` that compare equal (:ref:`COMPARE ... EQUAL <COMPARE>`), the hash
value of ``p1`` is equal to the hash value of ``p2``. The path is always
:ref:`normalized <Normalization>` before the hash is computed.

159
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/cmake_policy.rst Normal file
View File

@ -0,0 +1,159 @@
cmake_policy
------------
Manage CMake Policy settings. See the :manual:`cmake-policies(7)`
manual for defined policies.
As CMake evolves it is sometimes necessary to change existing behavior
in order to fix bugs or improve implementations of existing features.
The CMake Policy mechanism is designed to help keep existing projects
building as new versions of CMake introduce changes in behavior. Each
new policy (behavioral change) is given an identifier of the form
``CMP<NNNN>`` where ``<NNNN>`` is an integer index. Documentation
associated with each policy describes the ``OLD`` and ``NEW`` behavior
and the reason the policy was introduced. Projects may set each policy
to select the desired behavior. When CMake needs to know which behavior
to use it checks for a setting specified by the project. If no
setting is available the ``OLD`` behavior is assumed and a warning is
produced requesting that the policy be set.
Setting Policies by CMake Version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
behavior. While setting policies individually is supported, we
encourage projects to set policies based on CMake versions:
.. code-block:: cmake
cmake_policy(VERSION <min>[...<max>])
.. versionadded:: 3.12
The optional ``<max>`` version.
``<min>`` and the optional ``<max>`` are each CMake versions of the form
``major.minor[.patch[.tweak]]``, and the ``...`` is literal. The ``<min>``
version must be at least ``2.4`` and at most the running version of CMake.
The ``<max>`` version, if specified, must be at least the ``<min>`` version
but may exceed the running version of CMake. If the running version of
CMake is older than 3.12, the extra ``...`` dots will be seen as version
component separators, resulting in the ``...<max>`` part being ignored and
preserving the pre-3.12 behavior of basing policies on ``<min>``.
This specifies that the current CMake code is written for the given
range of CMake versions. All policies known to the running version of CMake
and introduced in the ``<min>`` (or ``<max>``, if specified) version
or earlier will be set to use ``NEW`` behavior. All policies
introduced in later versions will be unset (unless the
:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default).
This effectively requests behavior preferred as of a given CMake
version and tells newer CMake versions to warn about their new policies.
Note that the :command:`cmake_minimum_required(VERSION)`
command implicitly calls ``cmake_policy(VERSION)`` too.
.. include:: DEPRECATED_POLICY_VERSIONS.txt
Setting Policies Explicitly
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
cmake_policy(SET CMP<NNNN> NEW)
cmake_policy(SET CMP<NNNN> OLD)
Tell CMake to use the ``OLD`` or ``NEW`` behavior for a given policy.
Projects depending on the old behavior of a given policy may silence a
policy warning by setting the policy state to ``OLD``. Alternatively
one may fix the project to work with the new behavior and set the
policy state to ``NEW``.
.. include:: ../policy/DEPRECATED.txt
Checking Policy Settings
^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
cmake_policy(GET CMP<NNNN> <variable>)
Check whether a given policy is set to ``OLD`` or ``NEW`` behavior.
The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the
policy is set, and empty otherwise.
CMake Policy Stack
^^^^^^^^^^^^^^^^^^
CMake keeps policy settings on a stack, so changes made by the
``cmake_policy`` command affect only the top of the stack. A new entry on
the policy stack is managed automatically for each subdirectory to
protect its parents and siblings. CMake also manages a new entry for
scripts loaded by :command:`include` and :command:`find_package` commands
except when invoked with the ``NO_POLICY_SCOPE`` option
(see also policy :policy:`CMP0011`).
The ``cmake_policy`` command provides an interface to manage custom
entries on the policy stack:
.. code-block:: cmake
cmake_policy(PUSH)
cmake_policy(POP)
Each ``PUSH`` must have a matching ``POP`` to erase any changes.
This is useful to make temporary changes to policy settings.
Calls to the :command:`cmake_minimum_required(VERSION)`,
``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands
influence only the current top of the policy stack.
.. versionadded:: 3.25
The :command:`block` and :command:`endblock` commands offer a more flexible
and more secure way to manage the policy stack. The pop action is done
automatically when the :command:`endblock` command is executed, so it avoid
to call the :command:`cmake_policy(POP)` command before each
:command:`return` command.
.. code-block:: cmake
# stack management with cmake_policy()
function(my_func)
cmake_policy(PUSH)
cmake_policy(SET ...)
if (<cond1>)
...
cmake_policy(POP)
return()
elseif(<cond2>)
...
cmake_policy(POP)
return()
endif()
...
cmake_policy(POP)
endfunction()
# stack management with block()/endblock()
function(my_func)
block(SCOPE_FOR POLICIES)
cmake_policy(SET ...)
if (<cond1>)
...
return()
elseif(<cond2>)
...
return()
endif()
...
endblock()
endfunction()
Commands created by the :command:`function` and :command:`macro`
commands record policy settings when they are created and
use the pre-record policies when they are invoked. If the function or
macro implementation sets policies, the changes automatically
propagate up through callers until they reach the closest nested
policy stack entry.
See Also
^^^^^^^^
* :command:`cmake_minimum_required`

189
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/configure_file.rst Normal file
View File

@ -0,0 +1,189 @@
configure_file
--------------
Copy a file to another location and modify its contents.
.. code-block:: cmake
configure_file(<input> <output>
[NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
FILE_PERMISSIONS <permissions>...]
[COPYONLY] [ESCAPE_QUOTES] [@ONLY]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Copies an ``<input>`` file to an ``<output>`` file and substitutes
variable values referenced as ``@VAR@``, ``${VAR}``, ``$CACHE{VAR}`` or
``$ENV{VAR}`` in the input file content. Each variable reference will be
replaced with the current value of the variable, or the empty string if
the variable is not defined. Furthermore, input lines of the form
.. code-block:: c
#cmakedefine VAR ...
will be replaced with either
.. code-block:: c
#define VAR ...
or
.. code-block:: c
/* #undef VAR */
depending on whether ``VAR`` is set in CMake to any value not considered
a false constant by the :command:`if` command. The "..." content on the
line after the variable name, if any, is processed as above.
Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form
``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1``
rather than being assigned the value ``...``. Therefore, input lines of the form
.. code-block:: c
#cmakedefine01 VAR
will be replaced with either
.. code-block:: c
#define VAR 0
or
.. code-block:: c
#define VAR 1
Input lines of the form ``#cmakedefine01 VAR ...`` will expand
as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 1``,
which may lead to undefined behavior.
.. versionadded:: 3.10
The result lines (with the exception of the ``#undef`` comments) can be
indented using spaces and/or tabs between the ``#`` character
and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace
indentation will be preserved in the output lines:
.. code-block:: c
# cmakedefine VAR
# cmakedefine01 VAR
will be replaced, if ``VAR`` is defined, with
.. code-block:: c
# define VAR
# define VAR 1
If the input file is modified the build system will re-run CMake to
re-configure the file and generate the build system again.
The generated file is modified and its timestamp updated on subsequent
cmake runs only if its content is changed.
The arguments are:
``<input>``
Path to the input file. A relative path is treated with respect to
the value of :variable:`CMAKE_CURRENT_SOURCE_DIR`. The input path
must be a file, not a directory.
``<output>``
Path to the output file or directory. A relative path is treated
with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
If the path names an existing directory the output file is placed
in that directory with the same file name as the input file.
If the path contains non-existent directories, they are created.
``NO_SOURCE_PERMISSIONS``
.. versionadded:: 3.19
Do not transfer the permissions of the input file to the output file.
The copied file permissions default to the standard 644 value
(-rw-r--r--).
``USE_SOURCE_PERMISSIONS``
.. versionadded:: 3.20
Transfer the permissions of the input file to the output file.
This is already the default behavior if none of the three permissions-related
keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS``
or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly
serves as a way of making the intended behavior clearer at the call site.
``FILE_PERMISSIONS <permissions>...``
.. versionadded:: 3.20
Ignore the input file's permissions and use the specified ``<permissions>``
for the output file instead.
``COPYONLY``
Copy the file without replacing any variable references or other
content. This option may not be used with ``NEWLINE_STYLE``.
``ESCAPE_QUOTES``
Escape any substituted quotes with backslashes (C-style).
``@ONLY``
Restrict variable replacement to references of the form ``@VAR@``.
This is useful for configuring scripts that use ``${VAR}`` syntax.
``NEWLINE_STYLE <style>``
Specify the newline style for the output file. Specify
``UNIX`` or ``LF`` for ``\n`` newlines, or specify
``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
This option may not be used with ``COPYONLY``.
Example
^^^^^^^
Consider a source tree containing a ``foo.h.in`` file:
.. code-block:: c
#cmakedefine FOO_ENABLE
#cmakedefine FOO_STRING "@FOO_STRING@"
An adjacent ``CMakeLists.txt`` may use ``configure_file`` to
configure the header:
.. code-block:: cmake
option(FOO_ENABLE "Enable Foo" ON)
if(FOO_ENABLE)
set(FOO_STRING "foo")
endif()
configure_file(foo.h.in foo.h @ONLY)
This creates a ``foo.h`` in the build directory corresponding to
this source directory. If the ``FOO_ENABLE`` option is on, the
configured file will contain:
.. code-block:: c
#define FOO_ENABLE
#define FOO_STRING "foo"
Otherwise it will contain:
.. code-block:: c
/* #undef FOO_ENABLE */
/* #undef FOO_STRING */
One may then use the :command:`target_include_directories` command to
specify the output directory as an include directory:
.. code-block:: cmake
target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}")
so that sources may include the header as ``#include <foo.h>``.
See Also
^^^^^^^^
* :command:`file(GENERATE)`

16
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/continue.rst Normal file
View File

@ -0,0 +1,16 @@
continue
--------
.. versionadded:: 3.2
Continue to the top of enclosing foreach or while loop.
.. code-block:: cmake
continue()
The ``continue()`` command allows a cmake script to abort the rest of the
current iteration of a :command:`foreach` or :command:`while` loop, and start
at the top of the next iteration.
See also the :command:`break` command.

30
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/create_test_sourcelist.rst Normal file
View File

@ -0,0 +1,30 @@
create_test_sourcelist
----------------------
Create a test driver and source list for building test programs.
.. code-block:: cmake
create_test_sourcelist(sourceListName driverName
test1 test2 test3
EXTRA_INCLUDE include.h
FUNCTION function)
A test driver is a program that links together many small tests into a
single executable. This is useful when building static executables
with large libraries to shrink the total required size. The list of
source files needed to build the test driver will be in
``sourceListName``. ``driverName`` is the name of the test driver program.
The rest of the arguments consist of a list of test source files, can
be semicolon separated. Each test source file should have a function
in it that is the same name as the file with no extension (foo.cxx
should have int foo(int, char*[]);) ``driverName`` will be able to call
each of the tests by name on the command line. If ``EXTRA_INCLUDE`` is
specified, then the next argument is included into the generated file.
If ``FUNCTION`` is specified, then the next argument is taken as a
function name that is passed a pointer to ac and av. This can be used
to add extra command line processing to each test. The
``CMAKE_TESTDRIVER_BEFORE_TESTMAIN`` cmake variable can be set to
have code that will be placed directly before calling the test main function.
``CMAKE_TESTDRIVER_AFTER_TESTMAIN`` can be set to have code that
will be placed directly after the call to the test main function.

93
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_build.rst Normal file
View File

@ -0,0 +1,93 @@
ctest_build
-----------
Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_build([BUILD <build-dir>] [APPEND]
[CONFIGURATION <config>]
[PARALLEL_LEVEL <parallel>]
[FLAGS <flags>]
[PROJECT_NAME <project-name>]
[TARGET <target-name>]
[NUMBER_ERRORS <num-err-var>]
[NUMBER_WARNINGS <num-warn-var>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
)
Build the project and store results in ``Build.xml``
for submission with the :command:`ctest_submit` command.
The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly
specify the build command line. Otherwise the build command line is
computed automatically based on the options given.
The options are:
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
``APPEND``
Mark ``Build.xml`` for append to results previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
This does *not* cause results to be appended to a ``.xml`` file
produced by a previous call to this command.
``CONFIGURATION <config>``
Specify the build configuration (e.g. ``Debug``). If not
specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
Otherwise the :option:`-C \<cfg\> <ctest -C>` option given to the
:manual:`ctest(1)` command will be used, if any.
``PARALLEL_LEVEL <parallel>``
.. versionadded:: 3.21
Specify the parallel level of the underlying build system. If not
specified, the :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment
variable will be checked.
``FLAGS <flags>``
Pass additional arguments to the underlying build command.
If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
This can, e.g., be used to trigger a parallel build using the
``-j`` option of ``make``. See the :module:`ProcessorCount` module
for an example.
``PROJECT_NAME <project-name>``
Ignored since CMake 3.0.
.. versionchanged:: 3.14
This value is no longer required.
``TARGET <target-name>``
Specify the name of a target to build. If not specified the
``CTEST_BUILD_TARGET`` variable will be checked. Otherwise the
default target will be built. This is the "all" target
(called ``ALL_BUILD`` in :ref:`Visual Studio Generators`).
``NUMBER_ERRORS <num-err-var>``
Store the number of build errors detected in the given variable.
``NUMBER_WARNINGS <num-warn-var>``
Store the number of build warnings detected in the given variable.
``RETURN_VALUE <result-var>``
Store the return value of the native build tool in the given variable.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.7
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
.. versionadded:: 3.3
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise. The summary of warnings / errors,
as well as the output from the native build tool is unaffected by
this option.

50
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_configure.rst Normal file
View File

@ -0,0 +1,50 @@
ctest_configure
---------------
Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
[OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
[CAPTURE_CMAKE_ERROR <result-var>])
Configure the project build tree and record results in ``Configure.xml``
for submission with the :command:`ctest_submit` command.
The options are:
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
``SOURCE <source-dir>``
Specify the source directory. If not given, the
:variable:`CTEST_SOURCE_DIRECTORY` variable is used.
``APPEND``
Mark ``Configure.xml`` for append to results previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
This does *not* cause results to be appended to a ``.xml`` file
produced by a previous call to this command.
``OPTIONS <options>``
Specify command-line arguments to pass to the configuration tool.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable the return value of the native
configuration tool.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.7
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
.. versionadded:: 3.3
Suppress any CTest-specific non-error messages that would have
otherwise been printed to the console. Output from the underlying
configure command is not affected.

50
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_coverage.rst Normal file
View File

@ -0,0 +1,50 @@
ctest_coverage
--------------
Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_coverage([BUILD <build-dir>] [APPEND]
[LABELS <label>...]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[QUIET]
)
Collect coverage tool results and stores them in ``Coverage.xml``
for submission with the :command:`ctest_submit` command.
The options are:
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
``APPEND``
Mark ``Coverage.xml`` for append to results previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
This does *not* cause results to be appended to a ``.xml`` file
produced by a previous call to this command.
``LABELS``
Filter the coverage report to include only source files labeled
with at least one of the labels specified.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` if coverage tools
ran without error and non-zero otherwise.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.7
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
.. versionadded:: 3.3
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise. The summary indicating how many
lines of code were covered is unaffected by this option.

12
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_empty_binary_directory.rst Normal file
View File

@ -0,0 +1,12 @@
ctest_empty_binary_directory
----------------------------
empties the binary directory
.. code-block:: cmake
ctest_empty_binary_directory(<directory>)
Removes a binary directory. This command will perform some checks
prior to deleting the directory in an attempt to avoid malicious or
accidental directory deletion.

45
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_memcheck.rst Normal file
View File

@ -0,0 +1,45 @@
ctest_memcheck
--------------
Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_memcheck([BUILD <build-dir>] [APPEND]
[START <start-number>]
[END <end-number>]
[STRIDE <stride-number>]
[EXCLUDE <exclude-regex>]
[INCLUDE <include-regex>]
[EXCLUDE_LABEL <label-exclude-regex>]
[INCLUDE_LABEL <label-include-regex>]
[EXCLUDE_FIXTURE <regex>]
[EXCLUDE_FIXTURE_SETUP <regex>]
[EXCLUDE_FIXTURE_CLEANUP <regex>]
[PARALLEL_LEVEL <level>]
[RESOURCE_SPEC_FILE <file>]
[TEST_LOAD <threshold>]
[SCHEDULE_RANDOM <ON|OFF>]
[STOP_ON_FAILURE]
[STOP_TIME <time-of-day>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[REPEAT <mode>:<n>]
[OUTPUT_JUNIT <file>]
[DEFECT_COUNT <defect-count-var>]
[QUIET]
)
Run tests with a dynamic analysis tool and store results in
``MemCheck.xml`` for submission with the :command:`ctest_submit`
command.
Most options are the same as those for the :command:`ctest_test` command.
The options unique to this command are:
``DEFECT_COUNT <defect-count-var>``
.. versionadded:: 3.8
Store in the ``<defect-count-var>`` the number of defects found.

14
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_read_custom_files.rst Normal file
View File

@ -0,0 +1,14 @@
ctest_read_custom_files
-----------------------
read CTestCustom files.
.. code-block:: cmake
ctest_read_custom_files(<directory>...)
Read all the CTestCustom.ctest or CTestCustom.cmake files from the
given directory.
By default, invoking :manual:`ctest(1)` without a script will read custom
files from the binary directory.

15
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_run_script.rst Normal file
View File

@ -0,0 +1,15 @@
ctest_run_script
----------------
runs a :option:`ctest -S` script
.. code-block:: cmake
ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
script_file_name2 ... [RETURN_VALUE var])
Runs a script or scripts much like if it was run from :option:`ctest -S`.
If no argument is provided then the current script is run using the current
settings of the variables. If ``NEW_PROCESS`` is specified then each
script will be run in a separate process.If ``RETURN_VALUE`` is specified
the return value of the last script run will be put into ``var``.

16
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_sleep.rst Normal file
View File

@ -0,0 +1,16 @@
ctest_sleep
-----------
sleeps for some amount of time
.. code-block:: cmake
ctest_sleep(<seconds>)
Sleep for given number of seconds.
.. code-block:: cmake
ctest_sleep(<time1> <duration> <time2>)
Sleep for t=(time1 + duration - time2) seconds if t > 0.

88
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_start.rst Normal file
View File

@ -0,0 +1,88 @@
ctest_start
-----------
Starts the testing for a given model
.. code-block:: cmake
ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
Starts the testing for a given model. The command should be called
after the binary directory is initialized.
The parameters are as follows:
``<model>``
Set the dashboard model. Must be one of ``Experimental``, ``Continuous``, or
``Nightly``. This parameter is required unless ``APPEND`` is specified.
``<source>``
Set the source directory. If not specified, the value of
:variable:`CTEST_SOURCE_DIRECTORY` is used instead.
``<binary>``
Set the binary directory. If not specified, the value of
:variable:`CTEST_BINARY_DIRECTORY` is used instead.
``GROUP <group>``
If ``GROUP`` is used, the submissions will go to the specified group on the
CDash server. If no ``GROUP`` is specified, the name of the model is used by
default.
.. versionchanged:: 3.16
This replaces the deprecated option ``TRACK``. Despite the name
change its behavior is unchanged.
``APPEND``
If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new
one based on the current time stamp. If you use ``APPEND``, you can omit the
``<model>`` and ``GROUP <group>`` parameters, because they will be read from
the generated ``TAG`` file. For example:
.. code-block:: cmake
ctest_start(Experimental GROUP GroupExperimental)
Later, in another :option:`ctest -S` script:
.. code-block:: cmake
ctest_start(APPEND)
When the second script runs ``ctest_start(APPEND)``, it will read the
``Experimental`` model and ``GroupExperimental`` group from the ``TAG`` file
generated by the first ``ctest_start()`` command. Please note that if you
call ``ctest_start(APPEND)`` and specify a different model or group than
in the first ``ctest_start()`` command, a warning will be issued, and the
new model and group will be used.
``QUIET``
.. versionadded:: 3.3
If ``QUIET`` is used, CTest will suppress any non-error messages that it
otherwise would have printed to the console.
The parameters for ``ctest_start()`` can be issued in any order, with the
exception that ``<model>``, ``<source>``, and ``<binary>`` have to appear
in that order with respect to each other. The following are all valid and
equivalent:
.. code-block:: cmake
ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
However, for the sake of readability, it is recommended that you order your
parameters in the order listed at the top of this page.
If the :variable:`CTEST_CHECKOUT_COMMAND` variable (or the
:variable:`CTEST_CVS_CHECKOUT` variable) is set, its content is treated as
command-line. The command is invoked with the current working directory set
to the parent of the source directory, even if the source directory already
exists. This can be used to create the source tree from a version control
repository.

131
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_submit.rst Normal file
View File

@ -0,0 +1,131 @@
ctest_submit
------------
Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_submit([PARTS <part>...] [FILES <file>...]
[SUBMIT_URL <url>]
[BUILD_ID <result-var>]
[HTTPHEADER <header>]
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[QUIET]
)
Submit results to a dashboard server.
By default all available parts are submitted.
The options are:
``PARTS <part>...``
Specify a subset of parts to submit. Valid part names are::
Start = nothing
Update = ctest_update results, in Update.xml
Configure = ctest_configure results, in Configure.xml
Build = ctest_build results, in Build.xml
Test = ctest_test results, in Test.xml
Coverage = ctest_coverage results, in Coverage.xml
MemCheck = ctest_memcheck results, in DynamicAnalysis.xml and
DynamicAnalysis-Test.xml
Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
Upload = Files prepared for upload by ctest_upload(), in Upload.xml
Submit = nothing
Done = Build is complete, in Done.xml
``FILES <file>...``
Specify an explicit list of specific files to be submitted.
Each individual file must exist at the time of the call.
``SUBMIT_URL <url>``
.. versionadded:: 3.14
The ``http`` or ``https`` URL of the dashboard server to send the submission
to. If not given, the :variable:`CTEST_SUBMIT_URL` variable is used.
``BUILD_ID <result-var>``
.. versionadded:: 3.15
Store in the ``<result-var>`` variable the ID assigned to this build by
CDash.
``HTTPHEADER <HTTP-header>``
.. versionadded:: 3.9
Specify HTTP header to be included in the request to CDash during submission.
For example, CDash can be configured to only accept submissions from
authenticated clients. In this case, you should provide a bearer token in your
header:
.. code-block:: cmake
ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
This suboption can be repeated several times for multiple headers.
``RETRY_COUNT <count>``
Specify how many times to retry a timed-out submission.
``RETRY_DELAY <delay>``
Specify how long (in seconds) to wait after a timed-out submission
before attempting to re-submit.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` for success and
non-zero on failure.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.13
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
.. versionadded:: 3.3
Suppress all non-error messages that would have otherwise been
printed to the console.
Submit to CDash Upload API
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.2
.. code-block:: cmake
ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
[SUBMIT_URL <url>]
[BUILD_ID <result-var>]
[HTTPHEADER <header>]
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
[RETURN_VALUE <result-var>]
[QUIET])
This second signature is used to upload files to CDash via the CDash
file upload API. The API first sends a request to upload to CDash along
with a content hash of the file. If CDash does not already have the file,
then it is uploaded. Along with the file, a CDash type string is specified
to tell CDash which handler to use to process the data.
This signature interprets options in the same way as the first one.
.. versionadded:: 3.8
Added the ``RETRY_COUNT``, ``RETRY_DELAY``, ``QUIET`` options.
.. versionadded:: 3.9
Added the ``HTTPHEADER`` option.
.. versionadded:: 3.13
Added the ``RETURN_VALUE`` option.
.. versionadded:: 3.14
Added the ``SUBMIT_URL`` option.
.. versionadded:: 3.15
Added the ``BUILD_ID`` option.

312
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_test.rst Normal file
View File

@ -0,0 +1,312 @@
ctest_test
----------
Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_test([BUILD <build-dir>] [APPEND]
[START <start-number>]
[END <end-number>]
[STRIDE <stride-number>]
[EXCLUDE <exclude-regex>]
[INCLUDE <include-regex>]
[EXCLUDE_LABEL <label-exclude-regex>]
[INCLUDE_LABEL <label-include-regex>]
[EXCLUDE_FIXTURE <regex>]
[EXCLUDE_FIXTURE_SETUP <regex>]
[EXCLUDE_FIXTURE_CLEANUP <regex>]
[PARALLEL_LEVEL <level>]
[RESOURCE_SPEC_FILE <file>]
[TEST_LOAD <threshold>]
[SCHEDULE_RANDOM <ON|OFF>]
[STOP_ON_FAILURE]
[STOP_TIME <time-of-day>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[REPEAT <mode>:<n>]
[OUTPUT_JUNIT <file>]
[QUIET]
)
..
NOTE If updating the argument list here, please also update the argument
list documentation for :command:`ctest_memcheck` as well.
Run tests in the project build tree and store results in
``Test.xml`` for submission with the :command:`ctest_submit` command.
The options are:
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
``APPEND``
Mark ``Test.xml`` for append to results previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
This does *not* cause results to be appended to a ``.xml`` file
produced by a previous call to this command.
``START <start-number>``
Specify the beginning of a range of test numbers.
``END <end-number>``
Specify the end of a range of test numbers.
``STRIDE <stride-number>``
Specify the stride by which to step across a range of test numbers.
``EXCLUDE <exclude-regex>``
Specify a regular expression matching test names to exclude.
``INCLUDE <include-regex>``
Specify a regular expression matching test names to include.
Tests not matching this expression are excluded.
``EXCLUDE_LABEL <label-exclude-regex>``
Specify a regular expression matching test labels to exclude.
``INCLUDE_LABEL <label-include-regex>``
Specify a regular expression matching test labels to include.
Tests not matching this expression are excluded.
``EXCLUDE_FIXTURE <regex>``
.. versionadded:: 3.7
If a test in the set of tests to be executed requires a particular fixture,
that fixture's setup and cleanup tests would normally be added to the test
set automatically. This option prevents adding setup or cleanup tests for
fixtures matching the ``<regex>``. Note that all other fixture behavior is
retained, including test dependencies and skipping tests that have fixture
setup tests that fail.
``EXCLUDE_FIXTURE_SETUP <regex>``
.. versionadded:: 3.7
Same as ``EXCLUDE_FIXTURE`` except only matching setup tests are excluded.
``EXCLUDE_FIXTURE_CLEANUP <regex>``
.. versionadded:: 3.7
Same as ``EXCLUDE_FIXTURE`` except only matching cleanup tests are excluded.
``PARALLEL_LEVEL <level>``
Specify a positive number representing the number of tests to
be run in parallel.
``RESOURCE_SPEC_FILE <file>``
.. versionadded:: 3.16
Specify a
:ref:`resource specification file <ctest-resource-specification-file>`. See
:ref:`ctest-resource-allocation` for more information.
``TEST_LOAD <threshold>``
.. versionadded:: 3.4
While running tests in parallel, try not to start tests when they
may cause the CPU load to pass above a given threshold. If not
specified the :variable:`CTEST_TEST_LOAD` variable will be checked,
and then the :option:`--test-load <ctest --test-load>` command-line
argument to :manual:`ctest(1)`. See also the ``TestLoad`` setting
in the :ref:`CTest Test Step`.
``REPEAT <mode>:<n>``
.. versionadded:: 3.17
Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times.
The modes are:
``UNTIL_FAIL``
Require each test to run ``<n>`` times without failing in order to pass.
This is useful in finding sporadic failures in test cases.
``UNTIL_PASS``
Allow each test to run up to ``<n>`` times in order to pass.
Repeats tests if they fail for any reason.
This is useful in tolerating sporadic failures in test cases.
``AFTER_TIMEOUT``
Allow each test to run up to ``<n>`` times in order to pass.
Repeats tests only if they timeout.
This is useful in tolerating sporadic timeouts in test cases
on busy machines.
``SCHEDULE_RANDOM <ON|OFF>``
Launch tests in a random order. This may be useful for detecting
implicit test dependencies.
``STOP_ON_FAILURE``
.. versionadded:: 3.18
Stop the execution of the tests once one has failed.
``STOP_TIME <time-of-day>``
Specify a time of day at which the tests should all stop running.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` if all tests passed.
Store non-zero if anything went wrong.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.7
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``OUTPUT_JUNIT <file>``
.. versionadded:: 3.21
Write test results to ``<file>`` in JUnit XML format. If ``<file>`` is a
relative path, it will be placed in the build directory. If ``<file>``
already exists, it will be overwritten. Note that the resulting JUnit XML
file is **not** uploaded to CDash because it would be redundant with
CTest's ``Test.xml`` file.
``QUIET``
.. versionadded:: 3.3
Suppress any CTest-specific non-error messages that would have otherwise
been printed to the console. Output from the underlying test command is not
affected. Summary info detailing the percentage of passing tests is also
unaffected by the ``QUIET`` option.
See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`,
:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and
:variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables, along with their
corresponding :manual:`ctest(1)` command line options
:option:`--test-output-size-passed <ctest --test-output-size-passed>`,
:option:`--test-output-size-failed <ctest --test-output-size-failed>`, and
:option:`--test-output-truncation <ctest --test-output-truncation>`.
.. _`Additional Test Measurements`:
Additional Test Measurements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
CTest can parse the output of your tests for extra measurements to report
to CDash.
When run as a :ref:`Dashboard Client`, CTest will include these custom
measurements in the ``Test.xml`` file that gets uploaded to CDash.
Check the `CDash test measurement documentation
<https://github.com/Kitware/CDash/blob/master/docs/test_measurements.md>`_
for more information on the types of test measurements that CDash recognizes.
.. versionadded: 3.22
CTest can parse custom measurements from tags named
``<CTestMeasurement>`` or ``<CTestMeasurementFile>``. The older names
``<DartMeasurement>`` and ``<DartMeasurementFile>`` are still supported.
The following example demonstrates how to output a variety of custom test
measurements.
.. code-block:: c++
std::cout <<
"<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>"
<< std::endl;
std::cout <<
"<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>"
<< std::endl;
std::cout <<
"<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</CTestMeasurement>"
<< std::endl;
std::cout <<
"<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" <<
"line 1.\n" <<
" \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" <<
"line 3. Not bold or indented...\n" <<
"</CTestMeasurement>" << std::endl;
Image Measurements
""""""""""""""""""
The following example demonstrates how to upload test images to CDash.
.. code-block:: c++
std::cout <<
"<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" <<
"/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl;
std::cout <<
"<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" <<
"/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl;
std::cout <<
"<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\">" <<
"/dir/to/img.png</CTestMeasurementFile>"
<< std::endl;
Images will be displayed together in an interactive comparison mode on CDash
if they are provided with two or more of the following names.
* ``TestImage``
* ``ValidImage``
* ``BaselineImage``
* ``DifferenceImage2``
By convention, ``TestImage`` is the image generated by your test, and
``ValidImage`` (or ``BaselineImage``) is basis of comparison used to determine
if the test passed or failed.
If another image name is used it will be displayed by CDash as a static image
separate from the interactive comparison UI.
Attached Files
""""""""""""""
.. versionadded:: 3.21
The following example demonstrates how to upload non-image files to CDash.
.. code-block:: c++
std::cout <<
"<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" <<
"/dir/to/data1.csv</CTestMeasurementFile>\n" <<
"<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" <<
"/dir/to/data2.csv</CTestMeasurementFile>" << std::endl;
If the name of the file to upload is known at configure time, you can use the
:prop_test:`ATTACHED_FILES` or :prop_test:`ATTACHED_FILES_ON_FAIL` test
properties instead.
Custom Details
""""""""""""""
.. versionadded:: 3.21
The following example demonstrates how to specify a custom value for the
``Test Details`` field displayed on CDash.
.. code-block:: c++
std::cout <<
"<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl;
.. _`Additional Labels`:
Additional Labels
"""""""""""""""""
.. versionadded:: 3.22
The following example demonstrates how to add additional labels to a test
at runtime.
.. code-block:: c++
std::cout <<
"<CTestLabel>Custom Label 1</CTestLabel>\n" <<
"<CTestLabel>Custom Label 2</CTestLabel>" << std::endl;
Use the :prop_test:`LABELS` test property instead for labels that can be
determined at configure time.

43
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_update.rst Normal file
View File

@ -0,0 +1,43 @@
ctest_update
------------
Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_update([SOURCE <source-dir>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[QUIET])
Update the source tree from version control and record results in
``Update.xml`` for submission with the :command:`ctest_submit` command.
The options are:
``SOURCE <source-dir>``
Specify the source directory. If not given, the
:variable:`CTEST_SOURCE_DIRECTORY` variable is used.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable the number of files
updated or ``-1`` on error.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.13
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
.. versionadded:: 3.3
Tell CTest to suppress most non-error messages that it would
have otherwise printed to the console. CTest will still report
the new revision of the repository and any conflicting files
that were found.
The update always follows the version control branch currently checked
out in the source directory. See the :ref:`CTest Update Step`
documentation for information about variables that change the behavior
of ``ctest_update()``.

26
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/ctest_upload.rst Normal file
View File

@ -0,0 +1,26 @@
ctest_upload
------------
Upload files to a dashboard server as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
The options are:
``FILES <file>...``
Specify a list of files to be sent along with the build results to the
dashboard server.
``QUIET``
.. versionadded:: 3.3
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.7
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.

81
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/define_property.rst Normal file
View File

@ -0,0 +1,81 @@
define_property
---------------
Define and document custom properties.
.. code-block:: cmake
define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
TEST | VARIABLE | CACHED_VARIABLE>
PROPERTY <name> [INHERITED]
[BRIEF_DOCS <brief-doc> [docs...]]
[FULL_DOCS <full-doc> [docs...]]
[INITIALIZE_FROM_VARIABLE <variable>])
Defines one property in a scope for use with the :command:`set_property` and
:command:`get_property` commands. It is mainly useful for defining the way
a property is initialized or inherited. Historically, the command also
associated documentation with a property, but that is no longer considered a
primary use case.
The first argument determines the kind of scope in which the property should
be used. It must be one of the following:
::
GLOBAL = associated with the global namespace
DIRECTORY = associated with one directory
TARGET = associated with one target
SOURCE = associated with one source file
TEST = associated with a test named with add_test
VARIABLE = documents a CMake language variable
CACHED_VARIABLE = documents a CMake cache variable
Note that unlike :command:`set_property` and :command:`get_property` no
actual scope needs to be given; only the kind of scope is important.
The required ``PROPERTY`` option is immediately followed by the name of
the property being defined.
If the ``INHERITED`` option is given, then the :command:`get_property` command
will chain up to the next higher scope when the requested property is not set
in the scope given to the command.
* ``DIRECTORY`` scope chains to its parent directory's scope, continuing the
walk up parent directories until a directory has the property set or there
are no more parents. If still not found at the top level directory, it
chains to the ``GLOBAL`` scope.
* ``TARGET``, ``SOURCE`` and ``TEST`` properties chain to ``DIRECTORY`` scope,
including further chaining up the directories, etc. as needed.
Note that this scope chaining behavior only applies to calls to
:command:`get_property`, :command:`get_directory_property`,
:command:`get_target_property`, :command:`get_source_file_property` and
:command:`get_test_property`. There is no inheriting behavior when *setting*
properties, so using ``APPEND`` or ``APPEND_STRING`` with the
:command:`set_property` command will not consider inherited values when working
out the contents to append to.
The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be
associated with the property as its brief and full documentation.
CMake does not use this documentation other than making it available to the
project via corresponding options to the :command:`get_property` command.
.. versionchanged:: 3.23
The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are optional.
.. versionadded:: 3.23
The ``INITIALIZE_FROM_VARIABLE`` option specifies a variable from which the
property should be initialized. It can only be used with target properties.
The ``<variable>`` name must end with the property name and must not begin
with ``CMAKE_`` or ``_CMAKE_``. The property name must contain at least one
underscore. It is recommended that the property name have a prefix specific
to the project.
See Also
^^^^^^^^
* :command:`get_property`
* :command:`set_property`

10
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/else.rst Normal file
View File

@ -0,0 +1,10 @@
else
----
Starts the else portion of an if block.
.. code-block:: cmake
else([<condition>])
See the :command:`if` command.

11
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/elseif.rst Normal file
View File

@ -0,0 +1,11 @@
elseif
------
Starts an elseif portion of an if block.
.. code-block:: cmake
elseif(<condition>)
See the :command:`if` command, especially for the syntax and logic
of the ``<condition>``.

24
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/enable_language.rst Normal file
View File

@ -0,0 +1,24 @@
enable_language
---------------
Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc)
.. code-block:: cmake
enable_language(<lang>... [OPTIONAL])
Enables support for the named languages in CMake. This is the same as
the :command:`project` command but does not create any of the extra
variables that are created by the project command.
.. include:: SUPPORTED_LANGUAGES.txt
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or
indirectly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The ``OPTIONAL`` keyword is a placeholder for future implementation and
does not currently work. Instead you can use the :module:`CheckLanguage`
module to verify support before enabling.

20
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/enable_testing.rst Normal file
View File

@ -0,0 +1,20 @@
enable_testing
--------------
Enable testing for current directory and below.
.. code-block:: cmake
enable_testing()
Enables testing for this directory and below.
This command should be in the source directory root
because ctest expects to find a test file in the build
directory root.
This command is automatically invoked when the :module:`CTest`
module is included, except if the ``BUILD_TESTING`` option is
turned off.
See also the :command:`add_test` command.

11
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/endblock.rst Normal file
View File

@ -0,0 +1,11 @@
endblock
--------
.. versionadded:: 3.25
Ends a list of commands in a :command:`block` and removes the scopes
created by the :command:`block` command.
.. code-block:: cmake
endblock()

14
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/endforeach.rst Normal file
View File

@ -0,0 +1,14 @@
endforeach
----------
Ends a list of commands in a foreach block.
.. code-block:: cmake
endforeach([<loop_var>])
See the :command:`foreach` command.
The optional ``<loop_var>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<loop_var>`` argument of
the opening ``foreach`` clause.

14
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/endfunction.rst Normal file
View File

@ -0,0 +1,14 @@
endfunction
-----------
Ends a list of commands in a function block.
.. code-block:: cmake
endfunction([<name>])
See the :command:`function` command.
The optional ``<name>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<name>`` argument
of the opening ``function`` command.

14
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/endif.rst Normal file
View File

@ -0,0 +1,14 @@
endif
-----
Ends a list of commands in an if block.
.. code-block:: cmake
endif([<condition>])
See the :command:`if` command.
The optional ``<condition>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
``if`` clause.

14
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/endmacro.rst Normal file
View File

@ -0,0 +1,14 @@
endmacro
--------
Ends a list of commands in a macro block.
.. code-block:: cmake
endmacro([<name>])
See the :command:`macro` command.
The optional ``<name>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<name>`` argument
of the opening ``macro`` command.

14
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/endwhile.rst Normal file
View File

@ -0,0 +1,14 @@
endwhile
--------
Ends a list of commands in a while block.
.. code-block:: cmake
endwhile([<condition>])
See the :command:`while` command.
The optional ``<condition>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
``while`` clause.

26
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/exec_program.rst Normal file
View File

@ -0,0 +1,26 @@
exec_program
------------
.. deprecated:: 3.0
Use the :command:`execute_process` command instead.
Run an executable program during the processing of the CMakeList.txt
file.
.. code-block:: cmake
exec_program(Executable [directory in which to run]
[ARGS <arguments to executable>]
[OUTPUT_VARIABLE <var>]
[RETURN_VALUE <var>])
The executable is run in the optionally specified directory. The
executable can include arguments if it is double quoted, but it is
better to use the optional ``ARGS`` argument to specify arguments to the
program. This is because cmake will then be able to escape spaces in
the executable path. An optional argument ``OUTPUT_VARIABLE`` specifies a
variable in which to store the output. To capture the return value of
the execution, provide a ``RETURN_VALUE``. If ``OUTPUT_VARIABLE`` is
specified, then no output will go to the stdout/stderr of the console
running cmake.

171
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/execute_process.rst Normal file
View File

@ -0,0 +1,171 @@
execute_process
---------------
Execute one or more child processes.
.. code-block:: cmake
execute_process(COMMAND <cmd1> [<arguments>]
[COMMAND <cmd2> [<arguments>]]...
[WORKING_DIRECTORY <directory>]
[TIMEOUT <seconds>]
[RESULT_VARIABLE <variable>]
[RESULTS_VARIABLE <variable>]
[OUTPUT_VARIABLE <variable>]
[ERROR_VARIABLE <variable>]
[INPUT_FILE <file>]
[OUTPUT_FILE <file>]
[ERROR_FILE <file>]
[OUTPUT_QUIET]
[ERROR_QUIET]
[COMMAND_ECHO <where>]
[OUTPUT_STRIP_TRAILING_WHITESPACE]
[ERROR_STRIP_TRAILING_WHITESPACE]
[ENCODING <name>]
[ECHO_OUTPUT_VARIABLE]
[ECHO_ERROR_VARIABLE]
[COMMAND_ERROR_IS_FATAL <ANY|LAST>])
Runs the given sequence of one or more commands.
Commands are executed concurrently as a pipeline, with the standard
output of each process piped to the standard input of the next.
A single standard error pipe is used for all processes.
``execute_process`` runs commands while CMake is configuring the project,
prior to build system generation. Use the :command:`add_custom_target` and
:command:`add_custom_command` commands to create custom commands that run
at build time.
Options:
``COMMAND``
A child process command line.
CMake executes the child process using operating system APIs directly:
* On POSIX platforms, the command line is passed to the
child process in an ``argv[]`` style array.
* On Windows platforms, the command line is encoded as a string such
that child processes using ``CommandLineToArgvW`` will decode the
original arguments.
No intermediate shell is used, so shell operators such as ``>``
are treated as normal arguments.
(Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to
redirect stdin, stdout, and stderr.)
For **sequential execution** of multiple commands use multiple
``execute_process`` calls each with a single ``COMMAND`` argument.
``WORKING_DIRECTORY``
The named directory will be set as the current working directory of
the child processes.
``TIMEOUT``
After the specified number of seconds (fractions allowed), all unfinished
child processes will be terminated, and the ``RESULT_VARIABLE`` will be
set to a string mentioning the "timeout".
``RESULT_VARIABLE``
The variable will be set to contain the result of last child process.
This will be an integer return code from the last child or a string
describing an error condition.
``RESULTS_VARIABLE <variable>``
.. versionadded:: 3.10
The variable will be set to contain the result of all processes as a
:ref:`semicolon-separated list <CMake Language Lists>`, in order of the
given ``COMMAND`` arguments. Each entry will be an integer return code
from the corresponding child or a string describing an error condition.
``INPUT_FILE <file>``
``<file>`` is attached to the standard input pipe of the *first* ``COMMAND``
process.
``OUTPUT_FILE <file>``
``<file>`` is attached to the standard output pipe of the *last* ``COMMAND``
process.
``ERROR_FILE <file>``
``<file>`` is attached to the standard error pipe of *all* ``COMMAND``
processes.
.. versionadded:: 3.3
If the same ``<file>`` is named for both ``OUTPUT_FILE`` and ``ERROR_FILE``
then it will be used for both standard output and standard error pipes.
``OUTPUT_QUIET``, ``ERROR_QUIET``
The standard output on ``OUTPUT_VARIABLE`` or standard error on
``ERROR_VARIABLE`` are not connected (no variable content).
The ``*_FILE`` and ``ECHO_*_VARIABLE`` options are not affected.
``OUTPUT_VARIABLE``, ``ERROR_VARIABLE``
The variable named will be set with the contents of the standard output
and standard error pipes, respectively. If the same variable is named
for both pipes their output will be merged in the order produced.
``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
.. versionadded:: 3.18
The standard output or standard error will not be exclusively redirected to
the specified variables.
The output will be duplicated into the specified variables and also onto
standard output or standard error analogous to the ``tee`` Unix command.
.. note::
If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
same pipe the precedence is *not specified*.
If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will
be shared with the corresponding pipes of the CMake process itself.
``COMMAND_ECHO <where>``
.. versionadded:: 3.15
The command being run will be echo'ed to ``<where>`` with ``<where>``
being set to one of ``STDERR``, ``STDOUT`` or ``NONE``.
See the :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable for a way
to control the default behavior when this option is not present.
``ENCODING <name>``
.. versionadded:: 3.8
On Windows, the encoding that is used to decode output from the process.
Ignored on other platforms.
Valid encoding names are:
``NONE``
Perform no decoding. This assumes that the process output is encoded
in the same way as CMake's internal encoding (UTF-8).
This is the default.
``AUTO``
Use the current active console's codepage or if that isn't
available then use ANSI.
``ANSI``
Use the ANSI codepage.
``OEM``
Use the original equipment manufacturer (OEM) code page.
``UTF8`` or ``UTF-8``
Use the UTF-8 codepage.
.. versionadded:: 3.11
Accept ``UTF-8`` spelling for consistency with the
`UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention.
``COMMAND_ERROR_IS_FATAL <ANY|LAST>``
.. versionadded:: 3.19
The option following ``COMMAND_ERROR_IS_FATAL`` determines the behavior when
an error is encountered:
``ANY``
If any of the commands in the list of commands fail, the
``execute_process()`` command halts with an error.
``LAST``
If the last command in the list of commands fails, the
``execute_process()`` command halts with an error. Commands earlier in the
list will not cause a fatal error.

154
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/export.rst Normal file
View File

@ -0,0 +1,154 @@
export
------
Export targets or packages for outside projects to use them directly
from the current project's build tree, without installation.
See the :command:`install(EXPORT)` command to export targets from an
install tree.
Synopsis
^^^^^^^^
.. parsed-literal::
export(`TARGETS`_ <target>... [...])
export(`EXPORT`_ <export-name> [...])
export(`PACKAGE`_ <PackageName>)
Exporting Targets
^^^^^^^^^^^^^^^^^
.. _`export(TARGETS)`:
.. _TARGETS:
.. code-block:: cmake
export(TARGETS <target>... [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]
[CXX_MODULES_DIRECTORY <directory>])
Creates a file ``<filename>`` that may be included by outside projects to
import targets named by ``<target>...`` from the current project's build tree.
This is useful during cross-compiling to build utility executables that can
run on the host platform in one project and then import them into another
project being compiled for the target platform.
The file created by this command is specific to the build tree and
should never be installed. See the :command:`install(EXPORT)` command to
export targets from an install tree.
The options are:
``NAMESPACE <namespace>``
Prepend the ``<namespace>`` string to all target names written to the file.
``APPEND``
Append to the file instead of overwriting it. This can be used to
incrementally export multiple targets to the same file.
``EXPORT_LINK_INTERFACE_LIBRARIES``
Include the contents of the properties named with the pattern
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``
in the export, even when policy :policy:`CMP0022` is NEW. This is useful
to support consumers using CMake versions older than 2.8.12.
``CXX_MODULES_DIRECTORY <directory>``
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Export C++ module properties to files under the given directory. Each file
will be named according to the target's export name (without any namespace).
These files will automatically be included from the export file.
This signature requires all targets to be listed explicitly. If a library
target is included in the export, but a target to which it links is not
included, the behavior is unspecified. See the `export(EXPORT)`_ signature
to automatically export the same targets from the build tree as
:command:`install(EXPORT)` would from an install tree.
.. note::
:ref:`Object Libraries` under :generator:`Xcode` have special handling if
multiple architectures are listed in :variable:`CMAKE_OSX_ARCHITECTURES`.
In this case they will be exported as :ref:`Interface Libraries` with
no object files available to clients. This is sufficient to satisfy
transitive usage requirements of other targets that link to the
object libraries in their implementation.
This command exports all :ref:`build configurations` from the build tree.
See the :variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` variable to map
configurations of dependent projects to the exported configurations.
Exporting Targets to Android.mk
"""""""""""""""""""""""""""""""
.. code-block:: cmake
export(TARGETS <target>... ANDROID_MK <filename>)
.. versionadded:: 3.7
This signature exports cmake built targets to the android ndk build system
by creating an ``Android.mk`` file that references the prebuilt targets. The
Android NDK supports the use of prebuilt libraries, both static and shared.
This allows cmake to build the libraries of a project and make them available
to an ndk build system complete with transitive dependencies, include flags
and defines required to use the libraries. The signature takes a list of
targets and puts them in the ``Android.mk`` file specified by the
``<filename>`` given. This signature can only be used if policy
:policy:`CMP0022` is NEW for all targets given. A error will be issued if
that policy is set to OLD for one of the targets.
Exporting Targets matching install(EXPORT)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _`export(EXPORT)`:
.. _EXPORT:
.. code-block:: cmake
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]
[CXX_MODULES_DIRECTORY <directory>])
Creates a file ``<filename>`` that may be included by outside projects to
import targets from the current project's build tree. This is the same
as the `export(TARGETS)`_ signature, except that the targets are not
explicitly listed. Instead, it exports the targets associated with
the installation export ``<export-name>``. Target installations may be
associated with the export ``<export-name>`` using the ``EXPORT`` option
of the :command:`install(TARGETS)` command.
Exporting Packages
^^^^^^^^^^^^^^^^^^
.. _`export(PACKAGE)`:
.. _PACKAGE:
.. code-block:: cmake
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package ``<PackageName>``. The :command:`find_package` command may consider the
directory while searching for package ``<PackageName>``. This helps dependent
projects find and use a package from the current project's build tree
without help from the user. Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (``<PackageName>Config.cmake``) that works with the
build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package
registry.
.. versionchanged:: 3.1
If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable
is enabled, the ``export(PACKAGE)`` command will do nothing.
.. versionchanged:: 3.15
By default the ``export(PACKAGE)`` command does nothing (see policy
:policy:`CMP0090`) because populating the user package registry has effects
outside the source and build trees. Set the
:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories
to the CMake user package registry.

28
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/export_library_dependencies.rst Normal file
View File

@ -0,0 +1,28 @@
export_library_dependencies
---------------------------
Disallowed since version 3.0. See CMake Policy :policy:`CMP0033`.
Use :command:`install(EXPORT)` or :command:`export` command.
This command generates an old-style library dependencies file.
Projects requiring CMake 2.6 or later should not use the command. Use
instead the :command:`install(EXPORT)` command to help export targets from an
installation tree and the :command:`export` command to export targets from a
build tree.
The old-style library dependencies file does not take into account
per-configuration names of libraries or the
:prop_tgt:`LINK_INTERFACE_LIBRARIES` target property.
.. code-block:: cmake
export_library_dependencies(<file> [APPEND])
Create a file named ``<file>`` that can be included into a CMake listfile
with the INCLUDE command. The file will contain a number of SET
commands that will set all the variables needed for library dependency
information. This should be the last command in the top level
CMakeLists.txt file of the project. If the ``APPEND`` option is
specified, the SET commands will be appended to the given file instead
of replacing it.

1251
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/file.rst Normal file
View File

File diff suppressed because it is too large Load Diff

46
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/find_file.rst Normal file
View File

@ -0,0 +1,46 @@
find_file
---------
.. |FIND_XXX| replace:: find_file
.. |NAMES| replace:: NAMES name1 [name2 ...]
.. |SEARCH_XXX| replace:: full path to a file
.. |SEARCH_XXX_DESC| replace:: full path to named file
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_INCLUDE_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
:variable:`CMAKE_SYSTEM_INCLUDE_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
:variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
:variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
.. include:: FIND_XXX.txt

90
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/find_library.rst Normal file
View File

@ -0,0 +1,90 @@
find_library
------------
.. |FIND_XXX| replace:: find_library
.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
.. |SEARCH_XXX| replace:: library
.. |SEARCH_XXX_DESC| replace:: library
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/lib``
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_LIBRARY_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``LIB``
and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
:variable:`CMAKE_SYSTEM_LIBRARY_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
:variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
:variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY`
.. include:: FIND_XXX.txt
When more than one value is given to the ``NAMES`` option this command by
default will consider one name at a time and search every directory
for it. The ``NAMES_PER_DIR`` option tells this command to consider one
directory at a time and search for all names in it.
Each library name given to the ``NAMES`` option is first considered
as a library file name and then considered with platform-specific
prefixes (e.g. ``lib``) and suffixes (e.g. ``.so``). Therefore one
may specify library file names such as ``libfoo.a`` directly.
This can be used to locate static libraries on UNIX-like systems.
If the library found is a framework, then ``<VAR>`` will be set to the full
path to the framework ``<fullPath>/A.framework``. When a full path to a
framework is used as a library, CMake will use a ``-framework A``, and a
``-F<fullPath>`` to link the framework to the target.
If the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable is set all
search paths will be tested as normal, with the suffix appended, and with
all matches of ``lib/`` replaced with
``lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/``. This variable overrides
the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS`,
:prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS`,
and :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global properties.
If the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global property is set
all search paths will be tested as normal, with ``32/`` appended, and
with all matches of ``lib/`` replaced with ``lib32/``. This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.
If the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property is set
all search paths will be tested as normal, with ``x32/`` appended, and
with all matches of ``lib/`` replaced with ``libx32/``. This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.
If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set
all search paths will be tested as normal, with ``64/`` appended, and
with all matches of ``lib/`` replaced with ``lib64/``. This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.

729
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/find_package.rst Normal file
View File

@ -0,0 +1,729 @@
find_package
------------
.. |FIND_XXX| replace:: find_package
.. |FIND_ARGS_XXX| replace:: <PackageName>
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
:variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
.. only:: html
.. contents::
.. note:: The :guide:`Using Dependencies Guide` provides a high-level
introduction to this general topic. It provides a broader overview of
where the ``find_package()`` command fits into the bigger picture,
including its relationship to the :module:`FetchContent` module.
The guide is recommended pre-reading before moving on to the details below.
Find a package (usually provided by something external to the project),
and load its package-specific details. Calls to this command can also
be intercepted by :ref:`dependency providers <dependency_providers>`.
Search Modes
^^^^^^^^^^^^
The command has a few modes by which it searches for packages:
**Module mode**
In this mode, CMake searches for a file called ``Find<PackageName>.cmake``,
looking first in the locations listed in the :variable:`CMAKE_MODULE_PATH`,
then among the :ref:`Find Modules` provided by the CMake installation.
If the file is found, it is read and processed by CMake. It is responsible
for finding the package, checking the version, and producing any needed
messages. Some Find modules provide limited or no support for versioning;
check the Find module's documentation.
The ``Find<PackageName>.cmake`` file is not typically provided by the
package itself. Rather, it is normally provided by something external to
the package, such as the operating system, CMake itself, or even the project
from which the ``find_package()`` command was called. Being externally
provided, :ref:`Find Modules` tend to be heuristic in nature and are
susceptible to becoming out-of-date. They typically search for certain
libraries, files and other package artifacts.
Module mode is only supported by the
:ref:`basic command signature <Basic Signature>`.
**Config mode**
In this mode, CMake searches for a file called
``<lowercasePackageName>-config.cmake`` or ``<PackageName>Config.cmake``.
It will also look for ``<lowercasePackageName>-config-version.cmake`` or
``<PackageName>ConfigVersion.cmake`` if version details were specified
(see :ref:`version selection` for an explanation of how these separate
version files are used).
In config mode, the command can be given a list of names to search for
as package names. The locations where CMake searches for the config and
version files is considerably more complicated than for Module mode
(see :ref:`search procedure`).
The config and version files are typically installed as part of the
package, so they tend to be more reliable than Find modules. They usually
contain direct knowledge of the package contents, so no searching or
heuristics are needed within the config or version files themselves.
Config mode is supported by both the :ref:`basic <Basic Signature>` and
:ref:`full <Full Signature>` command signatures.
**FetchContent redirection mode**
.. versionadded:: 3.24
A call to ``find_package()`` can be redirected internally to a package
provided by the :module:`FetchContent` module. To the caller, the behavior
will appear similar to Config mode, except that the search logic is
by-passed and the component information is not used. See
:command:`FetchContent_Declare` and :command:`FetchContent_MakeAvailable`
for further details.
When not redirected to a package provided by :module:`FetchContent`, the
command arguments determine whether Module or Config mode is used. When the
`basic signature`_ is used, the command searches in Module mode first.
If the package is not found, the search falls back to Config mode.
A user may set the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable
to true to reverse the priority and direct CMake to search using Config mode
first before falling back to Module mode. The basic signature can also be
forced to use only Module mode with a ``MODULE`` keyword. If the
`full signature`_ is used, the command only searches in Config mode.
Where possible, user code should generally look for packages using the
`basic signature`_, since that allows the package to be found with any mode.
Project maintainers wishing to provide a config package should understand
the bigger picture, as explained in :ref:`Full Signature` and all subsequent
sections on this page.
.. _`basic signature`:
Basic Signature
^^^^^^^^^^^^^^^
.. parsed-literal::
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
[REQUIRED] [[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
[GLOBAL]
[NO_POLICY_SCOPE]
[BYPASS_PROVIDER])
The basic signature is supported by both Module and Config modes.
The ``MODULE`` keyword implies that only Module mode can be used to find
the package, with no fallback to Config mode.
Regardless of the mode used, a ``<PackageName>_FOUND`` variable will be
set to indicate whether the package was found. When the package is found,
package-specific information may be provided through other variables and
:ref:`Imported Targets` documented by the package itself. The
``QUIET`` option disables informational messages, including those indicating
that the package cannot be found if it is not ``REQUIRED``. The ``REQUIRED``
option stops processing with an error message if the package cannot be found.
A package-specific list of required components may be listed after the
``COMPONENTS`` keyword. If any of these components are not able to be
satisfied, the package overall is considered to be not found. If the
``REQUIRED`` option is also present, this is treated as a fatal error,
otherwise execution still continues. As a form of shorthand, if the
``REQUIRED`` option is present, the ``COMPONENTS`` keyword can be omitted
and the required components can be listed directly after ``REQUIRED``.
Additional optional components may be listed after
``OPTIONAL_COMPONENTS``. If these cannot be satisfied, the package overall
can still be considered found, as long as all required components are
satisfied.
The set of available components and their meaning are defined by the
target package. Formally, it is up to the target package how to
interpret the component information given to it, but it should follow
the expectations stated above. For calls where no components are specified,
there is no single expected behavior and target packages should clearly
define what occurs in such cases. Common arrangements include assuming it
should find all components, no components or some well-defined subset of the
available components.
.. versionadded:: 3.24
The ``REGISTRY_VIEW`` keyword specifies which registry views should be
queried. This keyword is only meaningful on ``Windows`` platforms and will
be ignored on all others. Formally, it is up to the target package how to
interpret the registry view information given to it.
.. versionadded:: 3.24
Specifying the ``GLOBAL`` keyword will promote all imported targets to
a global scope in the importing project. Alternatively, this functionality
can be enabled by setting the :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL`
variable.
.. _FIND_PACKAGE_VERSION_FORMAT:
The ``[version]`` argument requests a version with which the package found
should be compatible. There are two possible forms in which it may be
specified:
* A single version with the format ``major[.minor[.patch[.tweak]]]``, where
each component is a numeric value.
* A version range with the format ``versionMin...[<]versionMax`` where
``versionMin`` and ``versionMax`` have the same format and constraints
on components being integers as the single version. By default, both end
points are included. By specifying ``<``, the upper end point will be
excluded. Version ranges are only supported with CMake 3.19 or later.
The ``EXACT`` option requests that the version be matched exactly. This option
is incompatible with the specification of a version range.
If no ``[version]`` and/or component list is given to a recursive invocation
inside a find-module, the corresponding arguments are forwarded
automatically from the outer call (including the ``EXACT`` flag for
``[version]``). Version support is currently provided only on a
package-by-package basis (see the `Version Selection`_ section below).
When a version range is specified but the package is only designed to expect
a single version, the package will ignore the upper end point of the range and
only take the single version at the lower end of the range into account.
See the :command:`cmake_policy` command documentation for discussion
of the ``NO_POLICY_SCOPE`` option.
.. versionadded:: 3.24
The ``BYPASS_PROVIDER`` keyword is only allowed when ``find_package()`` is
being called by a :ref:`dependency provider <dependency_providers>`.
It can be used by providers to call the built-in ``find_package()``
implementation directly and prevent that call from being re-routed back to
itself. Future versions of CMake may detect attempts to use this keyword
from places other than a dependency provider and halt with a fatal error.
.. _`full signature`:
Full Signature
^^^^^^^^^^^^^^
.. parsed-literal::
find_package(<PackageName> [version] [EXACT] [QUIET]
[REQUIRED] [[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[CONFIG|NO_MODULE]
[GLOBAL]
[NO_POLICY_SCOPE]
[BYPASS_PROVIDER]
[NAMES name1 [name2 ...]]
[CONFIGS config1 [config2 ...]]
[HINTS path1 [path2 ... ]]
[PATHS path1 [path2 ... ]]
[REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_PACKAGE_REGISTRY]
[NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
[NO_CMAKE_SYSTEM_PATH]
[NO_CMAKE_INSTALL_PREFIX]
[NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH])
The ``CONFIG`` option, the synonymous ``NO_MODULE`` option, or the use
of options not specified in the `basic signature`_ all enforce pure Config
mode. In pure Config mode, the command skips Module mode search and
proceeds at once with Config mode search.
Config mode search attempts to locate a configuration file provided by the
package to be found. A cache entry called ``<PackageName>_DIR`` is created to
hold the directory containing the file. By default, the command searches for
a package with the name ``<PackageName>``. If the ``NAMES`` option is given,
the names following it are used instead of ``<PackageName>``. The names are
also considered when determining whether to redirect the call to a package
provided by :module:`FetchContent`.
The command searches for a file called ``<PackageName>Config.cmake`` or
``<lowercasePackageName>-config.cmake`` for each name specified.
A replacement set of possible configuration file names may be given
using the ``CONFIGS`` option. The :ref:`search procedure` is specified below.
Once found, any :ref:`version constraint <version selection>` is checked,
and if satisfied, the configuration file is read and processed by CMake.
Since the file is provided by the package it already knows the
location of package contents. The full path to the configuration file
is stored in the cmake variable ``<PackageName>_CONFIG``.
All configuration files which have been considered by CMake while
searching for the package with an appropriate version are stored in the
``<PackageName>_CONSIDERED_CONFIGS`` variable, and the associated versions
in the ``<PackageName>_CONSIDERED_VERSIONS`` variable.
If the package configuration file cannot be found CMake will generate
an error describing the problem unless the ``QUIET`` argument is
specified. If ``REQUIRED`` is specified and the package is not found a
fatal error is generated and the configure step stops executing. If
``<PackageName>_DIR`` has been set to a directory not containing a
configuration file CMake will ignore it and search from scratch.
Package maintainers providing CMake package configuration files are
encouraged to name and install them such that the :ref:`search procedure`
outlined below will find them without requiring use of additional options.
.. _`search procedure`:
Config Mode Search Procedure
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
When Config mode is used, this search procedure is applied regardless of
whether the :ref:`full <full signature>` or :ref:`basic <basic signature>`
signature was given.
.. versionadded:: 3.24
All calls to ``find_package()`` (even in Module mode) first look for a config
package file in the :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` directory.
The :module:`FetchContent` module, or even the project itself, may write files
to that location to redirect ``find_package()`` calls to content already
provided by the project. If no config package file is found in that location,
the search proceeds with the logic described below.
CMake constructs a set of possible installation prefixes for the
package. Under each prefix several directories are searched for a
configuration file. The tables below show the directories searched.
Each entry is meant for installation trees following Windows (``W``), UNIX
(``U``), or Apple (``A``) conventions:
==================================================================== ==========
Entry Convention
==================================================================== ==========
``<prefix>/`` W
``<prefix>/(cmake|CMake)/`` W
``<prefix>/<name>*/`` W
``<prefix>/<name>*/(cmake|CMake)/`` W
``<prefix>/<name>*/(cmake|CMake)/<name>*/`` [#]_ W
``<prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/`` U
``<prefix>/(lib/<arch>|lib*|share)/<name>*/`` U
``<prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/`` U
``<prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/`` W/U
``<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/`` W/U
``<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/`` W/U
==================================================================== ==========
.. [#] .. versionadded:: 3.25
On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the
following directories are searched for Frameworks or Application Bundles
containing a configuration file:
=========================================================== ==========
Entry Convention
=========================================================== ==========
``<prefix>/<name>.framework/Resources/`` A
``<prefix>/<name>.framework/Resources/CMake/`` A
``<prefix>/<name>.framework/Versions/*/Resources/`` A
``<prefix>/<name>.framework/Versions/*/Resources/CMake/`` A
``<prefix>/<name>.app/Contents/Resources/`` A
``<prefix>/<name>.app/Contents/Resources/CMake/`` A
=========================================================== ==========
In all cases the ``<name>`` is treated as case-insensitive and corresponds
to any of the names specified (``<PackageName>`` or names given by ``NAMES``).
Paths with ``lib/<arch>`` are enabled if the
:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one
or more of the values ``lib64``, ``lib32``, ``libx32`` or ``lib`` (searched in
that order).
* Paths with ``lib64`` are searched on 64 bit platforms if the
:prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` property is set to ``TRUE``.
* Paths with ``lib32`` are searched on 32 bit platforms if the
:prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` property is set to ``TRUE``.
* Paths with ``libx32`` are searched on platforms using the x32 ABI
if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``.
* The ``lib`` path is always searched.
.. versionchanged:: 3.24
On ``Windows`` platform, it is possible to include registry queries as part
of the directories specified through ``HINTS`` and ``PATHS`` keywords, using
a :ref:`dedicated syntax <Find Using Windows Registry>`. Such specifications
will be ignored on all other platforms.
.. versionadded:: 3.24
``REGISTRY_VIEW`` can be specified to manage ``Windows`` registry queries
specified as part of ``PATHS`` and ``HINTS``.
.. include:: FIND_XXX_REGISTRY_VIEW.txt
If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each
(``W``) or (``U``) directory entry one-by-one.
This set of directories is intended to work in cooperation with
projects that provide configuration files in their installation trees.
Directories above marked with (``W``) are intended for installations on
Windows where the prefix may point at the top of an application's
installation directory. Those marked with (``U``) are intended for
installations on UNIX platforms where the prefix is shared by multiple
packages. This is merely a convention, so all (``W``) and (``U``) directories
are still searched on all platforms. Directories marked with (``A``) are
intended for installations on Apple platforms. The
:variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE`
variables determine the order of preference.
The set of installation prefixes is constructed using the following
steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are
enabled.
1. Search prefixes unique to the current ``<PackageName>`` being found.
See policy :policy:`CMP0074`.
.. versionadded:: 3.12
Specifically, search prefixes 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 within a find module, root paths from the parent's find
module will also be searched after paths for the current package.
This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.
2. Search paths specified in cmake-specific cache variables. These
are intended to be used on the command line with a :option:`-DVAR=VALUE <cmake -D>`.
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``:
* :variable:`CMAKE_PREFIX_PATH`
* :variable:`CMAKE_FRAMEWORK_PATH`
* :variable:`CMAKE_APPBUNDLE_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``:
* ``<PackageName>_DIR``
* :envvar:`CMAKE_PREFIX_PATH`
* :envvar:`CMAKE_FRAMEWORK_PATH`
* :envvar:`CMAKE_APPBUNDLE_PATH`
4. Search 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``. Path entries
ending in ``/bin`` or ``/sbin`` are automatically converted to their
parent directories:
* ``PATH``
6. Search paths stored in the CMake :ref:`User Package Registry`.
This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by
setting the variable :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`
to ``FALSE`` or the deprecated variable
:variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` to ``TRUE``.
See the :manual:`cmake-packages(7)` manual for details on the user
package registry.
7. Search cmake variables defined in the Platform files for the
current system. The searching of :variable:`CMAKE_INSTALL_PREFIX` and
:variable:`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``:
* :variable:`CMAKE_SYSTEM_PREFIX_PATH`
* :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
* :variable:`CMAKE_SYSTEM_APPBUNDLE_PATH`
The platform paths that these variables contain are locations that
typically include installed software. An example being ``/usr/local`` for
UNIX based platforms.
8. Search paths stored in the CMake :ref:`System Package Registry`.
This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed
or by setting the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`
variable to ``FALSE`` or the deprecated variable
:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``.
See the :manual:`cmake-packages(7)` manual for details on the system
package registry.
9. Search paths specified by the ``PATHS`` option. 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 the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable
various search locations.
.. include:: FIND_XXX_ROOT.txt
.. include:: FIND_XXX_ORDER.txt
By default the value stored in the result variable will be the path at
which the file is found. The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS`
variable may be set to ``TRUE`` before calling ``find_package`` in order
to resolve symbolic links and store the real path to the file.
Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED:
* Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable
to ``TRUE`` disables the package. This also disables redirection to a
package provided by :module:`FetchContent`.
* Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable
to ``TRUE`` makes the package REQUIRED.
Setting both variables to ``TRUE`` simultaneously is an error.
.. _`version selection`:
Config Mode Version Selection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
When Config mode is used, this version selection process is applied
regardless of whether the :ref:`full <full signature>` or
:ref:`basic <basic signature>` signature was given.
When the ``[version]`` argument is given, Config mode will only find a
version of the package that claims compatibility with the requested
version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the
``EXACT`` option is given, only a version of the package claiming an exact match
of the requested version may be found. CMake does not establish any
convention for the meaning of version numbers. Package version
numbers are checked by "version" files provided by the packages themselves
or by :module:`FetchContent`. For a candidate package configuration file
``<config-file>.cmake`` the corresponding version file is located next
to it and named either ``<config-file>-version.cmake`` or
``<config-file>Version.cmake``. If no such version file is available
then the configuration file is assumed to not be compatible with any
requested version. A basic version file containing generic version
matching code can be created using the
:module:`CMakePackageConfigHelpers` module. When a version file
is found it is loaded to check the requested version number. The
version file is loaded in a nested scope in which the following
variables have been defined:
``PACKAGE_FIND_NAME``
The ``<PackageName>``
``PACKAGE_FIND_VERSION``
Full requested version string
``PACKAGE_FIND_VERSION_MAJOR``
Major version if requested, else 0
``PACKAGE_FIND_VERSION_MINOR``
Minor version if requested, else 0
``PACKAGE_FIND_VERSION_PATCH``
Patch version if requested, else 0
``PACKAGE_FIND_VERSION_TWEAK``
Tweak version if requested, else 0
``PACKAGE_FIND_VERSION_COUNT``
Number of version components, 0 to 4
When a version range is specified, the above version variables will hold
values based on the lower end of the version range. This is to preserve
compatibility with packages that have not been implemented to expect version
ranges. In addition, the version range will be described by the following
variables:
``PACKAGE_FIND_VERSION_RANGE``
Full requested version range string
``PACKAGE_FIND_VERSION_RANGE_MIN``
This specifies whether the lower end point of the version range should be
included or excluded. Currently, the only supported value for this variable
is ``INCLUDE``.
``PACKAGE_FIND_VERSION_RANGE_MAX``
This specifies whether the upper end point of the version range should be
included or excluded. The supported values for this variable are
``INCLUDE`` and ``EXCLUDE``.
``PACKAGE_FIND_VERSION_MIN``
Full requested version string of the lower end point of the range
``PACKAGE_FIND_VERSION_MIN_MAJOR``
Major version of the lower end point if requested, else 0
``PACKAGE_FIND_VERSION_MIN_MINOR``
Minor version of the lower end point if requested, else 0
``PACKAGE_FIND_VERSION_MIN_PATCH``
Patch version of the lower end point if requested, else 0
``PACKAGE_FIND_VERSION_MIN_TWEAK``
Tweak version of the lower end point if requested, else 0
``PACKAGE_FIND_VERSION_MIN_COUNT``
Number of version components of the lower end point, 0 to 4
``PACKAGE_FIND_VERSION_MAX``
Full requested version string of the upper end point of the range
``PACKAGE_FIND_VERSION_MAX_MAJOR``
Major version of the upper end point if requested, else 0
``PACKAGE_FIND_VERSION_MAX_MINOR``
Minor version of the upper end point if requested, else 0
``PACKAGE_FIND_VERSION_MAX_PATCH``
Patch version of the upper end point if requested, else 0
``PACKAGE_FIND_VERSION_MAX_TWEAK``
Tweak version of the upper end point if requested, else 0
``PACKAGE_FIND_VERSION_MAX_COUNT``
Number of version components of the upper end point, 0 to 4
Regardless of whether a single version or a version range is specified, the
variable ``PACKAGE_FIND_VERSION_COMPLETE`` will be defined and will hold
the full requested version string as specified.
The version file checks whether it satisfies the requested version and
sets these variables:
``PACKAGE_VERSION``
Full provided version string
``PACKAGE_VERSION_EXACT``
True if version is exact match
``PACKAGE_VERSION_COMPATIBLE``
True if version is compatible
``PACKAGE_VERSION_UNSUITABLE``
True if unsuitable as any version
These variables are checked by the ``find_package`` command to determine
whether the configuration file provides an acceptable version. They
are not available after the ``find_package`` call returns. If the version
is acceptable the following variables are set:
``<PackageName>_VERSION``
Full provided version string
``<PackageName>_VERSION_MAJOR``
Major version if provided, else 0
``<PackageName>_VERSION_MINOR``
Minor version if provided, else 0
``<PackageName>_VERSION_PATCH``
Patch version if provided, else 0
``<PackageName>_VERSION_TWEAK``
Tweak version if provided, else 0
``<PackageName>_VERSION_COUNT``
Number of version components, 0 to 4
and the corresponding package configuration file is loaded.
When multiple package configuration files are available whose version files
claim compatibility with the version requested it is unspecified which
one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
is set no attempt is made to choose a highest or closest version number.
To control the order in which ``find_package`` checks for compatibility use
the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
For instance in order to select the highest version one can set
.. code-block:: cmake
SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
before calling ``find_package``.
Package File Interface Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When loading a find module or package configuration file ``find_package``
defines variables to provide information about the call arguments (and
restores their original state before returning):
``CMAKE_FIND_PACKAGE_NAME``
The ``<PackageName>`` which is searched for
``<PackageName>_FIND_REQUIRED``
True if ``REQUIRED`` option was given
``<PackageName>_FIND_QUIETLY``
True if ``QUIET`` option was given
``<PackageName>_FIND_REGISTRY_VIEW``
The requested view if ``REGISTRY_VIEW`` option was given
``<PackageName>_FIND_VERSION``
Full requested version string
``<PackageName>_FIND_VERSION_MAJOR``
Major version if requested, else 0
``<PackageName>_FIND_VERSION_MINOR``
Minor version if requested, else 0
``<PackageName>_FIND_VERSION_PATCH``
Patch version if requested, else 0
``<PackageName>_FIND_VERSION_TWEAK``
Tweak version if requested, else 0
``<PackageName>_FIND_VERSION_COUNT``
Number of version components, 0 to 4
``<PackageName>_FIND_VERSION_EXACT``
True if ``EXACT`` option was given
``<PackageName>_FIND_COMPONENTS``
List of specified components (required and optional)
``<PackageName>_FIND_REQUIRED_<c>``
True if component ``<c>`` is required,
false if component ``<c>`` is optional
When a version range is specified, the above version variables will hold
values based on the lower end of the version range. This is to preserve
compatibility with packages that have not been implemented to expect version
ranges. In addition, the version range will be described by the following
variables:
``<PackageName>_FIND_VERSION_RANGE``
Full requested version range string
``<PackageName>_FIND_VERSION_RANGE_MIN``
This specifies whether the lower end point of the version range is
included or excluded. Currently, ``INCLUDE`` is the only supported value.
``<PackageName>_FIND_VERSION_RANGE_MAX``
This specifies whether the upper end point of the version range is
included or excluded. The possible values for this variable are
``INCLUDE`` or ``EXCLUDE``.
``<PackageName>_FIND_VERSION_MIN``
Full requested version string of the lower end point of the range
``<PackageName>_FIND_VERSION_MIN_MAJOR``
Major version of the lower end point if requested, else 0
``<PackageName>_FIND_VERSION_MIN_MINOR``
Minor version of the lower end point if requested, else 0
``<PackageName>_FIND_VERSION_MIN_PATCH``
Patch version of the lower end point if requested, else 0
``<PackageName>_FIND_VERSION_MIN_TWEAK``
Tweak version of the lower end point if requested, else 0
``<PackageName>_FIND_VERSION_MIN_COUNT``
Number of version components of the lower end point, 0 to 4
``<PackageName>_FIND_VERSION_MAX``
Full requested version string of the upper end point of the range
``<PackageName>_FIND_VERSION_MAX_MAJOR``
Major version of the upper end point if requested, else 0
``<PackageName>_FIND_VERSION_MAX_MINOR``
Minor version of the upper end point if requested, else 0
``<PackageName>_FIND_VERSION_MAX_PATCH``
Patch version of the upper end point if requested, else 0
``<PackageName>_FIND_VERSION_MAX_TWEAK``
Tweak version of the upper end point if requested, else 0
``<PackageName>_FIND_VERSION_MAX_COUNT``
Number of version components of the upper end point, 0 to 4
Regardless of whether a single version or a version range is specified, the
variable ``<PackageName>_FIND_VERSION_COMPLETE`` will be defined and will hold
the full requested version string as specified.
In Module mode the loaded find module is responsible to honor the
request detailed by these variables; see the find module for details.
In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and
``[version]`` options automatically but leaves it to the package
configuration file to handle components in a way that makes sense
for the package. The package configuration file may set
``<PackageName>_FOUND`` to false to tell ``find_package`` that component
requirements are not satisfied.

50
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/find_path.rst Normal file
View File

@ -0,0 +1,50 @@
find_path
---------
.. |FIND_XXX| replace:: find_path
.. |NAMES| replace:: NAMES name1 [name2 ...]
.. |SEARCH_XXX| replace:: file in a directory
.. |SEARCH_XXX_DESC| replace:: directory containing the named file
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_INCLUDE_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
:variable:`CMAKE_SYSTEM_INCLUDE_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
:variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
:variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
.. include:: FIND_XXX.txt
When searching for frameworks, if the file is specified as ``A/b.h``, then
the framework search will look for ``A.framework/Headers/b.h``. If that
is found the path will be set to the path to the framework. CMake
will convert this to the correct ``-F`` option to include the file.

43
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/find_program.rst Normal file
View File

@ -0,0 +1,43 @@
find_program
------------
.. |FIND_XXX| replace:: find_program
.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
.. |SEARCH_XXX| replace:: program
.. |SEARCH_XXX_DESC| replace:: program
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin``
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``BOTH``
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
|FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
|CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH`
.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
|ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_PROGRAM_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_APPBUNDLE_PATH`
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` itself.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts no extra search paths are included
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
|CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
:variable:`CMAKE_SYSTEM_PROGRAM_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
:variable:`CMAKE_SYSTEM_APPBUNDLE_PATH`
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
:variable:`CMAKE_FIND_ROOT_PATH_MODE_PROGRAM`
.. include:: FIND_XXX.txt
When more than one value is given to the ``NAMES`` option this command by
default will consider one name at a time and search every directory
for it. The ``NAMES_PER_DIR`` option tells this command to consider one
directory at a time and search for all names in it.

14
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/fltk_wrap_ui.rst Normal file
View File

@ -0,0 +1,14 @@
fltk_wrap_ui
------------
Create FLTK user interfaces Wrappers.
.. code-block:: cmake
fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )
Produce .h and .cxx files for all the .fl and .fld files listed. The
resulting .h and .cxx files will be added to a variable named
``resultingLibraryName_FLTK_UI_SRCS`` which should be added to your
library.

138
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/foreach.rst Normal file
View File

@ -0,0 +1,138 @@
foreach
-------
Evaluate a group of commands for each value in a list.
.. code-block:: cmake
foreach(<loop_var> <items>)
<commands>
endforeach()
where ``<items>`` is a list of items that are separated by
semicolon or whitespace.
All commands between ``foreach`` and the matching ``endforeach`` are recorded
without being invoked. Once the ``endforeach`` is evaluated, the recorded
list of commands is invoked once for each item in ``<items>``.
At the beginning of each iteration the variable ``<loop_var>`` will be set
to the value of the current item.
The scope of ``<loop_var>`` is restricted to the loop scope. See policy
:policy:`CMP0124` for details.
The commands :command:`break` and :command:`continue` provide means to
escape from the normal control flow.
Per legacy, the :command:`endforeach` command admits
an optional ``<loop_var>`` argument.
If used, it must be a verbatim
repeat of the argument of the opening
``foreach`` command.
.. code-block:: cmake
foreach(<loop_var> RANGE <stop>)
In this variant, ``foreach`` iterates over the numbers
0, 1, ... up to (and including) the nonnegative integer ``<stop>``.
.. code-block:: cmake
foreach(<loop_var> RANGE <start> <stop> [<step>])
In this variant, ``foreach`` iterates over the numbers from
``<start>`` up to at most ``<stop>`` in steps of ``<step>``.
If ``<step>`` is not specified, then the step size is 1.
The three arguments ``<start>`` ``<stop>`` ``<step>`` must
all be nonnegative integers, and ``<stop>`` must not be
smaller than ``<start>``; otherwise you enter the danger zone
of undocumented behavior that may change in future releases.
.. code-block:: cmake
foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])
In this variant, ``<lists>`` is a whitespace or semicolon
separated list of list-valued variables. The ``foreach``
command iterates over each item in each given list.
The ``<items>`` following the ``ITEMS`` keyword are processed
as in the first variant of the ``foreach`` command.
The forms ``LISTS A`` and ``ITEMS ${A}`` are
equivalent.
The following example shows how the ``LISTS`` option is
processed:
.. code-block:: cmake
set(A 0;1)
set(B 2 3)
set(C "4 5")
set(D 6;7 8)
set(E "")
foreach(X IN LISTS A B C D E)
message(STATUS "X=${X}")
endforeach()
yields::
-- X=0
-- X=1
-- X=2
-- X=3
-- X=4 5
-- X=6
-- X=7
-- X=8
.. code-block:: cmake
foreach(<loop_var>... IN ZIP_LISTS <lists>)
.. versionadded:: 3.17
In this variant, ``<lists>`` is a whitespace or semicolon
separated list of list-valued variables. The ``foreach``
command iterates over each list simultaneously setting the
iteration variables as follows:
- if the only ``loop_var`` given, then it sets a series of
``loop_var_N`` variables to the current item from the
corresponding list;
- if multiple variable names passed, their count should match
the lists variables count;
- if any of the lists are shorter, the corresponding iteration
variable is not defined for the current iteration.
.. code-block:: cmake
list(APPEND English one two three four)
list(APPEND Bahasa satu dua tiga)
foreach(num IN ZIP_LISTS English Bahasa)
message(STATUS "num_0=${num_0}, num_1=${num_1}")
endforeach()
foreach(en ba IN ZIP_LISTS English Bahasa)
message(STATUS "en=${en}, ba=${ba}")
endforeach()
yields::
-- num_0=one, num_1=satu
-- num_0=two, num_1=dua
-- num_0=three, num_1=tiga
-- num_0=four, num_1=
-- en=one, ba=satu
-- en=two, ba=dua
-- en=three, ba=tiga
-- en=four, ba=
See Also
^^^^^^^^
* :command:`break`
* :command:`continue`
* :command:`endforeach`
* :command:`while`

82
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/function.rst Normal file
View File

@ -0,0 +1,82 @@
function
--------
Start recording a function for later invocation as a command.
.. code-block:: cmake
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named ``<name>`` that takes arguments named
``<arg1>``, ... The ``<commands>`` in the function definition
are recorded; they are not executed until the function is invoked.
Per legacy, the :command:`endfunction` command admits an optional
``<name>`` argument. If used, it must be a verbatim repeat of the
argument of the opening ``function`` command.
A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for
details.
See the :command:`cmake_policy()` command documentation for the behavior
of policies inside functions.
See the :command:`macro()` command documentation for differences
between CMake functions and macros.
Invocation
^^^^^^^^^^
The function invocation is case-insensitive. A function defined as
.. code-block:: cmake
function(foo)
<commands>
endfunction()
can be invoked through any of
.. code-block:: cmake
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the
case chosen in the function definition. Typically functions use
all-lowercase names.
.. versionadded:: 3.18
The :command:`cmake_language(CALL ...)` command can also be used to
invoke the function.
Arguments
^^^^^^^^^
When the function is invoked, the recorded ``<commands>`` are first
modified by replacing formal parameters (``${arg1}``, ...) with the
arguments passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
``ARGC`` variable which will be set to the number of arguments passed
into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which
will have the actual values of the arguments passed in. This facilitates
creating functions with optional arguments.
Furthermore, ``ARGV`` holds the list of all arguments given to the
function and ``ARGN`` holds the list of arguments past the last expected
argument. Referencing to ``ARGV#`` arguments beyond ``ARGC`` have
undefined behavior. Checking that ``ARGC`` is greater than ``#`` is
the only way to ensure that ``ARGV#`` was passed to the function as an
extra argument.
See Also
^^^^^^^^
* :command:`cmake_parse_arguments`
* :command:`endfunction`
* :command:`return`

23
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/get_cmake_property.rst Normal file
View File

@ -0,0 +1,23 @@
get_cmake_property
------------------
Get a global property of the CMake instance.
.. code-block:: cmake
get_cmake_property(<var> <property>)
Gets a global property from the CMake instance. The value of
the ``<property>`` is stored in the variable ``<var>``.
If the property is not found, ``<var>`` will be set to ``NOTFOUND``.
See the :manual:`cmake-properties(7)` manual for available properties.
In addition to global properties, this command (for historical reasons)
also supports the :prop_dir:`VARIABLES` and :prop_dir:`MACROS` directory
properties. It also supports a special ``COMPONENTS`` global property that
lists the components given to the :command:`install` command.
See Also
^^^^^^^^
* the :command:`get_property` command ``GLOBAL`` option

41
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/get_directory_property.rst Normal file
View File

@ -0,0 +1,41 @@
get_directory_property
----------------------
Get a property of ``DIRECTORY`` scope.
.. code-block:: cmake
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Stores a property of directory scope in the named ``<variable>``.
The ``DIRECTORY`` argument specifies another directory from which
to retrieve the property value instead of the current directory.
Relative paths are treated as relative to the
current source directory. CMake must already know about the directory,
either by having added it through a call to :command:`add_subdirectory`
or being the top level directory.
.. versionadded:: 3.19
``<dir>`` may reference a binary directory.
If the property is not defined for the nominated directory scope,
an empty string is returned. In the case of ``INHERITED`` properties,
if the property is not found for the nominated directory scope,
the search will chain to a parent scope as described for the
:command:`define_property` command.
.. code-block:: cmake
get_directory_property(<variable> [DIRECTORY <dir>]
DEFINITION <var-name>)
Get a variable definition from a directory. This form is useful to
get a variable definition from another directory.
See Also
^^^^^^^^
* :command:`define_property`
* the more general :command:`get_property` command

76
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/get_filename_component.rst Normal file
View File

@ -0,0 +1,76 @@
get_filename_component
----------------------
Get a specific component of a full filename.
.. versionchanged:: 3.20
This command has been superseded by the :command:`cmake_path` command, except
for ``REALPATH``, which is now offered by :command:`file(REAL_PATH)`, and
``PROGRAM``, now available in :command:`separate_arguments(PROGRAM)`.
.. versionchanged:: 3.24
The undocumented feature offering the capability to query the ``Windows``
registry is superseded by
:ref:`cmake_host_system_information(QUERY WINDOWS_REGISTRY)<Query Windows registry>`
command.
.. code-block:: cmake
get_filename_component(<var> <FileName> <mode> [CACHE])
Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of:
::
DIRECTORY = Directory without file name
NAME = File name without directory
EXT = File name longest extension (.b.c from d/a.b.c)
NAME_WE = File name with neither the directory nor the longest extension
LAST_EXT = File name last extension (.c from d/a.b.c)
NAME_WLE = File name with neither the directory nor the last extension
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
.. versionadded:: 3.14
Added the ``LAST_EXT`` and ``NAME_WLE`` modes.
Paths are returned with forward slashes and have no trailing slashes.
If the optional ``CACHE`` argument is specified, the result variable is
added to the cache.
.. code-block:: cmake
get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
.. versionadded:: 3.4
Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one
of:
::
ABSOLUTE = Full path to file
REALPATH = Full path to existing file with symlinks resolved
If the provided ``<FileName>`` is a relative path, it is evaluated relative
to the given base directory ``<dir>``. If no base directory is
provided, the default base directory will be
:variable:`CMAKE_CURRENT_SOURCE_DIR`.
Paths are returned with forward slashes and have no trailing slashes. If the
optional ``CACHE`` argument is specified, the result variable is added to the
cache.
.. code-block:: cmake
get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
The program in ``<FileName>`` will be found in the system search path or
left as a full path. If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then
any command-line arguments present in the ``<FileName>`` string are split
from the program name and stored in ``<arg_var>``. This is used to
separate a program name from its arguments in a command line string.
See Also
^^^^^^^^
* :command:`cmake_path`

107
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/get_property.rst Normal file
View File

@ -0,0 +1,107 @@
get_property
------------
Get a property.
.. code-block:: cmake
get_property(<variable>
<GLOBAL |
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
VARIABLE >
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Gets one property from one object in a scope.
The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the property.
It must be one of the following:
``GLOBAL``
Scope is unique and does not accept a name.
``DIRECTORY``
Scope defaults to the current directory but another
directory (already processed by CMake) may be named by the
full or relative path ``<dir>``.
Relative paths are treated as relative to the current source directory.
See also the :command:`get_directory_property` command.
.. versionadded:: 3.19
``<dir>`` may reference a binary directory.
``TARGET``
Scope must name one existing target.
See also the :command:`get_target_property` command.
``SOURCE``
Scope must name one source file. By default, the source file's property
will be read from the current source directory's scope.
.. versionadded:: 3.18
Directory scope can be overridden with one of the following sub-options:
``DIRECTORY <dir>``
The source file property will be read from the ``<dir>`` directory's
scope. CMake must already know about
the directory, either by having added it through a call
to :command:`add_subdirectory` or ``<dir>`` being the top level directory.
Relative paths are treated as relative to the current source directory.
.. versionadded:: 3.19
``<dir>`` may reference a binary directory.
``TARGET_DIRECTORY <target>``
The source file property will be read from the directory scope in which
``<target>`` was created (``<target>`` must therefore already exist).
See also the :command:`get_source_file_property` command.
``INSTALL``
.. versionadded:: 3.1
Scope must name one installed file path.
``TEST``
Scope must name one existing test.
See also the :command:`get_test_property` command.
``CACHE``
Scope must name one cache entry.
``VARIABLE``
Scope is unique and does not accept a name.
The required ``PROPERTY`` option is immediately followed by the name of
the property to get. If the property is not set an empty value is
returned, although some properties support inheriting from a parent scope
if defined to behave that way (see :command:`define_property`).
If the ``SET`` option is given the variable is set to a boolean
value indicating whether the property has been set. If the ``DEFINED``
option is given the variable is set to a boolean value indicating
whether the property has been defined such as with the
:command:`define_property` command.
If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a
string containing documentation for the requested property. If
documentation is requested for a property that has not been defined
``NOTFOUND`` is returned.
.. note::
The :prop_sf:`GENERATED` source file property may be globally visible.
See its documentation for details.
See Also
^^^^^^^^
* :command:`define_property`
* :command:`set_property`

52
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/get_source_file_property.rst Normal file
View File

@ -0,0 +1,52 @@
get_source_file_property
------------------------
Get a property for a source file.
.. code-block:: cmake
get_source_file_property(<variable> <file>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>]
<property>)
Gets a property from a source file. The value of the property is
stored in the specified ``<variable>``. If the source property is not found,
the behavior depends on whether it has been defined to be an ``INHERITED``
property or not (see :command:`define_property`). Non-inherited properties
will set ``variable`` to ``NOTFOUND``, whereas inherited properties will search
the relevant parent scope as described for the :command:`define_property`
command and if still unable to find the property, ``variable`` will be set to
an empty string.
By default, the source file's property will be read from the current source
directory's scope.
.. versionadded:: 3.18
Directory scope can be overridden with one of the following sub-options:
``DIRECTORY <dir>``
The source file property will be read from the ``<dir>`` directory's
scope. CMake must already know about that source directory, either by
having added it through a call to :command:`add_subdirectory` or ``<dir>``
being the top level source directory. Relative paths are treated as
relative to the current source directory.
``TARGET_DIRECTORY <target>``
The source file property will be read from the directory scope in which
``<target>`` was created (``<target>`` must therefore already exist).
Use :command:`set_source_files_properties` to set property values. Source
file properties usually control how the file is built. One property that is
always there is :prop_sf:`LOCATION`.
.. note::
The :prop_sf:`GENERATED` source file property may be globally visible.
See its documentation for details.
See Also
^^^^^^^^
* :command:`define_property`
* the more general :command:`get_property` command
* :command:`set_source_files_properties`

31
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/get_target_property.rst Normal file
View File

@ -0,0 +1,31 @@
get_target_property
-------------------
Get a property from a target.
.. code-block:: cmake
get_target_property(<VAR> target property)
Get a property from a target. The value of the property is stored in
the variable ``<VAR>``. If the target property is not found, the behavior
depends on whether it has been defined to be an ``INHERITED`` property
or not (see :command:`define_property`). Non-inherited properties will
set ``<VAR>`` to ``<VAR>-NOTFOUND``, whereas inherited properties will search
the relevant parent scope as described for the :command:`define_property`
command and if still unable to find the property, ``<VAR>`` will be set to
an empty string.
Use :command:`set_target_properties` to set target property values.
Properties are usually used to control how a target is built, but some
query the target instead. This command can get properties for any
target so far created. The targets do not need to be in the current
``CMakeLists.txt`` file.
See Also
^^^^^^^^
* :command:`define_property`
* the more general :command:`get_property` command
* :command:`set_target_properties`
* :ref:`Target Properties` for the list of properties known to CMake

26
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/get_test_property.rst Normal file
View File

@ -0,0 +1,26 @@
get_test_property
-----------------
Get a property of the test.
.. code-block:: cmake
get_test_property(test property VAR)
Get a property from the test. The value of the property is stored in
the variable ``VAR``. If the test property is not found, the behavior
depends on whether it has been defined to be an ``INHERITED`` property
or not (see :command:`define_property`). Non-inherited properties will
set ``VAR`` to "NOTFOUND", whereas inherited properties will search the
relevant parent scope as described for the :command:`define_property`
command and if still unable to find the property, ``VAR`` will be set to
an empty string.
For a list of standard properties you can type
:option:`cmake --help-property-list`.
See Also
^^^^^^^^
* :command:`define_property`
* the more general :command:`get_property` command

459
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/if.rst Normal file
View File

@ -0,0 +1,459 @@
if
--
Conditionally execute a group of commands.
Synopsis
^^^^^^^^
.. code-block:: cmake
if(<condition>)
<commands>
elseif(<condition>) # optional block, can be repeated
<commands>
else() # optional block
<commands>
endif()
Evaluates the ``condition`` argument of the ``if`` clause according to the
`Condition syntax`_ described below. If the result is true, then the
``commands`` in the ``if`` block are executed.
Otherwise, optional ``elseif`` blocks are processed in the same way.
Finally, if no ``condition`` is true, ``commands`` in the optional ``else``
block are executed.
Per legacy, the :command:`else` and :command:`endif` commands admit
an optional ``<condition>`` argument.
If used, it must be a verbatim
repeat of the argument of the opening
``if`` command.
.. _`Condition Syntax`:
Condition Syntax
^^^^^^^^^^^^^^^^
The following syntax applies to the ``condition`` argument of
the ``if``, ``elseif`` and :command:`while` clauses.
Compound conditions are evaluated in the following order of precedence:
1. `Parentheses`_.
2. Unary tests such as `EXISTS`_, `COMMAND`_, and `DEFINED`_.
3. Binary tests such as `EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_,
`GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_,
`STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_,
`VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_,
`PATH_EQUAL`_, and `MATCHES`_.
4. Unary logical operator `NOT`_.
5. Binary logical operators `AND`_ and `OR`_, from left to right,
without any short-circuit.
Basic Expressions
"""""""""""""""""
.. signature:: if(<constant>)
:target: constant
True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``,
or a non-zero number (including floating point numbers).
False if the constant is ``0``, ``OFF``,
``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string,
or ends in the suffix ``-NOTFOUND``. Named boolean constants are
case-insensitive. If the argument is not one of these specific
constants, it is treated as a variable or string (see `Variable Expansion`_
further below) and one of the following two forms applies.
.. signature:: if(<variable>)
:target: variable
True if given a variable that is defined to a value that is not a false
constant. False otherwise, including if the variable is undefined.
Note that macro arguments are not variables.
:ref:`Environment Variables <CMake Language Environment Variables>` also
cannot be tested this way, e.g. ``if(ENV{some_var})`` will always evaluate
to false.
.. signature:: if(<string>)
:target: string
A quoted string always evaluates to false unless:
* The string's value is one of the true constants, or
* Policy :policy:`CMP0054` is not set to ``NEW`` and the string's value
happens to be a variable name that is affected by :policy:`CMP0054`'s
behavior.
Logic Operators
"""""""""""""""
.. signature:: if(NOT <condition>)
True if the condition is not true.
.. signature:: if(<cond1> AND <cond2>)
:target: AND
True if both conditions would be considered true individually.
.. signature:: if(<cond1> OR <cond2>)
:target: OR
True if either condition would be considered true individually.
.. signature:: if((condition) AND (condition OR (condition)))
:target: parentheses
The conditions inside the parenthesis are evaluated first and then
the remaining condition is evaluated as in the other examples.
Where there are nested parenthesis the innermost are evaluated as part
of evaluating the condition that contains them.
Existence Checks
""""""""""""""""
.. signature:: if(COMMAND <command-name>)
True if the given name is a command, macro or function that can be
invoked.
.. signature:: if(POLICY <policy-id>)
True if the given name is an existing policy (of the form ``CMP<NNNN>``).
.. signature:: if(TARGET <target-name>)
True if the given name is an existing logical target name created
by a call to the :command:`add_executable`, :command:`add_library`,
or :command:`add_custom_target` command that has already been invoked
(in any directory).
.. signature:: if(TEST <test-name>)
.. versionadded:: 3.3
True if the given name is an existing test name created by the
:command:`add_test` command.
.. signature:: if(DEFINED <name>|CACHE{<name>}|ENV{<name>})
True if a variable, cache variable or environment variable
with given ``<name>`` is defined. The value of the variable
does not matter. Note the following caveats:
* Macro arguments are not variables.
* It is not possible to test directly whether a `<name>` is a non-cache
variable. The expression ``if(DEFINED someName)`` will evaluate to true
if either a cache or non-cache variable ``someName`` exists. In
comparison, the expression ``if(DEFINED CACHE{someName})`` will only
evaluate to true if a cache variable ``someName`` exists. Both expressions
need to be tested if you need to know whether a non-cache variable exists:
``if(DEFINED someName AND NOT DEFINED CACHE{someName})``.
.. versionadded:: 3.14
Added support for ``CACHE{<name>}`` variables.
.. signature:: if(<variable|string> IN_LIST <variable>)
:target: IN_LIST
.. versionadded:: 3.3
True if the given element is contained in the named list variable.
File Operations
"""""""""""""""
.. signature:: if(EXISTS <path-to-file-or-directory>)
True if the named file or directory exists and is readable. Behavior
is well-defined only for explicit full paths (a leading ``~/`` is not
expanded as a home directory and is considered a relative path).
Resolves symbolic links, i.e. if the named file or directory is a
symbolic link, returns true if the target of the symbolic link exists.
False if the given path is an empty string.
.. signature:: if(<file1> IS_NEWER_THAN <file2>)
:target: IS_NEWER_THAN
True if ``file1`` is newer than ``file2`` or if one of the two files doesn't
exist. Behavior is well-defined only for full paths. If the file
time stamps are exactly the same, an ``IS_NEWER_THAN`` comparison returns
true, so that any dependent build operations will occur in the event
of a tie. This includes the case of passing the same file name for
both file1 and file2.
.. signature:: if(IS_DIRECTORY <path>)
True if ``path`` is a directory. Behavior is well-defined only
for full paths.
False if the given path is an empty string.
.. signature:: if(IS_SYMLINK <path>)
True if the given path is a symbolic link. Behavior is well-defined
only for full paths.
.. signature:: if(IS_ABSOLUTE <path>)
True if the given path is an absolute path. Note the following special
cases:
* An empty ``path`` evaluates to false.
* On Windows hosts, any ``path`` that begins with a drive letter and colon
(e.g. ``C:``), a forward slash or a backslash will evaluate to true.
This means a path like ``C:no\base\dir`` will evaluate to true, even
though the non-drive part of the path is relative.
* On non-Windows hosts, any ``path`` that begins with a tilde (``~``)
evaluates to true.
Comparisons
"""""""""""
.. signature:: if(<variable|string> MATCHES <regex>)
:target: MATCHES
True if the given string or variable's value matches the given regular
expression. See :ref:`Regex Specification` for regex format.
.. versionadded:: 3.9
``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables.
.. signature:: if(<variable|string> LESS <variable|string>)
:target: LESS
True if the given string or variable's value is a valid number and less
than that on the right.
.. signature:: if(<variable|string> GREATER <variable|string>)
:target: GREATER
True if the given string or variable's value is a valid number and greater
than that on the right.
.. signature:: if(<variable|string> EQUAL <variable|string>)
:target: EQUAL
True if the given string or variable's value is a valid number and equal
to that on the right.
.. signature:: if(<variable|string> LESS_EQUAL <variable|string>)
:target: LESS_EQUAL
.. versionadded:: 3.7
True if the given string or variable's value is a valid number and less
than or equal to that on the right.
.. signature:: if(<variable|string> GREATER_EQUAL <variable|string>)
:target: GREATER_EQUAL
.. versionadded:: 3.7
True if the given string or variable's value is a valid number and greater
than or equal to that on the right.
.. signature:: if(<variable|string> STRLESS <variable|string>)
:target: STRLESS
True if the given string or variable's value is lexicographically less
than the string or variable on the right.
.. signature:: if(<variable|string> STRGREATER <variable|string>)
:target: STRGREATER
True if the given string or variable's value is lexicographically greater
than the string or variable on the right.
.. signature:: if(<variable|string> STREQUAL <variable|string>)
:target: STREQUAL
True if the given string or variable's value is lexicographically equal
to the string or variable on the right.
.. signature:: if(<variable|string> STRLESS_EQUAL <variable|string>)
:target: STRLESS_EQUAL
.. versionadded:: 3.7
True if the given string or variable's value is lexicographically less
than or equal to the string or variable on the right.
.. signature:: if(<variable|string> STRGREATER_EQUAL <variable|string>)
:target: STRGREATER_EQUAL
.. versionadded:: 3.7
True if the given string or variable's value is lexicographically greater
than or equal to the string or variable on the right.
Version Comparisons
"""""""""""""""""""
.. signature:: if(<variable|string> VERSION_LESS <variable|string>)
:target: VERSION_LESS
Component-wise integer version number comparison (version format is
``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
Any non-integer version component or non-integer trailing part of a version
component effectively truncates the string at that point.
.. signature:: if(<variable|string> VERSION_GREATER <variable|string>)
:target: VERSION_GREATER
Component-wise integer version number comparison (version format is
``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
Any non-integer version component or non-integer trailing part of a version
component effectively truncates the string at that point.
.. signature:: if(<variable|string> VERSION_EQUAL <variable|string>)
:target: VERSION_EQUAL
Component-wise integer version number comparison (version format is
``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
Any non-integer version component or non-integer trailing part of a version
component effectively truncates the string at that point.
.. signature:: if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
:target: VERSION_LESS_EQUAL
.. versionadded:: 3.7
Component-wise integer version number comparison (version format is
``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
Any non-integer version component or non-integer trailing part of a version
component effectively truncates the string at that point.
.. signature:: if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
:target: VERSION_GREATER_EQUAL
.. versionadded:: 3.7
Component-wise integer version number comparison (version format is
``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
Any non-integer version component or non-integer trailing part of a version
component effectively truncates the string at that point.
Path Comparisons
""""""""""""""""
.. signature:: if(<variable|string> PATH_EQUAL <variable|string>)
:target: PATH_EQUAL
.. versionadded:: 3.24
Compares the two paths component-by-component. Only if every component of
both paths match will the two paths compare equal. Multiple path separators
are effectively collapsed into a single separator, but note that backslashes
are not converted to forward slashes. No other
:ref:`path normalization <Normalization>` is performed.
Component-wise comparison is superior to string-based comparison due to the
handling of multiple path separators. In the following example, the
expression evaluates to true using ``PATH_EQUAL``, but false with
``STREQUAL``:
.. code-block:: cmake
# comparison is TRUE
if ("/a//b/c" PATH_EQUAL "/a/b/c")
...
endif()
# comparison is FALSE
if ("/a//b/c" STREQUAL "/a/b/c")
...
endif()
See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details.
Variable Expansion
^^^^^^^^^^^^^^^^^^
The if command was written very early in CMake's history, predating
the ``${}`` variable evaluation syntax, and for convenience evaluates
variables named by its arguments as shown in the above signatures.
Note that normal variable evaluation with ``${}`` applies before the if
command even receives the arguments. Therefore code like
.. code-block:: cmake
set(var1 OFF)
set(var2 "var1")
if(${var2})
appears to the if command as
.. code-block:: cmake
if(var1)
and is evaluated according to the ``if(<variable>)`` case documented
above. The result is ``OFF`` which is false. However, if we remove the
``${}`` from the example then the command sees
.. code-block:: cmake
if(var2)
which is true because ``var2`` is defined to ``var1`` which is not a false
constant.
Automatic evaluation applies in the other cases whenever the
above-documented condition syntax accepts ``<variable|string>``:
* The left hand argument to `MATCHES`_ is first checked to see if it is
a defined variable. If so, the variable's value is used, otherwise the
original value is used.
* If the left hand argument to `MATCHES`_ is missing it returns false
without error
* Both left and right hand arguments to `LESS`_, `GREATER`_, `EQUAL`_,
`LESS_EQUAL`_, and `GREATER_EQUAL`_, are independently tested to see if
they are defined variables. If so, their defined values are used otherwise
the original value is used.
* Both left and right hand arguments to `STRLESS`_, `STRGREATER`_,
`STREQUAL`_, `STRLESS_EQUAL`_, and `STRGREATER_EQUAL`_ are independently
tested to see if they are defined variables. If so, their defined values are
used otherwise the original value is used.
* Both left and right hand arguments to `VERSION_LESS`_,
`VERSION_GREATER`_, `VERSION_EQUAL`_, `VERSION_LESS_EQUAL`_, and
`VERSION_GREATER_EQUAL`_ are independently tested to see if they are defined
variables. If so, their defined values are used otherwise the original value
is used.
* The right hand argument to `NOT`_ is tested to see if it is a boolean
constant. If so, the value is used, otherwise it is assumed to be a
variable and it is dereferenced.
* The left and right hand arguments to `AND`_ and `OR`_ are independently
tested to see if they are boolean constants. If so, they are used as
such, otherwise they are assumed to be variables and are dereferenced.
.. versionchanged:: 3.1
To prevent ambiguity, potential variable or keyword names can be
specified in a :ref:`Quoted Argument` or a :ref:`Bracket Argument`.
A quoted or bracketed variable or keyword will be interpreted as a
string and not dereferenced or interpreted.
See policy :policy:`CMP0054`.
There is no automatic evaluation for environment or cache
:ref:`Variable References`. Their values must be referenced as
``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented
condition syntax accepts ``<variable|string>``.
See also
^^^^^^^^
* :command:`else`
* :command:`elseif`
* :command:`endif`

25
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/include.rst Normal file
View File

@ -0,0 +1,25 @@
include
-------
Load and run CMake code from a file or module.
.. code-block:: cmake
include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
[NO_POLICY_SCOPE])
Loads and runs CMake code from the file given. Variable reads and
writes access the scope of the caller (dynamic scoping). If ``OPTIONAL``
is present, then no error is raised if the file does not exist. If
``RESULT_VARIABLE`` is given the variable ``<var>`` will be set to the
full filename which has been included or ``NOTFOUND`` if it failed.
If a module is specified instead of a file, the file with name
``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`,
then in the CMake module directory. There is one exception to this: if
the file which calls ``include()`` is located itself in the CMake builtin
module directory, then first the CMake builtin module directory is searched and
:variable:`CMAKE_MODULE_PATH` afterwards. See also policy :policy:`CMP0017`.
See the :command:`cmake_policy` command documentation for discussion of the
``NO_POLICY_SCOPE`` option.

44
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/include_directories.rst Normal file
View File

@ -0,0 +1,44 @@
include_directories
-------------------
Add include directories to the build.
.. code-block:: cmake
include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
Add the given directories to those the compiler uses to search for
include files. Relative paths are interpreted as relative to the
current source directory.
The include directories are added to the :prop_dir:`INCLUDE_DIRECTORIES`
directory property for the current ``CMakeLists`` file. They are also
added to the :prop_tgt:`INCLUDE_DIRECTORIES` target property for each
target in the current ``CMakeLists`` file. The target property values
are the ones used by the generators.
By default the directories specified are appended onto the current list of
directories. This default behavior can be changed by setting
:variable:`CMAKE_INCLUDE_DIRECTORIES_BEFORE` to ``ON``. By using
``AFTER`` or ``BEFORE`` explicitly, you can select between appending and
prepending, independent of the default.
If the ``SYSTEM`` option is given, the compiler will be told the
directories are meant as system include directories on some platforms.
Signaling this setting might achieve effects such as the compiler
skipping warnings, or these fixed-install system files not being
considered in dependency calculations - see compiler docs.
.. |command_name| replace:: ``include_directories``
.. include:: GENEX_NOTE.txt
.. note::
Prefer the :command:`target_include_directories` command to add include
directories to individual targets and optionally propagate/export them
to dependents.
See Also
^^^^^^^^
* :command:`target_include_directories`

27
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/include_external_msproject.rst Normal file
View File

@ -0,0 +1,27 @@
include_external_msproject
--------------------------
Include an external Microsoft project file in a workspace.
.. code-block:: cmake
include_external_msproject(projectname location
[TYPE projectTypeGUID]
[GUID projectGUID]
[PLATFORM platformName]
dep1 dep2 ...)
Includes an external Microsoft project in the generated workspace
file. Currently does nothing on UNIX. This will create a target
named ``[projectname]``. This can be used in the :command:`add_dependencies`
command to make things depend on the external project.
``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to
specify the type of project, id (``GUID``) of the project and the name of
the target platform. This is useful for projects requiring values
other than the default (e.g. WIX projects).
.. versionadded:: 3.9
If the imported project has different configuration names than the
current project, set the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>`
target property to specify the mapping.

48
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/include_guard.rst Normal file
View File

@ -0,0 +1,48 @@
include_guard
-------------
.. versionadded:: 3.10
Provides an include guard for the file currently being processed by CMake.
.. code-block:: cmake
include_guard([DIRECTORY|GLOBAL])
Sets up an include guard for the current CMake file (see the
:variable:`CMAKE_CURRENT_LIST_FILE` variable documentation).
CMake will end its processing of the current file at the location of the
``include_guard`` command if the current file has already been
processed for the applicable scope (see below). This provides functionality
similar to the include guards commonly used in source headers or to the
``#pragma once`` directive. If the current file has been processed previously
for the applicable scope, the effect is as though :command:`return` had been
called. Do not call this command from inside a function being defined within
the current file.
An optional argument specifying the scope of the guard may be provided.
Possible values for the option are:
``DIRECTORY``
The include guard applies within the current directory and below. The file
will only be included once within this directory scope, but may be included
again by other files outside of this directory (i.e. a parent directory or
another directory not pulled in by :command:`add_subdirectory` or
:command:`include` from the current file or its children).
``GLOBAL``
The include guard applies globally to the whole build. The current file
will only be included once regardless of the scope.
If no arguments given, ``include_guard`` has the same scope as a variable,
meaning that the include guard effect is isolated by the most recent
function scope or current directory if no inner function scopes exist.
In this case the command behavior is the same as:
.. code-block:: cmake
if(__CURRENT_FILE_VAR__)
return()
endif()
set(__CURRENT_FILE_VAR__ TRUE)

18
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/include_regular_expression.rst Normal file
View File

@ -0,0 +1,18 @@
include_regular_expression
--------------------------
Set the regular expression used for dependency checking.
.. code-block:: cmake
include_regular_expression(regex_match [regex_complain])
Sets the regular expressions used in dependency checking. Only files
matching ``regex_match`` will be traced as dependencies. Only files
matching ``regex_complain`` will generate warnings if they cannot be found
(standard header paths are not searched). The defaults are:
::
regex_match = "^.*$" (match everything)
regex_complain = "^$" (match empty string only)

1006
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/install.rst Normal file
View File

File diff suppressed because it is too large Load Diff

41
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/install_files.rst Normal file
View File

@ -0,0 +1,41 @@
install_files
-------------
.. deprecated:: 3.0
Use the :command:`install(FILES)` command instead.
This command has been superseded by the :command:`install` command. It is
provided for compatibility with older CMake code. The ``FILES`` form is
directly replaced by the ``FILES`` form of the :command:`install`
command. The regexp form can be expressed more clearly using the ``GLOB``
form of the :command:`file` command.
.. code-block:: cmake
install_files(<dir> extension file file ...)
Create rules to install the listed files with the given extension into
the given directory. Only files existing in the current source tree
or its corresponding location in the binary tree may be listed. If a
file specified already has an extension, that extension will be
removed first. This is useful for providing lists of source files
such as foo.cxx when you want the corresponding foo.h to be installed.
A typical extension is ``.h``.
.. code-block:: cmake
install_files(<dir> regexp)
Any files in the current source directory that match the regular
expression will be installed.
.. code-block:: cmake
install_files(<dir> FILES file file ...)
Any files listed after the ``FILES`` keyword will be installed explicitly
from the names given. Full paths are allowed in this form.
The directory ``<dir>`` is relative to the installation prefix, which is
stored in the variable :variable:`CMAKE_INSTALL_PREFIX`.

36
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/install_programs.rst Normal file
View File

@ -0,0 +1,36 @@
install_programs
----------------
.. deprecated:: 3.0
Use the :command:`install(PROGRAMS)` command instead.
This command has been superseded by the :command:`install` command. It is
provided for compatibility with older CMake code. The ``FILES`` form is
directly replaced by the ``PROGRAMS`` form of the :command:`install`
command. The regexp form can be expressed more clearly using the ``GLOB``
form of the :command:`file` command.
.. code-block:: cmake
install_programs(<dir> file1 file2 [file3 ...])
install_programs(<dir> FILES file1 [file2 ...])
Create rules to install the listed programs into the given directory.
Use the ``FILES`` argument to guarantee that the file list version of the
command will be used even when there is only one argument.
.. code-block:: cmake
install_programs(<dir> regexp)
In the second form any program in the current source directory that
matches the regular expression will be installed.
This command is intended to install programs that are not built by
cmake, such as shell scripts. See the ``TARGETS`` form of the
:command:`install` command to create installation rules for targets built
by cmake.
The directory ``<dir>`` is relative to the installation prefix, which is
stored in the variable :variable:`CMAKE_INSTALL_PREFIX`.

19
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/install_targets.rst Normal file
View File

@ -0,0 +1,19 @@
install_targets
---------------
.. deprecated:: 3.0
Use the :command:`install(TARGETS)` command instead.
This command has been superseded by the :command:`install` command. It is
provided for compatibility with older CMake code.
.. code-block:: cmake
install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
Create rules to install the listed targets into the given directory.
The directory ``<dir>`` is relative to the installation prefix, which is
stored in the variable :variable:`CMAKE_INSTALL_PREFIX`. If
``RUNTIME_DIRECTORY`` is specified, then on systems with special runtime
files (Windows DLL), the files will be copied to that directory.

61
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/link_directories.rst Normal file
View File

@ -0,0 +1,61 @@
link_directories
----------------
Add directories in which the linker will look for libraries.
.. code-block:: cmake
link_directories([AFTER|BEFORE] directory1 [directory2 ...])
Adds the paths in which the linker should search for libraries.
Relative paths given to this command are interpreted as relative to
the current source directory, see :policy:`CMP0015`.
The command will apply only to targets created after it is called.
.. versionadded:: 3.13
The directories are added to the :prop_dir:`LINK_DIRECTORIES` directory
property for the current ``CMakeLists.txt`` file, converting relative
paths to absolute as needed. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
.. versionadded:: 3.13
By default the directories specified are appended onto the current list of
directories. This default behavior can be changed by setting
:variable:`CMAKE_LINK_DIRECTORIES_BEFORE` to ``ON``. By using
``AFTER`` or ``BEFORE`` explicitly, you can select between appending and
prepending, independent of the default.
.. versionadded:: 3.13
Arguments to ``link_directories`` may use "generator expressions" with
the syntax "$<...>". See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.
.. note::
This command is rarely necessary and should be avoided where there are
other choices. Prefer to pass full absolute paths to libraries where
possible, since this ensures the correct library will always be linked.
The :command:`find_library` command provides the full path, which can
generally be used directly in calls to :command:`target_link_libraries`.
Situations where a library search path may be needed include:
- Project generators like Xcode where the user can switch target
architecture at build time, but a full path to a library cannot
be used because it only provides one architecture (i.e. it is not
a universal binary).
- Libraries may themselves have other private library dependencies
that expect to be found via ``RPATH`` mechanisms, but some linkers
are not able to fully decode those paths (e.g. due to the presence
of things like ``$ORIGIN``).
If a library search path must be provided, prefer to localize the effect
where possible by using the :command:`target_link_directories` command
rather than ``link_directories()``. The target-specific command can also
control how the search directories propagate to other dependent targets.
See Also
^^^^^^^^
* :command:`target_link_directories`
* :command:`target_link_libraries`

19
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/link_libraries.rst Normal file
View File

@ -0,0 +1,19 @@
link_libraries
--------------
Link libraries to all targets added later.
.. code-block:: cmake
link_libraries([item1 [item2 [...]]]
[[debug|optimized|general] <item>] ...)
Specify libraries or flags to use when linking any targets created later in
the current directory or below by commands such as :command:`add_executable`
or :command:`add_library`. See the :command:`target_link_libraries` command
for meaning of arguments.
.. note::
The :command:`target_link_libraries` command should be preferred whenever
possible. Library dependencies are chained automatically, so directory-wide
specification of link libraries is rarely needed.

334
cmake-3.27.7-linux-x86_64/share/cmake-3.27/Help/command/list.rst Normal file
View File

@ -0,0 +1,334 @@
list
----
Operations on :ref:`semicolon-separated lists <CMake Language Lists>`.
Synopsis
^^^^^^^^
.. parsed-literal::
`Reading`_
list(`LENGTH`_ <list> <out-var>)
list(`GET`_ <list> <element index> [<index> ...] <out-var>)
list(`JOIN`_ <list> <glue> <out-var>)
list(`SUBLIST`_ <list> <begin> <length> <out-var>)
`Search`_
list(`FIND`_ <list> <value> <out-var>)
`Modification`_
list(`APPEND`_ <list> [<element>...])
list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>)
list(`INSERT`_ <list> <index> [<element>...])
list(`POP_BACK`_ <list> [<out-var>...])
list(`POP_FRONT`_ <list> [<out-var>...])
list(`PREPEND`_ <list> [<element>...])
list(`REMOVE_ITEM`_ <list> <value>...)
list(`REMOVE_AT`_ <list> <index>...)
list(`REMOVE_DUPLICATES`_ <list>)
list(`TRANSFORM`_ <list> <ACTION> [...])
`Ordering`_
list(`REVERSE`_ <list>)
list(`SORT`_ <list> [...])
Introduction
^^^^^^^^^^^^
The list subcommands :cref:`APPEND`, :cref:`INSERT`, :cref:`FILTER`,
:cref:`PREPEND`, :cref:`POP_BACK`, :cref:`POP_FRONT`, :cref:`REMOVE_AT`,
:cref:`REMOVE_ITEM`, :cref:`REMOVE_DUPLICATES`, :cref:`REVERSE` and
:cref:`SORT` may create new values for the list within the current CMake
variable scope. Similar to the :command:`set` command, the ``list`` command
creates new variable values in the current scope, even if the list itself is
actually defined in a parent scope. To propagate the results of these
operations upwards, use :command:`set` with ``PARENT_SCOPE``,
:command:`set` with ``CACHE INTERNAL``, or some other means of value
propagation.
.. note::
A list in cmake is a ``;`` separated group of strings. To create a
list, the :command:`set` command can be used. For example,
``set(var a b c d e)`` creates a list with ``a;b;c;d;e``, and
``set(var "a b c d e")`` creates a string or a list with one item in it.
(Note that macro arguments are not variables, and therefore cannot be used
in ``LIST`` commands.)
Individual elements may not contain an unequal number of ``[`` and ``]``
characters, and may not end in a backslash (``\``).
See :ref:`semicolon-separated lists <CMake Language Lists>` for details.
.. note::
When specifying index values, if ``<element index>`` is 0 or greater, it
is indexed from the beginning of the list, with 0 representing the
first list element. If ``<element index>`` is -1 or lesser, it is indexed
from the end of the list, with -1 representing the last list element.
Be careful when counting with negative indices: they do not start from
0. -0 is equivalent to 0, the first list element.
Reading
^^^^^^^
.. signature::
list(LENGTH <list> <output variable>)
Returns the list's length.
.. signature::
list(GET <list> <element index> [<element index> ...] <output variable>)
Returns the list of elements specified by indices from the list.
.. signature:: list(JOIN <list> <glue> <output variable>)
.. versionadded:: 3.12
Returns a string joining all list's elements using the glue string.
To join multiple strings, which are not part of a list,
use :command:`string(JOIN)`.
.. signature::
list(SUBLIST <list> <begin> <length> <output variable>)
.. versionadded:: 3.12
Returns a sublist of the given list.
If ``<length>`` is 0, an empty list will be returned.
If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then
the remaining elements of the list starting at ``<begin>`` will be returned.
Search
^^^^^^
.. signature::
list(FIND <list> <value> <output variable>)
Returns the index of the element specified in the list
or ``-1`` if it wasn't found.
Modification
^^^^^^^^^^^^
.. signature::
list(APPEND <list> [<element> ...])
Appends elements to the list. If no variable named ``<list>`` exists in the
current scope its value is treated as empty and the elements are appended to
that empty list.
.. signature::
list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
.. versionadded:: 3.6
Includes or removes items from the list that match the mode's pattern.
In ``REGEX`` mode, items will be matched against the given regular expression.
For more information on regular expressions look under
:ref:`string(REGEX) <Regex Specification>`.
.. signature::
list(INSERT <list> <element_index> <element> [<element> ...])
Inserts elements to the list to the specified index. It is an
error to specify an out-of-range index. Valid indexes are 0 to `N`
where `N` is the length of the list, inclusive. An empty list
has length 0. If no variable named ``<list>`` exists in the
current scope its value is treated as empty and the elements are
inserted in that empty list.
.. signature::
list(POP_BACK <list> [<out-var>...])
.. versionadded:: 3.15
If no variable name is given, removes exactly one element. Otherwise,
with `N` variable names provided, assign the last `N` elements' values
to the given variables and then remove the last `N` values from
``<list>``.
.. signature::
list(POP_FRONT <list> [<out-var>...])
.. versionadded:: 3.15
If no variable name is given, removes exactly one element. Otherwise,
with `N` variable names provided, assign the first `N` elements' values
to the given variables and then remove the first `N` values from
``<list>``.
.. signature::
list(PREPEND <list> [<element> ...])
.. versionadded:: 3.15
Insert elements to the 0th position in the list. If no variable named
``<list>`` exists in the current scope its value is treated as empty and
the elements are prepended to that empty list.
.. signature::
list(REMOVE_ITEM <list> <value> [<value> ...])
Removes all instances of the given items from the list.
.. signature::
list(REMOVE_AT <list> <index> [<index> ...])
Removes items at given indices from the list.
.. signature::
list(REMOVE_DUPLICATES <list>)
Removes duplicated items in the list. The relative order of items
is preserved, but if duplicates are encountered,
only the first instance is preserved.
.. signature::
list(TRANSFORM <list> <ACTION> [<SELECTOR>]
[OUTPUT_VARIABLE <output variable>])
.. versionadded:: 3.12
Transforms the list by applying an ``<ACTION>`` to all or, by specifying a
``<SELECTOR>``, to the selected elements of the list, storing the result
in-place or in the specified output variable.
.. note::
The ``TRANSFORM`` sub-command does not change the number of elements in the
list. If a ``<SELECTOR>`` is specified, only some elements will be changed,
the other ones will remain the same as before the transformation.
``<ACTION>`` specifies the action to apply to the elements of the list.
The actions have exactly the same semantics as sub-commands of the
:command:`string` command. ``<ACTION>`` must be one of the following:
:command:`APPEND <string(APPEND)>`, :command:`PREPEND <string(PREPEND)>`
Append, prepend specified value to each element of the list.
.. signature::
list(TRANSFORM <list> (APPEND|PREPEND) <value> ...)
:target: TRANSFORM_APPEND
:command:`TOLOWER <string(TOLOWER)>`, :command:`TOUPPER <string(TOUPPER)>`
Convert each element of the list to lower, upper characters.
.. signature::
list(TRANSFORM <list> (TOLOWER|TOUPPER) ...)
:target: TRANSFORM_TOLOWER
:command:`STRIP <string(STRIP)>`
Remove leading and trailing spaces from each element of the list.
.. signature::
list(TRANSFORM <list> STRIP ...)
:target: TRANSFORM_STRIP
:command:`GENEX_STRIP <string(GENEX_STRIP)>`
Strip any
:manual:`generator expressions <cmake-generator-expressions(7)>`
from each element of the list.
.. signature::
list(TRANSFORM <list> GENEX_STRIP ...)
:target: TRANSFORM_GENEX_STRIP
:command:`REPLACE <string(REGEX REPLACE)>`:
Match the regular expression as many times as possible and substitute
the replacement expression for the match for each element of the list
(same semantic as :command:`string(REGEX REPLACE)`).
.. signature::
list(TRANSFORM <list> REPLACE <regular_expression>
<replace_expression> ...)
:target: TRANSFORM_REPLACE
``<SELECTOR>`` determines which elements of the list will be transformed.
Only one type of selector can be specified at a time.
When given, ``<SELECTOR>`` must be one of the following:
``AT``
Specify a list of indexes.
.. code-block:: cmake
list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
``FOR``
Specify a range with, optionally,
an increment used to iterate over the range.
.. code-block:: cmake
list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
``REGEX``
Specify a regular expression.
Only elements matching the regular expression will be transformed.
.. code-block:: cmake
list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
Ordering
^^^^^^^^
.. signature::
list(REVERSE <list>)
Reverses the contents of the list in-place.
.. signature::
list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
Sorts the list in-place alphabetically.
.. versionadded:: 3.13
Added the ``COMPARE``, ``CASE``, and ``ORDER`` options.
.. versionadded:: 3.18
Added the ``COMPARE NATURAL`` option.
Use the ``COMPARE`` keyword to select the comparison method for sorting.
The ``<compare>`` option should be one of:
``STRING``
Sorts a list of strings alphabetically.
This is the default behavior if the ``COMPARE`` option is not given.
``FILE_BASENAME``
Sorts a list of pathnames of files by their basenames.
``NATURAL``
Sorts a list of strings using natural order
(see ``strverscmp(3)`` manual), i.e. such that contiguous digits
are compared as whole numbers.
For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1`
will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL``
comparison is selected where it will be sorted as
`1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison.
Use the ``CASE`` keyword to select a case sensitive or case insensitive
sort mode. The ``<case>`` option should be one of:
``SENSITIVE``
List items are sorted in a case-sensitive manner.
This is the default behavior if the ``CASE`` option is not given.
``INSENSITIVE``
List items are sorted case insensitively. The order of
items which differ only by upper/lowercase is not specified.
To control the sort order, the ``ORDER`` keyword can be given.
The ``<order>`` option should be one of:
``ASCENDING``
Sorts the list in ascending order.
This is the default behavior when the ``ORDER`` option is not given.
``DESCENDING``
Sorts the list in descending order.

Some files were not shown because too many files have changed in this diff Show More