Lubuntu/cmake
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update upstream source from tag 'upstream/3.30.0'

Browse Source 
Update to upstream version '3.30.0'
with Debian dir bb6db5c1ef82bf3b6e45590d67ec9163cec008eb
This commit is contained in:
Timo Röhling 2024-07-09 14:47:14 +02:00
commit 6aca2ce44e
2092 changed files with 65396 additions and 27434 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
.clang-tidy
View File

@ -5,12 +5,16 @@ bugprone-*,\
-bugprone-easily-swappable-parameters,\
-bugprone-empty-catch,\
-bugprone-implicit-widening-of-multiplication-result,\
-bugprone-inc-dec-in-conditions,\
-bugprone-macro-parentheses,\
-bugprone-misplaced-widening-cast,\
-bugprone-multi-level-implicit-pointer-conversion,\
-bugprone-narrowing-conversions,\
-bugprone-switch-missing-default-case,\
-bugprone-too-small-loop-variable,\
-bugprone-unchecked-optional-access,\
-bugprone-unused-local-non-trivial-variable,\
-bugprone-unused-return-value,\
misc-*,\
-misc-confusable-identifiers,\
-misc-const-correctness,\
@ -31,9 +35,12 @@ modernize-*,\
-modernize-use-transparent-functors,\
performance-*,\
-performance-avoid-endl,\
-performance-enum-size,\
-performance-inefficient-vector-operation,\
-performance-noexcept-swap,\
readability-*,\
-readability-avoid-nested-conditional-operator,\
-readability-avoid-return-with-void-value,\
-readability-avoid-unconditional-preprocessor-if,\
-readability-convert-member-functions-to-static,\
-readability-function-cognitive-complexity,\
@ -45,8 +52,11 @@ readability-*,\
-readability-magic-numbers,\
-readability-make-member-function-const,\
-readability-named-parameter,\
-readability-redundant-casting,\
-readability-redundant-declaration,\
-readability-redundant-inline-specifier,\
-readability-redundant-member-init,\
-readability-reference-to-constructed-temporary,\
-readability-simplify-boolean-expr,\
-readability-static-accessed-through-instance,\
-readability-suspicious-call-argument,\

24
Auxiliary/bash-completion/cmake
View File

@ -2,14 +2,22 @@
_cmake()
{
local cur prev words cword split=false
if type -t _init_completion >/dev/null; then
_init_completion -n = || return
local is_old_completion=false
local is_init_completion=false
local cur prev words cword split was_split
if type -t _comp_initialize >/dev/null; then
_comp_initialize -s || return
elif type -t _init_completion >/dev/null; then
_init_completion -s || return
is_init_completion=true
else
# manual initialization for older bash completion versions
COMPREPLY=()
cur="${COMP_WORDS[COMP_CWORD]}"
prev="${COMP_WORDS[COMP_CWORD-1]}"
is_old_completion=true
split=false
fi
# Workaround for options like -DCMAKE_BUILD_TYPE=Release
@ -89,7 +97,9 @@ _cmake()
;;
esac
_split_longopt && split=true
if $is_old_completion; then
_split_longopt && split=true
fi
case "$prev" in
-C|-P|--graphviz|--system-information)
@ -187,7 +197,11 @@ _cmake()
;;
esac
$split && return
if ($is_old_completion || $is_init_completion); then
$split && return
else
[[ $was_split ]] && return
fi
if [[ "$cur" == -* ]]; then
COMPREPLY=( $(compgen -W '$( _parse_help "$1" --help )' -- ${cur}) )

4
Auxiliary/bash-completion/cpack
View File

