mirror of
https://github.com/crystalidea/qt-build-tools.git
synced 2024-11-25 20:27:35 +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