Update upstream source from tag 'upstream/3.12.1'

Update to upstream version '3.12.1'
with Debian dir 36d3327735
ci/unstable
Felix Geyer 6 years ago
commit 31dfd4f103

@ -1,8 +1,21 @@
---
# This configuration requires clang-format 3.8 or higher.
# This configuration requires clang-format version 6.0 exactly.
BasedOnStyle: Mozilla
AlignOperands: false
AlwaysBreakAfterReturnType: None
AllowShortFunctionsOnASingleLine: InlineOnly
AlwaysBreakAfterDefinitionReturnType: None
AlwaysBreakAfterReturnType: None
BinPackArguments: true
BinPackParameters: true
BraceWrapping:
AfterClass: true
AfterEnum: true
AfterFunction: true
AfterStruct: true
AfterUnion: true
BreakBeforeBraces: Custom
ColumnLimit: 79
IndentPPDirectives: AfterHash
SortUsingDeclarations: false
SpaceAfterTemplateKeyword: true
...

@ -285,7 +285,7 @@ if(CMake_RUN_IWYU)
message(FATAL_ERROR "CMake_RUN_IWYU is ON but include-what-you-use is not found!")
endif()
set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE
"${IWYU_COMMAND};-Xiwyu;--mapping_file=${CMake_SOURCE_DIR}/Utilities/IWYU/mapping.imp;-w")
"${IWYU_COMMAND};-Xiwyu;--mapping_file=${CMake_SOURCE_DIR}/Utilities/IWYU/mapping.imp;-w;-DCMAKE_IWYU")
endif()
@ -573,22 +573,24 @@ macro (CMAKE_BUILD_UTILITIES)
#---------------------------------------------------------------------
# Use curses?
if (UNIX)
# there is a bug in the Syllable libraries which makes linking ccmake fail, Alex
if(NOT CMAKE_SYSTEM_NAME MATCHES syllable)
set(CURSES_NEED_NCURSES TRUE)
find_package(Curses QUIET)
if (CURSES_LIBRARY)
option(BUILD_CursesDialog "Build the CMake Curses Dialog ccmake" ON)
if(NOT DEFINED BUILD_CursesDialog)
include(${CMake_SOURCE_DIR}/Source/Checks/Curses.cmake)
option(BUILD_CursesDialog "Build the CMake Curses Dialog ccmake" "${CMakeCheckCurses_COMPILED}")
endif()
else ()
message("Curses libraries were not found. Curses GUI for CMake will not be built.")
set(BUILD_CursesDialog 0)
endif ()
else()
if(BUILD_CursesDialog)
set(CURSES_NEED_NCURSES TRUE)
find_package(Curses)
if(NOT CURSES_FOUND)
message(WARNING
"'ccmake' will not be built because Curses was not found.\n"
"Turn off BUILD_CursesDialog to suppress this message."
)
set(BUILD_CursesDialog 0)
endif()
else ()
set(BUILD_CursesDialog 0)
endif ()
endif()
if(BUILD_CursesDialog)
if(NOT CMAKE_USE_SYSTEM_FORM)
add_subdirectory(Source/CursesDialog/form)

@ -29,11 +29,14 @@ To contribute patches:
#. Base all new work on the upstream ``master`` branch.
Base work on the upstream ``release`` branch only if it fixes a
regression or bug in a feature new to that release.
If in doubt, prefer ``master``. Reviewers may simply ask for
a rebase if deemed appropriate in particular cases.
#. Create commits making incremental, distinct, logically complete changes
with appropriate `commit messages`_.
#. Push a topic branch to a personal repository fork on GitLab.
#. Create a GitLab Merge Request targeting the upstream ``master`` branch
(even if the change is intended for merge to the ``release`` branch).
Check the box to allow edits from maintainers.
The merge request will enter the `CMake Review Process`_ for consideration.

@ -82,3 +82,26 @@ endif ()
if (CMAKE_ANSI_CFLAGS)
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${CMAKE_ANSI_CFLAGS}")
endif ()
# Allow per-translation-unit parallel builds when using MSVC
if(CMAKE_GENERATOR MATCHES "Visual Studio" AND
(CMAKE_C_COMPILER_ID MATCHES "MSVC|Intel" OR
CMAKE_CXX_COMPILER_ID MATCHES "MSVC|Intel"))
set(CMake_MSVC_PARALLEL ON CACHE STRING "\
Enables /MP flag for parallel builds using MSVC. Specify an \
integer value to control the number of threads used (Only \
works on some older versions of Visual Studio). Setting to \
ON lets the toolchain decide how many threads to use. Set to \
OFF to disable /MP completely." )
if(CMake_MSVC_PARALLEL)
if(CMake_MSVC_PARALLEL GREATER 0)
string(APPEND CMAKE_C_FLAGS " /MP${CMake_MSVC_PARALLEL}")
string(APPEND CMAKE_CXX_FLAGS " /MP${CMake_MSVC_PARALLEL}")
else()
string(APPEND CMAKE_C_FLAGS " /MP")
string(APPEND CMAKE_CXX_FLAGS " /MP")
endif()
endif()
endif()

@ -78,6 +78,7 @@ The following individuals and institutions are among the Contributors:
* Nikita Krupen'ko <krnekit@gmail.com>
* NVIDIA Corporation <www.nvidia.com>
* OpenGamma Ltd. <opengamma.com>
* Patrick Stotko <stotko@cs.uni-bonn.de>
* Per Øyvind Karlsen <peroyvind@mandriva.org>
* Peter Collingbourne <peter@pcc.me.uk>
* Petr Gotthard <gotthard@honeywell.com>

@ -0,0 +1,9 @@
The final set of compile 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``.

