Uploaded Test files
This commit is contained in:
parent
f584ad9d97
commit
2e81cb7d99
16627 changed files with 2065359 additions and 102444 deletions
44
venv/Lib/site-packages/cmake/data/share/aclocal/cmake.m4
Normal file
44
venv/Lib/site-packages/cmake/data/share/aclocal/cmake.m4
Normal 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
|
||||
# $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
|
||||
])
|
||||
|
|
@ -0,0 +1,166 @@
|
|||
# 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|--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
|
||||
;;
|
||||
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
|
||||
|
|
@ -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
|
||||
|
|
@ -0,0 +1,118 @@
|
|||
# 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
|
||||
;;
|
||||
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
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
|
||||
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
|
||||
``$<DEVICE_LINK:...>``
|
||||
:manual:`generator expression <cmake-generator-expressions(7)>` will be used
|
||||
only for the device link step. Options wrapped with ``$<HOST_LINK:...>``
|
||||
:manual:`generator expression <cmake-generator-expressions(7)>` will be used
|
||||
only for the host link step.
|
||||
|
|
@ -0,0 +1,161 @@
|
|||
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 path1 [path2 ... ENV var]]
|
||||
[PATHS path1 [path2 ... ENV var]]
|
||||
[PATH_SUFFIXES suffix1 [suffix2 ...]]
|
||||
[DOC "cache documentation string"]
|
||||
[REQUIRED]
|
||||
[NO_DEFAULT_PATH]
|
||||
[NO_PACKAGE_ROOT_PATH]
|
||||
[NO_CMAKE_PATH]
|
||||
[NO_CMAKE_ENVIRONMENT_PATH]
|
||||
[NO_SYSTEM_ENVIRONMENT_PATH]
|
||||
[NO_CMAKE_SYSTEM_PATH]
|
||||
[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 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``.
|
||||
The ``REQUIRED`` option stops 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.
|
||||
|
||||
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.
|
||||
|
||||
``PATH_SUFFIXES``
|
||||
Specify additional subdirectories to check below each directory
|
||||
location otherwise considered.
|
||||
|
||||
``DOC``
|
||||
Specify the documentation string for the ``<VAR>`` cache entry.
|
||||
|
||||
``REQUIRED``
|
||||
Stop processing with an error message if nothing is found.
|
||||
|
||||
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`
|
||||
|
||||
.. |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. Specifically, look in the
|
||||
:variable:`<PackageName>_ROOT` CMake variable and the
|
||||
:envvar:`<PackageName>_ROOT` environment variable.
|
||||
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``.
|
||||
See policy :policy:`CMP0074`.
|
||||
|
||||
* |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``.
|
||||
|
||||
* |CMAKE_PREFIX_PATH_XXX|
|
||||
* |CMAKE_XXX_PATH|
|
||||
* |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. This 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.
|
||||
|
||||
.. |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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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`.
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
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.
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
The final set of compile or link 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.
|
||||
While beneficial for individual options, the de-duplication step can break
|
||||
up option groups. For example, ``-D A -D B`` becomes ``-D 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:-D A" "SHELL:-D B"`` becomes ``-D A -D B``.
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
add_compile_definitions
|
||||
-----------------------
|
||||
|
||||
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).
|
||||
|
||||
Arguments to ``add_compile_definitions`` may use "generator expressions" with
|
||||
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
|
||||
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
|
||||
manual for more on defining buildsystem properties.
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
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.
|
||||
|
||||
Arguments
|
||||
^^^^^^^^^
|
||||
|
||||
Arguments to ``add_compile_options`` may use "generator expressions" with
|
||||
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
|
||||
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
|
||||
manual for more on defining buildsystem properties.
|
||||
|
||||
.. 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 and all warnings as errors
|
||||
add_compile_options(/W4 /WX)
|
||||
else()
|
||||
# lots of warnings and all warnings as errors
|
||||
add_compile_options(-Wall -Wextra -pedantic -Werror)
|
||||
endif()
|
||||
|
||||
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.
|
||||
|
||||
The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
|
||||
source file.
|
||||
|
|
@ -0,0 +1,281 @@
|
|||
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])
|
||||
|
||||
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 two 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).
|
||||
In makefile terms this creates a new target in the following form::
|
||||
|
||||
OUTPUT: MAIN_DEPENDENCY DEPENDS
|
||||
COMMAND
|
||||
|
||||
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.
|
||||
The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY``
|
||||
options are currently ignored when APPEND is given, but may be
|
||||
used in the future.
|
||||
|
||||
``BYPRODUCTS``
|
||||
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.
|
||||
|
||||
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``.
|
||||
|
||||
``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).
|
||||
* 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 ``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 a target is used as a command to execute or is mentioned in a
|
||||
generator expression as 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. However this 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.
|
||||
|
||||
``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.
|
||||
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.
|
||||
|
||||
Arguments to ``DEPENDS`` may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
|
||||
``COMMAND_EXPAND_LISTS``
|
||||
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.
|
||||
|
||||
``JOB_POOL``
|
||||
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.
|
||||
If an output name is a relative path it will be interpreted
|
||||
relative to the build tree directory corresponding to the
|
||||
current source directory.
|
||||
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.
|
||||
|
||||
``USES_TERMINAL``
|
||||
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.
|
||||
|
||||
Arguments to ``WORKING_DIRECTORY`` may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
|
||||
``DEPFILE``
|
||||
Specify a ``.d`` depfile for the :generator:`Ninja` generator.
|
||||
A ``.d`` file holds dependencies usually emitted by the custom
|
||||
command itself.
|
||||
Using ``DEPFILE`` with other generators than Ninja is an error.
|
||||
|
||||
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] [USES_TERMINAL]
|
||||
[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``
|
||||
On :ref:`Visual Studio Generators`, run before any other rules are
|
||||
executed within the target.
|
||||
On other generators, run just before ``PRE_LINK`` commands.
|
||||
``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.
|
||||
|
||||
.. 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 2010 (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.
|
||||
|
|
@ -0,0 +1,149 @@
|
|||
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``
|
||||
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.
|
||||
|
||||
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``.
|
||||
|
||||
``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).
|
||||
* 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 ``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 a target is used as a command to execute or is mentioned in a
|
||||
generator expression as a command argument, a target-level dependency
|
||||
will be added automatically so that the mentioned target will be built
|
||||
before this custom target.
|
||||
|
||||
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.
|
||||
|
||||
``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.
|
||||
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``
|
||||
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``
|
||||
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``
|
||||
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.
|
||||
|
||||
Arguments to ``WORKING_DIRECTORY`` may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
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 the :manual:`cmake-buildsystem(7)` manual for more on defining
|
||||
buildsystem properties.
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
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.
|
||||
|
||||
See the ``DEPENDS`` option of :command:`add_custom_target` and
|
||||
:command:`add_custom_command` commands for adding file-level
|
||||
dependencies in custom rules. See the :prop_sf:`OBJECT_DEPENDS`
|
||||
source file property to add file-level dependencies to object files.
|
||||
|
|
@ -0,0 +1,99 @@
|
|||
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 source files can be omitted
|
||||
here if they are added later using :command:`target_sources`.) 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>``).
|
||||
|
||||
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.
|
||||
|
||||
Source arguments to ``add_executable`` may use "generator expressions" with
|
||||
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
|
||||
manual for available expressions. 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``.
|
||||
|
||||
An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>`
|
||||
has scope in the directory in which the alias 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 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.
|
||||
|
|
@ -0,0 +1,187 @@
|
|||
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]
|
||||
[source1] [source2 ...])
|
||||
|
||||
Adds a library target called ``<name>`` to be built from the source files
|
||||
listed in the command invocation. (The source files can be omitted here
|
||||
if they are added later using :command:`target_sources`.) 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``).
|
||||
|
||||
``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`` or ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK`
|
||||
target property to create an macOS 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.
|
||||
|
||||
Source arguments to ``add_library`` may use "generator expressions" with
|
||||
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
|
||||
manual for available expressions. 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 Libraries
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
|
||||
[GLOBAL])
|
||||
|
||||
An :ref:`IMPORTED library target <Imported Targets>` references a library
|
||||
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`` 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 most important properties are:
|
||||
|
||||
* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration
|
||||
variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the
|
||||
location of the main library file on disk.
|
||||
* :prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`)
|
||||
for object libraries, specifies the locations of object files on disk.
|
||||
* :prop_tgt:`PUBLIC_HEADER` files to be installed during :command:`install` invocation
|
||||
|
||||
See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
|
||||
for more information.
|
||||
|
||||
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 Libraries
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_library(<name> OBJECT <src>...)
|
||||
|
||||
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 :command:`add_library` or
|
||||
:command:`add_executable` may reference the objects using an expression of the
|
||||
form ``$<TARGET_OBJECTS:objlib>`` 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
|
||||
``$<TARGET_OBJECTS:objlib>``.
|
||||
|
||||
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``.
|
||||
|
||||
An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>`
|
||||
has scope in the directory in which the alias 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.
|
||||
|
||||
Interface Libraries
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
|
||||
|
||||
Creates an :ref:`Interface Library <Interface Libraries>`. An ``INTERFACE``
|
||||
library target does not directly create build output, though it may
|
||||
have properties set on it and it may be installed, exported and
|
||||
imported. Typically the ``INTERFACE_*`` properties are populated on
|
||||
the 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`` :ref:`Imported Target <Imported Targets>` may also be
|
||||
created with this signature. An ``IMPORTED`` library target references a
|
||||
library defined outside the project. 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`.
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
add_link_options
|
||||
----------------
|
||||
|
||||
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.
|
||||
|
||||
Arguments to ``add_link_options`` may use "generator expressions" with
|
||||
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
|
||||
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
|
||||
manual for more on defining buildsystem properties.
|
||||
|
||||
.. include:: DEVICE_LINK_OPTIONS.txt
|
||||
|
||||
.. include:: OPTIONS_SHELL.txt
|
||||
|
||||
.. include:: LINK_OPTIONS_LINKER.txt
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
add_subdirectory
|
||||
----------------
|
||||
|
||||
Add a subdirectory to the build.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
|
||||
|
||||
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 VS 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.
|
||||
|
|
@ -0,0 +1,76 @@
|
|||
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 not contain spaces,
|
||||
quotes, or other characters special in CMake syntax. The 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.
|
||||
|
||||
``CONFIGURATIONS``
|
||||
Restrict execution of the test only to the named configurations.
|
||||
|
||||
``WORKING_DIRECTORY``
|
||||
Set the :prop_test:`WORKING_DIRECTORY` test property to
|
||||
specify the working directory in which to execute the test.
|
||||
If not specified the test will be run with the current working
|
||||
directory set to the build directory corresponding to the
|
||||
current source directory.
|
||||
|
||||
``COMMAND_EXPAND_LISTS``
|
||||
Lists in ``COMMAND`` arguments will be expanded, including those
|
||||
created with
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
|
||||
The given test command is expected to exit with code ``0`` to pass and
|
||||
non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test
|
||||
property is set. Any output written to stdout or stderr will be
|
||||
captured by :manual:`ctest(1)` but does not affect the pass/fail status
|
||||
unless the :prop_test:`PASS_REGULAR_EXPRESSION`,
|
||||
:prop_test:`FAIL_REGULAR_EXPRESSION` or
|
||||
:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used.
|
||||
|
||||
The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator
|
||||
expressions" with the syntax ``$<...>``. See the
|
||||
:manual:`cmake-generator-expressions(7)` manual for available expressions.
|
||||
|
||||
Example usage:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_test(NAME mytest
|
||||
COMMAND testDriver --config $<CONFIGURATION>
|
||||
--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``.
|
||||
|
||||
.. note::
|
||||
|
||||
CMake will generate tests only if the :command:`enable_testing`
|
||||
command has been invoked. The :module:`CTest` module invokes the
|
||||
command automatically unless the ``BUILD_TESTING`` option is turned
|
||||
``OFF``.
|
||||
|
||||
---------------------------------------------------------------------
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_test(<name> <command> [<arg>...])
|
||||
|
||||
Add a test called ``<name>`` with the given command-line. Unlike
|
||||
the above ``NAME`` signature no transformation is performed on the
|
||||
command-line to support target names or generator expressions.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
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>]
|
||||
[TARGET <target>]
|
||||
[PROJECT_NAME <projname>] # legacy, causes warning
|
||||
)
|
||||
|
||||
Sets the given ``<variable>`` to a command-line string of the form::
|
||||
|
||||
<cmake> --build . [--config <config>] [--target <target>...] [-- -i]
|
||||
|
||||
where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line
|
||||
tool, and ``<config>`` and ``<target>`` are the values provided to the
|
||||
``CONFIGURATION`` 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 ``cmake --build`` command line will launch the
|
||||
underlying build system tool.
|
||||
|
||||
.. 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 ``--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.
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
build_name
|
||||
----------
|
||||
|
||||
Disallowed since version 3.0. See CMake Policy :policy:`CMP0036`.
|
||||
|
||||
Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead.
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
cmake_host_system_information
|
||||
-----------------------------
|
||||
|
||||
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:
|
||||
|
||||
============================= ================================================
|
||||
Key Description
|
||||
============================= ================================================
|
||||
``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`` One if processor is 64Bit
|
||||
``HAS_FPU`` One if processor has floating point unit
|
||||
``HAS_MMX`` One if processor supports MMX instructions
|
||||
``HAS_MMX_PLUS`` One if processor supports Ext. MMX instructions
|
||||
``HAS_SSE`` One if processor supports SSE instructions
|
||||
``HAS_SSE2`` One if processor supports SSE2 instructions
|
||||
``HAS_SSE_FP`` One if processor supports SSE FP instructions
|
||||
``HAS_SSE_MMX`` One if processor supports SSE MMX instructions
|
||||
``HAS_AMD_3DNOW`` One if processor supports 3DNow instructions
|
||||
``HAS_AMD_3DNOW_PLUS`` One if processor supports 3DNow+ instructions
|
||||
``HAS_IA64`` One if IA64 processor emulating x86
|
||||
``HAS_SERIAL_NUMBER`` One if processor has serial number
|
||||
``PROCESSOR_SERIAL_NUMBER`` Processor serial number
|
||||
``PROCESSOR_NAME`` Human readable processor name
|
||||
``PROCESSOR_DESCRIPTION`` Human readable full processor description
|
||||
``OS_NAME`` See :variable:`CMAKE_HOST_SYSTEM_NAME`
|
||||
``OS_RELEASE`` The OS sub-type e.g. on Windows ``Professional``
|
||||
``OS_VERSION`` The OS build ID
|
||||
``OS_PLATFORM`` See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`
|
||||
============================= ================================================
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes.
|
||||
|
|
@ -0,0 +1,99 @@
|
|||
cmake_language
|
||||
--------------
|
||||
|
||||
Call meta-operations on CMake commands.
|
||||
|
||||
Synopsis
|
||||
^^^^^^^^
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
cmake_language(`CALL`_ <command> [<args>...])
|
||||
cmake_language(`EVAL`_ CODE <code>...)
|
||||
|
||||
Introduction
|
||||
^^^^^^^^^^^^
|
||||
|
||||
This command will call meta-operations on built-in CMake commands or
|
||||
those created via the :command:`macro` or :command:`function` commands.
|
||||
|
||||
``cmake_language`` does not introduce a new variable or policy scope.
|
||||
|
||||
Calling Commands
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
.. _CALL:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
cmake_language(CALL <command> [<args>...])
|
||||
|
||||
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``
|
||||
* ``while`` / ``endwhile``
|
||||
* ``foreach`` / ``endforeach``
|
||||
* ``function`` / ``endfunction``
|
||||
* ``macro`` / ``endmacro``
|
||||
|
||||
Evaluating Code
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. _EVAL:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
cmake_language(EVAL CODE <code>...)
|
||||
|
||||
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)
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
cmake_minimum_required
|
||||
----------------------
|
||||
|
||||
Require a minimum version of cmake.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
|
||||
|
||||
Sets the minimum required version of cmake for a project.
|
||||
Also updates the policy settings as explained below.
|
||||
|
||||
``<min>`` and the optional ``<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 ``<max>`` version, if specified, must be at least the
|
||||
``<min>`` version and affects policy settings as described below.
|
||||
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>``.
|
||||
|
||||
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. Such calls
|
||||
should not be made with the intention of having global effects.
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,109 @@
|
|||
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>)
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
|
||||
``<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``.
|
||||
|
|
@ -0,0 +1,108 @@
|
|||
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>])
|
||||
|
||||
``<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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,135 @@
|
|||
configure_file
|
||||
--------------
|
||||
|
||||
Copy a file to another location and modify its contents.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
configure_file(<input> <output>
|
||||
[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@`` or ``${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.
|
||||
Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with
|
||||
either ``#define VAR 1`` or ``#define VAR 0`` similarly.
|
||||
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.
|
||||
|
||||
``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:`include_directories` command to
|
||||
specify the output directory as an include directory:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
include_directories(${CMAKE_CURRENT_BINARY_DIR})
|
||||
|
||||
so that sources may include the header as ``#include <foo.h>``.
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
continue
|
||||
--------
|
||||
|
||||
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 a block
|
||||
in a :command:`foreach` or :command:`while` loop, and start at the top of
|
||||
the next iteration.
|
||||
|
||||
See also the :command:`break` command.
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
ctest_build
|
||||
-----------
|
||||
|
||||
Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
|
||||
|
||||
::
|
||||
|
||||
ctest_build([BUILD <build-dir>] [APPEND]
|
||||
[CONFIGURATION <config>]
|
||||
[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 ``-C <cfg>`` option given to the :manual:`ctest(1)`
|
||||
command will be used, if any.
|
||||
|
||||
``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. This was once used but is no longer needed.
|
||||
|
||||
``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>``
|
||||
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``
|
||||
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.
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
ctest_configure
|
||||
---------------
|
||||
|
||||
Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`.
|
||||
|
||||
::
|
||||
|
||||
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>``
|
||||
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``
|
||||
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.
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
ctest_coverage
|
||||
--------------
|
||||
|
||||
Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
|
||||
|
||||
::
|
||||
|
||||
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>``
|
||||
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``
|
||||
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.
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
ctest_empty_binary_directory
|
||||
----------------------------
|
||||
|
||||
empties the binary directory
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
ctest_memcheck
|
||||
--------------
|
||||
|
||||
Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.
|
||||
|
||||
::
|
||||
|
||||
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>]
|
||||
[TEST_LOAD <threshold>]
|
||||
[SCHEDULE_RANDOM <ON|OFF>]
|
||||
[STOP_TIME <time-of-day>]
|
||||
[RETURN_VALUE <result-var>]
|
||||
[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>``
|
||||
Store in the ``<defect-count-var>`` the number of defects found.
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
ctest_read_custom_files
|
||||
-----------------------
|
||||
|
||||
read CTestCustom files.
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
ctest_run_script
|
||||
----------------
|
||||
|
||||
runs a ctest -S script
|
||||
|
||||
::
|
||||
|
||||
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 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``.
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
ctest_sleep
|
||||
-----------
|
||||
|
||||
sleeps for some amount of time
|
||||
|
||||
::
|
||||
|
||||
ctest_sleep(<seconds>)
|
||||
|
||||
Sleep for given number of seconds.
|
||||
|
||||
::
|
||||
|
||||
ctest_sleep(<time1> <duration> <time2>)
|
||||
|
||||
Sleep for t=(time1 + duration - time2) seconds if t > 0.
|
||||
|
|
@ -0,0 +1,83 @@
|
|||
ctest_start
|
||||
-----------
|
||||
|
||||
Starts the testing for a given model
|
||||
|
||||
::
|
||||
|
||||
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. 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 ``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``
|
||||
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.
|
||||
|
|
@ -0,0 +1,104 @@
|
|||
ctest_submit
|
||||
------------
|
||||
|
||||
Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
|
||||
|
||||
::
|
||||
|
||||
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
|
||||
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>``
|
||||
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>``
|
||||
Store in the ``<result-var>`` variable the ID assigned to this build by
|
||||
CDash.
|
||||
|
||||
``HTTPHEADER <HTTP-header>``
|
||||
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>``
|
||||
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``
|
||||
Suppress all non-error messages that would have otherwise been
|
||||
printed to the console.
|
||||
|
||||
Submit to CDash Upload API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
|
||||
[SUBMIT_URL <url>]
|
||||
[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 accepts the ``SUBMIT_URL``, ``BUILD_ID``, ``HTTPHEADER``,
|
||||
``RETRY_COUNT``, ``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options
|
||||
as described above.
|
||||
|
|
@ -0,0 +1,144 @@
|
|||
ctest_test
|
||||
----------
|
||||
|
||||
Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
|
||||
|
||||
::
|
||||
|
||||
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>]
|
||||
[QUIET]
|
||||
)
|
||||
|
||||
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>``
|
||||
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>``
|
||||
Same as ``EXCLUDE_FIXTURE`` except only matching setup tests are excluded.
|
||||
|
||||
``EXCLUDE_FIXTURE_CLEANUP <regex>``
|
||||
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>``
|
||||
Specify a
|
||||
:ref:`resource specification file <ctest-resource-specification-file>`. See
|
||||
:ref:`ctest-resource-allocation` for more information.
|
||||
|
||||
``TEST_LOAD <threshold>``
|
||||
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 ``--test-load`` command-line argument to :manual:`ctest(1)`.
|
||||
See also the ``TestLoad`` setting in the :ref:`CTest Test Step`.
|
||||
|
||||
``REPEAT <mode>:<n>``
|
||||
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``
|
||||
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>``
|
||||
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``
|
||||
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`
|
||||
and :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables.
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
ctest_update
|
||||
------------
|
||||
|
||||
Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.
|
||||
|
||||
::
|
||||
|
||||
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>``
|
||||
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``
|
||||
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()``.
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
ctest_upload
|
||||
------------
|
||||
|
||||
Upload files to a dashboard server as a :ref:`Dashboard Client`.
|
||||
|
||||
::
|
||||
|
||||
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``
|
||||
Suppress any CTest-specific non-error output that would have been
|
||||
printed to the console otherwise.
|
||||
|
||||
``CAPTURE_CMAKE_ERROR <result-var>``
|
||||
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.
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
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...])
|
||||
|
||||
Defines one property in a scope for use with the :command:`set_property` and
|
||||
:command:`get_property` commands. This is primarily useful to associate
|
||||
documentation with property names that may be retrieved with the
|
||||
:command:`get_property` command. 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.
|
||||
Corresponding options to the :command:`get_property` command will retrieve
|
||||
the documentation.
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
else
|
||||
----
|
||||
|
||||
Starts the else portion of an if block.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
else([<condition>])
|
||||
|
||||
See the :command:`if` command.
|
||||
|
|
@ -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>``.
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
enable_language
|
||||
---------------
|
||||
Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
enable_language(<lang> [OPTIONAL] )
|
||||
|
||||
Enables support for the named language 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. Example languages
|
||||
are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, and ``ASM``.
|
||||
|
||||
If enabling ``ASM``, enable it last so that CMake can check whether
|
||||
compilers for other languages like ``C`` work for assembly too.
|
||||
|
||||
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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,129 @@
|
|||
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])
|
||||
|
||||
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.
|
||||
|
||||
Options:
|
||||
|
||||
``COMMAND``
|
||||
A child process command line.
|
||||
|
||||
CMake executes the child process using operating system APIs directly.
|
||||
All arguments are passed VERBATIM to the child process.
|
||||
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.)
|
||||
|
||||
If a sequential execution of multiple commands is required, use multiple
|
||||
:command:`execute_process` calls 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>``
|
||||
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.
|
||||
|
||||
``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.
|
||||
|
||||
``INPUT_FILE, OUTPUT_FILE``, ``ERROR_FILE``
|
||||
The file named will be attached to the standard input of the first
|
||||
process, standard output of the last process, or standard error of
|
||||
all processes, respectively. If the same file is named for both
|
||||
output and error then it will be used for both.
|
||||
|
||||
``OUTPUT_QUIET``, ``ERROR_QUIET``
|
||||
The standard output or standard error results will be quietly ignored.
|
||||
|
||||
``COMMAND_ECHO <where>``
|
||||
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>``
|
||||
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. Prior to CMake 3.11.0, only ``UTF8`` was accepted
|
||||
for this encoding. In CMake 3.11.0, ``UTF-8`` was added for consistency with
|
||||
the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention.
|
||||
|
||||
``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
|
||||
The standard output or standard error will not be exclusively redirected to
|
||||
the configured variables.
|
||||
|
||||
The output will be duplicated, it will be sent into the configured variables
|
||||
and also on standard output or standard error.
|
||||
|
||||
This is analogous to the ``tee`` Unix command.
|
||||
|
||||
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.
|
||||
|
||||
The :command:`execute_process` command is a newer more powerful version of
|
||||
:command:`exec_program`, but the old command has been kept for compatibility.
|
||||
Both commands run while CMake is processing the project prior to build
|
||||
system generation. Use :command:`add_custom_target` and
|
||||
:command:`add_custom_command` to create custom commands that run at
|
||||
build time.
|
||||
|
|
@ -0,0 +1,86 @@
|
|||
export
|
||||
------
|
||||
|
||||
Export targets from the build tree for use by outside projects.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
|
||||
|
||||
Creates a file ``<filename>`` that may be included by outside projects to
|
||||
import targets 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. If the ``NAMESPACE``
|
||||
option is given the ``<namespace>`` string will be prepended to all target
|
||||
names written to the file.
|
||||
|
||||
Target installations are associated with the export ``<export-name>``
|
||||
using the ``EXPORT`` option of the :command:`install(TARGETS)` command.
|
||||
|
||||
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 installation tree.
|
||||
|
||||
The properties set on the generated IMPORTED targets will have the
|
||||
same values as the final values of the input TARGETS.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
|
||||
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
|
||||
|
||||
This signature is similar to the ``EXPORT`` signature, but targets are listed
|
||||
explicitly rather than specified as an export-name. If the APPEND option is
|
||||
given the generated code will be appended to the file instead of overwriting it.
|
||||
The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the
|
||||
contents of the properties matching
|
||||
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
|
||||
policy CMP0022 is NEW. If a library target is included in the export
|
||||
but a target to which it links is not included the behavior is
|
||||
unspecified.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. 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.
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
|
||||
|
||||
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 CMP0022 is NEW for all
|
||||
targets given. A error will be issued if that policy is set to OLD for one
|
||||
of the targets.
|
||||
|
|
@ -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.
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,955 @@
|
|||
file
|
||||
----
|
||||
|
||||
File manipulation command.
|
||||
|
||||
Synopsis
|
||||
^^^^^^^^
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
`Reading`_
|
||||
file(`READ`_ <filename> <out-var> [...])
|
||||
file(`STRINGS`_ <filename> <out-var> [...])
|
||||
file(`\<HASH\> <HASH_>`_ <filename> <out-var>)
|
||||
file(`TIMESTAMP`_ <filename> <out-var> [...])
|
||||
file(`GET_RUNTIME_DEPENDENCIES`_ [...])
|
||||
|
||||
`Writing`_
|
||||
file({`WRITE`_ | `APPEND`_} <filename> <content>...)
|
||||
file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
|
||||
file(`GENERATE`_ OUTPUT <output-file> [...])
|
||||
file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...])
|
||||
|
||||
`Filesystem`_
|
||||
file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
|
||||
file(`RENAME`_ <oldname> <newname>)
|
||||
file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...])
|
||||
file(`MAKE_DIRECTORY`_ [<dir>...])
|
||||
file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
|
||||
file(`SIZE`_ <filename> <out-var>)
|
||||
file(`READ_SYMLINK`_ <linkname> <out-var>)
|
||||
file(`CREATE_LINK`_ <original> <linkname> [...])
|
||||
|
||||
`Path Conversion`_
|
||||
file(`RELATIVE_PATH`_ <out-var> <directory> <file>)
|
||||
file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>)
|
||||
|
||||
`Transfer`_
|
||||
file(`DOWNLOAD`_ <url> <file> [...])
|
||||
file(`UPLOAD`_ <file> <url> [...])
|
||||
|
||||
`Locking`_
|
||||
file(`LOCK`_ <path> [...])
|
||||
|
||||
`Archiving`_
|
||||
file(`ARCHIVE_CREATE`_ OUTPUT <archive> PATHS <paths>... [...])
|
||||
file(`ARCHIVE_EXTRACT`_ INPUT <archive> [...])
|
||||
|
||||
Reading
|
||||
^^^^^^^
|
||||
|
||||
.. _READ:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(READ <filename> <variable>
|
||||
[OFFSET <offset>] [LIMIT <max-in>] [HEX])
|
||||
|
||||
Read content from a file called ``<filename>`` and store it in a
|
||||
``<variable>``. Optionally start from the given ``<offset>`` and
|
||||
read at most ``<max-in>`` bytes. The ``HEX`` option causes data to
|
||||
be converted to a hexadecimal representation (useful for binary data). If the
|
||||
``HEX`` option is specified, letters in the output (``a`` through ``f``) are in
|
||||
lowercase.
|
||||
|
||||
.. _STRINGS:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(STRINGS <filename> <variable> [<options>...])
|
||||
|
||||
Parse a list of ASCII strings from ``<filename>`` and store it in
|
||||
``<variable>``. Binary data in the file are ignored. Carriage return
|
||||
(``\r``, CR) characters are ignored. The options are:
|
||||
|
||||
``LENGTH_MAXIMUM <max-len>``
|
||||
Consider only strings of at most a given length.
|
||||
|
||||
``LENGTH_MINIMUM <min-len>``
|
||||
Consider only strings of at least a given length.
|
||||
|
||||
``LIMIT_COUNT <max-num>``
|
||||
Limit the number of distinct strings to be extracted.
|
||||
|
||||
``LIMIT_INPUT <max-in>``
|
||||
Limit the number of input bytes to read from the file.
|
||||
|
||||
``LIMIT_OUTPUT <max-out>``
|
||||
Limit the number of total bytes to store in the ``<variable>``.
|
||||
|
||||
``NEWLINE_CONSUME``
|
||||
Treat newline characters (``\n``, LF) as part of string content
|
||||
instead of terminating at them.
|
||||
|
||||
``NO_HEX_CONVERSION``
|
||||
Intel Hex and Motorola S-record files are automatically converted to
|
||||
binary while reading unless this option is given.
|
||||
|
||||
``REGEX <regex>``
|
||||
Consider only strings that match the given regular expression.
|
||||
|
||||
``ENCODING <encoding-type>``
|
||||
Consider strings of a given encoding. Currently supported encodings are:
|
||||
UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. If the ENCODING option
|
||||
is not provided and the file has a Byte Order Mark, the ENCODING option
|
||||
will be defaulted to respect the Byte Order Mark.
|
||||
|
||||
For example, the code
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(STRINGS myfile.txt myfile)
|
||||
|
||||
stores a list in the variable ``myfile`` in which each item is a line
|
||||
from the input file.
|
||||
|
||||
.. _HASH:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(<HASH> <filename> <variable>)
|
||||
|
||||
Compute a cryptographic hash of the content of ``<filename>`` and
|
||||
store it in a ``<variable>``. The supported ``<HASH>`` algorithm names
|
||||
are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
|
||||
command.
|
||||
|
||||
.. _TIMESTAMP:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(TIMESTAMP <filename> <variable> [<format>] [UTC])
|
||||
|
||||
Compute a string representation of the modification time of ``<filename>``
|
||||
and store it in ``<variable>``. Should the command be unable to obtain a
|
||||
timestamp variable will be set to the empty string ("").
|
||||
|
||||
See the :command:`string(TIMESTAMP)` command for documentation of
|
||||
the ``<format>`` and ``UTC`` options.
|
||||
|
||||
.. _GET_RUNTIME_DEPENDENCIES:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(GET_RUNTIME_DEPENDENCIES
|
||||
[RESOLVED_DEPENDENCIES_VAR <deps_var>]
|
||||
[UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
|
||||
[CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
|
||||
[EXECUTABLES [<executable_files>...]]
|
||||
[LIBRARIES [<library_files>...]]
|
||||
[MODULES [<module_files>...]]
|
||||
[DIRECTORIES [<directories>...]]
|
||||
[BUNDLE_EXECUTABLE <bundle_executable_file>]
|
||||
[PRE_INCLUDE_REGEXES [<regexes>...]]
|
||||
[PRE_EXCLUDE_REGEXES [<regexes>...]]
|
||||
[POST_INCLUDE_REGEXES [<regexes>...]]
|
||||
[POST_EXCLUDE_REGEXES [<regexes>...]]
|
||||
)
|
||||
|
||||
Recursively get the list of libraries depended on by the given files.
|
||||
|
||||
Please note that this sub-command is not intended to be used in project mode.
|
||||
Instead, use it in an :command:`install(CODE)` or :command:`install(SCRIPT)`
|
||||
block. For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(CODE [[
|
||||
file(GET_RUNTIME_DEPENDENCIES
|
||||
# ...
|
||||
)
|
||||
]])
|
||||
|
||||
The arguments are as follows:
|
||||
|
||||
``RESOLVED_DEPENDENCIES_VAR <deps_var>``
|
||||
Name of the variable in which to store the list of resolved dependencies.
|
||||
|
||||
``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>``
|
||||
Name of the variable in which to store the list of unresolved dependencies.
|
||||
If this variable is not specified, and there are any unresolved dependencies,
|
||||
an error is issued.
|
||||
|
||||
``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>``
|
||||
Variable prefix in which to store conflicting dependency information.
|
||||
Dependencies are conflicting if two files with the same name are found in
|
||||
two different directories. The list of filenames that conflict are stored in
|
||||
``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list of paths
|
||||
that were found for that filename are stored in
|
||||
``<conflicting_deps_prefix>_<filename>``.
|
||||
|
||||
``EXECUTABLES <executable_files>``
|
||||
List of executable files to read for dependencies. These are executables that
|
||||
are typically created with :command:`add_executable`, but they do not have to
|
||||
be created by CMake. On Apple platforms, the paths to these files determine
|
||||
the value of ``@executable_path`` when recursively resolving the libraries.
|
||||
Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here
|
||||
will result in undefined behavior.
|
||||
|
||||
``LIBRARIES <library_files>``
|
||||
List of library files to read for dependencies. These are libraries that are
|
||||
typically created with :command:`add_library(SHARED)`, but they do not have
|
||||
to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE``
|
||||
libraries, or executables here will result in undefined behavior.
|
||||
|
||||
``MODULES <module_files>``
|
||||
List of loadable module files to read for dependencies. These are modules
|
||||
that are typically created with :command:`add_library(MODULE)`, but they do
|
||||
not have to be created by CMake. They are typically used by calling
|
||||
``dlopen()`` at runtime rather than linked at link time with ``ld -l``.
|
||||
Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here
|
||||
will result in undefined behavior.
|
||||
|
||||
``DIRECTORIES <directories>``
|
||||
List of additional directories to search for dependencies. On Linux
|
||||
platforms, these directories are searched if the dependency is not found in
|
||||
any of the other usual paths. If it is found in such a directory, a warning
|
||||
is issued, because it means that the file is incomplete (it does not list all
|
||||
of the directories that contain its dependencies). On Windows platforms,
|
||||
these directories are searched if the dependency is not found in any of the
|
||||
other search paths, but no warning is issued, because searching other paths
|
||||
is a normal part of Windows dependency resolution. On Apple platforms, this
|
||||
argument has no effect.
|
||||
|
||||
``BUNDLE_EXECUTABLE <bundle_executable_file>``
|
||||
Executable to treat as the "bundle executable" when resolving libraries. On
|
||||
Apple platforms, this argument determines the value of ``@executable_path``
|
||||
when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files.
|
||||
It has no effect on ``EXECUTABLES`` files. On other platforms, it has no
|
||||
effect. This is typically (but not always) one of the executables in the
|
||||
``EXECUTABLES`` argument which designates the "main" executable of the
|
||||
package.
|
||||
|
||||
The following arguments specify filters for including or excluding libraries to
|
||||
be resolved. See below for a full description of how they work.
|
||||
|
||||
``PRE_INCLUDE_REGEXES <regexes>``
|
||||
List of pre-include regexes through which to filter the names of
|
||||
not-yet-resolved dependencies.
|
||||
|
||||
``PRE_EXCLUDE_REGEXES <regexes>``
|
||||
List of pre-exclude regexes through which to filter the names of
|
||||
not-yet-resolved dependencies.
|
||||
|
||||
``POST_INCLUDE_REGEXES <regexes>``
|
||||
List of post-include regexes through which to filter the names of resolved
|
||||
dependencies.
|
||||
|
||||
``POST_EXCLUDE_REGEXES <regexes>``
|
||||
List of post-exclude regexes through which to filter the names of resolved
|
||||
dependencies.
|
||||
|
||||
These arguments can be used to exclude unwanted system libraries when
|
||||
resolving the dependencies, or to include libraries from a specific
|
||||
directory. The filtering works as follows:
|
||||
|
||||
1. If the not-yet-resolved dependency matches any of the
|
||||
``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency
|
||||
resolution proceeds to step 4.
|
||||
2. If the not-yet-resolved dependency matches any of the
|
||||
``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency.
|
||||
3. Otherwise, dependency resolution proceeds.
|
||||
4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to
|
||||
the linking rules of the platform (see below).
|
||||
5. If the dependency is found, and its full path matches one of the
|
||||
``POST_INCLUDE_REGEXES``, the full path is added to the resolved
|
||||
dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves
|
||||
that library's own dependencies. Otherwise, resolution proceeds to step 6.
|
||||
6. If the dependency is found, but its full path matches one of the
|
||||
``POST_EXCLUDE_REGEXES``, it is not added to the resolved dependencies, and
|
||||
dependency resolution stops for that dependency.
|
||||
7. If the dependency is found, and its full path does not match either
|
||||
``POST_INCLUDE_REGEXES`` or ``POST_EXCLUDE_REGEXES``, the full path is added
|
||||
to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)``
|
||||
recursively resolves that library's own dependencies.
|
||||
|
||||
Different platforms have different rules for how dependencies are resolved.
|
||||
These specifics are described here.
|
||||
|
||||
On Linux platforms, library resolution works as follows:
|
||||
|
||||
1. If the depending file does not have any ``RUNPATH`` entries, and the library
|
||||
exists in one of the depending file's ``RPATH`` entries, or its parents', in
|
||||
that order, the dependency is resolved to that file.
|
||||
2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the
|
||||
library exists in one of those entries, the dependency is resolved to that
|
||||
file.
|
||||
3. Otherwise, if the library exists in one of the directories listed by
|
||||
``ldconfig``, the dependency is resolved to that file.
|
||||
4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, the
|
||||
dependency is resolved to that file. In this case, a warning is issued,
|
||||
because finding a file in one of the ``DIRECTORIES`` means that the
|
||||
depending file is not complete (it does not list all the directories from
|
||||
which it pulls dependencies).
|
||||
5. Otherwise, the dependency is unresolved.
|
||||
|
||||
On Windows platforms, library resolution works as follows:
|
||||
|
||||
1. The dependent DLL name is converted to lowercase. Windows DLL names are
|
||||
case-insensitive, and some linkers mangle the case of the DLL dependency
|
||||
names. However, this makes it more difficult for ``PRE_INCLUDE_REGEXES``,
|
||||
``PRE_EXCLUDE_REGEXES``, ``POST_INCLUDE_REGEXES``, and
|
||||
``POST_EXCLUDE_REGEXES`` to properly filter DLL names - every regex would
|
||||
have to check for both uppercase and lowercase letters. For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(GET_RUNTIME_DEPENDENCIES
|
||||
# ...
|
||||
PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
|
||||
)
|
||||
|
||||
Converting the DLL name to lowercase allows the regexes to only match
|
||||
lowercase names, thus simplifying the regex. For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(GET_RUNTIME_DEPENDENCIES
|
||||
# ...
|
||||
PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
|
||||
)
|
||||
|
||||
This regex will match ``mylibrary.dll`` regardless of how it is cased,
|
||||
either on disk or in the depending file. (For example, it will match
|
||||
``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.)
|
||||
|
||||
Please note that the directory portion of any resolved DLLs retains its
|
||||
casing and is not converted to lowercase. Only the filename portion is
|
||||
converted.
|
||||
|
||||
2. (**Not yet implemented**) If the depending file is a Windows Store app, and
|
||||
the dependency is listed as a dependency in the application's package
|
||||
manifest, the dependency is resolved to that file.
|
||||
3. Otherwise, if the library exists in the same directory as the depending
|
||||
file, the dependency is resolved to that file.
|
||||
4. Otherwise, if the library exists in either the operating system's
|
||||
``system32`` directory or the ``Windows`` directory, in that order, the
|
||||
dependency is resolved to that file.
|
||||
5. Otherwise, if the library exists in one of the directories specified by
|
||||
``DIRECTORIES``, in the order they are listed, the dependency is resolved to
|
||||
that file. In this case, a warning is not issued, because searching other
|
||||
directories is a normal part of Windows library resolution.
|
||||
6. Otherwise, the dependency is unresolved.
|
||||
|
||||
On Apple platforms, library resolution works as follows:
|
||||
|
||||
1. If the dependency starts with ``@executable_path/``, and an ``EXECUTABLES``
|
||||
argument is in the process of being resolved, and replacing
|
||||
``@executable_path/`` with the directory of the executable yields an
|
||||
existing file, the dependency is resolved to that file.
|
||||
2. Otherwise, if the dependency starts with ``@executable_path/``, and there is
|
||||
a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` with
|
||||
the directory of the bundle executable yields an existing file, the
|
||||
dependency is resolved to that file.
|
||||
3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing
|
||||
``@loader_path/`` with the directory of the depending file yields an
|
||||
existing file, the dependency is resolved to that file.
|
||||
4. Otherwise, if the dependency starts with ``@rpath/``, and replacing
|
||||
``@rpath/`` with one of the ``RPATH`` entries of the depending file yields
|
||||
an existing file, the dependency is resolved to that file. Note that
|
||||
``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/``
|
||||
also have these items replaced with the appropriate path.
|
||||
5. Otherwise, if the dependency is an absolute file that exists, the dependency
|
||||
is resolved to that file.
|
||||
6. Otherwise, the dependency is unresolved.
|
||||
|
||||
This function accepts several variables that determine which tool is used for
|
||||
dependency resolution:
|
||||
|
||||
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
|
||||
|
||||
Determines which operating system and executable format the files are built
|
||||
for. This could be one of several values:
|
||||
|
||||
* ``linux+elf``
|
||||
* ``windows+pe``
|
||||
* ``macos+macho``
|
||||
|
||||
If this variable is not specified, it is determined automatically by system
|
||||
introspection.
|
||||
|
||||
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
|
||||
|
||||
Determines the tool to use for dependency resolution. It could be one of
|
||||
several values, depending on the value of
|
||||
:variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`:
|
||||
|
||||
================================================= =============================================
|
||||
``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL``
|
||||
================================================= =============================================
|
||||
``linux+elf`` ``objdump``
|
||||
``windows+pe`` ``dumpbin``
|
||||
``windows+pe`` ``objdump``
|
||||
``macos+macho`` ``otool``
|
||||
================================================= =============================================
|
||||
|
||||
If this variable is not specified, it is determined automatically by system
|
||||
introspection.
|
||||
|
||||
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
|
||||
|
||||
Determines the path to the tool to use for dependency resolution. This is the
|
||||
actual path to ``objdump``, ``dumpbin``, or ``otool``.
|
||||
|
||||
If this variable is not specified, it is determined by the value of
|
||||
``CMAKE_OBJDUMP`` if set, else by system introspection.
|
||||
|
||||
Writing
|
||||
^^^^^^^
|
||||
|
||||
.. _WRITE:
|
||||
.. _APPEND:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(WRITE <filename> <content>...)
|
||||
file(APPEND <filename> <content>...)
|
||||
|
||||
Write ``<content>`` into a file called ``<filename>``. If the file does
|
||||
not exist, it will be created. If the file already exists, ``WRITE``
|
||||
mode will overwrite it and ``APPEND`` mode will append to the end.
|
||||
Any directories in the path specified by ``<filename>`` that do not
|
||||
exist will be created.
|
||||
|
||||
If the file is a build input, use the :command:`configure_file` command
|
||||
to update the file only when its content changes.
|
||||
|
||||
.. _TOUCH:
|
||||
.. _TOUCH_NOCREATE:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(TOUCH [<files>...])
|
||||
file(TOUCH_NOCREATE [<files>...])
|
||||
|
||||
Create a file with no content if it does not yet exist. If the file already
|
||||
exists, its access and/or modification will be updated to the time when the
|
||||
function call is executed.
|
||||
|
||||
Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file
|
||||
does not exist it will be silently ignored.
|
||||
|
||||
With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be
|
||||
modified.
|
||||
|
||||
.. _GENERATE:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(GENERATE OUTPUT output-file
|
||||
<INPUT input-file|CONTENT content>
|
||||
[CONDITION expression])
|
||||
|
||||
Generate an output file for each build configuration supported by the current
|
||||
:manual:`CMake Generator <cmake-generators(7)>`. Evaluate
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`
|
||||
from the input content to produce the output content. The options are:
|
||||
|
||||
``CONDITION <condition>``
|
||||
Generate the output file for a particular configuration only if
|
||||
the condition is true. The condition must be either ``0`` or ``1``
|
||||
after evaluating generator expressions.
|
||||
|
||||
``CONTENT <content>``
|
||||
Use the content given explicitly as input.
|
||||
|
||||
``INPUT <input-file>``
|
||||
Use the content from a given file as input.
|
||||
A relative path is treated with respect to the value of
|
||||
:variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`.
|
||||
|
||||
``OUTPUT <output-file>``
|
||||
Specify the output file name to generate. Use generator expressions
|
||||
such as ``$<CONFIG>`` to specify a configuration-specific output file
|
||||
name. Multiple configurations may generate the same output file only
|
||||
if the generated content is identical. Otherwise, the ``<output-file>``
|
||||
must evaluate to an unique name for each configuration.
|
||||
A relative path (after evaluating generator expressions) is treated
|
||||
with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
|
||||
See policy :policy:`CMP0070`.
|
||||
|
||||
Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific
|
||||
``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
|
||||
Generated files are modified and their timestamp updated on subsequent cmake
|
||||
runs only if their content is changed.
|
||||
|
||||
Note also that ``file(GENERATE)`` does not create the output file until the
|
||||
generation phase. The output file will not yet have been written when the
|
||||
``file(GENERATE)`` command returns, it is written only after processing all
|
||||
of a project's ``CMakeLists.txt`` files.
|
||||
|
||||
.. _CONFIGURE:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(CONFIGURE OUTPUT output-file
|
||||
CONTENT content
|
||||
[ESCAPE_QUOTES] [@ONLY]
|
||||
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
|
||||
|
||||
Generate an output file using the input given by ``CONTENT`` and substitute
|
||||
variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The
|
||||
substitution rules behave the same as the :command:`configure_file` command.
|
||||
In order to match :command:`configure_file`'s behavior, generator expressions
|
||||
are not supported for both ``OUTPUT`` and ``CONTENT``.
|
||||
|
||||
The arguments are:
|
||||
|
||||
``OUTPUT <output-file>``
|
||||
Specify the output file name to generate. A relative path is treated with
|
||||
respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
|
||||
``<output-file>`` does not support generator expressions.
|
||||
|
||||
``CONTENT <content>``
|
||||
Use the content given explicitly as input.
|
||||
``<content>`` does not support generator expressions.
|
||||
|
||||
``ESCAPE_QUOTES``
|
||||
Escape any substituted quotes with backslashes (C-style).
|
||||
|
||||
``@ONLY``
|
||||
Restrict variable replacement to references of the form ``@VAR@``.
|
||||
This is useful for configuring scripts that use ``${VAR}`` syntax.
|
||||
|
||||
``NEWLINE_STYLE <style>``
|
||||
Specify the newline style for the output file. Specify
|
||||
``UNIX`` or ``LF`` for ``\n`` newlines, or specify
|
||||
``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
|
||||
|
||||
Filesystem
|
||||
^^^^^^^^^^
|
||||
|
||||
.. _GLOB:
|
||||
.. _GLOB_RECURSE:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(GLOB <variable>
|
||||
[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
|
||||
[<globbing-expressions>...])
|
||||
file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
|
||||
[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
|
||||
[<globbing-expressions>...])
|
||||
|
||||
Generate a list of files that match the ``<globbing-expressions>`` and
|
||||
store it into the ``<variable>``. Globbing expressions are similar to
|
||||
regular expressions, but much simpler. If ``RELATIVE`` flag is
|
||||
specified, the results will be returned as relative paths to the given
|
||||
path. The results will be ordered lexicographically.
|
||||
|
||||
On Windows and macOS, globbing is case-insensitive even if the underlying
|
||||
filesystem is case-sensitive (both filenames and globbing expressions are
|
||||
converted to lowercase before matching). On other platforms, globbing is
|
||||
case-sensitive.
|
||||
|
||||
If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic
|
||||
to the main build system check target to rerun the flagged ``GLOB`` commands
|
||||
at build time. If any of the outputs change, CMake will regenerate the build
|
||||
system.
|
||||
|
||||
By default ``GLOB`` lists directories - directories are omitted in result if
|
||||
``LIST_DIRECTORIES`` is set to false.
|
||||
|
||||
.. note::
|
||||
We do not recommend using GLOB to collect a list of source files from
|
||||
your source tree. If no CMakeLists.txt file changes when a source is
|
||||
added or removed then the generated build system cannot know when to
|
||||
ask CMake to regenerate.
|
||||
The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or if
|
||||
a new generator is added in the future that cannot support it, projects using
|
||||
it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there is
|
||||
still a cost to perform the check on every rebuild.
|
||||
|
||||
Examples of globbing expressions include::
|
||||
|
||||
*.cxx - match all files with extension cxx
|
||||
*.vt? - match all files with extension vta,...,vtz
|
||||
f[3-5].txt - match files f3.txt, f4.txt, f5.txt
|
||||
|
||||
The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the
|
||||
matched directory and match the files. Subdirectories that are symlinks
|
||||
are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
|
||||
:policy:`CMP0009` is not set to ``NEW``.
|
||||
|
||||
By default ``GLOB_RECURSE`` omits directories from result list - setting
|
||||
``LIST_DIRECTORIES`` to true adds directories to result list.
|
||||
If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to
|
||||
``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories.
|
||||
|
||||
Examples of recursive globbing include::
|
||||
|
||||
/dir/*.py - match all python files in /dir and subdirectories
|
||||
|
||||
.. _RENAME:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(RENAME <oldname> <newname>)
|
||||
|
||||
Move a file or directory within a filesystem from ``<oldname>`` to
|
||||
``<newname>``, replacing the destination atomically.
|
||||
|
||||
.. _REMOVE:
|
||||
.. _REMOVE_RECURSE:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(REMOVE [<files>...])
|
||||
file(REMOVE_RECURSE [<files>...])
|
||||
|
||||
Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given
|
||||
files and directories, also non-empty directories. No error is emitted if a
|
||||
given file does not exist. Relative input paths are evaluated with respect
|
||||
to the current source directory. Empty input paths are ignored with a warning.
|
||||
|
||||
.. _MAKE_DIRECTORY:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(MAKE_DIRECTORY [<directories>...])
|
||||
|
||||
Create the given directories and their parents as needed.
|
||||
|
||||
.. _COPY:
|
||||
.. _INSTALL:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(<COPY|INSTALL> <files>... DESTINATION <dir>
|
||||
[FILE_PERMISSIONS <permissions>...]
|
||||
[DIRECTORY_PERMISSIONS <permissions>...]
|
||||
[NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
|
||||
[FOLLOW_SYMLINK_CHAIN]
|
||||
[FILES_MATCHING]
|
||||
[[PATTERN <pattern> | REGEX <regex>]
|
||||
[EXCLUDE] [PERMISSIONS <permissions>...]] [...])
|
||||
|
||||
The ``COPY`` signature copies files, directories, and symlinks to a
|
||||
destination folder. Relative input paths are evaluated with respect
|
||||
to the current source directory, and a relative destination is
|
||||
evaluated with respect to the current build directory. Copying
|
||||
preserves input file timestamps, and optimizes out a file if it exists
|
||||
at the destination with the same timestamp. Copying preserves input
|
||||
permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
|
||||
are given (default is ``USE_SOURCE_PERMISSIONS``).
|
||||
|
||||
If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve
|
||||
the symlinks at the paths given until a real file is found, and install
|
||||
a corresponding symlink in the destination for each symlink encountered. For
|
||||
each symlink that is installed, the resolution is stripped of the directory,
|
||||
leaving only the filename, meaning that the new symlink points to a file in
|
||||
the same directory as the symlink. This feature is useful on some Unix systems,
|
||||
where libraries are installed as a chain of symlinks with version numbers, with
|
||||
less specific versions pointing to more specific versions.
|
||||
``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and the library
|
||||
itself into the destination directory. For example, if you have the following
|
||||
directory structure:
|
||||
|
||||
* ``/opt/foo/lib/libfoo.so.1.2.3``
|
||||
* ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3``
|
||||
* ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2``
|
||||
* ``/opt/foo/lib/libfoo.so -> libfoo.so.1``
|
||||
|
||||
and you do:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
|
||||
|
||||
This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into
|
||||
``lib``.
|
||||
|
||||
See the :command:`install(DIRECTORY)` command for documentation of
|
||||
permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
|
||||
``EXCLUDE`` options. Copying directories preserves the structure
|
||||
of their content even if options are used to select a subset of
|
||||
files.
|
||||
|
||||
The ``INSTALL`` signature differs slightly from ``COPY``: it prints
|
||||
status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable),
|
||||
and ``NO_SOURCE_PERMISSIONS`` is default.
|
||||
Installation scripts generated by the :command:`install` command
|
||||
use this signature (with some undocumented options for internal use).
|
||||
|
||||
.. _SIZE:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(SIZE <filename> <variable>)
|
||||
|
||||
Determine the file size of the ``<filename>`` and put the result in
|
||||
``<variable>`` variable. Requires that ``<filename>`` is a valid path
|
||||
pointing to a file and is readable.
|
||||
|
||||
.. _READ_SYMLINK:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(READ_SYMLINK <linkname> <variable>)
|
||||
|
||||
This subcommand queries the symlink ``<linkname>`` and stores the path it
|
||||
points to in the result ``<variable>``. If ``<linkname>`` does not exist or
|
||||
is not a symlink, CMake issues a fatal error.
|
||||
|
||||
Note that this command returns the raw symlink path and does not resolve
|
||||
a relative path. The following is an example of how to ensure that an
|
||||
absolute path is obtained:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(linkname "/path/to/foo.sym")
|
||||
file(READ_SYMLINK "${linkname}" result)
|
||||
if(NOT IS_ABSOLUTE "${result}")
|
||||
get_filename_component(dir "${linkname}" DIRECTORY)
|
||||
set(result "${dir}/${result}")
|
||||
endif()
|
||||
|
||||
.. _CREATE_LINK:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(CREATE_LINK <original> <linkname>
|
||||
[RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
|
||||
|
||||
Create a link ``<linkname>`` that points to ``<original>``.
|
||||
It will be a hard link by default, but providing the ``SYMBOLIC`` option
|
||||
results in a symbolic link instead. Hard links require that ``original``
|
||||
exists and is a file, not a directory. If ``<linkname>`` already exists,
|
||||
it will be overwritten.
|
||||
|
||||
The ``<result>`` variable, if specified, receives the status of the operation.
|
||||
It is set to ``0`` upon success or an error message otherwise. If ``RESULT``
|
||||
is not specified and the operation fails, a fatal error is emitted.
|
||||
|
||||
Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if
|
||||
creating the link fails. It can be useful for handling situations such as
|
||||
``<original>`` and ``<linkname>`` being on different drives or mount points,
|
||||
which would make them unable to support a hard link.
|
||||
|
||||
Path Conversion
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. _RELATIVE_PATH:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(RELATIVE_PATH <variable> <directory> <file>)
|
||||
|
||||
Compute the relative path from a ``<directory>`` to a ``<file>`` and
|
||||
store it in the ``<variable>``.
|
||||
|
||||
.. _TO_CMAKE_PATH:
|
||||
.. _TO_NATIVE_PATH:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(TO_CMAKE_PATH "<path>" <variable>)
|
||||
file(TO_NATIVE_PATH "<path>" <variable>)
|
||||
|
||||
The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style
|
||||
path with forward-slashes (``/``). The input can be a single path or a
|
||||
system search path like ``$ENV{PATH}``. A search path will be converted
|
||||
to a cmake-style list separated by ``;`` characters.
|
||||
|
||||
The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
|
||||
path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere).
|
||||
|
||||
Always use double quotes around the ``<path>`` to be sure it is treated
|
||||
as a single argument to this command.
|
||||
|
||||
Transfer
|
||||
^^^^^^^^
|
||||
|
||||
.. _DOWNLOAD:
|
||||
.. _UPLOAD:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(DOWNLOAD <url> <file> [<options>...])
|
||||
file(UPLOAD <file> <url> [<options>...])
|
||||
|
||||
The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``.
|
||||
The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``.
|
||||
|
||||
Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
|
||||
|
||||
``INACTIVITY_TIMEOUT <seconds>``
|
||||
Terminate the operation after a period of inactivity.
|
||||
|
||||
``LOG <variable>``
|
||||
Store a human-readable log of the operation in a variable.
|
||||
|
||||
``SHOW_PROGRESS``
|
||||
Print progress information as status messages until the operation is
|
||||
complete.
|
||||
|
||||
``STATUS <variable>``
|
||||
Store the resulting status of the operation in a variable.
|
||||
The status is a ``;`` separated list of length 2.
|
||||
The first element is the numeric return value for the operation,
|
||||
and the second element is a string value for the error.
|
||||
A ``0`` numeric error means no error in the operation.
|
||||
|
||||
``TIMEOUT <seconds>``
|
||||
Terminate the operation after a given total time has elapsed.
|
||||
|
||||
``USERPWD <username>:<password>``
|
||||
Set username and password for operation.
|
||||
|
||||
``HTTPHEADER <HTTP-header>``
|
||||
HTTP header for operation. Suboption can be repeated several times.
|
||||
|
||||
``NETRC <level>``
|
||||
Specify whether the .netrc file is to be used for operation. If this
|
||||
option is not specified, the value of the ``CMAKE_NETRC`` variable
|
||||
will be used instead.
|
||||
Valid levels are:
|
||||
|
||||
``IGNORED``
|
||||
The .netrc file is ignored.
|
||||
This is the default.
|
||||
``OPTIONAL``
|
||||
The .netrc file is optional, and information in the URL is preferred.
|
||||
The file will be scanned to find which ever information is not specified
|
||||
in the URL.
|
||||
``REQUIRED``
|
||||
The .netrc file is required, and information in the URL is ignored.
|
||||
|
||||
``NETRC_FILE <file>``
|
||||
Specify an alternative .netrc file to the one in your home directory,
|
||||
if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option
|
||||
is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will
|
||||
be used instead.
|
||||
|
||||
If neither ``NETRC`` option is given CMake will check variables
|
||||
``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively.
|
||||
|
||||
``TLS_VERIFY <ON|OFF>``
|
||||
Specify whether to verify the server certificate for ``https://`` URLs.
|
||||
The default is to *not* verify.
|
||||
|
||||
``TLS_CAINFO <file>``
|
||||
Specify a custom Certificate Authority file for ``https://`` URLs.
|
||||
|
||||
For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL``
|
||||
certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to
|
||||
check certificates. If neither ``TLS`` option is given CMake will check
|
||||
variables ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
|
||||
|
||||
Additional options to ``DOWNLOAD`` are:
|
||||
|
||||
``EXPECTED_HASH ALGO=<value>``
|
||||
|
||||
Verify that the downloaded content hash matches the expected value, where
|
||||
``ALGO`` is one of the algorithms supported by ``file(<HASH>)``.
|
||||
If it does not match, the operation fails with an error.
|
||||
|
||||
``EXPECTED_MD5 <value>``
|
||||
Historical short-hand for ``EXPECTED_HASH MD5=<value>``.
|
||||
|
||||
Locking
|
||||
^^^^^^^
|
||||
|
||||
.. _LOCK:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(LOCK <path> [DIRECTORY] [RELEASE]
|
||||
[GUARD <FUNCTION|FILE|PROCESS>]
|
||||
[RESULT_VARIABLE <variable>]
|
||||
[TIMEOUT <seconds>])
|
||||
|
||||
Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and file
|
||||
``<path>/cmake.lock`` otherwise. File will be locked for scope defined by
|
||||
``GUARD`` option (default value is ``PROCESS``). ``RELEASE`` option can be used
|
||||
to unlock file explicitly. If option ``TIMEOUT`` is not specified CMake will
|
||||
wait until lock succeed or until fatal error occurs. If ``TIMEOUT`` is set to
|
||||
``0`` lock will be tried once and result will be reported immediately. If
|
||||
``TIMEOUT`` is not ``0`` CMake will try to lock file for the period specified
|
||||
by ``<seconds>`` value. Any errors will be interpreted as fatal if there is no
|
||||
``RESULT_VARIABLE`` option. Otherwise result will be stored in ``<variable>``
|
||||
and will be ``0`` on success or error message on failure.
|
||||
|
||||
Note that lock is advisory - there is no guarantee that other processes will
|
||||
respect this lock, i.e. lock synchronize two or more CMake instances sharing
|
||||
some modifiable resources. Similar logic applied to ``DIRECTORY`` option -
|
||||
locking parent directory doesn't prevent other ``LOCK`` commands to lock any
|
||||
child directory or file.
|
||||
|
||||
Trying to lock file twice is not allowed. Any intermediate directories and
|
||||
file itself will be created if they not exist. ``GUARD`` and ``TIMEOUT``
|
||||
options ignored on ``RELEASE`` operation.
|
||||
|
||||
Archiving
|
||||
^^^^^^^^^
|
||||
|
||||
.. _ARCHIVE_CREATE:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(ARCHIVE_CREATE OUTPUT <archive>
|
||||
PATHS <paths>...
|
||||
[FORMAT <format>]
|
||||
[COMPRESSION <compression>]
|
||||
[MTIME <mtime>]
|
||||
[VERBOSE])
|
||||
|
||||
Creates the specified ``<archive>`` file with the files and directories
|
||||
listed in ``<paths>``. Note that ``<paths>`` must list actual files or
|
||||
directories, wildcards are not supported.
|
||||
|
||||
Use the ``FORMAT`` option to specify the archive format. Supported values
|
||||
for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and
|
||||
``zip``. If ``FORMAT`` is not given, the default format is ``paxr``.
|
||||
|
||||
Some archive formats allow the type of compression to be specified.
|
||||
The ``7zip`` and ``zip`` archive formats already imply a specific type of
|
||||
compression. The other formats use no compression by default, but can be
|
||||
directed to do so with the ``COMPRESSION`` option. Valid values for
|
||||
``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
|
||||
|
||||
.. note::
|
||||
With ``FORMAT`` set to ``raw`` only one file will be compressed with the
|
||||
compression type specified by ``COMPRESSION``.
|
||||
|
||||
The ``VERBOSE`` option enables verbose output for the archive operation.
|
||||
|
||||
To specify the modification time recorded in tarball entries, use
|
||||
the ``MTIME`` option.
|
||||
|
||||
.. _ARCHIVE_EXTRACT:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
file(ARCHIVE_EXTRACT INPUT <archive>
|
||||
[DESTINATION <dir>]
|
||||
[PATTERNS <patterns>...]
|
||||
[LIST_ONLY]
|
||||
[VERBOSE])
|
||||
|
||||
Extracts or lists the content of the specified ``<archive>``.
|
||||
|
||||
The directory where the content of the archive will be extracted to can
|
||||
be specified using the ``DESTINATION`` option. If the directory does not
|
||||
exist, it will be created. If ``DESTINATION`` is not given, the current
|
||||
binary directory will be used.
|
||||
|
||||
If required, you may select which files and directories to list or extract
|
||||
from the archive using the specified ``<patterns>``. Wildcards are supported.
|
||||
If the ``PATTERNS`` option is not given, the entire archive will be listed or
|
||||
extracted.
|
||||
|
||||
``LIST_ONLY`` will list the files in the archive rather than extract them.
|
||||
|
||||
With ``VERBOSE``, the command will produce verbose output.
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
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_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`
|
||||
|
||||
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``.
|
||||
.. |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
|
||||
|
|
@ -0,0 +1,81 @@
|
|||
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_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`
|
||||
|
||||
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``.
|
||||
.. |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.
|
||||
|
|
@ -0,0 +1,426 @@
|
|||
find_package
|
||||
------------
|
||||
|
||||
.. only:: html
|
||||
|
||||
.. contents::
|
||||
|
||||
Find an external project, and load its settings.
|
||||
|
||||
.. _`basic signature`:
|
||||
|
||||
Basic Signature and Module Mode
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
|
||||
[REQUIRED] [[COMPONENTS] [components...]]
|
||||
[OPTIONAL_COMPONENTS components...]
|
||||
[NO_POLICY_SCOPE])
|
||||
|
||||
Finds and loads settings from an external project. ``<PackageName>_FOUND``
|
||||
will be set to indicate whether the package was found. When the
|
||||
package is found package-specific information is provided through
|
||||
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`` option (or after the ``REQUIRED`` option if present).
|
||||
Additional optional components may be listed after
|
||||
``OPTIONAL_COMPONENTS``. Available components and their influence on
|
||||
whether a package is considered to be found are defined by the target
|
||||
package.
|
||||
|
||||
The ``[version]`` argument requests a version with which the package found
|
||||
should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The
|
||||
``EXACT`` option requests that the version be matched exactly. 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).
|
||||
|
||||
See the :command:`cmake_policy` command documentation for discussion
|
||||
of the ``NO_POLICY_SCOPE`` option.
|
||||
|
||||
The command has two modes by which it searches for packages: "Module"
|
||||
mode and "Config" mode. The above signature selects Module mode.
|
||||
If no module is found the command falls back to Config mode, described
|
||||
below. This fall back is disabled if the ``MODULE`` option is given.
|
||||
|
||||
In Module mode, CMake searches for a file called ``Find<PackageName>.cmake``.
|
||||
The file is first searched 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 module documentation.
|
||||
|
||||
If the ``MODULE`` option is not specified in the above signature,
|
||||
CMake first searches for the package using Module mode. Then, if the
|
||||
package is not found, it searches again using Config mode. A user
|
||||
may set the variable :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` to
|
||||
``TRUE`` to direct CMake first search using Config mode before falling
|
||||
back to Module mode.
|
||||
|
||||
Full Signature and Config Mode
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
User code should generally look for packages using the above `basic
|
||||
signature`_. The remainder of this command documentation specifies the
|
||||
full command signature and details of the search process. Project
|
||||
maintainers wishing to provide a package to be found by this command
|
||||
are encouraged to read on.
|
||||
|
||||
The complete Config mode command signature is
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
find_package(<PackageName> [version] [EXACT] [QUIET]
|
||||
[REQUIRED] [[COMPONENTS] [components...]]
|
||||
[OPTIONAL_COMPONENTS components...]
|
||||
[CONFIG|NO_MODULE]
|
||||
[NO_POLICY_SCOPE]
|
||||
[NAMES name1 [name2 ...]]
|
||||
[CONFIGS config1 [config2 ...]]
|
||||
[HINTS path1 [path2 ... ]]
|
||||
[PATHS path1 [path2 ... ]]
|
||||
[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_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 command searches for a file called ``<PackageName>Config.cmake`` or
|
||||
``<lower-case-package-name>-config.cmake`` for each name specified.
|
||||
A replacement set of possible configuration file names may be given
|
||||
using the ``CONFIGS`` option. The search procedure is specified below.
|
||||
Once found, 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 an installation of the package with an appropriate
|
||||
version are stored in the cmake variable ``<PackageName>_CONSIDERED_CONFIGS``,
|
||||
the associated versions in ``<PackageName>_CONSIDERED_VERSIONS``.
|
||||
|
||||
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 `Search Procedure`_
|
||||
outlined below will find them without requiring use of additional options.
|
||||
|
||||
Version Selection
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
When the ``[version]`` argument is given Config mode will only find a
|
||||
version of the package that claims compatibility with the requested
|
||||
version (format is ``major[.minor[.patch[.tweak]]]``). 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. 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
|
||||
|
||||
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``.
|
||||
|
||||
Search Procedure
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
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::
|
||||
|
||||
<prefix>/ (W)
|
||||
<prefix>/(cmake|CMake)/ (W)
|
||||
<prefix>/<name>*/ (W)
|
||||
<prefix>/<name>*/(cmake|CMake)/ (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)
|
||||
|
||||
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::
|
||||
|
||||
<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.
|
||||
|
||||
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 paths specified in the :variable:`<PackageName>_ROOT` CMake
|
||||
variable and the :envvar:`<PackageName>_ROOT` environment variable,
|
||||
where ``<PackageName>`` is the package to be found.
|
||||
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``.
|
||||
See policy :policy:`CMP0074`.
|
||||
|
||||
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``:
|
||||
|
||||
* :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`
|
||||
* ``CMAKE_FRAMEWORK_PATH``
|
||||
* ``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. This 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.
|
||||
|
||||
.. |FIND_XXX| replace:: find_package
|
||||
.. |FIND_ARGS_XXX| replace:: <PackageName>
|
||||
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
|
||||
:variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
|
||||
|
||||
.. 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 by setting the
|
||||
:variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``.
|
||||
|
||||
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_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 requested components
|
||||
``<PackageName>_FIND_REQUIRED_<c>``
|
||||
true if component ``<c>`` is required,
|
||||
false if component ``<c>`` is optional
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
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_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`
|
||||
|
||||
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``.
|
||||
.. |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.
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
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_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`
|
||||
|
||||
.. |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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,127 @@
|
|||
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 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>)
|
||||
|
||||
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=
|
||||
|
|
@ -0,0 +1,74 @@
|
|||
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.
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
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.
|
||||
|
||||
See also the :command:`get_property` command ``GLOBAL`` option.
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
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.
|
||||
The specified directory must have already been traversed by CMake.
|
||||
|
||||
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 the more general :command:`get_property` command.
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
get_filename_component
|
||||
----------------------
|
||||
|
||||
Get a specific component of a full filename.
|
||||
|
||||
.. 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 without directory or longest extension
|
||||
LAST_EXT = File name last extension (.c from d/a.b.c)
|
||||
NAME_WLE = File name without directory or last extension
|
||||
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
|
||||
|
||||
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])
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,85 @@
|
|||
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>``.
|
||||
See also the :command:`get_directory_property` command.
|
||||
|
||||
``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, but this 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).
|
||||
|
||||
See also the :command:`get_source_file_property` command.
|
||||
|
||||
``INSTALL``
|
||||
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.
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
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, but this 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`.
|
||||
|
||||
See also the more general :command:`get_property` command.
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
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 the more general :command:`get_property` command.
|
||||
|
||||
See :ref:`Target Properties` for the list of properties known to CMake.
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
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 ``cmake --help-property-list``.
|
||||
|
||||
See also the more general :command:`get_property` command.
|
||||
|
|
@ -0,0 +1,280 @@
|
|||
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:
|
||||
Innermost parentheses are evaluated first. Next come unary tests such
|
||||
as ``EXISTS``, ``COMMAND``, and ``DEFINED``. Then 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``,
|
||||
and ``MATCHES``. Then the boolean operators in the order ``NOT``, ``AND``,
|
||||
and finally ``OR``.
|
||||
|
||||
Possible conditions are:
|
||||
|
||||
``if(<constant>)``
|
||||
True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``,
|
||||
or a non-zero number. 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 and the following
|
||||
signature is used.
|
||||
|
||||
``if(<variable|string>)``
|
||||
True if given a variable that is defined to a value that is not a false
|
||||
constant. False otherwise. (Note macro arguments are not variables.)
|
||||
|
||||
``if(NOT <condition>)``
|
||||
True if the condition is not true.
|
||||
|
||||
``if(<cond1> AND <cond2>)``
|
||||
True if both conditions would be considered true individually.
|
||||
|
||||
``if(<cond1> OR <cond2>)``
|
||||
True if either condition would be considered true individually.
|
||||
|
||||
``if(COMMAND command-name)``
|
||||
True if the given name is a command, macro or function that can be
|
||||
invoked.
|
||||
|
||||
``if(POLICY policy-id)``
|
||||
True if the given name is an existing policy (of the form ``CMP<NNNN>``).
|
||||
|
||||
``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).
|
||||
|
||||
``if(TEST test-name)``
|
||||
True if the given name is an existing test name created by the
|
||||
:command:`add_test` command.
|
||||
|
||||
``if(EXISTS path-to-file-or-directory)``
|
||||
True if the named file or directory exists. Behavior is well-defined
|
||||
only for full paths. 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.
|
||||
|
||||
``if(file1 IS_NEWER_THAN file2)``
|
||||
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.
|
||||
|
||||
``if(IS_DIRECTORY path-to-directory)``
|
||||
True if the given name is a directory. Behavior is well-defined only
|
||||
for full paths.
|
||||
|
||||
``if(IS_SYMLINK file-name)``
|
||||
True if the given name is a symbolic link. Behavior is well-defined
|
||||
only for full paths.
|
||||
|
||||
``if(IS_ABSOLUTE path)``
|
||||
True if the given path is an absolute path.
|
||||
|
||||
``if(<variable|string> MATCHES regex)``
|
||||
True if the given string or variable's value matches the given regular
|
||||
condition. See :ref:`Regex Specification` for regex format.
|
||||
``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables.
|
||||
|
||||
``if(<variable|string> LESS <variable|string>)``
|
||||
True if the given string or variable's value is a valid number and less
|
||||
than that on the right.
|
||||
|
||||
``if(<variable|string> GREATER <variable|string>)``
|
||||
True if the given string or variable's value is a valid number and greater
|
||||
than that on the right.
|
||||
|
||||
``if(<variable|string> EQUAL <variable|string>)``
|
||||
True if the given string or variable's value is a valid number and equal
|
||||
to that on the right.
|
||||
|
||||
``if(<variable|string> LESS_EQUAL <variable|string>)``
|
||||
True if the given string or variable's value is a valid number and less
|
||||
than or equal to that on the right.
|
||||
|
||||
``if(<variable|string> GREATER_EQUAL <variable|string>)``
|
||||
True if the given string or variable's value is a valid number and greater
|
||||
than or equal to that on the right.
|
||||
|
||||
``if(<variable|string> STRLESS <variable|string>)``
|
||||
True if the given string or variable's value is lexicographically less
|
||||
than the string or variable on the right.
|
||||
|
||||
``if(<variable|string> STRGREATER <variable|string>)``
|
||||
True if the given string or variable's value is lexicographically greater
|
||||
than the string or variable on the right.
|
||||
|
||||
``if(<variable|string> STREQUAL <variable|string>)``
|
||||
True if the given string or variable's value is lexicographically equal
|
||||
to the string or variable on the right.
|
||||
|
||||
``if(<variable|string> STRLESS_EQUAL <variable|string>)``
|
||||
True if the given string or variable's value is lexicographically less
|
||||
than or equal to the string or variable on the right.
|
||||
|
||||
``if(<variable|string> STRGREATER_EQUAL <variable|string>)``
|
||||
True if the given string or variable's value is lexicographically greater
|
||||
than or equal to the string or variable on the right.
|
||||
|
||||
``if(<variable|string> VERSION_LESS <variable|string>)``
|
||||
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.
|
||||
|
||||
``if(<variable|string> VERSION_GREATER <variable|string>)``
|
||||
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.
|
||||
|
||||
``if(<variable|string> VERSION_EQUAL <variable|string>)``
|
||||
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.
|
||||
|
||||
``if(<variable|string> VERSION_LESS_EQUAL <variable|string>)``
|
||||
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.
|
||||
|
||||
``if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)``
|
||||
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.
|
||||
|
||||
``if(<variable|string> IN_LIST <variable>)``
|
||||
True if the given element is contained in the named list variable.
|
||||
|
||||
``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 that macro arguments are not variables.
|
||||
|
||||
``if((condition) AND (condition OR (condition)))``
|
||||
The conditions inside the parenthesis are evaluated first and then
|
||||
the remaining condition is evaluated as in the previous examples.
|
||||
Where there are nested parenthesis the innermost are evaluated as part
|
||||
of evaluating the condition that contains them.
|
||||
|
||||
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.
|
||||
|
||||
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>``.
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
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.
|
||||
Signalling 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.
|
||||
|
||||
Arguments to ``include_directories`` may use "generator expressions" with
|
||||
the syntax "$<...>". See the :manual:`cmake-generator-expressions(7)`
|
||||
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
|
||||
manual for more on defining buildsystem properties.
|
||||
|
||||
.. note::
|
||||
|
||||
Prefer the :command:`target_include_directories` command to add include
|
||||
directories to individual targets and optionally propagate/export them
|
||||
to dependents.
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
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).
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
include_guard
|
||||
-------------
|
||||
|
||||
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
|
||||
:command:`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)
|
||||
|
|
@ -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)
|
||||
|
|
@ -0,0 +1,733 @@
|
|||
install
|
||||
-------
|
||||
|
||||
Specify rules to run at install time.
|
||||
|
||||
Synopsis
|
||||
^^^^^^^^
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
install(`TARGETS`_ <target>... [...])
|
||||
install({`FILES`_ | `PROGRAMS`_} <file>... [...])
|
||||
install(`DIRECTORY`_ <dir>... [...])
|
||||
install(`SCRIPT`_ <file> [...])
|
||||
install(`CODE`_ <code> [...])
|
||||
install(`EXPORT`_ <export-name> [...])
|
||||
|
||||
Introduction
|
||||
^^^^^^^^^^^^
|
||||
|
||||
This command generates installation rules for a project. Install rules
|
||||
specified by calls to the ``install()`` command within a source directory
|
||||
are executed in order during installation. Install rules in subdirectories
|
||||
added by calls to the :command:`add_subdirectory` command are interleaved
|
||||
with those in the parent directory to run in the order declared (see
|
||||
policy :policy:`CMP0082`).
|
||||
|
||||
There are multiple signatures for this command. Some of them define
|
||||
installation options for files and targets. Options common to
|
||||
multiple signatures are covered here but they are valid only for
|
||||
signatures that specify them. The common options are:
|
||||
|
||||
``DESTINATION``
|
||||
Specify the directory on disk to which a file will be installed.
|
||||
Arguments can be relative or absolute paths.
|
||||
|
||||
If a relative path is given it is interpreted relative to the value
|
||||
of the :variable:`CMAKE_INSTALL_PREFIX` variable.
|
||||
The prefix can be relocated at install time using the ``DESTDIR``
|
||||
mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable
|
||||
documentation.
|
||||
|
||||
If an absolute path (with a leading slash or drive letter) is given
|
||||
it is used verbatim.
|
||||
|
||||
As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer
|
||||
generators, it is preferable to use relative paths throughout.
|
||||
|
||||
``PERMISSIONS``
|
||||
Specify permissions for installed files. Valid permissions are
|
||||
``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``,
|
||||
``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, ``WORLD_WRITE``,
|
||||
``WORLD_EXECUTE``, ``SETUID``, and ``SETGID``. Permissions that do
|
||||
not make sense on certain platforms are ignored on those platforms.
|
||||
|
||||
``CONFIGURATIONS``
|
||||
Specify a list of build configurations for which the install rule
|
||||
applies (Debug, Release, etc.). Note that the values specified for
|
||||
this option only apply to options listed AFTER the ``CONFIGURATIONS``
|
||||
option. For example, to set separate install paths for the Debug and
|
||||
Release configurations, do the following:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(TARGETS target
|
||||
CONFIGURATIONS Debug
|
||||
RUNTIME DESTINATION Debug/bin)
|
||||
install(TARGETS target
|
||||
CONFIGURATIONS Release
|
||||
RUNTIME DESTINATION Release/bin)
|
||||
|
||||
Note that ``CONFIGURATIONS`` appears BEFORE ``RUNTIME DESTINATION``.
|
||||
|
||||
``COMPONENT``
|
||||
Specify an installation component name with which the install rule
|
||||
is associated, such as "runtime" or "development". During
|
||||
component-specific installation only install rules associated with
|
||||
the given component name will be executed. During a full installation
|
||||
all components are installed unless marked with ``EXCLUDE_FROM_ALL``.
|
||||
If ``COMPONENT`` is not provided a default component "Unspecified" is
|
||||
created. The default component name may be controlled with the
|
||||
:variable:`CMAKE_INSTALL_DEFAULT_COMPONENT_NAME` variable.
|
||||
|
||||
``EXCLUDE_FROM_ALL``
|
||||
Specify that the file is excluded from a full installation and only
|
||||
installed as part of a component-specific installation
|
||||
|
||||
``RENAME``
|
||||
Specify a name for an installed file that may be different from the
|
||||
original file. Renaming is allowed only when a single file is
|
||||
installed by the command.
|
||||
|
||||
``OPTIONAL``
|
||||
Specify that it is not an error if the file to be installed does
|
||||
not exist.
|
||||
|
||||
Command signatures that install files may print messages during
|
||||
installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable
|
||||
to control which messages are printed.
|
||||
|
||||
Many of the ``install()`` variants implicitly create the directories
|
||||
containing the installed files. If
|
||||
:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` is set, these
|
||||
directories will be created with the permissions specified. Otherwise,
|
||||
they will be created according to the uname rules on Unix-like platforms.
|
||||
Windows platforms are unaffected.
|
||||
|
||||
Installing Targets
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. _`install(TARGETS)`:
|
||||
.. _TARGETS:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(TARGETS targets... [EXPORT <export-name>]
|
||||
[[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
|
||||
PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
|
||||
[DESTINATION <dir>]
|
||||
[PERMISSIONS permissions...]
|
||||
[CONFIGURATIONS [Debug|Release|...]]
|
||||
[COMPONENT <component>]
|
||||
[NAMELINK_COMPONENT <component>]
|
||||
[OPTIONAL] [EXCLUDE_FROM_ALL]
|
||||
[NAMELINK_ONLY|NAMELINK_SKIP]
|
||||
] [...]
|
||||
[INCLUDES DESTINATION [<dir> ...]]
|
||||
)
|
||||
|
||||
The ``TARGETS`` form specifies rules for installing targets from a
|
||||
project. There are several kinds of target :ref:`Output Artifacts`
|
||||
that may be installed:
|
||||
|
||||
``ARCHIVE``
|
||||
Target artifacts of this kind include:
|
||||
|
||||
* *Static libraries*
|
||||
(except on macOS when marked as ``FRAMEWORK``, see below);
|
||||
* *DLL import libraries*
|
||||
(on all Windows-based systems including Cygwin; they have extension
|
||||
``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``);
|
||||
* On AIX, the *linker import file* created for executables with
|
||||
:prop_tgt:`ENABLE_EXPORTS` enabled.
|
||||
|
||||
``LIBRARY``
|
||||
Target artifacts of this kind include:
|
||||
|
||||
* *Shared libraries*, except
|
||||
|
||||
- DLLs (these go to ``RUNTIME``, see below),
|
||||
- on macOS when marked as ``FRAMEWORK`` (see below).
|
||||
|
||||
``RUNTIME``
|
||||
Target artifacts of this kind include:
|
||||
|
||||
* *Executables*
|
||||
(except on macOS when marked as ``MACOSX_BUNDLE``, see ``BUNDLE`` below);
|
||||
* DLLs (on all Windows-based systems including Cygwin; note that the
|
||||
accompanying import libraries are of kind ``ARCHIVE``).
|
||||
|
||||
``OBJECTS``
|
||||
Object files associated with *object libraries*.
|
||||
|
||||
``FRAMEWORK``
|
||||
Both static and shared libraries marked with the ``FRAMEWORK``
|
||||
property are treated as ``FRAMEWORK`` targets on macOS.
|
||||
|
||||
``BUNDLE``
|
||||
Executables marked with the :prop_tgt:`MACOSX_BUNDLE` property are treated as
|
||||
``BUNDLE`` targets on macOS.
|
||||
|
||||
``PUBLIC_HEADER``
|
||||
Any :prop_tgt:`PUBLIC_HEADER` files associated with a library are installed in
|
||||
the destination specified by the ``PUBLIC_HEADER`` argument on non-Apple
|
||||
platforms. Rules defined by this argument are ignored for :prop_tgt:`FRAMEWORK`
|
||||
libraries on Apple platforms because the associated files are installed
|
||||
into the appropriate locations inside the framework folder. See
|
||||
:prop_tgt:`PUBLIC_HEADER` for details.
|
||||
|
||||
``PRIVATE_HEADER``
|
||||
Similar to ``PUBLIC_HEADER``, but for ``PRIVATE_HEADER`` files. See
|
||||
:prop_tgt:`PRIVATE_HEADER` for details.
|
||||
|
||||
``RESOURCE``
|
||||
Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for
|
||||
``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details.
|
||||
|
||||
For each of these arguments given, the arguments following them only apply
|
||||
to the target or file type specified in the argument. If none is given, the
|
||||
installation properties apply to all target types. If only one is given then
|
||||
only targets of that type will be installed (which can be used to install
|
||||
just a DLL or just an import library.)
|
||||
|
||||
For regular executables, static libraries and shared libraries, the
|
||||
``DESTINATION`` argument is not required. For these target types, when
|
||||
``DESTINATION`` is omitted, a default destination will be taken from the
|
||||
appropriate variable from :module:`GNUInstallDirs`, or set to a built-in
|
||||
default value if that variable is not defined. The same is true for the
|
||||
public and private headers associated with the installed targets through the
|
||||
:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties.
|
||||
A destination must always be provided for module libraries, Apple bundles and
|
||||
frameworks. A destination can be omitted for interface and object libraries,
|
||||
but they are handled differently (see the discussion of this topic toward the
|
||||
end of this section).
|
||||
|
||||
The following table shows the target types with their associated variables and
|
||||
built-in defaults that apply when no destination is given:
|
||||
|
||||
================== =============================== ======================
|
||||
Target Type GNUInstallDirs Variable Built-In Default
|
||||
================== =============================== ======================
|
||||
``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin``
|
||||
``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
|
||||
``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
|
||||
``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
|
||||
``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
|
||||
================== =============================== ======================
|
||||
|
||||
Projects wishing to follow the common practice of installing headers into a
|
||||
project-specific subdirectory will need to provide a destination rather than
|
||||
rely on the above.
|
||||
|
||||
To make packages compliant with distribution filesystem layout policies, if
|
||||
projects must specify a ``DESTINATION``, it is recommended that they use a
|
||||
path that begins with the appropriate :module:`GNUInstallDirs` variable.
|
||||
This allows package maintainers to control the install destination by setting
|
||||
the appropriate cache variables. The following example shows a static library
|
||||
being installed to the default destination provided by
|
||||
:module:`GNUInstallDirs`, but with its headers installed to a project-specific
|
||||
subdirectory that follows the above recommendation:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_library(mylib STATIC ...)
|
||||
set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
|
||||
include(GNUInstallDirs)
|
||||
install(TARGETS mylib
|
||||
PUBLIC_HEADER
|
||||
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
|
||||
)
|
||||
|
||||
In addition to the common options listed above, each target can accept
|
||||
the following additional arguments:
|
||||
|
||||
``NAMELINK_COMPONENT``
|
||||
On some platforms a versioned shared library has a symbolic link such
|
||||
as::
|
||||
|
||||
lib<name>.so -> lib<name>.so.1
|
||||
|
||||
where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so``
|
||||
is a "namelink" allowing linkers to find the library when given
|
||||
``-l<name>``. The ``NAMELINK_COMPONENT`` option is similar to the
|
||||
``COMPONENT`` option, but it changes the installation component of a shared
|
||||
library namelink if one is generated. If not specified, this defaults to the
|
||||
value of ``COMPONENT``. It is an error to use this parameter outside of a
|
||||
``LIBRARY`` block.
|
||||
|
||||
Consider the following example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(TARGETS mylib
|
||||
LIBRARY
|
||||
COMPONENT Libraries
|
||||
NAMELINK_COMPONENT Development
|
||||
PUBLIC_HEADER
|
||||
COMPONENT Development
|
||||
)
|
||||
|
||||
In this scenario, if you choose to install only the ``Development``
|
||||
component, both the headers and namelink will be installed without the
|
||||
library. (If you don't also install the ``Libraries`` component, the
|
||||
namelink will be a dangling symlink, and projects that link to the library
|
||||
will have build errors.) If you install only the ``Libraries`` component,
|
||||
only the library will be installed, without the headers and namelink.
|
||||
|
||||
This option is typically used for package managers that have separate
|
||||
runtime and development packages. For example, on Debian systems, the
|
||||
library is expected to be in the runtime package, and the headers and
|
||||
namelink are expected to be in the development package.
|
||||
|
||||
See the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties for
|
||||
details on creating versioned shared libraries.
|
||||
|
||||
``NAMELINK_ONLY``
|
||||
This option causes the installation of only the namelink when a library
|
||||
target is installed. On platforms where versioned shared libraries do not
|
||||
have namelinks or when a library is not versioned, the ``NAMELINK_ONLY``
|
||||
option installs nothing. It is an error to use this parameter outside of a
|
||||
``LIBRARY`` block.
|
||||
|
||||
When ``NAMELINK_ONLY`` is given, either ``NAMELINK_COMPONENT`` or
|
||||
``COMPONENT`` may be used to specify the installation component of the
|
||||
namelink, but ``COMPONENT`` should generally be preferred.
|
||||
|
||||
``NAMELINK_SKIP``
|
||||
Similar to ``NAMELINK_ONLY``, but it has the opposite effect: it causes the
|
||||
installation of library files other than the namelink when a library target
|
||||
is installed. When neither ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` are given,
|
||||
both portions are installed. On platforms where versioned shared libraries
|
||||
do not have symlinks or when a library is not versioned, ``NAMELINK_SKIP``
|
||||
installs the library. It is an error to use this parameter outside of a
|
||||
``LIBRARY`` block.
|
||||
|
||||
If ``NAMELINK_SKIP`` is specified, ``NAMELINK_COMPONENT`` has no effect. It
|
||||
is not recommended to use ``NAMELINK_SKIP`` in conjunction with
|
||||
``NAMELINK_COMPONENT``.
|
||||
|
||||
The `install(TARGETS)`_ command can also accept the following options at the
|
||||
top level:
|
||||
|
||||
``EXPORT``
|
||||
This option associates the installed target files with an export called
|
||||
``<export-name>``. It must appear before any target options. To actually
|
||||
install the export file itself, call `install(EXPORT)`_, documented below.
|
||||
See documentation of the :prop_tgt:`EXPORT_NAME` target property to change
|
||||
the name of the exported target.
|
||||
|
||||
``INCLUDES DESTINATION``
|
||||
This option specifies a list of directories which will be added to the
|
||||
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
|
||||
``<targets>`` when exported by the `install(EXPORT)`_ command. If a
|
||||
relative path is specified, it is treated as relative to the
|
||||
``$<INSTALL_PREFIX>``.
|
||||
|
||||
One or more groups of properties may be specified in a single call to
|
||||
the ``TARGETS`` form of this command. A target may be installed more than
|
||||
once to different locations. Consider hypothetical targets ``myExe``,
|
||||
``mySharedLib``, and ``myStaticLib``. The code:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(TARGETS myExe mySharedLib myStaticLib
|
||||
RUNTIME DESTINATION bin
|
||||
LIBRARY DESTINATION lib
|
||||
ARCHIVE DESTINATION lib/static)
|
||||
install(TARGETS mySharedLib DESTINATION /some/full/path)
|
||||
|
||||
will install ``myExe`` to ``<prefix>/bin`` and ``myStaticLib`` to
|
||||
``<prefix>/lib/static``. On non-DLL platforms ``mySharedLib`` will be
|
||||
installed to ``<prefix>/lib`` and ``/some/full/path``. On DLL platforms
|
||||
the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and
|
||||
``/some/full/path`` and its import library will be installed to
|
||||
``<prefix>/lib/static`` and ``/some/full/path``.
|
||||
|
||||
:ref:`Interface Libraries` may be listed among the targets to install.
|
||||
They install no artifacts but will be included in an associated ``EXPORT``.
|
||||
If :ref:`Object Libraries` are listed but given no destination for their
|
||||
object files, they will be exported as :ref:`Interface Libraries`.
|
||||
This is sufficient to satisfy transitive usage requirements of other
|
||||
targets that link to the object libraries in their implementation.
|
||||
|
||||
Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
|
||||
set to ``TRUE`` has undefined behavior.
|
||||
|
||||
`install(TARGETS)`_ can install targets that were created in
|
||||
other directories. When using such cross-directory install rules, running
|
||||
``make install`` (or similar) from a subdirectory will not guarantee that
|
||||
targets from other directories are up-to-date. You can use
|
||||
:command:`target_link_libraries` or :command:`add_dependencies`
|
||||
to ensure that such out-of-directory targets are built before the
|
||||
subdirectory-specific install rules are run.
|
||||
|
||||
An install destination given as a ``DESTINATION`` argument may
|
||||
use "generator expressions" with the syntax ``$<...>``. See the
|
||||
:manual:`cmake-generator-expressions(7)` manual for available expressions.
|
||||
|
||||
Installing Files
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
.. _`install(FILES)`:
|
||||
.. _`install(PROGRAMS)`:
|
||||
.. _FILES:
|
||||
.. _PROGRAMS:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(<FILES|PROGRAMS> files...
|
||||
TYPE <type> | DESTINATION <dir>
|
||||
[PERMISSIONS permissions...]
|
||||
[CONFIGURATIONS [Debug|Release|...]]
|
||||
[COMPONENT <component>]
|
||||
[RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
|
||||
|
||||
The ``FILES`` form specifies rules for installing files for a project.
|
||||
File names given as relative paths are interpreted with respect to the
|
||||
current source directory. Files installed by this form are by default
|
||||
given permissions ``OWNER_WRITE``, ``OWNER_READ``, ``GROUP_READ``, and
|
||||
``WORLD_READ`` if no ``PERMISSIONS`` argument is given.
|
||||
|
||||
The ``PROGRAMS`` form is identical to the ``FILES`` form except that the
|
||||
default permissions for the installed file also include ``OWNER_EXECUTE``,
|
||||
``GROUP_EXECUTE``, and ``WORLD_EXECUTE``. This form is intended to install
|
||||
programs that are not targets, such as shell scripts. Use the ``TARGETS``
|
||||
form to install targets built within the project.
|
||||
|
||||
The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use
|
||||
"generator expressions" with the syntax ``$<...>``. See the
|
||||
:manual:`cmake-generator-expressions(7)` manual for available expressions.
|
||||
However, if any item begins in a generator expression it must evaluate
|
||||
to a full path.
|
||||
|
||||
Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
|
||||
A ``TYPE`` argument specifies the generic file type of the files being
|
||||
installed. A destination will then be set automatically by taking the
|
||||
corresponding variable from :module:`GNUInstallDirs`, or by using a
|
||||
built-in default if that variable is not defined. See the table below for
|
||||
the supported file types and their corresponding variables and built-in
|
||||
defaults. Projects can provide a ``DESTINATION`` argument instead of a
|
||||
file type if they wish to explicitly define the install destination.
|
||||
|
||||
======================= ================================== =========================
|
||||
``TYPE`` Argument GNUInstallDirs Variable Built-In Default
|
||||
======================= ================================== =========================
|
||||
``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin``
|
||||
``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin``
|
||||
``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
|
||||
``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
|
||||
``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc``
|
||||
``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
|
||||
``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
|
||||
``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``<LOCALSTATE dir>/run``
|
||||
``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>``
|
||||
``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info``
|
||||
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
|
||||
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
|
||||
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc``
|
||||
======================= ================================== =========================
|
||||
|
||||
Projects wishing to follow the common practice of installing headers into a
|
||||
project-specific subdirectory will need to provide a destination rather than
|
||||
rely on the above.
|
||||
|
||||
Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
|
||||
a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
|
||||
``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
|
||||
default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
|
||||
``DATA`` instead.
|
||||
|
||||
To make packages compliant with distribution filesystem layout policies, if
|
||||
projects must specify a ``DESTINATION``, it is recommended that they use a
|
||||
path that begins with the appropriate :module:`GNUInstallDirs` variable.
|
||||
This allows package maintainers to control the install destination by setting
|
||||
the appropriate cache variables. The following example shows how to follow
|
||||
this advice while installing headers to a project-specific subdirectory:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
include(GNUInstallDirs)
|
||||
install(FILES mylib.h
|
||||
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
|
||||
)
|
||||
|
||||
An install destination given as a ``DESTINATION`` argument may
|
||||
use "generator expressions" with the syntax ``$<...>``. See the
|
||||
:manual:`cmake-generator-expressions(7)` manual for available expressions.
|
||||
|
||||
Installing Directories
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. _`install(DIRECTORY)`:
|
||||
.. _DIRECTORY:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(DIRECTORY dirs...
|
||||
TYPE <type> | DESTINATION <dir>
|
||||
[FILE_PERMISSIONS permissions...]
|
||||
[DIRECTORY_PERMISSIONS permissions...]
|
||||
[USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
|
||||
[CONFIGURATIONS [Debug|Release|...]]
|
||||
[COMPONENT <component>] [EXCLUDE_FROM_ALL]
|
||||
[FILES_MATCHING]
|
||||
[[PATTERN <pattern> | REGEX <regex>]
|
||||
[EXCLUDE] [PERMISSIONS permissions...]] [...])
|
||||
|
||||
The ``DIRECTORY`` form installs contents of one or more directories to a
|
||||
given destination. The directory structure is copied verbatim to the
|
||||
destination. The last component of each directory name is appended to
|
||||
the destination directory but a trailing slash may be used to avoid
|
||||
this because it leaves the last component empty. Directory names
|
||||
given as relative paths are interpreted with respect to the current
|
||||
source directory. If no input directory names are given the
|
||||
destination directory will be created but nothing will be installed
|
||||
into it. The ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` options
|
||||
specify permissions given to files and directories in the destination.
|
||||
If ``USE_SOURCE_PERMISSIONS`` is specified and ``FILE_PERMISSIONS`` is not,
|
||||
file permissions will be copied from the source directory structure.
|
||||
If no permissions are specified files will be given the default
|
||||
permissions specified in the ``FILES`` form of the command, and the
|
||||
directories will be given the default permissions specified in the
|
||||
``PROGRAMS`` form of the command.
|
||||
|
||||
The ``MESSAGE_NEVER`` option disables file installation status output.
|
||||
|
||||
Installation of directories may be controlled with fine granularity
|
||||
using the ``PATTERN`` or ``REGEX`` options. These "match" options specify a
|
||||
globbing pattern or regular expression to match directories or files
|
||||
encountered within input directories. They may be used to apply
|
||||
certain options (see below) to a subset of the files and directories
|
||||
encountered. The full path to each input file or directory (with
|
||||
forward slashes) is matched against the expression. A ``PATTERN`` will
|
||||
match only complete file names: the portion of the full path matching
|
||||
the pattern must occur at the end of the file name and be preceded by
|
||||
a slash. A ``REGEX`` will match any portion of the full path but it may
|
||||
use ``/`` and ``$`` to simulate the ``PATTERN`` behavior. By default all
|
||||
files and directories are installed whether or not they are matched.
|
||||
The ``FILES_MATCHING`` option may be given before the first match option
|
||||
to disable installation of files (but not directories) not matched by
|
||||
any expression. For example, the code
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(DIRECTORY src/ DESTINATION include/myproj
|
||||
FILES_MATCHING PATTERN "*.h")
|
||||
|
||||
will extract and install header files from a source tree.
|
||||
|
||||
Some options may follow a ``PATTERN`` or ``REGEX`` expression and are applied
|
||||
only to files or directories matching them. The ``EXCLUDE`` option will
|
||||
skip the matched file or directory. The ``PERMISSIONS`` option overrides
|
||||
the permissions setting for the matched file or directory. For
|
||||
example the code
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(DIRECTORY icons scripts/ DESTINATION share/myproj
|
||||
PATTERN "CVS" EXCLUDE
|
||||
PATTERN "scripts/*"
|
||||
PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
|
||||
GROUP_EXECUTE GROUP_READ)
|
||||
|
||||
will install the ``icons`` directory to ``share/myproj/icons`` and the
|
||||
``scripts`` directory to ``share/myproj``. The icons will get default
|
||||
file permissions, the scripts will be given specific permissions, and any
|
||||
``CVS`` directories will be excluded.
|
||||
|
||||
Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
|
||||
A ``TYPE`` argument specifies the generic file type of the files within the
|
||||
listed directories being installed. A destination will then be set
|
||||
automatically by taking the corresponding variable from
|
||||
:module:`GNUInstallDirs`, or by using a built-in default if that variable
|
||||
is not defined. See the table below for the supported file types and their
|
||||
corresponding variables and built-in defaults. Projects can provide a
|
||||
``DESTINATION`` argument instead of a file type if they wish to explicitly
|
||||
define the install destination.
|
||||
|
||||
======================= ================================== =========================
|
||||
``TYPE`` Argument GNUInstallDirs Variable Built-In Default
|
||||
======================= ================================== =========================
|
||||
``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin``
|
||||
``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin``
|
||||
``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
|
||||
``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
|
||||
``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc``
|
||||
``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
|
||||
``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
|
||||
``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``<LOCALSTATE dir>/run``
|
||||
``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>``
|
||||
``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info``
|
||||
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
|
||||
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
|
||||
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc``
|
||||
======================= ================================== =========================
|
||||
|
||||
Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
|
||||
a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
|
||||
``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
|
||||
default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
|
||||
``DATA`` instead.
|
||||
|
||||
To make packages compliant with distribution filesystem layout policies, if
|
||||
projects must specify a ``DESTINATION``, it is recommended that they use a
|
||||
path that begins with the appropriate :module:`GNUInstallDirs` variable.
|
||||
This allows package maintainers to control the install destination by setting
|
||||
the appropriate cache variables.
|
||||
|
||||
The list of ``dirs...`` given to ``DIRECTORY`` and an install destination
|
||||
given as a ``DESTINATION`` argument may use "generator expressions"
|
||||
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
|
||||
manual for available expressions.
|
||||
|
||||
Custom Installation Logic
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. _`install(CODE)`:
|
||||
.. _`install(SCRIPT)`:
|
||||
.. _CODE:
|
||||
.. _SCRIPT:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install([[SCRIPT <file>] [CODE <code>]]
|
||||
[COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
|
||||
|
||||
The ``SCRIPT`` form will invoke the given CMake script files during
|
||||
installation. If the script file name is a relative path it will be
|
||||
interpreted with respect to the current source directory. The ``CODE``
|
||||
form will invoke the given CMake code during installation. Code is
|
||||
specified as a single argument inside a double-quoted string. For
|
||||
example, the code
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(CODE "MESSAGE(\"Sample install message.\")")
|
||||
|
||||
will print a message during installation.
|
||||
|
||||
``<file>`` or ``<code>`` may use "generator expressions" with the syntax
|
||||
``$<...>`` (in the case of ``<file>``, this refers to their use in the file
|
||||
name, not the file's contents). See the
|
||||
:manual:`cmake-generator-expressions(7)` manual for available expressions.
|
||||
|
||||
Installing Exports
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. _`install(EXPORT)`:
|
||||
.. _EXPORT:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(EXPORT <export-name> DESTINATION <dir>
|
||||
[NAMESPACE <namespace>] [[FILE <name>.cmake]|
|
||||
[PERMISSIONS permissions...]
|
||||
[CONFIGURATIONS [Debug|Release|...]]
|
||||
[EXPORT_LINK_INTERFACE_LIBRARIES]
|
||||
[COMPONENT <component>]
|
||||
[EXCLUDE_FROM_ALL])
|
||||
install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
|
||||
|
||||
The ``EXPORT`` form generates and installs a CMake file containing code to
|
||||
import targets from the installation tree into another project.
|
||||
Target installations are associated with the export ``<export-name>``
|
||||
using the ``EXPORT`` option of the `install(TARGETS)`_ signature
|
||||
documented above. The ``NAMESPACE`` option will prepend ``<namespace>`` to
|
||||
the target names as they are written to the import file. By default
|
||||
the generated file will be called ``<export-name>.cmake`` but the ``FILE``
|
||||
option may be used to specify a different name. The value given to
|
||||
the ``FILE`` option must be a file name with the ``.cmake`` extension.
|
||||
If a ``CONFIGURATIONS`` option is given then the file will only be installed
|
||||
when one of the named configurations is installed. Additionally, the
|
||||
generated import file will reference only the matching target
|
||||
configurations. The ``EXPORT_LINK_INTERFACE_LIBRARIES`` keyword, if
|
||||
present, causes the contents of the properties matching
|
||||
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
|
||||
policy :policy:`CMP0022` is ``NEW``.
|
||||
|
||||
.. note::
|
||||
The installed ``<export-name>.cmake`` file may come with additional
|
||||
per-configuration ``<export-name>-*.cmake`` files to be loaded by
|
||||
globbing. Do not use an export name that is the same as the package
|
||||
name in combination with installing a ``<package-name>-config.cmake``
|
||||
file or the latter may be incorrectly matched by the glob and loaded.
|
||||
|
||||
When a ``COMPONENT`` option is given, the listed ``<component>`` implicitly
|
||||
depends on all components mentioned in the export set. The exported
|
||||
``<name>.cmake`` file will require each of the exported components to be
|
||||
present in order for dependent projects to build properly. For example, a
|
||||
project may define components ``Runtime`` and ``Development``, with shared
|
||||
libraries going into the ``Runtime`` component and static libraries and
|
||||
headers going into the ``Development`` component. The export set would also
|
||||
typically be part of the ``Development`` component, but it would export
|
||||
targets from both the ``Runtime`` and ``Development`` components. Therefore,
|
||||
the ``Runtime`` component would need to be installed if the ``Development``
|
||||
component was installed, but not vice versa. If the ``Development`` component
|
||||
was installed without the ``Runtime`` component, dependent projects that try
|
||||
to link against it would have build errors. Package managers, such as APT and
|
||||
RPM, typically handle this by listing the ``Runtime`` component as a dependency
|
||||
of the ``Development`` component in the package metadata, ensuring that the
|
||||
library is always installed if the headers and CMake export file are present.
|
||||
|
||||
In addition to cmake language files, the ``EXPORT_ANDROID_MK`` mode maybe
|
||||
used to specify an export to the android ndk build system. This mode
|
||||
accepts the same options as the normal export mode. 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 ``EXPORT`` form is useful to help outside projects use targets built
|
||||
and installed by the current project. For example, the code
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
install(TARGETS myexe EXPORT myproj DESTINATION bin)
|
||||
install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
|
||||
install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
|
||||
|
||||
will install the executable ``myexe`` to ``<prefix>/bin`` and code to import
|
||||
it in the file ``<prefix>/lib/myproj/myproj.cmake`` and
|
||||
``<prefix>/share/ndk-modules/Android.mk``. An outside project
|
||||
may load this file with the include command and reference the ``myexe``
|
||||
executable from the installation tree using the imported target name
|
||||
``mp_myexe`` as if the target were built in its own tree.
|
||||
|
||||
.. note::
|
||||
This command supercedes the :command:`install_targets` command and
|
||||
the :prop_tgt:`PRE_INSTALL_SCRIPT` and :prop_tgt:`POST_INSTALL_SCRIPT`
|
||||
target properties. It also replaces the ``FILES`` forms of the
|
||||
:command:`install_files` and :command:`install_programs` commands.
|
||||
The processing order of these install rules relative to
|
||||
those generated by :command:`install_targets`,
|
||||
:command:`install_files`, and :command:`install_programs` commands
|
||||
is not defined.
|
||||
|
||||
Generated Installation Script
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. note::
|
||||
|
||||
Use of this feature is not recommended. Please consider using the
|
||||
``--install`` argument of :manual:`cmake(1)` instead.
|
||||
|
||||
The ``install()`` command generates a file, ``cmake_install.cmake``, inside
|
||||
the build directory, which is used internally by the generated install target
|
||||
and by CPack. You can also invoke this script manually with ``cmake -P``. This
|
||||
script accepts several variables:
|
||||
|
||||
``COMPONENT``
|
||||
Set this variable to install only a single CPack component as opposed to all
|
||||
of them. For example, if you only want to install the ``Development``
|
||||
component, run ``cmake -DCOMPONENT=Development -P cmake_install.cmake``.
|
||||
|
||||
``BUILD_TYPE``
|
||||
Set this variable to change the build type if you are using a multi-config
|
||||
generator. For example, to install with the ``Debug`` configuration, run
|
||||
``cmake -DBUILD_TYPE=Debug -P cmake_install.cmake``.
|
||||
|
||||
``DESTDIR``
|
||||
This is an environment variable rather than a CMake variable. It allows you
|
||||
to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for
|
||||
details.
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
install_files
|
||||
-------------
|
||||
|
||||
.. deprecated:: 3.0
|
||||
|
||||
Use the :command:`install(FILES)` command instead.
|
||||
|
||||
This command has been superceded 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.
|
||||
|
||||
::
|
||||
|
||||
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``.
|
||||
|
||||
::
|
||||
|
||||
install_files(<dir> regexp)
|
||||
|
||||
Any files in the current source directory that match the regular
|
||||
expression will be installed.
|
||||
|
||||
::
|
||||
|
||||
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`.
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
install_programs
|
||||
----------------
|
||||
|
||||
.. deprecated:: 3.0
|
||||
|
||||
Use the :command:`install(PROGRAMS)` command instead.
|
||||
|
||||
This command has been superceded 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.
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
||||
::
|
||||
|
||||
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`.
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
install_targets
|
||||
---------------
|
||||
|
||||
.. deprecated:: 3.0
|
||||
|
||||
Use the :command:`install(TARGETS)` command instead.
|
||||
|
||||
This command has been superceded by the :command:`install` command. It is
|
||||
provided for compatibility with older CMake code.
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
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 directories are added to the :prop_dir:`LINK_DIRECTORIES` directory
|
||||
property for the current ``CMakeLists.txt`` file, converting relative
|
||||
paths to absolute as needed.
|
||||
The command will apply only to targets created after it is called.
|
||||
|
||||
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.
|
||||
|
||||
Arguments to ``link_directories`` may use "generator expressions" with
|
||||
the syntax "$<...>". See the :manual:`cmake-generator-expressions(7)`
|
||||
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
|
||||
manual for more on defining buildsystem properties.
|
||||
|
||||
.. 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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,332 @@
|
|||
list
|
||||
----
|
||||
|
||||
List operations.
|
||||
|
||||
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 ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``,
|
||||
``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``,
|
||||
``REMOVE_DUPLICATES``, ``REVERSE`` and ``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 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 macro arguments are not
|
||||
variables, and therefore cannot be used in LIST commands.)
|
||||
|
||||
.. 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
|
||||
^^^^^^^
|
||||
|
||||
.. _LENGTH:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(LENGTH <list> <output variable>)
|
||||
|
||||
Returns the list's length.
|
||||
|
||||
.. _GET:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(GET <list> <element index> [<element index> ...] <output variable>)
|
||||
|
||||
Returns the list of elements specified by indices from the list.
|
||||
|
||||
.. _JOIN:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(JOIN <list> <glue> <output variable>)
|
||||
|
||||
Returns a string joining all list's elements using the glue string.
|
||||
To join multiple strings, which are not part of a list, use ``JOIN`` operator
|
||||
from :command:`string` command.
|
||||
|
||||
.. _SUBLIST:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(SUBLIST <list> <begin> <length> <output variable>)
|
||||
|
||||
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
|
||||
^^^^^^
|
||||
|
||||
.. _FIND:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(FIND <list> <value> <output variable>)
|
||||
|
||||
Returns the index of the element specified in the list or -1
|
||||
if it wasn't found.
|
||||
|
||||
Modification
|
||||
^^^^^^^^^^^^
|
||||
|
||||
.. _APPEND:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(APPEND <list> [<element> ...])
|
||||
|
||||
Appends elements to the list.
|
||||
|
||||
.. _FILTER:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
|
||||
|
||||
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 see also the
|
||||
:command:`string` command.
|
||||
|
||||
.. _INSERT:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(INSERT <list> <element_index> <element> [<element> ...])
|
||||
|
||||
Inserts elements to the list to the specified location.
|
||||
|
||||
.. _POP_BACK:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(POP_BACK <list> [<out-var>...])
|
||||
|
||||
If no variable name is given, removes exactly one element. Otherwise,
|
||||
assign the last element's value to the given variable and removes it,
|
||||
up to the last variable name given.
|
||||
|
||||
.. _POP_FRONT:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(POP_FRONT <list> [<out-var>...])
|
||||
|
||||
If no variable name is given, removes exactly one element. Otherwise,
|
||||
assign the first element's value to the given variable and removes it,
|
||||
up to the last variable name given.
|
||||
|
||||
.. _PREPEND:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(PREPEND <list> [<element> ...])
|
||||
|
||||
Insert elements to the 0th position in the list.
|
||||
|
||||
.. _REMOVE_ITEM:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(REMOVE_ITEM <list> <value> [<value> ...])
|
||||
|
||||
Removes all instances of the given items from the list.
|
||||
|
||||
.. _REMOVE_AT:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(REMOVE_AT <list> <index> [<index> ...])
|
||||
|
||||
Removes items at given indices from the list.
|
||||
|
||||
.. _REMOVE_DUPLICATES:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
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.
|
||||
|
||||
.. _TRANSFORM:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(TRANSFORM <list> <ACTION> [<SELECTOR>]
|
||||
[OUTPUT_VARIABLE <output variable>])
|
||||
|
||||
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:
|
||||
|
||||
``APPEND``, ``PREPEND``: Append, prepend specified value to each element of
|
||||
the list.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
|
||||
|
||||
``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower
|
||||
characters.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
|
||||
|
||||
``STRIP``: Remove leading and trailing spaces from each element of the
|
||||
list.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(TRANSFORM <list> STRIP ...)
|
||||
|
||||
``GENEX_STRIP``: Strip any
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>` from each
|
||||
element of the list.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(TRANSFORM <list> GENEX_STRIP ...)
|
||||
|
||||
``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 ``REGEX REPLACE`` from :command:`string` command).
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(TRANSFORM <list> REPLACE <regular_expression>
|
||||
<replace_expression> ...)
|
||||
|
||||
``<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
|
||||
^^^^^^^^
|
||||
|
||||
.. _REVERSE:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(REVERSE <list>)
|
||||
|
||||
Reverses the contents of the list in-place.
|
||||
|
||||
.. _SORT:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
|
||||
|
||||
Sorts the list in-place alphabetically.
|
||||
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.
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
load_cache
|
||||
----------
|
||||
|
||||
Load in the values from another project's CMake cache.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)
|
||||
|
||||
Reads the cache and store the requested entries in variables with their
|
||||
name prefixed with the given prefix. This only reads the values, and
|
||||
does not create entries in the local project's cache.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
load_cache(pathToBuildDirectory [EXCLUDE entry1...]
|
||||
[INCLUDE_INTERNALS entry1...])
|
||||
|
||||
Loads in the values from another cache and store them in the local
|
||||
project's cache as internal entries. This is useful for a project
|
||||
that depends on another project built in a different tree. ``EXCLUDE``
|
||||
option can be used to provide a list of entries to be excluded.
|
||||
``INCLUDE_INTERNALS`` can be used to provide a list of internal entries to
|
||||
be included. Normally, no internal entries are brought in. Use of
|
||||
this form of the command is strongly discouraged, but it is provided
|
||||
for backward compatibility.
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
load_command
|
||||
------------
|
||||
|
||||
Disallowed since version 3.0. See CMake Policy :policy:`CMP0031`.
|
||||
|
||||
Load a command into a running CMake.
|
||||
|
||||
::
|
||||
|
||||
load_command(COMMAND_NAME <loc1> [loc2 ...])
|
||||
|
||||
The given locations are searched for a library whose name is
|
||||
cmCOMMAND_NAME. If found, it is loaded as a module and the command is
|
||||
added to the set of available CMake commands. Usually,
|
||||
:command:`try_compile` is used before this command to compile the
|
||||
module. If the command is successfully loaded a variable named
|
||||
|
||||
::
|
||||
|
||||
CMAKE_LOADED_COMMAND_<COMMAND_NAME>
|
||||
|
||||
will be set to the full path of the module that was loaded. Otherwise
|
||||
the variable will not be set.
|
||||
|
|
@ -0,0 +1,150 @@
|
|||
macro
|
||||
-----
|
||||
|
||||
Start recording a macro for later invocation as a command
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
macro(<name> [<arg1> ...])
|
||||
<commands>
|
||||
endmacro()
|
||||
|
||||
Defines a macro named ``<name>`` that takes arguments named
|
||||
``<arg1>``, ... Commands listed after macro, but before the
|
||||
matching :command:`endmacro()`, are not executed until the macro
|
||||
is invoked.
|
||||
|
||||
Per legacy, the :command:`endmacro` command admits an optional
|
||||
``<name>`` argument. If used, it must be a verbatim repeat of the
|
||||
argument of the opening ``macro`` command.
|
||||
|
||||
See the :command:`cmake_policy()` command documentation for the behavior
|
||||
of policies inside macros.
|
||||
|
||||
See the :ref:`Macro vs Function` section below for differences
|
||||
between CMake macros and :command:`functions <function>`.
|
||||
|
||||
Invocation
|
||||
^^^^^^^^^^
|
||||
|
||||
The macro invocation is case-insensitive. A macro defined as
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
macro(foo)
|
||||
<commands>
|
||||
endmacro()
|
||||
|
||||
can be invoked through any of
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
foo()
|
||||
Foo()
|
||||
FOO()
|
||||
cmake_language(CALL foo)
|
||||
|
||||
and so on. However, it is strongly recommended to stay with the
|
||||
case chosen in the macro definition. Typically macros use
|
||||
all-lowercase names.
|
||||
|
||||
The :command:`cmake_language(CALL ...)` command can also be used to
|
||||
invoke the macro.
|
||||
|
||||
Arguments
|
||||
^^^^^^^^^
|
||||
|
||||
When a macro is invoked, the commands recorded in the macro are
|
||||
first modified by replacing formal parameters (``${arg1}``, ...)
|
||||
with the arguments passed, and then invoked as normal commands.
|
||||
|
||||
In addition to referencing the formal parameters you can reference the
|
||||
values ``${ARGC}`` which will be set to the number of arguments passed
|
||||
into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``,
|
||||
... which will have the actual values of the arguments passed in.
|
||||
This facilitates creating macros with optional arguments.
|
||||
|
||||
Furthermore, ``${ARGV}`` holds the list of all arguments given to the
|
||||
macro and ``${ARGN}`` holds the list of arguments past the last expected
|
||||
argument.
|
||||
Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined
|
||||
behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only
|
||||
way to ensure that ``${ARGV#}`` was passed to the function as an extra
|
||||
argument.
|
||||
|
||||
.. _`Macro vs Function`:
|
||||
|
||||
Macro vs Function
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``macro`` command is very similar to the :command:`function` command.
|
||||
Nonetheless, there are a few important differences.
|
||||
|
||||
In a function, ``ARGN``, ``ARGC``, ``ARGV`` and ``ARGV0``, ``ARGV1``, ...
|
||||
are true variables in the usual CMake sense. In a macro, they are not,
|
||||
they are string replacements much like the C preprocessor would do
|
||||
with a macro. This has a number of consequences, as explained in
|
||||
the :ref:`Argument Caveats` section below.
|
||||
|
||||
Another difference between macros and functions is the control flow.
|
||||
A function is executed by transferring control from the calling
|
||||
statement to the function body. A macro is executed as if the macro
|
||||
body were pasted in place of the calling statement. This has the
|
||||
consequence that a :command:`return()` in a macro body does not
|
||||
just terminate execution of the macro; rather, control is returned
|
||||
from the scope of the macro call. To avoid confusion, it is recommended
|
||||
to avoid :command:`return()` in macros altogether.
|
||||
|
||||
Unlike a function, the :variable:`CMAKE_CURRENT_FUNCTION`,
|
||||
:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`,
|
||||
:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`,
|
||||
:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` variables are not
|
||||
set for a macro.
|
||||
|
||||
.. _`Argument Caveats`:
|
||||
|
||||
Argument Caveats
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Since ``ARGN``, ``ARGC``, ``ARGV``, ``ARGV0`` etc. are not variables,
|
||||
you will NOT be able to use commands like
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
if(ARGV1) # ARGV1 is not a variable
|
||||
if(DEFINED ARGV2) # ARGV2 is not a variable
|
||||
if(ARGC GREATER 2) # ARGC is not a variable
|
||||
foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
|
||||
|
||||
In the first case, you can use ``if(${ARGV1})``. In the second and
|
||||
third case, the proper way to check if an optional variable was
|
||||
passed to the macro is to use ``if(${ARGC} GREATER 2)``. In the
|
||||
last case, you can use ``foreach(loop_var ${ARGN})`` but this will
|
||||
skip empty arguments. If you need to include them, you can use
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(list_var "${ARGN}")
|
||||
foreach(loop_var IN LISTS list_var)
|
||||
|
||||
Note that if you have a variable with the same name in the scope from
|
||||
which the macro is called, using unreferenced names will use the
|
||||
existing variable instead of the arguments. For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
macro(bar)
|
||||
foreach(arg IN LISTS ARGN)
|
||||
<commands>
|
||||
endforeach()
|
||||
endmacro()
|
||||
|
||||
function(foo)
|
||||
bar(x y z)
|
||||
endfunction()
|
||||
|
||||
foo(a b c)
|
||||
|
||||
Will loop over ``a;b;c`` and not over ``x;y;z`` as one might have expected.
|
||||
If you want true CMake variables and/or better CMake scope control you
|
||||
should look at the function command.
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
make_directory
|
||||
--------------
|
||||
|
||||
.. deprecated:: 3.0
|
||||
|
||||
Use the :command:`file(MAKE_DIRECTORY)` command instead.
|
||||
|
||||
::
|
||||
|
||||
make_directory(directory)
|
||||
|
||||
Creates the specified directory. Full paths should be given. Any
|
||||
parent directories that do not exist will also be created. Use with
|
||||
care.
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
mark_as_advanced
|
||||
----------------
|
||||
|
||||
Mark cmake cached variables as advanced.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
mark_as_advanced([CLEAR|FORCE] <var1> ...)
|
||||
|
||||
Sets the advanced/non-advanced state of the named
|
||||
cached variables.
|
||||
|
||||
An advanced variable will not be displayed in any
|
||||
of the cmake GUIs unless the ``show advanced`` option is on.
|
||||
In script mode, the advanced/non-advanced state has no effect.
|
||||
|
||||
If the keyword ``CLEAR`` is given
|
||||
then advanced variables are changed back to unadvanced.
|
||||
If the keyword ``FORCE`` is given
|
||||
then the variables are made advanced.
|
||||
If neither ``FORCE`` nor ``CLEAR`` is specified,
|
||||
new values will be marked as advanced, but if a
|
||||
variable already has an advanced/non-advanced state,
|
||||
it will not be changed.
|
||||
|
||||
.. note::
|
||||
|
||||
Policy :policy:`CMP0102` affects the behavior of the ``mark_as_advanced``
|
||||
call. When set to ``NEW``, variables passed to this command which are not
|
||||
already in the cache are ignored. See policy :policy:`CMP0102`.
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
math
|
||||
----
|
||||
|
||||
Evaluate a mathematical expression.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
|
||||
|
||||
Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the
|
||||
resulting value. The result of the expression must be representable as a
|
||||
64-bit signed integer.
|
||||
|
||||
The mathematical expression must be given as a string (i.e. enclosed in
|
||||
double quotation marks). An example is ``"5 * (10 + 13)"``.
|
||||
Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``,
|
||||
``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning
|
||||
as in C code.
|
||||
|
||||
Hexadecimal numbers are recognized when prefixed with ``0x``, as in C code.
|
||||
|
||||
The result is formatted according to the option ``OUTPUT_FORMAT``,
|
||||
where ``<format>`` is one of
|
||||
|
||||
``HEXADECIMAL``
|
||||
Hexadecimal notation as in C code, i. e. starting with "0x".
|
||||
``DECIMAL``
|
||||
Decimal notation. Which is also used if no ``OUTPUT_FORMAT`` option
|
||||
is specified.
|
||||
|
||||
|
||||
For example
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
|
||||
math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"
|
||||
|
|
@ -0,0 +1,182 @@
|
|||
message
|
||||
-------
|
||||
|
||||
Log a message.
|
||||
|
||||
Synopsis
|
||||
^^^^^^^^
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
`General messages`_
|
||||
message([<mode>] "message text" ...)
|
||||
|
||||
`Reporting checks`_
|
||||
message(<checkState> "message text" ...)
|
||||
|
||||
|
||||
General messages
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
message([<mode>] "message text" ...)
|
||||
|
||||
Record the specified message text in the log. If more than one message
|
||||
string is given, they are concatenated into a single message with no
|
||||
separator between the strings.
|
||||
|
||||
The optional ``<mode>`` keyword determines the type of message, which
|
||||
influences the way the message is handled:
|
||||
|
||||
``FATAL_ERROR``
|
||||
CMake Error, stop processing and generation.
|
||||
|
||||
``SEND_ERROR``
|
||||
CMake Error, continue processing, but skip generation.
|
||||
|
||||
``WARNING``
|
||||
CMake Warning, continue processing.
|
||||
|
||||
``AUTHOR_WARNING``
|
||||
CMake Warning (dev), continue processing.
|
||||
|
||||
``DEPRECATION``
|
||||
CMake Deprecation Error or Warning if variable
|
||||
:variable:`CMAKE_ERROR_DEPRECATED` or :variable:`CMAKE_WARN_DEPRECATED`
|
||||
is enabled, respectively, else no message.
|
||||
|
||||
(none) or ``NOTICE``
|
||||
Important message printed to stderr to attract user's attention.
|
||||
|
||||
``STATUS``
|
||||
The main interesting messages that project users might be interested in.
|
||||
Ideally these should be concise, no more than a single line, but still
|
||||
informative.
|
||||
|
||||
``VERBOSE``
|
||||
Detailed informational messages intended for project users. These messages
|
||||
should provide additional details that won't be of interest in most cases,
|
||||
but which may be useful to those building the project when they want deeper
|
||||
insight into what's happening.
|
||||
|
||||
``DEBUG``
|
||||
Detailed informational messages intended for developers working on the
|
||||
project itself as opposed to users who just want to build it. These messages
|
||||
will not typically be of interest to other users building the project and
|
||||
will often be closely related to internal implementation details.
|
||||
|
||||
``TRACE``
|
||||
Fine-grained messages with very low-level implementation details. Messages
|
||||
using this log level would normally only be temporary and would expect to be
|
||||
removed before releasing the project, packaging up the files, etc.
|
||||
|
||||
The CMake command-line tool displays ``STATUS`` to ``TRACE`` messages on stdout
|
||||
with the message preceded by two hyphens and a space. All other message types
|
||||
are sent to stderr and are not prefixed with hyphens. The
|
||||
:manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area.
|
||||
The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE``
|
||||
messages one at a time on a status line and other messages in an
|
||||
interactive pop-up box. The ``--log-level`` command-line option to each of
|
||||
these tools can be used to control which messages will be shown.
|
||||
To make a log level persist between CMake runs, the
|
||||
:variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead.
|
||||
Note that the command line option takes precedence over the cache variable.
|
||||
|
||||
Messages of log levels ``NOTICE`` and below will have each line preceded
|
||||
by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to
|
||||
a single string by concatenating its list items). For ``STATUS`` to ``TRACE``
|
||||
messages, this indenting content will be inserted after the hyphens.
|
||||
|
||||
Messages of log levels ``NOTICE`` and below can also have each line preceded
|
||||
with context of the form ``[some.context.example]``. The content between the
|
||||
square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT`
|
||||
list variable to a dot-separated string. The message context will always
|
||||
appear before any indenting content but after any automatically added leading
|
||||
hyphens. By default, message context is not shown, it has to be explicitly
|
||||
enabled by giving the :manual:`cmake <cmake(1)>` ``--log-context``
|
||||
command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW`
|
||||
variable to true. See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for
|
||||
usage examples.
|
||||
|
||||
CMake Warning and Error message text displays using a simple markup
|
||||
language. Non-indented text is formatted in line-wrapped paragraphs
|
||||
delimited by newlines. Indented text is considered pre-formatted.
|
||||
|
||||
|
||||
Reporting checks
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
A common pattern in CMake output is a message indicating the start of some
|
||||
sort of check, followed by another message reporting the result of that check.
|
||||
For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
message(STATUS "Looking for someheader.h")
|
||||
#... do the checks, set checkSuccess with the result
|
||||
if(checkSuccess)
|
||||
message(STATUS "Looking for someheader.h - found")
|
||||
else()
|
||||
message(STATUS "Looking for someheader.h - not found")
|
||||
endif()
|
||||
|
||||
This can be more robustly and conveniently expressed using the ``CHECK_...``
|
||||
keyword form of the ``message()`` command:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
message(<checkState> "message" ...)
|
||||
|
||||
where ``<checkState>`` must be one of the following:
|
||||
|
||||
``CHECK_START``
|
||||
Record a concise message about the check about to be performed.
|
||||
|
||||
``CHECK_PASS``
|
||||
Record a successful result for a check.
|
||||
|
||||
``CHECK_FAIL``
|
||||
Record an unsuccessful result for a check.
|
||||
|
||||
When recording a check result, the command repeats the message from the most
|
||||
recently started check for which no result has yet been reported, then some
|
||||
separator characters and then the message text provided after the
|
||||
``CHECK_PASS`` or ``CHECK_FAIL`` keyword. Check messages are always reported
|
||||
at ``STATUS`` log level.
|
||||
|
||||
Checks may be nested and every ``CHECK_START`` should have exactly one
|
||||
matching ``CHECK_PASS`` or ``CHECK_FAIL``.
|
||||
The :variable:`CMAKE_MESSAGE_INDENT` variable can also be used to add
|
||||
indenting to nested checks if desired. For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
message(CHECK_START "Finding my things")
|
||||
list(APPEND CMAKE_MESSAGE_INDENT " ")
|
||||
unset(missingComponents)
|
||||
|
||||
message(CHECK_START "Finding partA")
|
||||
# ... do check, assume we find A
|
||||
message(CHECK_PASS "found")
|
||||
|
||||
message(CHECK_START "Finding partB")
|
||||
# ... do check, assume we don't find B
|
||||
list(APPEND missingComponents B)
|
||||
message(CHECK_FAIL "not found")
|
||||
|
||||
list(POP_BACK CMAKE_MESSAGE_INDENT)
|
||||
if(missingComponents)
|
||||
message(CHECK_FAIL "missing components: ${missingComponents}")
|
||||
else()
|
||||
message(CHECK_PASS "all components found")
|
||||
endif()
|
||||
|
||||
Output from the above would appear something like the following::
|
||||
|
||||
-- Finding my things
|
||||
-- Finding partA
|
||||
-- Finding partA - found
|
||||
-- Finding partB
|
||||
-- Finding partB - not found
|
||||
-- Finding my things - missing components: B
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
option
|
||||
------
|
||||
|
||||
Provide an option that the user can optionally select.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
option(<variable> "<help_text>" [value])
|
||||
|
||||
Provides an option for the user to select as ``ON`` or ``OFF``.
|
||||
If no initial ``<value>`` is provided, ``OFF`` is used.
|
||||
If ``<variable>`` is already set as a normal or cache variable,
|
||||
then the command does nothing (see policy :policy:`CMP0077`).
|
||||
|
||||
If you have options that depend on the values of other options, see
|
||||
the module help for :module:`CMakeDependentOption`.
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
output_required_files
|
||||
---------------------
|
||||
|
||||
Disallowed since version 3.0. See CMake Policy :policy:`CMP0032`.
|
||||
|
||||
Approximate C preprocessor dependency scanning.
|
||||
|
||||
This command exists only because ancient CMake versions provided it.
|
||||
CMake handles preprocessor dependency scanning automatically using a
|
||||
more advanced scanner.
|
||||
|
||||
::
|
||||
|
||||
output_required_files(srcfile outputfile)
|
||||
|
||||
Outputs a list of all the source files that are required by the
|
||||
specified ``srcfile``. This list is written into ``outputfile``. This is
|
||||
similar to writing out the dependencies for ``srcfile`` except that it
|
||||
jumps from ``.h`` files into ``.cxx``, ``.c`` and ``.cpp`` files if possible.
|
||||
|
|
@ -0,0 +1,133 @@
|
|||
project
|
||||
-------
|
||||
|
||||
Set the name of the project.
|
||||
|
||||
Synopsis
|
||||
^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
project(<PROJECT-NAME> [<language-name>...])
|
||||
project(<PROJECT-NAME>
|
||||
[VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
|
||||
[DESCRIPTION <project-description-string>]
|
||||
[HOMEPAGE_URL <url-string>]
|
||||
[LANGUAGES <language-name>...])
|
||||
|
||||
Sets the name of the project, and stores it in the variable
|
||||
:variable:`PROJECT_NAME`. When called from the top-level
|
||||
``CMakeLists.txt`` also stores the project name in the
|
||||
variable :variable:`CMAKE_PROJECT_NAME`.
|
||||
|
||||
Also sets the variables
|
||||
|
||||
* :variable:`PROJECT_SOURCE_DIR`,
|
||||
:variable:`<PROJECT-NAME>_SOURCE_DIR`
|
||||
* :variable:`PROJECT_BINARY_DIR`,
|
||||
:variable:`<PROJECT-NAME>_BINARY_DIR`
|
||||
|
||||
Further variables are set by the optional arguments described in the following.
|
||||
If any of these arguments is not used, then the corresponding variables are
|
||||
set to the empty string.
|
||||
|
||||
Options
|
||||
^^^^^^^
|
||||
|
||||
The options are:
|
||||
|
||||
``VERSION <version>``
|
||||
Optional; may not be used unless policy :policy:`CMP0048` is
|
||||
set to ``NEW``.
|
||||
|
||||
Takes a ``<version>`` argument composed of non-negative integer components,
|
||||
i.e. ``<major>[.<minor>[.<patch>[.<tweak>]]]``,
|
||||
and sets the variables
|
||||
|
||||
* :variable:`PROJECT_VERSION`,
|
||||
:variable:`<PROJECT-NAME>_VERSION`
|
||||
* :variable:`PROJECT_VERSION_MAJOR`,
|
||||
:variable:`<PROJECT-NAME>_VERSION_MAJOR`
|
||||
* :variable:`PROJECT_VERSION_MINOR`,
|
||||
:variable:`<PROJECT-NAME>_VERSION_MINOR`
|
||||
* :variable:`PROJECT_VERSION_PATCH`,
|
||||
:variable:`<PROJECT-NAME>_VERSION_PATCH`
|
||||
* :variable:`PROJECT_VERSION_TWEAK`,
|
||||
:variable:`<PROJECT-NAME>_VERSION_TWEAK`.
|
||||
|
||||
When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
|
||||
then the version is also stored in the variable :variable:`CMAKE_PROJECT_VERSION`.
|
||||
|
||||
``DESCRIPTION <project-description-string>``
|
||||
Optional.
|
||||
Sets the variables
|
||||
|
||||
* :variable:`PROJECT_DESCRIPTION`, :variable:`<PROJECT-NAME>_DESCRIPTION`
|
||||
|
||||
to ``<project-description-string>``.
|
||||
It is recommended that this description is a relatively short string,
|
||||
usually no more than a few words.
|
||||
|
||||
When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
|
||||
then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`.
|
||||
|
||||
``HOMEPAGE_URL <url-string>``
|
||||
Optional.
|
||||
Sets the variables
|
||||
|
||||
* :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL`
|
||||
|
||||
to ``<url-string>``, which should be the canonical home URL for the project.
|
||||
|
||||
When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
|
||||
then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`.
|
||||
|
||||
``LANGUAGES <language-name>...``
|
||||
Optional.
|
||||
Can also be specified without ``LANGUAGES`` keyword per the first, short signature.
|
||||
|
||||
Selects which programming languages are needed to build the project.
|
||||
Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``,
|
||||
``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, and ``ASM``.
|
||||
By default ``C`` and ``CXX`` are enabled if no language options are given.
|
||||
Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages,
|
||||
to skip enabling any languages.
|
||||
|
||||
If enabling ``ASM``, list it last so that CMake can check whether
|
||||
compilers for other languages like ``C`` work for assembly too.
|
||||
|
||||
The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL``
|
||||
options are intended for use as default values in package metadata and documentation.
|
||||
|
||||
Code Injection
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or
|
||||
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set,
|
||||
the files they point to will be included as the first step of the
|
||||
``project()`` command.
|
||||
If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be
|
||||
included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`.
|
||||
|
||||
If the :variable:`CMAKE_PROJECT_INCLUDE` or
|
||||
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files
|
||||
they point to will be included as the last step of the ``project()`` command.
|
||||
If both are set, then :variable:`CMAKE_PROJECT_INCLUDE` will be included before
|
||||
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`.
|
||||
|
||||
Usage
|
||||
^^^^^
|
||||
|
||||
The top-level ``CMakeLists.txt`` file for a project must contain a
|
||||
literal, direct call to the ``project()`` command; loading one
|
||||
through the :command:`include` command is not sufficient. If no such
|
||||
call exists, CMake will issue a warning and pretend there is a
|
||||
``project(Project)`` at the top to enable the default languages
|
||||
(``C`` and ``CXX``).
|
||||
|
||||
.. note::
|
||||
Call the ``project()`` command near the top of the top-level
|
||||
``CMakeLists.txt``, but *after* calling :command:`cmake_minimum_required`.
|
||||
It is important to establish version and policy settings before invoking
|
||||
other commands whose behavior they may affect.
|
||||
See also policy :policy:`CMP0000`.
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
qt_wrap_cpp
|
||||
-----------
|
||||
|
||||
.. deprecated:: 3.14
|
||||
|
||||
This command was originally added to support Qt 3 before the
|
||||
:command:`add_custom_command()` command was sufficiently mature. The
|
||||
:module:`FindQt4` module provides the ``qt4_wrap_cpp()`` macro, which
|
||||
should be used instead for Qt 4 projects. For projects using Qt 5 or
|
||||
later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides
|
||||
``qt5_wrap_cpp()``).
|
||||
|
||||
Manually create Qt Wrappers.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
|
||||
|
||||
Produces moc files for all the .h files listed in the SourceLists. The
|
||||
moc files will be added to the library using the ``DestName`` source list.
|
||||
|
||||
Consider updating the project to use the :prop_tgt:`AUTOMOC` target property
|
||||
instead for a more automated way of invoking the ``moc`` tool.
|
||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue