Update upstream source from tag 'upstream/3.31.0'

Update to upstream version '3.31.0'
with Debian dir 1d344e6970
ci/unstable
Timo Röhling 1 month ago
commit 6d77f15746

@ -2,6 +2,7 @@
Checks: "-*,\ Checks: "-*,\
bugprone-*,\ bugprone-*,\
-bugprone-assignment-in-if-condition,\ -bugprone-assignment-in-if-condition,\
-bugprone-crtp-constructor-accessibility,\
-bugprone-easily-swappable-parameters,\ -bugprone-easily-swappable-parameters,\
-bugprone-empty-catch,\ -bugprone-empty-catch,\
-bugprone-implicit-widening-of-multiplication-result,\ -bugprone-implicit-widening-of-multiplication-result,\
@ -10,19 +11,23 @@ bugprone-*,\
-bugprone-misplaced-widening-cast,\ -bugprone-misplaced-widening-cast,\
-bugprone-multi-level-implicit-pointer-conversion,\ -bugprone-multi-level-implicit-pointer-conversion,\
-bugprone-narrowing-conversions,\ -bugprone-narrowing-conversions,\
-bugprone-return-const-ref-from-parameter,\
-bugprone-suspicious-stringview-data-usage,\
-bugprone-switch-missing-default-case,\ -bugprone-switch-missing-default-case,\
-bugprone-too-small-loop-variable,\ -bugprone-too-small-loop-variable,\
-bugprone-unchecked-optional-access,\ -bugprone-unchecked-optional-access,\
-bugprone-unused-local-non-trivial-variable,\ -bugprone-unused-local-non-trivial-variable,\
-bugprone-unused-return-value,\ -bugprone-unused-return-value,\
-bugprone-use-after-move,\
misc-*,\ misc-*,\
-misc-confusable-identifiers,\ -misc-confusable-identifiers,\
-misc-const-correctness,\ -misc-const-correctness,\
-misc-include-cleaner,\ -misc-include-cleaner,\
-misc-no-recursion,\
-misc-non-private-member-variables-in-classes,\ -misc-non-private-member-variables-in-classes,\
-misc-no-recursion,\
-misc-static-assert,\ -misc-static-assert,\
-misc-use-anonymous-namespace,\ -misc-use-anonymous-namespace,\
-misc-use-internal-linkage,\
modernize-*,\ modernize-*,\
-modernize-avoid-c-arrays,\ -modernize-avoid-c-arrays,\
-modernize-macro-to-enum,\ -modernize-macro-to-enum,\
@ -36,13 +41,14 @@ modernize-*,\
performance-*,\ performance-*,\
-performance-avoid-endl,\ -performance-avoid-endl,\
-performance-enum-size,\ -performance-enum-size,\
-performance-inefficient-vector-operation,\ -performance-unnecessary-copy-initialization,\
-performance-noexcept-swap,\ -performance-unnecessary-value-param,\
readability-*,\ readability-*,\
-readability-avoid-nested-conditional-operator,\ -readability-avoid-nested-conditional-operator,\
-readability-avoid-return-with-void-value,\ -readability-avoid-return-with-void-value,\
-readability-avoid-unconditional-preprocessor-if,\ -readability-avoid-unconditional-preprocessor-if,\
-readability-convert-member-functions-to-static,\ -readability-convert-member-functions-to-static,\
-readability-enum-initial-value,\
-readability-function-cognitive-complexity,\ -readability-function-cognitive-complexity,\
-readability-function-size,\ -readability-function-size,\
-readability-identifier-length,\ -readability-identifier-length,\
@ -51,6 +57,7 @@ readability-*,\
-readability-inconsistent-declaration-parameter-name,\ -readability-inconsistent-declaration-parameter-name,\
-readability-magic-numbers,\ -readability-magic-numbers,\
-readability-make-member-function-const,\ -readability-make-member-function-const,\
-readability-math-missing-parentheses,\
-readability-named-parameter,\ -readability-named-parameter,\
-readability-redundant-casting,\ -readability-redundant-casting,\
-readability-redundant-declaration,\ -readability-redundant-declaration,\
@ -61,6 +68,7 @@ readability-*,\
-readability-static-accessed-through-instance,\ -readability-static-accessed-through-instance,\
-readability-suspicious-call-argument,\ -readability-suspicious-call-argument,\
-readability-uppercase-literal-suffix,\ -readability-uppercase-literal-suffix,\
-readability-use-std-min-max,\
cmake-*,\ cmake-*,\
-cmake-ostringstream-use-cmstrcat,\ -cmake-ostringstream-use-cmstrcat,\
-cmake-string-concatenation-use-cmstrcat,\ -cmake-string-concatenation-use-cmstrcat,\

@ -173,7 +173,9 @@ _cmake()
printf -v quoted %q "$cur" printf -v quoted %q "$cur"
if [[ ! "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then if [[ ! "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
COMPREPLY=( $( compgen -W "configure${IFS}build${IFS}test${IFS}all" -- "$quoted" ) ) COMPREPLY=(
$( compgen -W "configure${IFS}build${IFS}package${IFS}test${IFS}workflow${IFS}all" -- "$quoted" )
)
fi fi
return return
;; ;;
@ -182,12 +184,16 @@ _cmake()
local quoted local quoted
printf -v quoted %q "$cur" printf -v quoted %q "$cur"
local build_or_configure="configure" local preset_type
if [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then if [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--workflow${IFS}" ]]; then
build_or_configure="build" preset_type="workflow"
elif [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
preset_type="build"
else
preset_type="configure"
fi fi
local presets=$( cmake --list-presets="$build_or_configure" 2>/dev/null | local presets=$( cmake --list-presets="$preset_type" 2>/dev/null |
grep -o "^ \".*\"" | sed \ grep -o "^ \".*\"" | sed \
-e "s/^ //g" \ -e "s/^ //g" \
-e "s/\"//g" \ -e "s/\"//g" \
@ -195,6 +201,24 @@ _cmake()
COMPREPLY=( $( compgen -W "$presets" -- "$quoted" ) ) COMPREPLY=( $( compgen -W "$presets" -- "$quoted" ) )
return return
;; ;;
--workflow)
local quoted
printf -v quoted %q "$cur"
# Options allowed right after `--workflow`
local workflow_options='--preset --list-presets --fresh'
if [[ "$cur" == -* ]]; then
COMPREPLY=( $( compgen -W "$workflow_options" -- "$quoted" ) )
else
local presets=$( cmake --list-presets=workflow 2>/dev/null |
grep -o "^ \".*\"" | sed \
-e "s/^ //g" \
-e "s/\"//g" \
-e 's/ /\\\\ /g' )
COMPREPLY=( $( compgen -W "$presets $workflow_options" -- "$quoted" ) )
fi
return
;;
esac esac
if ($is_old_completion || $is_init_completion); then if ($is_old_completion || $is_init_completion); then
@ -204,6 +228,8 @@ _cmake()
fi fi
if [[ "$cur" == -* ]]; then if [[ "$cur" == -* ]]; then
# FIXME(#26100): `cmake --help` is missing some options and does not
# have any mode-specific options like `cmake --build`'s `--config`.
COMPREPLY=( $(compgen -W '$( _parse_help "$1" --help )' -- ${cur}) ) COMPREPLY=( $(compgen -W '$( _parse_help "$1" --help )' -- ${cur}) )
[[ $COMPREPLY == *= ]] && compopt -o nospace [[ $COMPREPLY == *= ]] && compopt -o nospace
[[ $COMPREPLY ]] && return [[ $COMPREPLY ]] && return

@ -183,7 +183,7 @@ set the path with these commands:
) )
(defun cmake-point-in-indendation () (defun cmake-point-in-indendation ()
(string-match "^[ \\t]*$" (buffer-substring (point-at-bol) (point)))) (string-match "^[ \\t]*$" (buffer-substring (line-beginning-position) (point))))
(defun cmake-indent-line-to (column) (defun cmake-indent-line-to (column)
"Indent the current line to COLUMN. "Indent the current line to COLUMN.

@ -416,6 +416,7 @@ syn keyword cmakeProperty contained
\ VS_DOTNET_STARTUP_OBJECT \ VS_DOTNET_STARTUP_OBJECT
\ VS_DOTNET_TARGET_FRAMEWORK_VERSION \ VS_DOTNET_TARGET_FRAMEWORK_VERSION
\ VS_DPI_AWARE \ VS_DPI_AWARE
\ VS_FRAMEWORK_REFERENCES
\ VS_GLOBAL_KEYWORD \ VS_GLOBAL_KEYWORD
\ VS_GLOBAL_PROJECT_TYPES \ VS_GLOBAL_PROJECT_TYPES
\ VS_GLOBAL_ROOTNAMESPACE \ VS_GLOBAL_ROOTNAMESPACE

@ -1,7 +1,7 @@
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying # Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details. # file Copyright.txt or https://cmake.org/licensing for details.
cmake_minimum_required(VERSION 3.13...3.28 FATAL_ERROR) cmake_minimum_required(VERSION 3.13...3.29 FATAL_ERROR)
set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake) 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) set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake)
@ -267,9 +267,7 @@ macro(CMAKE_SETUP_TESTING)
endif() endif()
# configure some files for testing # configure some files for testing
configure_file(Templates/CTestScript.cmake.in CTestScript.cmake @ONLY)
configure_file(Tests/.NoDartCoverage Tests/.NoDartCoverage) configure_file(Tests/.NoDartCoverage Tests/.NoDartCoverage)
configure_file(Tests/.NoDartCoverage Modules/.NoDartCoverage)
configure_file(CTestCustom.cmake.in CTestCustom.cmake @ONLY) configure_file(CTestCustom.cmake.in CTestCustom.cmake @ONLY)
endmacro() endmacro()

@ -26,7 +26,8 @@ To contribute patches:
#. Fork the upstream `CMake Repository`_ into a personal account. #. Fork the upstream `CMake Repository`_ into a personal account.
#. Run `Utilities/SetupForDevelopment.sh`_ for local git configuration. #. Run `Utilities/SetupForDevelopment.sh`_ for local git configuration.
#. See `Building CMake`_ for building CMake locally. #. See `Building CMake`_ for building CMake locally.
#. See the `CMake Source Code Guide`_ for coding guidelines. #. See the `CMake Source Code Guide`_ for coding guidelines
and the `CMake Testing Guide`_ for testing instructions.
#. Create a topic branch named suitably for your work. #. Create a topic branch named suitably for your work.
Base all new work on the upstream ``master`` branch. Base all new work on the upstream ``master`` branch.
Base work on the upstream ``release`` branch only if it fixes a Base work on the upstream ``release`` branch only if it fixes a
@ -49,6 +50,7 @@ The merge request will enter the `CMake Review Process`_ for consideration.
.. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh .. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh
.. _`Building CMake`: README.rst#building-cmake .. _`Building CMake`: README.rst#building-cmake
.. _`CMake Source Code Guide`: Help/dev/source.rst .. _`CMake Source Code Guide`: Help/dev/source.rst
.. _`CMake Testing Guide`: Help/dev/testing.rst
.. _`commit messages`: Help/dev/review.rst#commit-messages .. _`commit messages`: Help/dev/review.rst#commit-messages
.. _`CMake Review Process`: Help/dev/review.rst .. _`CMake Review Process`: Help/dev/review.rst
@ -61,10 +63,10 @@ drive testing and submit results to the `CMake CDash Page`_. Anyone is
welcome to provide testing machines in order to help keep support for their welcome to provide testing machines in order to help keep support for their
platforms working. platforms working.
See documentation on `CMake Testing Process`_ for more information. See documentation on `CMake Integration Testing`_ for more information.
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake .. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
.. _`CMake Testing Process`: Help/dev/testing.rst .. _`CMake Integration Testing`: Help/dev/integration-testing.rst
License License
======= =======

@ -86,7 +86,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"[0-9]+ Warning\\(s\\) detected" # SunPro "[0-9]+ Warning\\(s\\) detected" # SunPro
# Ignore false positive on `cm::optional` usage from GCC # 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\\]" "cmFileCommand.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& tlsVerifyOpt \\+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]*: 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]*: 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\\]" "cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& modmap_fmt \\+4\\)' may be used uninitialized in this function \\[-Wmaybe-uninitialized\\]"
@ -101,6 +101,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"libuv/src/.*:[0-9]+:[0-9]+: warning: 1st function call argument is an uninitialized value" "libuv/src/.*:[0-9]+:[0-9]+: warning: 1st function call argument is an uninitialized value"
"libuv/src/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer" "libuv/src/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
"libuv/src/.*:[0-9]+:[0-9]+: warning: The left operand of '[^']+' is a garbage value" "libuv/src/.*:[0-9]+:[0-9]+: warning: The left operand of '[^']+' is a garbage value"
"libuv/src/.*:[0-9]+:[0-9]+: warning: Value of '[^']+' was not checked and may be overwritten by function '[^']+'"
"nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Access to field '[^']+' results in a dereference of a null pointer" "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Access to field '[^']+' results in a dereference of a null pointer"
"nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer" "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
"nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Value stored to '[^']+' is never read" "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Value stored to '[^']+' is never read"

@ -37,7 +37,13 @@ elseif(_CLANG_MSVC_WINDOWS AND "x${CMAKE_CXX_COMPILER_FRONTEND_VARIANT}" STREQUA
string(APPEND CMAKE_EXE_LINKER_FLAGS " -Xlinker -stack:20000000") string(APPEND CMAKE_EXE_LINKER_FLAGS " -Xlinker -stack:20000000")
endif() endif()
#silence duplicate symbol warnings on AIX # Silence "Additional optimization may be attained by recompiling and
# specifying MAXMEM option" warning on XLC (AIX)
if(CMAKE_CXX_COMPILER_ID MATCHES "^(XL|XLClang)$")
string(APPEND CMAKE_CXX_FLAGS " -qmaxmem=-1")
endif()
# Silence duplicate symbol warnings on AIX
if(CMAKE_SYSTEM_NAME MATCHES "AIX") if(CMAKE_SYSTEM_NAME MATCHES "AIX")
if(NOT CMAKE_COMPILER_IS_GNUCXX) if(NOT CMAKE_COMPILER_IS_GNUCXX)
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -bhalt:5 ") set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -bhalt:5 ")

@ -1,3 +1,11 @@
.. versionchanged:: 3.31
Compatibility with versions of CMake older than 3.10 is deprecated.
Calls to :command:`cmake_minimum_required(VERSION)` or
:command:`cmake_policy(VERSION)` that do not specify at least
3.10 as their policy version (optionally via ``...<max>``)
will produce a deprecation warning in CMake 3.31 and above.
.. versionchanged:: 3.27 .. versionchanged:: 3.27
Compatibility with versions of CMake older than 3.5 is deprecated. Compatibility with versions of CMake older than 3.5 is deprecated.

@ -5,6 +5,8 @@ Add a custom build rule to the generated build system.
There are two main signatures for ``add_custom_command``. There are two main signatures for ``add_custom_command``.
.. _`add_custom_command(OUTPUT)`:
Generating Files Generating Files
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
@ -26,6 +28,7 @@ The first signature is for adding a custom command to produce an output:
[JOB_POOL job_pool] [JOB_POOL job_pool]
[JOB_SERVER_AWARE <bool>] [JOB_SERVER_AWARE <bool>]
[VERBATIM] [APPEND] [USES_TERMINAL] [VERBATIM] [APPEND] [USES_TERMINAL]
[CODEGEN]
[COMMAND_EXPAND_LISTS] [COMMAND_EXPAND_LISTS]
[DEPENDS_EXPLICIT_ONLY]) [DEPENDS_EXPLICIT_ONLY])
@ -53,7 +56,7 @@ The options are:
the appended commands and dependencies apply to all configurations. the appended commands and dependencies apply to all configurations.
The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY`` The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY``
options are currently ignored when APPEND is given, but may be options are currently ignored when ``APPEND`` is given, but may be
used in the future. used in the future.
``BYPRODUCTS`` ``BYPRODUCTS``
@ -81,6 +84,10 @@ The options are:
The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
:prop_sf:`GENERATED` files during ``make clean``. :prop_sf:`GENERATED` files during ``make clean``.
This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
All byproducts must be set in the first call to
``add_custom_command(OUTPUT...)`` for the output files.
.. versionadded:: 3.20 .. versionadded:: 3.20
Arguments to ``BYPRODUCTS`` may use a restricted set of Arguments to ``BYPRODUCTS`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`. :manual:`generator expressions <cmake-generator-expressions(7)>`.
@ -94,11 +101,15 @@ The options are:
``COMMAND`` ``COMMAND``
Specify the command-line(s) to execute at build time. Specify the command-line(s) to execute at build time.
If more than one ``COMMAND`` is specified they will be executed in order, At least one ``COMMAND`` would normally be given, but certain patterns
may omit it, such as adding commands in separate calls using `APPEND`.
If more than one ``COMMAND`` is specified, they will be executed in order,
but *not* necessarily composed into a stateful shell or batch script. but *not* necessarily composed into a stateful shell or batch script.
(To run a full script, use the :command:`configure_file` command or the To run a full script, use the :command:`configure_file` command or the
:command:`file(GENERATE)` command to create it, and then specify :command:`file(GENERATE)` command to create it, and then specify
a ``COMMAND`` to launch it.) a ``COMMAND`` to launch it.
The optional ``ARGS`` argument is for backward compatibility and The optional ``ARGS`` argument is for backward compatibility and
will be ignored. will be ignored.
@ -143,7 +154,8 @@ The options are:
``COMMENT`` ``COMMENT``
Display the given message before the commands are executed at Display the given message before the commands are executed at
build time. build time. This will be ignored if ``APPEND`` is given, although a future
version may use it.
.. versionadded:: 3.26 .. versionadded:: 3.26
Arguments to ``COMMENT`` may use Arguments to ``COMMENT`` may use
@ -203,6 +215,26 @@ The options are:
``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc`` ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
to be properly expanded. to be properly expanded.
This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
If the appended commands need this option to be set, it must be set on the
first call to ``add_custom_command(OUTPUT...)`` for the output files.
``CODEGEN``
.. versionadded:: 3.31
Adds the custom command to a global ``codegen`` target that can be
used to execute the custom command while avoiding the majority of the
build graph.
This option is supported only by :ref:`Ninja Generators` and
:ref:`Makefile Generators`, and is ignored by other generators.
Furthermore, this option is allowed only if policy :policy:`CMP0171`
is set to ``NEW``.
This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
It can only be set on the first call to ``add_custom_command(OUTPUT...)``
for the output files.
``IMPLICIT_DEPENDS`` ``IMPLICIT_DEPENDS``
Request scanning of implicit dependencies of an input file. Request scanning of implicit dependencies of an input file.
The language given specifies the programming language whose The language given specifies the programming language whose
@ -227,6 +259,10 @@ The options are:
Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
an error by ninja at build time. an error by ninja at build time.
This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
Job pools can only be specified in the first call to
``add_custom_command(OUTPUT...)`` for the output files.
``JOB_SERVER_AWARE`` ``JOB_SERVER_AWARE``
.. versionadded:: 3.28 .. versionadded:: 3.28
@ -238,6 +274,10 @@ The options are:
This option is silently ignored by other generators. This option is silently ignored by other generators.
This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
Job server awareness can only be specified in the first call to
``add_custom_command(OUTPUT...)`` for the output files.
.. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html .. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html
``MAIN_DEPENDENCY`` ``MAIN_DEPENDENCY``
@ -249,6 +289,9 @@ The options are:
library or an executable) counts as an implicit main dependency which library or an executable) counts as an implicit main dependency which
gets silently overwritten by a custom command specification. gets silently overwritten by a custom command specification.
This option is currently ignored if ``APPEND`` is given, but a future
version may use it.
``OUTPUT`` ``OUTPUT``
Specify the output files the command is expected to produce. Specify the output files the command is expected to produce.
Each output file will be marked with the :prop_sf:`GENERATED` Each output file will be marked with the :prop_sf:`GENERATED`
@ -293,6 +336,10 @@ The options are:
With the :generator:`Ninja` generator, this places the command in With the :generator:`Ninja` generator, this places the command in
the ``console`` :prop_gbl:`pool <JOB_POOLS>`. the ``console`` :prop_gbl:`pool <JOB_POOLS>`.
This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
If the appended commands need access to the terminal, it must be set on
the first call to ``add_custom_command(OUTPUT...)`` for the output files.
``VERBATIM`` ``VERBATIM``
All arguments to the commands will be escaped properly for the All arguments to the commands will be escaped properly for the
build tool so that the invoked command receives each argument build tool so that the invoked command receives each argument
@ -303,11 +350,18 @@ The options are:
is platform specific because there is no protection of is platform specific because there is no protection of
tool-specific special characters. tool-specific special characters.
This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
If the appended commands need to be treated as ``VERBATIM``, it must be set
on the first call to ``add_custom_command(OUTPUT...)`` for the output files.
``WORKING_DIRECTORY`` ``WORKING_DIRECTORY``
Execute the command with the given current working directory. Execute the command with the given current working directory.
If it is a relative path it will be interpreted relative to the If it is a relative path, it will be interpreted relative to the
build tree directory corresponding to the current source directory. build tree directory corresponding to the current source directory.
This option is currently ignored if ``APPEND`` is given, but a future
version may use it.
.. versionadded:: 3.13 .. versionadded:: 3.13
Arguments to ``WORKING_DIRECTORY`` may use Arguments to ``WORKING_DIRECTORY`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`. :manual:`generator expressions <cmake-generator-expressions(7)>`.
@ -393,6 +447,10 @@ The options are:
:ref:`Makefile Generators`, :ref:`Visual Studio Generators`, :ref:`Makefile Generators`, :ref:`Visual Studio Generators`,
and the :generator:`Xcode` generator. and the :generator:`Xcode` generator.
This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
Depfiles can only be set on the first call to
``add_custom_command(OUTPUT...)`` for the output files.
``DEPENDS_EXPLICIT_ONLY`` ``DEPENDS_EXPLICIT_ONLY``
.. versionadded:: 3.27 .. versionadded:: 3.27
@ -408,6 +466,10 @@ The options are:
This option can be enabled on all custom commands by setting This option can be enabled on all custom commands by setting
:variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to ``ON``. :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to ``ON``.
This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
It can only be set on the first call to ``add_custom_command(OUTPUT...)``
for the output files.
Only the :ref:`Ninja Generators` actually use this information to remove Only the :ref:`Ninja Generators` actually use this information to remove
unnecessary implicit dependencies. unnecessary implicit dependencies.
@ -454,6 +516,25 @@ will re-run whenever ``in.txt`` changes.
where ``<config>`` is the build configuration, and then compile the generated where ``<config>`` is the build configuration, and then compile the generated
source as part of a library. source as part of a library.
.. versionadded:: 3.31
Use the ``CODEGEN`` option to add a custom command's outputs to the builtin
``codegen`` target. This is useful to make generated code available for
static analysis without building the entire project. For example:
.. code-block:: cmake
add_executable(someTool someTool.c)
add_custom_command(
OUTPUT out.c
COMMAND someTool -o out.c
CODEGEN)
add_library(myLib out.c)
A user may build the ``codegen`` target to generate ``out.c``.
``someTool`` is built as dependency, but ``myLib`` is not built at all.
Example: Generating Files for Multiple Targets Example: Generating Files for Multiple Targets
"""""""""""""""""""""""""""""""""""""""""""""" """"""""""""""""""""""""""""""""""""""""""""""
@ -543,15 +624,17 @@ of the following is specified:
Run after all other rules within the target have been executed. Run after all other rules within the target have been executed.
Projects should always specify one of the above three keywords when using Projects should always specify one of the above three keywords when using
the ``TARGET`` form. For backward compatibility reasons, ``POST_BUILD`` is the ``TARGET`` form. See policy :policy:`CMP0175`.
assumed if no such keyword is given, but projects should explicitly provide
one of the keywords to make clear the behavior they expect. All other keywords shown in the signature above have the same meaning as they
do for the :command:`add_custom_command(OUTPUT)` form of the command.
At least one ``COMMAND`` must be given, see policy :policy:`CMP0175`.
.. note:: .. note::
Because generator expressions can be used in custom commands, Because generator expressions can be used in custom commands,
it is possible to define ``COMMAND`` lines or whole custom commands it is possible to define ``COMMAND`` lines or whole custom commands
which evaluate to empty strings for certain configurations. which evaluate to empty strings for certain configurations.
For **Visual Studio 12 2013 (and newer)** generators these command For :ref:`Visual Studio Generators` these command
lines or custom commands will be omitted for the specific lines or custom commands will be omitted for the specific
configuration and no "empty-string-command" will be added. configuration and no "empty-string-command" will be added.

@ -20,48 +20,49 @@ It processes the arguments given to that macro or function,
and defines a set of variables which hold the values of the and defines a set of variables which hold the values of the
respective options. respective options.
The first signature reads processes arguments passed in the ``<args>...``. The first signature reads arguments passed in the ``<args>...``.
This may be used in either a :command:`macro` or a :command:`function`. This may be used in either a :command:`macro` or a :command:`function`.
.. versionadded:: 3.7 .. versionadded:: 3.7
The ``PARSE_ARGV`` signature is only for use in a :command:`function` The ``PARSE_ARGV`` signature is only for use in a :command:`function`
body. In this case the arguments that are parsed come from the body. In this case, the arguments that are parsed come from the
``ARGV#`` variables of the calling function. The parsing starts with ``ARGV#`` variables of the calling function. The parsing starts with
the ``<N>``-th argument, where ``<N>`` is an unsigned integer. the ``<N>``-th argument, where ``<N>`` is an unsigned integer.
This allows for the values to have special characters like ``;`` in them. This allows for the values to have special characters like ``;`` in them.
The ``<options>`` argument contains all options for the respective macro, The ``<options>`` argument contains all options for the respective function
i.e. keywords which can be used when calling the macro without any value or macro. These are keywords that have no value following them, like the
following, like e.g. the ``OPTIONAL`` keyword of the :command:`install` ``OPTIONAL`` keyword of the :command:`install` command.
command.
The ``<one_value_keywords>`` argument contains all keywords for this macro The ``<one_value_keywords>`` argument contains all keywords for this function
which are followed by one value, like e.g. ``DESTINATION`` keyword of the or macro which are followed by one value, like the ``DESTINATION`` keyword of
:command:`install` command. the :command:`install` command.
The ``<multi_value_keywords>`` argument contains all keywords for this The ``<multi_value_keywords>`` argument contains all keywords for this
macro which can be followed by more than one value, like e.g. the function or macro which can be followed by more than one value, like the
``TARGETS`` or ``FILES`` keywords of the :command:`install` command. ``TARGETS`` or ``FILES`` keywords of the :command:`install` command.
.. versionchanged:: 3.5 .. versionchanged:: 3.5
All keywords shall be unique. I.e. every keyword shall only be specified All keywords must be unique. Each keyword can only be specified
once in either ``<options>``, ``<one_value_keywords>`` or once in any of the ``<options>``, ``<one_value_keywords>``, or
``<multi_value_keywords>``. A warning will be emitted if uniqueness is ``<multi_value_keywords>``. A warning will be emitted if uniqueness is
violated. violated.
When done, ``cmake_parse_arguments`` will consider for each of the When done, ``cmake_parse_arguments`` will consider for each of the
keywords listed in ``<options>``, ``<one_value_keywords>`` and keywords listed in ``<options>``, ``<one_value_keywords>``, and
``<multi_value_keywords>`` a variable composed of the given ``<prefix>`` ``<multi_value_keywords>``, a variable composed of the given ``<prefix>``
followed by ``"_"`` and the name of the respective keyword. These followed by ``"_"`` and the name of the respective keyword. For
variables will then hold the respective value from the argument list ``<one_value_keywords>`` and ``<multi_value_keywords>``, these variables
or be undefined if the associated option could not be found. will then hold the respective value(s) from the argument list, or be undefined
For the ``<options>`` keywords, these will always be defined, if the associated keyword was not given (policy :policy:`CMP0174` can also
to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not. affect the behavior for ``<one_value_keywords>``). For the ``<options>``
keywords, these variables will always be defined, and they will be set to
``TRUE`` if the keyword is present, or ``FALSE`` if it is not.
All remaining arguments are collected in a variable All remaining arguments are collected in a variable
``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments ``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments
were recognized. This can be checked afterwards to see were recognized. This can be checked afterwards to see
whether your macro was called with unrecognized parameters. whether your macro or function was called with unrecognized parameters.
.. versionadded:: 3.15 .. versionadded:: 3.15
``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no ``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no
@ -70,8 +71,47 @@ whether your macro was called with unrecognized parameters.
received values. This can be checked to see if there were keywords without received values. This can be checked to see if there were keywords without
any values given. any values given.
Consider the following example macro, ``my_install()``, which takes similar .. versionchanged:: 3.31
arguments to the real :command:`install` command: If a ``<one_value_keyword>`` is followed by an empty string as its value,
policy :policy:`CMP0174` controls whether a corresponding
``<prefix>_<keyword>`` variable is defined or not.
Choose a ``<prefix>`` carefully to avoid clashing with existing variable names.
When used inside a function, it is usually suitable to use the prefix ``arg``.
There is a very strong convention that all keywords are fully uppercase, so
this prefix results in variables of the form ``arg_SOME_KEYWORD``. This makes
the code more readable, and it minimizes the chance of clashing with cache
variables, which also have a strong convention of being all uppercase.
.. code-block:: cmake
function(my_install)
set(options OPTIONAL FAST)
set(oneValueArgs DESTINATION RENAME)
set(multiValueArgs TARGETS CONFIGURATIONS)
cmake_parse_arguments(PARSE_ARGV 0 arg
"${options}" "${oneValueArgs}" "${multiValueArgs}"
)
# The above will set or unset variables with the following names:
# arg_OPTIONAL
# arg_FAST
# arg_DESTINATION
# arg_RENAME
# arg_TARGETS
# arg_CONFIGURATIONS
#
# The following will also be set or unset:
# arg_UNPARSED_ARGUMENTS
# arg_KEYWORDS_MISSING_VALUES
When used inside a macro, ``arg`` might not be a suitable prefix because the
code will affect the calling scope. If another macro also called in the same
scope were to use ``arg`` in its own call to ``cmake_parse_arguments()``,
and if there are any common keywords between the two macros, the later call's
variables can overwrite or remove those of the earlier macro's call.
Therefore, it is advisable to incorporate something unique from the macro name
in the ``<prefix>``, such as ``arg_lowercase_macro_name``.
.. code-block:: cmake .. code-block:: cmake
@ -79,40 +119,63 @@ arguments to the real :command:`install` command:
set(options OPTIONAL FAST) set(options OPTIONAL FAST)
set(oneValueArgs DESTINATION RENAME) set(oneValueArgs DESTINATION RENAME)
set(multiValueArgs TARGETS CONFIGURATIONS) set(multiValueArgs TARGETS CONFIGURATIONS)
cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" cmake_parse_arguments(arg_my_install
"${multiValueArgs}" ${ARGN} ) "${options}" "${oneValueArgs}" "${multiValueArgs}"
${ARGN}
)
# ...
endmacro()
macro(my_special_install)
# NOTE: Has the same keywords as my_install()
set(options OPTIONAL FAST)
set(oneValueArgs DESTINATION RENAME)
set(multiValueArgs TARGETS CONFIGURATIONS)
cmake_parse_arguments(arg_my_special_install
"${options}" "${oneValueArgs}" "${multiValueArgs}"
${ARGN}
)
# ... # ...
endmacro()
Assume ``my_install()`` has been called like this: Suppose the above macros are called one after the other, like so:
.. code-block:: cmake .. code-block:: cmake
my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
my_special_install(TARGETS barry DESTINATION sbin RENAME FAST)
After the ``cmake_parse_arguments`` call the macro will have set or undefined
the following variables:: After these two calls, the following describes the variables that will be
set or unset::
MY_INSTALL_OPTIONAL = TRUE
MY_INSTALL_FAST = FALSE # was not used in call to my_install arg_my_install_OPTIONAL = TRUE
MY_INSTALL_DESTINATION = "bin" arg_my_install_FAST = FALSE # was not present in call to my_install
MY_INSTALL_RENAME <UNDEFINED> # was not used arg_my_install_DESTINATION = "bin"
MY_INSTALL_TARGETS = "foo;bar" arg_my_install_RENAME <UNSET> # was not present
MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used arg_my_install_TARGETS = "foo;bar"
MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL" arg_my_install_CONFIGURATIONS <UNSET> # was not present
MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS" arg_my_install_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
# No value for "CONFIGURATIONS" given arg_my_install_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS" # value was missing
You can then continue and process these variables. arg_my_special_install_OPTIONAL = FALSE # was not present
arg_my_special_install_FAST = TRUE
Keywords terminate lists of values, e.g. if directly after a arg_my_special_install_DESTINATION = "sbin"
``one_value_keyword`` another recognized keyword follows, this is arg_my_special_install_RENAME <UNSET> # value was missing
interpreted as the beginning of the new option. E.g. arg_my_special_install_TARGETS = "barry"
``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in arg_my_special_install_CONFIGURATIONS <UNSET> # was not present
``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL`` arg_my_special_install_UNPARSED_ARGUMENTS <UNSET>
is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added arg_my_special_install_KEYWORDS_MISSING_VALUES = "RENAME"
to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will
therefore be set to ``TRUE``. Keywords terminate lists of values. If a keyword is given directly after a
``<one_value_keyword>``, that preceding ``<one_value_keyword>`` receives no
value and the keyword is added to the ``<prefix>_KEYWORDS_MISSING_VALUES``
variable. In the above example, the call to ``my_special_install()`` contains
the ``RENAME`` keyword immediately followed by the ``FAST`` keyword.
In this case, ``FAST`` terminates processing of the ``RENAME`` keyword.
``arg_my_special_install_FAST`` is set to ``TRUE``,
``arg_my_special_install_RENAME`` is unset, and
``arg_my_special_install_KEYWORDS_MISSING_VALUES`` contains the value
``RENAME``.
See Also See Also
^^^^^^^^ ^^^^^^^^

@ -0,0 +1,263 @@
cmake_pkg_config
----------------
.. versionadded:: 3.31
.. only:: html
.. contents::
Process pkg-config format package files.
Synopsis
^^^^^^^^
.. parsed-literal::
cmake_pkg_config(EXTRACT <package> [<version>] [...])
Introduction
^^^^^^^^^^^^
This command generates CMake variables and targets from pkg-config format
package files natively, without needing to invoke or even require the presence
of a pkg-config implementation. A ``<package>`` is either an absolute path to a
package file, or a package name to be searched for using the typical pkg-config
search patterns. The optional ``<version>`` string has the same format and
semantics as a pkg-config style version specifier, with the exception that if
no comparison operator is specified ``=`` is assumed.
.. _`common options`:
There are multiple signatures for this command, and some of the options are
common between them. They are:
``EXACT`` / ``QUIET`` / ``REQUIRED``
The ``EXACT`` option requests that the version string be matched exactly
(including empty string, if no version is provided), overriding the typical
pkg-config version comparison algorithm. This will ignore any comparison
operator attached to the version string.
The ``QUIET`` option disables informational messages, including those
indicating that the package cannot be found if it is not ``REQUIRED``. The
``REQUIRED`` option stops processing with an error message if the package
cannot be found.
``STRICTNESS <mode>``
Specify how strictly the contents of the package files will be verified during
parsing and resolution. An invalid file, under the provided strictness mode,
will cause the command to fail. Possible modes are:
* ``STRICT``: Closely mirrors the behavior of the original FDO pkg-config.
Variables and keywords must be unique. Variables must be defined before
they are used. The Name, Description, and Version keywords must be present.
The overall structure of the file must be valid and parsable.
* ``PERMISSIVE``: Closely mirrors the behavior of the pkgconf implementation.
Duplicate variables are overridden. Duplicate keywords are appended.
Undefined variables resolve to empty strings. The Name, Description, and
Version keywords must be present. The overall structure of the file must be
valid and parsable.
* ``BEST_EFFORT``: Same behavior as ``PERMISSIVE`` with regards to duplicate
or uninitialized variables and keywords, but will not fail under any
conditions. Package files which require BEST_EFFORT will fail validation
under all other major implementations and should be fixed.
The default strictness is ``PERMISSIVE``.
``ENV_MODE``
Specifies which environment variables will be queried when running a given
command. Possible modes are:
* ``FDO``: Queries only the original set of ``PKG_CONFIG_*`` environment
variables used by the freedesktop.org ``pkg-config`` implementation.
* ``PKGCONF``: Queries the more extensive set of environment variables used
by the ``pkgconf`` implementation.
* ``IGNORE``: Ignores the presence, absence, and value of environment
variables entirely. In all cases an environment variable would be queried
its treated as defined, but with a value of empty string for the purpose
of the operation. This does not modify the current environment. For boolean
environment variables, such as ``PKG_CONFIG_ALLOW_*``, this means they are
evaluated as truthy.
``PKG_CONFIG_SYSROOT_PATH`` is a minor exception. When ``ENV_MODE IGNORE``
is used, no root path prepending will occur by default and ``pc_sysrootdir``
remains defaulted to ``/``.
Target-generating subcommands always ignore flag-filtering environment
variables. The default environment mode is ``PKGCONF``.
``PC_LIBDIR <path>...``
Overrides the default search location for package files; also used to derive
the ``pc_path`` package variable.
When this option is not provided, the default library directory is the first
available of the following values:
#. ``CMAKE_PKG_CONFIG_PC_LIB_DIRS``
#. The ``PKG_CONFIG_LIBDIR`` environment variable
#. The output of ``pkg-config --variable pc_path pkg-config``
#. A platform-dependent default value
``PC_PATH <path>...``
Overrides the supplemental package file directories which will be prepended
to the search path; also used to derive the ``pc_path`` package variable.
When this option is not provided, the default paths are the first available of
the following values:
#. ``CMAKE_PKG_CONFIG_PC_PATH``
#. The ``PKG_CONFIG_PATH`` environment variable
#. Empty list
``DISABLE_UNINSTALLED <bool>``
Overrides the search behavior for "uninstalled" package files. These are
package files with an "-uninstalled" suffix which describe packages integrated
directly from a build tree.
Normally such package files have higher priority than "installed" packages.
When ``DISABLE_UNINSTALLED`` is true, searching for "uninstalled" packages
is disabled.
When this option is not provided, the default search behavior is determined
by the first available of the following values:
#. ``CMAKE_PKG_CONFIG_DISABLE_UNINSTALLED``
#. If the ``PKG_CONFIG_DISABLE_UNINSTALLED`` environment variable is defined
the search is disabled, otherwise it is enabled.
``PC_SYSROOT_DIR <path>``
Overrides the root path which will be prepended to paths specified by ``-I``
compile flags and ``-L`` library search locations; also used to derive the
``pc_sysrootdir`` package variable.
When this option is not provided, the default root path is provided by the
first available of the following values:
#. ``CMAKE_PKG_CONFIG_SYSROOT_DIR``
#. The ``PKG_CONFIG_SYSROOT_DIR`` environment variable
#. If no root path is available, nothing will be prepended to include or
library directory paths and ``pc_sysrootdir`` will be set to ``/``
``TOP_BUILD_DIR <path>``
Overrides the top build directory path used to derived the ``pc_top_builddir``
package variable.
When this option is not provided, the default top build directory path is
the first available of the following values:
#. ``CMAKE_PKG_CONFIG_TOP_BUILD_DIR``
#. The ``PKG_CONFIG_TOP_BUILD_DIR`` environment variable
#. If no top build directory path is available, the ``pc_top_builddir``
package variable is not set
Signatures
^^^^^^^^^^
.. signature::
cmake_pkg_config(EXTRACT <package> [<version>] [...])
Extract the contents of the package into variables.
.. code-block:: cmake
cmake_pkg_config(EXTRACT <package> [<version>]
[REQUIRED] [EXACT] [QUIET]
[STRICTNESS <mode>]
[ENV_MODE <mode>]
[PC_LIBDIR <path>...]
[PC_PATH <path>...]
[DISABLE_UNINSTALLED <bool>]
[PC_SYSROOT_DIR <path>]
[TOP_BUILD_DIR <path>]
[SYSTEM_INCLUDE_DIRS <path>...]
[SYSTEM_LIBRARY_DIRS <path>...]
[ALLOW_SYSTEM_INCLUDES <bool>]
[ALLOW_SYSTEM_LIBS <bool>])
The following variables will be populated from the contents of package file:
==================================== ====== ========================================================================================
Variable Type Definition
==================================== ====== ========================================================================================
``CMAKE_PKG_CONFIG_NAME`` String Value of the ``Name`` keyword
``CMAKE_PKG_CONFIG_DESCRIPTION`` String Value of the ``Description`` keyword
``CMAKE_PKG_CONFIG_VERSION`` String Value of the ``Version`` keyword
``CMAKE_PKG_CONFIG_PROVIDES`` List Value of the ``Provides`` keyword
``CMAKE_PKG_CONFIG_REQUIRES`` List Value of the ``Requires`` keyword
``CMAKE_PKG_CONFIG_CONFLICTS`` List Value of the ``Conflicts`` keyword
``CMAKE_PKG_CONFIG_CFLAGS`` String Value of the ``CFlags`` / ``Cflags`` keyword
``CMAKE_PKG_CONFIG_INCLUDES`` List All ``-I`` prefixed flags from ``CMAKE_PKG_CONFIG_CFLAGS``
``CMAKE_PKG_CONFIG_COMPILE_OPTIONS`` List All flags not prefixed with ``-I`` from ``CMAKE_PKG_CONFIG_CFLAGS``
``CMAKE_PKG_CONFIG_LIBS`` String Value of the ``Libs`` keyword
``CMAKE_PKG_CONFIG_LIBDIRS`` List All ``-L`` prefixed flags from ``CMAKE_PKG_CONFIG_LIBS``
``CMAKE_PKG_CONFIG_LIBNAMES`` List All ``-l`` prefixed flags from ``CMAKE_PKG_CONFIG_LIBS``
``CMAKE_PKG_CONFIG_LINK_OPTIONS`` List All flags not prefixed with ``-L`` or ``-l`` from ``CMAKE_PKG_CONFIG_LIBS``
``CMAKE_PKG_CONFIG_*_PRIVATE`` \* ``CFLAGS`` / ``LIBS`` / ``REQUIRES`` and derived, but in their ``.private`` suffix forms
==================================== ====== ========================================================================================
``SYSTEM_INCLUDE_DIRS``
Overrides the "system" directories for the purpose of flag mangling include
directories in ``CMAKE_PKG_CONFIG_CFLAGS`` and derived variables.
When this option is not provided, the default directories are provided by the
first available of the following values:
#. ``CMAKE_PKG_CONFIG_SYS_INCLUDE_DIRS``
#. The ``PKG_CONFIG_SYSTEM_INCLUDE_PATH`` environment variable
#. The output of ``pkgconf --variable pc_system_includedirs pkg-config``
#. A platform-dependent default value
Additionally, when the ``ENV_MODE`` is ``PKGCONF`` the
``CMAKE_PKG_CONFIG_PKGCONF_INCLUDES`` variable will be concatenated to the
list if available. If it is not available, the following environment variables
will be queried and concatenated:
* ``CPATH``
* ``C_INCLUDE_PATH``
* ``CPLUS_INCLUDE_PATH``
* ``OBJC_INCLUDE_PATH``
* ``INCLUDE`` (Windows Only)
``SYSTEM_LIBRARY_DIRS``
Overrides the "system" directories for the purpose of flag mangling library
directories in ``CMAKE_PKG_CONFIG_LIBS`` and derived variables.
When this option is not provided, the default directories are provided by the
first available of the following values:
#. ``CMAKE_PKG_CONFIG_SYS_LIB_DIRS``
#. The ``PKG_CONFIG_SYSTEM_LIBRARY_PATH`` environment variable
#. The output of ``pkgconf --variable pc_system_libdirs pkg-config``
#. A platform-dependent default value
Additionally, when the ``ENV_MODE`` is ``PKGCONF`` the
``CMAKE_PKG_CONFIG_PKGCONF_LIB_DIRS`` variable will be concatenated to the
list if available. If it is not available, the ``LIBRARY_PATH`` environment
variable will be queried and concatenated.
``ALLOW_SYSTEM_INCLUDES``
Preserves "system" directories during flag mangling of include directories
in ``CMAKE_PKG_CONFIG_CFLAGS`` and derived variables.
When this option is not provided, the default value is determined by the first
available of the following values:
#. ``CMAKE_PKG_CONFIG_ALLOW_SYS_INCLUDES``
#. If the ``PKG_CONFIG_ALLOW_SYSTEM_CFLAGS`` environment variable is defined
the flags are preserved, otherwise they are filtered during flag mangling.
``ALLOW_SYSTEM_LIBS``
Preserves "system" directories during flag mangling of library directories
in ``CMAKE_PKG_CONFIG_LIBS`` and derived variables.
When this option is not provided, the default value is determined by the first
available of the following values:
#. ``CMAKE_PKG_CONFIG_ALLOW_SYS_LIBS``
#. If the ``PKG_CONFIG_ALLOW_SYSTEM_LIBS`` environment variable is defined
the flags are preserved, otherwise they are filtered during flag mangling.