@ -3,7 +3,9 @@
_cpack()
{
local cur prev words cword
if type -t _init_completion >/dev/null; then
if type -t _comp_initialize >/dev/null; then
_comp_initialize -n = || return
elif type -t _init_completion >/dev/null; then
_init_completion -n = || return
else
# manual initialization for older bash completion versions

4
Auxiliary/bash-completion/ctest
View File

@ -3,7 +3,9 @@
_ctest()
{
local cur prev words cword
if type -t _init_completion >/dev/null; then
if type -t _comp_initialize >/dev/null; then
_comp_initialize -n = || return
elif type -t _init_completion >/dev/null; then
_init_completion -n = || return
else
# manual initialization for older bash completion versions

11
Auxiliary/cmake-mode.el
View File

@ -1,4 +1,4 @@
;;; cmake-mode.el --- major-mode for editing CMake sources
;;; cmake-mode.el --- major-mode for editing CMake sources -*- lexical-binding: t; -*-
;; Package-Requires: ((emacs "24.1"))
@ -279,7 +279,7 @@ Return t unless search stops due to end of buffer."
;------------------------------------------------------------------------------
(defun cmake--syntax-propertize-until-bracket-close (syntax)
(defun cmake--syntax-propertize-until-bracket-close (syntax end)
;; This function assumes that a previous search has matched the
;; beginning of a bracket_comment or bracket_argument and that the
;; second capture group has matched the equal signs between the two
@ -307,10 +307,10 @@ Return t unless search stops due to end of buffer."
(syntax-propertize-rules
("\\(#\\)\\[\\(=*\\)\\["
(1
(prog1 "!" (cmake--syntax-propertize-until-bracket-close "!"))))
(prog1 "!" (cmake--syntax-propertize-until-bracket-close "!" end))))
("\\(\\[\\)\\(=*\\)\\["
(1
(prog1 "|" (cmake--syntax-propertize-until-bracket-close "|"))))))
(prog1 "|" (cmake--syntax-propertize-until-bracket-close "|" end))))))
;; Syntax table for this mode.
(defvar cmake-mode-syntax-table nil
@ -480,7 +480,8 @@ and store the result as a list in LISTVAR."
;;;###autoload
(defun cmake-help ()
"Queries for any of the four available help topics and prints out the appropriate page."
"Queries for any of the four available help topics and prints out the
appropriate page."
(interactive)
(let* ((default-entry (cmake-symbol-at-point))
(command-list (cmake-get-list "command"))

1
Auxiliary/vim/syntax/cmake.vim
View File

@ -450,6 +450,7 @@ syn keyword cmakeProperty contained
\ VS_STARTUP_PROJECT
\ VS_TOOL_OVERRIDE
\ VS_USER_PROPS
\ VS_FILTER_PROPS
\ VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
\ VS_WINRT_COMPONENT
\ VS_WINRT_EXTENSIONS

9
CMakeCPack.cmake
View File

@ -229,15 +229,12 @@ endif()
set(CPACK_WIX_UPGRADE_GUID "8ffd1d72-b7f1-11e2-8ee5-00238bca4991")
if(MSVC AND NOT "$ENV{WIX}" STREQUAL "")
set(WIX_CUSTOM_ACTION_ENABLED TRUE)
if(CMake_BUILD_WIX_CUSTOM_ACTION)
if(CMAKE_CONFIGURATION_TYPES)
set(WIX_CUSTOM_ACTION_MULTI_CONFIG TRUE)
set(CMake_BUILD_WIX_CUSTOM_ACTION_MULTI_CONFIG TRUE)
else()
set(WIX_CUSTOM_ACTION_MULTI_CONFIG FALSE)
set(CMake_BUILD_WIX_CUSTOM_ACTION_MULTI_CONFIG FALSE)
endif()
else()
set(WIX_CUSTOM_ACTION_ENABLED FALSE)
endif()
# Set the options file that needs to be included inside CMakeCPackOptions.cmake

25
CMakeCPackOptions.cmake.in
View File

@ -206,6 +206,9 @@ if("${CPACK_GENERATOR}" STREQUAL "DragNDrop")
endif()
if("${CPACK_GENERATOR}" STREQUAL "WIX")
set(CPACK_WIX_VERSION 4)
set(CPACK_WIX_BUILD_EXTRA_FLAGS "")
# Reset CPACK_PACKAGE_VERSION to deal with WiX restriction.
# But the file names still use the full CMake_VERSION value:
set(CPACK_PACKAGE_FILE_NAME
@ -246,14 +249,7 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX")
CPACK_START_MENU_SHORTCUTS "CMake Web Site"
)
set(CPACK_WIX_LIGHT_EXTRA_FLAGS "-dcl:high")
if(NOT "$ENV{CMAKE_CI_PACKAGE}" STREQUAL "")
# Suppress validation. It does not work without
# an interactive session or an admin account.
# https://github.com/wixtoolset/issues/issues/3968
list(APPEND CPACK_WIX_LIGHT_EXTRA_FLAGS "-sval")
endif()
list(APPEND CPACK_WIX_BUILD_EXTRA_FLAGS -dcl high)
set(CPACK_WIX_UI_BANNER
"@CMake_SOURCE_DIR@/Utilities/Release/WiX/ui_banner.jpg"
@ -265,17 +261,18 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX")
set(CPACK_WIX_EXTRA_SOURCES
"@CMake_SOURCE_DIR@/Utilities/Release/WiX/install_dir.wxs"
"@CMake_SOURCE_DIR@/Utilities/Release/WiX/cmake_extra_dialog.wxs"
"@CMake_SOURCE_DIR@/Utilities/Release/WiX/options.wxs"
"@CMake_SOURCE_DIR@/Utilities/Release/WiX/options_dlg.wxs"
)
set(_WIX_CUSTOM_ACTION_ENABLED "@WIX_CUSTOM_ACTION_ENABLED@")
set(_WIX_CUSTOM_ACTION_ENABLED "@CMake_BUILD_WIX_CUSTOM_ACTION@")
if(_WIX_CUSTOM_ACTION_ENABLED)
list(APPEND CPACK_WIX_EXTRA_SOURCES
"@CMake_SOURCE_DIR@/Utilities/Release/WiX/cmake_nsis_overwrite_dialog.wxs"
)
list(APPEND CPACK_WIX_CANDLE_EXTRA_FLAGS -dCHECK_NSIS=1)
list(APPEND CPACK_WIX_BUILD_EXTRA_FLAGS -d CHECK_NSIS=1)
set(_WIX_CUSTOM_ACTION_MULTI_CONFIG "@WIX_CUSTOM_ACTION_MULTI_CONFIG@")
set(_WIX_CUSTOM_ACTION_MULTI_CONFIG "@CMake_BUILD_WIX_CUSTOM_ACTION_MULTI_CONFIG@")
if(_WIX_CUSTOM_ACTION_MULTI_CONFIG)
if(CPACK_BUILD_CONFIG)
set(_WIX_CUSTOM_ACTION_CONFIG "${CPACK_BUILD_CONFIG}")
@ -291,7 +288,7 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX")
endif()
endif()
set(CPACK_WIX_UI_REF "CMakeUI_InstallDir")
set(CPACK_WIX_UI_REF "CMakeUI_InstallDir_$(sys.BUILDARCHSHORT)")
set(CPACK_WIX_PATCH_FILE
"@CMake_SOURCE_DIR@/Utilities/Release/WiX/patch_path_env.xml"
@ -307,6 +304,6 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX")
list(APPEND CPACK_WIX_PATCH_FILE
"@CMake_SOURCE_DIR@/Utilities/Release/WiX/patch_desktop_shortcut.xml"
)
list(APPEND CPACK_WIX_CANDLE_EXTRA_FLAGS -dBUILD_QtDialog=1)
list(APPEND CPACK_WIX_BUILD_EXTRA_FLAGS -d BUILD_QtDialog=1)
endif()
endif()

9
CMakeLists.txt
View File

@ -1,7 +1,7 @@
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
cmake_minimum_required(VERSION 3.13...3.27 FATAL_ERROR)
cmake_minimum_required(VERSION 3.13...3.28 FATAL_ERROR)
set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake)
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake)
@ -178,6 +178,9 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
string(TOLOWER "${util}" lutil)
set(CMAKE_USE_SYSTEM_${util} "${CMAKE_USE_SYSTEM_LIBRARY_${util}}"
CACHE BOOL "Use system-installed ${lutil}" FORCE)
elseif(util STREQUAL "CURL" AND APPLE)
# macOS provides a curl with backends configured by Apple.
set(CMAKE_USE_SYSTEM_LIBRARY_${util} ON)
else()
set(CMAKE_USE_SYSTEM_LIBRARY_${util} OFF)
endif()
@ -215,6 +218,10 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
mark_as_advanced(CMAKE_USE_SYSTEM_KWIML)
# Mention to the user what system libraries are being used.
if(CMAKE_USE_SYSTEM_CURL)
# Avoid messaging about curl-only dependencies.
list(REMOVE_ITEM UTILITIES NGHTTP2)
endif()
foreach(util IN LISTS UTILITIES ITEMS KWIML)
if(CMAKE_USE_SYSTEM_${util})
message(STATUS "Using system-installed ${util}")

6
CTestCustom.cmake.in
View File

@ -12,11 +12,12 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"warning: \\(Long double usage is reported only once for each file"
"warning: To disable this warning use"
"could not be inlined"
"libcmexpat.*has no symbols"
"libcmcurl.*has no symbols"
"libcm(curl|expat).*has no symbols"
"cm(curl|expat).build/[^ ]*.o has no symbols"
"not sorted slower link editing will result"
"stl_deque.h:479"
"Utilities.cmzlib."
"Utilities.cmzstd."
"Utilities.cmbzip2."
"Source.CTest.Curl"
"Source.CursesDialog.form"
@ -85,6 +86,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"[0-9]+ Warning\\(s\\) detected" # SunPro
# Ignore false positive on `cm::optional` usage from GCC
"cmFileCommand.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& tls_verify \\+2\\)' may be used uninitialized in this function \\[-Wmaybe-uninitialized\\]"
"cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: warning: '.*cm::optional<CxxModuleMapFormat>::_mem\\)\\)' may be used uninitialized \\[-Wmaybe-uninitialized\\]"
"cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: note: '.*cm::optional<CxxModuleMapFormat>::_mem\\)\\)' was declared here"
"cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& modmap_fmt \\+4\\)' may be used uninitialized in this function \\[-Wmaybe-uninitialized\\]"

14
Help/command/add_custom_command.rst
View File

@ -84,8 +84,8 @@ The options are:
.. versionadded:: 3.20
Arguments to ``BYPRODUCTS`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`.
:ref:`Target-dependent expressions <Target-Dependent Queries>` are not
permitted.
:ref:`Target-dependent expressions <Target-Dependent Expressions>`
are not permitted.
.. versionchanged:: 3.28
In targets using :ref:`file sets`, custom command byproducts are now
@ -269,17 +269,23 @@ The options are:
source tree is mentioned as an absolute source file path elsewhere
in the current directory.
The output file path may not contain ``<`` or ``>`` characters.
.. versionadded:: 3.20
Arguments to ``OUTPUT`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`.
:ref:`Target-dependent expressions <Target-Dependent Queries>` are not
permitted.
:ref:`Target-dependent expressions <Target-Dependent Expressions>`
are not permitted.
.. versionchanged:: 3.28
In targets using :ref:`file sets`, custom command outputs are now
considered private unless they are listed in a non-private file set.
See policy :policy:`CMP0154`.
.. versionchanged:: 3.30
The output file path may now use ``#`` characters, except
when using the :generator:`Borland Makefiles` generator.
``USES_TERMINAL``
.. versionadded:: 3.2

4
Help/command/add_custom_target.rst
View File

@ -60,8 +60,8 @@ The options are:
.. versionadded:: 3.20
Arguments to ``BYPRODUCTS`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`.
:ref:`Target-dependent expressions <Target-Dependent Queries>` are not
permitted.
:ref:`Target-dependent expressions <Target-Dependent Expressions>`
are not permitted.
.. versionchanged:: 3.28
In custom targets using :ref:`file sets`, byproducts are now

11
Help/command/add_dependencies.rst
View File

@ -20,6 +20,17 @@ transitively in its place since the target itself does not build.
.. versionadded:: 3.3
Allow adding dependencies to interface libraries.
.. versionadded:: 3.8
Dependencies will populate the :prop_tgt:`MANUALLY_ADDED_DEPENDENCIES`
property of ``<target>``.
.. versionchanged:: 3.9
The :ref:`Ninja Generators` use weaker ordering than
other generators in order to improve available concurrency.
They only guarantee that the dependencies' custom commands are
finished before sources in ``<target>`` start compiling; this
ensures generated sources are available.
See Also
^^^^^^^^

7
Help/command/add_library.rst
View File

@ -84,6 +84,13 @@ See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.
.. versionchanged:: 3.30
On platforms that do not support shared libraries, ``add_library``
now fails on calls creating ``SHARED`` libraries instead of
automatically converting them to ``STATIC`` libraries as before.
See policy :policy:`CMP0164`.
Object Libraries
^^^^^^^^^^^^^^^^

17
Help/command/add_subdirectory.rst
View File

@ -20,19 +20,10 @@ typical usage). The ``CMakeLists.txt`` file in the specified source
directory will be processed immediately by CMake before processing in
the current input file continues beyond this command.
If the ``EXCLUDE_FROM_ALL`` argument is provided then targets in the
subdirectory will not be included in the ``ALL`` target of the parent
directory by default, and will be excluded from IDE project files.
Users must explicitly build targets in the subdirectory. This is
meant for use when the subdirectory contains a separate part of the
project that is useful but not necessary, such as a set of examples.
Typically the subdirectory should contain its own :command:`project`
command invocation so that a full build system will be generated in the
subdirectory (such as a Visual Studio IDE solution file). Note that
inter-target dependencies supersede this exclusion. If a target built by
the parent project depends on a target in the subdirectory, the dependee
target will be included in the parent project build system to satisfy
the dependency.
If the ``EXCLUDE_FROM_ALL`` argument is provided then the
:prop_dir:`EXCLUDE_FROM_ALL` property will be set on the added directory.
This will exclude the directory from a default build. See the directory
property :prop_dir:`EXCLUDE_FROM_ALL` for full details.
.. versionadded:: 3.25
If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory

5
Help/command/cmake_language.rst
View File

@ -271,6 +271,11 @@ Dependency Providers
:command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
outside of that context will result in an error.
.. versionadded:: 3.30
The :prop_gbl:`PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE` global
property can be set if the dependency provider also wants to be enabled
in whole-project calls to :command:`try_compile`.
.. note::
The choice of dependency provider should always be under the user's control.
As a convenience, a project may choose to provide a file that users can

2
Help/command/cmake_path.rst
View File

@ -600,7 +600,7 @@ For example:
# filename is now already empty, the following removes nothing
cmake_path(REMOVE_FILENAME path)
message("Second path is \"${result}\"")
message("Second path is \"${path}\"")
Output::

16
Help/command/enable_language.rst
View File

@ -9,15 +9,19 @@ Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc)
Enables support for the named languages in CMake. This is the same as
the :command:`project` command but does not create any of the extra
variables that are created by the project command.
variables that are created by the :command:`project` command.
.. include:: SUPPORTED_LANGUAGES.txt
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or
indirectly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The following restrictions apply to where ``enable_language()`` may be called:
* It must be called in file scope, not in a function call.
* It must not be called before the first call to :command:`project`.
See policy :policy:`CMP0165`.
* It must be called in the highest directory common to all targets
using the named language directly for compiling sources or
indirectly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The ``OPTIONAL`` keyword is a placeholder for future implementation and
does not currently work. Instead you can use the :module:`CheckLanguage`

659
Help/command/file.rst
View File

@ -28,7 +28,6 @@ Synopsis
file(`STRINGS`_ <filename> <out-var> [...])
file(`\<HASH\>`_ <filename> <out-var>)
file(`TIMESTAMP`_ <filename> <out-var> [...])
file(`GET_RUNTIME_DEPENDENCIES`_ [...])
`Writing`_
file({`WRITE`_ | `APPEND`_} <filename> <content>...)
@ -65,6 +64,10 @@ Synopsis
file(`ARCHIVE_CREATE`_ OUTPUT <archive> PATHS <paths>... [...])
file(`ARCHIVE_EXTRACT`_ INPUT <archive> [...])
`Handling Runtime Binaries`_
file(`GET_RUNTIME_DEPENDENCIES`_ [...])
Reading
^^^^^^^
@ -157,323 +160,6 @@ Reading
See the :command:`string(TIMESTAMP)` command for documentation of
the ``<format>`` and ``UTC`` options.
.. signature::
file(GET_RUNTIME_DEPENDENCIES [...])
.. versionadded:: 3.16
Recursively get the list of libraries depended on by the given files:
.. code-block:: cmake
file(GET_RUNTIME_DEPENDENCIES
[RESOLVED_DEPENDENCIES_VAR <deps_var>]
[UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
[CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
[EXECUTABLES <executable_files>...]
[LIBRARIES <library_files>...]
[MODULES <module_files>...]
[DIRECTORIES <directories>...]
[BUNDLE_EXECUTABLE <bundle_executable_file>]
[PRE_INCLUDE_REGEXES <regexes>...]
[PRE_EXCLUDE_REGEXES <regexes>...]
[POST_INCLUDE_REGEXES <regexes>...]
[POST_EXCLUDE_REGEXES <regexes>...]
[POST_INCLUDE_FILES <files>...]
[POST_EXCLUDE_FILES <files>...]
)
Please note that this sub-command is not intended to be used in project mode.
It is intended for use at install time, either from code generated by the
:command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by
the project via :command:`install(CODE)` or :command:`install(SCRIPT)`.
For example:
.. code-block:: cmake
install(CODE [[
file(GET_RUNTIME_DEPENDENCIES
# ...
)
]])
The arguments are as follows:
``RESOLVED_DEPENDENCIES_VAR <deps_var>``
Name of the variable in which to store the list of resolved dependencies.
``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>``
Name of the variable in which to store the list of unresolved
dependencies. If this variable is not specified, and there are any
unresolved dependencies, an error is issued.
``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>``
Variable prefix in which to store conflicting dependency information.
Dependencies are conflicting if two files with the same name are found in
two different directories. The list of filenames that conflict are stored
in ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list
of paths that were found for that filename are stored in
``<conflicting_deps_prefix>_<filename>``.
``EXECUTABLES <executable_files>...``
List of executable files to read for dependencies. These are executables
that are typically created with :command:`add_executable`, but they do
not have to be created by CMake. On Apple platforms, the paths to these
files determine the value of ``@executable_path`` when recursively
resolving the libraries. Specifying any kind of library (``STATIC``,
``MODULE``, or ``SHARED``) here will result in undefined behavior.
``LIBRARIES <library_files>...``
List of library files to read for dependencies. These are libraries that
are typically created with :command:`add_library(SHARED)`, but they do
not have to be created by CMake. Specifying ``STATIC`` libraries,
``MODULE`` libraries, or executables here will result in undefined
behavior.
``MODULES <module_files>...``
List of loadable module files to read for dependencies. These are modules
that are typically created with :command:`add_library(MODULE)`, but they
do not have to be created by CMake. They are typically used by calling
``dlopen()`` at runtime rather than linked at link time with ``ld -l``.
Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables
here will result in undefined behavior.
``DIRECTORIES <directories>...``
List of additional directories to search for dependencies. On Linux
platforms, these directories are searched if the dependency is not found
in any of the other usual paths. If it is found in such a directory, a
warning is issued, because it means that the file is incomplete (it does
not list all of the directories that contain its dependencies).
On Windows platforms, these directories are searched if the dependency
is not found in any of the other search paths, but no warning is issued,
because searching other paths is a normal part of Windows dependency
resolution. On Apple platforms, this argument has no effect.
``BUNDLE_EXECUTABLE <bundle_executable_file>``
Executable to treat as the "bundle executable" when resolving libraries.
On Apple platforms, this argument determines the value of
``@executable_path`` when recursively resolving libraries for
``LIBRARIES`` and ``MODULES`` files. It has no effect on ``EXECUTABLES``
files. On other platforms, it has no effect. This is typically (but not
always) one of the executables in the ``EXECUTABLES`` argument which
designates the "main" executable of the package.
The following arguments specify filters for including or excluding libraries
to be resolved. See below for a full description of how they work.
``PRE_INCLUDE_REGEXES <regexes>...``
List of pre-include regexes through which to filter the names of
not-yet-resolved dependencies.
``PRE_EXCLUDE_REGEXES <regexes>...``
List of pre-exclude regexes through which to filter the names of
not-yet-resolved dependencies.
``POST_INCLUDE_REGEXES <regexes>...``
List of post-include regexes through which to filter the names of
resolved dependencies.
``POST_EXCLUDE_REGEXES <regexes>...``
List of post-exclude regexes through which to filter the names of
resolved dependencies.
``POST_INCLUDE_FILES <files>...``
.. versionadded:: 3.21
List of post-include filenames through which to filter the names of
resolved dependencies. Symlinks are resolved when attempting to match
these filenames.
``POST_EXCLUDE_FILES <files>...``
.. versionadded:: 3.21
List of post-exclude filenames through which to filter the names of
resolved dependencies. Symlinks are resolved when attempting to match
these filenames.
These arguments can be used to exclude unwanted system libraries when
resolving the dependencies, or to include libraries from a specific
directory. The filtering works as follows:
1. If the not-yet-resolved dependency matches any of the
``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency
resolution proceeds to step 4.
2. If the not-yet-resolved dependency matches any of the
``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency.
3. Otherwise, dependency resolution proceeds.
4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according
to the linking rules of the platform (see below).
5. If the dependency is found, and its full path matches one of the
``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added
to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)``
recursively resolves that library's own dependencies. Otherwise, resolution
proceeds to step 6.
6. If the dependency is found, but its full path matches one of the
``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the
resolved dependencies, and dependency resolution stops for that dependency.
7. If the dependency is found, and its full path does not match either
``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``,
or ``POST_EXCLUDE_FILES``, the full path is added to the resolved
dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves
that library's own dependencies.
Different platforms have different rules for how dependencies are resolved.
These specifics are described here.
On Linux platforms, library resolution works as follows:
1. If the depending file does not have any ``RUNPATH`` entries, and the
library exists in one of the depending file's ``RPATH`` entries, or its
parents', in that order, the dependency is resolved to that file.
2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the
library exists in one of those entries, the dependency is resolved to that
file.
3. Otherwise, if the library exists in one of the directories listed by
``ldconfig``, the dependency is resolved to that file.
4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries,
the dependency is resolved to that file. In this case, a warning is
issued, because finding a file in one of the ``DIRECTORIES`` means that
the depending file is not complete (it does not list all the directories
from which it pulls dependencies).
5. Otherwise, the dependency is unresolved.
On Windows platforms, library resolution works as follows:
1. DLL dependency names are converted to lowercase for matching filters.
Windows DLL names are case-insensitive, and some linkers mangle the
case of the DLL dependency names. However, this makes it more difficult
for ``PRE_INCLUDE_REGEXES``, ``PRE_EXCLUDE_REGEXES``,
``POST_INCLUDE_REGEXES``, and ``POST_EXCLUDE_REGEXES`` to properly
filter DLL names - every regex would have to check for both uppercase
and lowercase letters. For example:
.. code-block:: cmake
file(GET_RUNTIME_DEPENDENCIES
# ...
PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
)
Converting the DLL name to lowercase allows the regexes to only match
lowercase names, thus simplifying the regex. For example:
.. code-block:: cmake
file(GET_RUNTIME_DEPENDENCIES
# ...
PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
)
This regex will match ``mylibrary.dll`` regardless of how it is cased,
either on disk or in the depending file. (For example, it will match
``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.)
.. versionchanged:: 3.27
The conversion to lowercase only applies while matching filters.
Results reported after filtering case-preserve each DLL name as it is
found on disk, if resolved, and otherwise as it is referenced by the
dependent binary.
Prior to CMake 3.27, the results were reported with lowercase DLL
file names, but the directory portion retained its casing.
2. (**Not yet implemented**) If the depending file is a Windows Store app,
and the dependency is listed as a dependency in the application's package
manifest, the dependency is resolved to that file.
3. Otherwise, if the library exists in the same directory as the depending
file, the dependency is resolved to that file.
4. Otherwise, if the library exists in either the operating system's
``system32`` directory or the ``Windows`` directory, in that order, the
dependency is resolved to that file.
5. Otherwise, if the library exists in one of the directories specified by
``DIRECTORIES``, in the order they are listed, the dependency is resolved
to that file. In this case, a warning is not issued, because searching
other directories is a normal part of Windows library resolution.
6. Otherwise, the dependency is unresolved.
On Apple platforms, library resolution works as follows:
1. If the dependency starts with ``@executable_path/``, and an
``EXECUTABLES`` argument is in the process of being resolved, and
replacing ``@executable_path/`` with the directory of the executable
yields an existing file, the dependency is resolved to that file.
2. Otherwise, if the dependency starts with ``@executable_path/``, and there
is a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/``
with the directory of the bundle executable yields an existing file, the
dependency is resolved to that file.
3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing
``@loader_path/`` with the directory of the depending file yields an
existing file, the dependency is resolved to that file.
4. Otherwise, if the dependency starts with ``@rpath/``, and replacing
``@rpath/`` with one of the ``RPATH`` entries of the depending file
yields an existing file, the dependency is resolved to that file.
Note that ``RPATH`` entries that start with ``@executable_path/`` or
``@loader_path/`` also have these items replaced with the appropriate
path.
5. Otherwise, if the dependency is an absolute file that exists,
the dependency is resolved to that file.
6. Otherwise, the dependency is unresolved.
This function accepts several variables that determine which tool is used for
dependency resolution:
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
Determines which operating system and executable format the files are built
for. This could be one of several values:
* ``linux+elf``
* ``windows+pe``
* ``macos+macho``
If this variable is not specified, it is determined automatically by system
introspection.
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
Determines the tool to use for dependency resolution. It could be one of
several values, depending on the value of
:variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`:
================================================= =============================================
``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL``
================================================= =============================================
``linux+elf`` ``objdump``
``windows+pe`` ``objdump`` or ``dumpbin``
``macos+macho`` ``otool``
================================================= =============================================
If this variable is not specified, it is determined automatically by system
introspection.
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
Determines the path to the tool to use for dependency resolution. This is
the actual path to ``objdump``, ``dumpbin``, or ``otool``.
If this variable is not specified, it is determined by the value of
``CMAKE_OBJDUMP`` if set, else by system introspection.
.. versionadded:: 3.18
Use ``CMAKE_OBJDUMP`` if set.
Writing
^^^^^^^
@ -506,6 +192,10 @@ Writing
With ``TOUCH`` and ``TOUCH_NOCREATE``, the contents of an existing file
will not be modified.
.. versionchanged:: 3.30
``<files>`` can be an empty list. CMake 3.29 and earlier required
at least one file to be given.
.. signature::
file(GENERATE [...])
@ -712,6 +402,10 @@ Filesystem
Create the given directories and their parents as needed.
.. versionchanged:: 3.30
``<directories>`` can be an empty list. CMake 3.29 and earlier required
at least one directory to be given.
.. signature::
file(REMOVE <files>...)
file(REMOVE_RECURSE <files>...)
@ -1097,6 +791,15 @@ Transfer
is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable
will be used instead.
``TLS_VERSION <min>``
.. versionadded:: 3.30
Specify minimum TLS version for ``https://`` URLs.
If this option is not specified, the value of the
:variable:`CMAKE_TLS_VERSION` variable or :envvar:`CMAKE_TLS_VERSION`
environment variable will be used instead.
See :variable:`CMAKE_TLS_VERSION` for allowed values.
``TLS_VERIFY <ON|OFF>``
Specify whether to verify the server certificate for ``https://`` URLs.
The default is to *not* verify. If this option is not specified, the
@ -1266,3 +969,323 @@ Archiving
timestamp instead of extracting file timestamps from the archive.
With ``VERBOSE``, the command will produce verbose output.
Handling Runtime Binaries
^^^^^^^^^^^^^^^^^^^^^^^^^
.. signature::
file(GET_RUNTIME_DEPENDENCIES [...])
.. versionadded:: 3.16
Recursively get the list of libraries depended on by the given files:
.. code-block:: cmake
file(GET_RUNTIME_DEPENDENCIES
[RESOLVED_DEPENDENCIES_VAR <deps_var>]
[UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
[CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
[EXECUTABLES <executable_files>...]
[LIBRARIES <library_files>...]
[MODULES <module_files>...]
[DIRECTORIES <directories>...]
[BUNDLE_EXECUTABLE <bundle_executable_file>]
[PRE_INCLUDE_REGEXES <regexes>...]
[PRE_EXCLUDE_REGEXES <regexes>...]
[POST_INCLUDE_REGEXES <regexes>...]
[POST_EXCLUDE_REGEXES <regexes>...]
[POST_INCLUDE_FILES <files>...]
[POST_EXCLUDE_FILES <files>...]
)
Please note that this sub-command is not intended to be used in project mode.
It is intended for use at install time, either from code generated by the
:command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by
the project via :command:`install(CODE)` or :command:`install(SCRIPT)`.
For example:
.. code-block:: cmake
install(CODE [[
file(GET_RUNTIME_DEPENDENCIES
# ...
)
]])
The arguments are as follows:
``RESOLVED_DEPENDENCIES_VAR <deps_var>``
Name of the variable in which to store the list of resolved dependencies.
``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>``
Name of the variable in which to store the list of unresolved
dependencies. If this variable is not specified, and there are any
unresolved dependencies, an error is issued.
``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>``
Variable prefix in which to store conflicting dependency information.
Dependencies are conflicting if two files with the same name are found in
two different directories. The list of filenames that conflict are stored
in ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list
of paths that were found for that filename are stored in
``<conflicting_deps_prefix>_<filename>``.
``EXECUTABLES <executable_files>...``
List of executable files to read for dependencies. These are executables
that are typically created with :command:`add_executable`, but they do
not have to be created by CMake. On Apple platforms, the paths to these
files determine the value of ``@executable_path`` when recursively
resolving the libraries. Specifying any kind of library (``STATIC``,
``MODULE``, or ``SHARED``) here will result in undefined behavior.
``LIBRARIES <library_files>...``
List of library files to read for dependencies. These are libraries that
are typically created with :command:`add_library(SHARED)`, but they do
not have to be created by CMake. Specifying ``STATIC`` libraries,
``MODULE`` libraries, or executables here will result in undefined
behavior.
``MODULES <module_files>...``
List of loadable module files to read for dependencies. These are modules
that are typically created with :command:`add_library(MODULE)`, but they
do not have to be created by CMake. They are typically used by calling
``dlopen()`` at runtime rather than linked at link time with ``ld -l``.
Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables
here will result in undefined behavior.
``DIRECTORIES <directories>...``
List of additional directories to search for dependencies. On Linux
platforms, these directories are searched if the dependency is not found
in any of the other usual paths. If it is found in such a directory, a
warning is issued, because it means that the file is incomplete (it does
not list all of the directories that contain its dependencies).
On Windows platforms, these directories are searched if the dependency
is not found in any of the other search paths, but no warning is issued,
because searching other paths is a normal part of Windows dependency
resolution. On Apple platforms, this argument has no effect.
``BUNDLE_EXECUTABLE <bundle_executable_file>``
Executable to treat as the "bundle executable" when resolving libraries.
On Apple platforms, this argument determines the value of
``@executable_path`` when recursively resolving libraries for
``LIBRARIES`` and ``MODULES`` files. It has no effect on ``EXECUTABLES``
files. On other platforms, it has no effect. This is typically (but not
always) one of the executables in the ``EXECUTABLES`` argument which
designates the "main" executable of the package.
The following arguments specify filters for including or excluding libraries
to be resolved. See below for a full description of how they work.
``PRE_INCLUDE_REGEXES <regexes>...``
List of pre-include regexes through which to filter the names of
not-yet-resolved dependencies.
``PRE_EXCLUDE_REGEXES <regexes>...``
List of pre-exclude regexes through which to filter the names of
not-yet-resolved dependencies.
``POST_INCLUDE_REGEXES <regexes>...``
List of post-include regexes through which to filter the names of
resolved dependencies.
``POST_EXCLUDE_REGEXES <regexes>...``
List of post-exclude regexes through which to filter the names of
resolved dependencies.
``POST_INCLUDE_FILES <files>...``
.. versionadded:: 3.21
List of post-include filenames through which to filter the names of
resolved dependencies. Symlinks are resolved when attempting to match
these filenames.
``POST_EXCLUDE_FILES <files>...``
.. versionadded:: 3.21
List of post-exclude filenames through which to filter the names of
resolved dependencies. Symlinks are resolved when attempting to match
these filenames.
These arguments can be used to exclude unwanted system libraries when
resolving the dependencies, or to include libraries from a specific
directory. The filtering works as follows:
1. If the not-yet-resolved dependency matches any of the
``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency
resolution proceeds to step 4.
2. If the not-yet-resolved dependency matches any of the
``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency.
3. Otherwise, dependency resolution proceeds.
4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according
to the linking rules of the platform (see below).
5. If the dependency is found, and its full path matches one of the
``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added
to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)``
recursively resolves that library's own dependencies. Otherwise, resolution
proceeds to step 6.
6. If the dependency is found, but its full path matches one of the
``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the
resolved dependencies, and dependency resolution stops for that dependency.
7. If the dependency is found, and its full path does not match either
``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``,
or ``POST_EXCLUDE_FILES``, the full path is added to the resolved
dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves
that library's own dependencies.
Different platforms have different rules for how dependencies are resolved.
These specifics are described here.
On Linux platforms, library resolution works as follows:
1. If the depending file does not have any ``RUNPATH`` entries, and the
library exists in one of the depending file's ``RPATH`` entries, or its
parents', in that order, the dependency is resolved to that file.
2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the
library exists in one of those entries, the dependency is resolved to that
file.
3. Otherwise, if the library exists in one of the directories listed by
``ldconfig``, the dependency is resolved to that file.
4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries,
the dependency is resolved to that file. In this case, a warning is
issued, because finding a file in one of the ``DIRECTORIES`` means that
the depending file is not complete (it does not list all the directories
from which it pulls dependencies).
5. Otherwise, the dependency is unresolved.
On Windows platforms, library resolution works as follows:
1. DLL dependency names are converted to lowercase for matching filters.
Windows DLL names are case-insensitive, and some linkers mangle the
case of the DLL dependency names. However, this makes it more difficult
for ``PRE_INCLUDE_REGEXES``, ``PRE_EXCLUDE_REGEXES``,
``POST_INCLUDE_REGEXES``, and ``POST_EXCLUDE_REGEXES`` to properly
filter DLL names - every regex would have to check for both uppercase
and lowercase letters. For example:
.. code-block:: cmake
file(GET_RUNTIME_DEPENDENCIES
# ...
PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
)
Converting the DLL name to lowercase allows the regexes to only match
lowercase names, thus simplifying the regex. For example:
.. code-block:: cmake
file(GET_RUNTIME_DEPENDENCIES
# ...
PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
)
This regex will match ``mylibrary.dll`` regardless of how it is cased,
either on disk or in the depending file. (For example, it will match
``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.)
.. versionchanged:: 3.27
The conversion to lowercase only applies while matching filters.
Results reported after filtering case-preserve each DLL name as it is
found on disk, if resolved, and otherwise as it is referenced by the
dependent binary.
Prior to CMake 3.27, the results were reported with lowercase DLL
file names, but the directory portion retained its casing.
2. (**Not yet implemented**) If the depending file is a Windows Store app,
and the dependency is listed as a dependency in the application's package
manifest, the dependency is resolved to that file.
3. Otherwise, if the library exists in the same directory as the depending
file, the dependency is resolved to that file.
4. Otherwise, if the library exists in either the operating system's
``system32`` directory or the ``Windows`` directory, in that order, the
dependency is resolved to that file.
5. Otherwise, if the library exists in one of the directories specified by
``DIRECTORIES``, in the order they are listed, the dependency is resolved
to that file. In this case, a warning is not issued, because searching
other directories is a normal part of Windows library resolution.
6. Otherwise, the dependency is unresolved.
On Apple platforms, library resolution works as follows:
1. If the dependency starts with ``@executable_path/``, and an
``EXECUTABLES`` argument is in the process of being resolved, and
replacing ``@executable_path/`` with the directory of the executable
yields an existing file, the dependency is resolved to that file.
2. Otherwise, if the dependency starts with ``@executable_path/``, and there
is a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/``
with the directory of the bundle executable yields an existing file, the
dependency is resolved to that file.
3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing
``@loader_path/`` with the directory of the depending file yields an
existing file, the dependency is resolved to that file.
4. Otherwise, if the dependency starts with ``@rpath/``, and replacing
``@rpath/`` with one of the ``RPATH`` entries of the depending file
yields an existing file, the dependency is resolved to that file.
Note that ``RPATH`` entries that start with ``@executable_path/`` or
``@loader_path/`` also have these items replaced with the appropriate
path.
5. Otherwise, if the dependency is an absolute file that exists,
the dependency is resolved to that file.
6. Otherwise, the dependency is unresolved.
This function accepts several variables that determine which tool is used for
dependency resolution:
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
Determines which operating system and executable format the files are built
for. This could be one of several values:
* ``linux+elf``
* ``windows+pe``
* ``macos+macho``
If this variable is not specified, it is determined automatically by system
introspection.
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
Determines the tool to use for dependency resolution. It could be one of
several values, depending on the value of
:variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`:
================================================= =============================================
``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL``
================================================= =============================================
``linux+elf`` ``objdump``
``windows+pe`` ``objdump`` or ``dumpbin``
``macos+macho`` ``otool``
================================================= =============================================
If this variable is not specified, it is determined automatically by system
introspection.
.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
Determines the path to the tool to use for dependency resolution. This is
the actual path to ``objdump``, ``dumpbin``, or ``otool``.
If this variable is not specified, it is determined by the value of
``CMAKE_OBJDUMP`` if set, else by system introspection.
.. versionadded:: 3.18
Use ``CMAKE_OBJDUMP`` if set.

30
Help/command/find_package.rst
View File

@ -21,6 +21,30 @@ Find a package (usually provided by something external to the project),
and load its package-specific details. Calls to this command can also
be intercepted by :ref:`dependency providers <dependency_providers>`.
Typical Usage
^^^^^^^^^^^^^
Most calls to ``find_package()`` typically have the following form:
.. parsed-literal::
find_package(<PackageName> [<version>] [REQUIRED] [COMPONENTS <components>...])
The ``<PackageName>`` is the only mandatory argument. The ``<version>`` is
often omitted, and ``REQUIRED`` should be given if the project cannot be
configured successfully without the package. Some more complicated packages
support components which can be selected with the ``COMPONENTS`` keyword, but
most packages don't have that level of complexity.
The above is a reduced form of the `basic signature`_. Where possible,
projects should find packages using this form. This reduces complexity and
maximizes the ways in which the package can be found or provided.
Understanding the `basic signature`_ should be enough for general usage of
``find_package()``. Project maintainers who intend to provide a config
package should understand the bigger picture, as explained in
:ref:`Full Signature` and all subsequent sections on this page.
Search Modes
^^^^^^^^^^^^
@ -86,12 +110,6 @@ first before falling back to Module mode. The basic signature can also be
forced to use only Module mode with a ``MODULE`` keyword. If the
`full signature`_ is used, the command only searches in Config mode.
Where possible, user code should generally look for packages using the
`basic signature`_, since that allows the package to be found with any mode.
Project maintainers wishing to provide a config package should understand
the bigger picture, as explained in :ref:`Full Signature` and all subsequent
sections on this page.
.. _`basic signature`:
Basic Signature

2
Help/command/macro.rst
View File

@ -61,7 +61,7 @@ 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}``,
into the macro as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``,
... which will have the actual values of the arguments passed in.
This facilitates creating macros with optional arguments.

15
Help/command/string.rst
View File

@ -136,15 +136,16 @@ The following characters have special meaning in regular expressions:
or ``\\`` for a literal backslash ``\``. Escaping a non-special
character is unnecessary but allowed, e.g. ``\a`` matches ``a``.
``[ ]``
Matches any character(s) inside the brackets
Matches any character(s) inside the brackets.
To match a literal ``]``, make it the first character, e.g., ``[]ab]``.
``[^ ]``
Matches any character(s) not inside the brackets
Matches any character(s) not inside the brackets.
To not match a literal ``]``, make it the first character, e.g., ``[^]ab]``.
``-``
Inside brackets, specifies an inclusive range between
characters on either side e.g. ``[a-f]`` is ``[abcdef]``
To match a literal ``-`` using brackets, make it the first
or the last character e.g. ``[+*/-]`` matches basic
mathematical operators.
Inside brackets, specifies an inclusive range between characters on
either side, e.g., ``[a-f]`` is ``[abcdef]``.
To match a literal ``-`` using brackets, make it the first or the last
character, e.g., ``[+*/-]`` matches basic mathematical operators.
``*``
Matches preceding pattern zero or more times
``+``

