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

New upstream version 3.31.0

Browse Source
This commit is contained in:
Timo Röhling 2024-11-11 15:18:55 +01:00
parent 167f7148a5
commit f5761cd947
2660 changed files with 54745 additions and 24119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
.clang-tidy
View File

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

36
Auxiliary/bash-completion/cmake
View File

@ -173,7 +173,9 @@ _cmake()
printf -v quoted %q "$cur"
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
return
;;
@ -182,12 +184,16 @@ _cmake()
local quoted
printf -v quoted %q "$cur"
local build_or_configure="configure"
if [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
build_or_configure="build"
local preset_type
if [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--workflow${IFS}" ]]; then
preset_type="workflow"
elif [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
preset_type="build"
else
preset_type="configure"
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 \
-e "s/^ //g" \
-e "s/\"//g" \
@ -195,6 +201,24 @@ _cmake()
COMPREPLY=( $( compgen -W "$presets" -- "$quoted" ) )
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
if ($is_old_completion || $is_init_completion); then
@ -204,6 +228,8 @@ _cmake()
fi
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 == *= ]] && compopt -o nospace
[[ $COMPREPLY ]] && return

2
Auxiliary/cmake-mode.el
View File

@ -183,7 +183,7 @@ set the path with these commands:
)
(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)
"Indent the current line to COLUMN.

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

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

4
CMakeLists.txt
View File

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

8
CONTRIBUTING.rst
View File

@ -26,7 +26,8 @@ To contribute patches:
#. Fork the upstream `CMake Repository`_ into a personal account.
#. Run `Utilities/SetupForDevelopment.sh`_ for local git configuration.
#. 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.
Base all new work on the upstream ``master`` branch.
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
.. _`Building CMake`: README.rst#building-cmake
.. _`CMake Source Code Guide`: Help/dev/source.rst
.. _`CMake Testing Guide`: Help/dev/testing.rst
.. _`commit messages`: Help/dev/review.rst#commit-messages
.. _`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
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 Testing Process`: Help/dev/testing.rst
.. _`CMake Integration Testing`: Help/dev/integration-testing.rst
License
=======

3
CTestCustom.cmake.in
View File

@ -86,7 +86,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"[0-9]+ Warning\\(s\\) detected" # SunPro
# Ignore false positive on `cm::optional` usage from GCC
"cmFileCommand.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& tls_verify \\+2\\)' may be used uninitialized in this function \\[-Wmaybe-uninitialized\\]"
"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]*: 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\\]"
@ -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: 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: 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: Dereference of null pointer"
"nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Value stored to '[^']+' is never read"

8
CompileFlags.cmake
View File

@ -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")
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(NOT CMAKE_COMPILER_IS_GNUCXX)
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -bhalt:5 ")

8
Help/command/DEPRECATED_POLICY_VERSIONS.txt
View File

@ -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
Compatibility with versions of CMake older than 3.5 is deprecated.

103
Help/command/add_custom_command.rst
View File