@ -140,20 +140,32 @@ Options:
``NONE`` ``NONE``
Perform no decoding. This assumes that the process output is encoded Perform no decoding. This assumes that the process output is encoded
in the same way as CMake's internal encoding (UTF-8). in the same way as CMake's internal encoding (UTF-8).
This is the default.
This was the default in CMake 3.14 and older.
``AUTO`` ``AUTO``
Use the current active console's codepage or if that isn't Use the current active console's codepage or if that isn't
available then use ANSI. available then use ANSI.
This was the default in CMake 3.15 through 3.30.
``ANSI`` ``ANSI``
Use the ANSI codepage. Use the ANSI codepage.
``OEM`` ``OEM``
Use the original equipment manufacturer (OEM) code page. Use the original equipment manufacturer (OEM) code page.
``UTF8`` or ``UTF-8``
Use the UTF-8 codepage.
``UTF-8``
.. versionadded:: 3.11 .. versionadded:: 3.11
Accept ``UTF-8`` spelling for consistency with the
`UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention. Use the UTF-8 codepage.
This is the default. See policy :policy:`CMP0176`.
``UTF8``
Use the UTF-8 codepage. Use of this name is discouraged in favor
of ``UTF-8`` to match the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_
naming convention.
``COMMAND_ERROR_IS_FATAL <ANY|LAST>`` ``COMMAND_ERROR_IS_FATAL <ANY|LAST>``
.. versionadded:: 3.19 .. versionadded:: 3.19

@ -400,10 +400,19 @@ Filesystem
============== ====================================================== ============== ======================================================
.. signature:: .. signature::
file(MAKE_DIRECTORY <directories>...) file(MAKE_DIRECTORY <directories>... [RESULT <result>])
Create the given directories and their parents as needed. Create the given directories and their parents as needed.
The options are:
``RESULT <result>``
.. versionadded:: 3.31
Set ``<result>`` variable to ``0`` on success or an error message
otherwise. If ``RESULT`` is not specified and the operation fails,
an error is emitted.
.. versionchanged:: 3.30 .. versionchanged:: 3.30
``<directories>`` can be an empty list. CMake 3.29 and earlier required ``<directories>`` can be an empty list. CMake 3.29 and earlier required
at least one directory to be given. at least one directory to be given.
@ -802,10 +811,21 @@ Transfer
environment variable will be used instead. environment variable will be used instead.
See :variable:`CMAKE_TLS_VERSION` for allowed values. See :variable:`CMAKE_TLS_VERSION` for allowed values.
.. versionchanged:: 3.31
The default is TLS 1.2.
Previously, no minimum version was enforced by default.
``TLS_VERIFY <ON|OFF>`` ``TLS_VERIFY <ON|OFF>``
Specify whether to verify the server certificate for ``https://`` URLs. Specify whether to verify the server certificate for ``https://`` URLs.
The default is to *not* verify. If this option is not specified, the If this option is not specified, the value of the
value of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead. :variable:`CMAKE_TLS_VERIFY` variable or :envvar:`CMAKE_TLS_VERIFY`
environment variable will be used instead.
If neither is set, the default is *on*.
.. versionchanged:: 3.31
The default is on. Previously, the default was off.
Users may set the :envvar:`CMAKE_TLS_VERIFY` environment
variable to ``0`` to restore the old default.
.. versionadded:: 3.18 .. versionadded:: 3.18
Added support to ``file(UPLOAD)``. Added support to ``file(UPLOAD)``.
@ -818,9 +838,7 @@ Transfer
.. versionadded:: 3.18 .. versionadded:: 3.18
Added support to ``file(UPLOAD)``. Added support to ``file(UPLOAD)``.
For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL`` For ``https://`` URLs CMake must be built with SSL/TLS support.
certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to
check certificates.
Additional options to ``DOWNLOAD`` are: Additional options to ``DOWNLOAD`` are:
@ -894,6 +912,7 @@ Archiving
[COMPRESSION <compression> [COMPRESSION <compression>
[COMPRESSION_LEVEL <compression-level>]] [COMPRESSION_LEVEL <compression-level>]]
[MTIME <mtime>] [MTIME <mtime>]
[WORKING_DIRECTORY <dir>]
[VERBOSE]) [VERBOSE])
:target: ARCHIVE_CREATE :target: ARCHIVE_CREATE
:break: verbatim :break: verbatim
@ -904,17 +923,27 @@ Archiving
listed in ``<paths>``. Note that ``<paths>`` must list actual files or listed in ``<paths>``. Note that ``<paths>`` must list actual files or
directories; wildcards are not supported. directories; wildcards are not supported.
Use the ``FORMAT`` option to specify the archive format. Supported values The options are:
for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and
``zip``. If ``FORMAT`` is not given, the default format is ``paxr``. ``FORMAT <format>``
Specify the archive format. Supported values for ``<format>`` are
``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and ``zip``.
If ``FORMAT`` is not given, the default format is ``paxr``.
``COMPRESSION <compression>``
Some archive formats allow the type of compression to be specified. Some archive formats allow the type of compression to be specified.
The ``7zip`` and ``zip`` archive formats already imply a specific type of The ``7zip`` and ``zip`` archive formats already imply a specific type of
compression. The other formats use no compression by default, but can be compression. The other formats use no compression by default, but can be
directed to do so with the ``COMPRESSION`` option. Valid values for directed to do so with the ``COMPRESSION`` option. Valid values for
``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``. ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
.. note::
With ``FORMAT`` set to ``raw``, only one file will be compressed
with the compression type specified by ``COMPRESSION``.
``COMPRESSION_LEVEL <compression-level>``
.. versionadded:: 3.19 .. versionadded:: 3.19
The compression level can be specified with the ``COMPRESSION_LEVEL`` The compression level can be specified with the ``COMPRESSION_LEVEL``
option. The ``<compression-level>`` should be between 0-9, with the option. The ``<compression-level>`` should be between 0-9, with the
default being 0. The ``COMPRESSION`` option must be present when default being 0. The ``COMPRESSION`` option must be present when
@ -924,20 +953,25 @@ Archiving
The ``<compression-level>`` of the ``Zstd`` algorithm can be set The ``<compression-level>`` of the ``Zstd`` algorithm can be set
between 0-19. between 0-19.
.. note:: ``MTIME <mtime>``
With ``FORMAT`` set to ``raw``, only one file will be compressed with the Specify the modification time recorded in tarball entries.
compression type specified by ``COMPRESSION``.
``WORKING_DIRECTORY <dir>``
.. versionadded:: 3.31
The ``VERBOSE`` option enables verbose output for the archive operation. Specify the directory in which the archive creation operation will
be executed. Paths in the ``<paths>`` argument can be relative to
this directory. If this option is not provided, the current working
directory will be used by default.
To specify the modification time recorded in tarball entries, use ``VERBOSE``
the ``MTIME`` option. Enable verbose output from the archive operation.
.. signature:: .. signature::
file(ARCHIVE_EXTRACT file(ARCHIVE_EXTRACT
INPUT <archive> INPUT <archive>
[DESTINATION <dir>] [DESTINATION <dir>]
[PATTERNS <patterns>...] [PATTERNS <pattern>...]
[LIST_ONLY] [LIST_ONLY]
[VERBOSE] [VERBOSE]
[TOUCH]) [TOUCH])
@ -947,17 +981,30 @@ Archiving
Extracts or lists the content of the specified ``<archive>``. Extracts or lists the content of the specified ``<archive>``.
The directory where the content of the archive will be extracted to can The options are:
be specified using the ``DESTINATION`` option. If the directory does not
exist, it will be created. If ``DESTINATION`` is not given, the current ``DESTINATION <dir>``
binary directory will be used. Specify the directory under which the content of the archive will be
extracted. If the directory does not exist, it will be created.
If ``DESTINATION`` is not given, the current binary directory will
be used.
If required, you may select which files and directories to list or extract ``PATTERNS <pattern>...``
from the archive using the specified ``<patterns>``. Wildcards are Extract/list only files and directories that match one of the given
supported. If the ``PATTERNS`` option is not given, the entire archive will patterns. Wildcards are supported. If the ``PATTERNS`` option is
be listed or extracted. not given, the entire archive will be listed or extracted.
``LIST_ONLY`` will list the files in the archive rather than extract them. ``LIST_ONLY``
List the files in the archive rather than extract them.
``TOUCH``
.. versionadded:: 3.24
Give extracted files a current local timestamp instead of extracting
file timestamps from the archive.
``VERBOSE``
Enable verbose output from the extraction operation.
.. note:: .. note::
The working directory for this subcommand is the ``DESTINATION`` directory The working directory for this subcommand is the ``DESTINATION`` directory
@ -966,12 +1013,6 @@ Archiving
``INPUT`` archives as they are unlikely to be extracted where a relative ``INPUT`` archives as they are unlikely to be extracted where a relative
path works. path works.
.. versionadded:: 3.24
The ``TOUCH`` option gives extracted files a current local
timestamp instead of extracting file timestamps from the archive.
With ``VERBOSE``, the command will produce verbose output.
Handling Runtime Binaries Handling Runtime Binaries
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
@ -1162,6 +1203,14 @@ Handling Runtime Binaries
5. Otherwise, the dependency is unresolved. 5. Otherwise, the dependency is unresolved.
.. versionchanged:: 3.31
Resolution of each encountered library file name occurs at most once
while processing a given root ELF file (executable or shared object).
If a library file name is encountered again in the dependency tree,
the original resolution is assumed. This behavior more closely matches
the dynamic loader's behavior on Linux.
On Windows platforms, library resolution works as follows: On Windows platforms, library resolution works as follows:
1. DLL dependency names are converted to lowercase for matching filters. 1. DLL dependency names are converted to lowercase for matching filters.

@ -503,6 +503,42 @@ The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
of the above locations to be ignored. of the above locations to be ignored.
Paths are searched in the order described above. The first viable package
configuration file found is used, even if a newer version of the package
resides later in the list of search paths.
For search paths which contain ``<name>*``, the order among matching paths
is unspecified unless the :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` variable
is set. This variable, along with the
:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable, determines the order
in which CMake considers paths that match a single search path containing
``<name>*``. For example, if the file system contains the package
configuration files
::
<prefix>/example-1.2/example-config.cmake
<prefix>/example-1.10/example-config.cmake
<prefix>/share/example-2.0/example-config.cmake
it is unspecified (when the aforementioned variables are unset) whether
``find_package(example)`` will find ``example-1.2`` or ``example-1.10``
(assuming that both are viable), but ``find_package`` will *not* find
``example-2.0``, because one of the other two will be found first.
To control the order in which ``find_package`` searches directories that match
a glob expression, use :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
For instance, to cause the above example to select ``example-1.10``,
one can set
.. code-block:: cmake
SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
before calling ``find_package``.
.. versionadded:: 3.16 .. versionadded:: 3.16
Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable
various search locations. various search locations.
@ -648,22 +684,6 @@ is acceptable the following variables are set:
Number of version components, 0 to 4 Number of version components, 0 to 4
and the corresponding package configuration file is loaded. and the corresponding package configuration file is loaded.
When multiple package configuration files are available whose version files
claim compatibility with the version requested it is unspecified which
one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
is set no attempt is made to choose a highest or closest version number.
To control the order in which ``find_package`` checks for compatibility use
the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
For instance in order to select the highest version one can set
.. code-block:: cmake
SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
before calling ``find_package``.
Package File Interface Variables Package File Interface Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

@ -41,3 +41,23 @@ When more than one value is given to the ``NAMES`` option this command by
default will consider one name at a time and search every directory default will consider one name at a time and search every directory
for it. The ``NAMES_PER_DIR`` option tells this command to consider one for it. The ``NAMES_PER_DIR`` option tells this command to consider one
directory at a time and search for all names in it. directory at a time and search for all names in it.
The set of files considered to be programs is platform-specific:
* On Windows, filename suffixes are considered in order ``.com``, ``.exe``,
and no suffix.
* On non-Windows systems, no filename suffix is considered, but files
must have execute permission (see policy :policy:`CMP0109`).
To search for scripts, specify an extension explicitly:
.. code-block:: cmake
if(WIN32)
set(_script_suffix .bat)
else()
set(_script_suffix .sh)
endif()
find_program(MY_SCRIPT NAMES my_script${_script_suffix})

@ -29,7 +29,7 @@ It must be one of the following:
Scope is unique and does not accept a name. Scope is unique and does not accept a name.
``DIRECTORY`` ``DIRECTORY``
Scope defaults to the current directory but another Scope defaults to the current directory, but another
directory (already processed by CMake) may be named by the directory (already processed by CMake) may be named by the
full or relative path ``<dir>``. full or relative path ``<dir>``.
Relative paths are treated as relative to the current source directory. Relative paths are treated as relative to the current source directory.
@ -79,10 +79,10 @@ It must be one of the following:
``DIRECTORY <dir>`` ``DIRECTORY <dir>``
The test property will be read from the ``<dir>`` directory's The test property will be read from the ``<dir>`` directory's
scope. CMake must already know about the directory, either by having added scope. CMake must already know about the directory, either by having
it through a call to :command:`add_subdirectory` or ``<dir>`` being the top added it through a call to :command:`add_subdirectory` or ``<dir>`` being
level directory. Relative paths are treated as relative to the current the top level directory. Relative paths are treated as relative to the
source directory. ``<dir>`` may reference a binary directory. current source directory. ``<dir>`` may reference a binary directory.
``CACHE`` ``CACHE``
Scope must name one cache entry. Scope must name one cache entry.
@ -91,19 +91,20 @@ It must be one of the following:
Scope is unique and does not accept a name. Scope is unique and does not accept a name.
The required ``PROPERTY`` option is immediately followed by the name of The required ``PROPERTY`` option is immediately followed by the name of
the property to get. If the property is not set an empty value is the property to get. If the property is not set, the named ``<variable>``
returned, although some properties support inheriting from a parent scope will be unset in the calling scope upon return, although some properties
if defined to behave that way (see :command:`define_property`). support inheriting from a parent scope if defined to behave that way
(see :command:`define_property`).
If the ``SET`` option is given the variable is set to a boolean If the ``SET`` option is given, the variable is set to a boolean
value indicating whether the property has been set. If the ``DEFINED`` value indicating whether the property has been set. If the ``DEFINED``
option is given the variable is set to a boolean value indicating option is given, the variable is set to a boolean value indicating
whether the property has been defined such as with the whether the property has been defined, such as with the
:command:`define_property` command. :command:`define_property` command.
If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given, then the variable is set to a
string containing documentation for the requested property. If string containing documentation for the requested property. If
documentation is requested for a property that has not been defined documentation is requested for a property that has not been defined,
``NOTFOUND`` is returned. ``NOTFOUND`` is returned.
.. note:: .. note::

@ -41,13 +41,15 @@ Compound conditions are evaluated in the following order of precedence:
1. `Parentheses`_. 1. `Parentheses`_.
2. Unary tests such as `EXISTS`_, `COMMAND`_, and `DEFINED`_. 2. Unary tests such as `COMMAND`_, `POLICY`_, `TARGET`_, `TEST`_,
`EXISTS`_, `IS_READABLE`_, `IS_WRITABLE`_, `IS_EXECUTABLE`_,
`IS_DIRECTORY`_, `IS_SYMLINK`_, `IS_ABSOLUTE`_, and `DEFINED`_.
3. Binary tests such as `EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_, 3. Binary tests such as `EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_,
`GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_, `GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_,
`STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_, `STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_,
`VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_, `VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_,
`PATH_EQUAL`_, and `MATCHES`_. `PATH_EQUAL`_, `IN_LIST`_, `IS_NEWER_THAN`_, and `MATCHES`_.
4. Unary logical operator `NOT`_. 4. Unary logical operator `NOT`_.
@ -471,6 +473,10 @@ above-documented condition syntax accepts ``<variable|string>``:
variables. If so, their defined values are used otherwise the original value variables. If so, their defined values are used otherwise the original value
is used. is used.
* The left hand argument to `IN_LIST`_ is tested to see if it is a defined
variable. If so, the variable's value is used, otherwise the original
value is used.
* The right hand argument to `NOT`_ is tested to see if it is a boolean * The right hand argument to `NOT`_ is tested to see if it is a boolean
constant. If so, the value is used, otherwise it is assumed to be a constant. If so, the value is used, otherwise it is assumed to be a
variable and it is dereferenced. variable and it is dereferenced.

@ -1,7 +1,8 @@
include_external_msproject include_external_msproject
-------------------------- --------------------------
Include an external Microsoft project file in a workspace. Include an external Microsoft project file in the solution file produced
by :ref:`Visual Studio Generators`. Ignored on other generators.
.. code-block:: cmake .. code-block:: cmake
@ -11,9 +12,9 @@ Include an external Microsoft project file in a workspace.
[PLATFORM platformName] [PLATFORM platformName]
dep1 dep2 ...) dep1 dep2 ...)
Includes an external Microsoft project in the generated workspace Includes an external Microsoft project in the generated solution file.
file. Currently does nothing on UNIX. This will create a target This will create a target named ``[projectname]``.
named ``[projectname]``. This can be used in the :command:`add_dependencies` This can be used in the :command:`add_dependencies`
command to make things depend on the external project. command to make things depend on the external project.
``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to ``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to

@ -19,6 +19,7 @@ Synopsis
install(`SCRIPT`_ <file> [...]) install(`SCRIPT`_ <file> [...])
install(`CODE`_ <code> [...]) install(`CODE`_ <code> [...])
install(`EXPORT`_ <export-name> [...]) install(`EXPORT`_ <export-name> [...])
install(`PACKAGE_INFO`_ <package-name> [...])
install(`RUNTIME_DEPENDENCY_SET`_ <set-name> [...]) install(`RUNTIME_DEPENDENCY_SET`_ <set-name> [...])
Introduction Introduction
@ -38,6 +39,13 @@ are executed in order during installation.
The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
default copying behavior of ``install()``. default copying behavior of ``install()``.
.. versionchanged:: 3.31
Projects can enable :prop_gbl:`INSTALL_PARALLEL` to enable a parallel
installation. When using the parallel install, subdirectories added by calls
to the :command:`add_subdirectory` command are installed independently
and the order that install rules added in different subdirectories will run is
not guaranteed.
.. _`common options`: .. _`common options`:
There are multiple signatures for this command. Some of them define There are multiple signatures for this command. Some of them define
@ -50,7 +58,7 @@ signatures that specify them. The common options are:
``<dir>`` should be a relative path. An absolute path is allowed, ``<dir>`` should be a relative path. An absolute path is allowed,
but not recommended. but not recommended.
When a relative path is given it is interpreted relative to the value When a relative path is given, it is interpreted relative to the value
of the :variable:`CMAKE_INSTALL_PREFIX` variable. of the :variable:`CMAKE_INSTALL_PREFIX` variable.
The prefix can be relocated at install time using the ``DESTDIR`` The prefix can be relocated at install time using the ``DESTDIR``
mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable
@ -67,6 +75,11 @@ signatures that specify them. The common options are:
If an absolute path (with a leading slash or drive letter) is given If an absolute path (with a leading slash or drive letter) is given
it is used verbatim. it is used verbatim.
.. versionchanged:: 3.31
``<dir>`` will be normalized according to the same
:ref:`normalization rules <Normalization>` as the
:command:`cmake_path` command.
``PERMISSIONS <permission>...`` ``PERMISSIONS <permission>...``
Specify permissions for installed files. Valid permissions are Specify permissions for installed files. Valid permissions are
``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``, ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``,
@ -104,11 +117,6 @@ signatures that specify them. The common options are:
Specify that the file is excluded from a full installation and only Specify that the file is excluded from a full installation and only
installed as part of a component-specific installation installed as part of a component-specific installation
``RENAME <name>``
Specify a name for an installed file that may be different from the
original file. Renaming is allowed only when a single file is
installed by the command.
``OPTIONAL`` ``OPTIONAL``
Specify that it is not an error if the file to be installed does Specify that it is not an error if the file to be installed does
not exist. not exist.
@ -393,6 +401,12 @@ Signatures
If a relative path is specified, it is treated as relative to the If a relative path is specified, it is treated as relative to the
:genex:`$<INSTALL_PREFIX>`. :genex:`$<INSTALL_PREFIX>`.
Unlike other ``DESTINATION`` arguments for the various ``install()``
subcommands, paths given after ``INCLUDES DESTINATION`` are used as
given. They are not normalized, nor assumed to be normalized, although
it is recommended that they are given in normalized form (see
:ref:`Normalization`).
``RUNTIME_DEPENDENCY_SET <set-name>`` ``RUNTIME_DEPENDENCY_SET <set-name>``
.. versionadded:: 3.21 .. versionadded:: 3.21
@ -536,6 +550,10 @@ Signatures
However, if any item begins in a generator expression it must evaluate However, if any item begins in a generator expression it must evaluate
to a full path. to a full path.
The optional ``RENAME <name>`` argument is used to specify a name for the
installed file that is different from the original file name. Renaming
is allowed only when a single file is installed by the command.
Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
A ``TYPE`` argument specifies the generic file type of the files being A ``TYPE`` argument specifies the generic file type of the files being
installed. A destination will then be set automatically by taking the installed. A destination will then be set automatically by taking the
@ -561,6 +579,7 @@ Signatures
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale`` ``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man`` ``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc``
``LIBEXEC`` ``${CMAKE_INSTALL_LIBEXECDIR}`` ``libexec``
======================= ================================== ========================= ======================= ================================== =========================
Projects wishing to follow the common practice of installing headers into a Projects wishing to follow the common practice of installing headers into a
@ -599,6 +618,9 @@ Signatures
use "generator expressions" with the syntax ``$<...>``. See the use "generator expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions. :manual:`cmake-generator-expressions(7)` manual for available expressions.
.. versionadded:: 3.31
The ``TYPE`` argument now supports type ``LIBEXEC``.
.. signature:: .. signature::
install(DIRECTORY <dir>... [...]) install(DIRECTORY <dir>... [...])
@ -713,6 +735,7 @@ Signatures
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale`` ``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man`` ``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc``
``LIBEXEC`` ``${CMAKE_INSTALL_LIBEXECDIR}`` ``libexec``
======================= ================================== ========================= ======================= ================================== =========================
Note that some of the types' built-in defaults use the ``DATAROOT`` directory as Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
@ -736,6 +759,9 @@ Signatures
The list of ``dirs...`` given to ``DIRECTORY`` may use The list of ``dirs...`` given to ``DIRECTORY`` may use
"generator expressions" too. "generator expressions" too.
.. versionadded:: 3.31
The ``TYPE`` argument now supports type ``LIBEXEC``.
.. signature:: .. signature::
install(SCRIPT <file> [...]) install(SCRIPT <file> [...])
install(CODE <code> [...]) install(CODE <code> [...])
@ -800,6 +826,7 @@ Signatures
the generated file will be called ``<export-name>.cmake`` but the ``FILE`` the generated file will be called ``<export-name>.cmake`` but the ``FILE``
option may be used to specify a different name. The value given to option may be used to specify a different name. The value given to
the ``FILE`` option must be a file name with the ``.cmake`` extension. the ``FILE`` option must be a file name with the ``.cmake`` extension.
If a ``CONFIGURATIONS`` option is given then the file will only be installed If a ``CONFIGURATIONS`` option is given then the file will only be installed
when one of the named configurations is installed. Additionally, the when one of the named configurations is installed. Additionally, the
generated import file will reference only the matching target generated import file will reference only the matching target
@ -898,6 +925,61 @@ Signatures
executable from the installation tree using the imported target name executable from the installation tree using the imported target name
``mp_myexe`` as if the target were built in its own tree. ``mp_myexe`` as if the target were built in its own tree.
.. signature::
install(PACKAGE_INFO <package-name> [...])
.. versionadded:: 3.31
.. note::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``.
Installs a |CPS|_ file exporting targets for dependent projects:
.. code-block:: cmake
install(PACKAGE_INFO <package-name> EXPORT <export-name>
[APPENDIX <appendix-name>]
[DESTINATION <dir>]
[LOWER_CASE_FILE]
[VERSION <version>
[COMPAT_VERSION <version>]
[VERSION_SCHEMA <string>]]
[DEFAULT_TARGETS <target>...]
[DEFAULT_CONFIGURATIONS <config>...]
[PERMISSIONS <permission>...]
[CONFIGURATIONS <config>...]
[COMPONENT <component>]
[EXCLUDE_FROM_ALL])
The ``PACKAGE_INFO`` form generates and installs a |CPS| file which describes
installed targets such that they can be consumed by another project.
Target installations are associated with the export ``<export-name>``
using the ``EXPORT`` option of the :command:`install(TARGETS)` signature
documented above. Unlike :command:`install(EXPORT)`, this information is not
expressed in CMake code, and can be consumed by tools other than CMake. When
imported into another CMake project, the imported targets will be prefixed
with ``<package-name>::``. By default, the generated file will be called
``<package-name>[-<appendix-name>].cps``. If ``LOWER_CASE_FILE`` is given,
the package name as it appears on disk (in both the file name and install
destination) will be first converted to lower case.
If ``DESTINATION`` is not specified, a platform-specific default is used.
If ``APPENDIX`` is specified, rather than generating a top level package
specification, the specified targets will be exported as an appendix to the
named package. Appendices may be used to separate less commonly used targets
(along with their external dependencies) from the rest of a package. This
enables consumers to ignore transitive dependencies for targets that they
don't use, and also allows a single logical "package" to be composed of
artifacts produced by multiple build trees.
Appendices are not permitted to change basic package metadata; therefore,
none of ``VERSION``, ``COMPAT_VERSION``, ``VERSION_SCHEMA``,
``DEFAULT_TARGETS`` or ``DEFAULT_CONFIGURATIONS`` may be specified in
combination with ``APPENDIX``. Additionally, it is strongly recommended that
use of ``LOWER_CASE_FILE`` should be consistent between the main package and
any appendices.
.. signature:: .. signature::
install(RUNTIME_DEPENDENCY_SET <set-name> [...]) install(RUNTIME_DEPENDENCY_SET <set-name> [...])
@ -1090,3 +1172,6 @@ and by CPack. You can also invoke this script manually with
This is an environment variable rather than a CMake variable. It allows you This is an environment variable rather than a CMake variable. It allows you
to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for
details. details.
.. _CPS: https://cps-org.github.io/cps/
.. |CPS| replace:: Common Package Specification

@ -44,27 +44,18 @@ Projects should not rely on ``<PROJECT-NAME>_SOURCE_DIR`` or
``<PROJECT-NAME>_BINARY_DIR`` holding a particular value outside of the scope ``<PROJECT-NAME>_BINARY_DIR`` holding a particular value outside of the scope
of the call to ``project()`` or one of its child scopes. of the call to ``project()`` or one of its child scopes.
.. versionchanged:: 3.30.3 .. versionchanged:: 3.30
``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and ``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and
``<PROJECT-NAME>_IS_TOP_LEVEL`` are always set as non-cache variables by ``<PROJECT-NAME>_IS_TOP_LEVEL``, if already set as normal variables when
``project(<PROJECT-NAME> ...)``. ``project(<PROJECT-NAME> ...)`` is called, are updated by the call.
Cache entries by the same names are always set as before.
.. versionchanged:: 3.30.4 See release notes for 3.30.3, 3.30.4, and 3.30.5 for details.
The variables ``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``,
and ``<PROJECT-NAME>_IS_TOP_LEVEL`` are only set as non-cache variables if .. versionchanged:: 3.31
they are already set as cache or non-cache variables when ``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and
``project(<PROJECT-NAME> ...)`` is called. ``<PROJECT-NAME>_IS_TOP_LEVEL`` are always set as normal variables by
Note that this logic is flawed, as it can result in different behavior ``project(<PROJECT-NAME> ...)``. See policy :policy:`CMP0180`.
between the first and subsequent runs because cache variables won't exist Cache entries by the same names are always set as before.
on the first run, but they will on subsequent runs.
.. versionchanged:: 3.30.5
The variables ``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``,
and ``<PROJECT-NAME>_IS_TOP_LEVEL`` are only set as non-cache variables if
they are already set as non-cache variables when
``project(<PROJECT-NAME> ...)`` is called.
Unlike the flawed behavior of 3.30.4, non-cache variables will not be set
if only cache variables of the same name are set.
Options Options
^^^^^^^ ^^^^^^^

@ -140,6 +140,11 @@ Items containing ``::``, such as ``Foo::Bar``, are assumed to be
target names and will cause an error if no such target exists. target names and will cause an error if no such target exists.
See policy :policy:`CMP0028`. See policy :policy:`CMP0028`.
See the :variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable and
corresponding :prop_tgt:`LINK_LIBRARIES_STRATEGY` target property
for details on how CMake orders direct link dependencies on linker
command lines.
See the :manual:`cmake-buildsystem(7)` manual for more on defining See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties. buildsystem properties.

@ -91,14 +91,10 @@ CPack generators which are essentially archives at their core. These include:
.. versionadded:: 3.18 .. versionadded:: 3.18
:Default: ``1`` :Default: value of :variable:`CPACK_THREADS`
If set to ``0``, the number of available cores on the machine will be used instead. If set to ``0``, the number of available cores on the machine will be used instead.
The default is ``1`` which limits compression to a single thread. Note that Note that not all compression modes support threading in all environments.
not all compression modes support threading in all environments. Currently,
only the XZ compression may support it.
See also the :variable:`CPACK_THREADS` variable.
.. versionadded:: 3.21 .. versionadded:: 3.21

@ -182,11 +182,22 @@ List of CPack DEB generator specific variables:
only the automatically discovered dependencies will be set for this only the automatically discovered dependencies will be set for this
component. component.
.. versionchanged:: 3.31
The variable is always expanded as a list. Before it was expanded only
if used in cooperation with :variable:`CPACK_DEB_COMPONENT_INSTALL`,
:variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` or
:variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`.
This meant that if a component had no shared libraries discovered
(e.g. a package composed only of scripts) you had to join the list
by yourself to obtain a valid Depends field.
Example: Example:
.. code-block:: cmake .. code-block:: cmake
set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)") set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)")
list(APPEND CPACK_DEBIAN_PACKAGE_DEPENDS cmake)
.. variable:: CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS .. variable:: CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS
@ -654,6 +665,31 @@ List of CPack DEB generator specific variables:
This value is not interpreted. It is possible to pass an optional This value is not interpreted. It is possible to pass an optional
revision number of the referenced source package as well. revision number of the referenced source package as well.
.. variable:: CPACK_DEBIAN_PACKAGE_MULTIARCH
CPACK_DEBIAN_<COMPONENT>_PACKAGE_MULTIARCH
Sets the `Multi-Arch` field of the Debian package.
Packages can declare in their control file how they should handle
situations, where packages for different architectures are being installed
on the same machine.
:Mandatory: No
:Default:
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_MULTIARCH` for component-based
installations.
.. versionadded:: 3.31
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_MULTIARCH` variables.
See https://wiki.debian.org/MultiArch/Hints
.. note::
This value is validated. It must be one of the following values:
``same``, ``foreign``, ``allowed``.
Packaging of debug information Packaging of debug information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

@ -275,6 +275,16 @@ Package
This feature is available for QtIFW 4.0.0 and later. This feature is available for QtIFW 4.0.0 and later.
.. variable:: CPACK_IFW_PACKAGE_PRODUCT_IMAGE_URLS
.. versionadded:: 3.31
A list of URLs associated with the ProductImages.
Only used if ``CPACK_IFW_PACKAGE_PRODUCT_IMAGES`` is defined
and it has the same size.
This feature is available for QtIFW 4.0.0 and later.
.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM .. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM
.. versionadded:: 3.23 .. versionadded:: 3.23

@ -246,9 +246,8 @@ List of CPack RPM generator specific variables:
:Default: (system default) :Default: (system default)
May be used to override RPM compression type to be used to build the May be used to override RPM compression type to be used to build the
RPM. For example some Linux distribution now default to ``lzma`` or ``xz`` RPM. For example some Linux distributions default to ``xz`` or ``zstd``.
compression whereas older cannot use such RPM. Using this one can enforce Using this, one can specify a specific compression type to be used.
compression type to be used.
Possible values are: Possible values are:
@ -264,6 +263,11 @@ List of CPack RPM generator specific variables:
``gzip`` ``gzip``
GNU Gzip compression GNU Gzip compression
``zstd``
.. versionadded:: 3.31
Zstandard compression
.. variable:: CPACK_RPM_PACKAGE_AUTOREQ .. variable:: CPACK_RPM_PACKAGE_AUTOREQ
CPACK_RPM_<component>_PACKAGE_AUTOREQ CPACK_RPM_<component>_PACKAGE_AUTOREQ

@ -458,8 +458,7 @@ Windows using WiX.
administrative privileges. Start menu entries created by the administrative privileges. Start menu entries created by the
installer are visible to all users. installer are visible to all users.
This is the default if :variable:`CPACK_WIX_VERSION` is set to any This is the default. See policy :policy:`CMP0172`.
value other than ``3``.
``perUser`` ``perUser``
Not yet supported. This is reserved for future use. Not yet supported. This is reserved for future use.
@ -467,9 +466,8 @@ Windows using WiX.
``NONE`` ``NONE``
Create an installer without any ``InstallScope`` attribute. Create an installer without any ``InstallScope`` attribute.
If :variable:`CPACK_WIX_VERSION` is not set, or is set to ``3``, this This is supported only if :variable:`CPACK_WIX_VERSION` is not set,
value is the default to preserve compatibility with 3.28 and lower. or is set to ``3``.
Otherwise, this value is not supported.
.. deprecated:: 3.29 .. deprecated:: 3.29

@ -23,12 +23,13 @@ branches and tags. Upstream development processes are covered by the
following documents: following documents:
* The `CMake Review Process`_ manages integration of changes. * The `CMake Review Process`_ manages integration of changes.
* The `CMake Testing Process`_ drives integration testing. * The `CMake Integration Testing`_ infrastructure tests changes
before and after merging.
.. _`Kitware's GitLab Instance`: https://gitlab.kitware.com .. _`Kitware's GitLab Instance`: https://gitlab.kitware.com
.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
.. _`CMake Review Process`: review.rst .. _`CMake Review Process`: review.rst
.. _`CMake Testing Process`: testing.rst .. _`CMake Integration Testing`: integration-testing.rst
Developer Documentation Developer Documentation
======================= =======================
@ -37,10 +38,12 @@ CMake developer documentation is provided by the following documents:
* The `CMake Source Code Guide`_. * The `CMake Source Code Guide`_.
* The `CMake Documentation Guide`_. * The `CMake Documentation Guide`_.
* The `CMake Testing Guide`_.
* The `CMake Experimental Features Guide`_. * The `CMake Experimental Features Guide`_.
.. _`CMake Source Code Guide`: source.rst .. _`CMake Source Code Guide`: source.rst
.. _`CMake Documentation Guide`: documentation.rst .. _`CMake Documentation Guide`: documentation.rst
.. _`CMake Testing Guide`: testing.rst
.. _`CMake Experimental Features Guide`: experimental.rst .. _`CMake Experimental Features Guide`: experimental.rst
Maintainer Documentation Maintainer Documentation

@ -39,6 +39,23 @@ When activated, this experimental feature provides the following:
using the ``CMAKE_EXPORT_FIND_PACKAGE_NAME`` variable and/or using the ``CMAKE_EXPORT_FIND_PACKAGE_NAME`` variable and/or
``EXPORT_FIND_PACKAGE_NAME`` target property. ``EXPORT_FIND_PACKAGE_NAME`` target property.
Export |CPS| Package Information
================================
In order to activate support for this experimental feature, set
* variable ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO`` to
* value ``b80be207-778e-46ba-8080-b23bba22639e``.
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.
When activated, this experimental feature provides the following:
* The experimental ``install(PACKAGE_INFO)`` command is available to export
package information in the |CPS|_ format.
C++ ``import std`` support C++ ``import std`` support
========================== ==========================
@ -60,3 +77,27 @@ When activated, this experimental feature provides the following:
* Targets with the property set to a true value and at least ``cxx_std_23`` * 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. may use ``import std;`` in any scanned C++ source file.
.. _CPS: https://cps-org.github.io/cps/
.. |CPS| replace:: Common Package Specification
Build database support
======================
In order to activate support for exporting build databases, set
* variable ``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` to
* value ``4bd552e2-b7fb-429a-ab23-c83ef53f3f13``.
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.
When activated, this experimental feature provides the following:
* The :prop_tgt:`EXPORT_BUILD_DATABASE` target property and its initializing
variable :variable:`CMAKE_EXPORT_BUILD_DATABASE` and environment variable
:envvar:`CMAKE_EXPORT_BUILD_DATABASE`.
* Targets with the property set to a true value will have their C++ build
information exported to the build database.

@ -0,0 +1,46 @@
CMake Integration Testing
*************************
The following documents how to run integration testing builds.
See documentation on `CMake Development`_ for more information.
See the `CMake Testing Guide`_ for running the test suite locally.
.. _`CMake Development`: README.rst
.. _`CMake Testing Guide`: testing.rst
CMake Dashboard Scripts
=======================
The *integration testing* step of the `CMake Review Process`_ uses a set of
testing machines that follow an integration branch on their own schedule to
drive testing and submit results to the `CMake CDash Page`_. Anyone is
welcome to provide testing machines in order to help keep support for their
platforms working.
The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive
nightly, continuous, and experimental testing of CMake. Use the following
commands to set up a new integration testing client:
.. code-block:: console
$ mkdir -p ~/Dashboards
$ cd ~/Dashboards
$ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts
$ cd CMakeScripts
The `cmake_common.cmake`_ script contains comments at the top with
instructions to set up a testing client. As it instructs, create a
CTest script with local settings and include ``cmake_common.cmake``.
.. _`CMake Review Process`: review.rst
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
.. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts
.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/-/blob/master/cmake_common.cmake
Nightly Start Time
------------------
The ``cmake_common.cmake`` script expects its includer to be run from a
nightly scheduled task (cron job). Schedule such tasks for sometime after
``1:00am UTC``, the time at which our nightly testing branches fast-forward.

@ -306,11 +306,22 @@ Commit with a message such as::
Begin post-$ver development Begin post-$ver development
Push the update to the ``master`` and ``release`` branches: Create a topic branch for the update to ``master``:
.. code-block:: shell .. code-block:: shell
git push --atomic origin master release-$ver:release git branch branch-$ver master
Open a merge request with the ``branch-$ver`` branch for review and CI.
Add the following trailing lines in the merge request description::
Fast-forward: true
Backport-ff: release:HEAD~1^2
This configures the ``Do: merge`` action to fast-foward the ``master``
and ``release`` branches to the respective commits created above.
Further steps may proceed after this has been merged.
Announce 'release' Branch Announce 'release' Branch
------------------------- -------------------------

@ -348,7 +348,7 @@ Integration Testing
The above `topic testing`_ tests the MR topic independent of other The above `topic testing`_ tests the MR topic independent of other
merge requests and on only a few key platforms and configurations. merge requests and on only a few key platforms and configurations.
The `CMake Testing Process`_ also has a large number of machines `CMake Integration Testing`_ also uses a large number of machines
provided by Kitware and generous volunteers that cover nearly all provided by Kitware and generous volunteers that cover nearly all
supported platforms, generators, and configurations. In order to supported platforms, generators, and configurations. In order to
avoid overwhelming these resources, they do not test every MR avoid overwhelming these resources, they do not test every MR
@ -403,7 +403,7 @@ until one of the following occurs:
Once a MR has been removed from the topic stage a new ``Do: stage`` Once a MR has been removed from the topic stage a new ``Do: stage``
command is needed to stage it again. command is needed to stage it again.
.. _`CMake Testing Process`: testing.rst .. _`CMake Integration Testing`: integration-testing.rst
Resolve Resolve
======= =======

@ -249,6 +249,14 @@ These are:
* ``cm::is_unique_ptr``: * ``cm::is_unique_ptr``:
Checks if a type is a ``std::unique_ptr`` type. Checks if a type is a ``std::unique_ptr`` type.
* ``cm::remove_member_pointer``
Produces the underlying type of a member-pointer type, ie, given ``T C::*``,
returns ``T``.
* ``cm::member_pointer_class``
Produces the class associated with a member-pointer type, ie, given
``T C::*``, returns ``C``.
CMake assumes the compiler supports ``#pragma once``. Use this for all CMake assumes the compiler supports ``#pragma once``. Use this for all
hand-written header files. hand-written header files.
@ -310,6 +318,7 @@ The CMake source tree is organized as follows.
* ``Tests/``: * ``Tests/``:
The test suite. See `Tests/README.rst`_. The test suite. See `Tests/README.rst`_.
To run the tests, see the `CMake Testing Guide`_.
* ``Utilities/``: * ``Utilities/``:
Scripts, third-party source code. Scripts, third-party source code.
@ -331,5 +340,6 @@ The CMake source tree is organized as follows.
See `Utilities/Release/README.rst`_. See `Utilities/Release/README.rst`_.
.. _`CMake Documentation Guide`: documentation.rst .. _`CMake Documentation Guide`: documentation.rst
.. _`CMake Testing Guide`: testing.rst
.. _`Tests/README.rst`: ../../Tests/README.rst .. _`Tests/README.rst`: ../../Tests/README.rst
.. _`Utilities/Release/README.rst`: ../../Utilities/Release/README.rst .. _`Utilities/Release/README.rst`: ../../Utilities/Release/README.rst

@ -1,43 +1,111 @@
CMake Testing Process CMake Testing Guide
********************* *******************
The following documents the process for running integration testing builds. The following is a guide to the CMake test suite for developers.
See documentation on `CMake Development`_ for more information. See documentation on `CMake Development`_ for more information.
See `CMake Integration Testing`_ for running integration testing builds.
See `Tests/README.rst`_ for the test suite layout in the source tree.
.. _`CMake Development`: README.rst .. _`CMake Development`: README.rst
.. _`CMake Integration Testing`: integration-testing.rst
.. _`Tests/README.rst`: ../../Tests/README.rst
Running Tests in the Build Tree
===============================
After `Building CMake`_, one may run the test suite in the build tree
using `ctest(1)`_:
* With a single-configuration CMake generator, such as ``Ninja``
or ``Unix Makefiles``, one may simply run ``ctest``:
.. code-block:: console
$ ctest
* With a multi-configuration CMake generator, such as
``Ninja Multi-Config``, ``Visual Studio``, or ``Xcode``,
one must tell ``ctest`` which configuration to test
by passing the ``-C <config>`` option:
.. code-block:: console
$ ctest -C Debug
Some useful `ctest(1)`_ options include:
``-N``
List test names without running them.
``-V``
Show verbose output from each test.
CMake Dashboard Scripts ``-j <N>``
======================= Run to run up to ``N`` tests concurrently.
The *integration testing* step of the `CMake Review Process`_ uses a set of ``-R <regex>``
testing machines that follow an integration branch on their own schedule to Select tests for which the regular expression matches a substring
drive testing and submit results to the `CMake CDash Page`_. Anyone is of their name.
welcome to provide testing machines in order to help keep support for their
platforms working.
The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive Cleaning Test Build Trees
nightly, continuous, and experimental testing of CMake. Use the following -------------------------
commands to set up a new integration testing client:
Many CMake tests create their own test project build trees underneath
the ``Tests/`` directory at the top of the CMake build tree. These
build trees are left behind after testing completes in order to
facilitate manual investigation of results. Many of the tests do *not*
clean their build trees if they are run again, with the exception of
tests using the `RunCMake`_ infrastructure.
In order to clear test build trees, drive the ``test_clean`` custom target
in the CMake build tree:
.. code-block:: console .. code-block:: console
$ mkdir -p ~/Dashboards $ cmake --build . --target test_clean
$ cd ~/Dashboards
$ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts This removes the ``Tests/`` subdirectories created by individual tests
$ cd CMakeScripts so they will use a fresh directory next time they run.
.. _`Building CMake`: ../../README.rst#building-cmake
.. _`ctest(1)`: https://cmake.org/cmake/help/latest/manual/ctest.1.html
.. _`RunCMake`: ../../Tests/RunCMake/README.rst
The `cmake_common.cmake`_ script contains comments at the top with Running Tests with a Different Generator
instructions to set up a testing client. As it instructs, create a ========================================
CTest script with local settings and include ``cmake_common.cmake``.
After `Building CMake`_ with one CMake generator, one may configure the
test suite using a different generator in a separate build tree, without
building CMake itself again, by defining ``CMake_TEST_EXTERNAL_CMAKE``
to be the absolute path to the ``bin`` directory containing the ``cmake``,
``ctest``, and ``cpack`` executables.
For example, after building CMake with the ``Ninja`` generator:
.. code-block:: console
.. _`CMake Review Process`: review.rst $ cmake -B build-ninja -G Ninja -DCMAKE_BUILD_TYPE=Debug
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake $ cmake --build build-ninja
.. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts
.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/-/blob/master/cmake_common.cmake one may configure a second build tree to drive tests with the
``Ninja Multi-Config`` generator:
.. code-block:: console
$ cmake -B build-nmc-tests -G "Ninja Multi-Config" \
-DCMake_TEST_EXTERNAL_CMAKE="$PWD/build-ninja/bin"
$ cmake --build build-nmc-tests --config Release
The second build tree does not build CMake itself, but does configure
the test suite and build test binaries. One may then run tests normally:
.. code-block:: console
Nightly Start Time $ cd build-nmc-tests
------------------ $ ctest -C Release
The ``cmake_common.cmake`` script expects its includer to be run from a Note that the configuration with which one drives tests in the second
nightly scheduled task (cron job). Schedule such tasks for sometime after build tree is independent of the configuration with which CMake was
``1:00am UTC``, the time at which our nightly testing branches fast-forward. built in the first.

@ -1,6 +0,0 @@
try_compile-linker-language
---------------------------
* The :command:`try_compile` and :command:`try_run` commands gained a
``LINKER_LANGUAGE`` option to specify the :prop_tgt:`LINKER_LANGUAGE`
target property in the generated test project.

@ -0,0 +1,18 @@
CMAKE_CONFIG_DIR
----------------
.. versionadded:: 3.31
.. include:: ENV_VAR.txt
Specify a CMake user-wide configuration directory for
:manual:`cmake-file-api(7)` queries.
If this environment variable is not set, the default user-wide
configuration directory is platform-specific:
- Windows: ``%LOCALAPPDATA%\CMake``
- macOS: ``$XDG_CONFIG_HOME/CMake`` if set, otherwise
``$HOME/Library/Application Support/CMake``
- Linux/Other: ``$XDG_CONFIG_HOME/cmake`` if set, otherwise
``$HOME/.config/cmake``

@ -0,0 +1,17 @@
CMAKE_EXPORT_BUILD_DATABASE
---------------------------
.. versionadded:: 3.31
.. include:: ENV_VAR.txt
The default value for :variable:`CMAKE_EXPORT_BUILD_DATABASE` when there is no
explicit configuration given on the first run while creating a new build tree.
On later runs in an existing build tree the value persists in the cache as
:variable:`CMAKE_EXPORT_BUILD_DATABASE`.
.. note ::
This variable is meaningful only when experimental support for build
databases has been enabled by the
``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.

@ -0,0 +1,11 @@
CMAKE_INSTALL_PARALLEL_LEVEL
----------------------------
.. versionadded:: 3.31
.. include:: ENV_VAR.txt
Specifies the default maximum number of concurrent processes to use when
installing using ``cmake --install``.
This has no impact unless :prop_gbl:`INSTALL_PARALLEL` is enabled.

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

@ -1,57 +1,8 @@
Visual Studio 12 2013 Visual Studio 12 2013
--------------------- ---------------------
Deprecated. Generates Visual Studio 12 (VS 2013) project files. Removed. This once generated Visual Studio 12 2013 project files, but
the generator has been removed since CMake 3.31. It is still possible
.. note:: to build with VS 12 2013 tools using the :generator:`Visual Studio 14 2015`
This generator is deprecated and will be removed in a future version (or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v120``,
of CMake. It will still be possible to build with VS 12 2013 tools or by using the :generator:`NMake Makefiles` generator.
using the :generator:`Visual Studio 14 2015` (or above) generator
with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v120``, or by
using the :generator:`NMake Makefiles` generator.
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name "Visual Studio 12" without the year component.
Project Types
^^^^^^^^^^^^^
Only Visual C++ and C# projects may be generated (and Fortran with
Intel compiler integration). Other types of projects (JavaScript,
Powershell, Python, etc.) are not supported.
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 12 2013" -A Win32``
* ``cmake -G "Visual Studio 12 2013" -A x64``
* ``cmake -G "Visual Studio 12 2013" -A ARM``
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 12 2013 Win64``
Specify target platform ``x64``.
``Visual Studio 12 2013 ARM``
Specify target platform ``ARM``.
Toolset Selection
^^^^^^^^^^^^^^^^^
The ``v120`` toolset that comes with Visual Studio 12 2013 is selected by
default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :option:`cmake -T` option, to specify another toolset.
.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
By default this generator uses the 32-bit variant even on a 64-bit host.
.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt

@ -300,6 +300,8 @@ the table below:
commands used without a type commands used without a type
:variable:`CMAKE_EXPORT_COMPILE_COMMANDS` Generate a ``compile_commands.json`` :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` Generate a ``compile_commands.json``
file for use with clang-based tools file for use with clang-based tools
:variable:`CMAKE_EXPORT_BUILD_DATABASE` Generate a ``build_database.json``
file for use with clang-based tools
========================================== ============================================================ ========================================== ============================================================
Other project-specific variables may be available Other project-specific variables may be available

@ -22,6 +22,7 @@ These commands are always available.
/command/cmake_minimum_required /command/cmake_minimum_required
/command/cmake_parse_arguments /command/cmake_parse_arguments
/command/cmake_path /command/cmake_path
/command/cmake_pkg_config
/command/cmake_policy /command/cmake_policy
/command/configure_file /command/configure_file
/command/continue /command/continue

@ -43,15 +43,18 @@ Environment Variables that Control the Build
/envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_BUILD_PARALLEL_LEVEL
/envvar/CMAKE_BUILD_TYPE /envvar/CMAKE_BUILD_TYPE
/envvar/CMAKE_COLOR_DIAGNOSTICS /envvar/CMAKE_COLOR_DIAGNOSTICS
/envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIG_DIR
/envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_CONFIG_TYPE
/envvar/CMAKE_CONFIGURATION_TYPES
/envvar/CMAKE_CROSSCOMPILING_EMULATOR /envvar/CMAKE_CROSSCOMPILING_EMULATOR
/envvar/CMAKE_EXPORT_BUILD_DATABASE
/envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_EXPORT_COMPILE_COMMANDS
/envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR
/envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_INSTANCE
/envvar/CMAKE_GENERATOR_PLATFORM /envvar/CMAKE_GENERATOR_PLATFORM
/envvar/CMAKE_GENERATOR_TOOLSET /envvar/CMAKE_GENERATOR_TOOLSET
/envvar/CMAKE_INSTALL_MODE /envvar/CMAKE_INSTALL_MODE
/envvar/CMAKE_INSTALL_PARALLEL_LEVEL
/envvar/CMAKE_INSTALL_PREFIX /envvar/CMAKE_INSTALL_PREFIX
/envvar/CMAKE_LANG_COMPILER_LAUNCHER /envvar/CMAKE_LANG_COMPILER_LAUNCHER
/envvar/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES_EXCLUDE /envvar/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES_EXCLUDE

@ -50,6 +50,10 @@ It has the following subdirectories:
Clients may optionally create the ``reply/`` directory at any time Clients may optionally create the ``reply/`` directory at any time
and monitor it for the appearance of a new reply index file. and monitor it for the appearance of a new reply index file.
.. versionadded:: 3.31
Users can add query files to ``api/v1/query`` inside the
:envvar:`CMAKE_CONFIG_DIR` to create user-wide queries for all CMake projects.
v1 Shared Stateless Query Files v1 Shared Stateless Query Files
------------------------------- -------------------------------

@ -1877,6 +1877,14 @@ These expressions look up the values of
rather than the directory of the consuming target for which the rather than the directory of the consuming target for which the
expression is being evaluated. expression is being evaluated.
.. versionchanged:: 3.31
Generator expressions for transitive interface properties, such as
``$<TARGET_PROPERTY:target,INTERFACE_*>``, now correctly handle
repeated evaluations within nested generator expressions.
Previously, these repeated evaluations returned empty values due
to an optimization for transitive closures.
This change ensures consistent evaluation for non-union operations.
.. genex:: $<TARGET_PROPERTY:prop> .. genex:: $<TARGET_PROPERTY:prop>
:target: TARGET_PROPERTY:prop :target: TARGET_PROPERTY:prop

@ -55,7 +55,6 @@ These modules are loaded using the :command:`include` command.
/module/CMakeBackwardCompatibilityCXX /module/CMakeBackwardCompatibilityCXX
/module/CMakeDependentOption /module/CMakeDependentOption
/module/CMakeFindDependencyMacro /module/CMakeFindDependencyMacro
/module/CMakeFindFrameworks
/module/CMakeFindPackageMode /module/CMakeFindPackageMode
/module/CMakeGraphVizOptions /module/CMakeGraphVizOptions
/module/CMakePackageConfigHelpers /module/CMakePackageConfigHelpers
@ -269,6 +268,7 @@ Deprecated Utility Modules
/module/AddFileDependencies /module/AddFileDependencies
/module/CMakeDetermineVSServicePack /module/CMakeDetermineVSServicePack
/module/CMakeExpandImportedTargets /module/CMakeExpandImportedTargets
/module/CMakeFindFrameworks
/module/CMakeForceCompiler /module/CMakeForceCompiler
/module/CMakeParseArguments /module/CMakeParseArguments
/module/Dart /module/Dart

@ -51,6 +51,23 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
to determine whether to report an error on use of deprecated macros or to determine whether to report an error on use of deprecated macros or
functions. functions.
Policies Introduced by CMake 3.31
=================================
.. toctree::
:maxdepth: 1
CMP0180: project() always sets <PROJECT-NAME>_* as normal variables. </policy/CMP0180>
CMP0179: De-duplication of static libraries on link lines keeps first occurrence. </policy/CMP0179>
CMP0178: Test command lines preserve empty arguments. </policy/CMP0178>
CMP0177: install() DESTINATION paths are normalized. </policy/CMP0177>
CMP0176: execute_process() ENCODING is UTF-8 by default. </policy/CMP0176>
CMP0175: add_custom_command() rejects invalid arguments. </policy/CMP0175>
CMP0174: cmake_parse_arguments(PARSE_ARGV) defines a variable for an empty string after a single-value keyword. </policy/CMP0174>
CMP0173: The CMakeFindFrameworks module is removed. </policy/CMP0173>
CMP0172: The CPack module enables per-machine installation by default in the CPack WIX Generator. </policy/CMP0172>
CMP0171: 'codegen' is a reserved target name. </policy/CMP0171>
Policies Introduced by CMake 3.30 Policies Introduced by CMake 3.30
================================= =================================

@ -39,6 +39,9 @@ The files are a JSON document with an object as the root:
.. literalinclude:: presets/example.json .. literalinclude:: presets/example.json
:language: json :language: json
Preset files specifying version ``10`` or above may include comments using the
key ``$comment`` at any level within the JSON object to provide documentation.
The root object recognizes the following fields: The root object recognizes the following fields:
``$schema`` ``$schema``
@ -81,6 +84,9 @@ The root object recognizes the following fields:
``9`` ``9``
.. versionadded:: 3.30 .. versionadded:: 3.30
``10``
.. versionadded:: 3.31
``cmakeMinimumRequired`` ``cmakeMinimumRequired``
An optional object representing the minimum version of CMake needed to An optional object representing the minimum version of CMake needed to
build this project. This object consists of the following fields: build this project. This object consists of the following fields:
@ -261,6 +267,16 @@ that may contain the following fields:
:variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files :variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files
specifying version ``3`` or above. specifying version ``3`` or above.
``graphviz``
An optional string representing the path to the graphviz input file,
that will contain all the library and executable dependencies
in the project. See the documentation for :module:`CMakeGraphVizOptions`
for more details.
This field supports `macro expansion`_. If a relative path is specified,
it is calculated relative to the current working directory. It is allowed
in preset files specifying version ``10`` or above.
``binaryDir`` ``binaryDir``
An optional string representing the path to the output binary directory. An optional string representing the path to the output binary directory.
This field supports `macro expansion`_. If a relative path is specified, This field supports `macro expansion`_. If a relative path is specified,
@ -307,10 +323,14 @@ that may contain the following fields:
(which may not be an empty string), and the value is either ``null`` or (which may not be an empty string), and the value is either ``null`` or
a string representing the value of the variable. Each variable is set a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's regardless of whether or not a value was given to it by the process's
environment. This field supports `macro expansion`_, and environment environment.
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example, This field supports `macro expansion`_, and environment variables in this map
if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) may reference each other, and may be listed in any order, as long as such
references do not cause a cycle (for example, if ``ENV_1`` is
``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``). ``$penv{NAME}``
allows one to prepend or append values to existing environment variables by
accessing only values from the parent environment.
Environment variables are inherited through the ``inherits`` field, and Environment variables are inherited through the ``inherits`` field, and
the preset's environment will be the union of its own ``environment`` and the preset's environment will be the union of its own ``environment`` and
@ -492,10 +512,14 @@ that may contain the following fields:
(which may not be an empty string), and the value is either ``null`` or (which may not be an empty string), and the value is either ``null`` or
a string representing the value of the variable. Each variable is set a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's regardless of whether or not a value was given to it by the process's
environment. This field supports macro expansion, and environment environment.
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example, if This field supports `macro expansion`_, and environment variables in this map
``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) may reference each other, and may be listed in any order, as long as such
references do not cause a cycle (for example, if ``ENV_1`` is
``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``). ``$penv{NAME}``
allows one to prepend or append values to existing environment variables by
accessing only values from the parent environment.
Environment variables are inherited through the ``inherits`` field, and Environment variables are inherited through the ``inherits`` field, and
the preset's environment will be the union of its own ``environment`` the preset's environment will be the union of its own ``environment``
@ -653,10 +677,14 @@ that may contain the following fields:
(which may not be an empty string), and the value is either ``null`` or (which may not be an empty string), and the value is either ``null`` or
a string representing the value of the variable. Each variable is set a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's regardless of whether or not a value was given to it by the process's
environment. This field supports macro expansion, and environment environment.
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example, if This field supports `macro expansion`_, and environment variables in this map
``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) may reference each other, and may be listed in any order, as long as such
references do not cause a cycle (for example, if ``ENV_1`` is
``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``). ``$penv{NAME}``
allows one to prepend or append values to existing environment variables by
accessing only values from the parent environment.
Environment variables are inherited through the ``inherits`` field, and Environment variables are inherited through the ``inherits`` field, and
the preset's environment will be the union of its own ``environment`` the preset's environment will be the union of its own ``environment``
@ -994,10 +1022,14 @@ fields:
(which may not be an empty string), and the value is either ``null`` or (which may not be an empty string), and the value is either ``null`` or
a string representing the value of the variable. Each variable is set a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's regardless of whether or not a value was given to it by the process's
environment. This field supports macro expansion, and environment environment.
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example, if This field supports `macro expansion`_, and environment variables in this map
``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) may reference each other, and may be listed in any order, as long as such
references do not cause a cycle (for example, if ``ENV_1`` is
``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``). ``$penv{NAME}``
allows one to prepend or append values to existing environment variables by
accessing only values from the parent environment.
Environment variables are inherited through the ``inherits`` field, and Environment variables are inherited through the ``inherits`` field, and
the preset's environment will be the union of its own ``environment`` the preset's environment will be the union of its own ``environment``
@ -1264,7 +1296,7 @@ Recognized macros include:
``$penv{<variable-name>}`` ``$penv{<variable-name>}``
Similar to ``$env{<variable-name>}``, except that the value only comes from Similar to ``$env{<variable-name>}``, except that the value only comes from
the parent environment, and never from the ``environment`` field. This the parent environment, and never from the ``environment`` field. This
allows you to prepend or append values to existing environment variables. allows one to prepend or append values to existing environment variables.
For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will
prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This
is needed because ``$env{<variable-name>}`` does not allow circular is needed because ``$env{<variable-name>}`` does not allow circular

