mirror of
https://github.com/crystalidea/qt-build-tools.git
synced 2024-11-26 04:31:39 +08:00
qt 6.5.1 builds
This commit is contained in:
parent
fffd3d4b0a
commit
d516dfb2a3
BIN
6.5.1/_tools/7z.dll
Normal file
BIN
6.5.1/_tools/7z.dll
Normal file
Binary file not shown.
BIN
6.5.1/_tools/7z.exe
Normal file
BIN
6.5.1/_tools/7z.exe
Normal file
Binary file not shown.
BIN
6.5.1/_tools/cmake/bin/cmake-gui.exe
Normal file
BIN
6.5.1/_tools/cmake/bin/cmake-gui.exe
Normal file
Binary file not shown.
BIN
6.5.1/_tools/cmake/bin/cmake.exe
Normal file
BIN
6.5.1/_tools/cmake/bin/cmake.exe
Normal file
Binary file not shown.
BIN
6.5.1/_tools/cmake/bin/cmcldeps.exe
Normal file
BIN
6.5.1/_tools/cmake/bin/cmcldeps.exe
Normal file
Binary file not shown.
BIN
6.5.1/_tools/cmake/bin/cpack.exe
Normal file
BIN
6.5.1/_tools/cmake/bin/cpack.exe
Normal file
Binary file not shown.
BIN
6.5.1/_tools/cmake/bin/ctest.exe
Normal file
BIN
6.5.1/_tools/cmake/bin/ctest.exe
Normal file
Binary file not shown.
44
6.5.1/_tools/cmake/share/aclocal/cmake.m4
Normal file
44
6.5.1/_tools/cmake/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, MIPSpro, 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
|
||||||
|
])
|
145
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/FIND_XXX.txt
Normal file
145
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/FIND_XXX.txt
Normal file
@ -0,0 +1,145 @@
|
|||||||
|
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"]
|
||||||
|
[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``, and 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.
|
||||||
|
|
||||||
|
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 loaded by
|
||||||
|
: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, root paths from the parent's find module will be
|
||||||
|
searched after paths from the current module,
|
||||||
|
i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
|
||||||
|
``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
|
||||||
|
This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
|
||||||
|
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.
|
||||||
|
|
||||||
|
* |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.
|
||||||
|
|
||||||
|
* |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 an argument.
|
||||||
|
|
||||||
|
* |SYSTEM_ENVIRONMENT_PATH_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.
|
||||||
|
|
||||||
|
* |CMAKE_SYSTEM_PREFIX_PATH_XXX|
|
||||||
|
* |CMAKE_SYSTEM_XXX_PATH|
|
||||||
|
* |CMAKE_SYSTEM_XXX_MAC_PATH|
|
||||||
|
|
||||||
|
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 is own syntax.
|
||||||
|
The ``LINKER:`` prefix can be used to specify, in a portable way, options
|
||||||
|
to pass to the linker tool. The ``LINKER:`` prefix is replaced by the required
|
||||||
|
driver option and the rest of the option string defines linker arguments using
|
||||||
|
``,`` as separator. These arguments will be formatted according to 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 alternate syntax, specification of
|
||||||
|
arguments using ``SHELL:`` prefix and space as separator. Previous example
|
||||||
|
becomes ``"LINKER:SHELL:-z defs"``.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Specifying ``SHELL:`` prefix elsewhere 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
|
||||||
|
it 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,23 @@
|
|||||||
|
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 for targets in the
|
||||||
|
current directory and below (whether added before or after this command is
|
||||||
|
invoked). See documentation of the :prop_dir:`directory <COMPILE_DEFINITIONS>`
|
||||||
|
and :prop_tgt:`target <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS`` properties.
|
||||||
|
|
||||||
|
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,48 @@
|
|||||||
|
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.
|
@ -0,0 +1,243 @@
|
|||||||
|
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]
|
||||||
|
[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 ``BYPRODUCTS`` option is ignored on non-Ninja generators
|
||||||
|
except to mark byproducts ``GENERATED``.
|
||||||
|
|
||||||
|
``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 set, the
|
||||||
|
:prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will
|
||||||
|
also be prepended to the command to allow the executable to run on
|
||||||
|
the host.
|
||||||
|
(Use the ``TARGET_FILE``
|
||||||
|
:manual:`generator expression <cmake-generator-expressions(7)>` to
|
||||||
|
reference an executable later in the command line.)
|
||||||
|
Additionally a target-level dependency will be added so that the
|
||||||
|
executable 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.
|
||||||
|
|
||||||
|
Arguments to ``COMMAND`` may use
|
||||||
|
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||||
|
References to target names in generator expressions imply target-level
|
||||||
|
dependencies, but NOT file-level dependencies. List target names with
|
||||||
|
the ``DEPENDS`` option to add file-level dependencies.
|
||||||
|
|
||||||
|
``COMMENT``
|
||||||
|
Display the given message before the commands are executed at
|
||||||
|
build time.
|
||||||
|
|
||||||
|
``DEPENDS``
|
||||||
|
Specify files on which the command depends. 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.
|
||||||
|
If ``DEPENDS`` is not specified the command will run whenever
|
||||||
|
the ``OUTPUT`` is missing; if the command does not actually
|
||||||
|
create the ``OUTPUT`` then the rule will always run.
|
||||||
|
If ``DEPENDS`` specifies any 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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
``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])
|
||||||
|
|
||||||
|
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,126 @@
|
|||||||
|
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]
|
||||||
|
[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 ``BYPRODUCTS`` option is ignored on non-Ninja generators
|
||||||
|
except to mark byproducts ``GENERATED``.
|
||||||
|
|
||||||
|
``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 set, the
|
||||||
|
:prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will
|
||||||
|
also be prepended to the command to allow the executable to run on
|
||||||
|
the host.
|
||||||
|
Additionally a target-level dependency will be added so that the
|
||||||
|
executable target will be built before this custom target.
|
||||||
|
|
||||||
|
Arguments to ``COMMAND`` may use
|
||||||
|
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||||
|
References to target names in generator expressions imply target-level
|
||||||
|
dependencies.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
``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 and below (whether added before or after this command is invoked).
|
||||||
|
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,85 @@
|
|||||||
|
add_executable
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Add an executable to the project using the specified source files.
|
||||||
|
|
||||||
|
.. 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.
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------
|
||||||
|
|
||||||
|
.. 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.
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------
|
||||||
|
|
||||||
|
.. 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 a non-``GLOBAL``
|
||||||
|
:ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
|
||||||
|
``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.
|
171
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/add_library.rst
Normal file
171
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/add_library.rst
Normal file
@ -0,0 +1,171 @@
|
|||||||
|
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 such
|
||||||
|
property is :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. Or, for object libraries,
|
||||||
|
:prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`)
|
||||||
|
specifies the locations of object files on disk.
|
||||||
|
See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
|
||||||
|
for more information.
|
||||||
|
|
||||||
|
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 a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>` or an
|
||||||
|
``ALIAS``.
|
||||||
|
``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,26 @@
|
|||||||
|
add_link_options
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Add options to the link of shared library, module and executable targets.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
add_link_options(<option> ...)
|
||||||
|
|
||||||
|
Adds options to the link step for targets in the current directory and below
|
||||||
|
that are added after this command is invoked. See documentation of the
|
||||||
|
:prop_dir:`directory <LINK_OPTIONS>` and
|
||||||
|
:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties.
|
||||||
|
|
||||||
|
This command can be used to add any options, but alternative commands
|
||||||
|
exist to add libraries (:command:`target_link_libraries` or
|
||||||
|
:command:`link_libraries`).
|
||||||
|
|
||||||
|
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:: 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,68 @@
|
|||||||
|
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>])
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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` or
|
||||||
|
:prop_test:`FAIL_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 when the ``BUILD_TESTING`` option is ``ON``.
|
||||||
|
|
||||||
|
---------------------------------------------------------------------
|
||||||
|
|
||||||
|
.. 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.
|
12
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/break.rst
Normal file
12
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/break.rst
Normal 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,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,101 @@
|
|||||||
|
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 argument
|
||||||
|
where recognized. This can be checked afterwards to see
|
||||||
|
whether your macro was called with unrecognized parameters.
|
||||||
|
|
||||||
|
As an example here a ``my_install()`` macro, which takes similar arguments
|
||||||
|
as 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)
|
||||||
|
|
||||||
|
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"
|
||||||
|
|
||||||
|
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 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,82 @@
|
|||||||
|
ctest_start
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Starts the testing for a given model
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET])
|
||||||
|
|
||||||
|
ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] 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.
|
||||||
|
|
||||||
|
``TRACK <track>``
|
||||||
|
If ``TRACK`` is used, the submissions will go to the specified track on the
|
||||||
|
CDash server. If no ``TRACK`` is specified, the name of the model is used by
|
||||||
|
default.
|
||||||
|
|
||||||
|
``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 ``TRACK <track>`` parameters, because they will be read from
|
||||||
|
the generated ``TAG`` file. For example:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
ctest_start(Experimental TRACK TrackExperimental)
|
||||||
|
|
||||||
|
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 ``TrackExperimental`` track 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 track than
|
||||||
|
in the first ``ctest_start()`` command, a warning will be issued, and the
|
||||||
|
new model and track 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 TRACK SomeTrack QUIET APPEND)
|
||||||
|
|
||||||
|
ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary)
|
||||||
|
|
||||||
|
ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack 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,90 @@
|
|||||||
|
ctest_submit
|
||||||
|
------------
|
||||||
|
|
||||||
|
Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
ctest_submit([PARTS <part>...] [FILES <file>...]
|
||||||
|
[SUBMIT_URL <url>]
|
||||||
|
[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.
|
||||||
|
|
||||||
|
``HTTPHEADER <HTTP-header>``
|
||||||
|
Specify HTTP header to be included in the request to CDash during submission.
|
||||||
|
This suboption can be repeated several times.
|
||||||
|
|
||||||
|
``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``, ``HTTPHEADER``, ``RETRY_COUNT``,
|
||||||
|
``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options as described above.
|
114
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/ctest_test.rst
Normal file
114
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/ctest_test.rst
Normal file
@ -0,0 +1,114 @@
|
|||||||
|
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>]
|
||||||
|
[TEST_LOAD <threshold>]
|
||||||
|
[SCHEDULE_RANDOM <ON|OFF>]
|
||||||
|
[STOP_TIME <time-of-day>]
|
||||||
|
[RETURN_VALUE <result-var>]
|
||||||
|
[CAPTURE_CMAKE_ERROR <result-var>]
|
||||||
|
[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.
|
||||||
|
|
||||||
|
``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`.
|
||||||
|
|
||||||
|
``SCHEDULE_RANDOM <ON|OFF>``
|
||||||
|
Launch tests in a random order. This may be useful for detecting
|
||||||
|
implicit test dependencies.
|
||||||
|
|
||||||
|
``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,38 @@
|
|||||||
|
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 more information.
|
@ -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.
|
10
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/else.rst
Normal file
10
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/else.rst
Normal file
@ -0,0 +1,10 @@
|
|||||||
|
else
|
||||||
|
----
|
||||||
|
|
||||||
|
Starts the else portion of an if block.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
else([<condition>])
|
||||||
|
|
||||||
|
See the :command:`if` command.
|
11
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/elseif.rst
Normal file
11
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/elseif.rst
Normal file
@ -0,0 +1,11 @@
|
|||||||
|
elseif
|
||||||
|
------
|
||||||
|
|
||||||
|
Starts an elseif portion of an if block.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
elseif(<condition>)
|
||||||
|
|
||||||
|
See the :command:`if` command, especially for the syntax and logic
|
||||||
|
of the ``<condition>``.
|
@ -0,0 +1,26 @@
|
|||||||
|
enable_language
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Enable a language (CXX/C/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``, ``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,13 @@
|
|||||||
|
enable_testing
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Enable testing for current directory and below.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
enable_testing()
|
||||||
|
|
||||||
|
Enables testing for this directory and below. See also the
|
||||||
|
:command:`add_test` command. Note that ctest expects to find a test file
|
||||||
|
in the build directory root. Therefore, this command should be in the
|
||||||
|
source directory root.
|
@ -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.
|
14
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/endif.rst
Normal file
14
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/endif.rst
Normal file
@ -0,0 +1,14 @@
|
|||||||
|
endif
|
||||||
|
-----
|
||||||
|
|
||||||
|
Ends a list of commands in an if block.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
endif([<condition>])
|
||||||
|
|
||||||
|
See the :command:`if` command.
|
||||||
|
|
||||||
|
The optional ``<condition>`` argument is supported for backward compatibility
|
||||||
|
only. If used it must be a verbatim repeat of the argument of the opening
|
||||||
|
``if`` clause.
|
@ -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,108 @@
|
|||||||
|
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]
|
||||||
|
[OUTPUT_STRIP_TRAILING_WHITESPACE]
|
||||||
|
[ERROR_STRIP_TRAILING_WHITESPACE]
|
||||||
|
[ENCODING <name>])
|
||||||
|
|
||||||
|
Runs the given sequence of one or more commands in parallel 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``
|
||||||
|
The child processes will be terminated if they do not finish in the
|
||||||
|
specified number of seconds (fractions are allowed).
|
||||||
|
|
||||||
|
``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.
|
||||||
|
|
||||||
|
``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.
|
||||||
|
|
||||||
|
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.
|
81
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/export.rst
Normal file
81
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/export.rst
Normal file
@ -0,0 +1,81 @@
|
|||||||
|
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 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. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable
|
||||||
|
is enabled, the ``export(PACKAGE)`` command will do nothing.
|
||||||
|
|
||||||
|
.. 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.
|
547
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/file.rst
Normal file
547
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/file.rst
Normal file
@ -0,0 +1,547 @@
|
|||||||
|
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> [...])
|
||||||
|
|
||||||
|
`Writing`_
|
||||||
|
file({`WRITE`_ | `APPEND`_} <filename> <content>...)
|
||||||
|
file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
|
||||||
|
file(`GENERATE`_ OUTPUT <output-file> [...])
|
||||||
|
|
||||||
|
`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> [...])
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
.. _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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
``OLD`` 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.
|
||||||
|
|
||||||
|
.. _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]
|
||||||
|
[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``).
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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>``.
|
||||||
|
|
||||||
|
``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 and/or use ``EXPECTED_HASH`` to verify downloaded content.
|
||||||
|
If neither ``TLS`` option is given CMake will check variables
|
||||||
|
``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
|
||||||
|
|
||||||
|
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.
|
@ -0,0 +1,37 @@
|
|||||||
|
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:: Directories in ``INCLUDE``.
|
||||||
|
On Windows hosts:
|
||||||
|
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
|
||||||
|
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the
|
||||||
|
directories in ``PATH`` itself.
|
||||||
|
|
||||||
|
.. |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,82 @@
|
|||||||
|
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:: Directories in ``LIB``.
|
||||||
|
On Windows hosts:
|
||||||
|
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
|
||||||
|
and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
|
||||||
|
and the directories in ``PATH`` itself.
|
||||||
|
|
||||||
|
.. |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,405 @@
|
|||||||
|
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.
|
||||||
|
|
||||||
|
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...]]
|
||||||
|
[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 Frameworks and Application Bundles the
|
||||||
|
following directories are searched for frameworks or 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.
|
||||||
|
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::
|
||||||
|
|
||||||
|
CMAKE_PREFIX_PATH
|
||||||
|
CMAKE_FRAMEWORK_PATH
|
||||||
|
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::
|
||||||
|
|
||||||
|
<PackageName>_DIR
|
||||||
|
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. 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:`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::
|
||||||
|
|
||||||
|
CMAKE_SYSTEM_PREFIX_PATH
|
||||||
|
CMAKE_SYSTEM_FRAMEWORK_PATH
|
||||||
|
CMAKE_SYSTEM_APPBUNDLE_PATH
|
||||||
|
|
||||||
|
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_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,42 @@
|
|||||||
|
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:: Directories in ``INCLUDE``.
|
||||||
|
On Windows hosts:
|
||||||
|
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
|
||||||
|
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the
|
||||||
|
directories in ``PATH`` itself.
|
||||||
|
|
||||||
|
.. |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,35 @@
|
|||||||
|
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:: ``PATH``
|
||||||
|
|
||||||
|
.. |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.
|
84
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/foreach.rst
Normal file
84
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/foreach.rst
Normal file
@ -0,0 +1,84 @@
|
|||||||
|
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
|
@ -0,0 +1,70 @@
|
|||||||
|
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()
|
||||||
|
|
||||||
|
and so on. However, it is strongly recommended to stay with the
|
||||||
|
case chosen in the function definition. Typically functions use
|
||||||
|
all-lowercase names.
|
||||||
|
|
||||||
|
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,66 @@
|
|||||||
|
get_property
|
||||||
|
------------
|
||||||
|
|
||||||
|
Get a property.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
get_property(<variable>
|
||||||
|
<GLOBAL |
|
||||||
|
DIRECTORY [<dir>] |
|
||||||
|
TARGET <target> |
|
||||||
|
SOURCE <source> |
|
||||||
|
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>``.
|
||||||
|
|
||||||
|
``TARGET``
|
||||||
|
Scope must name one existing target.
|
||||||
|
|
||||||
|
``SOURCE``
|
||||||
|
Scope must name one source file.
|
||||||
|
|
||||||
|
``INSTALL``
|
||||||
|
Scope must name one installed file path.
|
||||||
|
|
||||||
|
``TEST``
|
||||||
|
Scope must name one existing test.
|
||||||
|
|
||||||
|
``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,22 @@
|
|||||||
|
get_source_file_property
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Get a property for a source file.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
get_source_file_property(VAR file property)
|
||||||
|
|
||||||
|
Gets a property from a source file. The value of the property is
|
||||||
|
stored in the variable ``VAR``. 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
|
||||||
|
``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.
|
||||||
|
|
||||||
|
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 "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.
|
276
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/if.rst
Normal file
276
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/if.rst
Normal file
@ -0,0 +1,276 @@
|
|||||||
|
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
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
``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>``.
|
25
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/include.rst
Normal file
25
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/include.rst
Normal file
@ -0,0 +1,25 @@
|
|||||||
|
include
|
||||||
|
-------
|
||||||
|
|
||||||
|
Load and run CMake code from a file or module.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
|
||||||
|
[NO_POLICY_SCOPE])
|
||||||
|
|
||||||
|
Loads and runs CMake code from the file given. Variable reads and
|
||||||
|
writes access the scope of the caller (dynamic scoping). If ``OPTIONAL``
|
||||||
|
is present, then no error is raised if the file does not exist. If
|
||||||
|
``RESULT_VARIABLE`` is given the variable ``<var>`` will be set to the
|
||||||
|
full filename which has been included or ``NOTFOUND`` if it failed.
|
||||||
|
|
||||||
|
If a module is specified instead of a file, the file with name
|
||||||
|
``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`,
|
||||||
|
then in the CMake module directory. There is one exception to this: if
|
||||||
|
the file which calls ``include()`` is located itself in the CMake builtin
|
||||||
|
module directory, then first the CMake builtin module directory is searched and
|
||||||
|
:variable:`CMAKE_MODULE_PATH` afterwards. See also policy :policy:`CMP0017`.
|
||||||
|
|
||||||
|
See the :command:`cmake_policy` command documentation for discussion of the
|
||||||
|
``NO_POLICY_SCOPE`` option.
|
@ -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)
|
694
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/install.rst
Normal file
694
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/install.rst
Normal file
@ -0,0 +1,694 @@
|
|||||||
|
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. Rules
|
||||||
|
specified by calls to this command within a source directory are
|
||||||
|
executed in order during installation. The order across directories
|
||||||
|
is not defined.
|
||||||
|
|
||||||
|
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.
|
||||||
|
If a full path (with a leading slash or drive letter) is given
|
||||||
|
it is used directly. 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.
|
||||||
|
|
||||||
|
``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
|
||||||
|
^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
.. _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 files that may be installed:
|
||||||
|
|
||||||
|
``ARCHIVE``
|
||||||
|
Static libraries are treated as ``ARCHIVE`` targets, except those
|
||||||
|
marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK``
|
||||||
|
below.) For DLL platforms (all Windows-based systems including
|
||||||
|
Cygwin), the DLL import library is treated as an ``ARCHIVE`` target.
|
||||||
|
|
||||||
|
``LIBRARY``
|
||||||
|
Module libraries are always treated as ``LIBRARY`` targets. For non-
|
||||||
|
DLL platforms shared libraries are treated as ``LIBRARY`` targets,
|
||||||
|
except those marked with the ``FRAMEWORK`` property on macOS (see
|
||||||
|
``FRAMEWORK`` below.)
|
||||||
|
|
||||||
|
``RUNTIME``
|
||||||
|
Executables are treated as ``RUNTIME`` objects, except those marked
|
||||||
|
with the ``MACOSX_BUNDLE`` property on macOS (see ``BUNDLE`` below.)
|
||||||
|
For DLL platforms (all Windows-based systems including Cygwin), the
|
||||||
|
DLL part of a shared library is treated as a ``RUNTIME`` target.
|
||||||
|
|
||||||
|
``OBJECTS``
|
||||||
|
Object libraries (a simple group of object files) are always treated
|
||||||
|
as ``OBJECTS`` targets.
|
||||||
|
|
||||||
|
``FRAMEWORK``
|
||||||
|
Both static and shared libraries marked with the ``FRAMEWORK``
|
||||||
|
property are treated as ``FRAMEWORK`` targets on macOS.
|
||||||
|
|
||||||
|
``BUNDLE``
|
||||||
|
Executables marked with the ``MACOSX_BUNDLE`` property are treated as
|
||||||
|
``BUNDLE`` targets on macOS.
|
||||||
|
|
||||||
|
``PUBLIC_HEADER``
|
||||||
|
Any ``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 ``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.
|
||||||
|
|
||||||
|
``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 :command:`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.
|
||||||
|
|
||||||
|
:command:`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
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
.. _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
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
.. _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
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
.. _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
|
||||||
|
^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
.. _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``.
|
||||||
|
|
||||||
|
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 myexp 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
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
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.
|
295
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/list.rst
Normal file
295
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/list.rst
Normal file
@ -0,0 +1,295 @@
|
|||||||
|
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(`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``, ``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.
|
||||||
|
|
||||||
|
.. _REMOVE_ITEM:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
list(REMOVE_ITEM <list> <value> [<value> ...])
|
||||||
|
|
||||||
|
Removes 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.
|
||||||
|
|
||||||
|
.. _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 result in-place
|
||||||
|
or in the specified output variable.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
``TRANSFORM`` sub-command does not change the number of elements of the
|
||||||
|
list. If a ``<SELECTOR>`` is specified, only some elements will be changed,
|
||||||
|
the other ones will remain same as before the transformation.
|
||||||
|
|
||||||
|
``<ACTION>`` specify the action to apply to the elements of list.
|
||||||
|
The actions have exactly the same semantics as sub-commands of
|
||||||
|
:command:`string` command.
|
||||||
|
|
||||||
|
The ``<ACTION>`` may be one of:
|
||||||
|
|
||||||
|
``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>`` select which elements of the list will be transformed. Only one
|
||||||
|
type of selector can be specified at a time.
|
||||||
|
|
||||||
|
The ``<SELECTOR>`` may be one of:
|
||||||
|
|
||||||
|
``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.
|
||||||
|
|
||||||
|
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(pathToCacheFile 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(pathToCacheFile [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.
|
140
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/macro.rst
Normal file
140
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/macro.rst
Normal file
@ -0,0 +1,140 @@
|
|||||||
|
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()
|
||||||
|
|
||||||
|
and so on. However, it is strongly recommended to stay with the
|
||||||
|
case chosen in the macro definition. Typically macros use
|
||||||
|
all-lowercase names.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. _`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,24 @@
|
|||||||
|
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.
|
36
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/math.rst
Normal file
36
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/math.rst
Normal file
@ -0,0 +1,36 @@
|
|||||||
|
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 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"
|
33
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/message.rst
Normal file
33
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/message.rst
Normal file
@ -0,0 +1,33 @@
|
|||||||
|
message
|
||||||
|
-------
|
||||||
|
|
||||||
|
Display a message to the user.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
message([<mode>] "message to display" ...)
|
||||||
|
|
||||||
|
The optional ``<mode>`` keyword determines the type of message:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
(none) = Important information
|
||||||
|
STATUS = Incidental information
|
||||||
|
WARNING = CMake Warning, continue processing
|
||||||
|
AUTHOR_WARNING = CMake Warning (dev), continue processing
|
||||||
|
SEND_ERROR = CMake Error, continue processing,
|
||||||
|
but skip generation
|
||||||
|
FATAL_ERROR = CMake Error, stop processing and generation
|
||||||
|
DEPRECATION = CMake Deprecation Error or Warning if variable
|
||||||
|
CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED
|
||||||
|
is enabled, respectively, else no message.
|
||||||
|
|
||||||
|
The CMake command-line tool displays STATUS messages on stdout and all
|
||||||
|
other message types on stderr. The CMake GUI displays all messages in
|
||||||
|
its log area. The interactive dialogs (ccmake and CMakeSetup) show
|
||||||
|
STATUS messages one at a time on a status line and other messages in
|
||||||
|
interactive pop-up boxes.
|
||||||
|
|
||||||
|
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.
|
16
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/option.rst
Normal file
16
6.5.1/_tools/cmake/share/cmake-3.14/Help/command/option.rst
Normal file
@ -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 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.
|
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user