2
Help/command/target_compile_definitions.rst
View File

@ -15,7 +15,7 @@ named ``<target>`` must have been created by a command such as
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
specify the :ref:`scope <Target Command Scope>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_DEFINITIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``.

2
Help/command/target_compile_options.rst
View File

@ -28,7 +28,7 @@ instead of being appended. See policy :policy:`CMP0101` which affects
whether ``BEFORE`` will be ignored in certain cases.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
specify the :ref:`scope <Target Command Scope>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_OPTIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``.

2
Help/command/target_include_directories.rst
View File

@ -18,7 +18,7 @@ By using ``AFTER`` or ``BEFORE`` explicitly, you can select between appending
and prepending, independent of the default.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify
the :ref:`scope <Target Usage Requirements>` of the following arguments.
the :ref:`scope <Target Command Scope>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`INCLUDE_DIRECTORIES`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``.

2
Help/command/target_link_directories.rst
View File

@ -21,7 +21,7 @@ The named ``<target>`` must have been created by a command such as
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the :ref:`scope <Target Usage Requirements>` of the items that follow
specify the :ref:`scope <Target Command Scope>` of the items that follow
them. ``PRIVATE`` and ``PUBLIC`` items will populate the
:prop_tgt:`LINK_DIRECTORIES` property of ``<target>``. ``PUBLIC`` and
``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_LINK_DIRECTORIES`

2
Help/command/target_link_libraries.rst
View File