@ -109,6 +109,7 @@ Properties on Targets
/prop_tgt/ADDITIONAL_CLEAN_FILES /prop_tgt/ADDITIONAL_CLEAN_FILES
/prop_tgt/AIX_EXPORT_ALL_SYMBOLS /prop_tgt/AIX_EXPORT_ALL_SYMBOLS
/prop_tgt/AIX_SHARED_LIBRARY_ARCHIVE
/prop_tgt/ALIAS_GLOBAL /prop_tgt/ALIAS_GLOBAL
/prop_tgt/ALIASED_TARGET /prop_tgt/ALIASED_TARGET
/prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS /prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS
@ -216,6 +217,7 @@ Properties on Targets
/prop_tgt/EXCLUDE_FROM_ALL /prop_tgt/EXCLUDE_FROM_ALL
/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD
/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG
/prop_tgt/EXPORT_BUILD_DATABASE
/prop_tgt/EXPORT_COMPILE_COMMANDS /prop_tgt/EXPORT_COMPILE_COMMANDS
/prop_tgt/EXPORT_FIND_PACKAGE_NAME /prop_tgt/EXPORT_FIND_PACKAGE_NAME
/prop_tgt/EXPORT_NAME /prop_tgt/EXPORT_NAME
@ -334,6 +336,7 @@ Properties on Targets
/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG
/prop_tgt/LINK_LIBRARIES /prop_tgt/LINK_LIBRARIES
/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS
/prop_tgt/LINK_LIBRARIES_STRATEGY
/prop_tgt/LINK_LIBRARY_OVERRIDE /prop_tgt/LINK_LIBRARY_OVERRIDE
/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY /prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY
/prop_tgt/LINK_OPTIONS /prop_tgt/LINK_OPTIONS
@ -430,6 +433,7 @@ Properties on Targets
/prop_tgt/VS_DOTNET_STARTUP_OBJECT /prop_tgt/VS_DOTNET_STARTUP_OBJECT
/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION
/prop_tgt/VS_DPI_AWARE /prop_tgt/VS_DPI_AWARE
/prop_tgt/VS_FRAMEWORK_REFERENCES
/prop_tgt/VS_GLOBAL_KEYWORD /prop_tgt/VS_GLOBAL_KEYWORD
/prop_tgt/VS_GLOBAL_PROJECT_TYPES /prop_tgt/VS_GLOBAL_PROJECT_TYPES
/prop_tgt/VS_GLOBAL_ROOTNAMESPACE /prop_tgt/VS_GLOBAL_ROOTNAMESPACE

@ -591,14 +591,14 @@ a different SDK (e.g. a simulator) can be selected by setting the
necessary (see :ref:`Switching Between Device and Simulator` below). necessary (see :ref:`Switching Between Device and Simulator` below).
A list of available SDKs can be obtained by running ``xcodebuild -showsdks``. A list of available SDKs can be obtained by running ``xcodebuild -showsdks``.
======== ================= ==================== ================ ======== ================= ==================== ================ ============
OS CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK OS CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK Catalyst SDK
======== ================= ==================== ================ ======== ================= ==================== ================ ============
iOS iOS iphoneos iphonesimulator iOS iOS iphoneos iphonesimulator macosx
tvOS tvOS appletvos appletvsimulator tvOS tvOS appletvos appletvsimulator N/A
visionOS visionOS xros xrsimulator visionOS visionOS xros xrsimulator N/A
watchOS watchOS watchos watchsimulator watchOS watchOS watchos watchsimulator N/A
======== ================= ==================== ================ ======== ================= ==================== ================ ============
For example, to create a CMake configuration for iOS, the following For example, to create a CMake configuration for iOS, the following
command is sufficient: command is sufficient:

@ -106,6 +106,7 @@ Variables that Provide Information
/variable/CMAKE_SCRIPT_MODE_FILE /variable/CMAKE_SCRIPT_MODE_FILE
/variable/CMAKE_SHARED_LIBRARY_PREFIX /variable/CMAKE_SHARED_LIBRARY_PREFIX
/variable/CMAKE_SHARED_LIBRARY_SUFFIX /variable/CMAKE_SHARED_LIBRARY_SUFFIX
/variable/CMAKE_SHARED_LIBRARY_ARCHIVE_SUFFIX
/variable/CMAKE_SHARED_MODULE_PREFIX /variable/CMAKE_SHARED_MODULE_PREFIX
/variable/CMAKE_SHARED_MODULE_SUFFIX /variable/CMAKE_SHARED_MODULE_SUFFIX
/variable/CMAKE_SIZEOF_VOID_P /variable/CMAKE_SIZEOF_VOID_P
@ -142,6 +143,7 @@ Variables that Provide Information
/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
/variable/CMAKE_WINDOWS_KMDF_VERSION
/variable/CMAKE_XCODE_BUILD_SYSTEM /variable/CMAKE_XCODE_BUILD_SYSTEM
/variable/CMAKE_XCODE_PLATFORM_TOOLSET /variable/CMAKE_XCODE_PLATFORM_TOOLSET
/variable/PROJECT-NAME_BINARY_DIR /variable/PROJECT-NAME_BINARY_DIR
@ -194,6 +196,7 @@ Variables that Change Behavior
/variable/CMAKE_ERROR_DEPRECATED /variable/CMAKE_ERROR_DEPRECATED
/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO /variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO
/variable/CMAKE_EXPORT_BUILD_DATABASE
/variable/CMAKE_EXPORT_COMPILE_COMMANDS /variable/CMAKE_EXPORT_COMPILE_COMMANDS
/variable/CMAKE_EXPORT_PACKAGE_REGISTRY /variable/CMAKE_EXPORT_PACKAGE_REGISTRY
/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY
@ -320,6 +323,7 @@ Variables that Describe the System
/variable/CMAKE_COMPILER_2005 /variable/CMAKE_COMPILER_2005
/variable/CMAKE_HOST_APPLE /variable/CMAKE_HOST_APPLE
/variable/CMAKE_HOST_BSD /variable/CMAKE_HOST_BSD
/variable/CMAKE_HOST_EXECUTABLE_SUFFIX
/variable/CMAKE_HOST_LINUX /variable/CMAKE_HOST_LINUX
/variable/CMAKE_HOST_SOLARIS /variable/CMAKE_HOST_SOLARIS
/variable/CMAKE_HOST_SYSTEM /variable/CMAKE_HOST_SYSTEM
@ -346,6 +350,7 @@ Variables that Describe the System
/variable/MSVC_VERSION /variable/MSVC_VERSION
/variable/MSYS /variable/MSYS
/variable/UNIX /variable/UNIX
/variable/WASI
/variable/WIN32 /variable/WIN32
/variable/WINCE /variable/WINCE
/variable/WINDOWS_PHONE /variable/WINDOWS_PHONE
@ -360,6 +365,7 @@ Variables that Control the Build
:maxdepth: 1 :maxdepth: 1
/variable/CMAKE_ADSP_ROOT /variable/CMAKE_ADSP_ROOT
/variable/CMAKE_AIX_SHARED_LIBRARY_ARCHIVE
/variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS /variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS
/variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS /variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS
/variable/CMAKE_ANDROID_API /variable/CMAKE_ANDROID_API
@ -486,6 +492,7 @@ Variables that Control the Build
/variable/CMAKE_LINK_GROUP_USING_FEATURE /variable/CMAKE_LINK_GROUP_USING_FEATURE
/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED /variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED
/variable/CMAKE_LINK_INTERFACE_LIBRARIES /variable/CMAKE_LINK_INTERFACE_LIBRARIES
/variable/CMAKE_LINK_LIBRARIES_STRATEGY
/variable/CMAKE_LINK_LIBRARY_FEATURE_ATTRIBUTES /variable/CMAKE_LINK_LIBRARY_FEATURE_ATTRIBUTES
/variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FILE_FLAG
/variable/CMAKE_LINK_LIBRARY_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG
@ -614,6 +621,7 @@ Variables for Languages
/variable/CMAKE_LANG_COMPILER_TARGET /variable/CMAKE_LANG_COMPILER_TARGET
/variable/CMAKE_LANG_COMPILER_VERSION /variable/CMAKE_LANG_COMPILER_VERSION
/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY
/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY_ARCHIVE
/variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_SHARED_MODULE
/variable/CMAKE_LANG_CREATE_STATIC_LIBRARY /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY
/variable/CMAKE_LANG_EXTENSIONS /variable/CMAKE_LANG_EXTENSIONS
@ -631,6 +639,8 @@ Variables for Languages
/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO
/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT
/variable/CMAKE_LANG_HOST_COMPILER /variable/CMAKE_LANG_HOST_COMPILER
/variable/CMAKE_LANG_HOST_COMPILER_ID
/variable/CMAKE_LANG_HOST_COMPILER_VERSION
/variable/CMAKE_LANG_IGNORE_EXTENSIONS /variable/CMAKE_LANG_IGNORE_EXTENSIONS
/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES
/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES
@ -650,6 +660,7 @@ Variables for Languages
/variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES
/variable/CMAKE_LANG_STANDARD_LATEST /variable/CMAKE_LANG_STANDARD_LATEST
/variable/CMAKE_LANG_STANDARD_LIBRARIES /variable/CMAKE_LANG_STANDARD_LIBRARIES
/variable/CMAKE_LANG_STANDARD_LINK_DIRECTORIES
/variable/CMAKE_LANG_STANDARD_REQUIRED /variable/CMAKE_LANG_STANDARD_REQUIRED
/variable/CMAKE_OBJC_EXTENSIONS /variable/CMAKE_OBJC_EXTENSIONS
/variable/CMAKE_OBJC_STANDARD /variable/CMAKE_OBJC_STANDARD

@ -31,7 +31,7 @@ Synopsis
cmake --find-package [<options>] cmake --find-package [<options>]
`Run a Workflow Preset`_ `Run a Workflow Preset`_
cmake --workflow [<options>] cmake --workflow <options>
`View Help`_ `View Help`_
cmake --help[-<topic>] cmake --help[-<topic>]
@ -232,6 +232,17 @@ Options
will display also advanced variables. If ``H`` is specified, it will also will display also advanced variables. If ``H`` is specified, it will also
display help for each variable. display help for each variable.
.. option:: -LR[A][H] <regex>
.. versionadded:: 3.31
Show specific non-advanced cached variables
Show non-``INTERNAL`` nor :prop_cache:`ADVANCED` variables from the CMake
``CACHE`` that match the given regex. If ``A`` is specified, then it
will also show advanced variables. If ``H`` is specified, it will also
display help for each variable.
.. option:: -N .. option:: -N
View mode only. View mode only.
@ -255,8 +266,18 @@ Options
from the top of a binary tree for a CMake project it will dump from the top of a binary tree for a CMake project it will dump
additional information such as the cache, log files etc. additional information such as the cache, log files etc.
.. option:: --print-config-dir
.. versionadded:: 3.31
Print CMake config directory for user-wide FileAPI queries.
See :envvar:`CMAKE_CONFIG_DIR` for more details.
.. option:: --log-level=<level> .. option:: --log-level=<level>
.. versionadded:: 3.16
Set the log ``<level>``. Set the log ``<level>``.
The :command:`message` command will only output messages of the specified The :command:`message` command will only output messages of the specified
@ -745,6 +766,15 @@ The options are:
This option can be omitted if :envvar:`VERBOSE` environment variable is set. This option can be omitted if :envvar:`VERBOSE` environment variable is set.
.. option:: -j <jobs>, --parallel <jobs>
.. versionadded:: 3.31
Install in parallel using the given number of jobs. Only available if
:prop_gbl:`INSTALL_PARALLEL` is enabled. The
:envvar:`CMAKE_INSTALL_PARALLEL_LEVEL` environment variable specifies a
default parallel level when this option is not provided.
Run :option:`cmake --install` with no options for quick help. Run :option:`cmake --install` with no options for quick help.
Open a Project Open a Project
@ -1364,7 +1394,7 @@ build steps in order:
.. code-block:: shell .. code-block:: shell
cmake --workflow [<options>] cmake --workflow <options>
The options are: The options are:
@ -1381,6 +1411,15 @@ The options are:
must contain CMake preset files. must contain CMake preset files.
See :manual:`preset <cmake-presets(7)>` for more details. See :manual:`preset <cmake-presets(7)>` for more details.
.. versionchanged:: 3.31
When following immediately after the ``--workflow`` option,
the ``--preset`` argument can be omitted and just the ``<preset>``
name can be given. This means the following syntax is valid:
.. code-block:: console
$ cmake --workflow my-preset
.. option:: --list-presets .. option:: --list-presets
Lists the available workflow presets. The current working directory must Lists the available workflow presets. The current working directory must

@ -1560,6 +1560,10 @@ Configuration settings include:
* `CTest Script`_ variable: :variable:`CTEST_TLS_VERSION` * `CTest Script`_ variable: :variable:`CTEST_TLS_VERSION`
* :module:`CTest` module variable: ``CTEST_TLS_VERSION`` * :module:`CTest` module variable: ``CTEST_TLS_VERSION``
.. versionchanged:: 3.31
The default is TLS 1.2.
Previously, no minimum version was enforced by default.
``TLSVerify`` ``TLSVerify``
.. versionadded:: 3.30 .. versionadded:: 3.30
@ -1569,6 +1573,11 @@ Configuration settings include:
* `CTest Script`_ variable: :variable:`CTEST_TLS_VERIFY` * `CTest Script`_ variable: :variable:`CTEST_TLS_VERIFY`
* :module:`CTest` module variable: ``CTEST_TLS_VERIFY`` * :module:`CTest` module variable: ``CTEST_TLS_VERIFY``
.. versionchanged:: 3.31
The default is on. Previously, the default was off.
Users may set the :envvar:`CMAKE_TLS_VERIFY` environment
variable to ``0`` to restore the old default.
``TriggerSite`` ``TriggerSite``
Legacy option. Not used. Legacy option. Not used.