@ -5,6 +5,8 @@ Add a custom build rule to the generated build system.
There are two main signatures for ``add_custom_command``.
.. _`add_custom_command(OUTPUT)`:
Generating Files
^^^^^^^^^^^^^^^^
@ -26,6 +28,7 @@ The first signature is for adding a custom command to produce an output:
[JOB_POOL job_pool]
[JOB_SERVER_AWARE <bool>]
[VERBATIM] [APPEND] [USES_TERMINAL]
[CODEGEN]
[COMMAND_EXPAND_LISTS]
[DEPENDS_EXPLICIT_ONLY])
@ -53,7 +56,7 @@ The options are:
the appended commands and dependencies apply to all configurations.
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.
``BYPRODUCTS``
@ -81,6 +84,10 @@ The options are:
The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
: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
Arguments to ``BYPRODUCTS`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`.
@ -94,11 +101,15 @@ The options are:
``COMMAND``
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.
(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
a ``COMMAND`` to launch it.)
a ``COMMAND`` to launch it.
The optional ``ARGS`` argument is for backward compatibility and
will be ignored.
@ -143,7 +154,8 @@ The options are:
``COMMENT``
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
Arguments to ``COMMENT`` may use
@ -203,6 +215,26 @@ The options are:
``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
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``
Request scanning of implicit dependencies of an input file.
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
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``
.. versionadded:: 3.28
@ -238,6 +274,10 @@ The options are:
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
``MAIN_DEPENDENCY``
@ -249,6 +289,9 @@ The options are:
library or an executable) counts as an implicit main dependency which
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``
Specify the output files the command is expected to produce.
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
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``
All arguments to the commands will be escaped properly for the
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
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``
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.
This option is currently ignored if ``APPEND`` is given, but a future
version may use it.
.. versionadded:: 3.13
Arguments to ``WORKING_DIRECTORY`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
@ -393,6 +447,10 @@ The options are:
:ref:`Makefile Generators`, :ref:`Visual Studio Generators`,
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``
.. versionadded:: 3.27
@ -408,6 +466,10 @@ The options are:
This option can be enabled on all custom commands by setting
: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
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
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
""""""""""""""""""""""""""""""""""""""""""""""
@ -543,15 +624,17 @@ of the following is specified:
Run after all other rules within the target have been executed.
Projects should always specify one of the above three keywords when using
the ``TARGET`` form. For backward compatibility reasons, ``POST_BUILD`` is
assumed if no such keyword is given, but projects should explicitly provide
one of the keywords to make clear the behavior they expect.
the ``TARGET`` form. See policy :policy:`CMP0175`.
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::
Because generator expressions can be used in custom commands,
it is possible to define ``COMMAND`` lines or whole custom commands
which evaluate to empty strings for certain configurations.
For **Visual Studio 12 2013 (and newer)** generators these command
For :ref:`Visual Studio Generators` these command
lines or custom commands will be omitted for the specific
configuration and no "empty-string-command" will be added.

155
Help/command/cmake_parse_arguments.rst
View File

@ -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
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`.
.. versionadded:: 3.7
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
the ``<N>``-th argument, where ``<N>`` is an unsigned integer.
This allows for the values to have special characters like ``;`` in them.
The ``<options>`` argument contains all options for the respective macro,
i.e. keywords which can be used when calling the macro without any value
following, like e.g. the ``OPTIONAL`` keyword of the :command:`install`
command.
The ``<options>`` argument contains all options for the respective function
or macro. These are keywords that have no value following them, like the
``OPTIONAL`` keyword of the :command:`install` command.
The ``<one_value_keywords>`` argument contains all keywords for this macro
which are followed by one value, like e.g. ``DESTINATION`` keyword of the
:command:`install` command.
The ``<one_value_keywords>`` argument contains all keywords for this function
or macro which are followed by one value, like the ``DESTINATION`` keyword of
the :command:`install` command.
The ``<multi_value_keywords>`` argument contains all keywords for this
macro which can be followed by more than one value, like e.g. the
function or macro which can be followed by more than one value, like the
``TARGETS`` or ``FILES`` keywords of the :command:`install` command.
.. versionchanged:: 3.5
All keywords shall be unique. I.e. every keyword shall only be specified
once in either ``<options>``, ``<one_value_keywords>`` or
All keywords must be unique. Each keyword can only be specified
once in any of the ``<options>``, ``<one_value_keywords>``, or
``<multi_value_keywords>``. A warning will be emitted if uniqueness is
violated.
When done, ``cmake_parse_arguments`` will consider for each of the
keywords listed in ``<options>``, ``<one_value_keywords>`` and
``<multi_value_keywords>`` a variable composed of the given ``<prefix>``
followed by ``"_"`` and the name of the respective keyword. These
variables will then hold the respective value from the argument list
or be undefined if the associated option could not be found.
For the ``<options>`` keywords, these will always be defined,
to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not.
keywords listed in ``<options>``, ``<one_value_keywords>``, and
``<multi_value_keywords>``, a variable composed of the given ``<prefix>``
followed by ``"_"`` and the name of the respective keyword. For
``<one_value_keywords>`` and ``<multi_value_keywords>``, these variables
will then hold the respective value(s) from the argument list, or be undefined
if the associated keyword was not given (policy :policy:`CMP0174` can also
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
``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments
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
``<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
any values given.
Consider the following example macro, ``my_install()``, which takes similar
arguments to the real :command:`install` command:
.. versionchanged:: 3.31
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
@ -79,40 +119,63 @@ arguments to the real :command:`install` command:
set(options OPTIONAL FAST)
set(oneValueArgs DESTINATION RENAME)
set(multiValueArgs TARGETS CONFIGURATIONS)
cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
"${multiValueArgs}" ${ARGN} )
cmake_parse_arguments(arg_my_install
"${options}" "${oneValueArgs}" "${multiValueArgs}"
${ARGN}
)
# ...
endmacro()
Assume ``my_install()`` has been called like this:
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()
Suppose the above macros are called one after the other, like so:
.. code-block:: cmake
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
MY_INSTALL_DESTINATION = "bin"
MY_INSTALL_RENAME <UNDEFINED> # was not used
MY_INSTALL_TARGETS = "foo;bar"
MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
# No value for "CONFIGURATIONS" given
arg_my_install_OPTIONAL = TRUE
arg_my_install_FAST = FALSE # was not present in call to my_install
arg_my_install_DESTINATION = "bin"
arg_my_install_RENAME <UNSET> # was not present
arg_my_install_TARGETS = "foo;bar"
arg_my_install_CONFIGURATIONS <UNSET> # was not present
arg_my_install_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
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
arg_my_special_install_DESTINATION = "sbin"
arg_my_special_install_RENAME <UNSET> # value was missing
arg_my_special_install_TARGETS = "barry"
arg_my_special_install_CONFIGURATIONS <UNSET> # was not present
arg_my_special_install_UNPARSED_ARGUMENTS <UNSET>
arg_my_special_install_KEYWORDS_MISSING_VALUES = "RENAME"
Keywords terminate lists of values, e.g. if directly after a
``one_value_keyword`` another recognized keyword follows, this is
interpreted as the beginning of the new option. E.g.
``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in
``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL``
is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added
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
^^^^^^^^