@ -153,7 +153,7 @@ Libraries for a Target and/or its Dependents
[<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE``
:ref:`scope <Target Usage Requirements>` keywords can be used to
:ref:`scope <Target Command Scope>` 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

2
Help/command/target_link_options.rst
View File

@ -32,7 +32,7 @@ If ``BEFORE`` is specified, the content will be prepended to the property
instead of being appended.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
specify the :ref:`scope <Target Command Scope>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`LINK_OPTIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``.

2
Help/command/target_precompile_headers.rst
View File

@ -25,7 +25,7 @@ The named ``<target>`` must have been created by a command such as
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
specify the :ref:`scope <Target Command Scope>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`PRECOMPILE_HEADERS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>``

2
Help/command/target_sources.rst
View File

@ -22,7 +22,7 @@ The named ``<target>`` must have been created by a command such as
``<target>`` can be a custom target.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the :ref:`scope <Target Usage Requirements>` of the source file paths
specify the :ref:`scope <Target Command Scope>` of the source file paths
(``<items>``) that follow them. ``PRIVATE`` and ``PUBLIC`` items will
populate the :prop_tgt:`SOURCES` property of ``<target>``, which are used when
building the target itself. ``PUBLIC`` and ``INTERFACE`` items will populate the

16
Help/command/try_compile.rst
View File

@ -47,6 +47,11 @@ below for the meaning of other options.
:ref:`configure-log try_compile event <try_compile configure-log event>`
if the ``NO_LOG`` option is not specified.
.. versionadded:: 3.30
If the :prop_gbl:`PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE` global
property is set to true, :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` is
propagated into the project's build configuration.
This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.
@ -156,8 +161,9 @@ The options for the above signatures are:
Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed
to the :manual:`cmake(1)` command-line used to drive the test build.
The above example shows how values for variables
``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
are used.
``COMPILE_DEFINITIONS``, ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``,
``LINK_LIBRARIES``, and ``LINK_OPTIONS`` are used. Compiler options
can be passed in like `CMAKE_FLAGS -DCOMPILE_DEFINITIONS=-Werror`.
``COMPILE_DEFINITIONS <defs>...``
Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions`
@ -387,6 +393,12 @@ configuration:
:variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify the MSVC debug
information format.
.. versionadded:: 3.30
If the :prop_gbl:`PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE` global
property is set to true, :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` is
propagated into the test project's build configuration when using the
:ref:`whole-project signature <Try Compiling Whole Projects>`.
See Also
^^^^^^^^

6
Help/cpack_gen/innosetup.rst
View File

@ -12,7 +12,11 @@ The generator provides a lot of options like components. Unfortunately, not
all features (e.g. component dependencies) are currently supported by
Inno Setup and they're ignored by the generator for now.
CPack requires Inno Setup 6 or greater and only works on Windows.
CPack requires Inno Setup 6 or greater.
.. versionadded:: 3.30
The generator is now available on non-Windows hosts,
but requires Wine to run the Inno Setup tools.
Variables specific to CPack Inno Setup generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

228
Help/cpack_gen/nuget.rst
View File

@ -34,6 +34,17 @@ List of CPack NuGet generator specific variables:
:Mandatory: No
:Default: ``OFF``
.. variable:: CPACK_NUGET_PACKAGE_DEBUG
Enable debug messages while executing CPack NuGet generator.
:Mandatory: No
:Default: ``OFF``
Required metadata variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. variable:: CPACK_NUGET_PACKAGE_NAME
CPACK_NUGET_<compName>_PACKAGE_NAME
@ -74,22 +85,16 @@ List of CPack NuGet generator specific variables:
:Mandatory: Yes
:Default: :variable:`CPACK_PACKAGE_VENDOR`
.. variable:: CPACK_NUGET_PACKAGE_TITLE
CPACK_NUGET_<compName>_PACKAGE_TITLE
A human-friendly title of the package, typically used in UI displays
as on nuget.org_ and the Package Manager in Visual Studio. If not
specified, the package ID is used.
:Mandatory: No
:Default:
- :variable:`CPACK_COMPONENT_<compName>_DISPLAY_NAME`,
- :variable:`!CPACK_COMPONENT_GROUP_<groupName>_DISPLAY_NAME`
Optional metadata variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. variable:: CPACK_NUGET_PACKAGE_OWNERS
CPACK_NUGET_<compName>_PACKAGE_OWNERS
.. deprecated:: 3.30
Use authors (:variable:`CPACK_NUGET_PACKAGE_AUTHORS`) instead.
A comma-separated list of the package creators using profile names
on nuget.org_. This is often the same list as in authors,
and is ignored when uploading the package to nuget.org_.
@ -120,6 +125,21 @@ List of CPack NuGet generator specific variables:
:Mandatory: No
:Default: None
:Supported: NuGet 4.9.0 and above
.. variable:: CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME
CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME
.. versionadded:: 3.20
The package's license file in :file:`.txt` or :file:`.md` format.
If :variable:`!CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` is specified,
:variable:`!CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` is ignored.
:Mandatory: No
:Default: None
:Supported: NuGet 4.9.0 and above
.. variable:: CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION
CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION
@ -139,19 +159,6 @@ List of CPack NuGet generator specific variables:
:Mandatory: No
:Default: None
.. variable:: CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME
CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME
The package's license file in :file:`.txt` or :file:`.md` format.
If :variable:`!CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` is specified,
:variable:`!CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` is ignored.
.. versionadded:: 3.20
:Mandatory: No
:Default: None
.. variable:: CPACK_NUGET_PACKAGE_ICONURL
CPACK_NUGET_<compName>_PACKAGE_ICONURL
@ -164,14 +171,6 @@ List of CPack NuGet generator specific variables:
:Mandatory: No
:Default: None
.. variable:: CPACK_NUGET_PACKAGE_REQUIRE_LICENSE_ACCEPTANCE
When set to a true value, the user will be prompted to accept the license
before installing the package.
:Mandatory: No
:Default: None
.. variable:: CPACK_NUGET_PACKAGE_ICON
CPACK_NUGET_<compName>_PACKAGE_ICON
@ -182,10 +181,36 @@ List of CPack NuGet generator specific variables:
:Mandatory: No
:Default: None
:Supported: NuGet 5.3.0 and above
.. variable:: CPACK_NUGET_PACKAGE_README
CPACK_NUGET_<compName>_PACKAGE_README
.. versionadded:: 3.30
The package path relative to the root of the package to a readme file.
Supported file formats include only Markdown (``*.md``).
:Mandatory: No
:Default: None
:Supported: NuGet 5.10.0 preview 2 and above
.. variable:: CPACK_NUGET_PACKAGE_REQUIRE_LICENSE_ACCEPTANCE
When set to a true value, the user will be prompted to accept the license
before installing the package.
:Mandatory: No
:Default: None
.. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION_SUMMARY
CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION_SUMMARY
.. deprecated:: 3.30
Summary is being deprecated. Use description
(:variable:`CPACK_NUGET_PACKAGE_DESCRIPTION`) instead.
A short description of the package for UI display. If omitted, a
truncated version of description is used.
@ -230,10 +255,75 @@ List of CPack NuGet generator specific variables:
:Mandatory: No
:Default: None
.. variable:: CPACK_NUGET_PACKAGE_REPOSITORY_URL
CPACK_NUGET_<compName>_REPOSITORY_URL
.. versionadded:: 3.30
Repository metadata allows you to map the ``*.nupkg`` to the repository
that built it. This should be a publicly available URL that can be invoked
directly by a version control software. It should not be an HTML page as
this is meant for the computer.
:Mandatory: No
:Default: None
:Supported: NuGet 4.0 and above
.. variable:: CPACK_NUGET_PACKAGE_REPOSITORY_TYPE
CPACK_NUGET_<compName>_REPOSITORY_TYPE
.. versionadded:: 3.30
A type of the VCS repository. When uploading a package to nuget.org_, the
type is limited to 100 characters.
:Mandatory: Yes, if repository URL has been specified
:Default: None
:Supported: NuGet 4.0 and above
.. variable:: CPACK_NUGET_PACKAGE_REPOSITORY_BRANCH
CPACK_NUGET_<compName>_REPOSITORY_BRANCH
.. versionadded:: 3.30
A VSC branch name to build the package.
:Mandatory: No
:Default: None
:Supported: NuGet 4.6 and above
.. variable:: CPACK_NUGET_PACKAGE_REPOSITORY_COMMIT
CPACK_NUGET_<compName>_REPOSITORY_COMMIT
.. versionadded:: 3.30
A SHA-1 hash of the commit to build the package.
:Mandatory: No
:Default: None
:Supported: NuGet 4.6 and above
.. variable:: CPACK_NUGET_PACKAGE_TITLE
CPACK_NUGET_<compName>_PACKAGE_TITLE
A human-friendly title of the package, typically used in UI displays
as on nuget.org_ and the Package Manager in Visual Studio. If not
specified, the package ID is used.
:Mandatory: No
:Default:
- :variable:`CPACK_COMPONENT_<compName>_DISPLAY_NAME`,
- :variable:`!CPACK_COMPONENT_GROUP_<groupName>_DISPLAY_NAME`
Dependencies specification
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES
CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES
A list of package dependencies.
A list of default (not framework-specific) package dependencies.
:Mandatory: No
:Default: None
@ -242,23 +332,85 @@ List of CPack NuGet generator specific variables:
CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES_<dependency>_VERSION
A `version specification`_ for the particular dependency, where
``<dependency>`` is an item of the dependency list (see above)
transformed with :command:`string(MAKE_C_IDENTIFIER)` command.
``<dependency>`` is an item of the dependency list (see above).
:Mandatory: No
:Default: None
.. variable:: CPACK_NUGET_PACKAGE_DEBUG
.. variable:: CPACK_NUGET_PACKAGE_TFMS
CPACK_NUGET_<compName>_PACKAGE_TFMS
Enable debug messages while executing CPack NuGet generator.
.. versionadded:: 3.30
A list of Target Framework Monikers (TFMs) for the package, e.g., "net47;netcoreapp21".
For each of these TFMs a `dependency group`_ will be generated in the dependencies block of the NuGet
package. Framework-specific dependencies can be added to these groups with the TFM
dependency lists (see below).
This variable is particularly useful for fixing warnings `NU5128`_.
:Mandatory: No
:Default: ``OFF``
:Default: None
.. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES_<tfm>
CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES_<tfm>
.. versionadded:: 3.30
A list of package dependencies that apply specifically to the ``<tfm>`` framework, where ``<tfm>``
is an item from the TFMs list (see above).
:Mandatory: No
:Default: None
.. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES_<tfm>_<dependency>_VERSION
CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES_<tfm>_<dependency>_VERSION
.. versionadded:: 3.30
A `version specification`_ for the particular framework-specific dependency, where
``<dependency>`` is an item of the ``<tfm>``-specific dependency list (see above).
:Mandatory: No
:Default: None
Example usage
^^^^^^^^^^^^^
.. code-block:: cmake
set(CPACK_GENERATOR NuGet)
# Set up package metadata
set(CPACK_PACKAGE_NAME SamplePackage)
set(CPACK_PACKAGE_VERSION "1.0.0")
set(CPACK_PACKAGE_VENDOR "Example Inc")
set(CPACK_NUGET_PACKAGE_AUTHORS "ExampleInc")
set(CPACK_PACKAGE_DESCRIPTION "A .NET wrapper around the foobar library for frobbling bratchens")
set(CPACK_PACKAGE_HOMEPAGE_URL "https://www.example.com")
set(CPACK_NUGET_PACKAGE_REPOSITORY_URL "https://github.com/example/libfoobar.git")
set(CPACK_NUGET_PACKAGE_REPOSITORY_TYPE git)
set(CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION "MIT")
# Set up dependencies
set(CPACK_NUGET_PACKAGE_TFMS "net4;net6.0")
set(CPACK_NUGET_PACKAGE_DEPENDENCIES_net4 "Foo;Bar")
# NB: If a version number is omitted, the dependency will not be created
set(CPACK_NUGET_PACKAGE_DEPENDENCIES_net4_Foo_VERSION "1.23")
set(CPACK_NUGET_PACKAGE_DEPENDENCIES_net4_Bar_VERSION "4.3.2")
# NB: General dependencies (not framework-specific) go in this variable
set(CPACK_NUGET_PACKAGE_DEPENDENCIES "Baz")
set(CPACK_NUGET_PACKAGE_DEPENDENCIES_Baz_VERSION "9.8.6")
# NB: Since "net6.0" was listed but no dependencies have been specified, an empty group
# will be added to the nuspec file for this framework. This can be used to address warning NU5128.
include(CPack)
.. _nuget.org: https://www.nuget.org
.. _version specification: https://learn.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges
.. _SPDX license identifier: https://spdx.org/licenses
.. _SPDX specification: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions
.. _dependency group: https://learn.microsoft.com/en-us/nuget/reference/nuspec#dependency-groups
.. _NU5128: https://learn.microsoft.com/en-us/nuget/reference/errors-and-warnings/nu5128
.. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec

160
Help/cpack_gen/wix.rst
View File

@ -1,10 +1,103 @@
CPack WIX Generator
-------------------
CPack WIX generator specific options
Use the `WiX Toolset`_ to produce a Windows Installer ``.msi`` database.
.. _`WiX Toolset`: https://wixtoolset.org/
.. versionadded:: 3.7
Support :variable:`CPACK_COMPONENT_<compName>_DISABLED` variable.
The :variable:`CPACK_COMPONENT_<compName>_DISABLED` variable is now
supported.
WiX Toolsets
^^^^^^^^^^^^
CPack selects one of the following variants of the WiX Toolset
based on the :variable:`CPACK_WIX_VERSION` variable:
* `WiX .NET Tools`_
* `WiX Toolset v3`_
WiX .NET Tools
""""""""""""""
Packaging is performed using the following tools:
``wix build``
Build WiX source files directly into a Windows Installer ``.msi`` database.
Invocations may be customized using tool-specific variables:
* :variable:`CPACK_WIX_BUILD_EXTENSIONS <CPACK_WIX_<TOOL>_EXTENSIONS>`
* :variable:`CPACK_WIX_BUILD_EXTRA_FLAGS <CPACK_WIX_<TOOL>_EXTRA_FLAGS>`
WiX extensions must be named with the form ``WixToolset.<Name>.wixext``.
CPack expects the ``wix`` .NET tool to be available for command-line use
with any required WiX extensions already installed. Be sure the ``wix``
version is compatible with :variable:`CPACK_WIX_VERSION`, and that WiX
extension versions match the ``wix`` tool version. For example:
1. Install the ``wix`` command-line tool using ``dotnet``.
To install ``wix`` globally for the current user:
.. code-block:: bat
dotnet tool install --global wix --version 4.0.4
This places ``wix.exe`` in ``%USERPROFILE%\.dotnet\tools`` and adds
the directory to the current user's ``PATH`` environment variable.
Or, to install ``wix`` in a specific path, e.g., in ``c:\WiX``:
.. code-block:: bat
dotnet tool install --tool-path c:\WiX wix --version 4.0.4
This places ``wix.exe`` in ``c:\WiX``, but does *not* add it to the
current user's ``PATH`` environment variable. The ``WIX`` environment
variable may be set to tell CPack where to find the tool,
e.g., ``set WIX=c:\WiX``.
2. Add the WiX ``UI`` extension, needed by CPack's default WiX template:
.. code-block:: bat
wix extension add --global WixToolset.UI.wixext/4.0.4
Extensions added globally are stored in ``%USERPROFILE%\.wix``, or if the
``WIX_EXTENSIONS`` environment variable is set, in ``%WIX_EXTENSIONS%\.wix``.
WiX Toolset v3
""""""""""""""
Packaging is performed using the following tools:
``candle``
Compiles WiX source files into ``.wixobj`` files.
Invocations may be customized using tool-specific variables:
* :variable:`CPACK_WIX_CANDLE_EXTENSIONS <CPACK_WIX_<TOOL>_EXTENSIONS>`
* :variable:`CPACK_WIX_CANDLE_EXTRA_FLAGS <CPACK_WIX_<TOOL>_EXTRA_FLAGS>`
``light``
Links ``.wixobj`` files into a Windows Installer ``.msi`` database.
Invocations may be customized using tool-specific variables:
* :variable:`CPACK_WIX_LIGHT_EXTENSIONS <CPACK_WIX_<TOOL>_EXTENSIONS>`
* :variable:`CPACK_WIX_LIGHT_EXTRA_FLAGS <CPACK_WIX_<TOOL>_EXTRA_FLAGS>`
CPack invokes both tools as needed. Intermediate ``.wixobj`` files
are considered implementation details.
WiX extensions must be named with the form ``Wix<Name>Extension``.
CPack expects the above tools to be available for command-line
use via the ``PATH``. Or, if the ``WIX`` environment variable is set,
CPack looks for the tools in ``%WIX%`` and ``%WIX%\bin``.
Variables specific to CPack WIX generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -12,6 +105,19 @@ Variables specific to CPack WIX generator
The following variables are specific to the installers built on
Windows using WiX.
.. variable:: CPACK_WIX_VERSION
.. versionadded:: 3.30
Specify the version of WiX Toolset for which the configuration
is written. The value must be one of
``4``
Package using `WiX .NET Tools`_.
``3``
Package using `WiX Toolset v3`_. This is the default.
.. variable:: CPACK_WIX_UPGRADE_GUID
Upgrade GUID (``Product/@UpgradeCode``)
@ -68,8 +174,13 @@ Windows using WiX.
.. variable:: CPACK_WIX_UI_REF
This variable allows you to override the Id of the ``<UIRef>`` element
in the WiX template.
Specify the WiX ``UI`` extension's dialog set:
* With `WiX .NET Tools`_, this is the Id of the
``<ui:WixUI>`` element in the default WiX template.
* With `WiX Toolset v3`_, this is the Id of the
``<UIRef>`` element in the default WiX template.
The default is ``WixUI_InstallDir`` in case no CPack components have
been defined and ``WixUI_FeatureTree`` otherwise.
@ -107,7 +218,7 @@ Windows using WiX.
Language(s) of the installer
Languages are compiled into the WixUI extension library. To use them,
Languages are compiled into the Wix ``UI`` extension library. To use them,
simply provide the name of the culture. If you specify more than one
culture identifier in a comma or semicolon delimited list, the first one
that is found will be used. You can find a list of supported languages at:
@ -196,39 +307,35 @@ Windows using WiX.
Extra WiX source files
This variable provides an optional list of extra WiX source files (.wxs)
that should be compiled and linked. The full path to source files is
required.
This variable provides an optional list of extra WiX source files (``.wxs``)
that should be compiled and linked. The paths must be absolute.
.. variable:: CPACK_WIX_EXTRA_OBJECTS
Extra WiX object files or libraries
Extra WiX object files or libraries to use with `WiX Toolset v3`_.
This variable provides an optional list of extra WiX object (.wixobj)
and/or WiX library (.wixlib) files. The full path to objects and libraries
is required.
This variable provides an optional list of extra WiX object (``.wixobj``)
and/or WiX library (``.wixlib``) files. The paths must be absolute.
.. variable:: CPACK_WIX_EXTENSIONS
This variable provides a list of additional extensions for the WiX
tools light and candle.
Specify a list of additional extensions for WiX tools.
See `WiX Toolsets`_ for extension naming patterns.
.. variable:: CPACK_WIX_<TOOL>_EXTENSIONS
This is the tool specific version of CPACK_WIX_EXTENSIONS.
``<TOOL>`` can be either LIGHT or CANDLE.
Specify a list of additional extensions for a specific WiX tool.
See `WiX Toolsets`_ for possible ``<TOOL>`` names.
.. variable:: CPACK_WIX_<TOOL>_EXTRA_FLAGS
This list variable allows you to pass additional
flags to the WiX tool ``<TOOL>``.
Specify a list of additional command-line flags for a specific WiX tool.
See `WiX Toolsets`_ for possible ``<TOOL>`` names.
Use it at your own risk.
Future versions of CPack may generate flags which may be in conflict
with your own flags.
``<TOOL>`` can be either LIGHT or CANDLE.
.. variable:: CPACK_WIX_CMAKE_PACKAGE_REGISTRY
If this variable is set the generated installer will create
@ -326,9 +433,9 @@ Windows using WiX.
.. versionadded:: 3.23
If this variable is set then the inclusion of WixUIExtensions is skipped,
i.e. the ``-ext "WixUIExtension"`` command line is not included during
the execution of the WiX light tool.
If this variable is set to true, the default inclusion of the WiX ``UI``
extension is skipped, i.e., the ``-ext WixUIExtension`` or
``-ext WixToolset.UI.wixext`` flag is not passed to WiX tools.
.. variable:: CPACK_WIX_ARCHITECTURE
@ -351,13 +458,18 @@ Windows using WiX.
administrative privileges. Start menu entries created by the
installer are visible to all users.
This is the default if :variable:`CPACK_WIX_VERSION` is set to any
value other than ``3``.
``perUser``
Not yet supported. This is reserved for future use.
``NONE``
Create an installer without any ``InstallScope`` attribute.
This is the default to preserve compatibility with CPack 3.28 and older.
If :variable:`CPACK_WIX_VERSION` is not set, or is set to ``3``, this
value is the default to preserve compatibility with 3.28 and lower.
Otherwise, this value is not supported.
.. deprecated:: 3.29

22
Help/dev/experimental.rst
View File

@ -38,3 +38,25 @@ When activated, this experimental feature provides the following:
* The package name associated with specific targets may be specified
using the ``CMAKE_EXPORT_FIND_PACKAGE_NAME`` variable and/or
``EXPORT_FIND_PACKAGE_NAME`` target property.
C++ ``import std`` support
==========================
In order to activate support for ``import std`` in C++23 and newer targets,
set
* variable ``CMAKE_EXPERIMENTAL_CXX_IMPORT_STD`` to
* value ``0e5b6991-d74f-4b3d-a41c-cf096e0b2508``.
This UUID may change in future versions of CMake. Be sure to use the value
documented here by the source tree of the version of CMake with which you are
experimenting. It must be set before the ``CXX`` toolchain is discovered by
CMake, usually as part of a :command:`project` call.
When activated, this experimental feature provides the following:
* The :prop_tgt:`CXX_MODULE_STD` target property and its initializing variable
:variable:`CMAKE_CXX_MODULE_STD`.
* Targets with the property set to a true value and at least ``cxx_std_23``
may use ``import std;`` in any scanned C++ source file.

2
Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst
View File

@ -4,7 +4,7 @@ CMAKE_MSVCIDE_RUN_PATH
.. include:: ENV_VAR.txt
Extra PATH locations for custom commands when using
:generator:`Visual Studio 9 2008` (or above) generators.
:generator:`Visual Studio 12 2013` (or above) generators.
The ``CMAKE_MSVCIDE_RUN_PATH`` environment variable sets the default value for
the :variable:`CMAKE_MSVCIDE_RUN_PATH` variable if not already explicitly set.

15
Help/envvar/CMAKE_TLS_VERIFY.rst Normal file
View File

@ -0,0 +1,15 @@
CMAKE_TLS_VERIFY
----------------
.. versionadded:: 3.30
.. include:: ENV_VAR.txt
Specify the default value for the :command:`file(DOWNLOAD)` and
:command:`file(UPLOAD)` commands' ``TLS_VERIFY`` option.
This environment variable is used if the option is not given
and the :variable:`CMAKE_TLS_VERIFY` cmake variable is not set.
This variable is also used by the :module:`ExternalProject` and
:module:`FetchContent` modules for internal calls to
:command:`file(DOWNLOAD)` and ``git clone``.

16
Help/envvar/CMAKE_TLS_VERSION.rst Normal file
View File

@ -0,0 +1,16 @@
CMAKE_TLS_VERSION
-----------------
.. versionadded:: 3.30
.. include:: ENV_VAR.txt
Specify the default value for the :command:`file(DOWNLOAD)` and
:command:`file(UPLOAD)` commands' ``TLS_VERSION`` option.
This environment variable is used if the option is not given
and the :variable:`CMAKE_TLS_VERSION` cmake variable is not set.
See that variable for allowed values.
This variable is also used by the :module:`ExternalProject` and
:module:`FetchContent` modules for internal calls to
:command:`file(DOWNLOAD)` and ``git clone``.

14
Help/envvar/OBJCFLAGS.rst Normal file
View File

@ -0,0 +1,14 @@
OBJCFLAGS
---------
.. versionadded:: 3.16
.. include:: ENV_VAR.txt
Add default compilation flags to be used when compiling ``Objective C`` files.
.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_OBJC_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``OBJC``
.. include:: LANG_FLAGS.txt
See also :variable:`CMAKE_OBJC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

14
Help/envvar/OBJCXXFLAGS.rst Normal file
View File

@ -0,0 +1,14 @@
OBJCXXFLAGS
-----------
.. versionadded:: 3.16
.. include:: ENV_VAR.txt
Add default compilation flags to be used when compiling ``Objective C++`` (.mm) files.
.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_OBJCXX_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``OBJCXX``
.. include:: LANG_FLAGS.txt
See also :variable:`CMAKE_OBJCXX_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

36
Help/generator/Ninja.rst
View File

@ -1,11 +1,35 @@
Ninja
-----
Generates ``build.ninja`` files.
Generates a ``build.ninja`` file into the build tree.
A ``build.ninja`` file is generated into the build tree. Use the ninja
program to build the project through the ``all`` target and install the
project through the ``install`` (or ``install/strip``) target.
Builtin Targets
^^^^^^^^^^^^^^^
``all``
Depends on all targets required by the project, except those with
:prop_tgt:`EXCLUDE_FROM_ALL` set to true.
``install``
Runs the install step.
``install/strip``
.. versionadded:: 3.7
Runs the install followed by a ``CMAKE_STRIP`` command, if any.
The ``CMAKE_STRIP`` variable will contain the platform's ``strip`` utility, which
removes symbols information from generated binaries.
``install/parallel``
.. versionadded:: 3.30
Created only if the :prop_gbl:`INSTALL_PARALLEL` global property is ``ON``.
Runs the install step for each subdirectory independently and in parallel.
For each subdirectory ``sub/dir`` of the project, additional targets
are generated:
@ -25,12 +49,10 @@ are generated:
``sub/dir/install/strip``
.. versionadded:: 3.7
Runs the install step in the subdirectory followed by a ``CMAKE_STRIP`` command,
if any.
The ``CMAKE_STRIP`` variable will contain the platform's ``strip`` utility, which
removes symbols information from generated binaries.
``sub/dir/test``
.. versionadded:: 3.7

44
Help/generator/Visual Studio 9 2008.rst
View File

@ -1,41 +1,9 @@
Visual Studio 9 2008
--------------------
Deprecated. Generates Visual Studio 9 2008 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 9 2008 tools
using the :generator:`Visual Studio 14 2015` generator (or above,
and with VS 10 2010 also installed) with
:variable:`CMAKE_GENERATOR_TOOLSET` set to ``v90``,
or by using the :generator:`NMake Makefiles` generator.
Platform Selection
^^^^^^^^^^^^^^^^^^
The default target platform name (architecture) is ``Win32``.
.. versionadded:: 3.1
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :option:`cmake -A` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 9 2008" -A Win32``
* ``cmake -G "Visual Studio 9 2008" -A x64``
* ``cmake -G "Visual Studio 9 2008" -A Itanium``
* ``cmake -G "Visual Studio 9 2008" -A <WinCE-SDK>``
(Specify a target platform matching a Windows CE SDK name.)
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of the generator name.
This is supported only for:
``Visual Studio 9 2008 Win64``
Specify target platform ``x64``.
``Visual Studio 9 2008 IA64``
Specify target platform ``Itanium``.
``Visual Studio 9 2008 <WinCE-SDK>``
Specify target platform matching a Windows CE SDK name.
Removed. This once generated Visual Studio 9 2008 project files, but
the generator has been removed since CMake 3.30. It is still possible
to build with VS 9 2008 tools using the :generator:`Visual Studio 14 2015`
generator (or above, and with VS 10 2010 also installed) with
:variable:`CMAKE_GENERATOR_TOOLSET` set to ``v90``, or by using
the :generator:`NMake Makefiles` generator.

2
Help/guide/tutorial/Adding Export Configuration.rst
View File

@ -46,7 +46,7 @@ you will see that CMake will generate an error that looks like:
which is prefixed in the source directory.
What CMake is trying to say is that during generating the export information
CMake is telling you that during the generation of the export information
it will export a path that is intrinsically tied to the current machine and
will not be valid on other machines. The solution to this is to update the
``MathFunctions`` :command:`target_include_directories` to understand that it

1
Help/guide/tutorial/Complete/CMakeLists.txt
View File

@ -89,6 +89,7 @@ include(InstallRequiredSystemLibraries)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
set(CPACK_GENERATOR "TGZ")
set(CPACK_SOURCE_GENERATOR "TGZ")
include(CPack)

10
Help/guide/tutorial/Packaging an Installer.rst
View File

@ -23,8 +23,9 @@ libraries that are needed by the project for the current platform. Next we set
some CPack variables to where we have stored the license and version
information for this project. The version information was set earlier in this
tutorial and the ``License.txt`` has been included in the top-level source
directory for this step. The :variable:`CPACK_SOURCE_GENERATOR` variable
selects a file format for the source package.
directory for this step. The :variable:`CPACK_GENERATOR` and
:variable:`CPACK_SOURCE_GENERATOR` variables select the generators used for
binary and source installations, respectively.
Finally we include the :module:`CPack module <CPack>` which will use these
variables and some other properties of the current system to setup an
@ -38,8 +39,9 @@ binary directory run:
cpack
To specify the generator, use the :option:`-G <cpack -G>` option. For multi-config builds,
use :option:`-C <cpack -C>` to specify the configuration. For example:
To specify the binary generator, use the :option:`-G <cpack -G>` option. For
multi-config builds, use :option:`-C <cpack -C>` to specify the configuration.
For example:
.. code-block:: console

1
Help/guide/tutorial/Step10/CMakeLists.txt
View File

@ -72,5 +72,6 @@ include(InstallRequiredSystemLibraries)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
set(CPACK_GENERATOR "TGZ")
set(CPACK_SOURCE_GENERATOR "TGZ")
include(CPack)

1
Help/guide/tutorial/Step11/CMakeLists.txt
View File

@ -80,5 +80,6 @@ include(InstallRequiredSystemLibraries)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
set(CPACK_GENERATOR "TGZ")
set(CPACK_SOURCE_GENERATOR "TGZ")
include(CPack)

2
Help/guide/tutorial/Step12/CMakeLists.txt
View File

@ -85,6 +85,8 @@ include(InstallRequiredSystemLibraries)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
set(CPACK_GENERATOR "TGZ")
set(CPACK_SOURCE_GENERATOR "TGZ")
include(CPack)
# install the configuration targets

4
Help/manual/OPTIONS_BUILD.txt
View File

@ -108,7 +108,9 @@
.. versionadded:: 3.21
Specify the cross compiling toolchain file, equivalent to setting
:variable:`CMAKE_TOOLCHAIN_FILE` variable.
:variable:`CMAKE_TOOLCHAIN_FILE` variable. Relative paths are interpreted as
relative to the build directory, and if not found, relative to the source
directory.
.. option:: --install-prefix <directory>

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

@ -162,103 +162,285 @@ or :command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``.
Build Specification and Usage Requirements
==========================================
The :command:`target_include_directories`, :command:`target_compile_definitions`
and :command:`target_compile_options` commands specify the build specifications
and the usage requirements of binary targets. The commands populate the
:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and
:prop_tgt:`COMPILE_OPTIONS` target properties respectively, and/or the
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`
and :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties.
Targets build according to their own
`build specification <Target Build Specification_>`_ in combination with
`usage requirements <Target Usage Requirements_>`_ propagated from their
link dependencies. Both may be specified using target-specific
`commands <Target Commands_>`_.
Each of the commands has a ``PRIVATE``, ``PUBLIC`` and ``INTERFACE`` mode. The
``PRIVATE`` mode populates only the non-``INTERFACE_`` variant of the target
property and the ``INTERFACE`` mode populates only the ``INTERFACE_`` variants.
The ``PUBLIC`` mode populates both variants of the respective target property.
Each command may be invoked with multiple uses of each keyword:
For example:
.. code-block:: cmake
target_compile_definitions(archive
PRIVATE BUILDING_WITH_LZMA
INTERFACE USING_ARCHIVE_LIB
)
add_library(archive SHARED archive.cpp zip.cpp)
if (LZMA_FOUND)
# Add a source implementing support for lzma.
target_sources(archive PRIVATE lzma.cpp)
# Compile the 'archive' library sources with '-DBUILDING_WITH_LZMA'.
target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
endif()
target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
add_executable(consumer consumer.cpp)
# Link 'consumer' to 'archive'. This also consumes its usage requirements,
# so 'consumer.cpp' is compiled with '-DUSING_ARCHIVE_LIB'.
target_link_libraries(consumer archive)
Target Commands
---------------
Target-specific commands populate the
`build specification <Target Build Specification_>`_ of `Binary Targets`_ and
`usage requirements <Target Usage Requirements_>`_ of `Binary Targets`_,
`Interface Libraries`_, and `Imported Targets`_.
.. _`Target Command Scope`:
Invocations must specify scope keywords, each affecting the visibility
of arguments following it. The scopes are:
``PUBLIC``
Populates both properties for `building <Target Build Specification_>`_
and properties for `using <Target Usage Requirements_>`_ a target.
``PRIVATE``
Populates only properties for `building <Target Build Specification_>`_
a target.
``INTERFACE``
Populates only properties for `using <Target Usage Requirements_>`_
a target.
The commands are:
:command:`target_compile_definitions`
Populates the :prop_tgt:`COMPILE_DEFINITIONS` build specification and
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` usage requirement properties.
For example, the call
.. code-block:: cmake
target_compile_definitions(archive
PRIVATE BUILDING_WITH_LZMA
INTERFACE USING_ARCHIVE_LIB
)
appends ``BUILDING_WITH_LZMA`` to the target's ``COMPILE_DEFINITIONS``
property and appends ``USING_ARCHIVE_LIB`` to the target's
``INTERFACE_COMPILE_DEFINITIONS`` property.
:command:`target_compile_options`
Populates the :prop_tgt:`COMPILE_OPTIONS` build specification and
:prop_tgt:`INTERFACE_COMPILE_OPTIONS` usage requirement properties.
:command:`target_compile_features`
.. versionadded:: 3.1
Populates the :prop_tgt:`COMPILE_FEATURES` build specification and
:prop_tgt:`INTERFACE_COMPILE_FEATURES` usage requirement properties.
:command:`target_include_directories`
Populates the :prop_tgt:`INCLUDE_DIRECTORIES` build specification
and :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` usage requirement
properties. With the ``SYSTEM`` option, it also populates the
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` usage requirement.
For convenience, the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable
may be enabled to add the source directory and corresponding build
directory as ``INCLUDE_DIRECTORIES`` on all targets. Similarly,
the :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` variable may
be enabled to add them as ``INTERFACE_INCLUDE_DIRECTORIES`` on all
targets.
:command:`target_sources`
.. versionadded:: 3.1
Populates the :prop_tgt:`SOURCES` build specification and
:prop_tgt:`INTERFACE_SOURCES` usage requirement properties.
It also supports specifying :ref:`File Sets`, which can add C++ module
sources and headers not listed in the ``SOURCES`` and ``INTERFACE_SOURCES``
properties. File sets may also populate the :prop_tgt:`INCLUDE_DIRECTORIES`
build specification and :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` usage
requirement properties with the include directories containing the headers.
:command:`target_precompile_headers`
.. versionadded:: 3.16
Populates the :prop_tgt:`PRECOMPILE_HEADERS` build specification and
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` usage requirement properties.
:command:`target_link_libraries`
Populates the :prop_tgt:`LINK_LIBRARIES` build specification
and :prop_tgt:`INTERFACE_LINK_LIBRARIES` usage requirement properties.
This is the primary mechanism by which link dependencies and their
`usage requirements <Target Usage Requirements_>`_ are transitively
propagated to affect compilation and linking of a target.
:command:`target_link_directories`
.. versionadded:: 3.13
Populates the :prop_tgt:`LINK_DIRECTORIES` build specification and
:prop_tgt:`INTERFACE_LINK_DIRECTORIES` usage requirement properties.
:command:`target_link_options`
.. versionadded:: 3.13
Populates the :prop_tgt:`LINK_OPTIONS` build specification and
:prop_tgt:`INTERFACE_LINK_OPTIONS` usage requirement properties.
.. _`Target Build Specification`:
Target Build Specification
--------------------------
The build specification of `Binary Targets`_ is represented by target
properties. For each of the following `compile <Target Compile Properties_>`_
and `link <Target Link Properties_>`_ properties, compilation and linking
of the target is affected both by its own value and by the corresponding
`usage requirement <Target Usage Requirements_>`_ property, named with
an ``INTERFACE_`` prefix, collected from the transitive closure of link
dependencies.
.. _`Target Compile Properties`:
Target Compile Properties
^^^^^^^^^^^^^^^^^^^^^^^^^
These represent the `build specification <Target Build Specification_>`_
for compiling a target.
:prop_tgt:`COMPILE_DEFINITIONS`
List of compile definitions for compiling sources in the target.
These are passed to the compiler with ``-D`` flags, or equivalent,
in an unspecified order.
The :prop_tgt:`DEFINE_SYMBOL` target property is also used
as a compile definition as a special convenience case for
``SHARED`` and ``MODULE`` library targets.
:prop_tgt:`COMPILE_OPTIONS`
List of compile options for compiling sources in the target.
These are passed to the compiler as flags, in the order of appearance.
Compile options are automatically escaped for the shell.
Some compile options are best specified via dedicated settings,
such as the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property.
:prop_tgt:`COMPILE_FEATURES`
.. versionadded:: 3.1
List of :manual:`compile features <cmake-compile-features(7)>` needed
for compiling sources in the target. Typically these ensure the
target's sources are compiled using a sufficient language standard level.
:prop_tgt:`INCLUDE_DIRECTORIES`
List of include directories for compiling sources in the target.
These are passed to the compiler with ``-I`` or ``-isystem`` flags,
or equivalent, in the order of appearance.
For convenience, the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable
may be enabled to add the source directory and corresponding build
directory as ``INCLUDE_DIRECTORIES`` on all targets.
:prop_tgt:`SOURCES`
List of source files associated with the target. This includes sources
specified when the target was created by the :command:`add_executable`,
:command:`add_library`, or :command:`add_custom_target` command.
It also includes sources added by the :command:`target_sources` command,
but does not include :ref:`File Sets`.
:prop_tgt:`PRECOMPILE_HEADERS`
.. versionadded:: 3.16
List of header files to precompile and include when compiling
sources in the target.
:prop_tgt:`AUTOMOC_MACRO_NAMES`
.. versionadded:: 3.10
List of macro names used by :prop_tgt:`AUTOMOC` to determine if a
C++ source in the target needs to be processed by ``moc``.
:prop_tgt:`AUTOUIC_OPTIONS`
.. versionadded:: 3.0
List of options used by :prop_tgt:`AUTOUIC` when invoking ``uic``
for the target.
.. _`Target Link Properties`:
Target Link Properties
^^^^^^^^^^^^^^^^^^^^^^
These represent the `build specification <Target Build Specification_>`_
for linking a target.
:prop_tgt:`LINK_LIBRARIES`
List of link libraries for linking the target, if it is an executable,
shared library, or module library. Entries for `Normal Libraries`_ are
passed to the linker either via paths to their link artifacts, or
with ``-l`` flags or equivalent. Entries for `Object Libraries`_ are
passed to the linker via paths to their object files.
Additionally, for compiling and linking the target itself,
`usage requirements <Target Usage Requirements_>`_ are propagated from
``LINK_LIBRARIES`` entries naming `Normal Libraries`_,
`Interface Libraries`_, `Object Libraries`_, and `Imported Targets`_,
collected over the transitive closure of their
:prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
:prop_tgt:`LINK_DIRECTORIES`
.. versionadded:: 3.13
List of link directories for linking the target, if it is an executable,
shared library, or module library. The directories are passed to the
linker with ``-L`` flags, or equivalent.
:prop_tgt:`LINK_OPTIONS`
.. versionadded:: 3.13
List of link options for linking the target, if it is an executable,
shared library, or module library. The options are passed to the
linker as flags, in the order of appearance.
Link options are automatically escaped for the shell.
:prop_tgt:`LINK_DEPENDS`
List of files on which linking the target depends, if it is an executable,
shared library, or module library. For example, linker scripts specified
via :prop_tgt:`LINK_OPTIONS` may be listed here such that changing them
causes binaries to be linked again.
.. _`Target Usage Requirements`:
Target Usage Requirements
-------------------------
The *usage requirements* of a target are settings that propagate to consumers,
which link to the target via :command:`target_link_libraries`, in order to
correctly compile and link with it. They are represented by transitive
`compile <Transitive Compile Properties_>`_ and
`link <Transitive Link Properties_>`_ properties.
Note that usage requirements are not designed as a way to make downstreams
use particular :prop_tgt:`COMPILE_OPTIONS` or
:prop_tgt:`COMPILE_DEFINITIONS` etc for convenience only. The contents of
the properties must be **requirements**, not merely recommendations or
convenience.
use particular :prop_tgt:`COMPILE_OPTIONS`, :prop_tgt:`COMPILE_DEFINITIONS`,
etc. for convenience only. The contents of the properties must be
**requirements**, not merely recommendations.
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
-----------------
The contents of the :prop_tgt:`INCLUDE_DIRECTORIES`,
:prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS` target
properties are used appropriately when compiling the source files of a
binary target.
Entries in the :prop_tgt:`INCLUDE_DIRECTORIES` are added to the compile line
with ``-I`` or ``-isystem`` prefixes and in the order of appearance in the
property value.
Entries in the :prop_tgt:`COMPILE_DEFINITIONS` are prefixed with ``-D`` or
``/D`` and added to the compile line in an unspecified order. The
:prop_tgt:`DEFINE_SYMBOL` target property is also added as a compile
definition as a special convenience case for ``SHARED`` and ``MODULE``
library targets.
Entries in the :prop_tgt:`COMPILE_OPTIONS` are escaped for the shell and added
in the order of appearance in the property value. Several compile options have
special separate handling, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`.
The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and
:prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties are
*Usage Requirements* -- they specify content which consumers
must use to correctly compile and link with the target they appear on.
For any binary target, the contents of each ``INTERFACE_`` property on
each target specified in a :command:`target_link_libraries` command is
consumed:
.. code-block:: cmake
set(srcs archive.cpp zip.cpp)
if (LZMA_FOUND)
list(APPEND srcs lzma.cpp)
endif()
add_library(archive SHARED ${srcs})
if (LZMA_FOUND)
# The archive library sources are compiled with -DBUILDING_WITH_LZMA
target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
endif()
target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
add_executable(consumer)
# Link consumer to archive and consume its usage requirements. The consumer
# executable sources are compiled with -DUSING_ARCHIVE_LIB.
target_link_libraries(consumer archive)
Because it is common to require that the source directory and corresponding
build directory are added to the :prop_tgt:`INCLUDE_DIRECTORIES`, the
:variable:`CMAKE_INCLUDE_CURRENT_DIR` variable can be enabled to conveniently
add the corresponding directories to the :prop_tgt:`INCLUDE_DIRECTORIES` of
all targets. The variable :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE`
can be enabled to add the corresponding directories to the
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of all targets. This makes use of
targets in multiple different directories convenient through use of the
:command:`target_link_libraries` command.
.. _`Target Usage Requirements`:
Transitive Usage Requirements
-----------------------------
The usage requirements of a target can transitively propagate to the dependents.
The :command:`target_link_libraries` command has ``PRIVATE``,
``INTERFACE`` and ``PUBLIC`` keywords to control the propagation.
@ -329,6 +511,156 @@ Note that care must be taken when specifying usage requirements for targets
which will be exported for installation using the :command:`install(EXPORT)`
command. See :ref:`Creating Packages` for more.
.. _`Transitive Compile Properties`:
Transitive Compile Properties
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These represent `usage requirements <Target Usage Requirements_>`_ for
compiling consumers.
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`
List of compile definitions for compiling sources in the target's consumers.
Typically these are used by the target's header files.
:prop_tgt:`INTERFACE_COMPILE_OPTIONS`
List of compile options for compiling sources in the target's consumers.
:prop_tgt:`INTERFACE_COMPILE_FEATURES`
.. versionadded:: 3.1
List of :manual:`compile features <cmake-compile-features(7)>` needed
for compiling sources in the target's consumers. Typically these
ensure the target's header files are processed when compiling consumers
using a sufficient language standard level.
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
List of include directories for compiling sources in the target's consumers.
Typically these are the locations of the target's header files.
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`
List of directories that, when specified as include directories, e.g., by
:prop_tgt:`INCLUDE_DIRECTORIES` or :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
should be treated as "system" include directories when compiling sources
in the target's consumers.
:prop_tgt:`INTERFACE_SOURCES`
List of source files to associate with the target's consumers.
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS`
.. versionadded:: 3.16
List of header files to precompile and include when compiling
sources in the target's consumers.
:prop_tgt:`INTERFACE_AUTOMOC_MACRO_NAMES`
.. versionadded:: 3.27
List of macro names used by :prop_tgt:`AUTOMOC` to determine if a
C++ source in the target's consumers needs to be processed by ``moc``.
:prop_tgt:`INTERFACE_AUTOUIC_OPTIONS`
.. versionadded:: 3.0
List of options used by :prop_tgt:`AUTOUIC` when invoking ``uic``
for the target's consumers.
.. _`Transitive Link Properties`:
Transitive Link Properties
^^^^^^^^^^^^^^^^^^^^^^^^^^
These represent `usage requirements <Target Usage Requirements_>`_ for
linking consumers.
:prop_tgt:`INTERFACE_LINK_LIBRARIES`
List of link libraries for linking the target's consumers, for
those that are executables, shared libraries, or module libraries.
These are the transitive dependencies of the target.
Additionally, for compiling and linking the target's consumers,
`usage requirements <Target Usage Requirements_>`_ are collected from
the transitive closure of ``INTERFACE_LINK_LIBRARIES`` entries naming
`Normal Libraries`_, `Interface Libraries`_, `Object Libraries`_,
and `Imported Targets`_,
:prop_tgt:`INTERFACE_LINK_DIRECTORIES`
.. versionadded:: 3.13
List of link directories for linking the target's consumers, for
those that are executables, shared libraries, or module libraries.
:prop_tgt:`INTERFACE_LINK_OPTIONS`
.. versionadded:: 3.13
List of link options for linking the target's consumers, for
those that are executables, shared libraries, or module libraries.
:prop_tgt:`INTERFACE_LINK_DEPENDS`
.. versionadded:: 3.13
List of files on which linking the target's consumers depends, for
those that are executables, shared libraries, or module libraries.
.. _`Custom Transitive Properties`:
Custom Transitive Properties
----------------------------
.. versionadded:: 3.30
The :genex:`TARGET_PROPERTY` generator expression evaluates the above
`build specification <Target Build Specification_>`_ and
`usage requirement <Target Usage Requirements_>`_ properties
as builtin transitive properties. It also supports custom transitive
properties defined by the :prop_tgt:`TRANSITIVE_COMPILE_PROPERTIES`
and :prop_tgt:`TRANSITIVE_LINK_PROPERTIES` properties on the target
and its link dependencies.
For example:
.. code-block:: cmake
add_library(example INTERFACE)
set_target_properties(example PROPERTIES
TRANSITIVE_COMPILE_PROPERTIES "CUSTOM_C"
TRANSITIVE_LINK_PROPERTIES "CUSTOM_L"
INTERFACE_CUSTOM_C "EXAMPLE_CUSTOM_C"
INTERFACE_CUSTOM_L "EXAMPLE_CUSTOM_L"
)
add_library(mylib STATIC mylib.c)
target_link_libraries(mylib PRIVATE example)
set_target_properties(mylib PROPERTIES
CUSTOM_C "MYLIB_PRIVATE_CUSTOM_C"
CUSTOM_L "MYLIB_PRIVATE_CUSTOM_L"
INTERFACE_CUSTOM_C "MYLIB_IFACE_CUSTOM_C"
INTERFACE_CUSTOM_L "MYLIB_IFACE_CUSTOM_L"
)
add_executable(myexe myexe.c)
target_link_libraries(myexe PRIVATE mylib)
set_target_properties(myexe PROPERTIES
CUSTOM_C "MYEXE_CUSTOM_C"
CUSTOM_L "MYEXE_CUSTOM_L"
)
add_custom_target(print ALL VERBATIM
COMMAND ${CMAKE_COMMAND} -E echo
# Prints "MYLIB_PRIVATE_CUSTOM_C;EXAMPLE_CUSTOM_C"
"$<TARGET_PROPERTY:mylib,CUSTOM_C>"
# Prints "MYLIB_PRIVATE_CUSTOM_L;EXAMPLE_CUSTOM_L"
"$<TARGET_PROPERTY:mylib,CUSTOM_L>"
# Prints "MYEXE_CUSTOM_C"
"$<TARGET_PROPERTY:myexe,CUSTOM_C>"
# Prints "MYEXE_CUSTOM_L;MYLIB_IFACE_CUSTOM_L;EXAMPLE_CUSTOM_L"
"$<TARGET_PROPERTY:myexe,CUSTOM_L>"
)
.. _`Compatible Interface Properties`:
Compatible Interface Properties

65
Help/manual/cmake-cxxmodules.7.rst
View File

@ -12,6 +12,49 @@ to scan source files for module dependencies during the build, collates
scanning results to infer ordering constraints, and tells the build tool
how to dynamically update the build graph.
Compilation Strategy
====================
With C++ modules, compiling a set of C++ sources is no longer embarrassingly
parallel. That is, any given source may first require the compilation of
another source file first in order to provide a "CMI" (compiled module
interface) or "BMI" (binary module interface) that C++ compilers use to
satisfy ``import`` statements in other sources. With headers, sources could
share their declarations so that any consumers could compile independently.
With modules, declarations are now generated into these BMI files by the
compiler during compilation based on the contents of the source file and its
``export`` statements.
The order necessary for compilation requires build-time resolution of the
ordering because the order is controlled by the contents of the sources. This
means that the ordering needs extracted from the source during the build to
avoid regenerating the build graph via a configure and generate phase for
every source change to get a correct build.
The general strategy is to use a "scanner" to extract the ordering dependency
information and update the build graph with new edges between existing edges
by taking the per-source scan results (represented by `P1689R5`_ files) and
"collating" the dependencies within a target and to modules produced by
targets visible to the target. The primary task is to generate "module map"
files to pass to each compile rule with the paths to the BMIs needed to
satisfy ``import`` statements. The collator also has tasks to use the
build-time information to fill out information including ``install`` rules for
the module interface units, their BMIs, and properties for any exported
targets with C++ modules.
.. _`P1689R5`: https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html
.. note::
CMake is focusing on correct builds before looking at performance
improvements. There are known tactics within the chosen strategy which may
offer build performance improvements. However, they are being deferred
until we have a working model against which to compare them. It is also
important to note that a tactic useful in one situation (e.g., clean
builds) may not be performant in a different situation (e.g., incremental
builds). Finding a balance and offering controls to select the tactics is
future work.
Scanning Control
================
@ -43,6 +86,25 @@ Compilers which CMake natively supports module dependency scanning include:
* LLVM/Clang 16.0 and newer
* GCC 14 (for the in-development branch, after 2023-09-20) and newer
``import std`` Support
======================
Support for ``import std`` is limited to the following toolchain and standard
library combinations:
* Clang 18.1.2 and newer with ``-stdlib=libc++``
* MSVC toolset 14.36 and newer (provided with Visual Studio 17.6 Preview 2 and
newer)
The :variable:`CMAKE_CXX_COMPILER_IMPORT_STD` variable may be used to detect
support for a standard level with the active C++ toolchain.
.. note ::
This support is provided only when experimental support for
``import std;`` has been enabled by the
``CMAKE_EXPERIMENTAL_CXX_IMPORT_STD`` gate.
Generator Support
=================
@ -73,6 +135,7 @@ For the :ref:`Visual Studio Generators`:
- Only Visual Studio 2022 and MSVC toolsets 14.34 (Visual Studio
17.4) and newer.
- No support for exporting or installing BMI or module information.
- No support for compiling BMIs from ``IMPORTED`` targets with C++ modules.
- No support for compiling BMIs from ``IMPORTED`` targets with C++ modules
(including ``import std``).
- No diagnosis of using modules provided by ``PRIVATE`` sources from
``PUBLIC`` module sources.

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

@ -119,7 +119,8 @@ do.
The more modern approach is to behave as much like
:ref:`config file packages <Config File Packages>` files as possible, by
providing :ref:`imported target <Imported targets>`. This has the advantage
of propagating :ref:`Target Usage Requirements` to consumers.
of propagating :ref:`usage requirements <Target Usage Requirements>`
to consumers.
In either case (or even when providing both variables and imported
targets), find modules should provide backwards compatibility with old

4
Help/manual/cmake-env-variables.7.rst
View File

@ -27,6 +27,8 @@ Environment Variables that Change Behavior
/envvar/CMAKE_MAXIMUM_RECURSION_DEPTH
/envvar/CMAKE_PREFIX_PATH
/envvar/CMAKE_PROGRAM_PATH
/envvar/CMAKE_TLS_VERIFY
/envvar/CMAKE_TLS_VERSION
/envvar/SSL_CERT_DIR
/envvar/SSL_CERT_FILE
@ -90,7 +92,9 @@ Environment Variables for Languages
/envvar/ISPC
/envvar/ISPCFLAGS
/envvar/OBJC
/envvar/OBJCFLAGS
/envvar/OBJCXX
/envvar/OBJCXXFLAGS
/envvar/RC
/envvar/RCFLAGS
/envvar/SWIFTC

50
Help/manual/cmake-file-api.7.rst
View File

@ -1489,7 +1489,7 @@ There is only one ``cmakeFiles`` object major version, version 1.
{
"kind": "cmakeFiles",
"version": { "major": 1, "minor": 0 },
"version": { "major": 1, "minor": 1 },
"paths": {
"build": "/path/to/top-level-build-dir",
"source": "/path/to/top-level-source-dir"
@ -1511,6 +1511,16 @@ There is only one ``cmakeFiles`` object major version, version 1.
"isExternal": true,
"path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake"
}
],
"globsDependent": [
{
"expression": "src/*.cxx",
"recurse": true,
"files": [
"src/foo.cxx",
"src/bar.cxx"
]
}
]
}
@ -1553,6 +1563,44 @@ The members specific to ``cmakeFiles`` objects are:
Optional member that is present with boolean value ``true``
if the path specifies a file in the CMake installation.
``globsDependent``
Optional member that is present when the project calls :command:`file(GLOB)`
or :command:`file(GLOB_RECURSE)` with the ``CONFIGURE_DEPENDS`` option.
The value is a JSON array of JSON objects, each specifying a globbing
expression and the list of paths it matched. If the globbing expression
no longer matches the same list of paths, CMake considers the build system
to be out of date.
This field was added in ``cmakeFiles`` version 1.1.
The members of each entry are:
``expression``
A string specifying the globbing expression.
``recurse``
Optional member that is present with boolean value ``true``
if the entry corresponds to a :command:`file(GLOB_RECURSE)` call.
Otherwise the entry corresponds to a :command:`file(GLOB)` call.
``listDirectories``
Optional member that is present with boolean value ``true`` if
:command:`file(GLOB)` was called without ``LIST_DIRECTORIES false`` or
:command:`file(GLOB_RECURSE)` was called with ``LIST_DIRECTORIES true``.
``followSymlinks``
Optional member that is present with boolean value ``true`` if
:command:`file(GLOB)` was called with the ``FOLLOW_SYMLINKS`` option.
``relative``
Optional member that is present if :command:`file(GLOB)` was called
with the ``RELATIVE <path>`` option. The value is a string containing
the ``<path>`` given.
``paths``
A JSON array of strings specifying the paths matched by the call
to :command:`file(GLOB)` or :command:`file(GLOB_RECURSE)`.
Object Kind "toolchains"
------------------------

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