@ -1,16 +1,22 @@
{ {
"version": 6, "version": 10,
"cmakeMinimumRequired": { "cmakeMinimumRequired": {
"major": 3, "major": 3,
"minor": 23, "minor": 23,
"patch": 0 "patch": 0
}, },
"$comment": "An example CMakePresets.json file",
"include": [ "include": [
"otherThings.json", "otherThings.json",
"moreThings.json" "moreThings.json"
], ],
"configurePresets": [ "configurePresets": [
{ {
"$comment": [
"This is a comment row.",
"This is another comment,",
"just because we can do it"
],
"name": "default", "name": "default",
"displayName": "Default Config", "displayName": "Default Config",
"description": "Default build using Ninja generator", "description": "Default build using Ninja generator",

File diff suppressed because it is too large Load Diff

@ -0,0 +1,5 @@
``CMAKE_REQUIRED_LINK_DIRECTORIES``
.. versionadded:: 3.31
A :ref:`;-list <CMake Language Lists>` of libraries search paths to pass to
the linker (see :command:`try_compile` for further details).

@ -34,6 +34,11 @@ are de-duplicated by keeping their first occurrence, thus respecting the
project-specified order. This policy provides compatibility with projects project-specified order. This policy provides compatibility with projects
that have not been updated to expect the latter behavior. that have not been updated to expect the latter behavior.
.. note::
When this policy is set to ``NEW``, the policy :policy:`CMP0179` controls
which occurrence of the static libraries is kept when they are de-duplicated.
The ``OLD`` behavior for this policy is to always repeat static libraries The ``OLD`` behavior for this policy is to always repeat static libraries
as if using a traditional linker, and always de-duplicate shared libraries as if using a traditional linker, and always de-duplicate shared libraries
by keeping the last occurrence of each. The ``NEW`` behavior for this policy by keeping the last occurrence of each. The ``NEW`` behavior for this policy

@ -0,0 +1,26 @@
CMP0171
-------
.. versionadded:: 3.31
``codegen`` is a reserved target name.
CMake 3.30 and earlier did not reserve ``codegen`` as a builtin target name,
leaving projects free to create their own target with that name.
CMake 3.31 and later prefer to reserve ``codegen`` as a builtin target name
to drive custom commands created with the ``CODEGEN`` option to
:command:`add_custom_command`. In order to support building the ``codegen``
target in scripted environments, e.g., ``cmake --build . --target codegen``,
the ``codegen`` target needs to be generated even if no custom commands
use the ``CODEGEN`` option. This policy provides compatibility for projects
that have not been updated to avoid creating a target named ``codegen``.
The ``OLD`` behavior of this policy allows projects to create a target
with the name ``codegen``. The ``NEW`` behavior halts with a fatal error
if a target with the name ``codegen`` is created.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

@ -0,0 +1,39 @@
CMP0172
-------
.. versionadded:: 3.31
The :module:`CPack` module enables per-machine installation by default
in the :cpack_gen:`CPack WIX Generator`.
The :cpack_gen:`CPack WIX Generator`'s :variable:`CPACK_WIX_INSTALL_SCOPE`
option controls the scope of the generated Windows Installer package.
When :variable:`CPACK_WIX_VERSION` is set to 4 or higher, the default scope
is ``perMachine``. However, when using WIX 3 the default scope is ``NONE``,
and CPack does not set any ``InstallScope`` in the package specification.
The resulting installer requires administrative privileges and installs
into the system-wide ``ProgramFiles`` directory, but the start menu entry
and uninstaller registration are created only for the current user.
The :module:`CPack` module in CMake 3.30 and older does not specify any
:variable:`CPACK_WIX_INSTALL_SCOPE` value by default, so CPack uses no
installation scope by default with WIX 3. CMake 3.31 and newer instead
prefer to set :variable:`CPACK_WIX_INSTALL_SCOPE` to ``perMachine`` by
default to make the behavior consistent across all WIX versions. This
policy provides compatibility for projects that have not been updated
to expect ``perMachine`` behavior.
The ``OLD`` behavior for this policy is to not set
:variable:`CPACK_WIX_INSTALL_SCOPE` by default. The ``NEW`` behavior for
this policy is to set :variable:`CPACK_WIX_INSTALL_SCOPE` to ``perMachine``
by default.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn by default
.. include:: STANDARD_ADVICE.txt
See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0172 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.
.. include:: DEPRECATED.txt

@ -0,0 +1,22 @@
CMP0173
-------
.. versionadded:: 3.31
The :module:`CMakeFindFrameworks` module is removed.
CMake's framework handling has evolved well beyond what the
``CMakeFindFrameworks`` module supports. The module lacks any handling of
XCFrameworks, it never documented the one command it provides, and
:command:`find_library` provides superior capabilities in all respects.
The ``OLD`` behavior of this policy is for :module:`CMakeFindFrameworks` to
continue to provide the undocumented ``cmake_find_frameworks()`` command.
The ``NEW`` behavior halts with a fatal error if anything tries to include
the module.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

@ -0,0 +1,37 @@
CMP0174
-------
.. versionadded:: 3.31
:command:`cmake_parse_arguments(PARSE_ARGV)` defines a variable for an empty
string after a single-value keyword.
One of the main reasons for using the ``PARSE_ARGV`` form of the
:command:`cmake_parse_arguments` command is to more robustly handle corner
cases related to empty values. The non-``PARSE_ARGV`` form doesn't preserve
empty arguments, but the ``PARSE_ARGV`` form does. For each single-value
keyword given, a variable should be defined if the keyword is present, even
if it is followed by an empty string.
Prior to CMake 3.31, no variable would be defined if the value given after a
single-value keyword was an empty string. This meant the code could not detect
the difference between the keyword not being given, and it being given but with
an empty value, except by iterating over all the arguments and checking if the
keyword is present.
For the ``OLD`` behavior of this policy,
:command:`cmake_parse_arguments(PARSE_ARGV)` does not define a variable for a
single-value keyword followed by an empty string, or followed by no value at
all.
For the ``NEW`` behavior, :command:`cmake_parse_arguments(PARSE_ARGV)` always
defines a variable for each keyword given in the arguments, even a single-value
keyword with an empty string as its value or no value at all. With the
``NEW`` behavior, the code can robustly check if a single-value keyword was
given using just ``if(DEFINED <prefix>_<keyword>)``.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

@ -0,0 +1,40 @@
CMP0175
-------
.. versionadded:: 3.31
:command:`add_custom_command` rejects invalid arguments.
CMake 3.30 and earlier silently ignored unsupported keywords and missing or
invalid arguments for the different forms of the :command:`add_custom_command`
command. CMake 3.31 implements more rigorous argument checking and will flag
invalid or missing arguments as errors.
The ``OLD`` behavior of this policy will accept the same invalid keywords or
arguments as CMake 3.30 and earlier. The ``NEW`` behavior will flag the
following as errors that previously went unreported:
* The ``OUTPUT`` form does not accept ``PRE_BUILD``, ``PRE_LINK``, or
``POST_BUILD`` keywords.
* When the ``APPEND`` keyword is given, the ``OUTPUT`` form also does not
accept ``BYPRODUCTS``, ``COMMAND_EXPAND_LISTS``, ``DEPENDS_EXPLICIT_ONLY``,
``DEPFILE``, ``JOB_POOL``, ``JOB_SERVER_AWARE``, ``USES_TERMINAL``, or
``VERBATIM`` keywords.
* The ``TARGET`` form requires exactly one of ``PRE_BUILD``, ``PRE_LINK``, or
``POST_BUILD`` to be given. Previously, if none were given, ``POST_BUILD``
was assumed, or if multiple keywords were given, the last one was used.
* The ``TARGET`` form does not accept ``DEPENDS``, ``DEPENDS_EXPLICIT_ONLY``,
``DEPFILE``, ``IMPLICIT_DEPENDS``, ``MAIN_DEPENDENCY``, ``JOB_POOL``,
``JOB_SERVER_AWARE``, or ``USES_TERMINAL`` keywords.
* The ``TARGET`` form now requires at least one ``COMMAND`` to be given.
* If a keyword expects a value to be given after it, but no value is provided,
that was previously treated as though the keyword was not given at all.
* The ``COMMENT`` keyword expects exactly one value after it. If multiple
values are given, or if the ``COMMENT`` keyword is given more than once,
this is an error.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

@ -0,0 +1,27 @@
CMP0176
-------
.. versionadded:: 3.31
:command:`execute_process` ``ENCODING`` is ``UTF-8`` by default.
The ``ENCODING`` option is meaningful only on Windows. It specifies the
character encoding expected in the process's output on stdout and stderr.
In CMake 3.14 and below the default encoding was ``NONE``, which corresponds
to CMake's internal UTF-8 encoding. In CMake 3.15 through CMake 3.30 the
default encoding was accidentally changed to ``AUTO``, but the change went
unnoticed and was not documented.
CMake 3.31 and above prefer the ``ENCODING`` default to be ``UTF-8``.
This policy provides compatibility with projects that may have been
relying on the default being ``AUTO``.
The ``OLD`` behavior of this policy is for :command:`execute_process`
to use ``AUTO`` by default if no ``ENCODING`` is specified. The ``NEW``
behavior for this policy is to use ``UTF-8`` as the default ``ENCODING``.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

@ -0,0 +1,38 @@
CMP0177
-------
.. versionadded:: 3.31
:command:`install` ``DESTINATION`` paths are normalized.
The :command:`install` command has a number of different forms, and most of
them take a ``DESTINATION`` keyword, some in more than one place.
CMake 3.30 and earlier used the value given after the ``DESTINATION`` keyword
as provided with no transformations. The :command:`install(EXPORT)` form
assumes the path contains no ``..`` or ``.`` path components when computing
a path relative to the ``DESTINATION``, and if the project provided a path
that violated that assumption, the computed path would be incorrect.
CMake 3.31 normalizes all ``DESTINATION`` values given in any form of the
:command:`install` command, except for the ``INCLUDES DESTINATION`` of the
:command:`install(TARGETS)` form. The normalization performed is the same
as for the :command:`cmake_path` command (see :ref:`Normalization`).
The ``OLD`` behavior of this policy performs no translation on the
``DESTINATION`` values of any :command:`install` command. They are used
exactly as provided. If a destination path contains ``..`` or ``.`` path
components, :command:`install(EXPORT)` will use the same wrong paths as
CMake 3.30 and earlier.
The ``NEW`` behavior will normalize all ``DESTINATION`` values except for
``INCLUDES DESTINATION``. If a destination path contains a generator
expression, it will be wrapped in a ``$<PATH:CMAKE_PATH,NORMALIZE,...>``
generator expression.
This policy was introduced in CMake version 3.31.
It may be set by :command:`cmake_policy` or :command:`cmake_minimum_required`.
If it is not set, CMake will warn if it detects a path that would be different
if normalized, and uses ``OLD`` behavior. If a destination path contains a
generator expression, no such warning will be issued regardless of the value.
.. include:: DEPRECATED.txt

@ -0,0 +1,37 @@
CMP0178
-------
.. versionadded:: 3.31
Test command lines preserve empty arguments.
Empty values in the :prop_tgt:`TEST_LAUNCHER` and
:prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are now preserved
for tests added by the following:
* The :command:`add_test` command.
* The :command:`ExternalData_Add_Test` command from the :module:`ExternalData`
module.
* The :command:`gtest_add_tests` or :command:`gtest_discover_tests` commands
from the :module:`GoogleTest` module.
For the :command:`gtest_add_tests` and :command:`gtest_discover_tests`
commands, empty elements in the values passed after the ``EXTRA_ARGS``
keyword are also now preserved.
The ``OLD`` behavior of this policy silently discards empty list items
from the :prop_tgt:`TEST_LAUNCHER` and :prop_tgt:`CROSSCOMPILING_EMULATOR`
target properties in the above-mentioned cases. It also silently discards
empty items from the values given after ``EXTRA_ARGS`` for the
:command:`gtest_add_tests` and :command:`gtest_discover_tests` commands.
The ``NEW`` behavior of this policy preserves empty list items in the
:prop_tgt:`TEST_LAUNCHER` and :prop_tgt:`CROSSCOMPILING_EMULATOR` target
properties, and in values given after ``EXTRA_ARGS`` for
:command:`gtest_add_tests` and :command:`gtest_discover_tests`.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

@ -0,0 +1,28 @@
CMP0179
-------
.. versionadded:: 3.31
De-duplication of static libraries on link lines keeps first occurrence.
This policy is only relevant when policy :policy:`CMP0156` is set to ``NEW``.
Based on the linker capabilities, the static libraries can
be de-duplicated. See policy :policy:`CMP0156` for more information.
CMake 3.30 and below may choose to keep, on some platforms, the last occurrence
of the static libraries rather than the fist occurrence when they are
de-duplicated.
CMake 3.31 and above prefer to keep, on all platforms, the first occurrence of
the static libraries when they are de-duplicated.
The ``OLD`` behavior for this policy is to keep, on some platforms, the last
occurrence of the static libraries when they are de-duplicated. The ``NEW``
behavior for this policy is to keep the first occurrence of the static
libraries when they are de-duplicated, regardless of the platform.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

@ -0,0 +1,36 @@
CMP0180
-------
.. versionadded:: 3.31
:command:`project` always sets ``<PROJECT-NAME>_*`` as normal variables.
In CMake 3.29 and below, the :command:`project` command set
:variable:`<PROJECT-NAME>_SOURCE_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR`,
and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` as cache entries, but not as
normal variables. CMake 3.30 started setting them as normal variables,
but only if they are already set as normal variables. This was needed to
preserve support for some :module:`FetchContent` use cases under policy
:policy:`CMP0169`'s NEW behavior, while also preserving behavior of nested
directories that call :command:`project` with the same project name.
See release notes for 3.30.3, 3.30.4, and 3.30.5 for details.
CMake 3.31 and later prefer to always set ``<PROJECT-NAME>_SOURCE_DIR``,
``<PROJECT-NAME>_BINARY_DIR``, and ``<PROJECT-NAME>_IS_TOP_LEVEL``, as both
cache entries and normal variables, regardless of what cache or normal
variables already exist. This policy provides compatibility for projects
that have not been updated to expect this behavior.
The ``OLD`` behavior for this policy will only set normal variables for
``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and
``<PROJECT-NAME>_IS_TOP_LEVEL`` if there is already a normal variable by that
name when :command:`project` is called.
The ``NEW`` behavior for this policy will always set normal variables for
``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and
``<PROJECT-NAME>_IS_TOP_LEVEL`` when :command:`project` is called.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

@ -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. solution global section. Whitespace around key and value is ignored.
List elements which do not contain an equal sign are skipped. List elements which do not contain an equal sign are skipped.
This property only works for Visual Studio 12 and above; it is ignored This property only works for :ref:`Visual Studio Generators`; it is ignored
on other generators. The property only applies when set on a on other generators. The property only applies when set on a
directory whose ``CMakeLists.txt`` contains a :command:`project` command. directory whose ``CMakeLists.txt`` contains a :command:`project` command.

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

@ -3,18 +3,22 @@ INSTALL_PARALLEL
.. versionadded:: 3.30 .. versionadded:: 3.30
Enables parallel installation option for the Ninja generator. Enables parallel installation option for a project. The install code for each
subdirectory added with ``add_subdirectory`` can run independently.
When this property is ``ON``, ``install/local`` targets have the When using the Ninja generator, setting this property to ``ON``, causes
console pool disabled, allowing them to run concurrently. ``install/local`` targets have the console pool disabled, allowing them to run
concurrently.
This property also provides the target ``install/parallel``, which has an This property also provides the target ``install/parallel``, which has an
explicit dependency on the ``install/local`` target for each subdirectory, 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``. .. versionadded:: 3.31
The install must be invoked by building the ``install/parallel`` target
directly. When this property is ``ON``, ``cmake --install`` can be given the ``-j <jobs>``
or ``--parallel <jobs>`` option to specify a maximum number of jobs.
The :envvar:`CMAKE_INSTALL_PARALLEL_LEVEL` environment variable specifies a
default parallel level if this option is not provided.
Calls to :command:`install(CODE)` or :command:`install(SCRIPT)` might depend Calls to :command:`install(CODE)` or :command:`install(SCRIPT)` might depend
on actions performed by an earlier :command:`install` command in a different on actions performed by an earlier :command:`install` command in a different

@ -0,0 +1,20 @@
AIX_SHARED_LIBRARY_ARCHIVE
--------------------------
.. versionadded:: 3.31
On AIX, enable creation of a shared library archive. This places
the shared object ``.so`` file inside an archive ``.a`` file.
By default, CMake creates shared libraries on AIX as plain
shared object ``.so`` files for consistency with other UNIX platforms.
Alternatively, set this property to a true value to create a shared
library archive instead, as is AIX convention.
The shared object name in the archive encodes version information from
the :prop_tgt:`SOVERSION` target property, if set, and otherwise from
the :prop_tgt:`VERSION` target property, if set.
This property defaults to :variable:`CMAKE_AIX_SHARED_LIBRARY_ARCHIVE`
if that variable is set when a ``SHARED`` library target is created
by :command:`add_library`.

@ -7,5 +7,8 @@ The ``COMPILE_FLAGS`` property sets additional compiler flags used to
build sources within the target. Use :prop_tgt:`COMPILE_DEFINITIONS` build sources within the target. Use :prop_tgt:`COMPILE_DEFINITIONS`
to pass additional preprocessor definitions. to pass additional preprocessor definitions.
This property is deprecated. Use the :prop_tgt:`COMPILE_OPTIONS` .. note::
property or the :command:`target_compile_options` command instead.
This property has been superseded by the :prop_tgt:`COMPILE_OPTIONS` property.
Alternatively, you can also use the :command:`target_compile_options` command
instead.

@ -0,0 +1,15 @@
EXPORT_BUILD_DATABASE
---------------------
.. versionadded:: 3.31
Enable/Disable output of a build database for a target.
This property is initialized by the value of the variable
:variable:`CMAKE_EXPORT_BUILD_DATABASE` if it is set when a target is created.
.. note ::
This property is meaningful only when experimental support for build
databases has been enabled by the
``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.

@ -28,3 +28,8 @@ In advanced use cases, the list of direct link dependencies specified
by this property may be updated by usage requirements from dependencies. by this property may be updated by usage requirements from dependencies.
See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties. :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties.
See the :variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable and
corresponding :prop_tgt:`LINK_LIBRARIES_STRATEGY` target property
for details on how CMake orders direct link dependencies on linker
command lines.

@ -0,0 +1,87 @@
LINK_LIBRARIES_STRATEGY
-----------------------
.. versionadded:: 3.31
Specify a strategy for ordering a target's direct link dependencies
on linker command lines. This property is initialized by the value of the
:variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable if it is set when a
target is created.
CMake generates a target's link line using its :ref:`Target Link Properties`.
In particular, the :prop_tgt:`LINK_LIBRARIES` target property records the
target's direct link dependencies, typically populated by calls to
:command:`target_link_libraries`. Indirect link dependencies are
propagated from those entries of :prop_tgt:`LINK_LIBRARIES` that name
library targets by following the transitive closure of their
:prop_tgt:`INTERFACE_LINK_LIBRARIES` properties. CMake supports multiple
strategies for nominally ordering direct and indirect link dependencies,
which are then filtered for `Toolchain-Specific Behavior`_.
Consider this example for the strategies below:
.. code-block:: cmake
add_library(A STATIC ...)
add_library(B STATIC ...)
add_library(C STATIC ...)
add_executable(main ...)
target_link_libraries(B PRIVATE A)
target_link_libraries(C PRIVATE A)
target_link_libraries(main PRIVATE A B C)
The supported strategies are:
``REORDER_MINIMALLY``
Entries of :prop_tgt:`LINK_LIBRARIES` always appear first and in their
original order. Indirect link dependencies not satisfied by the
original entries may be reordered and de-duplicated with respect to
one another, but are always appended after the original entries.
This may result in less efficient link lines, but gives projects
control of ordering among independent entries. Such control may be
important when intermixing link flags with libraries, or when multiple
libraries provide a given symbol.
This is the default.
In the above example, this strategy computes a link line for ``main``
by starting with its original entries ``A B C``, and then appends
another ``A`` to satisfy the dependencies of ``B`` and ``C`` on ``A``.
The nominal order produced by this strategy is ``A B C A``.
Note that additional filtering for `Toolchain-Specific Behavior`_
may de-duplicate ``A`` on the actual linker invocation in the
generated build system, resulting in either ``A B C`` or ``B C A``.
``REORDER_FREELY``
Entries of :prop_tgt:`LINK_LIBRARIES` may be reordered, de-duplicated,
and intermixed with indirect link dependencies. This may result in
more efficient link lines, but does not give projects any control of
ordering among independent entries.
In the above example, this strategy computes a link line for ``main``
by re-ordering its original entries ``A B C`` to satisfy the
dependencies of ``B`` and ``C`` on ``A``.
The nominal order produced by this strategy is ``B C A``.
Toolchain-Specific Behavior
^^^^^^^^^^^^^^^^^^^^^^^^^^^
After one of the above strategies produces a nominal order among
direct and indirect link dependencies, the actual linker invocation
in the generated build system may de-duplicate entries based on
platform-specific requirements and linker capabilities.
See policy :policy:`CMP0156`.
For example, if the ``REORDER_MINIMALLY`` strategy produces ``A B C A``,
the actual link line may de-duplicate ``A`` as follows:
* If ``A`` is a static library and the linker re-scans automatically,
the first occurrence is kept, resulting in ``A B C``.
See policy :policy:`CMP0179`
* If ``A`` is a shared library on Windows, the first
occurrence is kept, resulting in ``A B C``.
* If ``A`` is a shared library on macOS or UNIX platforms, the last
occurrence is kept, resulting in ``B C A``.

@ -12,12 +12,20 @@ file name which may be a full path.
The following target properties may be set to specify content to be The following target properties may be set to specify content to be
configured into the file: configured into the file:
``MACOSX_FRAMEWORK_BUNDLE_NAME``
.. versionadded:: 3.31
Sets ``CFBundleName``.
``MACOSX_FRAMEWORK_BUNDLE_VERSION`` ``MACOSX_FRAMEWORK_BUNDLE_VERSION``
Sets ``CFBundleVersion``. Sets ``CFBundleVersion``.
``MACOSX_FRAMEWORK_ICON_FILE`` ``MACOSX_FRAMEWORK_ICON_FILE``
Sets ``CFBundleIconFile``. Sets ``CFBundleIconFile``.
``MACOSX_FRAMEWORK_IDENTIFIER`` ``MACOSX_FRAMEWORK_IDENTIFIER``
Sets ``CFBundleIdentifier``. Sets ``CFBundleIdentifier``.
``MACOSX_FRAMEWORK_SHORT_VERSION_STRING`` ``MACOSX_FRAMEWORK_SHORT_VERSION_STRING``
Sets ``CFBundleShortVersionString``. Sets ``CFBundleShortVersionString``.

@ -38,6 +38,9 @@ Unity builds are supported for the following languages:
``CXX`` ``CXX``
.. versionadded:: 3.16 .. versionadded:: 3.16
``CUDA``
.. versionadded:: 3.31
``OBJC`` ``OBJC``
.. versionadded:: 3.29 .. versionadded:: 3.29

@ -11,5 +11,5 @@ project file. This property is initialized by the value of the variable
:variable:`CMAKE_VS_DEBUGGER_COMMAND` if it is set when a target is :variable:`CMAKE_VS_DEBUGGER_COMMAND` if it is set when a target is
created. created.
This property only works for Visual Studio 12 2013 and above; This property only works for :ref:`Visual Studio Generators`;
it is ignored on other generators. it is ignored on other generators.

@ -11,5 +11,5 @@ project file. This property is initialized by the value of the variable
:variable:`CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS` if it is set when a target is :variable:`CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS` if it is set when a target is
created. created.
This property only works for Visual Studio 12 2013 and above; This property only works for :ref:`Visual Studio Generators`;
it is ignored on other generators. it is ignored on other generators.

@ -11,5 +11,5 @@ project file. This property is initialized by the value of the variable
:variable:`CMAKE_VS_DEBUGGER_ENVIRONMENT` if it is set when a target is :variable:`CMAKE_VS_DEBUGGER_ENVIRONMENT` if it is set when a target is
created. created.
This property only works for Visual Studio 12 2013 and above; This property only works for :ref:`Visual Studio Generators`;
it is ignored on other generators. it is ignored on other generators.

@ -11,5 +11,5 @@ project file. This property is initialized by the value of the variable
:variable:`CMAKE_VS_DEBUGGER_WORKING_DIRECTORY` if it is set when a target is :variable:`CMAKE_VS_DEBUGGER_WORKING_DIRECTORY` if it is set when a target is
created. created.
This property only works for Visual Studio 12 2013 and above; This property only works for :ref:`Visual Studio Generators`;
it is ignored on other generators. it is ignored on other generators.

@ -12,7 +12,7 @@ If the property is unset, Visual Studio uses the first matching
than one ``Main()`` method is available in the current project, the property than one ``Main()`` method is available in the current project, the property
becomes mandatory for building the project. becomes mandatory for building the project.
This property only works for Visual Studio 12 2013 and above; This property only works for :ref:`Visual Studio Generators`;
it is ignored on other generators. it is ignored on other generators.
.. code-block:: cmake .. code-block:: cmake

@ -0,0 +1,12 @@
VS_FRAMEWORK_REFERENCES
-----------------------
.. versionadded:: 3.31
Visual Studio framework references.
Specify a :ref:`semicolon-separated list <CMake Language Lists>` of framework references
to be added to a generated Visual Studio project. For example:
* "Microsoft.WindowsDesktop.App.WPF" for WPF applications
* "Microsoft.WindowsDesktop.App.WindowsForms" for WinForms applications
* "Microsoft.WindowsDesktop.App" for applications using both frameworks

@ -6,4 +6,4 @@ for the :generator:`Visual Studio 9 2008` generator, and older,
but all of those generators have been removed. but all of those generators have been removed.
Use the :prop_tgt:`VS_GLOBAL_KEYWORD` target property to set the Use the :prop_tgt:`VS_GLOBAL_KEYWORD` target property to set the
keyword for Visual Studio 12 (2013) and newer. keyword for remaining :ref:`Visual Studio Generators`.

@ -64,6 +64,10 @@ Commands
* The :command:`if` command gained new tests ``IS_READABLE``, ``IS_WRITABLE`` * The :command:`if` command gained new tests ``IS_READABLE``, ``IS_WRITABLE``
and ``IS_EXECUTABLE`` to check file or directory permissions. and ``IS_EXECUTABLE`` to check file or directory permissions.
* The :command:`try_compile` and :command:`try_run` commands gained a
``LINKER_LANGUAGE`` option to specify the :prop_tgt:`LINKER_LANGUAGE`
target property in the generated test project.
Variables Variables
--------- ---------

@ -0,0 +1,259 @@
CMake 3.31 Release Notes
************************
.. only:: html
.. contents::
Changes made since CMake 3.30 include the following.
New Features
============
Presets
-------
* :manual:`cmake-presets(7)` files may now include comments using the key
``$comment`` at any level within the JSON object to provide documentation.
* :manual:`cmake-presets(7)` files may now request graphviz output using
the ``graphviz`` key in a configure preset.
Generators
----------
* The :ref:`Ninja Generators` and :ref:`Makefile Generators` now produce
a ``codegen`` build target. See policy :policy:`CMP0171`. It drives a
subset of the build graph sufficient to run custom commands created with
:command:`add_custom_command`'s new ``CODEGEN`` option.
Command-Line
------------
* The :option:`cmake --workflow` mode now accepts a preset name as the first
argument, allowing the simpler command line
:option:`cmake --workflow \<preset\> <cmake--workflow --preset>`.
* The :option:`cmake -LR[A][H]` option was added to list cache entries
whose names match a regular expression.
Compilers
---------
* The LFortran compiler is now supported with
:variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``LFortran``.
Commands
--------
* The :command:`add_custom_command` command gained a ``CODEGEN`` option
to mark a custom command's outputs as dependencies of a ``codegen`` target.
See policy :policy:`CMP0171`.
* The :command:`cmake_pkg_config` command was added as an endpoint for using
CMake's native pkg-config format parser. The only supported option in this
release is ``EXTRACT``, which provides low-level access to the values
produced by parsing a pkg-config file. For most users, this is not yet a
suitable replacement for the :module:`FindPkgConfig` module.
* The :command:`file(ARCHIVE_CREATE)` command gained a ``WORKING_DIRECTORY``
option to specify a working directory for the archiving process.
* The :command:`file(MAKE_DIRECTORY)` command gained a ``RESULT`` option
to capture failure in a result variable.
* The :command:`install(FILES)` and :command:`install(DIRECTORY)` commands'
``TYPE`` argument gained support for a ``LIBEXEC`` type.
Variables
---------
* The :variable:`CMAKE_AIX_SHARED_LIBRARY_ARCHIVE` variable and corresponding
:prop_tgt:`AIX_SHARED_LIBRARY_ARCHIVE` target property were added to
create shared libraries on AIX as shared library archives.
* The :variable:`CMAKE_EXPORT_BUILD_DATABASE` variable, a corresponding
:envvar:`CMAKE_EXPORT_BUILD_DATABASE` environment variable, and an
:prop_tgt:`EXPORT_BUILD_DATABASE` target property, were added to
enable exporting C++ module compile commands.
This is only supported with :ref:`Ninja Generators`.
* The :variable:`CMAKE_HOST_EXECUTABLE_SUFFIX` variable was added to
provide the suffix for executable names on the host platform.
* The :variable:`CMAKE_<LANG>_HOST_COMPILER_ID` and
:variable:`CMAKE_<LANG>_HOST_COMPILER_VERSION` variables were added,
where ``<LANG>`` is either ``CUDA`` or ``HIP``. They are populated
when :variable:`CMAKE_<LANG>_COMPILER_ID` is ``NVIDIA`` to identify
NVCC's host compiler.
* The :variable:`CMAKE_<LANG>_STANDARD_LINK_DIRECTORIES` variable was added.
Toolchain files can set this variable to control which link library directory
paths are always passed to the compiler for the specified language.
* The :variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable and
corresponding :prop_tgt:`LINK_LIBRARIES_STRATEGY` target
property were added to optionally specify the strategy
CMake uses to generate link lines.
Properties
----------
* The :prop_tgt:`MACOSX_FRAMEWORK_BUNDLE_NAME <MACOSX_FRAMEWORK_INFO_PLIST>`
target property was added to set the ``CFBundleName`` key in an Apple
:prop_tgt:`FRAMEWORK`'s ``Info.plist`` file.
* The :prop_tgt:`UNITY_BUILD` target property now supports the
``CUDA`` language.
* The :prop_tgt:`VS_FRAMEWORK_REFERENCES` target property was added
to tell :ref:`Visual Studio Generators` to add framework references.
Modules
-------
* Check modules now support a ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
The following modules gained this support:
* :module:`CMakePushCheckState`
* :module:`CheckCCompilerFlag`
* :module:`CheckCSourceCompiles`
* :module:`CheckCSourceRuns`
* :module:`CheckCXXCompilerFlag`
* :module:`CheckCXXSourceCompiles`
* :module:`CheckCXXSourceRuns`
* :module:`CheckCXXSymbolExists`
* :module:`CheckCompilerFlag`
* :module:`CheckFortranCompilerFlag`
* :module:`CheckFortranFunctionExists`
* :module:`CheckFortranSourceCompiles`
* :module:`CheckFortranSourceRuns`
* :module:`CheckFunctionExists`
* :module:`CheckIncludeFile`
* :module:`CheckIncludeFileCXX`
* :module:`CheckIncludeFiles`
* :module:`CheckOBJCCompilerFlag`
* :module:`CheckLibraryExists`
* :module:`CheckOBJCCompilerFlag`
* :module:`CheckOBJCSourceCompiles`
* :module:`CheckOBJCSourceRuns`
* :module:`CheckOBJCXXCompilerFlag`
* :module:`CheckOBJCXXSourceCompiles`
* :module:`CheckOBJCXXSourceRuns`
* :module:`CheckPrototypeDefinition`
* :module:`CheckSourceCompiles`
* :module:`CheckSourceRuns`
* :module:`CheckStructHasMember`
* :module:`CheckSymbolExists`
* :module:`CheckTypeSize`
* :module:`CheckVariableExists`
* The :module:`CMakePackageConfigHelpers` module's
:command:`generate_apple_platform_selection_file` function
gained support for iOS Mac Catalyst.
* The :module:`GoogleTest` module :command:`gtest_discover_tests` command
gained a new ``DISCOVERY_EXTRA_ARGS`` keyword. It allows extra arguments
to be appended to the command line when querying for the list of tests.
* The :module:`FindCUDAToolkit` module now provides a ``CUDA::nvml_static``
target.
* The :module:`FindOpenMP` module gained support for the ``CUDA`` language.
CTest
-----
* The :command:`ctest_submit` command and :option:`ctest -T Submit <ctest -T>`
step now verify TLS server certificates for connections to ``https://`` URLs
by default. See the :variable:`CTEST_TLS_VERIFY` variable for details.
* The :command:`ctest_submit` command and :option:`ctest -T Submit <ctest -T>`
step now require TLS 1.2 or higher for connections to ``https://`` URLs by
default. See the :variable:`CTEST_TLS_VERSION` variable for details.
CPack
-----
* The :cpack_gen:`CPack DEB Generator` gained a
:variable:`CPACK_DEBIAN_PACKAGE_MULTIARCH` option
to support multi-arch packages.
* The :cpack_gen:`CPack IFW Generator` gained the new
:variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGE_URLS` variable to
specify images associated with entries of
:variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGES`.
This feature is available for QtIFW 4.0 and newer.
* The :cpack_gen:`CPack RPM Generator` gained support for ``zstd`` as a
:variable:`CPACK_RPM_COMPRESSION_TYPE` value.
* The :module:`CPack` module enables per-machine installation by default
in the :cpack_gen:`CPack WIX Generator`. See policy :policy:`CMP0172`
and the :variable:`CPACK_WIX_INSTALL_SCOPE` variable.
Deprecated and Removed Features
===============================
* Compatibility with versions of CMake older than 3.10 is now deprecated
and will be removed from a future version. Calls to
:command:`cmake_minimum_required` or :command:`cmake_policy` that set
the policy version to an older value now issue a deprecation diagnostic.
* The :module:`CMakeFindFrameworks` module has been deprecated via
:policy:`CMP0173`. Projects should use :command:`find_library` instead.
* The :generator:`Visual Studio 12 2013` generator has been removed.
Other Changes
=============
* When static libraries on link lines are de-duplicated (by policy
:policy:`CMP0156`), the first occurrence is now kept on all platforms.
See policy :policy:`CMP0179`.
* Empty list elements in the :prop_tgt:`TEST_LAUNCHER` and
:prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are now preserved by:
* The :command:`add_test` command.
* The :command:`ExternalData_Add_Test` command from the
:module:`ExternalData` module.
* The :command:`gtest_add_tests` and :command:`gtest_discover_tests`
commands from the :module:`GoogleTest` module.
Empty list elements after the ``EXTRA_ARGS`` keyword of these
two commands are also now preserved.
See policy :policy:`CMP0178`.
* The :command:`execute_process` command's ``ENCODING`` option,
meaningful on Windows, now defaults to ``UTF-8``.
See policy :policy:`CMP0176`.
* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands now
verify TLS server certificates for connections to ``https://`` URLs by
default. See the :variable:`CMAKE_TLS_VERIFY` variable for details.
This change was made without a policy so that users are protected
even when building projects that have not been updated.
Users may set the :envvar:`CMAKE_TLS_VERIFY` environment
variable to ``0`` to restore the old default.
* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands now
require TLS 1.2 or higher for connections to ``https://`` URLs by default.
See the :variable:`CMAKE_TLS_VERSION` variable for details.
* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command was updated
to more closely match the dynamic loader's behavior on Linux.
* The :command:`install` command's ``DESTINATION`` arguments are
now :ref:`normalized <Normalization>`, with the exception
of ``INCLUDES DESTINATION`` arguments in :command:`install(TARGETS)`.
See policy :policy:`CMP0177`.
* The :command:`project` command now always sets
:variable:`<PROJECT-NAME>_SOURCE_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR`,
and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` as both normal variables and
cache entries. See policy :policy:`CMP0180`.
* The :command:`cmake_parse_arguments(PARSE_ARGV)` command now defines a
variable for an empty string after a single-value keyword. See policy
:policy:`CMP0174`.

@ -13,6 +13,7 @@ Releases
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
3.31 <3.31>
3.30 <3.30> 3.30 <3.30>
3.29 <3.29> 3.29 <3.29>
3.28 <3.28> 3.28 <3.28>

@ -0,0 +1,10 @@
CMAKE_AIX_SHARED_LIBRARY_ARCHIVE
--------------------------------
.. versionadded:: 3.31
On AIX, enable creation of shared library archives.
This variable initializes the :prop_tgt:`AIX_SHARED_LIBRARY_ARCHIVE`
target property on ``SHARED`` library targets as they are created
by :command:`add_library`. See that target property for details.

@ -18,7 +18,7 @@ Example values:
:: ::
$(Configuration) = Visual Studio 12 and above $(Configuration) = Visual Studio
$(CONFIGURATION) = Xcode $(CONFIGURATION) = Xcode
. = Make-based tools . = Make-based tools
. = Ninja . = Ninja

@ -1,10 +1,14 @@
CMAKE_EXECUTABLE_SUFFIX CMAKE_EXECUTABLE_SUFFIX
----------------------- -----------------------
The suffix for executables on this platform. The suffix for executables on the target platform.
The suffix to use for the end of an executable filename if any, ``.exe`` The suffix to use for the end of an executable filename if any, ``.exe``
on Windows. on Windows.
:variable:`CMAKE_EXECUTABLE_SUFFIX_<LANG>` overrides this for :variable:`CMAKE_EXECUTABLE_SUFFIX_<LANG>` overrides this for
language ``<LANG>``. language ``<LANG>``.
See the :variable:`CMAKE_HOST_EXECUTABLE_SUFFIX` variable for the
executable suffix on the host platform.

@ -0,0 +1,86 @@
CMAKE_EXPORT_BUILD_DATABASE
---------------------------
.. versionadded:: 3.31
.. note ::
This variable is meaningful only when experimental support for build
databases has been enabled by the
``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.
Enable/Disable output of module compile commands during the build.
If enabled, generates a ``build_database.json`` file containing the
information necessary to compile a target's C++ module sources with any
tooling. The format of the JSON file looks like:
.. code-block:: javascript
{
"version": 1,
"revision": 0,
"sets": [
{
"family-name" : "export_build_database",
"name" : "export_build_database@Debug",
"translation-units" : [
{
"arguments": [
"/path/to/compiler",
"...",
],
"baseline-arguments" :
[
"...",
],
"local-arguments" :
[
"...",
],
"object": "CMakeFiles/target.dir/source.cxx.o",
"private": true,
"provides": {
"importable": "path/to/bmi"
},
"requires" : [],
"source": "path/to/source.cxx",
"work-directory": "/path/to/working/directory"
}
],
"visible-sets" : []
}
]
}
This is initialized by the :envvar:`CMAKE_EXPORT_BUILD_DATABASE` environment
variable, and initializes the :prop_tgt:`EXPORT_BUILD_DATABASE` target
property for all targets.
.. note::
This option is implemented only by the :ref:`Ninja Generators`. It is
ignored on other generators.
When supported and enabled, numerous targets are created in order to make it
possible to build a file containing just the commands that are needed for the
tool in question.
``cmake_build_database-<CONFIG>``
Writes ``build_database_<CONFIG>.json``. Writes a build database for the
entire build for the given configuration and all languages. Not available if
the configuration name is the empty string.
``cmake_build_database-<LANG>-<CONFIG>``
Writes ``build_database_<LANG>_<CONFIG>.json``. Writes build database for
the entire build for the given configuration and language. Not available if
the configuration name is the empty string.
``cmake_build_database-<LANG>``
Writes ``build_database_<LANG>.json``. Writes build database for the entire
build for the given language and all configurations. In a multi-config
generator, other build configuration database may be assumed to exist.
``cmake_build_database``
Writes to ``build_database.json``. Writes build database for all languages
and configurations. In a multi-config generator, other build configuration
database may be assumed to exist.

@ -3,23 +3,26 @@ CMAKE_FIND_PACKAGE_SORT_ORDER
.. versionadded:: 3.7 .. versionadded:: 3.7
The default order for sorting packages found using :command:`find_package`. The default order for sorting directories which match a search path containing
It can assume one of the following values: a glob expression found using :command:`find_package`. It can assume one of
the following values:
``NONE`` ``NONE``
Default. No attempt is done to sort packages. Default. No attempt is done to sort directories.
The first valid package found will be selected. The first valid package found will be selected.
``NAME`` ``NAME``
Sort packages lexicographically before selecting one. Sort directories lexicographically before searching.
``NATURAL`` ``NATURAL``
Sort packages using natural order (see ``strverscmp(3)`` manual), Sort directories using natural order (see ``strverscmp(3)`` manual),
i.e. such that contiguous digits are compared as whole numbers. i.e. such that contiguous digits are compared as whole numbers.
Natural sorting can be employed to return the highest version when multiple Natural sorting can be employed to return the highest version when multiple
versions of the same library are found by :command:`find_package`. For versions of the same library are available to be found by
example suppose that the following libraries have been found: :command:`find_package`. For example suppose that the following libraries
have package configuration files on disk, in a directory of the same name,
with all such directories residing in the same parent directory:
* libX-1.1.0 * libX-1.1.0
* libX-1.2.9 * libX-1.2.9
@ -35,4 +38,4 @@ version number ``libX-1.2.10``.
The sort direction can be controlled using the The sort direction can be controlled using the
:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable
(by default decrescent, e.g. lib-B will be tested before lib-A). (by default descending, e.g. lib-B will be tested before lib-A).

@ -3,7 +3,7 @@ CMAKE_FIND_PACKAGE_TARGETS_GLOBAL
.. versionadded:: 3.24 .. versionadded:: 3.24
Setting to ``TRUE`` promotes all :prop_tgt:`IMPORTED` targets discoverd Setting to ``TRUE`` promotes all :prop_tgt:`IMPORTED` targets discovered
by :command:`find_package` to a ``GLOBAL`` scope. by :command:`find_package` to a ``GLOBAL`` scope.

@ -0,0 +1,12 @@
CMAKE_HOST_EXECUTABLE_SUFFIX
----------------------------
.. versionadded:: 3.31
The suffix for executables on the host platform. This may differ from
the suffix for the target platform, :variable:`CMAKE_EXECUTABLE_SUFFIX`.
The suffix to use for the end of an executable filename if any, ``.exe``
on Windows.
See also :variable:`CMAKE_EXECUTABLE_SUFFIX`.

@ -32,6 +32,7 @@ Value Name
``Intel`` Intel Classic Compiler ``Intel`` Intel Classic Compiler
``IntelLLVM`` `Intel LLVM-Based Compiler`_ ``IntelLLVM`` `Intel LLVM-Based Compiler`_
``LCC`` MCST Elbrus C/C++/Fortran Compiler ``LCC`` MCST Elbrus C/C++/Fortran Compiler
``LFortran`` LFortran Fortran Compiler
``MSVC`` `Microsoft Visual Studio`_ ``MSVC`` `Microsoft Visual Studio`_
``NVHPC`` `NVIDIA HPC Compiler`_ ``NVHPC`` `NVIDIA HPC Compiler`_
``NVIDIA`` `NVIDIA CUDA Compiler`_ ``NVIDIA`` `NVIDIA CUDA Compiler`_
@ -40,7 +41,7 @@ Value Name
``PGI`` The Portland Group ``PGI`` The Portland Group
``PathScale`` PathScale ``PathScale`` PathScale
``SDCC`` `Small Device C Compiler`_ ``SDCC`` `Small Device C Compiler`_
``SunPro`` Oracle Solaris Studio ``SunPro`` Oracle Developer Studio
``Tasking`` `Tasking Compiler Toolsets`_ ``Tasking`` `Tasking Compiler Toolsets`_
``TI`` Texas Instruments ``TI`` Texas Instruments
``TIClang`` `Texas Instruments Clang-based Compilers`_ ``TIClang`` `Texas Instruments Clang-based Compilers`_

@ -0,0 +1,10 @@
CMAKE_<LANG>_CREATE_SHARED_LIBRARY_ARCHIVE
------------------------------------------
.. versionadded:: 3.31
Rule variable to create a shared library with archive.
This is a rule variable that tells CMake how to create a shared
library with an archive for the language <LANG>. This rule variable
is a ; delimited list of commands to run to perform the linking step.

@ -42,3 +42,8 @@ variable is read-only and changes to it are undefined behavior.
.. note:: .. note::
Ignored when using :ref:`Visual Studio Generators`. Ignored when using :ref:`Visual Studio Generators`.
See the :variable:`CMAKE_<LANG>_HOST_COMPILER_ID` and
:variable:`CMAKE_<LANG>_HOST_COMPILER_VERSION` variables for
information about the host compiler used by ``nvcc``, whether
by default or specified by ``CMAKE_<LANG>_HOST_COMPILER``.

@ -0,0 +1,10 @@
CMAKE_<LANG>_HOST_COMPILER_ID
-----------------------------
.. versionadded:: 3.31
This variable is available when ``<LANG>`` is ``CUDA`` or ``HIP``
and :variable:`CMAKE_<LANG>_COMPILER_ID` is ``NVIDIA``.
It contains the identity of the host compiler invoked by ``nvcc``,
either by default or as specified by :variable:`CMAKE_<LANG>_HOST_COMPILER`,
among possibilities documented by :variable:`CMAKE_<LANG>_COMPILER_ID`.

@ -0,0 +1,10 @@
CMAKE_<LANG>_HOST_COMPILER_VERSION
----------------------------------
.. versionadded:: 3.31
This variable is available when ``<LANG>`` is ``CUDA`` or ``HIP``
and :variable:`CMAKE_<LANG>_COMPILER_ID` is ``NVIDIA``.
It contains the version of the host compiler invoked by ``nvcc``,
either by default or as specified by :variable:`CMAKE_<LANG>_HOST_COMPILER`,
in the same format as :variable:`CMAKE_<LANG>_COMPILER_VERSION`.

@ -0,0 +1,14 @@
CMAKE_<LANG>_STANDARD_LINK_DIRECTORIES
--------------------------------------
.. versionadded:: 3.31
Link directories specified for every executable and library linked
for language ``<LANG>``. This is meant for specification of system
link directories needed by the language for the current platform.
This variable should not be set by project code. It is meant to be set by
CMake's platform information modules for the current toolchain, or by a
toolchain file when used with :variable:`CMAKE_TOOLCHAIN_FILE`.
See also :variable:`CMAKE_<LANG>_STANDARD_LIBRARIES`.

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

Loading…
Cancel
Save