263
Help/command/cmake_pkg_config.rst Normal file
View File

@ -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.

22
Help/command/execute_process.rst
View File

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

131
Help/command/file.rst
View File

@ -400,10 +400,19 @@ Filesystem
============== ======================================================
.. signature::
file(MAKE_DIRECTORY <directories>...)
file(MAKE_DIRECTORY <directories>... [RESULT <result>])
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
``<directories>`` can be an empty list. CMake 3.29 and earlier required
at least one directory to be given.
@ -802,10 +811,21 @@ Transfer
environment variable will be used instead.
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>``
Specify whether to verify the server certificate for ``https://`` URLs.
The default is to *not* verify. If this option is not specified, the
value of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead.
If this option is not specified, the value of the
: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
Added support to ``file(UPLOAD)``.
@ -818,9 +838,7 @@ Transfer
.. versionadded:: 3.18
Added support to ``file(UPLOAD)``.
For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL``
certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to
check certificates.
For ``https://`` URLs CMake must be built with SSL/TLS support.
Additional options to ``DOWNLOAD`` are:
@ -892,8 +910,9 @@ Archiving
PATHS <paths>...
[FORMAT <format>]
[COMPRESSION <compression>
[COMPRESSION_LEVEL <compression-level>]]
[COMPRESSION_LEVEL <compression-level>]]
[MTIME <mtime>]
[WORKING_DIRECTORY <dir>]
[VERBOSE])
:target: ARCHIVE_CREATE
:break: verbatim
@ -904,40 +923,55 @@ Archiving
listed in ``<paths>``. Note that ``<paths>`` must list actual files or
directories; wildcards are not supported.
Use the ``FORMAT`` option to 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``.
The options are:
Some archive formats allow the type of compression to be specified.
The ``7zip`` and ``zip`` archive formats already imply a specific type of
compression. The other formats use no compression by default, but can be
directed to do so with the ``COMPRESSION`` option. Valid values for
``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
``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.
The ``7zip`` and ``zip`` archive formats already imply a specific type of
compression. The other formats use no compression by default, but can be
directed to do so with the ``COMPRESSION`` option. Valid values for
``<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``
option. The ``<compression-level>`` should be between 0-9, with the
default being 0. The ``COMPRESSION`` option must be present when
``COMPRESSION_LEVEL`` is given.
.. versionadded:: 3.26
The ``<compression-level>`` of the ``Zstd`` algorithm can be set
between 0-19.
.. versionadded:: 3.26
The ``<compression-level>`` of the ``Zstd`` algorithm can be set
between 0-19.
.. note::
With ``FORMAT`` set to ``raw``, only one file will be compressed with the
compression type specified by ``COMPRESSION``.
``MTIME <mtime>``
Specify the modification time recorded in tarball entries.
The ``VERBOSE`` option enables verbose output for the archive operation.
``WORKING_DIRECTORY <dir>``
.. versionadded:: 3.31
To specify the modification time recorded in tarball entries, use
the ``MTIME`` option.
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.
``VERBOSE``
Enable verbose output from the archive operation.
.. signature::
file(ARCHIVE_EXTRACT
INPUT <archive>
[DESTINATION <dir>]
[PATTERNS <patterns>...]
[PATTERNS <pattern>...]
[LIST_ONLY]
[VERBOSE]
[TOUCH])
@ -947,17 +981,30 @@ Archiving
Extracts or lists the content of the specified ``<archive>``.
The directory where the content of the archive will be extracted to can
be specified using the ``DESTINATION`` option. If the directory does not
exist, it will be created. If ``DESTINATION`` is not given, the current
binary directory will be used.
The options are:
If required, you may select which files and directories to list or extract
from the archive using the specified ``<patterns>``. Wildcards are
supported. If the ``PATTERNS`` option is not given, the entire archive will
be listed or extracted.
``DESTINATION <dir>``
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.
``LIST_ONLY`` will list the files in the archive rather than extract them.
``PATTERNS <pattern>...``
Extract/list only files and directories that match one of the given
patterns. Wildcards are supported. If the ``PATTERNS`` option is
not given, the entire archive will be listed or extracted.
``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::
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
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
^^^^^^^^^^^^^^^^^^^^^^^^^
@ -1162,6 +1203,14 @@ Handling Runtime Binaries
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:
1. DLL dependency names are converted to lowercase for matching filters.

