kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

CMake origin/3.3.0 merged.

This commit is contained in:
Kolan Sh 2015-07-27 20:56:55 +03:00
parent 544402648f 3a0db0223b
commit 44eeae2c55
1586 changed files with 28908 additions and 14216 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
Auxiliary/bash-completion/cmake
View File

@ -3,7 +3,14 @@
_cmake()
{
local cur prev words cword split=false
_init_completion -n := || return
if type -t _init_completion >/dev/null; then
_init_completion -n = || return
else
# manual initialization for older bash completion versions
COMPREPLY=()
cur="${COMP_WORDS[COMP_CWORD]}"
prev="${COMP_WORDS[COMP_CWORD-1]}"
fi
# Workaround for options like -DCMAKE_BUILD_TYPE=Release
local prefix=

9
Auxiliary/bash-completion/cpack
View File

@ -3,7 +3,14 @@
_cpack()
{
local cur prev words cword
_init_completion -n = || return
if type -t _init_completion >/dev/null; then
_init_completion -n = || return
else
# manual initialization for older bash completion versions
COMPREPLY=()
cur="${COMP_WORDS[COMP_CWORD]}"
prev="${COMP_WORDS[COMP_CWORD-1]}"
fi
case "$prev" in
-G)

9
Auxiliary/bash-completion/ctest
View File

@ -3,7 +3,14 @@
_ctest()
{
local cur prev words cword
_init_completion -n = || return
if type -t _init_completion >/dev/null; then
_init_completion -n = || return
else
# manual initialization for older bash completion versions
COMPREPLY=()
cur="${COMP_WORDS[COMP_CWORD]}"
prev="${COMP_WORDS[COMP_CWORD-1]}"
fi
case "$prev" in
-C|--build-config)

34
CMakeCPackOptions.cmake.in
View File

@ -38,6 +38,10 @@ if(CPACK_GENERATOR MATCHES "IFW")
@_CPACK_IFW_PACKAGE_ICON@
set(CPACK_IFW_PACKAGE_WINDOW_ICON
"@CMake_SOURCE_DIR@/Source/QtDialog/CMakeSetup128.png")
set(CPACK_IFW_PACKAGE_CONTROL_SCRIPT
"@CMake_SOURCE_DIR@/Source/QtIFW/controlscript.qs")
# Uninstaller configuration
set(CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME "cmake-maintenance")
# Package configuration group
set(CPACK_IFW_PACKAGE_GROUP CMake)
# Group configuration
@ -87,4 +91,34 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX")
if(patch MATCHES "^[0-9]+$" AND patch LESS 65535)
set(CPACK_PACKAGE_VERSION "${CPACK_PACKAGE_VERSION}.${patch}")
endif()
set(CPACK_WIX_PROPERTY_ARPURLINFOABOUT "http://www.cmake.org")
set(CPACK_WIX_PROPERTY_ARPCONTACT "@CPACK_PACKAGE_CONTACT@")
set(CPACK_WIX_PROPERTY_ARPCOMMENTS
"CMake is a cross-platform, open-source build system."
)
set(CPACK_WIX_PRODUCT_ICON
"@CMake_SOURCE_DIR@/Utilities/Release/CMakeLogo.ico"
)
set_property(INSTALL "@CMAKE_DOC_DIR@/html/index.html" PROPERTY
CPACK_START_MENU_SHORTCUTS "CMake Documentation"
)
set_property(INSTALL "cmake.org.html" PROPERTY
CPACK_START_MENU_SHORTCUTS "CMake Web Site"
)
set(CPACK_WIX_LIGHT_EXTRA_FLAGS "-dcl:high")
set(CPACK_WIX_UI_BANNER
"@CMake_SOURCE_DIR@/Utilities/Release/cpack_wix_ui_banner.jpg"
)
set(CPACK_WIX_UI_DIALOG
"@CMake_SOURCE_DIR@/Utilities/Release/cpack_wix_ui_dialog.jpg"
)
endif()

19
CMakeLists.txt
View File

@ -37,11 +37,19 @@ if("${CMake_SOURCE_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}")
endif()
# Use most-recent available language dialects with GNU and Clang
if(NOT DEFINED CMAKE_C_STANDARD)
if(NOT DEFINED CMAKE_C_STANDARD AND NOT CMake_NO_C_STANDARD)
set(CMAKE_C_STANDARD 11)
endif()
if(NOT DEFINED CMAKE_CXX_STANDARD)
set(CMAKE_CXX_STANDARD 14)
if(NOT DEFINED CMAKE_CXX_STANDARD AND NOT CMake_NO_CXX_STANDARD)
include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx14_cstdio.cmake)
if(NOT CMake_CXX14_CSTDIO_BROKEN)
set(CMAKE_CXX_STANDARD 14)
else()
set(CMAKE_CXX_STANDARD 11)
endif()
endif()
if(NOT CMake_TEST_EXTERNAL_CMAKE)
include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx11_unordered_map.cmake)
endif()
# option to set the internal encoding of CMake to UTF-8
@ -543,10 +551,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
"${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}.${CMake_VERSION_PATCH}")
set(CMAKE_BUNDLE_LOCATION "${CMAKE_INSTALL_PREFIX}")
# make sure CMAKE_INSTALL_PREFIX ends in /
string(LENGTH "${CMAKE_INSTALL_PREFIX}" LEN)
math(EXPR LEN "${LEN} -1" )
string(SUBSTRING "${CMAKE_INSTALL_PREFIX}" ${LEN} 1 ENDCH)
if(NOT "${ENDCH}" STREQUAL "/")
if(NOT CMAKE_INSTALL_PREFIX MATCHES "/$")
set(CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}/")
endif()
set(CMAKE_INSTALL_PREFIX

18
CTestCustom.cmake.in
View File

@ -33,8 +33,11 @@ set(CTEST_CUSTOM_WARNING_EXCEPTION
"warning .980: wrong number of actual arguments to intrinsic function .std::basic_"
"LINK : warning LNK4089: all references to.*ADVAPI32.dll.*discarded by /OPT:REF"
"LINK : warning LNK4089: all references to.*PSAPI.DLL.*discarded by /OPT:REF"
"LINK : warning LNK4089: all references to.*RPCRT4.dll.*discarded by /OPT:REF"
"LINK : warning LNK4089: all references to.*SHELL32.dll.*discarded by /OPT:REF"
"LINK : warning LNK4089: all references to.*USER32.dll.*discarded by /OPT:REF"
"LINK : warning LNK4089: all references to.*ole32.dll.*discarded by /OPT:REF"
"Warning.*: .*/Utilities/KWIML/test/test_INT_format.h.* # Redundant preprocessing concatenation"
"Warning: library was too large for page size.*"
"Warning: public.*_archive_.*in module.*archive_*clashes with prior module.*archive_.*"
"Warning: public.*BZ2_bz.*in module.*bzlib.*clashes with prior module.*bzlib.*"
@ -53,6 +56,9 @@ set(CTEST_CUSTOM_WARNING_EXCEPTION
"CMakeSetupManifest.xml.*manifest authoring warning.*Unrecognized Element"
"cc-3968 CC: WARNING File.*" # "implicit" truncation by static_cast
"ld: warning: directory not found for option .-(F|L)"
"ld: warning .*/libgcc.a archive's cputype"
"ld: warning: ignoring file .*/libgcc.a, file was built for archive which is not the architecture being linked"
"ld: warning: in .*/libgcc.a, file is not of required architecture"
"warning.*This version of Mac OS X is unsupported"
"clang.*: warning: argument unused during compilation: .-g"
"note: in expansion of macro" # diagnostic context note
@ -62,6 +68,18 @@ set(CTEST_CUSTOM_WARNING_EXCEPTION
# Ignore clang's summary warning, assuming prior text has matched some
# other warning expression:
"[0-9,]+ warnings? generated."
# scanbuild exceptions
"char_traits.h:.*: warning: Null pointer argument in call to string length function"
"stl_construct.h:.*: warning: Forming reference to null pointer"
".*stl_uninitialized.h:75:19: warning: Forming reference to null pointer.*"
".*stl_vector.h:.*: warning: Returning null reference.*"
"warning: Value stored to 'yymsg' is never read"
"warning: Value stored to 'yytoken' is never read"
"index_encoder.c.241.2. warning: Value stored to .out_start. is never read"
"index.c.*warning: Access to field.*results in a dereference of a null pointer.*loaded from variable.*"
"cm_sha2.*warning: Value stored to.*is never read"
"testProcess.*warning: Dereference of null pointer .loaded from variable .invalidAddress.."
)
if(NOT "@CMAKE_GENERATOR@" MATCHES "Xcode")

4
Help/command/FIND_XXX.txt
View File

@ -53,6 +53,10 @@ If NO_DEFAULT_PATH is not specified, the search process is as follows:
.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
<prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_PREFIX_PATH
.. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace::
<prefix>/|XXX_SUBDIR| for each <prefix>/[s]bin in PATH, and
<entry>/|XXX_SUBDIR| for other entries in PATH
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
<prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH

3
Help/command/add_custom_command.rst
View File

@ -79,6 +79,9 @@ The options are:
If ``COMMAND`` specifies an executable target (created by the
:command:`add_executable` command) it will automatically be replaced
by the location of the executable created at build time.
(Use the ``TARGET_FILE``
:manual:`generator expression <cmake-generator-expressions(7)>` to
reference an executable later in the command line.)
Additionally a target-level dependency will be added so that the
executable target will be built before any target using this custom
command. However this does NOT add a file-level dependency that

22
Help/command/add_dependencies.rst
View File

@ -7,13 +7,17 @@ Add a dependency between top-level targets.
add_dependencies(<target> [<target-dependency>]...)
Make a top-level <target> depend on other top-level targets to ensure
that they build before <target> does. A top-level target is one
created by ADD_EXECUTABLE, ADD_LIBRARY, or ADD_CUSTOM_TARGET.
Dependencies added to an IMPORTED target are followed transitively in
its place since the target itself does not build.
Make a top-level ``<target>`` depend on other top-level targets to
ensure that they build before ``<target>`` does. A top-level target
is one created by one of the :command:`add_executable`,
:command:`add_library`, or :command:`add_custom_target` commands
(but not targets generated by CMake like ``install``).
See the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND for
adding file-level dependencies in custom rules. See the
OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES to add file-level
dependencies to object files.
Dependencies added to an :ref:`imported target <Imported Targets>`
or an :ref:`interface library <Interface Libraries>` are followed
transitively in its place since the target itself does not build.
See the ``DEPENDS`` option of :command:`add_custom_target` and
:command:`add_custom_command` commands for adding file-level
dependencies in custom rules. See the :prop_sf:`OBJECT_DEPENDS`
source file property to add file-level dependencies to object files.

5
Help/command/build_command.rst
View File

@ -19,7 +19,8 @@ Sets the given ``<variable>`` to a command-line string of the form::
where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line
tool, and ``<config>`` and ``<target>`` are the values provided to the
``CONFIGURATION`` and ``TARGET`` options, if any. The trailing ``-- -i``
option is added for Makefile generators.
option is added for :ref:`Makefile Generators` if policy :policy:`CMP0061`
is not set to ``NEW``.
When invoked, this ``cmake --build`` command line will launch the
underlying build system tool.
@ -32,7 +33,7 @@ This second signature is deprecated, but still available for backwards
compatibility. Use the first signature instead.
It sets the given ``<cachevariable>`` to a command-line string as
above but without the ``--config`` or ``--target`` options.
above but without the ``--target`` option.
The ``<makecommand>`` is ignored but should be the full path to
msdev, devenv, nmake, make or one of the end user build tools
for legacy invocations.

11
Help/command/cmake_minimum_required.rst
View File

@ -28,3 +28,14 @@ which enables compatibility features for CMake 2.4 and lower.
The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
higher. It should be specified so CMake versions 2.4 and lower fail
with an error instead of just a warning.
.. note::
Call the ``cmake_minimum_required()`` command at the beginning of
the top-level ``CMakeLists.txt`` file even before calling the
:command:`project` command. It is important to establish version
and policy settings before invoking other commands whose behavior
they may affect. See also policy :policy:`CMP0000`.
Calling ``cmake_minimum_required()`` inside a :command:`function`
limits some effects to the function scope when invoked. Such calls
should not be made with the intention of having global effects.

2
Help/command/cmake_policy.rst
View File

@ -53,6 +53,8 @@ policy warning by setting the policy state to ``OLD``. Alternatively
one may fix the project to work with the new behavior and set the
policy state to ``NEW``.
.. include:: ../policy/DEPRECATED.txt
Checking Policy Settings
^^^^^^^^^^^^^^^^^^^^^^^^

80
Help/command/ctest_build.rst
View File

@ -1,29 +1,73 @@
ctest_build
-----------
Build the project.
Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
::
ctest_build([BUILD build_dir] [TARGET target] [RETURN_VALUE res]
[APPEND][NUMBER_ERRORS val] [NUMBER_WARNINGS val])
ctest_build([BUILD <build-dir>] [APPEND]
[CONFIGURATION <config>]
[FLAGS <flags>]
[PROJECT_NAME <project-name>]
[TARGET <target-name>]
[NUMBER_ERRORS <num-err-var>]
[NUMBER_WARNINGS <num-warn-var>]
[RETURN_VALUE <result-var>]
)
Builds the given build directory and stores results in Build.xml. If
no BUILD is given, the CTEST_BINARY_DIRECTORY variable is used.
Build the project and store results in ``Build.xml``
for submission with the :command:`ctest_submit` command.
The TARGET variable can be used to specify a build target. If none is
specified, the "all" target will be built.
The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly
specify the build command line. Otherwise the build command line is
computed automatically based on the options given.
The RETURN_VALUE option specifies a variable in which to store the
return value of the native build tool. The NUMBER_ERRORS and
NUMBER_WARNINGS options specify variables in which to store the number
of build errors and warnings detected.
The options are:
The APPEND option marks results for append to those previously
submitted to a dashboard server since the last ctest_start. Append
semantics are defined by the dashboard server in use.
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
If set, the contents of the variable CTEST_BUILD_FLAGS are passed as
additional arguments to the underlying build command. This can e.g. be
used to trigger a parallel build using the -j option of make. See
:module:`ProcessorCount` for an example.
``APPEND``
Mark results for append to those previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
``CONFIGURATION <config>``
Specify the build configuration (e.g. ``Debug``). If not
specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)`
command will be used, if any.
``FLAGS <flags>``
Pass additional arguments to the underlying build command.
If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
This can, e.g., be used to trigger a parallel build using the
``-j`` option of make. See the :module:`ProcessorCount` module
for an example.
``PROJECT_NAME <project-name>``
Set the name of the project to build. This should correspond
to the top-level call to the :command:`project` command.
If not specified the ``CTEST_PROJECT_NAME`` variable will be checked.
``TARGET <target-name>``
Specify the name of a target to build. If not specified the
``CTEST_BUILD_TARGET`` variable will be checked. Otherwise the
default target will be built. This is the "all" target
(called ``ALL_BUILD`` in :ref:`Visual Studio Generators`).
``NUMBER_ERRORS <num-err-var>``
Store the number of build errors detected in the given variable.
``NUMBER_WARNINGS <num-warn-var>``
Store the number of build warnings detected in the given variable.
``RETURN_VALUE <result-var>``
Store the return value of the native build tool in the given variable.
``QUIET``
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise. The summary of warnings / errors,
as well as the output from the native build tool is unaffected by
this option.

44
Help/command/ctest_configure.rst
View File

@ -1,21 +1,39 @@
ctest_configure
---------------
Configure the project build tree.
Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`.
::
ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND]
[OPTIONS options] [RETURN_VALUE res])
ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
[OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET])
Configures the given build directory and stores results in
Configure.xml. If no BUILD is given, the CTEST_BINARY_DIRECTORY
variable is used. If no SOURCE is given, the CTEST_SOURCE_DIRECTORY
variable is used. The OPTIONS argument specifies command line
arguments to pass to the configuration tool. The RETURN_VALUE option
specifies a variable in which to store the return value of the native
build tool.
Configure the project build tree and record results in ``Configure.xml``
for submission with the :command:`ctest_submit` command.
The APPEND option marks results for append to those previously
submitted to a dashboard server since the last ctest_start. Append
semantics are defined by the dashboard server in use.
The options are:
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
``SOURCE <source-dir>``
Specify the source directory. If not given, the
:variable:`CTEST_SOURCE_DIRECTORY` variable is used.
``APPEND``
Mark results for append to those previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
``OPTIONS <options>``
Specify command-line arguments to pass to the configuration tool.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable the return value of the native
configuration tool.
``QUIET``
Suppress any CTest-specific non-error messages that would have
otherwise been printed to the console. Output from the underlying
configure command is not affected.