@ -967,7 +967,7 @@ closely related to the expressions in this sub-section.
.. genex:: $<CXX_COMPILER_VERSION:version>
``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``.
``1`` if the version of the C++ compiler matches ``version``, otherwise ``0``.
.. genex:: $<CUDA_COMPILER_VERSION>
@ -979,31 +979,31 @@ closely related to the expressions in this sub-section.
.. versionadded:: 3.15
``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``.
``1`` if the version of the C++ compiler matches ``version``, otherwise ``0``.
.. genex:: $<OBJC_COMPILER_VERSION>
.. versionadded:: 3.16
The version of the OBJC compiler used.
The version of the Objective-C compiler used.
.. genex:: $<OBJC_COMPILER_VERSION:version>
.. versionadded:: 3.16
``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``.
``1`` if the version of the Objective-C compiler matches ``version``, otherwise ``0``.
.. genex:: $<OBJCXX_COMPILER_VERSION>
.. versionadded:: 3.16
The version of the OBJCXX compiler used.
The version of the Objective-C++ compiler used.
.. genex:: $<OBJCXX_COMPILER_VERSION:version>
.. versionadded:: 3.16
``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``.
``1`` if the version of the Objective-C++ compiler matches ``version``, otherwise ``0``.
.. genex:: $<Fortran_COMPILER_VERSION>
@ -1037,10 +1037,11 @@ closely related to the expressions in this sub-section.
``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``.
Compiler Language And ID
^^^^^^^^^^^^^^^^^^^^^^^^
Compiler Language, ID, and Frontend-Variant
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable, which is closely
See also the :variable:`CMAKE_<LANG>_COMPILER_ID` and
:variable:`CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT` variables, which are closely
related to most of the expressions in this sub-section.
.. genex:: $<C_COMPILER_ID>
@ -1059,12 +1060,12 @@ related to most of the expressions in this sub-section.
.. genex:: $<CXX_COMPILER_ID>
CMake's compiler id of the CXX compiler used.
CMake's compiler id of the C++ compiler used.
.. genex:: $<CXX_COMPILER_ID:compiler_ids>
where ``compiler_ids`` is a comma-separated list.
``1`` if CMake's compiler id of the CXX compiler matches any one
``1`` if CMake's compiler id of the C++ compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. versionchanged:: 3.15
@ -1089,7 +1090,7 @@ related to most of the expressions in this sub-section.
.. versionadded:: 3.16
CMake's compiler id of the OBJC compiler used.
CMake's compiler id of the Objective-C compiler used.
.. genex:: $<OBJC_COMPILER_ID:compiler_ids>
@ -1103,7 +1104,7 @@ related to most of the expressions in this sub-section.
.. versionadded:: 3.16
CMake's compiler id of the OBJCXX compiler used.
CMake's compiler id of the Objective-C++ compiler used.
.. genex:: $<OBJCXX_COMPILER_ID:compiler_ids>
@ -1155,6 +1156,118 @@ related to most of the expressions in this sub-section.
``1`` if CMake's compiler id of the ISPC compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. genex:: $<C_COMPILER_FRONTEND_VARIANT>
.. versionadded:: 3.30
CMake's compiler frontend variant of the C compiler used.
.. genex:: $<C_COMPILER_FRONTEND_VARIANT:compiler_ids>
.. versionadded:: 3.30
where ``compiler_ids`` is a comma-separated list.
``1`` if CMake's compiler frontend variant of the C compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. genex:: $<CXX_COMPILER_FRONTEND_VARIANT>
.. versionadded:: 3.30
CMake's compiler frontend variant of the C++ compiler used.
.. genex:: $<CXX_COMPILER_FRONTEND_VARIANT:compiler_ids>
.. versionadded:: 3.30
where ``compiler_ids`` is a comma-separated list.
``1`` if CMake's compiler frontend variant of the C++ compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. genex:: $<CUDA_COMPILER_FRONTEND_VARIANT>
.. versionadded:: 3.30
CMake's compiler id of the CUDA compiler used.
.. genex:: $<CUDA_COMPILER_FRONTEND_VARIANT:compiler_ids>
.. versionadded:: 3.30
where ``compiler_ids`` is a comma-separated list.
``1`` if CMake's compiler frontend variant of the CUDA compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. genex:: $<OBJC_COMPILER_FRONTEND_VARIANT>
.. versionadded:: 3.30
CMake's compiler frontend variant of the Objective-C compiler used.
.. genex:: $<OBJC_COMPILER_FRONTEND_VARIANT:compiler_ids>
.. versionadded:: 3.30
where ``compiler_ids`` is a comma-separated list.
``1`` if CMake's compiler frontend variant of the Objective-C compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. genex:: $<OBJCXX_COMPILER_FRONTEND_VARIANT>
.. versionadded:: 3.30
CMake's compiler frontend variant of the Objective-C++ compiler used.
.. genex:: $<OBJCXX_COMPILER_FRONTEND_VARIANT:compiler_ids>
.. versionadded:: 3.30
where ``compiler_ids`` is a comma-separated list.
``1`` if CMake's compiler frontend variant of the Objective-C++ compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. genex:: $<Fortran_COMPILER_FRONTEND_VARIANT>
.. versionadded:: 3.30
CMake's compiler id of the Fortran compiler used.
.. genex:: $<Fortran_COMPILER_FRONTEND_VARIANT:compiler_ids>
.. versionadded:: 3.30
where ``compiler_ids`` is a comma-separated list.
``1`` if CMake's compiler frontend variant of the Fortran compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. genex:: $<HIP_COMPILER_FRONTEND_VARIANT>
.. versionadded:: 3.30
CMake's compiler id of the HIP compiler used.
.. genex:: $<HIP_COMPILER_FRONTEND_VARIANT:compiler_ids>
.. versionadded:: 3.30
where ``compiler_ids`` is a comma-separated list.
``1`` if CMake's compiler frontend variant of the HIP compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. genex:: $<ISPC_COMPILER_FRONTEND_VARIANT>
.. versionadded:: 3.30
CMake's compiler id of the ISPC compiler used.
.. genex:: $<ISPC_COMPILER_FRONTEND_VARIANT:compiler_ids>
.. versionadded:: 3.30
where ``compiler_ids`` is a comma-separated list.
``1`` if CMake's compiler frontend variant of the ISPC compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. genex:: $<COMPILE_LANGUAGE>
.. versionadded:: 3.3
@ -1281,7 +1394,8 @@ Compile Context
.. versionadded:: 3.27
Content of ``...``, when collecting :ref:`Target Usage Requirements`,
Content of ``...``, when collecting
:ref:`transitive compile properties <Transitive Compile Properties>`,
otherwise it is the empty string. This is intended for use in an
:prop_tgt:`INTERFACE_LINK_LIBRARIES` and :prop_tgt:`LINK_LIBRARIES` target
properties, typically populated via the :command:`target_link_libraries` command.
@ -1669,7 +1783,8 @@ Link Context
.. versionadded:: 3.1
Content of ``...``, except while collecting :ref:`Target Usage Requirements`,
Content of ``...``, except while collecting usage requirements from
:ref:`transitive compile properties <Transitive Compile Properties>`,
in which case it is the empty string. This is intended for use in an
:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated
via the :command:`target_link_libraries` command, to specify private link
@ -1700,22 +1815,15 @@ Link Context
only be used to specify link options.
.. _`Target-Dependent Queries`:
.. _`Target-Dependent Expressions`:
Target-Dependent Expressions
----------------------------
These queries refer to a target ``tgt``. Unless otherwise stated, this can
be any runtime artifact, namely:
Target Meta-Data
^^^^^^^^^^^^^^^^
* An executable target created by :command:`add_executable`.
* A shared library target (``.so``, ``.dll`` but not their ``.lib`` import
library) created by :command:`add_library`.
* A static library target created by :command:`add_library`.
In the following, the phrase "the ``tgt`` filename" means the name of the
``tgt`` binary file. This has to be distinguished from the phrase
"the target name", which is just the string ``tgt``.
These expressions look up information about a target.
.. genex:: $<TARGET_EXISTS:tgt>
@ -1732,15 +1840,32 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
.. genex:: $<TARGET_NAME:...>
.. genex:: $<TARGET_NAME:tgt>
Marks ``...`` as being the name of a target. This is required if exporting
targets to multiple dependent export sets. The ``...`` must be a literal
name of a target, it may not contain generator expressions.
The target name ``tgt`` as written. This marks ``tgt`` as being the name
of a target inside a larger expression, which is required if exporting
targets to multiple dependent export sets. The ``tgt`` text must be a
literal name of a target; it may not contain generator expressions.
The target does not have to exist.
.. genex:: $<TARGET_POLICY:policy>
``1`` if the ``policy`` was ``NEW`` when the 'head' target was created,
else ``0``. If the ``policy`` was not set, the warning message for the policy
will be emitted. This generator expression only works for a subset of
policies.
Target Properties
^^^^^^^^^^^^^^^^^
These expressions look up the values of
:ref:`target properties <Target Properties>`.
.. genex:: $<TARGET_PROPERTY:tgt,prop>
Value of the property ``prop`` on the target ``tgt``.
Value of the property ``prop`` on the target ``tgt``, or empty if
the property is not set.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
@ -1756,23 +1881,129 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
:target: TARGET_PROPERTY:prop
Value of the property ``prop`` on the target for which the expression
is being evaluated. Note that for generator expressions in
:ref:`Target Usage Requirements` this is the consuming target rather
than the target specifying the requirement.
is being evaluated, or empty if the property is not set.
Note that for generator expressions in :ref:`Target Usage Requirements`
this is the consuming target rather than the target specifying the
requirement.
.. genex:: $<TARGET_OBJECTS:tgt>
The expressions have special evaluation rules for some properties:
.. versionadded:: 3.1
:ref:`Target Build Specification Properties <Target Build Specification>`
These evaluate as a :ref:`semicolon-separated list <CMake Language Lists>`
representing the union of the value on the target itself with the values
of the corresponding :ref:`Target Usage Requirements` on targets named by
the target's :prop_tgt:`LINK_LIBRARIES`:
List of objects resulting from building ``tgt``. This would typically be
used on :ref:`object library <Object Libraries>` targets.
* For :ref:`Target Compile Properties`, evaluation of corresponding usage
requirements is transitive over the closure of the linked targets'
:prop_tgt:`INTERFACE_LINK_LIBRARIES` *excluding* entries guarded by the
:genex:`LINK_ONLY` generator expression.
.. genex:: $<TARGET_POLICY:policy>
* For :ref:`Target Link Properties`, evaluation of corresponding usage
requirements is transitive over the closure of the linked targets'
:prop_tgt:`INTERFACE_LINK_LIBRARIES` *including* entries guarded by the
:genex:`LINK_ONLY` generator expression. See policy :policy:`CMP0166`.
``1`` if the ``policy`` was ``NEW`` when the 'head' target was created,
else ``0``. If the ``policy`` was not set, the warning message for the policy
will be emitted. This generator expression only works for a subset of
policies.
Evaluation of :prop_tgt:`LINK_LIBRARIES` itself is not transitive.
:ref:`Target Usage Requirement Properties <Target Usage Requirements>`
These evaluate as a :ref:`semicolon-separated list <CMake Language Lists>`
representing the union of the value on the target itself with the values
of the same properties on targets named by the target's
:prop_tgt:`INTERFACE_LINK_LIBRARIES`:
* For :ref:`Transitive Compile Properties`, evaluation is transitive over
the closure of the target's :prop_tgt:`INTERFACE_LINK_LIBRARIES`
*excluding* entries guarded by the :genex:`LINK_ONLY` generator expression.
* For :ref:`Transitive Link Properties`, evaluation is transitive over
the closure of the target's :prop_tgt:`INTERFACE_LINK_LIBRARIES`
*including* entries guarded by the :genex:`LINK_ONLY` generator expression.
See policy :policy:`CMP0166`.
Evaluation of :prop_tgt:`INTERFACE_LINK_LIBRARIES` itself is not transitive.
:ref:`Custom Transitive Properties`
.. versionadded:: 3.30
These are processed during evaluation as follows:
* Evaluation of :genex:`$<TARGET_PROPERTY:tgt,PROP>` for some property
``PROP``, named without an ``INTERFACE_`` prefix,
checks the :prop_tgt:`TRANSITIVE_COMPILE_PROPERTIES`
and :prop_tgt:`TRANSITIVE_LINK_PROPERTIES` properties on target ``tgt``,
on targets named by its :prop_tgt:`LINK_LIBRARIES`, and on the
transitive closure of targets named by the linked targets'
:prop_tgt:`INTERFACE_LINK_LIBRARIES`.
If ``PROP`` is listed by one of those properties, then it evaluates as
a :ref:`semicolon-separated list <CMake Language Lists>` representing
the union of the value on the target itself with the values of the
corresponding ``INTERFACE_PROP`` on targets named by the target's
:prop_tgt:`LINK_LIBRARIES`:
* If ``PROP`` is named by :prop_tgt:`TRANSITIVE_COMPILE_PROPERTIES`,
evaluation of the corresponding ``INTERFACE_PROP`` is transitive over
the closure of the linked targets' :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
excluding entries guarded by the :genex:`LINK_ONLY` generator expression.
* If ``PROP`` is named by :prop_tgt:`TRANSITIVE_LINK_PROPERTIES`,
evaluation of the corresponding ``INTERFACE_PROP`` is transitive over
the closure of the linked targets' :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
including entries guarded by the :genex:`LINK_ONLY` generator expression.
* Evaluation of :genex:`$<TARGET_PROPERTY:tgt,INTERFACE_PROP>` for some
property ``INTERFACE_PROP``, named with an ``INTERFACE_`` prefix,
checks the :prop_tgt:`TRANSITIVE_COMPILE_PROPERTIES`
and :prop_tgt:`TRANSITIVE_LINK_PROPERTIES` properties on target ``tgt``,
and on the transitive closure of targets named by its
:prop_tgt:`INTERFACE_LINK_LIBRARIES`.
If the corresponding ``PROP`` is listed by one of those properties,
then ``INTERFACE_PROP`` evaluates as a
:ref:`semicolon-separated list <CMake Language Lists>` representing the
union of the value on the target itself with the value of the same
property on targets named by the target's
:prop_tgt:`INTERFACE_LINK_LIBRARIES`:
* If ``PROP`` is named by :prop_tgt:`TRANSITIVE_COMPILE_PROPERTIES`,
evaluation of the corresponding ``INTERFACE_PROP`` is transitive over
the closure of the target's :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
excluding entries guarded by the :genex:`LINK_ONLY` generator expression.
* If ``PROP`` is named by :prop_tgt:`TRANSITIVE_LINK_PROPERTIES`,
evaluation of the corresponding ``INTERFACE_PROP`` is transitive over
the closure of the target's :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
including entries guarded by the :genex:`LINK_ONLY` generator expression.
If a ``PROP`` is named by both :prop_tgt:`TRANSITIVE_COMPILE_PROPERTIES`
and :prop_tgt:`TRANSITIVE_LINK_PROPERTIES`, the latter takes precedence.
:ref:`Compatible Interface Properties`
These evaluate as a single value combined from the target itself,
from targets named by the target's :prop_tgt:`LINK_LIBRARIES`, and
from the transitive closure of the linked targets'
:prop_tgt:`INTERFACE_LINK_LIBRARIES`. Values of a compatible
interface property from multiple targets combine based on the type
of compatibility required by the ``COMPATIBLE_INTERFACE_*`` property
defining it.
Target Artifacts
^^^^^^^^^^^^^^^^
These expressions look up information about artifacts associated with
a given target ``tgt``. Unless otherwise stated, this can be any
runtime artifact, namely:
* An executable target created by :command:`add_executable`.
* A shared library target (``.so``, ``.dll`` but not their ``.lib`` import
library) created by :command:`add_library`.
* A static library target created by :command:`add_library`.
In the following, the phrase "the ``tgt`` filename" means the name of the
``tgt`` binary file. This has to be distinguished from the phrase
"the target name", which is just the string ``tgt``.
.. genex:: $<TARGET_FILE:tgt>
@ -2254,6 +2485,13 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on (see policy :policy:`CMP0112`).
.. genex:: $<TARGET_OBJECTS:tgt>
.. versionadded:: 3.1
List of objects resulting from building ``tgt``. This would typically be
used on :ref:`object library <Object Libraries>` targets.
.. genex:: $<TARGET_RUNTIME_DLLS:tgt>
.. versionadded:: 3.21
@ -2410,6 +2648,13 @@ special meaning.
A literal ``;``. Used to prevent list expansion on an argument with ``;``.
.. genex:: $<QUOTE>
.. versionadded:: 3.30
A literal ``"``. Used to allow string literal quotes inside a generator expression.
Deprecated Expressions
----------------------

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