52
Help/command/find_package.rst
View File

@ -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
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
Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable
various search locations.
@ -648,22 +684,6 @@ is acceptable the following variables are set:
Number of version components, 0 to 4
and the corresponding package configuration file is loaded.
When multiple package configuration files are available whose version files
claim compatibility with the version requested it is unspecified which
one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
is set no attempt is made to choose a highest or closest version number.
To control the order in which ``find_package`` checks for compatibility use
the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
For instance in order to select the highest version one can set
.. code-block:: cmake
SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
before calling ``find_package``.
Package File Interface Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

20
Help/command/find_program.rst
View File

@ -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
for it. The ``NAMES_PER_DIR`` option tells this command to consider one
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})

27
Help/command/get_property.rst
View File

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

10
Help/command/if.rst
View File

@ -41,13 +41,15 @@ Compound conditions are evaluated in the following order of precedence:
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`_,
`GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_,
`STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_,
`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`_.
@ -471,6 +473,10 @@ above-documented condition syntax accepts ``<variable|string>``:
variables. If so, their defined values are used otherwise the original value
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
constant. If so, the value is used, otherwise it is assumed to be a
variable and it is dereferenced.

9
Help/command/include_external_msproject.rst
View File

@ -1,7 +1,8 @@
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
@ -11,9 +12,9 @@ Include an external Microsoft project file in a workspace.
[PLATFORM platformName]
dep1 dep2 ...)
Includes an external Microsoft project in the generated workspace
file. Currently does nothing on UNIX. This will create a target
named ``[projectname]``. This can be used in the :command:`add_dependencies`
Includes an external Microsoft project in the generated solution file.
This will create a target named ``[projectname]``.
This can be used in the :command:`add_dependencies`
command to make things depend on the external project.
``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to

97
Help/command/install.rst
View File

@ -19,6 +19,7 @@ Synopsis
install(`SCRIPT`_ <file> [...])
install(`CODE`_ <code> [...])
install(`EXPORT`_ <export-name> [...])
install(`PACKAGE_INFO`_ <package-name> [...])
install(`RUNTIME_DEPENDENCY_SET`_ <set-name> [...])
Introduction
@ -38,6 +39,13 @@ are executed in order during installation.
The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
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`:
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,
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.
The prefix can be relocated at install time using the ``DESTDIR``
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
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>...``
Specify permissions for installed files. Valid permissions are
``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
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``
Specify that it is not an error if the file to be installed does
not exist.
@ -393,6 +401,12 @@ Signatures
If a relative path is specified, it is treated as relative to the
: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>``
.. versionadded:: 3.21
@ -536,6 +550,10 @@ Signatures
However, if any item begins in a generator expression it must evaluate
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.
A ``TYPE`` argument specifies the generic file type of the files being
installed. A destination will then be set automatically by taking the
@ -561,6 +579,7 @@ Signatures
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc``
``LIBEXEC`` ``${CMAKE_INSTALL_LIBEXECDIR}`` ``libexec``
======================= ================================== =========================
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
:manual:`cmake-generator-expressions(7)` manual for available expressions.
.. versionadded:: 3.31
The ``TYPE`` argument now supports type ``LIBEXEC``.
.. signature::
install(DIRECTORY <dir>... [...])
@ -713,6 +735,7 @@ Signatures
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
``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
@ -736,6 +759,9 @@ Signatures
The list of ``dirs...`` given to ``DIRECTORY`` may use
"generator expressions" too.
.. versionadded:: 3.31
The ``TYPE`` argument now supports type ``LIBEXEC``.
.. signature::
install(SCRIPT <file> [...])
install(CODE <code> [...])
@ -800,6 +826,7 @@ Signatures
the generated file will be called ``<export-name>.cmake`` but the ``FILE``
option may be used to specify a different name. The value given to
the ``FILE`` option must be a file name with the ``.cmake`` extension.
If a ``CONFIGURATIONS`` option is given then the file will only be installed
when one of the named configurations is installed. Additionally, the
generated import file will reference only the matching target
@ -898,6 +925,61 @@ Signatures
executable from the installation tree using the imported target name
``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::
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
to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for
details.
.. _CPS: https://cps-org.github.io/cps/
.. |CPS| replace:: Common Package Specification