41
Help/command/ctest_coverage.rst
View File

@ -1,20 +1,39 @@
ctest_coverage
--------------
Collect coverage tool results.
Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
::
ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND]
[LABELS label1 [label2 [...]]])
ctest_coverage([BUILD <build-dir>] [APPEND]
[LABELS <label>...]
[RETURN_VALUE <result-var>]
[QUIET]
)
Perform the coverage of the given build directory and stores results
in Coverage.xml. The second argument is a variable that will hold
value.
Collect coverage tool results and stores them in ``Coverage.xml``
for submission with the :command:`ctest_submit` command.
The LABELS option filters the coverage report to include only source
files labeled with at least one of the labels specified.
The options are:
The APPEND option marks results for append to those previously
submitted to a dashboard server since the last ctest_start. Append
semantics are defined by the dashboard server in use.
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
``APPEND``
Mark results for append to those previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
``LABELS``
Filter the coverage report to include only source files labeled
with at least one of the labels specified.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` if coverage tools
ran without error and non-zero otherwise.
``QUIET``
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise. The summary indicating how many
lines of code were covered is unaffected by this option.

40
Help/command/ctest_memcheck.rst
View File

@ -1,28 +1,28 @@
ctest_memcheck
--------------
Run tests with a dynamic analysis tool.
Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.
::
ctest_memcheck([BUILD build_dir] [RETURN_VALUE res] [APPEND]
[START start number] [END end number]
[STRIDE stride number] [EXCLUDE exclude regex ]
[INCLUDE include regex]
[EXCLUDE_LABEL exclude regex]
[INCLUDE_LABEL label regex]
[PARALLEL_LEVEL level] )
ctest_memcheck([BUILD <build-dir>] [APPEND]
[START <start-number>]
[END <end-number>]
[STRIDE <stride-number>]
[EXCLUDE <exclude-regex>]
[INCLUDE <include-regex>]
[EXCLUDE_LABEL <label-exclude-regex>]
[INCLUDE_LABEL <label-include-regex>]
[PARALLEL_LEVEL <level>]
[SCHEDULE_RANDOM <ON|OFF>]
[STOP_TIME <time-of-day>]
[RETURN_VALUE <result-var>]
[QUIET]
)
Tests the given build directory and stores results in MemCheck.xml.
The second argument is a variable that will hold value. Optionally,
you can specify the starting test number START, the ending test number
END, the number of tests to skip between each test STRIDE, a regular
expression for tests to run INCLUDE, or a regular expression for tests
not to run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular
expressions for tests to be included or excluded by the test property
LABEL. PARALLEL_LEVEL should be set to a positive number representing
the number of tests to be run in parallel.
The APPEND option marks results for append to those previously
submitted to a dashboard server since the last ctest_start. Append
semantics are defined by the dashboard server in use.
Run tests with a dynamic analysis tool and store results in
``MemCheck.xml`` for submission with the :command:`ctest_submit`
command.
The options are the same as those for the :command:`ctest_test` command.

5
Help/command/ctest_start.rst
View File

@ -5,7 +5,7 @@ Starts the testing for a given model
::
ctest_start(Model [TRACK <track>] [APPEND] [source [binary]])
ctest_start(Model [TRACK <track>] [APPEND] [source [binary]] [QUIET])
Starts the testing for a given model. The command should be called
after the binary directory is initialized. If the 'source' and
@ -14,7 +14,8 @@ after the binary directory is initialized. If the 'source' and
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.
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)

65
Help/command/ctest_submit.rst
View File

@ -1,42 +1,55 @@
ctest_submit
------------
Submit results to a dashboard server.
Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
::
ctest_submit([PARTS ...] [FILES ...]
[RETRY_COUNT count]
[RETRY_DELAY delay]
[RETURN_VALUE res]
ctest_submit([PARTS <part>...] [FILES <file>...]
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
[RETURN_VALUE <result-var>]
[QUIET]
)
By default all available parts are submitted if no PARTS or FILES are
specified. The PARTS option lists a subset of parts to be submitted.
Valid part names are:
Submit results to a dashboard server.
By default all available parts are submitted.
::
The options are:
Start = nothing
Update = ctest_update results, in Update.xml
Configure = ctest_configure results, in Configure.xml
Build = ctest_build results, in Build.xml
Test = ctest_test results, in Test.xml
Coverage = ctest_coverage results, in Coverage.xml
MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
Upload = Files prepared for upload by ctest_upload(), in Upload.xml
Submit = nothing
``PARTS <part>...``
Specify a subset of parts to submit. Valid part names are::
The FILES option explicitly lists specific files to be submitted.
Each individual file must exist at the time of the call.
Start = nothing
Update = ctest_update results, in Update.xml
Configure = ctest_configure results, in Configure.xml
Build = ctest_build results, in Build.xml
Test = ctest_test results, in Test.xml
Coverage = ctest_coverage results, in Coverage.xml
MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
Upload = Files prepared for upload by ctest_upload(), in Upload.xml
Submit = nothing
The RETRY_DELAY option specifies how long in seconds to wait after a
timed-out submission before attempting to re-submit.
``FILES <file>...``
Specify an explicit list of specific files to be submitted.
Each individual file must exist at the time of the call.
The RETRY_COUNT option specifies how many times to retry a timed-out
submission.
``RETRY_COUNT <count>``
Specify how many times to retry a timed-out submission.
``RETRY_DELAY <delay>``
Specify how long (in seconds) to wait after a timed-out submission
before attempting to re-submit.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` for success and
non-zero on failure.
``QUIET``
Suppress all non-error messages that would have otherwise been
printed to the console.
Submit to CDash Upload API
^^^^^^^^^^^^^^^^^^^^^^^^^^

96
Help/command/ctest_test.rst
View File