@ -51,6 +51,22 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
to determine whether to report an error on use of deprecated macros or
functions.
Policies Introduced by CMake 3.30
=================================
.. toctree::
:maxdepth: 1
CMP0170: FETCHCONTENT_FULLY_DISCONNECTED requirements are enforced. </policy/CMP0170>
CMP0169: FetchContent_Populate(depName) single-argument signature is deprecated. </policy/CMP0169>
CMP0168: FetchContent implements steps directly instead of through a sub-build. </policy/CMP0168>
CMP0167: The FindBoost module is removed. </policy/CMP0167>
CMP0166: TARGET_PROPERTY evaluates link properties transitively over private dependencies of static libraries. </policy/CMP0166>
CMP0165: enable_language() must not be called before project(). </policy/CMP0165>
CMP0164: add_library() rejects SHARED libraries when not supported by the platform. </policy/CMP0164>
CMP0163: The GENERATED source file property is now visible in all directories. </policy/CMP0163>
CMP0162: Visual Studio generators add UseDebugLibraries indicators by default. </policy/CMP0162>
Policies Introduced by CMake 3.29
=================================
@ -118,7 +134,7 @@ Policies Introduced by CMake 3.24
CMP0138: CheckIPOSupported uses flags from calling project. </policy/CMP0138>
CMP0137: try_compile() passes platform variables in project mode. </policy/CMP0137>
CMP0136: Watcom runtime library flags are selected by an abstraction. </policy/CMP0136>
CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method. </policy/CMP0135>
CMP0135: ExternalProject and FetchContent ignore timestamps in archives by default for the URL download method. </policy/CMP0135>
CMP0134: Fallback to "HOST" Windows registry view when "TARGET" view is not usable. </policy/CMP0134>
CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator. </policy/CMP0133>
CMP0132: Do not set compiler environment variables on first run. </policy/CMP0132>
@ -163,7 +179,7 @@ Policies Introduced by CMake 3.20
CMP0120: The WriteCompilerDetectionHeader module is removed. </policy/CMP0120>
CMP0119: LANGUAGE source file property explicitly compiles as language. </policy/CMP0119>
CMP0118: The GENERATED source file property is now visible in all directories. </policy/CMP0118>
CMP0118: GENERATED sources may be used across directories without manual marking. </policy/CMP0118>
CMP0117: MSVC RTTI flag /GR is not added to CMAKE_CXX_FLAGS by default. </policy/CMP0117>
CMP0116: Ninja generators transform DEPFILEs from add_custom_command(). </policy/CMP0116>
CMP0115: Source file extensions must be explicit. </policy/CMP0115>
@ -203,7 +219,7 @@ Policies Introduced by CMake 3.17
CMP0102: mark_as_advanced() does nothing if a cache entry does not exist. </policy/CMP0102>
CMP0101: target_compile_options honors BEFORE keyword in all scopes. </policy/CMP0101>
CMP0100: Let AUTOMOC and AUTOUIC process .hh header files. </policy/CMP0100>
CMP0099: Link properties are transitive over private dependency on static libraries. </policy/CMP0099>
CMP0099: Link properties are transitive over private dependencies of static libraries. </policy/CMP0099>
CMP0098: FindFLEX runs flex in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0098>
Policies Introduced by CMake 3.16

12
Help/manual/cmake-presets.7.rst
View File

@ -78,6 +78,9 @@ The root object recognizes the following fields:
``8``
.. versionadded:: 3.28
``9``
.. versionadded:: 3.30
``cmakeMinimumRequired``
An optional object representing the minimum version of CMake needed to
build this project. This object consists of the following fields:
@ -146,7 +149,10 @@ guaranteed to be provided by the project. ``CMakeUserPresets.json`` may
include files from anywhere.
Starting from version ``7``, the ``include`` field supports
`macro expansion`_, but only ``$penv{}`` macro expansion.
`macro expansion`_, but only ``$penv{}`` macro expansion. Starting from version
``9``, other macro expansions are also available, except for ``$env{}`` and
preset-specific macros, i.e., those derived from the fields inside a preset's
definition like ``presetName``.
Configure Preset
^^^^^^^^^^^^^^^^
@ -1212,11 +1218,15 @@ Recognized macros include:
``${presetName}``
Name specified in the preset's ``name`` field.
This is a preset-specific macro.
``${generator}``
Generator specified in the preset's ``generator`` field. For build and
test presets, this will evaluate to the generator specified by
``configurePreset``.
This is a preset-specific macro.
``${hostSystemName}``
The name of the host operating system. Contains the same value as
:variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files

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

@ -25,6 +25,7 @@ Properties of Global Scope
/prop_gbl/CMAKE_C_KNOWN_FEATURES
/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES
/prop_gbl/CMAKE_CXX_KNOWN_FEATURES
/prop_gbl/CMAKE_HIP_KNOWN_FEATURES
/prop_gbl/CMAKE_ROLE
/prop_gbl/DEBUG_CONFIGURATIONS
/prop_gbl/DISABLED_FEATURES
@ -39,11 +40,13 @@ Properties of Global Scope
/prop_gbl/GENERATOR_IS_MULTI_CONFIG
/prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE
/prop_gbl/GLOBAL_DEPENDS_NO_CYCLES
/prop_gbl/INSTALL_PARALLEL
/prop_gbl/IN_TRY_COMPILE
/prop_gbl/JOB_POOLS
/prop_gbl/PACKAGES_FOUND
/prop_gbl/PACKAGES_NOT_FOUND
/prop_gbl/PREDEFINED_TARGETS_FOLDER
/prop_gbl/PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE
/prop_gbl/REPORT_UNDEFINED_PROPERTIES
/prop_gbl/RULE_LAUNCH_COMPILE
/prop_gbl/RULE_LAUNCH_CUSTOM
@ -194,6 +197,7 @@ Properties on Targets
/prop_tgt/CXX_MODULE_SET
/prop_tgt/CXX_MODULE_SET_NAME
/prop_tgt/CXX_MODULE_SETS
/prop_tgt/CXX_MODULE_STD
/prop_tgt/CXX_SCAN_FOR_MODULES
/prop_tgt/CXX_STANDARD
/prop_tgt/CXX_STANDARD_REQUIRED
@ -400,6 +404,8 @@ Properties on Targets
/prop_tgt/Swift_MODULE_NAME
/prop_tgt/SYSTEM
/prop_tgt/TEST_LAUNCHER
/prop_tgt/TRANSITIVE_COMPILE_PROPERTIES
/prop_tgt/TRANSITIVE_LINK_PROPERTIES
/prop_tgt/TYPE
/prop_tgt/UNITY_BUILD
/prop_tgt/UNITY_BUILD_BATCH_SIZE
@ -445,7 +451,9 @@ Properties on Targets
/prop_tgt/VS_SDK_REFERENCES
/prop_tgt/VS_SOLUTION_DEPLOY
/prop_tgt/VS_SOURCE_SETTINGS_tool
/prop_tgt/VS_USE_DEBUG_LIBRARIES
/prop_tgt/VS_USER_PROPS
/prop_tgt/VS_FILTER_PROPS
/prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
/prop_tgt/VS_WINRT_COMPONENT
/prop_tgt/VS_WINRT_REFERENCES

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

@ -137,6 +137,7 @@ Variables that Provide Information
/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER
/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION
/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION
/variable/CMAKE_VS_USE_DEBUG_LIBRARIES
/variable/CMAKE_VS_VERSION_BUILD_NUMBER
/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
@ -271,6 +272,7 @@ Variables that Change Behavior
/variable/CMAKE_SYSTEM_PROGRAM_PATH
/variable/CMAKE_TLS_CAINFO
/variable/CMAKE_TLS_VERIFY
/variable/CMAKE_TLS_VERSION
/variable/CMAKE_USER_MAKE_RULES_OVERRIDE
/variable/CMAKE_WARN_DEPRECATED
/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
@ -422,6 +424,7 @@ Variables that Control the Build
/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS
/variable/CMAKE_CUDA_RUNTIME_LIBRARY
/variable/CMAKE_CUDA_SEPARABLE_COMPILATION
/variable/CMAKE_CXX_MODULE_STD
/variable/CMAKE_CXX_SCAN_FOR_MODULES
/variable/CMAKE_DEBUG_POSTFIX
/variable/CMAKE_DEFAULT_BUILD_TYPE
@ -464,6 +467,7 @@ Variables that Control the Build
/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE
/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE
/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED
/variable/CMAKE_LANG_LINK_LIBRARY_FEATURE_ATTRIBUTES
/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG
/variable/CMAKE_LANG_LINK_LIBRARY_FLAG
/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE
@ -482,6 +486,7 @@ Variables that Control the Build
/variable/CMAKE_LINK_GROUP_USING_FEATURE
/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED
/variable/CMAKE_LINK_INTERFACE_LIBRARIES
/variable/CMAKE_LINK_LIBRARY_FEATURE_ATTRIBUTES
/variable/CMAKE_LINK_LIBRARY_FILE_FLAG
/variable/CMAKE_LINK_LIBRARY_FLAG
/variable/CMAKE_LINK_LIBRARY_USING_FEATURE
@ -577,6 +582,7 @@ Variables for Languages
/variable/CMAKE_CUDA_STANDARD_REQUIRED
/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES
/variable/CMAKE_CXX_COMPILE_FEATURES
/variable/CMAKE_CXX_COMPILER_IMPORT_STD
/variable/CMAKE_CXX_EXTENSIONS
/variable/CMAKE_CXX_STANDARD
/variable/CMAKE_CXX_STANDARD_REQUIRED
@ -584,6 +590,7 @@ Variables for Languages
/variable/CMAKE_Fortran_MODDIR_FLAG
/variable/CMAKE_Fortran_MODOUT_FLAG
/variable/CMAKE_HIP_ARCHITECTURES
/variable/CMAKE_HIP_COMPILE_FEATURES
/variable/CMAKE_HIP_EXTENSIONS
/variable/CMAKE_HIP_PLATFORM
/variable/CMAKE_HIP_STANDARD
@ -641,6 +648,7 @@ Variables for Languages
/variable/CMAKE_LANG_STANDARD
/variable/CMAKE_LANG_STANDARD_DEFAULT
/variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES
/variable/CMAKE_LANG_STANDARD_LATEST
/variable/CMAKE_LANG_STANDARD_LIBRARIES
/variable/CMAKE_LANG_STANDARD_REQUIRED
/variable/CMAKE_OBJC_EXTENSIONS
@ -726,6 +734,8 @@ Variables for CTest
/variable/CTEST_SVN_UPDATE_OPTIONS
/variable/CTEST_TEST_LOAD
/variable/CTEST_TEST_TIMEOUT
/variable/CTEST_TLS_VERIFY
/variable/CTEST_TLS_VERSION
/variable/CTEST_UPDATE_COMMAND
/variable/CTEST_UPDATE_OPTIONS
/variable/CTEST_UPDATE_VERSION_ONLY

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