@ -16,6 +16,7 @@ The general signature is:
[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]
@ -60,6 +61,13 @@ 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`
@ -71,7 +79,22 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
|prefix_XXX_SUBDIR| for each ``<prefix>`` in
:variable:`CMAKE_SYSTEM_PREFIX_PATH`
1. Search paths specified in cmake-specific cache variables.
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:`;-lists <CMake Language Lists>`.
This can be skipped if ``NO_CMAKE_PATH`` is passed.
@ -80,7 +103,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
* |CMAKE_XXX_PATH|
* |CMAKE_XXX_MAC_PATH|
2. Search paths specified in cmake-specific environment variables.
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).
@ -90,17 +113,17 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
* |CMAKE_XXX_PATH|
* |CMAKE_XXX_MAC_PATH|
3. Search the paths specified by the ``HINTS`` option.
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.
4. Search the standard system environment variables.
5. Search the standard system environment variables.
This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument.
* |SYSTEM_ENVIRONMENT_PATH_XXX|
5. Search cmake variables defined in the Platform files
6. Search cmake variables defined in the Platform files
for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
is passed.
@ -108,7 +131,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
* |CMAKE_SYSTEM_XXX_PATH|
* |CMAKE_SYSTEM_XXX_MAC_PATH|
6. Search the paths specified by the PATHS option
7. Search the paths specified by the PATHS option
or in the short-hand version of the command.
These are typically hard-coded guesses.

@ -0,0 +1,23 @@
add_compile_definitions
-----------------------
Adds preprocessor definitions to the compilation of source files.
::
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.

@ -14,10 +14,12 @@ See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and
This command can be used to add any options, but alternative commands
exist to add preprocessor definitions (:command:`target_compile_definitions`
and :command:`add_definitions`) or include directories
and :command:`add_compile_definitions`) or include directories
(:command:`target_include_directories` and :command:`include_directories`).
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:: COMPILE_OPTIONS_SHELL.txt

@ -216,10 +216,9 @@ When the command will happen is determined by which
of the following is specified:
``PRE_BUILD``
Run before any other rules are executed within the target.
This is supported only on Visual Studio 8 or later.
For all other generators ``PRE_BUILD`` will be treated as
``PRE_LINK``.
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.

@ -10,8 +10,16 @@ Adds -D define flags to the compilation of source files.
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 (see the :command:`add_compile_options` command
to add other flags).
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

@ -83,8 +83,11 @@ 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. See documentation of the
``IMPORTED_*`` and ``INTERFACE_*`` properties for more information.
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
^^^^^^^^^^^^^^^^
@ -110,10 +113,10 @@ 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. Object libraries
cannot be linked. 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>``.
``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
^^^^^^^^^^^^^^^

@ -27,13 +27,13 @@ Key Description
``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 porcessor supports Ext. MMX instructions
``HAS_SSE`` One if porcessor supports SSE instructions
``HAS_SSE2`` One if porcessor supports SSE2 instructions
``HAS_SSE_FP`` One if porcessor supports SSE FP instructions
``HAS_SSE_MMX`` One if porcessor supports SSE MMX instructions
``HAS_AMD_3DNOW`` One if porcessor supports 3DNow instructions
``HAS_AMD_3DNOW_PLUS`` One if porcessor supports 3DNow+ 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

@ -4,11 +4,19 @@ cmake_minimum_required
Set the minimum required version of cmake for a project and
update `Policy Settings`_ to match the version given::
cmake_minimum_required(VERSION major.minor[.patch[.tweak]]
[FATAL_ERROR])
cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
If the current version of CMake is lower than that required it will
stop processing the project and report an error.
``<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
@ -30,21 +38,23 @@ 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 version of CMake.
All policies introduced in the specified version or earlier will be
set to use NEW behavior. All policies introduced after the specified
version will be unset. This effectively requests behavior preferred
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 version higher than 2.4 is specified the command implicitly
invokes::
When a ``<min>`` version higher than 2.4 is specified the command
implicitly invokes::
cmake_policy(VERSION major[.minor[.patch[.tweak]]])
cmake_policy(VERSION <min>[...<max>])
which sets the cmake policy version level to the version specified.
When version 2.4 or lower is given the command implicitly invokes::
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::
cmake_policy(VERSION 2.4)
cmake_policy(VERSION 2.4[...<max>])
which enables compatibility features for CMake 2.4 and lower.

@ -24,17 +24,25 @@ 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::
cmake_policy(VERSION major.minor[.patch[.tweak]])
Specify that the current CMake code is written for the given
version of CMake. All policies introduced in the specified version or
earlier will be set to use ``NEW`` behavior. All policies introduced
after the specified version will be unset (unless the
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.
The policy version specified must be at least 2.4 or the command will
report an error.
Note that the :command:`cmake_minimum_required(VERSION)`
command implicitly calls ``cmake_policy(VERSION)`` too.

@ -5,21 +5,78 @@ Starts the testing for a given model
::
ctest_start(Model [TRACK <track>] [APPEND] [source [binary]] [QUIET])
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. If the 'source' and
'binary' directory are not specified, it reads the
:variable:`CTEST_SOURCE_DIRECTORY` and :variable:`CTEST_BINARY_DIRECTORY`.
If the track is
specified, the submissions will go to the specified track. If APPEND
is used, the existing TAG is used rather than creating a new one based
on the current time stamp. If ``QUIET`` is used, CTest will suppress any
non-error messages that it otherwise would have printed to the console.
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.
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.

@ -68,7 +68,7 @@ Submit to CDash Upload API
[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
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.

@ -34,10 +34,24 @@ 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 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
``GLOBAL``. ``TARGET``, ``SOURCE``, and ``TEST`` chain to ``DIRECTORY``.
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.

@ -40,6 +40,15 @@ 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.
::
export(PACKAGE <name>)

@ -3,23 +3,44 @@ file
File manipulation command.
------------------------------------------------------------------------------
Synopsis
^^^^^^^^
::
.. parsed-literal::
file(WRITE <filename> <content>...)
file(APPEND <filename> <content>...)
`Reading`_
file(`READ`_ <filename> <out-var> [...])
file(`STRINGS`_ <filename> <out-var> [...])
file(`\<HASH\> <HASH_>`_ <filename> <out-var>)
file(`TIMESTAMP`_ <filename> <out-var> [...])
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.
`Writing`_
file({`WRITE`_ | `APPEND`_} <filename> <content>...)
file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
file(`GENERATE`_ OUTPUT <output-file> [...])
If the file is a build input, use the :command:`configure_file` command
to update the file only when its content changes.
`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> [...])
`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:
::
@ -31,7 +52,7 @@ Read content from a file called ``<filename>`` and store it in a
read at most ``<max-in>`` bytes. The ``HEX`` option causes data to
be converted to a hexadecimal representation (useful for binary data).
------------------------------------------------------------------------------
.. _STRINGS:
::
@ -82,7 +103,7 @@ For example, the code
stores a list in the variable ``myfile`` in which each item is a line
from the input file.
------------------------------------------------------------------------------
.. _HASH:
::
@ -93,15 +114,116 @@ store it in a ``<variable>``. The supported ``<HASH>`` algorithm names
are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
command.
------------------------------------------------------------------------------
.. _TIMESTAMP:
::
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:
::
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:
::
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:
::
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:
::
file(GLOB <variable>
[LIST_DIRECTORIES true|false] [RELATIVE <path>]
[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
[<globbing-expressions>...])
file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
[LIST_DIRECTORIES true|false] [RELATIVE <path>]
[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
[<globbing-expressions>...])
Generate a list of files that match the ``<globbing-expressions>`` and
@ -110,6 +232,11 @@ 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.
@ -118,6 +245,10 @@ By default ``GLOB`` lists directories - directories are omitted in result if
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::
@ -139,7 +270,7 @@ Examples of recursive globbing include::
/dir/*.py - match all python files in /dir and subdirectories
------------------------------------------------------------------------------
.. _RENAME:
::
@ -148,7 +279,8 @@ Examples of recursive globbing include::
Move a file or directory within a filesystem from ``<oldname>`` to
``<newname>``, replacing the destination atomically.
------------------------------------------------------------------------------
.. _REMOVE:
.. _REMOVE_RECURSE:
::
@ -159,7 +291,7 @@ 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:
::
@ -167,7 +299,44 @@ given file does not exist.
Create the given directories and their parents as needed.
------------------------------------------------------------------------------
.. _COPY:
.. _INSTALL:
::
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).
Path Conversion
^^^^^^^^^^^^^^^
.. _RELATIVE_PATH:
::
@ -176,7 +345,8 @@ Create the given directories and their parents as needed.
Compute the relative path from a ``<directory>`` to a ``<file>`` and
store it in the ``<variable>``.
------------------------------------------------------------------------------
.. _TO_CMAKE_PATH:
.. _TO_NATIVE_PATH:
::
@ -194,7 +364,11 @@ 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:
::
@ -281,99 +455,10 @@ 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.
------------------------------------------------------------------------------
::
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.
------------------------------------------------------------------------------
::
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.
------------------------------------------------------------------------------
::
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).
Locking
^^^^^^^
------------------------------------------------------------------------------
.. _LOCK:
::

@ -8,6 +8,9 @@ find_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|

@ -8,6 +8,9 @@ find_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|

@ -64,6 +64,7 @@ The complete Config mode command signature is::
[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]
@ -208,12 +209,12 @@ Each entry is meant for installation trees following Windows (W), UNIX
<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)
<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 OS X Frameworks and Application Bundles the
following directories are searched for frameworks or bundles
@ -228,10 +229,22 @@ containing a configuration file::
In all cases the ``<name>`` is treated as case-insensitive and corresponds
to any of the names specified (``<package>`` or names given by ``NAMES``).
Paths with ``lib/<arch>`` are enabled if the
:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. If ``PATH_SUFFIXES``
is specified the suffixes are appended to each (W) or (U) directory entry
one-by-one.
: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.
@ -249,7 +262,16 @@ 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 cmake-specific cache variables. These
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:`;-lists <CMake Language Lists>`.
This can be skipped if ``NO_CMAKE_PATH`` is passed::
@ -258,7 +280,7 @@ enabled.
CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH
2. Search paths specified in cmake-specific environment variables.
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).
@ -269,26 +291,26 @@ enabled.
CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH
3. Search paths specified by the ``HINTS`` option. These should be paths
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.
4. Search the standard system environment variables. This can be
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
5. Search paths stored in the CMake :ref:`User Package Registry`.
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.
6. Search cmake variables defined in the Platform files for the
7. Search cmake variables defined in the Platform files for the
current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
passed::
@ -296,14 +318,14 @@ enabled.
CMAKE_SYSTEM_FRAMEWORK_PATH
CMAKE_SYSTEM_APPBUNDLE_PATH
7. Search paths stored in the CMake :ref:`System Package Registry`.
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.
8. Search paths specified by the ``PATHS`` option. These are typically
9. Search paths specified by the ``PATHS`` option. These are typically
hard-coded guesses.
.. |FIND_XXX| replace:: find_package

@ -8,6 +8,9 @@ find_path
.. |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|

@ -8,6 +8,8 @@ find_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`

@ -7,11 +7,16 @@ Get a property of ``DIRECTORY`` scope.
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Store a property of directory scope in the named variable. If the
property is not defined the empty-string is returned. The ``DIRECTORY``
argument specifies another directory from which to retrieve the
property value. The specified directory must have already been
traversed by CMake.
Store 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.
::

@ -45,7 +45,7 @@ to the given base directory ``<BASE_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 slahes. If the
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.

@ -50,7 +50,10 @@ be one of the following:
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. If the ``SET`` option is given the variable is set to a boolean
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