@ -1,33 +1,79 @@
ctest_test
----------
Run tests in the project build tree.
Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
::
ctest_test([BUILD build_dir] [APPEND]
[START start number] [END end number]
[STRIDE stride number] [EXCLUDE exclude regex ]
[INCLUDE include regex] [RETURN_VALUE res]
[EXCLUDE_LABEL exclude regex]
[INCLUDE_LABEL label regex]
[PARALLEL_LEVEL level]
[SCHEDULE_RANDOM on]
[STOP_TIME time of day])
ctest_test([BUILD <build-dir>] [APPEND]
[START <start-number>]
[END <end-number>]
[STRIDE <stride-number>]
[EXCLUDE <exclude-regex>]
[INCLUDE <include-regex>]
[EXCLUDE_LABEL <label-exclude-regex>]
[INCLUDE_LABEL <label-include-regex>]
[PARALLEL_LEVEL <level>]
[SCHEDULE_RANDOM <ON|OFF>]
[STOP_TIME <time-of-day>]
[RETURN_VALUE <result-var>]
[QUIET]
)
Tests the given build directory and stores results in Test.xml. The
second argument is a variable that will hold value. Optionally, you
can specify the starting test number START, the ending test number
END, the number of tests to skip between each test STRIDE, a regular
expression for tests to run INCLUDE, or a regular expression for tests
to not run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular
expression for test to be included or excluded by the test property
LABEL. PARALLEL_LEVEL should be set to a positive number representing
the number of tests to be run in parallel. SCHEDULE_RANDOM will
launch tests in a random order, and is typically used to detect
implicit test dependencies. STOP_TIME is the time of day at which the
tests should all stop running.
Run tests in the project build tree and store results in
``Test.xml`` for submission with the :command:`ctest_submit` command.
The APPEND option marks results for append to those previously
submitted to a dashboard server since the last ctest_start. Append
semantics are defined by the dashboard server in use.
The options are:
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
``APPEND``
Mark results for append to those previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
``START <start-number>``
Specify the beginning of a range of test numbers.
``END <end-number>``
Specify the end of a range of test numbers.
``STRIDE <stride-number>``
Specify the stride by which to step acorss a range of test numbers.
``EXCLUDE <exclude-regex>``
Specify a regular expression matching test names to exclude.
``INCLUDE <include-regex>``
Specify a regular expression matching test names to include.
Tests not matching this expression are excluded.
``EXCLUDE_LABEL <label-exclude-regex>``
Specify a regular expression matching test labels to exclude.
``INCLUDE_LABEL <label-include-regex>``
Specify a regular expression matching test labels to include.
Tests not matching this expression are excluded.
``PARALLEL_LEVEL <level>``
Specify a positive number representing the number of tests to
be run in parallel.
``SCHEDULE_RANDOM <ON|OFF>``
Launch tests in a random order. This may be useful for detecting
implicit test dependencies.
``STOP_TIME <time-of-day>``
Specify a time of day at which the tests should all stop running.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` if all tests passed.
Store non-zero if anything went wrong.
``QUIET``
Suppress any CTest-specific non-error messages that would have otherwise
been printed to the console. Output from the underlying test command is not
affected. Summary info detailing the percentage of passing tests is also
unaffected by the ``QUIET`` option.

26
Help/command/ctest_update.rst
View File

@ -1,13 +1,27 @@
ctest_update
------------
Update the work tree from version control.
Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.
::
ctest_update([SOURCE source] [RETURN_VALUE res])
ctest_update([SOURCE <source-dir>] [RETURN_VALUE <result-var>] [QUIET])
Updates the given source directory and stores results in Update.xml.
If no SOURCE is given, the CTEST_SOURCE_DIRECTORY variable is used.
The RETURN_VALUE option specifies a variable in which to store the
result, which is the number of files updated or -1 on error.
Update the source tree from version control and record results in
``Update.xml`` for submission with the :command:`ctest_submit` command.
The options are:
``SOURCE <source-dir>``
Specify the source directory. If not given, the
:variable:`CTEST_SOURCE_DIRECTORY` variable is used.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable the number of files
updated or ``-1`` on error.
``QUIET``
Tell CTest to suppress most non-error messages that it would
have otherwise printed to the console. CTest will still report
the new revision of the repository and any conflicting files
that were found.

15
Help/command/ctest_upload.rst
View File

@ -1,11 +1,18 @@
ctest_upload
------------
Upload files to a dashboard server.
Upload files to a dashboard server as a :ref:`Dashboard Client`.
::
ctest_upload(FILES ...)
ctest_upload(FILES <file>... [QUIET])
Pass a list of files to be sent along with the build results to the
dashboard server.
The options are:
``FILES <file>...``
Specify a list of files to be sent along with the build results to the
dashboard server.
``QUIET``
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise.

3
Help/command/execute_process.rst
View File

@ -57,7 +57,8 @@ OUTPUT_VARIABLE, ERROR_VARIABLE
INPUT_FILE, OUTPUT_FILE, ERROR_FILE
The file named will be attached to the standard input of the first
process, standard output of the last process, or standard error of
all processes, respectively.
all processes, respectively. If the same file is named for both
output and error then it will be used for both.
OUTPUT_QUIET, ERROR_QUIET
The standard output or standard error results will be quietly ignored.

23
Help/command/file.rst
View File

@ -92,9 +92,12 @@ store it in a ``<variable>``.
::
file(GLOB <variable> [RELATIVE <path>] [<globbing-expressions>...])
file(GLOB_RECURSE <variable> [RELATIVE <path>]
[FOLLOW_SYMLINKS] [<globbing-expressions>...])
file(GLOB <variable>
[LIST_DIRECTORIES true|false] [RELATIVE <path>]
[<globbing-expressions>...])
file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
[LIST_DIRECTORIES true|false] [RELATIVE <path>]
[<globbing-expressions>...])
Generate a list of files that match the ``<globbing-expressions>`` and
store it into the ``<variable>``. Globbing expressions are similar to
@ -102,6 +105,9 @@ regular expressions, but much simpler. If ``RELATIVE`` flag is
specified, the results will be returned as relative paths to the given
path.
By default ``GLOB`` lists directories - directories are omited in result if
``LIST_DIRECTORIES`` is set to false.
.. note::
We do not recommend using GLOB to collect a list of source files from
your source tree. If no CMakeLists.txt file changes when a source is
@ -119,6 +125,11 @@ matched directory and match the files. Subdirectories that are symlinks
are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
:policy:`CMP0009` is not set to ``NEW``.
By default ``GLOB_RECURSE`` omits directories from result list - setting
``LIST_DIRECTORIES`` to true adds directories to result list.
If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to
``OLD`` then ``LIST_DIRECTORIES`` treats symlinks as directories.
Examples of recursive globbing include::
/dir/*.py - match all python files in /dir and subdirectories
@ -302,8 +313,12 @@ 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, ``PATTERN``, ``REGEX``, and ``EXCLUDE`` options.
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),

5
Help/command/find_file.rst
View File

@ -13,7 +13,10 @@ find_file
.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE,
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
and the directories in PATH itself.
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and

11
Help/command/find_library.rst
View File

@ -13,7 +13,10 @@ find_library
.. |CMAKE_XXX_PATH| replace:: CMAKE_LIBRARY_PATH
.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and LIB
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in LIB,
<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
and the directories in PATH itself.
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
@ -31,6 +34,12 @@ default will consider one name at a time and search every directory
for it. The NAMES_PER_DIR option tells this command to consider one
directory at a time and search for all names in it.
Each library name given to the ``NAMES`` option is first considered
as a library file name and then considered with platform-specific
prefixes (e.g. ``lib``) and suffixes (e.g. ``.so``). Therefore one
may specify library file names such as ``libfoo.a`` directly.
This can be used to locate static libraries on UNIX-like systems.
If the library found is a framework, then VAR will be set to the full
path to the framework <fullPath>/A.framework. When a full path to a
framework is used as a library, CMake will use a -framework A, and a

16
Help/command/find_package.rst
View File

@ -68,7 +68,7 @@ The complete Config mode command signature is::
[NO_CMAKE_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_PACKAGE_REGISTRY]
[NO_CMAKE_BUILDS_PATH]
[NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
[NO_CMAKE_SYSTEM_PATH]
[NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
[CMAKE_FIND_ROOT_PATH_BOTH |
@ -265,20 +265,14 @@ enabled.
PATH
5. Search project build trees recently configured in a :manual:`cmake-gui(1)`.
This can be skipped if ``NO_CMAKE_BUILDS_PATH`` is passed. It is intended
for the case when a user is building multiple dependent projects one
after another.
(This step is implemented only on Windows.)
6. Search paths stored in the CMake :ref:`User Package Registry`.
5. Search paths stored in the CMake :ref:`User Package Registry`.
This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by
setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`
to ``TRUE``.
See the :manual:`cmake-packages(7)` manual for details on the user
package registry.
7. Search cmake variables defined in the Platform files for the
6. Search cmake variables defined in the Platform files for the
current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
passed::
@ -286,14 +280,14 @@ enabled.
CMAKE_SYSTEM_FRAMEWORK_PATH
CMAKE_SYSTEM_APPBUNDLE_PATH
8. Search paths stored in the CMake :ref:`System Package Registry`.
7. Search paths stored in the CMake :ref:`System Package Registry`.
This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed
or by setting the
:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``.
See the :manual:`cmake-packages(7)` manual for details on the system
package registry.
9. Search paths specified by the ``PATHS`` option. These are typically
8. Search paths specified by the ``PATHS`` option. These are typically
hard-coded guesses.
.. |FIND_XXX| replace:: find_package

5
Help/command/find_path.rst
View File

@ -13,7 +13,10 @@ find_path
.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE,
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
and the directories in PATH itself.
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and

43
Help/command/function.rst
View File

@ -1,9 +1,7 @@
function
--------
Start recording a function for later invocation as a command.
::
Start recording a function for later invocation as a command::
function(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...)
@ -11,21 +9,28 @@ Start recording a function for later invocation as a command.
...
endfunction(<name>)
Define a function named <name> that takes arguments named arg1 arg2
arg3 (...). Commands listed after function, but before the matching
endfunction, are not invoked until the function is invoked. When it
is invoked, the commands recorded in the function are first modified
by replacing formal parameters (${arg1}) with the arguments passed,
and then invoked as normal commands. In addition to referencing the
formal parameters you can reference the variable ARGC which will be
set to the number of arguments passed into the function as well as
ARGV0 ARGV1 ARGV2 ... which will have the actual values of the
arguments passed in. This facilitates creating functions with
optional arguments. Additionally ARGV holds the list of all arguments
given to the function and ARGN holds the list of arguments past the
last expected argument.
Define a function named ``<name>`` that takes arguments named ``arg1``,
``arg2``, ``arg3``, (...).
Commands listed after function, but before the matching
:command:`endfunction()`, are not invoked until the function is invoked.
When it is invoked, the commands recorded in the function are first
modified by replacing formal parameters (``${arg1}``) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
``ARGC`` variable which will be set to the number of arguments passed
into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which
will have the actual values of the arguments passed in.
This facilitates creating functions with optional arguments.
Additionally ``ARGV`` holds the list of all arguments given to the
function and ``ARGN`` holds the list of arguments past the last expected
argument.
Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined
behavior. Checking that ``ARGC`` is greater than ``#`` is the only way
to ensure that ``ARGV#`` was passed to the function as an extra
argument.
A function opens a new scope: see set(var PARENT_SCOPE) for details.
A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for
details.
See the cmake_policy() command documentation for the behavior of
policies inside functions.
See the :command:`cmake_policy()` command documentation for the behavior
of policies inside functions.

3
Help/command/if.rst
View File