@ -213,6 +213,13 @@ Options
This removes any existing ``CMakeCache.txt`` file and associated
``CMakeFiles/`` directory, and recreates them from scratch.
.. versionchanged:: 3.30
For dependencies previously populated by :module:`FetchContent` with the
``NEW`` setting for policy :policy:`CMP0168`, their stamp and script files
from any previous run will be removed. The download, update, and patch
steps will therefore be forced to re-execute.
.. option:: -L[A][H]
List non-advanced cached variables.
@ -507,27 +514,33 @@ Options
.. option:: --preset <preset>, --preset=<preset>
Reads a :manual:`preset <cmake-presets(7)>` from
``<path-to-source>/CMakePresets.json`` and
``<path-to-source>/CMakeUserPresets.json``. The preset may specify the
generator and the build directory, and a list of variables and other
arguments to pass to CMake. The current working directory must contain
CMake preset files. The :manual:`CMake GUI <cmake-gui(1)>` can
also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For
full details on these files, see :manual:`cmake-presets(7)`.
Reads a :manual:`preset <cmake-presets(7)>` from ``CMakePresets.json`` and
``CMakeUserPresets.json`` files, which must be located in the same directory
as the top level ``CMakeLists.txt`` file. The preset may specify the
generator, the build directory, a list of variables, and other arguments to
pass to CMake. At least one of ``CMakePresets.json`` or
``CMakeUserPresets.json`` must be present.
The :manual:`CMake GUI <cmake-gui(1)>` also recognizes and supports
``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For full details
on these files, see :manual:`cmake-presets(7)`.
The presets are read before all other command line options. The options
specified by the preset (variables, generator, etc.) can all be overridden by
manually specifying them on the command line. For example, if the preset sets
a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a
``-D`` argument, the value ``2`` is preferred.
The presets are read before all other command line options, although the
:option:`-S <cmake -S>` option can be used to specify the source directory
containing the ``CMakePresets.json`` and ``CMakeUserPresets.json`` files.
If :option:`-S <cmake -S>` is not given, the current directory is assumed to
be the top level source directory and must contain the presets files. The
options specified by the chosen preset (variables, generator, etc.) can all
be overridden by manually specifying them on the command line. For example,
if the preset sets a variable called ``MYVAR`` to ``1``, but the user sets
it to ``2`` with a ``-D`` argument, the value ``2`` is preferred.
.. option:: --list-presets[=<type>]
Lists the available presets of the specified ``<type>``. Valid values for
``<type>`` are ``configure``, ``build``, ``test``, ``package``, or ``all``.
If ``<type>`` is omitted, ``configure`` is assumed. The current working
directory must contain CMake preset files.
directory must contain CMake preset files unless the :option:`-S <cmake -S>`
option is used to specify a different top level source directory.
.. option:: --debugger
@ -1375,9 +1388,8 @@ The options are:
.. option:: --fresh
Perform a fresh configuration of the build tree.
This removes any existing ``CMakeCache.txt`` file and associated
``CMakeFiles/`` directory, and recreates them from scratch.
Perform a fresh configuration of the build tree, which has the same effect
as :option:`cmake --fresh`.
View Help
=========

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

@ -1452,14 +1452,25 @@ Configuration settings include:
* :module:`CTest` module variable: ``CTEST_SUBMIT_RETRY_DELAY``
``CurlOptions``
.. deprecated:: 3.30
Use ``TLSVerify`` instead.
Specify a semicolon-separated list of options to control the
Curl library that CTest uses internally to connect to the
server. Possible options are ``CURLOPT_SSL_VERIFYPEER_OFF``
and ``CURLOPT_SSL_VERIFYHOST_OFF``.
server.
* `CTest Script`_ variable: :variable:`CTEST_CURL_OPTIONS`
* :module:`CTest` module variable: ``CTEST_CURL_OPTIONS``
Possible options are:
``CURLOPT_SSL_VERIFYPEER_OFF``
Disable the ``CURLOPT_SSL_VERIFYPEER`` curl option.
``CURLOPT_SSL_VERIFYHOST_OFF``
Disable the ``CURLOPT_SSL_VERIFYHOST`` curl option.
``DropLocation``
Legacy option. When ``SubmitURL`` is not set, it is constructed from
``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and
@ -1540,6 +1551,24 @@ Configuration settings include:
* `CTest Script`_ variable: :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT`
* :module:`CTest` module variable: ``CTEST_SUBMIT_INACTIVITY_TIMEOUT``
``TLSVersion``
.. versionadded:: 3.30
Specify a minimum TLS version allowed when submitting to a dashboard
via ``https://`` URLs.
* `CTest Script`_ variable: :variable:`CTEST_TLS_VERSION`
* :module:`CTest` module variable: ``CTEST_TLS_VERSION``
``TLSVerify``
.. versionadded:: 3.30
Specify a boolean value indicating whether to verify the server
certificate when submitting to a dashboard via ``https://`` URLs.
* `CTest Script`_ variable: :variable:`CTEST_TLS_VERIFY`
* :module:`CTest` module variable: ``CTEST_TLS_VERIFY``
``TriggerSite``
Legacy option. Not used.

18
Help/manual/presets/schema.json
View File

@ -124,6 +124,24 @@
"include": { "$ref": "#/definitions/include" }
},
"additionalProperties": false
},
{
"properties": {
"$schema": { "$ref": "#/definitions/$schema" },
"version": {
"const": 9,
"description": "A required integer representing the version of the JSON schema."
},
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
"vendor": { "$ref": "#/definitions/vendor" },
"configurePresets": { "$ref": "#/definitions/configurePresetsV7" },
"buildPresets": { "$ref": "#/definitions/buildPresetsV4" },
"testPresets": { "$ref": "#/definitions/testPresetsV6" },
"packagePresets": { "$ref": "#/definitions/packagePresetsV6" },
"workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" },
"include": { "$ref": "#/definitions/include" }
},
"additionalProperties": false
}
],
"required": [

2
Help/policy/CMP0066.rst
View File

@ -18,7 +18,7 @@ variables like :variable:`CMAKE_<LANG>_FLAGS_DEBUG` and only use CMake's
built-in defaults for the current compiler and platform.
The ``NEW`` behavior of this policy is to honor config-specific flag
variabldes like :variable:`CMAKE_<LANG>_FLAGS_DEBUG`.
variables like :variable:`CMAKE_<LANG>_FLAGS_DEBUG`.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.7
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn by default

15
Help/policy/CMP0097.rst
View File

@ -4,9 +4,7 @@ CMP0097
.. versionadded:: 3.16
:command:`ExternalProject_Add` with ``GIT_SUBMODULES ""`` initializes no
submodules. The policy also applies to :command:`FetchContent_Declare`,
which uses the same download and update features as
:command:`ExternalProject_Add`.
submodules.
The commands provide a ``GIT_SUBMODULES`` option which controls what submodules
to initialize and update. Starting with CMake 3.16, explicitly setting
@ -25,4 +23,15 @@ an empty string to initialize and update no git submodules.
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt
.. note::
This policy also applies to :command:`FetchContent_Declare`,
which uses the same download and update features as
:command:`ExternalProject_Add`. However, due to an implementation deficiency
present since the policy was first introduced, CMake 3.16 and later always
uses the ``NEW`` behavior for :command:`FetchContent_Declare`, regardless of
the policy setting. Formally, this forcing of ``NEW`` behavior for
:command:`FetchContent_Declare` will continue to apply in future CMake
releases.
.. include:: DEPRECATED.txt

19
Help/policy/CMP0099.rst
View File

@ -3,13 +3,16 @@ CMP0099
.. versionadded:: 3.17
Target link properties :prop_tgt:`INTERFACE_LINK_OPTIONS`,
:prop_tgt:`INTERFACE_LINK_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_DEPENDS`
are now transitive over private dependencies of static libraries.
Link properties are transitive over private dependencies of static libraries.
In CMake 3.16 and below the interface link properties attached to libraries
are not propagated for private dependencies of static libraries.
In CMake 3.16 and below, evaluation of target properties
:prop_tgt:`INTERFACE_LINK_OPTIONS`, :prop_tgt:`INTERFACE_LINK_DIRECTORIES`,
and :prop_tgt:`INTERFACE_LINK_DEPENDS` during buildsystem generation does not
follow private dependencies of static libraries, which appear in their
:prop_tgt:`INTERFACE_LINK_LIBRARIES` guarded by :genex:`LINK_ONLY` generator
expressions.
Only the libraries themselves are propagated to link the dependent binary.
CMake 3.17 and later prefer to propagate all interface link properties.
This policy provides compatibility for projects that have not been updated
to expect the new behavior.
@ -18,6 +21,12 @@ The ``OLD`` behavior for this policy is to not propagate interface link
properties. The ``NEW`` behavior of this policy is to propagate interface link
properties.
.. versionadded:: 3.30
Policy :policy:`CMP0166` makes :genex:`TARGET_PROPERTY` evaluation of
these three transitive link properties follow private dependencies of
static libraries too.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.17
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

35
Help/policy/CMP0118.rst
View File

@ -3,25 +3,36 @@ CMP0118
.. versionadded:: 3.20
The :prop_sf:`GENERATED` source file property is now visible in all directories.
:prop_sf:`GENERATED` sources may be used across directories without manual marking.
In CMake 3.19 and below, the :prop_sf:`GENERATED` source file property,
like other source file properties, was scoped in every directory separately.
If a source file was generated in one directory, projects had to manually
set the ``GENERATED`` property in another directory in order to use the file.
Whether or not a source file is generated is an all-or-nothing global
property of the source. Consequently, the associated ``GENERATED``
property is now visible from any directory scope, not only from the scope
for which it was set.
property of the source: a source is either generated or it is not.
CMake 3.20 and above prefer to allow source files generated in one directory
to be used in other directories without manually marking them as ``GENERATED``.
Additionally, the ``GENERATED`` property may now be set only to boolean
values, and may not be turned off once turned on.
values, and may not be turned off once turned on. This policy provides
compatibility for projects that have not been updated for this behavior.
The ``OLD`` behavior of this policy is to only allow ``GENERATED`` to be
visible from the directory scope for which it was set. The ``NEW``
behavior on the other hand allows it to be visible from any scope.
The ``OLD`` behavior of this policy is to allow generated files to be used
only in directories in which their ``GENERATED`` property has been turned on.
The ``NEW`` behavior of this policy is to allow generated files to be used
in other directories without explicitly turning on the ``GENERATED`` property
for those directories.
.. versionadded:: 3.30
Policy :policy:`CMP0163` additionally makes the :prop_sf:`GENERATED` source
file property visible to :command:`get_property` and
:command:`get_source_file_property` calls in other directories.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.20
.. |WARNS_OR_DOES_NOT_WARN| replace::
does *not* warn with regard to visibility of the ``GENERATED``
property, but does warn about setting the ``GENERATED`` property
to a non-boolean value,
warns about setting the ``GENERATED`` property to a non-boolean value
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

18
Help/policy/CMP0135.rst
View File

@ -4,20 +4,20 @@ CMP0135
.. versionadded:: 3.24
When using the ``URL`` download method with the :command:`ExternalProject_Add`
command, CMake 3.23 and below sets the timestamps of the extracted contents
to the same as the timestamps in the archive. When the ``URL`` changes, the
new archive is downloaded and extracted, but the timestamps of the extracted
contents might not be newer than the previous contents. Anything that depends
on the extracted contents might not be rebuilt, even though the contents may
change.
or :command:`FetchContent_Declare` commands, CMake 3.23 and below sets the
timestamps of the extracted contents to the same as the timestamps in the
archive. When the ``URL`` changes, the new archive is downloaded and extracted,
but the timestamps of the extracted contents might not be newer than the
previous contents. Anything that depends on the extracted contents might not
be rebuilt, even though the contents may change.
CMake 3.24 and above prefers to set the timestamps of all extracted contents
to the time of the extraction. This ensures that anything that depends on the
extracted contents will be rebuilt whenever the ``URL`` changes.
The ``DOWNLOAD_EXTRACT_TIMESTAMP`` option to the
:command:`ExternalProject_Add` command can be used to explicitly specify how
timestamps should be handled. When ``DOWNLOAD_EXTRACT_TIMESTAMP`` is not
The ``DOWNLOAD_EXTRACT_TIMESTAMP`` option to the :command:`ExternalProject_Add`
and :command:`FetchContent_Declare` commands can be used to explicitly specify
how timestamps should be handled. When ``DOWNLOAD_EXTRACT_TIMESTAMP`` is not
given, this policy controls the default behavior. The ``OLD`` behavior for
this policy is to restore the timestamps from the archive. The ``NEW``
behavior sets the timestamps of extracted contents to the time of extraction.

47
Help/policy/CMP0162.rst Normal file
View File

@ -0,0 +1,47 @@
CMP0162
-------
.. versionadded:: 3.30
:ref:`Visual Studio Generators` add ``UseDebugLibraries`` indicators by default.
The "Use Debug Libraries" setting in Visual Studio projects indicates what
configurations are considered debug configurations. In standalone projects,
this may affect MSBuild's default selection of MSVC runtime library,
optimization flags, runtime checks, and similar settings. CMake typically
generates all those settings explicitly based on the project's specification,
so CMake 3.29 and below do not write any ``UseDebugLibraries`` indicators to
``.vcxproj`` files.
CMake 3.30 and above prefer to write ``UseDebugLibraries`` indicators because
they are useful for reference by both humans and tools, and may also affect
the behavior of platform-specific SDKs. The indicator for each configuration
of a target is determined as follows:
* If the target compiles sources for a known MSVC runtime library
(such as that specified by :prop_tgt:`MSVC_RUNTIME_LIBRARY`),
then ``UseDebugLibraries`` is ``true`` for configurations that
compile for a "Debug" runtime library, and ``false`` for others.
* Otherwise, such as in targets created by :command:`add_custom_target`,
``UseDebugLibraries`` is ``true`` for the ``Debug`` configuration,
and ``false`` for others.
This policy provides compatibility for projects that have not been updated to
expect the indicators. The policy setting is recorded by each target as it is
created and used to determine the default behavior for that target's
``.vcxproj`` file.
The ``OLD`` behavior for this policy is to not generate ``UseDebugLibraries``
indicators by default. The ``NEW`` behavior for this policy is to generate
``UseDebugLibraries`` indicators by default.
If the :variable:`CMAKE_VS_USE_DEBUG_LIBRARIES` variable and/or
:prop_tgt:`VS_USE_DEBUG_LIBRARIES` target property is set, it explicitly
controls ``UseDebugLibraries`` generation regardless of this policy.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

37
Help/policy/CMP0163.rst Normal file
View File

@ -0,0 +1,37 @@
CMP0163
-------
.. versionadded:: 3.30
The :prop_sf:`GENERATED` source file property is now visible in all directories.
In CMake 3.29 and below, the :prop_sf:`GENERATED` source file property,
like other source file properties, was scoped in every directory separately.
Although policy :policy:`CMP0118` allowed sources marked ``GENERATED`` in one
directory to be used in other directories without manually marking them as
``GENERATED`` again, the ``GENERATED`` property was still not visible to
:command:`get_property` and :command:`get_source_file_property` calls.
Whether or not a source file is generated is an all-or-nothing global
property of the source: a source is either generated or it is not.
CMake 3.30 and above prefer to treat the :prop_sf:`GENERATED` source file
property as globally scoped. Once it is set in one directory, it is
immediately visible to :command:`get_property` and
:command:`get_source_file_property` calls in other directories.
This policy provides compatibility for projects that have not been
updated for this behavior.
The ``OLD`` behavior of this policy is for the ``GENERATED`` source file
property to be visible only in the directories in which it is set. The
``NEW`` behavior of this policy is to allow the ``GENERATED`` source file
property to be visible in all directories once set in any directory.
Furthermore, the ``NEW`` behavior of this policy implies the ``NEW``
behavior of policy :policy:`CMP0118`: the ``GENERATED`` property may
be set only to boolean values, and may not be turned off once turned on.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
.. |WARNS_OR_DOES_NOT_WARN| replace::
does *not* warn
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

31
Help/policy/CMP0164.rst Normal file
View File

@ -0,0 +1,31 @@
CMP0164
-------
.. versionadded:: 3.30
:command:`add_library` rejects ``SHARED`` libraries when not supported by
the platform.
In CMake 3.29 and below, on platforms that do not support shared libraries
(:prop_gbl:`TARGET_SUPPORTS_SHARED_LIBS` is false), the
:command:`add_library` command automatically converts ``SHARED`` libraries to
``STATIC`` libraries to help users build projects on such platforms. However,
the semantics of shared and static libraries are different enough that such
automatic conversion cannot work in general. Projects using shared libraries
need to be ported to such platforms on a case-by-case basis.
In CMake 3.30 and above, :command:`add_library` prefers to reject creation
of shared libraries on platforms that do not support them, and fail with a
fatal error message. This policy provides compatibility for projects that
happened to work with the automatic conversion to static libraries and have
not been updated with an explicit port.
The ``OLD`` behavior for this policy is to implicitly create a static
library with a developer warning. The ``NEW`` behavior for this policy is
to fail.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn about the behavior change
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

26
Help/policy/CMP0165.rst Normal file
View File

@ -0,0 +1,26 @@
CMP0165
-------
.. versionadded:: 3.30
:command:`enable_language` must not be called before :command:`project`.
In CMake 3.29 and below, if a project called :command:`enable_language`
before the first call to :command:`project`, the language would be enabled
but possibly using unset details that were expected to be set.
In CMake 3.30 and above, :command:`enable_language` prefers to reject this
case and stop with a fatal error instead if it detects that :command:`project`
has not yet been called. This policy provides compatibility for projects that
happened to work when :command:`enable_language` was called before
:command:`project` and have not been updated to call these commands in the
required order.
The ``OLD`` behavior for this policy is to allow :command:`enable_language`
to be called before :command:`project`. The ``NEW`` behavior for this policy
is to fail with a fatal error in such cases.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

40
Help/policy/CMP0166.rst Normal file
View File

@ -0,0 +1,40 @@
CMP0166
-------
.. versionadded:: 3.30
:genex:`TARGET_PROPERTY` evaluates link properties transitively over private
dependencies of static libraries.
In CMake 3.29 and below, the :genex:`TARGET_PROPERTY` generator expression
evaluates properties :prop_tgt:`INTERFACE_LINK_OPTIONS`,
:prop_tgt:`INTERFACE_LINK_DIRECTORIES`, and :prop_tgt:`INTERFACE_LINK_DEPENDS`
as if they were :ref:`Transitive Compile Properties` rather than
:ref:`Transitive Link Properties`, even when policy :policy:`CMP0099` is
set to ``NEW``. Private dependencies of static libraries, which appear in
their :prop_tgt:`INTERFACE_LINK_LIBRARIES` guarded by :genex:`LINK_ONLY`
generator expressions, are not followed. This is inconsistent with
evaluation of the same target properties during buildsystem generation.
CMake 3.30 and above prefer that :genex:`TARGET_PROPERTY` evaluates
properties :prop_tgt:`INTERFACE_LINK_OPTIONS`,
:prop_tgt:`INTERFACE_LINK_DIRECTORIES`, and :prop_tgt:`INTERFACE_LINK_DEPENDS`
as :ref:`Transitive Link Properties` such that private dependencies of static
libraries, which appear in their :prop_tgt:`INTERFACE_LINK_LIBRARIES` guarded
by :genex:`LINK_ONLY` generator expressions, are followed.
This policy provides compatibility for projects that have not been updated
to expect the new behavior.
The ``OLD`` behavior for this policy is for :genex:`TARGET_PROPERTY` to
evaluate properties :prop_tgt:`INTERFACE_LINK_OPTIONS`,
:prop_tgt:`INTERFACE_LINK_DIRECTORIES`, and :prop_tgt:`INTERFACE_LINK_DEPENDS`
as if they were :ref:`Transitive Compile Properties` by not following private
dependencies of static libraries. The ``NEW`` behavior for this policy is
to evaluate them as :ref:`Transitive Link Properties` by following private
dependencies of static libraries.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

28
Help/policy/CMP0167.rst Normal file
View File

@ -0,0 +1,28 @@
CMP0167
-------
.. versionadded:: 3.30
The :module:`FindBoost` module is removed.
CMake 3.29 and below provide a ``FindBoost`` module, but it needs constant
updates to keep up with upstream Boost releases. Upstream Boost 1.70
and above provide a ``BoostConfig.cmake`` package configuration file.
``find_package(Boost CONFIG)`` finds the upstream package directly,
without the find module.
CMake 3.30 and above prefer to not provide the ``FindBoost`` module
so that ``find_package(Boost)`` calls, without the ``CONFIG`` or
``NO_MODULE`` options, find the upstream ``BoostConfig.cmake`` directly.
This policy provides compatibility for projects that have not been ported
to use the upstream Boost package.
The ``OLD`` behavior of this policy is for ``find_package(Boost)`` to
load CMake's :module:`FindBoost` module. The ``NEW`` behavior is for
``find_package(Boost)`` to search for the upstream ``BoostConfig.cmake``.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

72
Help/policy/CMP0168.rst Normal file
View File

@ -0,0 +1,72 @@
CMP0168
-------
.. versionadded:: 3.30
The :module:`FetchContent` module implements steps directly instead of through
a sub-build.
CMake 3.29 and below implement FetchContent as a separate sub-build.
This required configuring that separate project and using a build tool.
This approach can be very slow with some generators and operating systems.
CMake 3.30 and above prefer to implement the download, update, and patch
steps directly as part of the main project.
The ``NEW`` behavior has the following characteristics:
* No sub-build is used. All operations are implemented directly from the
main project's CMake configure step. When running in CMake script mode,
no build tool needs to be available.
* Generator expressions and GNU Make variables of the form ``$(SOMEVAR)`` are
not supported. They should not be used in any argument to
:command:`FetchContent_Declare` or :command:`FetchContent_Populate`.
* All ``LOG_...`` and ``USES_TERMINAL_...`` options, the ``QUIET`` option, and
the :variable:`FETCHCONTENT_QUIET` variable are ignored.
:module:`FetchContent` output is always part of the main project's configure
output. This also means it now respects the message logging level (see
:variable:`CMAKE_MESSAGE_LOG_LEVEL` and
:option:`--log-level <cmake --log-level>`). The default message log level
should be comparable to using ``QUIET`` with the ``OLD`` policy setting,
except that warnings will now be shown.
* The ``PREFIX``, ``TMP_DIR``, ``STAMP_DIR``, ``LOG_DIR``, and ``DOWNLOAD_DIR``
options and their associated directory properties are ignored. The
:module:`FetchContent` module controls those locations internally.
* :option:`cmake --fresh` will remove the stamp and script files used for
tracking and populating the dependency. This will force the dependency's
download, update, and patch steps to be re-executed. The directory used for
downloads is not affected by :option:`cmake --fresh`, so any previously
downloaded files for the ``URL`` download method can still be re-used.
The ``OLD`` behavior has the following characteristics:
* A sub-build is always used to implement the download, update, and patch
steps. A build tool must be available, even when using
:command:`FetchContent_Populate` in CMake script mode.
* Generator expressions and GNU Make variables of the form ``$(SOMEVAR)`` can
be used, although such use is almost always inappropriate. They are evaluated
in the sub-build, so they do not see any information from the main build.
* All logging, terminal control, and directory options related to the download,
update, or patch steps are supported.
* If the ``QUIET`` option is used, or the :variable:`FETCHCONTENT_QUIET`
variable is set to true, warnings will not be shown in the output.
* :option:`cmake --fresh` has no effect on the dependency's stamp or script
files. Previously executed steps will only re-run if details about the
dependency have changed.
There's a reasonably good chance that users can set the
:variable:`CMAKE_POLICY_DEFAULT_CMP0168 <CMAKE_POLICY_DEFAULT_CMP<NNNN>>`
variable to ``NEW`` to globally switch to the ``NEW`` behavior while waiting
for the project and its dependencies to be updated use the ``NEW`` policy
setting by default. Projects don't typically make use of the features that the
``NEW`` behavior no longer supports, and even those projects that do will often
still work fine when those options are ignored. Before setting this behavior
globally, check whether any :command:`FetchContent_Declare` or
:command:`FetchContent_Populate` calls use the ignored options in a way that
would change observable behavior, other than putting temporary or
internally-generated files in different locations.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

49
Help/policy/CMP0169.rst Normal file
View File

@ -0,0 +1,49 @@
CMP0169
-------
.. versionadded:: 3.30
Calling :command:`FetchContent_Populate` with a single argument (the name of
a declared dependency) is deprecated.
Prior to the introduction of :command:`FetchContent_MakeAvailable`, projects
populated previously declared content (with :command:`FetchContent_Declare`)
using the following pattern:
.. code-block:: cmake
FetchContent_GetProperties(depname)
if(NOT depname_POPULATED)
FetchContent_Populate(depname)
add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR})
endif()
The above pattern does not support a number of features that have been added
to :module:`FetchContent` over time. It ignores options like ``SYSTEM`` and
``EXCLUDE_FROM_ALL`` which may be given to :command:`FetchContent_Declare`,
but can't be made known to the above project code. It also does not support
:ref:`dependency providers <dependency_providers_overview>`.
Projects should call :command:`FetchContent_MakeAvailable` instead of using
the above pattern.
CMake 3.30 and above prefers to reject calls to
:command:`FetchContent_Populate` with the name of a declared dependency.
This policy provides compatibility for projects that have not been updated
to call :command:`FetchContent_MakeAvailable` instead.
The ``OLD`` behavior of this policy allows :command:`FetchContent_Populate`
to be called with the name of a declared dependency.
The ``NEW`` behavior halts with a fatal error in such cases.
.. note::
Calling :command:`FetchContent_Populate` with the full population details
as command arguments rather than just a dependency name remains fully
supported. Only the form calling :command:`FetchContent_Populate` with a
single argument (the name of a previously declared dependency) is deprecated
with this policy.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

30
Help/policy/CMP0170.rst Normal file
View File

@ -0,0 +1,30 @@
CMP0170
-------
.. versionadded:: 3.30
When ``FETCHCONTENT_FULLY_DISCONNECTED`` is set to true,
:command:`FetchContent_MakeAvailable` and :command:`FetchContent_Populate`
enforce the constraint that their source directory must already be populated.
The requirement has always been documented, but it was not checked or enforced
with CMake 3.29 or older. This sometimes led to hard-to-trace errors when a
project expected a dependency to have been populated, but its population was
silently skipped.
CMake 3.30 and above prefers to check and enforce the constraint.
This policy provides compatibility for situations where the user cannot easily
prevent ``FETCHCONTENT_FULLY_DISCONNECTED`` from being inappropriately set
to true.
The ``OLD`` behavior of this policy allows ``FETCHCONTENT_FULLY_DISCONNECTED``
to be set to true even if a dependency's source directory has not been
populated.
The ``NEW`` behavior halts with a fatal error if
``FETCHCONTENT_FULLY_DISCONNECTED`` is set to true and a dependency population
would be skipped, but that dependency's source directory doesn't exist.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

27
Help/prop_dir/EXCLUDE_FROM_ALL.rst
View File

@ -8,6 +8,27 @@ subdirectory by default. This does not affect the "all" target of the
subdirectory itself. Running e.g. ``make`` inside the subdirectory will
still build its targets.
If the :prop_tgt:`EXCLUDE_FROM_ALL` target property is set on a target
then its value determines whether the target is included in the "all"
target of this directory and its ancestors.
``EXCLUDE_FROM_ALL`` is meant for when the subdirectory contains
a separate part of the project that is useful, but not necessary,
such as a set of examples, or e.g. an integrated 3rd party library.
Typically the subdirectory should contain its own :command:`project`
command invocation so that a full build system will be generated in the
subdirectory (such as a Visual Studio IDE solution file). Note that
inter-target dependencies supersede this exclusion. If a target built by
the parent project depends on a target in the subdirectory, the dependee
target will be included in the parent project build system to satisfy
the dependency.
If the ``EXCLUDE_FROM_ALL`` argument is provided, it has the following effects:
* Targets defined in the subdirectory or below will not be
included in the ``ALL`` target of the parent directory.
Those targets must be built explicitly by the user,
or be a dependency of another target that will be built.
* Targets defined in the subdirectory or below will be
excluded from IDE project files.
* Any install rules defined in the subdirectory or below will
be ignored when installing the parent directory.
Note that these effects are not the same as those for the
:prop_tgt:`EXCLUDE_FROM_ALL` target property.

2
Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst
View File

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

2
Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst
View File

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

2
Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst
View File

@ -37,7 +37,7 @@ The features known to this version of CMake are:
Compiler mode is at least CUDA/C++ 23.
``cuda_std_26``
.. versionadded:: 3.25
.. versionadded:: 3.30
Compiler mode is at least CUDA/C++ 26.

2
Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst
View File

@ -47,7 +47,7 @@ but it does not necessarily imply complete conformance to that standard.
Compiler mode is at least C++ 23.
``cxx_std_26``
.. versionadded:: 3.25
.. versionadded:: 3.30
Compiler mode is at least C++ 26.

42
Help/prop_gbl/CMAKE_HIP_KNOWN_FEATURES.rst Normal file
View File

@ -0,0 +1,42 @@
CMAKE_HIP_KNOWN_FEATURES
------------------------
.. versionadded:: 3.30
List of HIP features known to this version of CMake.
The features listed in this global property may be known to be available to the
HIP compiler. If the feature is available with the HIP compiler, it will
be listed in the :variable:`CMAKE_HIP_COMPILE_FEATURES` variable.
The features listed here may be used with the :command:`target_compile_features`
command. See the :manual:`cmake-compile-features(7)` manual for information on
compile features and a list of supported compilers.
The features known to this version of CMake are:
``hip_std_98``
Compiler mode is at least HIP/C++ 98.
``hip_std_11``
Compiler mode is at least HIP/C++ 11.
``hip_std_14``
Compiler mode is at least HIP/C++ 14.
``hip_std_17``
Compiler mode is at least HIP/C++ 17.
``hip_std_20``
Compiler mode is at least HIP/C++ 20.
``hip_std_23``
Compiler mode is at least HIP/C++ 23.
``hip_std_26``
.. versionadded:: 3.30
Compiler mode is at least HIP/C++ 26.
.. include:: CMAKE_LANG_STD_FLAGS.txt

23
Help/prop_gbl/INSTALL_PARALLEL.rst Normal file
View File

@ -0,0 +1,23 @@
INSTALL_PARALLEL
----------------
.. versionadded:: 3.30
Enables parallel installation option for the Ninja generator.
When this property is ``ON``, ``install/local`` targets have the
console pool disabled, allowing them to run concurrently.
This property also provides the target ``install/parallel``, which has an
explicit dependency on the ``install/local`` target for each subdirectory,
recursing down the project.
Setting this property has no affect on the behavior of ``cmake --install``.
The install must be invoked by building the ``install/parallel`` target
directly.
Calls to :command:`install(CODE)` or :command:`install(SCRIPT)` might depend
on actions performed by an earlier :command:`install` command in a different
directory such as files installed or variable settings. If the project has
such order-dependent installation logic, parallel installation should be
not be enabled, in order to prevent possible race conditions.

19
Help/prop_gbl/PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE.rst Normal file
View File

@ -0,0 +1,19 @@
PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE
-------------------------------------------
.. versionadded:: 3.30
When this global property is set to true, the
:variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable is propagated into
:command:`try_compile` calls that use the
:ref:`whole-project signature <Try Compiling Whole Projects>`.
Calls to the :ref:`source file signature <Try Compiling Source Files>` are not
affected by this property.
``PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE`` is unset by default.
For :ref:`dependency providers <dependency_providers_overview>` that want to
be enabled in whole-project :command:`try_compile` calls, set this global
property to true just before or after registering the provider.
Note that all files listed in :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES`
will need to be able to handle being included in such :command:`try_compile`
calls, and it is the user's responsibility to ensure this.