@ -8,9 +8,15 @@ Get a property for a source file.
get_source_file_property(VAR file property)
Get a property from a source file. The value of the property is
stored in the variable ``VAR``. If the property is not found, ``VAR``
will be set to "NOTFOUND". 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`
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.

@ -8,8 +8,15 @@ Get a property from a target.
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 property is not found, ``VAR`` will be set to
"NOTFOUND". Use :command:`set_target_properties` to set property values.
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

@ -8,8 +8,14 @@ Get a property of the test.
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 or property is not found, ``VAR`` will
be set to "NOTFOUND". For a list of standard properties you can type
``cmake --help-property-list``.
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.

@ -1,11 +1,19 @@
install
-------
.. only:: html
Specify rules to run at install time.
.. contents::
Synopsis
^^^^^^^^
Specify rules to run at install time.
.. parsed-literal::
install(`TARGETS`_ <target>... [...])
install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...])
install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...])
install(`SCRIPT`_ <file> [...])
install(`CODE`_ <code> [...])
install(`EXPORT`_ <export-name> DESTINATION <dir> [...])
Introduction
^^^^^^^^^^^^
@ -84,6 +92,8 @@ to control which messages are printed.
Installing Targets
^^^^^^^^^^^^^^^^^^
.. _TARGETS:
::
install(TARGETS targets... [EXPORT <export-name>]
@ -93,6 +103,7 @@ Installing Targets
[PERMISSIONS permissions...]
[CONFIGURATIONS [Debug|Release|...]]
[COMPONENT <component>]
[NAMELINK_COMPONENT <component>]
[OPTIONAL] [EXCLUDE_FROM_ALL]
[NAMELINK_ONLY|NAMELINK_SKIP]
] [...]
@ -100,63 +111,144 @@ Installing Targets
)
The ``TARGETS`` form specifies rules for installing targets from a
project. There are six kinds of target files that may be installed:
``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, ``FRAMEWORK``, and
``BUNDLE``. Executables are treated as ``RUNTIME`` targets, except that
those marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE``
targets on OS X. Static libraries are treated as ``ARCHIVE`` targets,
except that those marked with the ``FRAMEWORK`` property are treated
as ``FRAMEWORK`` targets on OS X.
Module libraries are always treated as ``LIBRARY`` targets.
For non-DLL platforms shared libraries are treated as ``LIBRARY``
targets, except that those marked with the ``FRAMEWORK`` property are
treated as ``FRAMEWORK`` targets on OS X. For DLL platforms the DLL
part of a shared library is treated as a ``RUNTIME`` target and the
corresponding import library is treated as an ``ARCHIVE`` target.
All Windows-based systems including Cygwin are DLL platforms. Object
libraries are always treated as ``OBJECTS`` targets.
The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, and ``FRAMEWORK``
arguments change the type of target to which the subsequent properties
apply. 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).
The ``PRIVATE_HEADER``, ``PUBLIC_HEADER``, and ``RESOURCE`` arguments
cause subsequent properties to be applied to installing a ``FRAMEWORK``
shared library target's associated files on non-Apple platforms. Rules
defined by these arguments are ignored on Apple platforms because the
associated files are installed into the appropriate locations inside
the framework folder. See documentation of the
:prop_tgt:`PRIVATE_HEADER`, :prop_tgt:`PUBLIC_HEADER`, and
:prop_tgt:`RESOURCE` target properties for details.
Either ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` may be specified as a
``LIBRARY`` option. On some platforms a versioned shared library
has a symbolic link such as::
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 OS X (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 OS X (see
``FRAMEWORK`` below.)
``RUNTIME``
Executables are treated as ``RUNTIME`` objects, except those marked
with the ``MACOSX_BUNDLE`` property on OS X (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 OS X.
``BUNDLE``
Executables marked with the ``MACOSX_BUNDLE`` property are treated as
``BUNDLE`` targets on OS X.
``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.)
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_ONLY`` option causes installation of only the
namelink when a library target is installed. The ``NAMELINK_SKIP`` option
causes installation of library files other than the namelink when a
library target is installed. When neither option is given both
portions are installed. On platforms where versioned shared libraries
do not have namelinks or when a library is not versioned the
``NAMELINK_SKIP`` option installs the library and the ``NAMELINK_ONLY``
option installs nothing. See the :prop_tgt:`VERSION` and
:prop_tgt:`SOVERSION` target properties for details on creating versioned
shared libraries.
The ``INCLUDES DESTINATION`` 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>``.
This is independent of the rest of the argument groups and does
not actually install anything.
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
DESTINATION lib
COMPONENT Libraries
NAMELINK_COMPONENT Development
PUBLIC_HEADER
DESTINATION include
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
@ -178,10 +270,12 @@ 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``.
The ``EXPORT`` option associates the installed target files with an
export called ``<export-name>``. It must appear before any ``RUNTIME``,
``LIBRARY``, ``ARCHIVE``, or ``OBJECTS`` options. To actually install the
export file itself, call ``install(EXPORT)``, documented below.
: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.
@ -193,6 +287,9 @@ use "generator expressions" with the syntax ``$<...>``. See the
Installing Files
^^^^^^^^^^^^^^^^
.. _FILES:
.. _PROGRAMS:
::
install(<FILES|PROGRAMS> files... DESTINATION <dir>
@ -226,6 +323,8 @@ use "generator expressions" with the syntax ``$<...>``. See the
Installing Directories
^^^^^^^^^^^^^^^^^^^^^^
.. _DIRECTORY:
::
install(DIRECTORY dirs... DESTINATION <dir>
@ -307,6 +406,9 @@ manual for available expressions.
Custom Installation Logic
^^^^^^^^^^^^^^^^^^^^^^^^^
.. _CODE:
.. _SCRIPT:
::
install([[SCRIPT <file>] [CODE <code>]]
@ -328,16 +430,18 @@ will print a message during installation.
Installing Exports
^^^^^^^^^^^^^^^^^^
.. _EXPORT:
::
install(EXPORT <export-name> DESTINATION <dir>
[NAMESPACE <namespace>] [[FILE <name>.cmake]|
[EXPORT_ANDROID_MK <name>.mk]]
[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.
@ -354,14 +458,28 @@ 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``. If a ``COMPONENT`` option is
specified that does not match that given to the targets associated with
``<export-name>`` the behavior is undefined. If a library target is
included in the export but a target to which it links is not included
the behavior is unspecified.
In addition to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe
used to specify an export to the android ndk build system. The Android
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
@ -378,7 +496,7 @@ and installed by the current project. For example, the code
will install the executable myexe to ``<prefix>/bin`` and code to import
it in the file ``<prefix>/lib/myproj/myproj.cmake`` and
``<prefix>/lib/share/ndk-modules/Android.mk``. An outside project
``<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.
@ -392,3 +510,26 @@ executable from the installation tree using the imported target name
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.

@ -3,66 +3,257 @@ 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:
::
list(LENGTH <list> <output variable>)
list(GET <list> <element index> [<element index> ...]
<output variable>)
Returns the list's length.
.. _GET:
::
list(GET <list> <element index> [<element index> ...] <output variable>)
Returns the list of elements specified by indices from the list.
.. _JOIN:
::
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:
::
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:
::
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:
::
list(APPEND <list> [<element> ...])
Appends elements to the list.
.. _FILTER:
::
list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
list(FIND <list> <value> <output variable>)
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:
::
list(INSERT <list> <element_index> <element> [<element> ...])
Inserts elements to the list to the specified location.
.. _REMOVE_ITEM:
::
list(REMOVE_ITEM <list> <value> [<value> ...])
Removes the given items from the list.
.. _REMOVE_AT:
::
list(REMOVE_AT <list> <index> [<index> ...])
Removes items at given indices from the list.
.. _REMOVE_DUPLICATES:
::
list(REMOVE_DUPLICATES <list>)
list(REVERSE <list>)
list(SORT <list>)
``LENGTH`` will return a given list's length.
Removes duplicated items in the list.
``GET`` will return list of elements specified by indices from the list.
.. _TRANSFORM:
``APPEND`` will append elements to the list.
::
``FILTER`` will include or remove 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.
list(TRANSFORM <list> <ACTION> [<SELECTOR>]
[OUTPUT_VARIABLE <output variable>])
``FIND`` will return the index of the element specified in the list or -1
if it wasn't found.
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.
``INSERT`` will insert elements to the list to the specified location.
.. note::
``REMOVE_AT`` and ``REMOVE_ITEM`` will remove items from the list. The
difference is that ``REMOVE_ITEM`` will remove the given items, while
``REMOVE_AT`` will remove the items at the given indices.
``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.
``REMOVE_DUPLICATES`` will remove duplicated items in the list.
``<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.
``REVERSE`` reverses the contents of the list in-place.
The ``<ACTION>`` may be one of:
``SORT`` sorts the list in-place alphabetically.
``APPEND``, ``PREPEND``: Append, prepend specified value to each element of
the list. ::
list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower
characters. ::
list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
``STRIP``: Remove leading and trailing spaces from each element of the
list. ::
list(TRANSFORM <list> STRIP ...)
``GENEX_STRIP``: Strip any
:manual:`generator expressions <cmake-generator-expressions(7)>` from each
element of the list. ::
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). ::
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. ::
list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
``FOR``: Specify a range with, optionally, an increment used to iterate over
the range. ::
list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
``REGEX``: Specify a regular expression. Only elements matching the regular
expression will be transformed. ::
list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
Ordering
^^^^^^^^
.. _REVERSE:
::
list(REVERSE <list>)
Reverses the contents of the list in-place.
.. _SORT:
::
list(SORT <list>)
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.
NOTES: 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.)
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.
Sorts the list in-place alphabetically.

@ -1,7 +1,7 @@
project
-------
Set a name, version, and enable languages for the entire project.
Sets project details such as name, version, etc. and enables languages.
.. code-block:: cmake
@ -9,6 +9,7 @@ Set a name, version, and enable languages for the entire project.
project(<PROJECT-NAME>
[VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
[DESCRIPTION <project-description-string>]
[HOMEPAGE_URL <url-string>]
[LANGUAGES <language-name>...])
Sets the name of the project and stores the name in the
@ -41,9 +42,18 @@ in variables
Variables corresponding to unspecified versions are set to the empty string
(if policy :policy:`CMP0048` is set to ``NEW``).
If optional ``DESCRIPTION`` is given, then additional :variable:`PROJECT_DESCRIPTION`
variable will be set to its argument. The argument must be a string with short
description of the project (only a few words).
If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION`
and :variable:`<PROJECT-NAME>_DESCRIPTION` will be set to its argument.
The description is expected to be a relatively short string, usually no more
than a few words.
The optional ``HOMEPAGE_URL`` sets the analogous variables
:variable:`PROJECT_HOMEPAGE_URL` and :variable:`<PROJECT-NAME>_HOMEPAGE_URL`.
When this option is given, the URL provided should be the canonical home for
the project.
Note that the description and homepage URL may be used as defaults for
things like packaging meta-data, documentation, etc.
Optionally you can specify which languages your project supports.
Example languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``,
@ -63,7 +73,12 @@ The top-level ``CMakeLists.txt`` file for a project must contain a
literal, direct call to the :command:`project` command; loading one
through the :command:`include` command is not sufficient. If no such
call exists CMake will implicitly add one to the top that enables the
default languages (``C`` and ``CXX``).
default languages (``C`` and ``CXX``). The name of the project set in
the top level ``CMakeLists.txt`` file is available from the
:variable:`CMAKE_PROJECT_NAME` variable, its description from
:variable:`CMAKE_PROJECT_DESCRIPTION`, its homepage URL from
:variable:`CMAKE_PROJECT_HOMEPAGE_URL` and its version from
:variable:`CMAKE_PROJECT_VERSION`.
.. note::
Call the :command:`cmake_minimum_required` command at the beginning

@ -59,11 +59,17 @@ be one of the following:
The required ``PROPERTY`` option is immediately followed by the name of
the property to set. Remaining arguments are used to compose the
property value in the form of a semicolon-separated list. If the
``APPEND`` option is given the list is appended to any existing property
value. If the ``APPEND_STRING`` option is given the string is append to any
existing property value as string, i.e. it results in a longer string
and not a list of strings.
property value in the form of a semicolon-separated list.
If the ``APPEND`` option is given the list is appended to any existing
property value. If the ``APPEND_STRING`` option is given the string is
appended to any existing property value as string, i.e. it results in a
longer string and not a list of strings. When using ``APPEND`` or
``APPEND_STRING`` with a property defined to support ``INHERITED``
behavior (see :command:`define_property`), no inheriting occurs when
finding the initial value to append to. If the property is not already
directly set in the nominated scope, the command will behave as though
``APPEND`` or ``APPEND_STRING`` had not been given.
See the :manual:`cmake-properties(7)` manual for a list of properties
in each scope.

@ -9,10 +9,12 @@ Targets can have properties that affect how they are built.
PROPERTIES prop1 value1
prop2 value2 ...)
Set properties on a target. The syntax for the command is to list all
the files you want to change, and then provide the values you want to
Set properties on targets. The syntax for the command is to list all
the targets you want to change, and then provide the values you want to
set next. You can use any prop value pair you want and extract it
later with the :command:`get_property` or :command:`get_target_property`
command.
See also the :command:`set_property(TARGET)` command.
See :ref:`Target Properties` for the list of properties known to CMake.

@ -1,17 +1,52 @@
string
------
.. only:: html
.. contents::
String operations.
Synopsis
^^^^^^^^
.. parsed-literal::
`Search and Replace`_
string(`FIND`_ <string> <substring> <out-var> [...])
string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...)
`Regular Expressions`_
string(`REGEX MATCH`_ <match-regex> <out-var> <input>...)
string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...)
string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...)
`Manipulation`_
string(`APPEND`_ <string-var> [<input>...])
string(`PREPEND`_ <string-var> [<input>...])
string(`CONCAT`_ <out-var> [<input>...])
string(`JOIN`_ <glue> <out-var> [<input>...])
string(`TOLOWER`_ <string1> <out-var>)
string(`TOUPPER`_ <string1> <out-var>)
string(`LENGTH`_ <string> <out-var>)
string(`SUBSTRING`_ <string> <begin> <length> <out-var>)
string(`STRIP`_ <string> <out-var>)
string(`GENEX_STRIP`_ <string> <out-var>)
`Comparison`_
string(`COMPARE`_ <op> <string1> <string2> <out-var>)
`Hashing`_
string(`\<HASH\> <HASH_>`_ <out-var> <input>)
`Generation`_
string(`ASCII`_ <number>... <out-var>)
string(`CONFIGURE`_ <string1> <out-var> [...])
string(`MAKE_C_IDENTIFIER`_ <string> <out-var>)
string(`RANDOM`_ [<option>...] <out-var>)
string(`TIMESTAMP`_ <out-var> [<format string>] [UTC])
string(`UUID`_ <out-var> ...)
Search and Replace
^^^^^^^^^^^^^^^^^^
FIND
""""
.. _FIND:
::
@ -22,8 +57,7 @@ the supplied string. If the ``REVERSE`` flag was used, the command will
search for the position of the last occurrence of the specified
substring. If the substring is not found, a position of -1 is returned.
REPLACE
"""""""
.. _REPLACE:
::
@ -37,8 +71,7 @@ with ``replace_string`` and store the result in the output.
Regular Expressions
^^^^^^^^^^^^^^^^^^^
REGEX MATCH
"""""""""""
.. _`REGEX MATCH`:
::
@ -48,8 +81,7 @@ REGEX MATCH
Match the regular expression once and store the match in the output variable.
All ``<input>`` arguments are concatenated before matching.
REGEX MATCHALL
""""""""""""""
.. _`REGEX MATCHALL`:
::
@ -60,8 +92,7 @@ Match the regular expression as many times as possible and store the matches
in the output variable as a list.
All ``<input>`` arguments are concatenated before matching.
REGEX REPLACE
"""""""""""""
.. _`REGEX REPLACE`:
::
@ -123,8 +154,7 @@ expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``.
Manipulation
^^^^^^^^^^^^
APPEND
""""""
.. _APPEND:
::
@ -132,8 +162,7 @@ APPEND
Append all the input arguments to the string.
PREPEND
"""""""
.. _PREPEND:
::
@ -141,8 +170,7 @@ PREPEND
Prepend all the input arguments to the string.
CONCAT
""""""
.. _CONCAT:
::
@ -151,8 +179,20 @@ CONCAT
Concatenate all the input arguments together and store
the result in the named output variable.
TOLOWER
"""""""
.. _JOIN:
::
string(JOIN <glue> <output variable> [<input>...])
Join all the input arguments together using the glue
string and store the result in the named output variable.
To join list's elements, use preferably the ``JOIN`` operator
from :command:`list` command. This allows for the elements to have
special characters like ``;`` in them.
.. _TOLOWER:
::
@ -160,8 +200,7 @@ TOLOWER
Convert string to lower characters.
TOUPPER
"""""""
.. _TOUPPER:
::
@ -169,8 +208,7 @@ TOUPPER
Convert string to upper characters.
LENGTH
""""""
.. _LENGTH:
::
@ -178,8 +216,7 @@ LENGTH
Store in an output variable a given string's length.
SUBSTRING
"""""""""
.. _SUBSTRING:
::
@ -193,8 +230,7 @@ If string is shorter than length then end of string is used instead.
CMake 3.1 and below reported an error if length pointed past
the end of string.
STRIP
"""""
.. _STRIP:
::
@ -203,8 +239,7 @@ STRIP
Store in an output variable a substring of a given string with leading and
trailing spaces removed.
GENEX_STRIP
"""""""""""
.. _GENEX_STRIP:
::
@ -216,6 +251,8 @@ from the ``input string`` and store the result in the ``output variable``.
Comparison
^^^^^^^^^^
.. _COMPARE:
::
string(COMPARE LESS <string1> <string2> <output variable>)
@ -232,6 +269,8 @@ Compare the strings and store true or false in the output variable.
Hashing
^^^^^^^
.. _`HASH`:
::
string(<HASH> <output variable> <input>)
@ -263,8 +302,7 @@ The supported ``<HASH>`` algorithm names are:
Generation
^^^^^^^^^^
ASCII
"""""
.. _ASCII:
::
@ -272,8 +310,7 @@ ASCII
Convert all numbers into corresponding ASCII characters.
CONFIGURE
"""""""""
.. _CONFIGURE:
::
@ -282,8 +319,18 @@ CONFIGURE
Transform a string like :command:`configure_file` transforms a file.
RANDOM
""""""
.. _MAKE_C_IDENTIFIER:
::
string(MAKE_C_IDENTIFIER <input string> <output variable>)
Convert each non-alphanumeric character in the ``<input string>`` to an
underscore and store the result in the ``<output variable>``. If the first
character of the string is a digit, an underscore will also be prepended to
the result.
.. _RANDOM:
::
@ -296,8 +343,7 @@ and default alphabet is all numbers and upper and lower case letters.
If an integer ``RANDOM_SEED`` is given, its value will be used to seed the
random number generator.
TIMESTAMP
"""""""""
.. _TIMESTAMP:
::
@ -346,28 +392,20 @@ If no explicit ``<format string>`` is given it will default to:
%Y-%m-%dT%H:%M:%S for local time.
%Y-%m-%dT%H:%M:%SZ for UTC.
::
string(MAKE_C_IDENTIFIER <input string> <output variable>)
Write a string which can be used as an identifier in C.
.. note::
If the ``SOURCE_DATE_EPOCH`` environment variable is set,
its value will be used instead of the current time.
See https://reproducible-builds.org/specs/source-date-epoch/ for details.
UUID
""""
.. _UUID:
::
string(UUID <output variable> NAMESPACE <namespace> NAME <name>
TYPE <MD5|SHA1> [UPPER])
Create a univerally unique identifier (aka GUID) as per RFC4122
Create a universally unique identifier (aka GUID) as per RFC4122
based on the hash of the combined values of ``<namespace>``
(which itself has to be a valid UUID) and ``<name>``.
The hash algorithm can be either ``MD5`` (Version 3 UUID) or

@ -27,3 +27,13 @@ Arguments to ``target_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.
Any leading ``-D`` on an item will be removed. Empty items are ignored.
For example, the following are all equivalent:
.. code-block:: cmake
target_compile_definitions(foo PUBLIC FOO)
target_compile_definitions(foo PUBLIC -DFOO) # -D removed
target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored

@ -19,8 +19,8 @@ instead of being appended.
This command can be used to add any options, but
alternative commands exist to add preprocessor definitions
(:command:`target_compile_definitions` and :command:`add_definitions`) or
include directories (:command:`target_include_directories` and
(:command:`target_compile_definitions` and :command:`add_compile_definitions`)
or include directories (:command:`target_include_directories` and
:command:`include_directories`). See documentation of the
:prop_dir:`directory <COMPILE_OPTIONS>` and
:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties.
@ -38,3 +38,5 @@ Arguments to ``target_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:: COMPILE_OPTIONS_SHELL.txt

@ -183,6 +183,70 @@ is not ``NEW``, they are also appended to the
``general`` (or without any keyword) are treated as if specified for both
``debug`` and ``optimized``.
Linking Object Libraries
^^^^^^^^^^^^^^^^^^^^^^^^
:ref:`Object Libraries` may be used as the ``<target>`` (first) argument
of ``target_link_libraries`` to specify dependencies of their sources
on other libraries. For example, the code
.. code-block:: cmake
add_library(A SHARED a.c)
target_compile_definitions(A PUBLIC A)
add_library(obj OBJECT obj.c)
target_compile_definitions(obj PUBLIC OBJ)
target_link_libraries(obj PUBLIC A)
compiles ``obj.c`` with ``-DA -DOBJ`` and establishes usage requirements
for ``obj`` that propagate to its dependents.
Normal libraries and executables may link to :ref:`Object Libraries`
to get their objects and usage requirements. Continuing the above
example, the code
.. code-block:: cmake
add_library(B SHARED b.c)
target_link_libraries(B PUBLIC obj)
compiles ``b.c`` with ``-DA -DOBJ``, creates shared library ``B``
with object files from ``b.c`` and ``obj.c``, and links ``B`` to ``A``.
Furthermore, the code
.. code-block:: cmake
add_executable(main main.c)
target_link_libraries(main B)
compiles ``main.c`` with ``-DA -DOBJ`` and links executable ``main``
to ``B`` and ``A``. The object library's usage requirements are
propagated transitively through ``B``, but its object files are not.
:ref:`Object Libraries` may "link" to other object libraries to get
usage requirements, but since they do not have a link step nothing
is done with their object files. Continuing from the above example,
the code:
.. code-block:: cmake
add_library(obj2 OBJECT obj2.c)
target_link_libraries(obj2 PUBLIC obj)
add_executable(main2 main2.c)
target_link_libraries(main2 obj2)
compiles ``obj2.c`` with ``-DA -DOBJ``, creates executable ``main2``
with object files from ``main2.c`` and ``obj2.c``, and links ``main2``
to ``A``.
In other words, when :ref:`Object Libraries` appear in a target's
:prop_tgt:`INTERFACE_LINK_LIBRARIES` property they will be
treated as :ref:`Interface Libraries`, but when they appear in
a target's :prop_tgt:`LINK_LIBRARIES` property their object files
will be included in the link too.
Cyclic Dependencies of Static Libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

@ -401,11 +401,14 @@ The ``Do: merge`` command accepts the following arguments:
branch in the constructed merge commit message.
Additionally, ``Do: merge`` extracts configuration from trailing lines
in the MR description:
in the MR description (the following have no effect if used in a MR
comment instead):
* ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of
the MR topic branch in the constructed merge commit message.
The ``-t`` option overrides this.
It is also used in merge commits constructed by ``Do: stage``.
The ``-t`` option to a ``Do: merge`` command overrides any topic
rename set in the MR description.
.. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members

@ -9,7 +9,7 @@ See documentation on `CMake Development`_ for more information.
C++ Code Style
==============
We use `clang-format`_ version **3.8** to define our style for C++ code in
We use `clang-format`_ version **6.0** to define our style for C++ code in
the CMake source tree. See the `.clang-format`_ configuration file for our
style settings. Use the `Utilities/Scripts/clang-format.bash`_ script to
format source code. It automatically runs ``clang-format`` on the set of

@ -0,0 +1,9 @@
CMAKE_BUILD_PARALLEL_LEVEL
--------------------------
Specifies the maximum number of concurrent processes to use when building
using the ``cmake --build`` command line
:ref:`Build Tool Mode <Build Tool Mode>`.
If this variable is defined empty the native build tool's default number is
used.

@ -0,0 +1,19 @@
DESTDIR
-------
On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the
whole installation. ``DESTDIR`` means DESTination DIRectory. It is
commonly used by makefile users in order to install software at
non-default location. It is usually invoked like this:
::
make DESTDIR=/home/john install
which will install the concerned software using the installation
prefix, e.g. ``/usr/local`` prepended with the ``DESTDIR`` value which
finally gives ``/home/john/usr/local``.
WARNING: ``DESTDIR`` may not be used on Windows because installation
prefix usually contains a drive letter like in ``C:/Program Files``
which cannot be prepended with some other prefix.

@ -0,0 +1,15 @@
<PackageName>_ROOT
------------------
Calls to :command:`find_package(<PackageName>)` will search in prefixes
specified by the ``<PackageName>_ROOT`` environment variable, where
``<PackageName>`` is the name given to the ``find_package`` call
and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search
prefixes specified in the ``Foo_ROOT`` environment variable (if set).
See policy :policy:`CMP0074`.
This variable may hold a single prefix or a list of prefixes separated
by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
variable convention on those platforms).
See also the :variable:`<PackageName>_ROOT` CMake variable.

@ -1,23 +1,6 @@
Visual Studio 8 2005
--------------------
Deprecated. Generates Visual Studio 8 2005 project files.
.. note::
This generator is deprecated and will be removed in a future version
of CMake. It will still be possible to build with VS 8 2005 tools
using the :generator:`Visual Studio 10 2010` (or above) generator
with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v80``, or by
using the :generator:`NMake Makefiles` generator.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
to specify a target platform name.
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of this generator name:
``Visual Studio 8 2005 Win64``
Specify target platform ``x64``.
``Visual Studio 8 2005 <WinCE-SDK>``
Specify target platform matching a Windows CE SDK name.
Removed. This once generated Visual Studio 8 2005 project files, but
the generator has been removed since CMake 3.12. It is still possible to
build with VS 2005 tools using the :generator:`NMake Makefiles` generator.

@ -29,18 +29,18 @@ Reference Manuals
/manual/cmake-commands.7
/manual/cmake-compile-features.7
/manual/cmake-developer.7
/manual/cmake-env-variables.7
/manual/cmake-generator-expressions.7
/manual/cmake-generators.7
/manual/cmake-language.7
/manual/cmake-server.7
/manual/cmake-modules.7
/manual/cmake-packages.7
/manual/cmake-policies.7
/manual/cmake-properties.7
/manual/cmake-qt.7
/manual/cmake-server.7
/manual/cmake-toolchains.7
/manual/cmake-variables.7
/manual/cmake-env-variables.7
.. only:: html or text

@ -5,15 +5,11 @@ Home Page
The primary starting point for learning about CMake.
Frequently Asked Questions
https://cmake.org/Wiki/CMake_FAQ
A Wiki is provided containing answers to frequently asked questions.
Online Documentation
Online Documentation and Community Resources
https://cmake.org/documentation
Links to available documentation may be found on this web page.
Links to available documentation and community resources may be
found on this web page.
Mailing List
https://cmake.org/mailing-lists

@ -11,7 +11,7 @@
cache-format file.
``-D <var>:<type>=<value>, -D <var>=<value>``
Create a cmake cache entry.
Create or update a cmake cache entry.
When cmake is first run in an empty build tree, it creates a
CMakeCache.txt file and populates it with customizable settings for

@ -8,7 +8,7 @@ Synopsis
.. parsed-literal::
ccmake [<options>] (<path-to-source> | <path-to-existing-build>)
ccmake [<options>] {<path-to-source> | <path-to-existing-build>}
Description
===========

@ -113,9 +113,9 @@ and it uniquely identifies the bundle.
Object Libraries
^^^^^^^^^^^^^^^^
The ``OBJECT`` library type is also not linked to. It defines a non-archival
collection of object files resulting from compiling the given source files.
The object files collection can be used as source inputs to other targets:
The ``OBJECT`` library type defines a non-archival collection of object files
resulting from compiling the given source files. The object files collection
may be used as source inputs to other targets:
.. code-block:: cmake
@ -125,22 +125,31 @@ The object files collection can be used as source inputs to other targets:
add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
``OBJECT`` libraries may not be used in the right hand side of
:command:`target_link_libraries`. They also may not be used as the ``TARGET``
in a use of the :command:`add_custom_command(TARGET)` command signature. They
may be installed, and will be exported as an INTERFACE library.
The link (or archiving) step of those other targets will use the object
files collection in addition to those from their own sources.
Although object libraries may not be named directly in calls to
the :command:`target_link_libraries` command, they can be "linked"
indirectly by using an :ref:`Interface Library <Interface Libraries>`
whose :prop_tgt:`INTERFACE_SOURCES` target property is set to name
``$<TARGET_OBJECTS:objlib>``.
Alternatively, object libraries may be linked into other targets:
Although object libraries may not be used as the ``TARGET``
in a use of the :command:`add_custom_command(TARGET)` command signature,
the list of objects can be used by :command:`add_custom_command(OUTPUT)` or
:command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``.
.. code-block:: cmake
add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
add_library(archiveExtras STATIC extras.cpp)
target_link_libraries(archiveExtras PUBLIC archive)
add_executable(test_exe test.cpp)
target_link_libraries(test_exe archive)
The link (or archiving) step of those other targets will use the object
files from object libraries that are *directly* linked. Additionally,
usage requirements of the object libraries will be honored when compiling
sources in those other targets. Furthermore, those usage requirements
will propagate transitively to dependents of those other targets.
Object libraries may not be used as the ``TARGET`` in a use of the
:command:`add_custom_command(TARGET)` command signature. However,
the list of objects can be used by :command:`add_custom_command(OUTPUT)`
or :command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``.
Build Specification and Usage Requirements
==========================================
@ -812,7 +821,7 @@ Directory-Scoped Commands
The :command:`target_include_directories`,
:command:`target_compile_definitions` and
:command:`target_compile_options` commands have an effect on only one
target at a time. The commands :command:`add_definitions`,
target at a time. The commands :command:`add_compile_definitions`,
:command:`add_compile_options` and :command:`include_directories` have
a similar function, but operate at directory scope instead of target
scope for convenience.

@ -70,6 +70,7 @@ These commands are available only in CMake projects.
.. toctree::
:maxdepth: 1
/command/add_compile_definitions
/command/add_compile_options
/command/add_custom_command
/command/add_custom_target

@ -331,9 +331,9 @@ and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from
the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the
versions specified for each:
* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 6.2.
* ``Clang``: Clang compiler versions 2.9 through 3.4.
* ``GNU``: GNU compiler versions 4.4 through 5.0.
* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 9.2.
* ``Clang``: Clang compiler versions 2.9 through 6.0.
* ``GNU``: GNU compiler versions 4.4 through 8.0.
* ``MSVC``: Microsoft Visual Studio versions 2010 through 2017.
* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.6.
* ``Intel``: Intel compiler versions 12.1 through 17.0.
@ -344,7 +344,7 @@ the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the
versions specified for each:
* all compilers and versions listed above for C++.
* ``GNU``: GNU compiler versions 3.4 through 5.0.
* ``GNU``: GNU compiler versions 3.4 through 8.0.
CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and
their associated meta-features (e.g. ``cxx_std_11``) available from the
@ -361,9 +361,10 @@ following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the
versions specified for each:
* all compilers and versions listed above with only meta-features for C++.
* ``TI``: Texas Instruments compiler.
CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>`
from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the
versions specified for each:
* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 8.0.
* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 9.1.

@ -644,6 +644,8 @@ Documentation`_ section above.
.. _`CMake Developer Standard Variable Names`:
Standard Variable Names
^^^^^^^^^^^^^^^^^^^^^^^
@ -943,7 +945,7 @@ populated:
endif()
The ``RELEASE`` variant should be listed first in the property
so that that variant is chosen if the user uses a configuration which is
so that the variant is chosen if the user uses a configuration which is
not an exact match for any listed ``IMPORTED_CONFIGURATIONS``.
Most of the cache variables should be hidden in the ``ccmake`` interface unless

@ -13,11 +13,14 @@ Environment Variables that Control the Build
.. toctree::
:maxdepth: 1
/envvar/CMAKE_BUILD_PARALLEL_LEVEL
/envvar/CMAKE_CONFIG_TYPE
/envvar/CMAKE_MSVCIDE_RUN_PATH
/envvar/CMAKE_OSX_ARCHITECTURES
/envvar/DESTDIR
/envvar/LDFLAGS
/envvar/MACOSX_DEPLOYMENT_TARGET
/envvar/PackageName_ROOT
Environment Variables for Languages
===================================

@ -57,6 +57,10 @@ Available logical expressions are:
``1`` if ``a`` is STREQUAL ``b``, else ``0``
``$<EQUAL:a,b>``
``1`` if ``a`` is EQUAL ``b`` in a numeric comparison, else ``0``
``$<IN_LIST:a,b>``
``1`` if ``a`` is IN_LIST ``b``, else ``0``
``$<TARGET_EXISTS:tgt>``
``1`` if ``tgt`` is an existed target name, else ``0``.
``$<CONFIG:cfg>``
``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison.
The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by
@ -270,6 +274,9 @@ Available output expressions are:
Marks ``...`` as being the name of a target. This is required if exporting
targets to multiple dependent export sets. The ``...`` must be a literal
name of a target- it may not contain generator expressions.
``$<TARGET_NAME_IF_EXISTS:...>``
Expands to the ``...`` if the given target exists, an empty string
otherwise.
``$<LINK_ONLY:...>``
Content of ``...`` except when evaluated in a link interface while
propagating :ref:`Target Usage Requirements`, in which case it is the
@ -289,7 +296,8 @@ Available output expressions are:
``$<UPPER_CASE:...>``
Content of ``...`` converted to upper case.
``$<MAKE_C_IDENTIFIER:...>``
Content of ``...`` converted to a C identifier.
Content of ``...`` converted to a C identifier. The conversion follows the
same behavior as :command:`string(MAKE_C_IDENTIFIER)`.
``$<TARGET_OBJECTS:objLib>``
List of objects resulting from build of ``objLib``. ``objLib`` must be an
object of type ``OBJECT_LIBRARY``.
@ -297,3 +305,42 @@ Available output expressions are:
Content of ``...`` converted to shell path style. For example, slashes are
converted to backslashes in Windows shells and drive letters are converted
to posix paths in MSYS shells. The ``...`` must be an absolute path.
``$<GENEX_EVAL:...>``
Content of ``...`` evaluated as a generator expression in the current
context. This enables consumption of generator expressions
whose evaluation results itself in generator expressions.
``$<TARGET_GENEX_EVAL:tgt,...>``
Content of ``...`` evaluated as a generator expression in the context of
``tgt`` target. This enables consumption of custom target properties that
themselves contain generator expressions.
Having the capability to evaluate generator expressions is very useful when
you want to manage custom properties supporting generator expressions.
For example:
.. code-block:: cmake
add_library(foo ...)
set_property(TARGET foo PROPERTY
CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
)
add_custom_target(printFooKeys
COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
)
This naive implementation of the ``printFooKeys`` custom command is wrong
because ``CUSTOM_KEYS`` target property is not evaluated and the content
is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``).
To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is
``Debug``), it is required to evaluate the output of
``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``:
.. code-block:: cmake
add_custom_target(printFooKeys
COMMAND ${CMAKE_COMMAND} -E
echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
)

@ -9,7 +9,7 @@ Synopsis
.. parsed-literal::
cmake-gui [<options>]
cmake-gui [<options>] (<path-to-source> | <path-to-existing-build>)
cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>}
Description
===========

@ -64,6 +64,7 @@ All Modules
/module/CPackIFW
/module/CPackIFWConfigureFile
/module/CPackNSIS
/module/CPackNuGet
/module/CPackPackageMaker
/module/CPackProductBuild
/module/CPackRPM
@ -155,6 +156,7 @@ All Modules
/module/FindMPEG2
/module/FindMPEG
/module/FindMPI
/module/FindODBC
/module/FindOpenACC
/module/FindOpenAL
/module/FindOpenCL
@ -196,6 +198,9 @@ All Modules
/module/FindPostgreSQL
/module/FindProducer
/module/FindProtobuf
/module/FindPython
/module/FindPython2
/module/FindPython3
/module/FindPythonInterp
/module/FindPythonLibs
/module/FindQt3

@ -51,6 +51,16 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
to determine whether to report an error on use of deprecated macros or
functions.
Policies Introduced by CMake 3.12
=================================
.. toctree::
:maxdepth: 1
CMP0075: Include file check macros honor CMAKE_REQUIRED_LIBRARIES. </policy/CMP0075>
CMP0074: find_package uses PackageName_ROOT variables. </policy/CMP0074>
CMP0073: Do not produce legacy _LIB_DEPENDS cache entries. </policy/CMP0073>
Policies Introduced by CMake 3.11
=================================

@ -40,6 +40,7 @@ Properties of Global Scope
/prop_gbl/JOB_POOLS
/prop_gbl/PREDEFINED_TARGETS_FOLDER
/prop_gbl/ECLIPSE_EXTRA_NATURES
/prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS
/prop_gbl/REPORT_UNDEFINED_PROPERTIES
/prop_gbl/RULE_LAUNCH_COMPILE
/prop_gbl/RULE_LAUNCH_CUSTOM
@ -84,6 +85,7 @@ Properties on Directories
/prop_dir/RULE_LAUNCH_LINK
/prop_dir/SOURCE_DIR
/prop_dir/SUBDIRECTORIES
/prop_dir/TESTS
/prop_dir/TEST_INCLUDE_FILES
/prop_dir/VARIABLES
/prop_dir/VS_GLOBAL_SECTION_POST_section
@ -142,6 +144,7 @@ Properties on Targets
/prop_tgt/C_EXTENSIONS
/prop_tgt/C_STANDARD
/prop_tgt/C_STANDARD_REQUIRED
/prop_tgt/COMMON_LANGUAGE_RUNTIME
/prop_tgt/COMPATIBLE_INTERFACE_BOOL
/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MAX
/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN
@ -169,12 +172,14 @@ Properties on Targets
/prop_tgt/DEBUG_POSTFIX
/prop_tgt/DEFINE_SYMBOL
/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY
/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION
/prop_tgt/EchoString
/prop_tgt/ENABLE_EXPORTS
/prop_tgt/EXCLUDE_FROM_ALL
/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG
/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD
/prop_tgt/EXPORT_NAME
/prop_tgt/EXPORT_PROPERTIES
/prop_tgt/FOLDER
/prop_tgt/Fortran_FORMAT
/prop_tgt/Fortran_MODULE_DIRECTORY
@ -184,6 +189,7 @@ Properties on Targets
/prop_tgt/GNUtoMS
/prop_tgt/HAS_CXX
/prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
/prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME
/prop_tgt/IMPORTED_CONFIGURATIONS
/prop_tgt/IMPORTED_GLOBAL
/prop_tgt/IMPORTED_IMPLIB_CONFIG
@ -295,6 +301,7 @@ Properties on Targets
/prop_tgt/VISIBILITY_INLINES_HIDDEN
/prop_tgt/VS_CONFIGURATION_TYPE
/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY
/prop_tgt/VS_DEBUGGER_COMMAND
/prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION
/prop_tgt/VS_DOTNET_REFERENCE_refname
/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname
@ -347,6 +354,7 @@ Properties on Tests
/prop_test/LABELS
/prop_test/MEASUREMENT
/prop_test/PASS_REGULAR_EXPRESSION
/prop_test/PROCESSOR_AFFINITY
/prop_test/PROCESSORS
/prop_test/REQUIRED_FILES
/prop_test/RESOURCE_LOCK
@ -399,6 +407,7 @@ Properties on Source Files
/prop_sf/VS_SHADER_ENTRYPOINT
/prop_sf/VS_SHADER_FLAGS
/prop_sf/VS_SHADER_MODEL
/prop_sf/VS_SHADER_OBJECT_FILE_NAME
/prop_sf/VS_SHADER_OUTPUT_HEADER_FILE
/prop_sf/VS_SHADER_TYPE
/prop_sf/VS_SHADER_VARIABLE_NAME

@ -49,10 +49,12 @@ Operation
Start :manual:`cmake(1)` in the server command mode, supplying the path to
the build directory to process::
cmake -E server (--debug|--pipe <NAMED_PIPE>)
cmake -E server (--debug|--pipe=<NAMED_PIPE>)
The server will communicate using stdin/stdout (with the ``--debug`` parameter)
or using a named pipe (with the ``--pipe <NAMED_PIPE>`` parameter).
or using a named pipe (with the ``--pipe=<NAMED_PIPE>`` parameter). Note
that "named pipe" refers to a local domain socket on Unix and to a named pipe
on Windows.
When connecting to the server (via named pipe or by starting it in ``--debug``
mode), the server will reply with a hello message::

@ -34,6 +34,7 @@ Variables that Provide Information
/variable/CMAKE_CURRENT_SOURCE_DIR
/variable/CMAKE_DIRECTORY_LABELS
/variable/CMAKE_DL_LIBS
/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION
/variable/CMAKE_EDIT_COMMAND
/variable/CMAKE_EXECUTABLE_SUFFIX
/variable/CMAKE_EXTRA_GENERATOR
@ -67,7 +68,13 @@ Variables that Provide Information
/variable/CMAKE_PARENT_LIST_FILE
/variable/CMAKE_PATCH_VERSION
/variable/CMAKE_PROJECT_DESCRIPTION
/variable/CMAKE_PROJECT_HOMEPAGE_URL
/variable/CMAKE_PROJECT_NAME
/variable/CMAKE_PROJECT_VERSION
/variable/CMAKE_PROJECT_VERSION_MAJOR
/variable/CMAKE_PROJECT_VERSION_MINOR
/variable/CMAKE_PROJECT_VERSION_PATCH
/variable/CMAKE_PROJECT_VERSION_TWEAK
/variable/CMAKE_RANLIB
/variable/CMAKE_ROOT
/variable/CMAKE_SCRIPT_MODE_FILE
@ -93,10 +100,13 @@ Variables that Provide Information
/variable/CMAKE_VS_PLATFORM_TOOLSET
/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA
/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION
/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
/variable/CMAKE_XCODE_GENERATE_SCHEME
/variable/CMAKE_XCODE_PLATFORM_TOOLSET
/variable/PROJECT-NAME_BINARY_DIR
/variable/PROJECT-NAME_DESCRIPTION
/variable/PROJECT-NAME_HOMEPAGE_URL
/variable/PROJECT-NAME_SOURCE_DIR
/variable/PROJECT-NAME_VERSION
/variable/PROJECT-NAME_VERSION_MAJOR
@ -105,6 +115,7 @@ Variables that Provide Information
/variable/PROJECT-NAME_VERSION_TWEAK
/variable/PROJECT_BINARY_DIR
/variable/PROJECT_DESCRIPTION
/variable/PROJECT_HOMEPAGE_URL
/variable/PROJECT_NAME
/variable/PROJECT_SOURCE_DIR
/variable/PROJECT_VERSION
@ -178,6 +189,7 @@ Variables that Change Behavior
/variable/CMAKE_STAGING_PREFIX
/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
/variable/CMAKE_SUPPRESS_REGENERATION
/variable/CMAKE_SYSROOT
/variable/CMAKE_SYSROOT_COMPILE
/variable/CMAKE_SYSROOT_LINK
@ -192,6 +204,7 @@ Variables that Change Behavior
/variable/CMAKE_WARN_DEPRECATED
/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
/variable/PackageName_ROOT
Variables that Describe the System
==================================
@ -234,6 +247,7 @@ Variables that Describe the System
/variable/MSVC80
/variable/MSVC90
/variable/MSVC_IDE
/variable/MSVC_TOOLSET_VERSION
/variable/MSVC_VERSION
/variable/UNIX
/variable/WIN32
@ -300,6 +314,7 @@ Variables that Control the Build
/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG
/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT
/variable/CMAKE_EXE_LINKER_FLAGS_INIT
/variable/CMAKE_FOLDER
/variable/CMAKE_Fortran_FORMAT
/variable/CMAKE_Fortran_MODULE_DIRECTORY
/variable/CMAKE_GNUtoMS
@ -362,6 +377,13 @@ Variables that Control the Build
/variable/CMAKE_VISIBILITY_INLINES_HIDDEN
/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD
/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES
/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES
/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES
/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES
/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES
/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES
/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES
/variable/CMAKE_WIN32_EXECUTABLE
/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute

@ -8,8 +8,8 @@ Synopsis
.. parsed-literal::
cmake [<options>] (<path-to-source> | <path-to-existing-build>)
cmake [(-D <var>=<value>)...] -P <cmake-script-file>
cmake [<options>] {<path-to-source> | <path-to-existing-build>}
cmake [{-D <var>=<value>}...] -P <cmake-script-file>
cmake --build <dir> [<options>...] [-- <build-tool-options>...]
cmake --open <dir>
cmake -E <command> [<options>...]
@ -159,6 +159,13 @@ following options:
``--build <dir>``
Project binary directory to be built. This is required and must be first.
``-j [<jobs>], --parallel [<jobs>]``
The maximum number of concurrent processes to use when building.
If ``<jobs>`` is omitted the native build tool's default number is used.
The :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment variable, if set,
specifies a default parallel level when this option is not given.
``--target <tgt>``
Build ``<tgt>`` instead of default targets. May only be specified once.

@ -8,92 +8,85 @@ Synopsis
.. parsed-literal::
cpack -G <generator> [<options>]
cpack [<options>]
Description
===========
The "cpack" executable is the CMake packaging program.
CMake-generated build trees created for projects that use the
INSTALL_* commands have packaging support. This program will generate
the package.
CMake is a cross-platform build system generator. Projects specify
their build process with platform-independent CMake listfiles included
in each directory of a source tree with the name CMakeLists.txt.
Users build a project by using CMake to generate a build system for a
native tool on their platform.
The ``cpack`` executable is the CMake packaging program.
CMake projects use :command:`install` commands to define the contents of
packages which can be generated in various formats by this tool.
The :module:`CPack` module greatly simplifies the creation of the input file
used by ``cpack``, allowing most aspects of the packaging configuration to be
controlled directly from the CMake project's own ``CMakeLists.txt`` files.
Options
=======
``-G <generator>``
Use the specified generator to generate package.
CPack may support multiple native packaging systems on certain
platforms. A generator is responsible for generating input files
for particular system and invoking that systems. Possible generator
names are specified in the Generators section.
``-G <generators>``
``<generators>`` is a :ref:`semicolon-separated list <CMake Language Lists>`
of generator names. ``cpack`` will iterate through this list and produce
package(s) in that generator's format according to the details provided in
the ``CPackConfig.cmake`` configuration file. A generator is responsible for
generating the required inputs for a particular package system and invoking
that system's package creation tools. Possible generator names are specified
in the :manual:`Generators <cmake-generators(7)>` section of the manual and
the ``--help`` option lists the generators supported for the target platform.
If this option is not given, the :variable:`CPACK_GENERATOR` variable
determines the default set of generators that will be used.
``-C <Configuration>``
Specify the project configuration
This option specifies the configuration that the project was build
with, for example 'Debug', 'Release'.
Specify the project configuration to be packaged (e.g. ``Debug``,
``Release``, etc.). When the CMake project uses a multi-configuration
generator such as Xcode or Visual Studio, this option is needed to tell
``cpack`` which built executables to include in the package.
``-D <var>=<value>``
Set a CPack variable.
Set a variable that can be used by the generator.
Set a CPack variable. This will override any value set for ``<var>`` in the
input file read by ``cpack``.
``--config <config file>``
Specify the config file.
Specify the config file to use to create the package. By default
CPackConfig.cmake in the current directory will be used.
``--config <configFile>``
Specify the configuration file read by ``cpack`` to provide the packaging
details. By default, ``CPackConfig.cmake`` in the current directory will
be used.
``--verbose,-V``
enable verbose output
Run cpack with verbose output.
Run ``cpack`` with verbose output. This can be used to show more details
from the package generation tools and is suitable for project developers.
``--debug``
enable debug output (for CPack developers)
Run cpack with debug output (for CPack developers).
Run ``cpack`` with debug output. This option is intended mainly for the
developers of ``cpack`` itself and is not normally needed by project
developers.
``--trace``
Put underlying cmake scripts in trace mode.
Put the underlying cmake scripts in trace mode.
``--trace-expand``
Put underlying cmake scripts in expanded trace mode.
``-P <package name>``
override/define CPACK_PACKAGE_NAME
If the package name is not specified on cpack command line
thenCPack.cmake defines it as CMAKE_PROJECT_NAME
``-R <package version>``
override/define CPACK_PACKAGE_VERSION
If version is not specified on cpack command line thenCPack.cmake
defines it from CPACK_PACKAGE_VERSION_[MAJOR|MINOR|PATCH]look into
CPack.cmake for detail
``-B <package directory>``
override/define CPACK_PACKAGE_DIRECTORY
The directory where CPack will be doing its packaging work.The
resulting package will be found there. Inside this directoryCPack
creates '_CPack_Packages' sub-directory which is theCPack temporary
directory.
``--vendor <vendor name>``
override/define CPACK_PACKAGE_VENDOR
If vendor is not specified on cpack command line (or inside
CMakeLists.txt) thenCPack.cmake defines it with a default value
Put the underlying cmake scripts in expanded trace mode.
``-P <packageName>``
Override/define the value of the :variable:`CPACK_PACKAGE_NAME` variable used
for packaging. Any value set for this variable in the ``CPackConfig.cmake``
file will then be ignored.
``-R <packageVersion>``
Override/define the value of the :variable:`CPACK_PACKAGE_VERSION`
variable used for packaging. It will override a value set in the
``CPackConfig.cmake`` file or one automatically computed from
:variable:`CPACK_PACKAGE_VERSION_MAJOR`,
:variable:`CPACK_PACKAGE_VERSION_MINOR` and
:variable:`CPACK_PACKAGE_VERSION_PATCH`.
``-B <packageDirectory>``
Override/define :variable:`CPACK_PACKAGE_DIRECTORY`, which controls the
directory where CPack will perform its packaging work. The resultant
package(s) will be created at this location by default and a
``_CPack_Packages`` subdirectory will also be created below this directory to
use as a working area during package creation.
``--vendor <vendorName>``
Override/define :variable:`CPACK_PACKAGE_VENDOR`.
.. include:: OPTIONS_HELP.txt

@ -13,7 +13,7 @@ Synopsis
ctest [<options>]
ctest <path-to-source> <path-to-build> --build-generator <generator>
[<options>...] [-- <build-options>...] [--test-command <test>]
ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>}
[-- <dashboard-options>...]
Description
@ -368,12 +368,14 @@ for "SubprojectB").
Build and Test Mode
===================
CTest provides a command-line signature to to configure (i.e. run cmake on),
build, and or execute a test::
CTest provides a command-line signature to configure (i.e. run cmake on),
build, and/or execute a test::
ctest --build-and-test <path-to-source> <path-to-build>
--build-generator <generator> [<options>...] [-- <build-options>...]
[--test-command <test>]
--build-generator <generator>
[<options>...]
[--build-options <opts>...]
[--test-command <command> [<args>...]]
The configure and test steps are optional. The arguments to this command line
are the source and binary directories. The ``--build-generator`` option *must*
@ -425,13 +427,15 @@ this mode include:
should be used. e.g. Debug/Release/etc.
``--build-options``
Add extra options to the build step.
This option must be the last option with the exception of
``--test-command``
Additional options for configuring the build (i.e. for CMake, not for
the build tool). Note that if this is specified, the ``--build-options``
keyword and its arguments must be the last option given on the command
line, with the possible exception of ``--test-command``.
``--test-command``
The test to run with the ``--build-and-test`` option.
The command to run as the test step with the ``--build-and-test`` option.
All arguments following this keyword will be assumed to be part of the
test command line, so it must be the last option given.
``--test-timeout``
The time limit in seconds

@ -0,0 +1 @@
.. cmake-module:: ../../Modules/CPackNuGet.cmake

@ -0,0 +1 @@
.. cmake-module:: ../../Modules/FindODBC.cmake

@ -0,0 +1 @@
.. cmake-module:: ../../Modules/FindPython.cmake

@ -0,0 +1 @@
.. cmake-module:: ../../Modules/FindPython2.cmake

@ -0,0 +1 @@
.. cmake-module:: ../../Modules/FindPython3.cmake

@ -0,0 +1,25 @@
CMP0073
-------
Do not produce legacy ``_LIB_DEPENDS`` cache entries.
Ancient CMake versions once used ``<tgt>_LIB_DEPENDS`` cache entries to
propagate library link dependencies. This has long been done by other
means, leaving the :command:`export_library_dependencies` command as the
only user of these values. That command has long been disallowed by
policy :policy:`CMP0033`, but the ``<tgt>_LIB_DEPENDS`` cache entries
were left for compatibility with possible non-standard uses by projects.
CMake 3.12 and above now prefer to not produce these cache entries
at all. This policy provides compatibility with projects that have
not been updated to avoid using them.
The ``OLD`` behavior for this policy is to set ``<tgt>_LIB_DEPENDS`` cache
entries. The ``NEW`` behavior for this policy is to not set them.
This policy was introduced in CMake version 3.12. Use the
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
Unlike most policies, CMake version |release| does *not* warn
when this policy is not set and simply uses ``OLD`` behavior.
.. include:: DEPRECATED.txt

@ -0,0 +1,23 @@
CMP0074
-------
:command:`find_package` uses ``<PackageName>_ROOT`` variables.
In CMake 3.12 and above the :command:`find_package(<PackageName>)` command now
searches prefixes specified by the :variable:`<PackageName>_ROOT` CMake
variable and the :envvar:`<PackageName>_ROOT` environment variable.
Package roots are maintained as a stack so nested calls to all ``find_*``
commands inside find modules also search the roots as prefixes. This policy
provides compatibility with projects that have not been updated to avoid using
``<PackageName>_ROOT`` variables for other purposes.
The ``OLD`` behavior for this policy is to ignore ``<PackageName>_ROOT``
variables. The ``NEW`` behavior for this policy is to use
``<PackageName>_ROOT`` variables.
This policy was introduced in CMake version 3.12. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior.
Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt

@ -0,0 +1,26 @@
CMP0075
-------
Include file check macros honor ``CMAKE_REQUIRED_LIBRARIES``.
In CMake 3.12 and above, the
* ``check_include_file`` macro in the :module:`CheckIncludeFile` module, the
* ``check_include_file_cxx`` macro in the
:module:`CheckIncludeFileCXX` module, and the
* ``check_include_files`` macro in the :module:`CheckIncludeFiles` module
now prefer to link the check executable to the libraries listed in the
``CMAKE_REQUIRED_LIBRARIES`` variable. This policy provides compatibility
with projects that have not been updated to expect this behavior.
The ``OLD`` behavior for this policy is to ignore ``CMAKE_REQUIRED_LIBRARIES``
in the include file check macros. The ``NEW`` behavior of this policy is to
honor ``CMAKE_REQUIRED_LIBRARIES`` in the include file check macros.
This policy was introduced in CMake version 3.12. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior.
Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt

@ -4,7 +4,7 @@ COMPILE_DEFINITIONS
Preprocessor definitions for compiling a directory's sources.
This property specifies the list of options given so far to the
:command:`add_definitions` command.
:command:`add_compile_definitions` (or :command:`add_definitions`) command.
The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated
list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``.

@ -0,0 +1,7 @@
TESTS
-----
List of tests.
This read-only property holds a :ref:`;-list <CMake Language Lists>` of tests
defined so far by the :command:`add_test` command.

@ -17,7 +17,7 @@ pairs. Each such pair will be transformed into an entry in the
solution global section. Whitespace around key and value is ignored.
List elements which do not contain an equal sign are skipped.
This property only works for Visual Studio 8 and above; it is ignored
This property only works for Visual Studio 9 and above; it is ignored
on other generators. The property only applies when set on a
directory whose CMakeLists.txt contains a project() command.

@ -17,6 +17,6 @@ pairs. Each such pair will be transformed into an entry in the
solution global section. Whitespace around key and value is ignored.
List elements which do not contain an equal sign are skipped.
This property only works for Visual Studio 8 and above; it is ignored
This property only works for Visual Studio 9 and above; it is ignored
on other generators. The property only applies when set on a
directory whose CMakeLists.txt contains a project() command.

@ -26,6 +26,9 @@ The features known to this version of CMake are:
``cxx_std_17``
Compiler mode is aware of C++ 17.
``cxx_std_20``
Compiler mode is aware of C++ 20.
``cxx_aggregate_default_initializers``
Aggregate default initializers, as defined in N3605_.

@ -0,0 +1,12 @@
ECLIPSE_EXTRA_CPROJECT_CONTENTS
-------------------------------
Additional contents to be inserted into the generated Eclipse cproject file.
The cproject file defines the CDT specific information. Some third party IDE's
are based on Eclipse with the addition of other information specific to that IDE.
Through this property, it is possible to add this additional contents to
the generated project.
It is expected to contain valid XML.
Also see the :prop_gbl:`ECLIPSE_EXTRA_NATURES` property.

@ -6,3 +6,5 @@ List of natures to add to the generated Eclipse project file.
Eclipse projects specify language plugins by using natures. This property
should be set to the unique identifier for a nature (which looks like a Java
package name).
Also see the :prop_gbl:`ECLIPSE_EXTRA_CPROJECT_CONTENTS` property.

@ -0,0 +1,6 @@
VS_SHADER_OBJECT_FILE_NAME
--------------------------
Specifies a file name for the compiled shader object file for an ``.hlsl``
source file. This adds the ``-Fo`` flag to the command line for the FxCompiler
tool.

@ -2,6 +2,7 @@ PROCESSORS
----------
Set to specify how many process slots this test requires.
If not set, the default is ``1`` processor.
Denotes the number of processors that this test will require. This is
typically used for MPI tests, and should be used in conjunction with
@ -11,3 +12,5 @@ This will also be used to display a weighted test timing result in label and
subproject summaries in the command line output of :manual:`ctest(1)`. The wall
clock time for the test run will be multiplied by this property to give a
better idea of how much cpu resource CTest allocated for the test.
See also the :prop_test:`PROCESSOR_AFFINITY` test property.

@ -0,0 +1,11 @@
PROCESSOR_AFFINITY
------------------
Set to a true value to ask CTest to launch the test process with CPU affinity
for a fixed set of processors. If enabled and supported for the current
platform, CTest will choose a set of processors to place in the CPU affinity
mask when launching the test process. The number of processors in the set is
determined by the :prop_test:`PROCESSORS` test property or the number of
processors available to CTest, whichever is smaller. The set of processors
chosen will be disjoint from the processors assigned to other concurrently
running tests that also have the ``PROCESSOR_AFFINITY`` property enabled.

@ -3,5 +3,7 @@ WORKING_DIRECTORY
The directory from which the test executable will be called.
If this is not set it is called from the directory the test executable
is located in.
If this is not set, the test will be run with the working directory set to the
binary directory associated with where the test was created (i.e. the
:variable:`CMAKE_CURRENT_BINARY_DIR` for where :command:`add_test` was
called).

@ -25,8 +25,8 @@ with Qt.
Example
^^^^^^^
In this case the the ``Q_OBJECT`` macro is hidden inside an other macro
called ``CUSTOM_MACRO``. To let CMake know that source files, that contain
``CUSTOM_MACRO``, need to be ``moc`` processed, we call::
In this case the ``Q_OBJECT`` macro is hidden inside another macro
called ``CUSTOM_MACRO``. To let CMake know that source files that contain
``CUSTOM_MACRO`` need to be ``moc`` processed, we call::
set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")

@ -0,0 +1,22 @@
COMMON_LANGUAGE_RUNTIME
-----------------------
By setting this target property, the target is configured to build with
``C++/CLI`` support.
The Visual Studio generator defines the ``clr`` parameter depending on
the value of ``COMMON_LANGUAGE_RUNTIME``:
* property not set: native C++ (i.e. default)
* property set but empty: mixed unmanaged/managed C++
* property set to any non empty value: managed C++
Supported values: ``""``, ``"pure"``, ``"safe"``
This property is only evaluated :ref:`Visual Studio Generators` for
VS 2010 and above.
To be able to build managed C++ targets with VS 2017 and above the component
``C++/CLI support`` must be installed, which may not be done by default.
See also :prop_tgt:`IMPORTED_COMMON_LANGUAGE_RUNTIME`

@ -9,7 +9,7 @@ flag such as ``-std=gnu++11`` to the compile line. For compilers that
have no notion of a standard level, such as Microsoft Visual C++ before
2015 Update 3, this has no effect.
Supported values are ``98``, ``11``, ``14``, and ``17``.
Supported values are ``98``, ``11``, ``14``, ``17``, and ``20``.
If the value requested does not result in a compile flag being added for
the compiler in use, a previous standard flag will be added instead. This

@ -3,8 +3,8 @@ DEPLOYMENT_REMOTE_DIRECTORY
Set the WinCE project ``RemoteDirectory`` in ``DeploymentTool`` and
``RemoteExecutable`` in ``DebuggerTool`` in ``.vcproj`` files generated
by the :generator:`Visual Studio 9 2008` and :generator:`Visual Studio 8 2005`
generators. This is useful when you want to debug on remote WinCE device.
by the :generator:`Visual Studio 9 2008` generator.
This is useful when you want to debug on remote WinCE device.
For example:
.. code-block:: cmake

@ -0,0 +1,13 @@
DOTNET_TARGET_FRAMEWORK_VERSION
-------------------------------
Specify the .NET target framework version.
Used to specify the .NET target framework version for C++/CLI. For
example, "v4.5".
This property is only evaluated for :ref:`Visual Studio Generators`
VS 2010 and above.
Can be initialized for all targets using the variable
:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`.

@ -0,0 +1,14 @@
EXPORT_PROPERTIES
-----------------
List additional properties to export for a target.
This property contains a list of property names that should be exported by
the :command:`install(EXPORT)` and :command:`export` commands. By default
only a limited number of properties are exported. This property can be used
to additionally export other properties as well.
Properties starting with ``INTERFACE_`` or ``IMPORTED_`` are not allowed as
they are reserved for internal CMake use.
Properties containing generator expressions are also not allowed.

@ -8,3 +8,6 @@ IDEs like Visual Studio. Targets with the same FOLDER property value
will appear next to each other in a folder of that name. To nest
folders, use FOLDER values such as 'GUI/Dialogs' with '/' characters
separating folder levels.
This property is initialized by the value of the variable
:variable:`CMAKE_FOLDER` if it is set when a target is created.

@ -0,0 +1,8 @@
IMPORTED_COMMON_LANGUAGE_RUNTIME
--------------------------------
Property to define if the target uses ``C++/CLI``.
Ignored for non-imported targets.
See also the :prop_tgt:`COMMON_LANGUAGE_RUNTIME` target property.

@ -6,3 +6,7 @@ Mac OSX directory name for installed targets.
INSTALL_NAME_DIR is a string specifying the directory portion of the
"install_name" field of shared libraries on Mac OSX to use in the
installed targets.
This property is initialized by the value of the variable
:variable:`CMAKE_INSTALL_NAME_DIR` if it is set when a target is
created.

@ -5,8 +5,14 @@ Output directory for the MS debug symbols ``.pdb`` file
generated by the linker for an executable or shared library target.
This property specifies the directory into which the MS debug symbols
will be placed by the linker. This property is initialized by the
value of the :variable:`CMAKE_PDB_OUTPUT_DIRECTORY` variable if it is
will be placed by the linker. The property value may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
Multi-configuration generators append a per-configuration
subdirectory to the specified directory unless a generator expression
is used.
This property is initialized by the value of the
:variable:`CMAKE_PDB_OUTPUT_DIRECTORY` variable if it is
set when a target is created.
.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY`

@ -11,5 +11,8 @@ property is initialized by the value of the
:variable:`CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable if it is
set when a target is created.
Contents of ``PDB_OUTPUT_DIRECTORY_<CONFIG>`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>`
.. include:: PDB_NOTE.txt

@ -5,5 +5,5 @@ The type of the target.
This read-only property can be used to test the type of the given
target. It will be one of STATIC_LIBRARY, MODULE_LIBRARY,
SHARED_LIBRARY, INTERFACE_LIBRARY, EXECUTABLE or one of the internal
target types.
SHARED_LIBRARY, OBJECT_LIBRARY, INTERFACE_LIBRARY, EXECUTABLE or one
of the internal target types.

@ -0,0 +1,9 @@
VS_DEBUGGER_COMMAND
-------------------
Sets the local debugger command for Visual Studio C++ targets.
This is defined in ``<LocalDebuggerCommand>`` in the Visual Studio
project file.
This property only works for Visual Studio 2010 and above;
it is ignored on other generators.

@ -4,3 +4,6 @@ VS_DEBUGGER_WORKING_DIRECTORY
Sets the local debugger working directory for Visual Studio C++ targets.
This is defined in ``<LocalDebuggerWorkingDirectory>`` in the Visual Studio
project file.
This property only works for Visual Studio 2010 and above;
it is ignored on other generators.

@ -5,3 +5,6 @@ Specify the .NET target framework version.
Used to specify the .NET target framework version for C++/CLI. For
example, "v4.5".
This property is deprecated and should not be used anymore. Use
:prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` instead.

@ -224,7 +224,7 @@ Modules
option to change the ``boost`` prefix on library names.
* The :module:`FindBoost` module learned to control search
for libraies with the ``g`` tag (for MS debug runtime) with
for libraries with the ``g`` tag (for MS debug runtime) with
a new ``Boost_USE_DEBUG_RUNTIME`` option. It is ``ON`` by
default to preserve existing behavior.

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

Loading…
Cancel
Save