29
Help/command/project.rst
View File

@ -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
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>_IS_TOP_LEVEL`` are always set as non-cache variables by
``project(<PROJECT-NAME> ...)``.
``<PROJECT-NAME>_IS_TOP_LEVEL``, if already set as normal variables when
``project(<PROJECT-NAME> ...)`` is called, are updated by the call.
Cache entries by the same names are always set as before.
See release notes for 3.30.3, 3.30.4, and 3.30.5 for details.
.. versionchanged:: 3.30.4
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 cache or non-cache variables when
``project(<PROJECT-NAME> ...)`` is called.
Note that this logic is flawed, as it can result in different behavior
between the first and subsequent runs because cache variables won't exist
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.
.. versionchanged:: 3.31
``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and
``<PROJECT-NAME>_IS_TOP_LEVEL`` are always set as normal variables by
``project(<PROJECT-NAME> ...)``. See policy :policy:`CMP0180`.
Cache entries by the same names are always set as before.
Options
^^^^^^^

5
Help/command/target_link_libraries.rst
View File

@ -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.
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
buildsystem properties.

8
Help/cpack_gen/archive.rst
View File

@ -91,14 +91,10 @@ CPack generators which are essentially archives at their core. These include:
.. 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.
The default is ``1`` which limits compression to a single thread. Note that
not all compression modes support threading in all environments. Currently,
only the XZ compression may support it.
See also the :variable:`CPACK_THREADS` variable.
Note that not all compression modes support threading in all environments.
.. versionadded:: 3.21

36
Help/cpack_gen/deb.rst
View File

@ -182,11 +182,22 @@ List of CPack DEB generator specific variables:
only the automatically discovered dependencies will be set for this
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:
.. code-block:: cmake
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
@ -654,6 +665,31 @@ List of CPack DEB generator specific variables:
This value is not interpreted. It is possible to pass an optional
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

10
Help/cpack_gen/ifw.rst
View File

@ -275,6 +275,16 @@ Package
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
.. versionadded:: 3.23

10
Help/cpack_gen/rpm.rst
View File

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

8
Help/cpack_gen/wix.rst
View File

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

7
Help/dev/README.rst
View File

@ -23,12 +23,13 @@ branches and tags. Upstream development processes are covered by the
following documents:
* 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
.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
.. _`CMake Review Process`: review.rst
.. _`CMake Testing Process`: testing.rst
.. _`CMake Integration Testing`: integration-testing.rst
Developer Documentation
=======================
@ -37,10 +38,12 @@ CMake developer documentation is provided by the following documents:
* The `CMake Source Code Guide`_.
* The `CMake Documentation Guide`_.
* The `CMake Testing Guide`_.
* The `CMake Experimental Features Guide`_.
.. _`CMake Source Code Guide`: source.rst
.. _`CMake Documentation Guide`: documentation.rst
.. _`CMake Testing Guide`: testing.rst
.. _`CMake Experimental Features Guide`: experimental.rst
Maintainer Documentation

18
Help/dev/documentation.rst
View File

@ -310,17 +310,17 @@ are suppressed inside of square- or angle-brackets. This behavior can be
controlled using the ``:break:`` option; note, however, that there is no way
to *force* a line break. The default value is 'smart'. Allowable values are:
``all``
Allow line breaks at any whitespace.
``all``
Allow line breaks at any whitespace.
``smart`` (default)
Allow line breaks at whitespace, except between matched square- or
angle-brackets. For example, if a signature contains the text
``<input>... [OUTPUT_VARIABLE <out-var>]``, a line break would be allowed
after ``<input>...`` but not between ``OUTPUT_VARIABLE`` and ``<out-var>``.
``smart`` (default)
Allow line breaks at whitespace, except between matched square- or
angle-brackets. For example, if a signature contains the text
``<input>... [OUTPUT_VARIABLE <out-var>]``, a line break would be allowed
after ``<input>...`` but not between ``OUTPUT_VARIABLE`` and ``<out-var>``.
``verbatim``
Allow line breaks only where the source document contains a newline.
``verbatim``
Allow line breaks only where the source document contains a newline.
The directive treats its content as the documentation of the signature(s).
Indent the signature documentation accordingly.

41
Help/dev/experimental.rst
View File

@ -39,6 +39,23 @@ When activated, this experimental feature provides the following:
using the ``CMAKE_EXPORT_FIND_PACKAGE_NAME`` variable and/or
``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
==========================
@ -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``
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.