4
Help/prop_gbl/TARGET_SUPPORTS_SHARED_LIBS.rst
View File

@ -3,7 +3,7 @@ TARGET_SUPPORTS_SHARED_LIBS
Does the target platform support shared libraries.
TARGET_SUPPORTS_SHARED_LIBS is a boolean specifying whether the target
``TARGET_SUPPORTS_SHARED_LIBS`` is a boolean specifying whether the target
platform supports shared libraries. Basically all current general
general purpose OS do so, the exception are usually embedded systems
purpose OS do so, the exceptions are usually embedded systems
with no or special OSs.

3
Help/prop_sf/COMPILE_FLAGS.rst
View File

@ -5,8 +5,7 @@ Additional flags to be added when compiling this source file.
The ``COMPILE_FLAGS`` property, managed as a string, sets additional compiler
flags used that will be added to the list of compile flags when this source
file builds. The flags will be added after target-wide flags (except in
some cases not supported by the :generator:`Visual Studio 9 2008` generator).
file builds. The flags will be added after target-wide flags.
Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions.

3
Help/prop_sf/COMPILE_OPTIONS.rst
View File

@ -7,8 +7,7 @@ List of additional options to pass to the compiler.
This property holds a :ref:`semicolon-separated list <CMake Language Lists>`
of options and will be added to the list of compile flags when this source
file builds. The options will be added after target-wide options (except in
some cases not supported by the :generator:`Visual Studio 9 2008` generator).
file builds. The options will be added after target-wide options.
Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the
syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual

19
Help/prop_sf/GENERATED.rst
View File

@ -4,7 +4,16 @@ GENERATED
Is this source file generated as part of the build or CMake process.
.. versionchanged:: 3.20
The GENERATED source file property is now visible in all directories.
Turning on the ``GENERATED`` source file property in one directory allows
the associated source file to be used across directories without the need
to manually setting that property for other directory scopes, too.
Additionally, it may now be set only to boolean values, and may not be
turned off once turned on. See policy :policy:`CMP0118`.
.. versionchanged:: 3.30
Whether or not a source file is generated is an all-or-nothing global
property of the source. Consequently, the ``GENERATED`` source file
property is now visible in all directories. See policy :policy:`CMP0163`.
Tells the internal CMake engine that a source file is generated by an outside
process such as another build step, or the execution of CMake itself.
@ -38,11 +47,3 @@ be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMO
:prop_gbl:`AUTORCC_SOURCE_GROUP` and :prop_gbl:`AUTOUIC_SOURCE_GROUP` target
properties may influence where the generated sources are grouped in the project's
file lists.
.. note::
Starting with CMake 3.20 the ``GENERATED`` source file property can be set
and retrieved from any directory scope. It is an all-or-nothing property.
It also can no longer be removed or unset if it was set to ``TRUE``. Policy
:policy:`CMP0118` was introduced to allow supporting the ``OLD`` behavior
for some time.

2
Help/prop_tgt/AUTOUIC_OPTIONS.rst
View File

@ -1,6 +1,8 @@
AUTOUIC_OPTIONS
---------------
.. versionadded:: 3.0
Additional options for ``uic`` when using :prop_tgt:`AUTOUIC`
This property holds additional command line options which will be used when

41
Help/prop_tgt/CXX_MODULE_STD.rst Normal file
View File

@ -0,0 +1,41 @@
CXX_MODULE_STD
--------------
.. versionadded:: 3.30
``CXX_MODULE_STD`` is a boolean specifying whether the target may use
``import std;`` its C++ sources or not.
.. note ::
This setting is meaningful only when experimental support for ``import
std;`` has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_IMPORT_STD`` gate.
When this property is explicitly set to ``ON``, CMake will add a dependency to
a target which provides the C++ standard library's modules for the C++
standard applied to the target. This target is only applicable within the
current build and will not appear in the exported interfaces of the targets.
When consumed, these targets will be reapplied as necessary.
.. note:
Similar to the introduction of :prop:`CXX_SCAN_FOR_MODULES`, this property
defaults to _not_ adding ``import std`` support to targets using
``cxx_std_23`` without an explicit request in order to preserve existing
behavior for projects using C++23 without ``import std``. A future policy
to change the default behavior is expected once the feature sees wider
usage.
This property's value is not relevant for targets which disable scanning (see
:prop_tgt:`CXX_SCAN_FOR_MODULES`). Additionally, this property only applies to
targets utilizing C++23 (``cxx_std_23``) or newer.
The property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`, however
expressions that depend upon the configuration, the consuming target, or the
linker language are not allowed. Whether a target uses ``import std`` should
not depend upon such things as it is a static property of the target's source
code.
Targets which are exported with C++ module sources will have this property's
resolved value exported.

2
Help/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES.rst
View File

@ -4,7 +4,7 @@ DEPLOYMENT_ADDITIONAL_FILES
.. versionadded:: 3.13
Set the WinCE project ``AdditionalFiles`` in ``DeploymentTool`` in ``.vcproj``
files generated by the :generator:`Visual Studio 9 2008` generator.
files generated by the :ref:`Visual Studio Generators`.
This is useful when you want to debug on remote WinCE device.
Specify additional files that will be copied to the device.
For example:

2
Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst
View File

@ -5,7 +5,7 @@ DEPLOYMENT_REMOTE_DIRECTORY
Set the WinCE project ``RemoteDirectory`` in ``DeploymentTool`` and
``RemoteExecutable`` in ``DebuggerTool`` in ``.vcproj`` files generated
by the :generator:`Visual Studio 9 2008` generator.
by the :ref:`Visual Studio Generators`.
This is useful when you want to debug on remote WinCE device.
For example:

2
Help/prop_tgt/INTERFACE_AUTOUIC_OPTIONS.rst
View File

@ -1,6 +1,8 @@
INTERFACE_AUTOUIC_OPTIONS
-------------------------
.. versionadded:: 3.0
List of interface options to pass to uic.
Targets may populate this property to publish the options

2
Help/prop_tgt/LANG_STANDARD.rst
View File

@ -18,7 +18,7 @@ controlled with the :prop_tgt:`<LANG>_STANDARD_REQUIRED` target property.
Note that the actual language standard used may be higher than that specified
by ``<LANG>_STANDARD``, regardless of the value of
:prop_tgt:`<LANG>_STANDARD_REQUIRED`. In particular,
:ref:`transitive usage requirements <Target Usage Requirements>` or the use of
:ref:`usage requirements <Target Usage Requirements>` or the use of
:manual:`compile features <cmake-compile-features(7)>` can raise the required
language standard above what ``<LANG>_STANDARD`` specifies.

2
Help/prop_tgt/LANG_STANDARD_REQUIRED.rst
View File

@ -20,7 +20,7 @@ error will be issued if that requirement cannot be met.
Note that the actual language standard used may be higher than that specified
by :prop_tgt:`<LANG>_STANDARD`, regardless of the value of
``<LANG>_STANDARD_REQUIRED``. In particular,
:ref:`transitive usage requirements <Target Usage Requirements>` or the use of
:ref:`usage requirements <Target Usage Requirements>` or the use of
:manual:`compile features <cmake-compile-features(7)>` can raise the required
language standard above what :prop_tgt:`<LANG>_STANDARD` specifies.

3
Help/prop_tgt/LINKER_TYPE.rst
View File

@ -8,8 +8,7 @@ Specify which linker will be used for the link step. The property value may use
.. include:: ../variable/LINKER_PREDEFINED_TYPES.txt
This property is not supported on :generator:`Green Hills MULTI` and
:generator:`Visual Studio 9 2008` generators.
This property is not supported on :generator:`Green Hills MULTI` generator.
The implementation details for the selected linker will be provided by the
:variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` variable. For example:

2
Help/prop_tgt/SOURCES.rst
View File

@ -18,7 +18,7 @@ evaluate to an absolute path. Not doing so is considered undefined behavior.
Paths that are for files generated by the build will be treated
as relative to the build directory of the target, if the path is not
already specified as an absolute path. Note that whether a file is seen as
generated may be affected by policy :policy:`CMP0118`.
generated may be affected by policies :policy:`CMP0118` and :policy:`CMP0163`.
If a path does not start with a generator expression, is not an
absolute path and is not a generated file, it will be treated as relative to

12
Help/prop_tgt/Swift_MODULE_DIRECTORY.rst
View File

@ -10,3 +10,15 @@ the modules will be placed. When this property is not set, the modules will be
placed in the build directory corresponding to the target's source directory.
If the variable :variable:`CMAKE_Swift_MODULE_DIRECTORY` is set when a target is
created its value is used to initialize this property.
.. warning::
This property does not currently provide a way to express per-config
module directories, so use with multi-config generators is problematic:
* The :generator:`Xcode` generator does not implement the property at all.
* The :generator:`Ninja Multi-Config` generator implements this property,
but module files generated for different build configurations have the
same path, which can lead to subtle problems when building more than
one configuration.

19
Help/prop_tgt/TRANSITIVE_COMPILE_PROPERTIES.rst Normal file
View File

@ -0,0 +1,19 @@
TRANSITIVE_COMPILE_PROPERTIES
-----------------------------
.. versionadded:: 3.30
Properties that the :genex:`TARGET_PROPERTY` generator expression, on the
target and its dependents, evaluates as the union of values collected from
the transitive closure of link dependencies, excluding entries guarded by
:genex:`LINK_ONLY`.
The value is a :ref:`semicolon-separated list <CMake Language Lists>`
of :ref:`custom transitive property <Custom Transitive Properties>` names.
Any leading ``INTERFACE_`` prefix is ignored, e.g., ``INTERFACE_PROP`` is
treated as just ``PROP``.
See documentation of the :genex:`TARGET_PROPERTY` generator expression
for details of custom transitive property evaluation. See also the
:prop_tgt:`TRANSITIVE_LINK_PROPERTIES` target property, which includes
entries guarded by :genex:`LINK_ONLY`.

19
Help/prop_tgt/TRANSITIVE_LINK_PROPERTIES.rst Normal file
View File

@ -0,0 +1,19 @@
TRANSITIVE_LINK_PROPERTIES
--------------------------
.. versionadded:: 3.30
Properties that the :genex:`TARGET_PROPERTY` generator expression, on the
target and its dependents, evaluates as the union of values collected from
the transitive closure of link dependencies, including entries guarded by
:genex:`LINK_ONLY`.
The value is a :ref:`semicolon-separated list <CMake Language Lists>`
of :ref:`custom transitive property <Custom Transitive Properties>` names.
Any leading ``INTERFACE_`` prefix is ignored, e.g., ``INTERFACE_PROP`` is
treated as just ``PROP``.
See documentation of the :genex:`TARGET_PROPERTY` generator expression
for details of custom transitive property evaluation. See also the
:prop_tgt:`TRANSITIVE_COMPILE_PROPERTIES` target property, which excludes
entries guarded by :genex:`LINK_ONLY`..

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