@ -134,6 +134,9 @@ Possible expressions are:
Component-wise integer version number comparison (version format is
``major[.minor[.patch[.tweak]]]``).
``if(<variable|string> IN_LIST <variable>)``
True if the given element is contained in the named list variable.
``if(DEFINED <variable>)``
True if the given variable is defined. It does not matter if the
variable is true or false just if it has been set. (Note macro

4
Help/command/install.rst
View File

@ -159,6 +159,10 @@ file itself, call ``install(EXPORT)``, documented below.
Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
set to ``TRUE`` has undefined behavior.
The install destination given to the target install ``DESTINATION`` may
use "generator expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions.
Installing Files
^^^^^^^^^^^^^^^^

43
Help/command/macro.rst
View File

@ -1,9 +1,7 @@
macro
-----
Start recording a macro for later invocation as a command.
::
Start recording a macro for later invocation as a command::
macro(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...)
@ -11,22 +9,28 @@ Start recording a macro for later invocation as a command.
...
endmacro(<name>)
Define a macro named <name> that takes arguments named arg1 arg2 arg3
(...). Commands listed after macro, but before the matching endmacro,
are not invoked until the macro is invoked. When it is invoked, the
commands recorded in the macro are first modified by replacing formal
parameters (``${arg1}``) with the arguments passed, and then invoked as
normal commands. In addition to referencing the formal parameters you
can reference the values ``${ARGC}`` which will be set to the number of
arguments passed into the function as well as ``${ARGV0}`` ``${ARGV1}``
``${ARGV2}`` ... which will have the actual values of the arguments
passed in. This facilitates creating macros with optional arguments.
Define a macro named ``<name>`` that takes arguments named ``arg1``,
``arg2``, ``arg3``, (...).
Commands listed after macro, but before the matching
:command:`endmacro()`, are not invoked until the macro is invoked.
When it is invoked, the commands recorded in the macro are first
modified by replacing formal parameters (``${arg1}``) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
values ``${ARGC}`` which will be set to the number of arguments passed
into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``,
... which will have the actual values of the arguments passed in.
This facilitates creating macros with optional arguments.
Additionally ``${ARGV}`` holds the list of all arguments given to the
macro and ``${ARGN}`` holds the list of arguments past the last expected
argument.
Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined
behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only
way to ensure that ``${ARGV#}`` was passed to the function as an extra
argument.
See the cmake_policy() command documentation for the behavior of
policies inside macros.
See the :command:`cmake_policy()` command documentation for the behavior
of policies inside macros.
Macro Argument Caveats
^^^^^^^^^^^^^^^^^^^^^^
@ -37,10 +41,15 @@ replacements much like the C preprocessor would do with a macro.
Therefore you will NOT be able to use commands like::
if(ARGV1) # ARGV1 is not a variable
if(DEFINED ARGV2) # ARGV2 is not a variable
if(ARGC GREATER 2) # ARGC is not a variable
foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
In the first case you can use ``if(${ARGV1})``, in the second case, you can
use ``foreach(loop_var ${ARGN})`` but this will skip empty arguments.
In the first case, you can use ``if(${ARGV1})``.
In the second and third case, the proper way to check if an optional
variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``.
In the last case, you can use ``foreach(loop_var ${ARGN})`` but this
will skip empty arguments.
If you need to include them, you can use::
set(list_var "${ARGN}")

7
Help/command/project.rst
View File

@ -55,3 +55,10 @@ 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``).
.. note::
Call the :command:`cmake_minimum_required` command at the beginning
of the top-level ``CMakeLists.txt`` file even before calling the
``project()`` command. It is important to establish version and
policy settings before invoking other commands whose behavior they
may affect. See also policy :policy:`CMP0000`.

169
Help/command/set.rst
View File

@ -1,116 +1,89 @@
set
---
Set a CMake, cache or environment variable to a given value.
Set a normal, cache, or environment variable to a given value.
See the :ref:`cmake-language(7) variables <CMake Language Variables>`
documentation for the scopes and interaction of normal variables
and cache entries.
Signatures of this command that specify a ``<value>...`` placeholder
expect zero or more arguments. Multiple arguments will be joined as
a :ref:`;-list <CMake Language Lists>` to form the actual variable
value to be set. Zero arguments will cause normal variables to be
unset. See the :command:`unset` command to unset variables explicitly.
Set Normal Variable
^^^^^^^^^^^^^^^^^^^
::
set(<variable> <value>
[[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
set(<variable> <value>... [PARENT_SCOPE])
Within CMake sets <variable> to the value <value>. <value> is
expanded before <variable> is set to it. Normally, set will set a
regular CMake variable. If CACHE is present, then the <variable> is
put in the cache instead, unless it is already in the cache. See
section 'Variable types in CMake' below for details of regular and
cache variables and their interactions. If CACHE is used, <type> and
<docstring> are required. <type> is used by the CMake GUI to choose a
widget with which the user sets a value. The value for <type> may be
one of
Set the given ``<variable>`` in the current function or directory scope.
If the ``PARENT_SCOPE`` option is given the variable will be set in
the scope above the current scope. Each new directory or function
creates a new scope. This command will set the value of a variable
into the parent directory or calling function (whichever is applicable
to the case at hand).
Set Cache Entry
^^^^^^^^^^^^^^^
::
FILEPATH = File chooser dialog.
PATH = Directory chooser dialog.
STRING = Arbitrary string.
BOOL = Boolean ON/OFF checkbox.
INTERNAL = No GUI entry (used for persistent variables).
set(<variable> <value>... CACHE <type> <docstring> [FORCE])
If <type> is INTERNAL, the cache variable is marked as internal, and
will not be shown to the user in tools like cmake-gui. This is
intended for values that should be persisted in the cache, but which
users should not normally change. INTERNAL implies FORCE.
Set the given cache ``<variable>`` (cache entry). Since cache entries
are meant to provide user-settable values this does not overwrite
existing cache entries by default. Use the ``FORCE`` option to
overwrite existing entries.
Normally, set(...CACHE...) creates cache variables, but does not
modify them. If FORCE is specified, the value of the cache variable
is set, even if the variable is already in the cache. This should
normally be avoided, as it will remove any changes to the cache
variable's value by the user.
The ``<type>`` must be specified as one of:
If PARENT_SCOPE is present, the variable will be set in the scope
above the current scope. Each new directory or function creates a new
scope. This command will set the value of a variable into the parent
directory or calling function (whichever is applicable to the case at
hand). PARENT_SCOPE cannot be combined with CACHE.
``BOOL``
Boolean ``ON/OFF`` value. :manual:`cmake-gui(1)` offers a checkbox.
If <value> is not specified then the variable is removed instead of
set. See also: the unset() command.
``FILEPATH``
Path to a file on disk. :manual:`cmake-gui(1)` offers a file dialog.
``PATH``
Path to a directory on disk. :manual:`cmake-gui(1)` offers a file dialog.
``STRING``
A line of text. :manual:`cmake-gui(1)` offers a text field or a
drop-down selection if the :prop_cache:`STRINGS` cache entry
property is set.
``INTERNAL``
A line of text. :manual:`cmake-gui(1)` does not show internal entries.
They may be used to store variables persistently across runs.
Use of this type implies ``FORCE``.
The ``<docstring>`` must be specified as a line of text providing
a quick summary of the option for presentation to :manual:`cmake-gui(1)`
users.
If the cache entry does not exist prior to the call or the ``FORCE``
option is given then the cache entry will be set to the given value.
Furthermore, any normal variable binding in the current scope will
be removed to expose the newly cached value to any immediately
following evaluation.
It is possible for the cache entry to exist prior to the call but
have no type set if it was created on the :manual:`cmake(1)` command
line by a user through the ``-D<var>=<value>`` option without
specifying a type. In this case the ``set`` command will add the
type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
and the ``<value>`` provided on the command line is a relative path,
then the ``set`` command will treat the path as relative to the
current working directory and convert it to an absolute path.
Set Environment Variable
^^^^^^^^^^^^^^^^^^^^^^^^
::
set(<variable> <value1> ... <valueN>)
set(ENV{<variable>} <value>...)
In this case <variable> is set to a semicolon separated list of
values.
<variable> can be an environment variable such as:
::
set( ENV{PATH} /home/martink )
in which case the environment variable will be set.
*** Variable types in CMake ***
In CMake there are two types of variables: normal variables and cache
variables. Normal variables are meant for the internal use of the
script (just like variables in most programming languages); they are
not persisted across CMake runs. Cache variables (unless set with
INTERNAL) are mostly intended for configuration settings where the
first CMake run determines a suitable default value, which the user
can then override, by editing the cache with tools such as ccmake or
cmake-gui. Cache variables are stored in the CMake cache file, and
are persisted across CMake runs.
Both types can exist at the same time with the same name but different
values. When ${FOO} is evaluated, CMake first looks for a normal
variable 'FOO' in scope and uses it if set. If and only if no normal
variable exists then it falls back to the cache variable 'FOO'.
Some examples:
The code 'set(FOO "x")' sets the normal variable 'FOO'. It does not
touch the cache, but it will hide any existing cache value 'FOO'.
The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache,
ignoring any normal variable of the same name. If 'FOO' is in the
cache then nothing happens to either the normal variable or the cache
variable. If 'FOO' is not in the cache, then it is added to the
cache.
Finally, whenever a cache variable is added or modified by a command,
CMake also *removes* the normal variable of the same name from the
current scope so that an immediately following evaluation of it will
expose the newly cached value.
Normally projects should avoid using normal and cache variables of the
same name, as this interaction can be hard to follow. However, in
some situations it can be useful. One example (used by some
projects):
A project has a subproject in its source tree. The child project has
its own CMakeLists.txt, which is included from the parent
CMakeLists.txt using add_subdirectory(). Now, if the parent and the
child project provide the same option (for example a compiler option),
the parent gets the first chance to add a user-editable option to the
cache. Normally, the child would then use the same value that the
parent uses. However, it may be necessary to hard-code the value for
the child project's option while still allowing the user to edit the
value used by the parent project. The parent project can achieve this
simply by setting a normal variable with the same name as the option
in a scope sufficient to hide the option's cache variable from the
child completely. The parent has already set the cache variable, so
the child's set(...CACHE...) will do nothing, and evaluating the
option variable will use the value from the normal variable, which
hides the cache variable.
Set the current process environment ``<variable>`` to the given value.

9
Help/command/set_directory_properties.rst
View File

@ -7,9 +7,6 @@ Set a property of the directory.
set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
Set a property for the current directory and subdirectories. If the
property is not found, CMake will report an error. The properties
include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES,
INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES.
ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be cleaned as
a part of "make clean" stage.
Set a property for the current directory and subdirectories. See
:ref:`Directory Properties` for the list of properties known
to CMake.

6
Help/command/set_source_files_properties.rst
View File

@ -10,6 +10,6 @@ Source files can have properties that affect how they are built.
[prop2 value2 [...]])
Set properties associated with source files using a key/value paired
list. See properties documentation for those known to CMake.
Unrecognized properties are ignored. Source file properties are
visible only to targets added in the same directory (CMakeLists.txt).
list. See :ref:`Source File Properties` for the list of properties known
to CMake. Source file properties are visible only to targets added
in the same directory (CMakeLists.txt).

30
Help/command/set_tests_properties.rst
View File

@ -8,29 +8,7 @@ Set a property of the tests.
set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
Set a property for the tests. If the test is not found, CMake
will report an error. Generator expressions will be expanded the same
as supported by the test's add_test call. The properties include:
WILL_FAIL: If set to true, this will invert the pass/fail flag of the
test.
PASS_REGULAR_EXPRESSION: If set, the test output will be checked
against the specified regular expressions and at least one of the
regular expressions has to match, otherwise the test will fail.
::
Example: PASS_REGULAR_EXPRESSION "TestPassed;All ok"
FAIL_REGULAR_EXPRESSION: If set, if the output will match to one of
specified regular expressions, the test will fail.
::
Example: FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
Both PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION expect a list
of regular expressions.
TIMEOUT: Setting this will limit the test runtime to the number of
seconds specified.
will report an error.
:manual:`Generator expressions <cmake-generator-expressions(7)>` will be
expanded the same as supported by the test's :command:`add_test` call. See
:ref:`Test Properties` for the list of properties known to CMake.

2
Help/command/target_compile_definitions.rst
View File

@ -9,7 +9,7 @@ Add compile definitions to a target.
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specify compile definitions to use when compiling a given <target. The
Specify compile definitions to use when compiling a given ``<target>``. The
named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
:ref:`Imported Target <Imported Targets>`.

2
Help/command/target_compile_features.rst
View File

@ -29,4 +29,4 @@ Arguments to ``target_compile_features`` may use "generator expressions"
with the syntax ``$<...>``.
See the :manual:`cmake-generator-expressions(7)` manual for available
expressions. See the :manual:`cmake-compile-features(7)` manual for
information on compile features.
information on compile features and a list of supported compilers.

4
Help/command/target_compile_options.rst
View File

@ -20,8 +20,8 @@ alternative commands exist to add preprocessor definitions
(:command:`target_compile_definitions` and :command:`add_definitions`) or
include directories (:command:`target_include_directories` and
:command:`include_directories`). See documentation of the
:prop_tgt:`directory <COMPILE_OPTIONS>` and
:prop_tgt:` target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties.
:prop_dir:`directory <COMPILE_OPTIONS>` and
:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``

3
Help/command/target_include_directories.rst
View File

@ -55,5 +55,8 @@ installation prefix. For example:
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
Creating Relocatable Packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt

215
Help/command/target_link_libraries.rst
View File

@ -1,38 +1,113 @@
target_link_libraries
---------------------
Link a target to given libraries.
.. only:: html
.. contents::
Specify libraries or flags to use when linking a given target and/or
its dependents. :ref:`Usage requirements <Target Usage Requirements>`
from linked library targets will be propagated. Usage requirements
of a target's dependencies affect compilation of its own sources.
Overview
^^^^^^^^
This command has several signatures as detailed in subsections below.
All of them have the general form::
target_link_libraries(<target> ... <item>... ...)
The named ``<target>`` must have been created in the current directory by
a command such as :command:`add_executable` or :command:`add_library`.
Repeated calls for the same ``<target>`` append items in the order called.
Each ``<item>`` may be:
* **A library target name**: The generated link line will have the
full path to the linkable library file associated with the target.
The buildsystem will have a dependency to re-link ``<target>`` if
the library file changes.
The named target must be created by :command:`add_library` within
the project or as an :ref:`IMPORTED library <Imported Targets>`.
If it is created within the project an ordering dependency will
automatically be added in the build system to make sure the named
library target is up-to-date before the ``<target>`` links.
If an imported library has the :prop_tgt:`IMPORTED_NO_SONAME`
target property set, CMake may ask the linker to search for
the library instead of using the full path
(e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``).
* **A full path to a library file**: The generated link line will
normally preserve the full path to the file. The buildsystem will
have a dependency to re-link ``<target>`` if the library file changes.
There are some cases where CMake may ask the linker to search for
the library (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such
as when a shared library is detected to have no ``SONAME`` field.
See policy :policy:`CMP0060` for discussion of another case.
If the library file is in a Mac OSX framework, the ``Headers`` directory
of the framework will also be processed as a
:ref:`usage requirement <Target Usage Requirements>`. This has the same
effect as passing the framework directory as an include directory.
* **A plain library name**: The generated link line will ask the linker
to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``).
* **A link flag**: Item names starting with ``-``, but not ``-l`` or
``-framework``, are treated as linker flags. Note that such flags will
be treated like any other library link item for purposes of transitive
dependencies, so they are generally safe to specify only as private link
items that will not propagate to dependents.
* A ``debug``, ``optimized``, or ``general`` keyword immediately followed
by another ``<item>``. The item following such a keyword will be used
only for the corresponding build configuration. The ``debug`` keyword
corresponds to the ``Debug`` configuration (or to configurations named
in the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set).
The ``optimized`` keyword corresponds to all other configurations. The
``general`` keyword corresponds to all configurations, and is purely
optional. Higher granularity may be achieved for per-configuration
rules by creating and linking to
:ref:`IMPORTED library targets <Imported Targets>`.
Items containing ``::``, such as ``Foo::Bar``, are assumed to be
:ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library
target names and will cause an error if no such target exists.
See policy :policy:`CMP0028`.
Arguments to ``target_link_libraries`` may use "generator expressions"
with the syntax ``$<...>``. Note however, that generator expressions
will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`.
See the :manual:`cmake-generator-expressions(7)` manual for available
expressions. See the :manual:`cmake-buildsystem(7)` manual for more on
defining buildsystem properties.
Libraries for a Target and/or its Dependents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
target_link_libraries(<target> [item1 [item2 [...]]]
[[debug|optimized|general] <item>] ...)
target_link_libraries(<target>
<PRIVATE|PUBLIC|INTERFACE> <item>...
[<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
Specify libraries or flags to use when linking a given target. The
named ``<target>`` must have been created in the current directory by a
command such as :command:`add_executable` or :command:`add_library`. The
remaining arguments specify library names or flags. Repeated calls for
the same ``<target>`` append items in the order called.
The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
specify both the link dependencies and the link interface in one command.
Libraries and targets following ``PUBLIC`` are linked to, and are made
part of the link interface. Libraries and targets following ``PRIVATE``
are linked to, but are not made part of the link interface. Libraries
following ``INTERFACE`` are appended to the link interface and are not
used for linking ``<target>``.
If a library name matches that of another target in the project a
dependency will automatically be added in the build system to make sure
the library being linked is up-to-date before the target links. Item names
starting with ``-``, but not ``-l`` or ``-framework``, are treated as
linker flags. Note that such flags will be treated like any other library
link item for purposes of transitive dependencies, so they are generally
safe to specify only as private link items that will not propagate to
dependents of ``<target>``.
Libraries for both a Target and its Dependents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A ``debug``, ``optimized``, or ``general`` keyword indicates that the
library immediately following it is to be used only for the
corresponding build configuration. The ``debug`` keyword corresponds to
the Debug configuration (or to configurations named in the
:prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). The
``optimized`` keyword corresponds to all other configurations. The
``general`` keyword corresponds to all configurations, and is purely
optional (assumed if omitted). Higher granularity may be achieved for
per-configuration rules by creating and linking to
:ref:`IMPORTED library targets <Imported Targets>`.
::
target_link_libraries(<target> <item>...)
Library dependencies are transitive by default with this signature.
When this target is linked into another target then the libraries
@ -45,40 +120,34 @@ by setting the property directly. When :policy:`CMP0022` is not set to
of this command may set the property making any libraries linked
exclusively by this signature private.
CMake will also propagate :ref:`usage requirements <Target Usage Requirements>`
from linked library targets. Usage requirements of dependencies affect
compilation of sources in the ``<target>``.
.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt
If an ``<item>`` is a library in a Mac OX framework, the ``Headers``
directory of the framework will also be processed as a
:ref:`usage requirement <Target Usage Requirements>`. This has the same
effect as passing the framework directory as an include directory.
--------------------------------------------------------------------------
Libraries for a Target and/or its Dependents (Legacy)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
target_link_libraries(<target>
<PRIVATE|PUBLIC|INTERFACE> <lib> ...
[<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...])
<LINK_PRIVATE|LINK_PUBLIC> <lib>...
[<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
specify both the link dependencies and the link interface in one command.
Libraries and targets following ``PUBLIC`` are linked to, and are made
part of the link interface. Libraries and targets following ``PRIVATE``
are linked to, but are not made part of the link interface. Libraries
following ``INTERFACE`` are appended to the link interface and are not
used for linking ``<target>``.
The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
the link dependencies and the link interface in one command.
--------------------------------------------------------------------------
This signature is for compatibility only. Prefer the ``PUBLIC`` or
``PRIVATE`` keywords instead.
Libraries and targets following ``LINK_PUBLIC`` are linked to, and are
made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy
:policy:`CMP0022` is not ``NEW``, they are also made part of the
:prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following
``LINK_PRIVATE`` are linked to, but are not made part of the
:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`).
Libraries for Dependents Only (Legacy)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
target_link_libraries(<target> LINK_INTERFACE_LIBRARIES
[[debug|optimized|general] <lib>] ...)
target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the
:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them
@ -102,28 +171,8 @@ is not ``NEW``, they are also appended to the
``general`` (or without any keyword) are treated as if specified for both
``debug`` and ``optimized``.
--------------------------------------------------------------------------
::
target_link_libraries(<target>
<LINK_PRIVATE|LINK_PUBLIC>
[[debug|optimized|general] <lib>] ...
[<LINK_PRIVATE|LINK_PUBLIC>
[[debug|optimized|general] <lib>] ...])
The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
the link dependencies and the link interface in one command.
This signature is for compatibility only. Prefer the ``PUBLIC`` or
``PRIVATE`` keywords instead.
Libraries and targets following ``LINK_PUBLIC`` are linked to, and are
made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy
:policy:`CMP0022` is not ``NEW``, they are also made part of the
:prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following
``LINK_PRIVATE`` are linked to, but are not made part of the
:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`).
Cyclic Dependencies of Static Libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The library dependency graph is normally acyclic (a DAG), but in the case
of mutually-dependent ``STATIC`` libraries CMake allows the graph to
@ -142,14 +191,14 @@ For example, the code
links ``main`` to ``A B A B``. While one repetition is usually
sufficient, pathological object file and symbol arrangements can require
more. One may handle such cases by manually repeating the component in
the last ``target_link_libraries`` call. However, if two archives are
really so interdependent they should probably be combined into a single
archive.
more. One may handle such cases by using the
:prop_tgt:`LINK_INTERFACE_MULTIPLICITY` target property or by manually
repeating the component in the last ``target_link_libraries`` call.
However, if two archives are really so interdependent they should probably
be combined into a single archive, perhaps by using :ref:`Object Libraries`.
Arguments to target_link_libraries may use "generator expressions"
with the syntax ``$<...>``. Note however, that generator expressions
will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`.
See the :manual:`cmake-generator-expressions(7)` manual for available
expressions. See the :manual:`cmake-buildsystem(7)` manual for more on
defining buildsystem properties.
Creating Relocatable Packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt

4
Help/command/target_sources.rst
View File

@ -22,10 +22,6 @@ items will populate the :prop_tgt:`SOURCES` property of
following arguments specify sources. Repeated calls for the same
``<target>`` append items in the order called.
Targets with :prop_tgt:`INTERFACE_SOURCES` may not be exported with the
:command:`export` or :command:`install(EXPORT)` commands. This limitation may be
lifted in a future version of CMake.
Arguments to ``target_sources`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`

3
Help/command/try_run.rst
View File

@ -73,7 +73,8 @@ When cross compiling, the executable compiled in the first step
usually cannot be run on the build host. The ``try_run`` command checks
the :variable:`CMAKE_CROSSCOMPILING` variable to detect whether CMake is in
cross-compiling mode. If that is the case, it will still try to compile
the executable, but it will not try to run the executable. Instead it
the executable, but it will not try to run the executable unless the
:variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable is set. Instead it
will create cache variables which must be filled by the user or by
presetting them in some CMake script file to the values the executable
would have produced if it had been run on its actual target platform.

16
Help/generator/Green Hills MULTI.rst Normal file
View File

@ -0,0 +1,16 @@
Green Hills MULTI
-----------------
Generates Green Hills MULTI project files (experimental, work-in-progress).
Customizations are available through the following cache variables:
* ``GHS_BSP_NAME``
* ``GHS_CUSTOMIZATION``
* ``GHS_GPJ_MACROS``
* ``GHS_OS_DIR``
.. note::
This generator is deemed experimental as of CMake |release|
and is still a work in progress. Future versions of CMake
may make breaking changes as the generator matures.

2
Help/generator/Ninja.rst
View File

@ -1,7 +1,7 @@
Ninja
-----
Generates build.ninja files (experimental).
Generates build.ninja files.
A build.ninja file is generated into the build tree. Recent versions
of the ninja program can build the project through the "all" target.

8
Help/generator/Visual Studio 6.rst
View File

@ -1,4 +1,10 @@
Visual Studio 6
---------------
Generates Visual Studio 6 project files.
Deprected. Generates Visual Studio 6 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 6 tools using the
:generator:`NMake Makefiles` generator.

8
Help/generator/Visual Studio 7.rst
View File

@ -1,4 +1,10 @@
Visual Studio 7
---------------
Generates Visual Studio .NET 2002 project files.
Deprected. Generates Visual Studio .NET 2002 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 7.0 tools using the
:generator:`NMake Makefiles` generator.

38
Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
View File

@ -1,30 +1,18 @@
Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the
|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies.
That would hard-code into installed packages the include directory paths
for dependencies **as found on the machine the package was made on**.
|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
directories of dependencies. That would hard-code into installed packages
the include directory paths for dependencies
**as found on the machine the package was made on**.
The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only
suitable for specifying the required include directories of the target itself,
not its dependencies.
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target
property. Those dependencies should themselves be targets that specify
their own header locations in |INTERFACE_PROPERTY_LINK|.
That is, code like this is incorrect for targets which will be used to
generate :manual:`cmake-packages(7)`:
.. code-block:: cmake
target_include_directories(mylib INTERFACE
$<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>
)
Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
which have their own |INTERFACE_PROPERTY_LINK| populated
appropriately. Those :ref:`IMPORTED targets <Imported Targets>` may then be
used with the :command:`target_link_libraries` command for ``mylib``.
That way, when a consumer uses the installed package, the
consumer will run the appropriate :command:`find_package` command to find
the dependencies on their own machine and populate the
:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. See
:ref:`Creating Packages` for more. Note that many modules currently shipped
with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`.
See the :ref:`Creating Relocatable Packages` section of the
:manual:`cmake-packages(7)` manual for discussion of additional care
that must be taken when specifying usage requirements while creating
packages for redistribution.

25
Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt
View File

@ -1,23 +1,10 @@
Note that it is not advisable to populate the
|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies.
That would hard-code into installed packages the include directory paths
|INTERFACE_PROPERTY_LINK| of a target with absolute paths to dependencies.
That would hard-code into installed packages the library file paths
for dependencies **as found on the machine the package was made on**.
That is, code like this is incorrect for targets which will be used to
generate :manual:`cmake-packages(7)`:
.. code-block:: cmake
target_link_libraries(mylib INTERFACE
${Boost_LIBRARIES};${OtherDep_LIBRARIES}
)
Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
which have their own :prop_tgt:`IMPORTED_LOCATION` populated
appropriately. That way, when a consumer uses the installed package, the
consumer will run the appropriate :command:`find_package` command to find
the dependencies on their own machine and populate the
:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. See
:ref:`Creating Packages` for more. Note that many modules currently shipped
with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`.
See the :ref:`Creating Relocatable Packages` section of the
:manual:`cmake-packages(7)` manual for discussion of additional care
that must be taken when specifying usage requirements while creating
packages for redistribution.

15
Help/manual/OPTIONS_BUILD.txt
View File

@ -10,7 +10,7 @@
containing SET commands that use the CACHE option, not a
cache-format file.
``-D <var>:<type>=<value>``
``-D <var>:<type>=<value>, -D <var>=<value>``
Create a cmake cache entry.
When cmake is first run in an empty build tree, it creates a
@ -19,6 +19,17 @@
takes priority over the project's default value. The option may be
repeated for as many cache entries as desired.
If the ``:<type>`` portion is given it must be one of the types
specified by the :command:`set` command documentation for its
``CACHE`` signature.
If the ``:<type>`` portion is omitted the entry will be created
with no type if it does not exist with a type already. If a
command in the project sets the type to ``PATH`` or ``FILEPATH``
then the ``<value>`` will be converted to an absolute path.
This option may also be given as a single argument:
``-D<var>:<type>=<value>`` or ``-D<var>=<value>``.
``-U <globbing_expr>``
Remove matching entries from CMake cache.
@ -35,7 +46,7 @@
CMake may support multiple native build systems on certain
platforms. A generator is responsible for generating a particular
build system. Possible generator names are specified in the
Generators section.
:manual:`cmake-generators(7)` manual.
``-T <toolset-name>``
Specify toolset name if supported by generator.

82
Help/manual/cmake-buildsystem.7.rst
View File

@ -143,6 +143,11 @@ use particular :prop_tgt:`COMPILE_OPTIONS` or
the properties must be **requirements**, not merely recommendations or
convenience.
See the :ref:`Creating Relocatable Packages` section of the
:manual:`cmake-packages(7)` manual for discussion of additional care
that must be taken when specifying usage requirements while creating
packages for redistribution.
Target Properties
-----------------
@ -627,7 +632,7 @@ may be enabled, with an equivalent effect to:
.. code-block:: cmake
set_property(TARGET tgt APPEND PROPERTY
set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
)
@ -690,8 +695,10 @@ edge of linking ``exe1`` is determined by the same
:prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above
contains a cycle. :manual:`cmake(1)` issues a diagnostic in this case.
Output Files
------------
.. _`Output Artifacts`:
Output Artifacts
----------------
The buildsystem targets created by the :command:`add_library` and
:command:`add_executable` commands create rules to create binary outputs.
@ -703,6 +710,71 @@ name and location of generated binaries. These expressions do not work
for ``OBJECT`` libraries however, as there is no single file generated
by such libraries which is relevant to the expressions.
There are three kinds of output artifacts that may be build by targets
as detailed in the following sections. Their classification differs
between DLL platforms and non-DLL platforms. All Windows-based
systems including Cygwin are DLL platforms.
.. _`Runtime Output Artifacts`:
Runtime Output Artifacts
^^^^^^^^^^^^^^^^^^^^^^^^
A *runtime* output artifact of a buildsystem target may be:
* The executable file (e.g. ``.exe``) of an executable target
created by the :command:`add_executable` command.
* On DLL platforms: the executable file (e.g. ``.dll``) of a shared
library target created by the :command:`add_library` command
with the ``SHARED`` option.
The :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`RUNTIME_OUTPUT_NAME`
target properties may be used to control runtime output artifact locations
and names in the build tree.
.. _`Library Output Artifacts`:
Library Output Artifacts
^^^^^^^^^^^^^^^^^^^^^^^^
A *library* output artifact of a buildsystem target may be:
* The loadable module file (e.g. ``.dll`` or ``.so``) of a module
library target created by the :command:`add_library` command
with the ``MODULE`` option.
* On non-DLL platforms: the shared library file (e.g. ``.so`` or ``.dylib``)
of a shared shared library target created by the :command:`add_library`
command with the ``SHARED`` option.
The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME`
target properties may be used to control library output artifact locations
and names in the build tree.
.. _`Archive Output Artifacts`:
Archive Output Artifacts
^^^^^^^^^^^^^^^^^^^^^^^^
An *archive* output artifact of a buildsystem target may be:
* The static library file (e.g. ``.lib`` or ``.a``) of a static
library target created by the :command:`add_library` command
with the ``STATIC`` option.
* On DLL platforms: the import library file (e.g. ``.lib``) of a shared
library target created by the :command:`add_library` command
with the ``SHARED`` option.
* On DLL platforms: the import library file (e.g. ``.lib``) of an
executable target created by the :command:`add_executable` command
when its :prop_tgt:`ENABLE_EXPORTS` target property is set.
The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`
target properties may be used to control archive output artifact locations
and names in the build tree.
Directory-Scoped Commands
-------------------------
@ -814,9 +886,9 @@ It may specify usage requirements such as
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
:prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
:prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
:prop_tgt:`INTERFACE_LINK_LIBRARIES`,
:prop_tgt:`INTERFACE_SOURCES`,
:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
:command:`target_compile_definitions`, :command:`target_compile_options`,
:command:`target_sources`, and :command:`target_link_libraries` commands

16
Help/manual/cmake-compile-features.7.rst
View File

@ -278,7 +278,7 @@ properties:
add_library(foo INTERFACE)
set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics)
set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics)
target_link_libraries(foo
target_include_directories(foo
INTERFACE
"$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>"
"$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>"
@ -295,3 +295,17 @@ the feature-appropriate include directory
add_executable(consumer_no consumer_no.cpp)
target_link_libraries(consumer_no foo)
Supported Compilers
===================
CMake is currently aware of the :prop_tgt:`language standards <CXX_STANDARD>`
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.
* ``MSVC``: Microsoft Visual Studio versions 2010 through 2015.
* ``SunPro``: Oracle SolarisStudio version 12.4.

30
Help/manual/cmake-developer.7.rst
View File

@ -28,34 +28,6 @@ Some implementations have a ``std::auto_ptr`` which can not be used as a
return value from a function. ``std::auto_ptr`` may not be used. Use
``cmsys::auto_ptr`` instead.
Template Parameter Defaults
---------------------------
On ancient compilers, C++ template must use template parameters in function
arguments. If no parameter of that type is needed, the common workaround is
to add a defaulted pointer to the type to the templated function. However,
this does not work with other ancient compilers:
.. code-block:: c++
template<typename PropertyType>
PropertyType getTypedProperty(cmTarget* tgt, const char* prop,
PropertyType* = 0) // Wrong
{
}
.. code-block:: c++
template<typename PropertyType>
PropertyType getTypedProperty(cmTarget* tgt, const char* prop,
PropertyType*) // Ok
{
}
and invoke it with the value ``0`` explicitly in all cases.
size_t
------
@ -633,6 +605,7 @@ have a .cmake file in this directory NOT show up in the modules
documentation, simply leave out the ``Help/module/<module-name>.rst``
file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.
.. _`Find Modules`:
Find Modules
------------
@ -894,7 +867,6 @@ look.
find_path(Foo_INCLUDE_DIR
NAMES foo.h
PATHS ${PC_Foo_INCLUDE_DIRS}
# if you need to put #include <Foo/foo.h> in your code, add:
PATH_SUFFIXES Foo
)
find_library(Foo_LIBRARY

54
Help/manual/cmake-generator-expressions.7.rst
View File

@ -40,10 +40,6 @@ otherwise expands to nothing.
Available logical expressions are:
``$<0:...>``
Empty string (ignores ``...``)
``$<1:...>``
Content of ``...``
``$<BOOL:...>``
``1`` if the ``...`` is true, else ``0``
``$<AND:?[,?]...>``
@ -92,7 +88,47 @@ Available logical expressions are:
increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD`
for the 'head' target, an error is reported. See the
:manual:`cmake-compile-features(7)` manual for information on
compile features.
compile features and a list of supported compilers.
``$<COMPILE_LANGUAGE:lang>``
``1`` when the language used for compilation unit matches ``lang``,
otherwise ``0``. This expression used to specify compile options for
source files of a particular language in a target. For example, to specify
the use of the ``-fno-exceptions`` compile option (compiler id checks
elided):
.. code-block:: cmake
add_executable(myapp main.cpp foo.c bar.cpp)
target_compile_options(myapp
PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
)
This generator expression has limited use because it is not possible to
use it with the Visual Studio generators. Portable buildsystems would
not use this expression, and would create separate libraries for each
source file language instead:
.. code-block:: cmake
add_library(myapp_c foo.c)
add_library(myapp_cxx foo.c)
target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
add_executable(myapp main.cpp)
target_link_libraries(myapp myapp_c myapp_cxx)
The ``Makefile`` and ``Ninja`` based generators can also use this
expression to specify compile-language specific compile definitions
and include directories:
.. code-block:: cmake
add_executable(myapp main.cpp foo.c bar.cpp)
target_compile_definitions(myapp
PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
)
target_include_directories(myapp
PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers>
)
Informational Expressions
=========================
@ -174,6 +210,10 @@ Available informational expressions are:
``$<INSTALL_PREFIX>``
Content of the install prefix when the target is exported via
:command:`install(EXPORT)` and empty otherwise.
``$<COMPILE_LANGUAGE>``
The compile language of source files when evaluating compile options. See
the unary version for notes about portability of this generator
expression.
Output Expressions
==================
@ -197,6 +237,10 @@ where ``${prop}`` refers to a helper variable::
Available output expressions are:
``$<0:...>``
Empty string (ignores ``...``)
``$<1:...>``
Content of ``...``
``$<JOIN:list,...>``
Joins the list with the content of ``...``
``$<ANGLE-R>``

27
Help/manual/cmake-generators.7.rst
View File

@ -34,6 +34,11 @@ These generators support command-line build tools. In order to use them,
one must launch CMake from a command-line prompt whose environment is
already configured for the chosen compiler and build tool.
.. _`Makefile Generators`:
Makefile Generators
^^^^^^^^^^^^^^^^^^^
.. toctree::
:maxdepth: 1
@ -42,10 +47,17 @@ already configured for the chosen compiler and build tool.
/generator/MinGW Makefiles
/generator/NMake Makefiles
/generator/NMake Makefiles JOM
/generator/Ninja
/generator/Unix Makefiles
/generator/Watcom WMake
Ninja Generator
^^^^^^^^^^^^^^^
.. toctree::
:maxdepth: 1
/generator/Ninja
IDE Build Tool Generators
-------------------------
@ -53,6 +65,11 @@ These generators support Integrated Development Environment (IDE)
project files. Since the IDEs configure their own environment
one may launch CMake from any environment.
.. _`Visual Studio Generators`:
Visual Studio Generators
^^^^^^^^^^^^^^^^^^^^^^^^
.. toctree::
:maxdepth: 1
@ -65,6 +82,14 @@ one may launch CMake from any environment.
/generator/Visual Studio 11 2012
/generator/Visual Studio 12 2013
/generator/Visual Studio 14 2015
Other Generators
^^^^^^^^^^^^^^^^
.. toctree::
:maxdepth: 1
/generator/Green Hills MULTI
/generator/Xcode
Extra Generators

4
Help/manual/cmake-language.7.rst
View File

@ -485,6 +485,8 @@ The :command:`macro`/:command:`endmacro`, and
:command:`function`/:command:`endfunction` commands delimit
code blocks to be recorded for later invocation as commands.
.. _`CMake Language Variables`:
Variables
=========
@ -538,6 +540,8 @@ The :manual:`cmake-variables(7)` manual documents many variables
that are provided by CMake or have meaning to CMake when set
by project code.
.. _`CMake Language Lists`:
Lists
=====

2
Help/manual/cmake-modules.7.rst
View File

@ -22,6 +22,7 @@ All Modules
/module/CheckCXXSourceCompiles
/module/CheckCXXSourceRuns
/module/CheckCXXSymbolExists
/module/CheckFortranCompilerFlag
/module/CheckFortranFunctionExists
/module/CheckFortranSourceCompiles
/module/CheckFunctionExists
@ -211,6 +212,7 @@ All Modules
/module/FindWish
/module/FindwxWidgets
/module/FindwxWindows
/module/FindXCTest
/module/FindXercesC
/module/FindX11
/module/FindXMLRPC

178
Help/manual/cmake-packages.7.rst
View File

@ -373,38 +373,6 @@ attempt to use version 3 together with version 4. Packages can choose to
employ such a pattern if different major versions of the package are designed
to be incompatible.
Note that it is not advisable to populate any properties which may contain
paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevnt to dependencies.
That would hard-code into installed packages the include directory or library
paths for dependencies **as found on the machine the package was made on**.
That is, code like this is incorrect for targets which will be used to
generate config file packages:
.. code-block:: cmake
target_link_libraries(ClimbingStats INTERFACE
${Boost_LIBRARIES};${OtherDep_LIBRARIES}>
)
target_include_directories(ClimbingStats INTERFACE
$<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>
)
Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
:prop_tgt:`IMPORTED_LOCATION` populated appropriately. Those
:ref:`IMPORTED targets <Imported Targets>` may then be
used with the :command:`target_link_libraries` command for ``ClimbingStats``.
That way, when a consumer uses the installed package, the
consumer will run the appropriate :command:`find_package` command (via the
find_dependency macro described below) to find
the dependencies on their own machine and populate the
:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. Note that
many modules currently shipped with CMake do not currently provide
:ref:`IMPORTED targets <Imported Targets>`.
A ``NAMESPACE`` with double-colons is specified when exporting the targets
for installation. This convention of double-colons gives CMake a hint that
the name is an :prop_tgt:`IMPORTED` target when it is used by downstreams
@ -418,6 +386,9 @@ directory in the :variable:`CMAKE_INSTALL_PREFIX`. When the ``IMPORTED``
target is used by downsteam, it automatically consumes the entries from
that property.
Creating a Package Configuration File
-------------------------------------
In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as:
.. code-block:: cmake
@ -429,44 +400,6 @@ should be provided by the ``ClimbingStats`` package, they should
be in a separate file which is installed to the same location as the
``ClimbingStatsConfig.cmake`` file, and included from there.
Packages created by :command:`install(EXPORT)` are designed to be relocatable,
using paths relative to the location of the package itself. When defining
the interface of a target for ``EXPORT``, keep in mind that the include
directories should be specified as relative paths which are relative to the
:variable:`CMAKE_INSTALL_PREFIX`:
.. code-block:: cmake
target_include_directories(tgt INTERFACE
# Wrong, not relocatable:
$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
)
target_include_directories(tgt INTERFACE
# Ok, relocatable:
$<INSTALL_INTERFACE:include/TgtName>
)
The ``$<INSTALL_PREFIX>``
:manual:`generator expression <cmake-generator-expressions(7)>` may be used as
a placeholder for the install prefix without resulting in a non-relocatable
package. This is necessary if complex generator expressions are used:
.. code-block:: cmake
target_include_directories(tgt INTERFACE
# Ok, relocatable:
$<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
)
The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets
definition file which is specific to the build-tree, and is not relocatable.
This can similiarly be used with a suitable package configuration file and
package version file to define a package for the build tree which may be used
without installation. Consumers of the build tree can simply ensure that the
:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the
``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache.
This can also be extended to cover dependencies:
.. code-block:: cmake
@ -526,6 +459,111 @@ could not be found because an invalid component was specified. This message
variable can be set for any case where the ``_FOUND`` variable is set to ``False``,
and will be displayed to the user.
Creating a Package Configuration File for the Build Tree
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets
definition file which is specific to the build-tree, and is not relocatable.
This can similiarly be used with a suitable package configuration file and
package version file to define a package for the build tree which may be used
without installation. Consumers of the build tree can simply ensure that the
:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the
``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache.
.. _`Creating Relocatable Packages`:
Creating Relocatable Packages
-----------------------------
A relocatable package must not reference absolute paths of files on
the machine where the package is built that will not exist on the
machines where the package may be installed.
Packages created by :command:`install(EXPORT)` are designed to be relocatable,
using paths relative to the location of the package itself. When defining
the interface of a target for ``EXPORT``, keep in mind that the include
directories should be specified as relative paths which are relative to the
:variable:`CMAKE_INSTALL_PREFIX`:
.. code-block:: cmake
target_include_directories(tgt INTERFACE
# Wrong, not relocatable:
$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
)
target_include_directories(tgt INTERFACE
# Ok, relocatable:
$<INSTALL_INTERFACE:include/TgtName>
)
The ``$<INSTALL_PREFIX>``
:manual:`generator expression <cmake-generator-expressions(7)>` may be used as
a placeholder for the install prefix without resulting in a non-relocatable
package. This is necessary if complex generator expressions are used:
.. code-block:: cmake
target_include_directories(tgt INTERFACE
# Ok, relocatable:
$<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
)
This also applies to paths referencing external dependencies.
It is not advisable to populate any properties which may contain
paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies.
For example, this code may not work well for a relocatable package:
.. code-block:: cmake
target_link_libraries(ClimbingStats INTERFACE
${Foo_LIBRARIES} ${Bar_LIBRARIES}
)
target_include_directories(ClimbingStats INTERFACE
"$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>"
)
The referenced variables may contain the absolute paths to libraries
and include directories **as found on the machine the package was made on**.
This would create a package with hard-coded paths to dependencies and not
suitable for relocation.
Ideally such dependencies should be used through their own
:ref:`IMPORTED targets <Imported Targets>` that have their own
:prop_tgt:`IMPORTED_LOCATION` and usage requirement properties
such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated
appropriately. Those imported targets may then be used with
the :command:`target_link_libraries` command for ``ClimbingStats``:
.. code-block:: cmake
target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar)
With this approach the package references its external dependencies
only through the names of :ref:`IMPORTED targets <Imported Targets>`.
When a consumer uses the installed package, the consumer will run the
appropriate :command:`find_package` commands (via the ``find_dependency``
macro described above) to find the dependencies and populate the
imported targets with appropriate paths on their own machine.
Unfortunately many :manual:`modules <cmake-modules(7)>` shipped with
CMake do not yet provide :ref:`IMPORTED targets <Imported Targets>`
because their development pre-dated this approach. This may improve
incrementally over time. Workarounds to create relocatable packages
using such modules include:
* When building the package, specify each ``Foo_LIBRARY`` cache
entry as just a library name, e.g. ``-DFoo_LIBRARY=foo``. This
tells the corresponding find module to populate the ``Foo_LIBRARIES``
with just ``foo`` to ask the linker to search for the library
instead of hard-coding a path.
* Or, after installing the package content but before creating the
package installation binary for redistribution, manually replace
the absolute paths with placeholders for substitution by the
installation tool when the package is installed.
.. _`Package Registry`:
Package Registry

17
Help/manual/cmake-policies.7.rst
View File

@ -20,11 +20,11 @@ for a policy, also avoiding the warning. Each policy can also be set to
either ``NEW`` or ``OLD`` behavior explicitly on the command line with the
:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable.
Note that policies are not reliable feature toggles. A policy should
almost never be set to ``OLD``, except to silence warnings in an otherwise
frozen or stable codebase, or temporarily as part of a larger migration
path. The ``OLD`` behavior of each policy is undesirable and will be
replaced with an error condition in a future release.
A policy is a deprecation mechanism and not a reliable feature toggle.
A policy should almost never be set to ``OLD``, except to silence warnings
in an otherwise frozen or stable codebase, or temporarily as part of a
larger migration path. The ``OLD`` behavior of each policy is undesirable
and will be replaced with an error condition in a future release.
The :command:`cmake_minimum_required` command does more than report an
error if a too-old version of CMake is used to build a project. It
@ -114,3 +114,10 @@ All Policies
/policy/CMP0054
/policy/CMP0055
/policy/CMP0056
/policy/CMP0057
/policy/CMP0058
/policy/CMP0059
/policy/CMP0060
/policy/CMP0061
/policy/CMP0062
/policy/CMP0063

23
Help/manual/cmake-properties.7.rst
View File

@ -7,6 +7,8 @@ cmake-properties(7)
.. contents::
.. _`Global Properties`:
Properties of Global Scope
==========================
@ -41,6 +43,8 @@ Properties of Global Scope
/prop_gbl/TARGET_SUPPORTS_SHARED_LIBS
/prop_gbl/USE_FOLDERS
.. _`Directory Properties`:
Properties on Directories
=========================
@ -72,6 +76,8 @@ Properties on Directories
/prop_dir/VS_GLOBAL_SECTION_POST_section
/prop_dir/VS_GLOBAL_SECTION_PRE_section
.. _`Target Properties`:
Properties on Targets
=====================
@ -113,6 +119,7 @@ Properties on Targets
/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
/prop_tgt/CONFIG_OUTPUT_NAME
/prop_tgt/CONFIG_POSTFIX
/prop_tgt/CROSSCOMPILING_EMULATOR
/prop_tgt/CXX_EXTENSIONS
/prop_tgt/CXX_STANDARD
/prop_tgt/CXX_STANDARD_REQUIRED
@ -170,6 +177,7 @@ Properties on Targets
/prop_tgt/JOB_POOL_COMPILE
/prop_tgt/JOB_POOL_LINK
/prop_tgt/LABELS
/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE
/prop_tgt/LANG_VISIBILITY_PRESET
/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG
/prop_tgt/LIBRARY_OUTPUT_DIRECTORY
@ -243,6 +251,9 @@ Properties on Targets
/prop_tgt/VS_WINRT_REFERENCES
/prop_tgt/WIN32_EXECUTABLE
/prop_tgt/XCODE_ATTRIBUTE_an-attribute
/prop_tgt/XCTEST
.. _`Test Properties`:
Properties on Tests
===================
@ -268,6 +279,8 @@ Properties on Tests
/prop_test/WILL_FAIL
/prop_test/WORKING_DIRECTORY
.. _`Source File Properties`:
Properties on Source Files
==========================
@ -297,10 +310,13 @@ Properties on Source Files
/prop_sf/VS_SHADER_FLAGS
/prop_sf/VS_SHADER_MODEL
/prop_sf/VS_SHADER_TYPE
/prop_sf/VS_XAML_TYPE
/prop_sf/WRAP_EXCLUDE
/prop_sf/XCODE_EXPLICIT_FILE_TYPE
/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE
.. _`Cache Entry Properties`:
Properties on Cache Entries
===========================
@ -314,19 +330,24 @@ Properties on Cache Entries
/prop_cache/TYPE
/prop_cache/VALUE
.. _`Installed File Properties`:
Properties on Installed Files
=============================
.. toctree::
:maxdepth: 1
/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst
/prop_inst/CPACK_NEVER_OVERWRITE.rst
/prop_inst/CPACK_PERMANENT.rst
/prop_inst/CPACK_START_MENU_SHORTCUTS.rst
/prop_inst/CPACK_STARTUP_SHORTCUTS.rst
/prop_inst/CPACK_WIX_ACL.rst
Deprecated Properties on Directories
=====================================
====================================
.. toctree::
:maxdepth: 1

11
Help/manual/cmake-variables.7.rst
View File

@ -25,6 +25,7 @@ Variables that Provide Information
/variable/CMAKE_CFG_INTDIR
/variable/CMAKE_COMMAND
/variable/CMAKE_CROSSCOMPILING
/variable/CMAKE_CROSSCOMPILING_EMULATOR
/variable/CMAKE_CTEST_COMMAND
/variable/CMAKE_CURRENT_BINARY_DIR
/variable/CMAKE_CURRENT_LIST_DIR
@ -181,6 +182,7 @@ Variables that Describe the System
/variable/CMAKE_SYSTEM_VERSION
/variable/CYGWIN
/variable/ENV
/variable/GHS-MULTI
/variable/MINGW
/variable/MSVC10
/variable/MSVC11
@ -211,6 +213,7 @@ Variables that Control the Build
/variable/CMAKE_ANDROID_API_MIN
/variable/CMAKE_ANDROID_GUI
/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY
/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_AUTOMOC_MOC_OPTIONS
/variable/CMAKE_AUTOMOC
/variable/CMAKE_AUTORCC
@ -232,8 +235,10 @@ Variables that Control the Build
/variable/CMAKE_INSTALL_NAME_DIR
/variable/CMAKE_INSTALL_RPATH
/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH
/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE
/variable/CMAKE_LANG_VISIBILITY_PRESET
/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY
/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_LIBRARY_PATH_FLAG
/variable/CMAKE_LINK_DEF_FILE_FLAG
/variable/CMAKE_LINK_DEPENDS_NO_SHARED
@ -254,6 +259,7 @@ Variables that Control the Build
/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_POSITION_INDEPENDENT_CODE
/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY
/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG
/variable/CMAKE_SHARED_LINKER_FLAGS
/variable/CMAKE_SKIP_BUILD_RPATH
@ -263,6 +269,7 @@ Variables that Control the Build
/variable/CMAKE_TRY_COMPILE_CONFIGURATION
/variable/CMAKE_USE_RELATIVE_PATHS
/variable/CMAKE_VISIBILITY_INLINES_HIDDEN
/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
/variable/CMAKE_WIN32_EXECUTABLE
/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute
/variable/EXECUTABLE_OUTPUT_PATH
@ -306,6 +313,10 @@ Variables for Languages
/variable/CMAKE_LANG_FLAGS_RELEASE
/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO
/variable/CMAKE_LANG_FLAGS
/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG
/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL
/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE
/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO
/variable/CMAKE_LANG_IGNORE_EXTENSIONS
/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES
/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES

6
Help/manual/cmake.1.rst
View File

@ -9,7 +9,7 @@ Synopsis
.. parsed-literal::
cmake [<options>] (<path-to-source> | <path-to-existing-build>)
cmake [(-D<var>=<value>)...] -P <cmake-script-file>
cmake [(-D <var>=<value>)...] -P <cmake-script-file>
cmake --build <dir> [<options>] [-- <build-tool-options>...]
cmake -E <command> [<options>...]
cmake --find-package <options>...
@ -215,6 +215,10 @@ Available commands are:
names start in ``-``.
``--mtime=<date>``
Specify modification time recorded in tarball entries.
``--format=<format>``
Specify the format of the archive to be created.
Supported formats are: ``7zip``, ``gnutar``, ``pax``,
``paxr`` (restricted pax, default), and ``zip``.
``time <command> [<args>...]``
Run command and return elapsed time.

22
Help/manual/ctest.1.rst
View File

@ -48,7 +48,9 @@ Options
useful for debugging dashboard problems.
``--output-on-failure``
Output anything outputted by the test program if the test should fail. This option can also be enabled by setting the environment variable CTEST_OUTPUT_ON_FAILURE
Output anything outputted by the test program if the test should fail.
This option can also be enabled by setting the environment variable
``CTEST_OUTPUT_ON_FAILURE``.
``-F``
Enable failover.
@ -62,7 +64,7 @@ Options
This option tells ctest to run the tests in parallel using given
number of jobs. This option can also be set by setting the
environment variable CTEST_PARALLEL_LEVEL.
environment variable ``CTEST_PARALLEL_LEVEL``.
``-Q,--quiet``
Make ctest quiet.
@ -194,6 +196,11 @@ Options
subsequent calls to ctest with the --rerun-failed option will run
the set of tests that most recently failed (if any).
``--repeat-until-fail <n>``
Require each test to run ``<n>`` times without failing in order to pass.
This is useful in finding sporadic failures in test cases.
``--max-width <width>``
Set the max width for a test name to output
@ -365,6 +372,8 @@ Options
.. include:: OPTIONS_HELP.txt
.. _`Dashboard Client`:
Dashboard Client
================
@ -568,7 +577,7 @@ Configuration settings to specify the version control tool include:
* :module:`CTest` module variable: ``GITCOMMAND``
``GITUpdateCustom``
Specify a semicolon-separated list of custom command lines to run
Specify a custom command line (as a semicolon-separated list) to run
in the source tree (Git work tree) to update it instead of running
the ``GITCommand``.
@ -612,7 +621,7 @@ Configuration settings to specify the version control tool include:
* :module:`CTest` module variable: ``CTEST_P4_OPTIONS``
``P4UpdateCustom``
Specify a semicolon-separated list of custom command lines to run
Specify a custom command line (as a semicolon-separated list) to run
in the source tree (Perforce tree) to update it instead of running
the ``P4Command``.
@ -742,8 +751,9 @@ Configuration settings include:
initialized by the :command:`build_command` command
``UseLaunchers``
For build trees generated by CMake using a Makefile generator
or the :generator:`Ninja` generator, specify whether the
For build trees generated by CMake using one of the
:ref:`Makefile Generators` or the :generator:`Ninja`
generator, specify whether the
``CTEST_USE_LAUNCHERS`` feature is enabled by the
:module:`CTestUseLaunchers` module (also included by the
:module:`CTest` module). When enabled, the generated build

1
Help/module/CheckFortranCompilerFlag.rst Normal file
View File

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

1
Help/module/FindXCTest.rst Normal file
View File

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

2
Help/policy/CMP0000.rst
View File

@ -28,3 +28,5 @@ a warning. An included file may set CMP0000 explicitly to affect how
this policy is enforced for the main CMakeLists.txt file.
This policy was introduced in CMake version 2.6.0.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0001.rst
View File

@ -17,3 +17,5 @@ below.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0002.rst
View File

@ -24,3 +24,5 @@ property ALLOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator).
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0003.rst
View File

@ -100,3 +100,5 @@ when setting the policy once will probably fix all targets.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0004.rst
View File

@ -21,3 +21,5 @@ target is created by an add_executable or add_library command.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0005.rst
View File

@ -22,3 +22,5 @@ limitations of the escaping implementation.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0006.rst
View File

@ -20,3 +20,5 @@ without a BUNDLE DESTINATION.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0007.rst
View File

@ -13,3 +13,5 @@ empty elements in a list.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0008.rst
View File

@ -30,3 +30,5 @@ pass it directly to the native build tool unchanged.
This policy was introduced in CMake version 2.6.1. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0009.rst
View File

@ -17,3 +17,5 @@ as an additional argument to the FILE command.
This policy was introduced in CMake version 2.6.2. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0010.rst
View File

@ -16,3 +16,5 @@ and is treated as always being ``NEW``.
This policy was introduced in CMake version 2.6.3. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0011.rst
View File

@ -20,3 +20,5 @@ cmake_policy PUSH and POP.
This policy was introduced in CMake version 2.6.3. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0012.rst
View File

@ -23,3 +23,5 @@ dereferencing variables with such names.
This policy was introduced in CMake version 2.8.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0013.rst
View File

@ -17,3 +17,5 @@ with an error.
This policy was introduced in CMake version 2.8.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0014.rst
View File

@ -13,3 +13,5 @@ behavior for this policy is to report an error.
This policy was introduced in CMake version 2.8.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0015.rst
View File

@ -15,3 +15,5 @@ paths by appending the relative path to CMAKE_CURRENT_SOURCE_DIR.
This policy was introduced in CMake version 2.8.1. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0016.rst
View File

@ -11,3 +11,5 @@ in this case.
This policy was introduced in CMake version 2.8.3. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0017.rst
View File

@ -17,3 +17,5 @@ from the CMake modules directory.
This policy was introduced in CMake version 2.8.4. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0018.rst
View File

@ -30,3 +30,5 @@ honor the POSITION_INDEPENDENT_CODE target property.
This policy was introduced in CMake version 2.8.9. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0019.rst
View File

@ -18,3 +18,5 @@ the values untouched.
This policy was introduced in CMake version 2.8.11. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0020.rst
View File

@ -23,3 +23,5 @@ automatically when they link to QtCore IMPORTED target.
This policy was introduced in CMake version 2.8.11. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0021.rst
View File

@ -16,3 +16,5 @@ relative path.
This policy was introduced in CMake version 2.8.12. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0022.rst
View File

@ -35,3 +35,5 @@ property for in-build targets, and ignore the old properties matching
This policy was introduced in CMake version 2.8.12. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0023.rst
View File

@ -31,3 +31,5 @@ signatures.
This policy was introduced in CMake version 2.8.12. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0024.rst
View File

@ -20,3 +20,5 @@ allow including the result of an export() command.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0025.rst
View File

@ -25,3 +25,5 @@ by default when this policy is not set and simply uses OLD behavior.
See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0025 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.
.. include:: DEPRECATED.txt

4
Help/policy/CMP0026.rst
View File

@ -1,7 +1,7 @@
CMP0026
-------
Disallow use of the LOCATION target property.
Disallow use of the LOCATION property for build targets.
CMake 2.8.12 and lower allowed reading the LOCATION target
property (and configuration-specific variants) to
@ -24,3 +24,5 @@ not to allow reading the LOCATION properties from build-targets.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0027.rst
View File

@ -23,3 +23,5 @@ conditionally linked IMPORTED target does not exist.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0028.rst
View File

@ -21,3 +21,5 @@ double-colons but is not an IMPORTED target or an ALIAS target.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt

2
Help/policy/CMP0029.rst
View File

@ -8,3 +8,5 @@ but was kept in CMake for compatibility for a long time.
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt

2
Help/policy/CMP0030.rst
View File

@ -9,3 +9,5 @@ not used it in years.
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt

2
Help/policy/CMP0031.rst
View File

@ -11,3 +11,5 @@ the CMake process. It has been mostly superseded by the
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt

2
Help/policy/CMP0032.rst
View File

@ -11,3 +11,5 @@ functionality is better achieved through dedicated outside tools.
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt

2
Help/policy/CMP0033.rst
View File

@ -12,3 +12,5 @@ The functionality has been superseded by the :command:`export` and
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt

2
Help/policy/CMP0034.rst
View File

@ -9,3 +9,5 @@ generate other files. This approach has long been replaced by
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt

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