46
Help/dev/integration-testing.rst Normal file
View File

@ -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.

15
Help/dev/maint.rst
View File

@ -306,11 +306,22 @@ Commit with a message such as::
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
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
-------------------------

4
Help/dev/review.rst
View File

@ -348,7 +348,7 @@ Integration Testing
The above `topic testing`_ tests the MR topic independent of other
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
supported platforms, generators, and configurations. In order to
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``
command is needed to stage it again.
.. _`CMake Testing Process`: testing.rst
.. _`CMake Integration Testing`: integration-testing.rst
Resolve
=======

10
Help/dev/source.rst
View File

@ -249,6 +249,14 @@ These are:
* ``cm::is_unique_ptr``:
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
hand-written header files.
@ -310,6 +318,7 @@ The CMake source tree is organized as follows.
* ``Tests/``:
The test suite. See `Tests/README.rst`_.
To run the tests, see the `CMake Testing Guide`_.
* ``Utilities/``:
Scripts, third-party source code.
@ -331,5 +340,6 @@ The CMake source tree is organized as follows.
See `Utilities/Release/README.rst`_.
.. _`CMake Documentation Guide`: documentation.rst
.. _`CMake Testing Guide`: testing.rst
.. _`Tests/README.rst`: ../../Tests/README.rst
.. _`Utilities/Release/README.rst`: ../../Utilities/Release/README.rst

126
Help/dev/testing.rst
View File

@ -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 `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 Integration Testing`: integration-testing.rst
.. _`Tests/README.rst`: ../../Tests/README.rst
CMake Dashboard Scripts
=======================
Running Tests in the Build Tree
===============================
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.
After `Building CMake`_, one may run the test suite in the build tree
using `ctest(1)`_:
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:
* 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.
``-j <N>``
Run to run up to ``N`` tests concurrently.
``-R <regex>``
Select tests for which the regular expression matches a substring
of their name.
Cleaning Test Build Trees
-------------------------
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
$ mkdir -p ~/Dashboards
$ cd ~/Dashboards
$ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts
$ cd CMakeScripts
$ cmake --build . --target test_clean
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``.
This removes the ``Tests/`` subdirectories created by individual tests
so they will use a fresh directory next time they run.
.. _`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
.. _`Building CMake`: ../../README.rst#building-cmake
.. _`ctest(1)`: https://cmake.org/cmake/help/latest/manual/ctest.1.html
.. _`RunCMake`: ../../Tests/RunCMake/README.rst
Nightly Start Time
------------------
Running Tests with a Different Generator
========================================
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.
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 -B build-ninja -G Ninja -DCMAKE_BUILD_TYPE=Debug
$ cmake --build build-ninja
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
$ cd build-nmc-tests
$ ctest -C Release
Note that the configuration with which one drives tests in the second
build tree is independent of the configuration with which CMake was
built in the first.

6
Help/dev/try_compile-linker-language.rst
View File

@ -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.

18
Help/envvar/CMAKE_CONFIG_DIR.rst Normal file
View File

@ -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``

17
Help/envvar/CMAKE_EXPORT_BUILD_DATABASE.rst Normal file
View File

@ -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.

11
Help/envvar/CMAKE_INSTALL_PARALLEL_LEVEL.rst Normal file
View File

@ -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.

2
Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst
View File

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

59
Help/generator/Visual Studio 12 2013.rst
View File

@ -1,57 +1,8 @@
Visual Studio 12 2013
---------------------
Deprecated. Generates Visual Studio 12 (VS 2013) project files.
.. note::
This generator is deprecated and will be removed in a future version
of CMake. It will still be possible to build with VS 12 2013 tools
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
Removed. This once generated Visual Studio 12 2013 project files, but
the generator has been removed since CMake 3.31. It is still possible
to build with VS 12 2013 tools 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.

2
Help/guide/user-interaction/index.rst
View File

@ -300,6 +300,8 @@ the table below:
commands used without a type
:variable:`CMAKE_EXPORT_COMPILE_COMMANDS` Generate a ``compile_commands.json``
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

1
Help/manual/cmake-commands.7.rst
View File

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

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

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

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

@ -50,6 +50,10 @@ It has the following subdirectories:
Clients may optionally create the ``reply/`` directory at any time
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
-------------------------------

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

@ -1877,6 +1877,14 @@ These expressions look up the values of
rather than the directory of the consuming target for which the
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>
:target: TARGET_PROPERTY:prop

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

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

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

@ -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
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
=================================

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

@ -39,6 +39,9 @@ The files are a JSON document with an object as the root:
.. literalinclude:: presets/example.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:
``$schema``
@ -81,6 +84,9 @@ The root object recognizes the following fields:
``9``
.. versionadded:: 3.30
``10``
.. versionadded:: 3.31
``cmakeMinimumRequired``
An optional object representing the minimum version of CMake needed to
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
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``
An optional string representing the path to the output binary directory.
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
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
environment. This field supports `macro expansion`_, and 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 ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
environment.
This field supports `macro expansion`_, and 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 ``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
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
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
environment. This field supports macro expansion, and 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
``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
environment.
This field supports `macro expansion`_, and 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 ``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
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
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
environment. This field supports macro expansion, and 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
``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
environment.
This field supports `macro expansion`_, and 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 ``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
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
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
environment. This field supports macro expansion, and 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
``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
environment.
This field supports `macro expansion`_, and 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 ``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
the preset's environment will be the union of its own ``environment``
@ -1264,7 +1296,7 @@ Recognized macros include:
``$penv{<variable-name>}``
Similar to ``$env{<variable-name>}``, except that the value only comes from
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
prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This
is needed because ``$env{<variable-name>}`` does not allow circular

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

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

16
Help/manual/cmake-toolchains.7.rst
View File

@ -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).
A list of available SDKs can be obtained by running ``xcodebuild -showsdks``.
======== ================= ==================== ================
OS CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK
======== ================= ==================== ================
iOS iOS iphoneos iphonesimulator
tvOS tvOS appletvos appletvsimulator
visionOS visionOS xros xrsimulator
watchOS watchOS watchos watchsimulator
======== ================= ==================== ================
======== ================= ==================== ================ ============
OS CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK Catalyst SDK
======== ================= ==================== ================ ============
iOS iOS iphoneos iphonesimulator macosx
tvOS tvOS appletvos appletvsimulator N/A
visionOS visionOS xros xrsimulator N/A
watchOS watchOS watchos watchsimulator N/A
======== ================= ==================== ================ ============
For example, to create a CMake configuration for iOS, the following
command is sufficient:

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

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

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

@ -31,7 +31,7 @@ Synopsis
cmake --find-package [<options>]
`Run a Workflow Preset`_
cmake --workflow [<options>]
cmake --workflow <options>
`View Help`_
cmake --help[-<topic>]
@ -232,6 +232,17 @@ Options
will display also advanced variables. If ``H`` is specified, it will also
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
View mode only.
@ -255,8 +266,18 @@ Options
from the top of a binary tree for a CMake project it will dump
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>
.. versionadded:: 3.16
Set the log ``<level>``.
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.
.. 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.
Open a Project
@ -1364,7 +1394,7 @@ build steps in order:
.. code-block:: shell
cmake --workflow [<options>]
cmake --workflow <options>
The options are:
@ -1381,6 +1411,15 @@ The options are:
must contain CMake preset files.
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
Lists the available workflow presets. The current working directory must

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

@ -1560,6 +1560,10 @@ Configuration settings include:
* `CTest Script`_ variable: :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``
.. versionadded:: 3.30
@ -1569,6 +1573,11 @@ Configuration settings include:
* `CTest Script`_ variable: :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``
Legacy option. Not used.

8
Help/manual/presets/example.json
View File

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

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

File diff suppressed because it is too large Load Diff

5
Help/module/CMAKE_REQUIRED_LINK_DIRECTORIES.txt Normal file
View File

@ -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).

5
Help/policy/CMP0156.rst
View File

@ -34,6 +34,11 @@ are de-duplicated by keeping their first occurrence, thus respecting the
project-specified order. This policy provides compatibility with projects
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
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

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

@ -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

39
Help/policy/CMP0172.rst Normal file
View File

@ -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

22
Help/policy/CMP0173.rst Normal file
View File

@ -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

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

@ -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

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

@ -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

27
Help/policy/CMP0176.rst Normal file
View File

@ -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

38
Help/policy/CMP0177.rst Normal file
View File

@ -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

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

@ -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

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

@ -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

36
Help/policy/CMP0180.rst Normal file
View File

@ -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

2
Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst
View File

@ -17,7 +17,7 @@ pairs. Each such pair will be transformed into an entry in the
solution global section. Whitespace around key and value is ignored.
List elements which do not contain an equal sign are skipped.
This property only works for Visual Studio 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
directory whose ``CMakeLists.txt`` contains a :command:`project` command.

2
Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst
View File

@ -17,6 +17,6 @@ pairs. Each such pair will be transformed into an entry in the
solution global section. Whitespace around key and value is ignored.
List elements which do not contain an equal sign are skipped.
This property only works for Visual Studio 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
directory whose ``CMakeLists.txt`` contains a :command:`project` command.

20
Help/prop_gbl/INSTALL_PARALLEL.rst
View File

@ -3,18 +3,22 @@ INSTALL_PARALLEL
.. 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
console pool disabled, allowing them to run concurrently.
When using the Ninja generator, setting this property to ``ON``, causes
``install/local`` targets have the console pool disabled, allowing them to run
concurrently.
This property also provides the target ``install/parallel``, which has an
explicit dependency on the ``install/local`` target for each subdirectory,
recursing down the project.
explicit dependency on the ``install/local`` target for each subdirectory.
Setting this property has no affect on the behavior of ``cmake --install``.
The install must be invoked by building the ``install/parallel`` target
directly.
.. versionadded:: 3.31
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
on actions performed by an earlier :command:`install` command in a different

20
Help/prop_tgt/AIX_SHARED_LIBRARY_ARCHIVE.rst Normal file
View File

@ -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
Help/prop_tgt/COMPILE_FLAGS.rst
View File

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

15
Help/prop_tgt/EXPORT_BUILD_DATABASE.rst Normal file
View File

@ -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.

5
Help/prop_tgt/LINK_LIBRARIES.rst
View File

@ -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.
See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
: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.

87
Help/prop_tgt/LINK_LIBRARIES_STRATEGY.rst Normal file
View File

@ -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``.

8
Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst
View File

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

3
Help/prop_tgt/UNITY_BUILD.rst
View File

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

2
Help/prop_tgt/VS_DEBUGGER_COMMAND.rst
View File

@ -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
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.

2
Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst
View File

@ -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
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.

2
Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst
View File

@ -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
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.

2
Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst
View File

@ -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
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.

2
Help/prop_tgt/VS_DOTNET_STARTUP_OBJECT.rst
View File

@ -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
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.
.. code-block:: cmake

12
Help/prop_tgt/VS_FRAMEWORK_REFERENCES.rst Normal file
View File

@ -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

2
Help/prop_tgt/VS_KEYWORD.rst
View File

@ -6,4 +6,4 @@ for the :generator:`Visual Studio 9 2008` generator, and older,
but all of those generators have been removed.
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`.

4
Help/release/3.29.rst
View File

@ -64,6 +64,10 @@ Commands
* The :command:`if` command gained new tests ``IS_READABLE``, ``IS_WRITABLE``
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
---------

259
Help/release/3.31.rst Normal file
View File

@ -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`.

1
Help/release/index.rst
View File

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

10
Help/variable/CMAKE_AIX_SHARED_LIBRARY_ARCHIVE.rst Normal file
View File

@ -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.

2
Help/variable/CMAKE_CFG_INTDIR.rst
View File

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

6
Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst
View File

@ -1,10 +1,14 @@
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``
on Windows.
:variable:`CMAKE_EXECUTABLE_SUFFIX_<LANG>` overrides this for
language ``<LANG>``.
See the :variable:`CMAKE_HOST_EXECUTABLE_SUFFIX` variable for the
executable suffix on the host platform.

86
Help/variable/CMAKE_EXPORT_BUILD_DATABASE.rst Normal file
View File

@ -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.

19
Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst
View File

@ -3,23 +3,26 @@ CMAKE_FIND_PACKAGE_SORT_ORDER
.. versionadded:: 3.7
The default order for sorting packages found using :command:`find_package`.
It can assume one of the following values:
The default order for sorting directories which match a search path containing
a glob expression found using :command:`find_package`. It can assume one of
the following values:
``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.
``NAME``
Sort packages lexicographically before selecting one.
Sort directories lexicographically before searching.
``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.
Natural sorting can be employed to return the highest version when multiple
versions of the same library are found by :command:`find_package`. For
example suppose that the following libraries have been found:
versions of the same library are available to be found by
: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.2.9
@ -35,4 +38,4 @@ version number ``libX-1.2.10``.
The sort direction can be controlled using the
: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).

2
Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst
View File

@ -3,7 +3,7 @@ CMAKE_FIND_PACKAGE_TARGETS_GLOBAL
.. 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.

12
Help/variable/CMAKE_HOST_EXECUTABLE_SUFFIX.rst Normal file
View File

@ -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`.

3
Help/variable/CMAKE_LANG_COMPILER_ID.rst
View File

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

10
Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY_ARCHIVE.rst Normal file
View File

@ -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.

5
Help/variable/CMAKE_LANG_HOST_COMPILER.rst
View File

@ -42,3 +42,8 @@ variable is read-only and changes to it are undefined behavior.
.. note::
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``.

10
Help/variable/CMAKE_LANG_HOST_COMPILER_ID.rst Normal file
View File

@ -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`.

10
Help/variable/CMAKE_LANG_HOST_COMPILER_VERSION.rst Normal file
View File

@ -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`.

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