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

Update upstream source from tag 'upstream/3.23.0'

Browse Source 
Update to upstream version '3.23.0'
with Debian dir 9280ce0b50108829eb7a3dc513fc3ec0daa4e40a
This commit is contained in:
Timo Röhling 2022-03-29 21:11:19 +02:00
commit 7d9ab5a7e9
1484 changed files with 41039 additions and 11741 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.clang-tidy
View File

@ -1,6 +1,8 @@
---
Checks: "-*,\
bugprone-*,\
-bugprone-easily-swappable-parameters,\
-bugprone-implicit-widening-of-multiplication-result,\
-bugprone-macro-parentheses,\
-bugprone-misplaced-widening-cast,\
-bugprone-narrowing-conversions,\
@ -12,6 +14,7 @@ misc-*,\
-misc-static-assert,\
modernize-*,\
-modernize-avoid-c-arrays,\
-modernize-return-braced-init-list,\
-modernize-use-nodiscard,\
-modernize-use-noexcept,\
-modernize-use-trailing-return-type,\
@ -27,6 +30,8 @@ readability-*,\
-readability-magic-numbers,\
-readability-named-parameter,\
-readability-redundant-declaration,\
-readability-redundant-member-init,\
-readability-suspicious-call-argument,\
-readability-uppercase-literal-suffix,\
"
HeaderFilterRegex: 'Source/cm[^/]*\.(h|hxx|cxx)$'

2
Auxiliary/cmake.m4
View File

@ -13,7 +13,7 @@ fi
# $2: language (e.g. C/CXX/Fortran)
# $3: The compiler ID, defaults to GNU.
# Possible values are: GNU, Intel, Clang, SunPro, HP, XL, VisualAge, PGI,
# PathScale, Cray, SCO, MSVC
# PathScale, Cray, SCO, MSVC, LCC
# $4: optional extra arguments to cmake, e.g. "-DCMAKE_SIZEOF_VOID_P=8"
# $5: optional path to cmake binary
AC_DEFUN([CMAKE_FIND_PACKAGE], [

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

@ -152,6 +152,7 @@ syn keyword cmakeProperty contained
\ DISABLED
\ DISABLED_FEATURES
\ DISABLE_PRECOMPILE_HEADERS
\ DOTNET_SDK
\ DOTNET_TARGET_FRAMEWORK
\ DOTNET_TARGET_FRAMEWORK_VERSION
\ ECLIPSE_EXTRA_CPROJECT_CONTENTS
@ -426,6 +427,7 @@ syn keyword cmakeProperty contained
\ XCODE_SCHEME_ARGUMENTS
\ XCODE_SCHEME_DEBUG_AS_ROOT
\ XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
\ XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
\ XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
\ XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
\ XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
@ -1000,6 +1002,7 @@ syn keyword cmakeVariable contained
\ CMAKE_DIRECTORY_LABELS
\ CMAKE_DISABLE_PRECOMPILE_HEADERS
\ CMAKE_DL_LIBS
\ CMAKE_DOTNET_SDK
\ CMAKE_DOTNET_TARGET_FRAMEWORK
\ CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION
\ CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES
@ -1524,6 +1527,7 @@ syn keyword cmakeVariable contained
\ CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
\ CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
\ CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
\ CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
\ CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
\ CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
\ CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
@ -1608,6 +1612,7 @@ syn keyword cmakeVariable contained
\ CTEST_SCP_COMMAND
\ CTEST_SITE
\ CTEST_SOURCE_DIRECTORY
\ CTEST_SUBMIT_INACTIVITY_TIMEOUT
\ CTEST_SUBMIT_URL
\ CTEST_SVN_COMMAND
\ CTEST_SVN_OPTIONS
@ -1900,7 +1905,7 @@ syn keyword cmakeVariable contained
\ DOXYGEN_XML_PROGRAMLISTING
\ ENV
\ EXECUTABLE_OUTPUT_PATH
\ GHS-MULTI
\ GHSMULTI
\ IOS
\ LIBRARY_OUTPUT_PATH
\ MINGW
@ -2051,6 +2056,7 @@ syn keyword cmakeKWExternalProject contained
\ USES_TERMINAL_CONFIGURE
\ USES_TERMINAL_DOWNLOAD
\ USES_TERMINAL_INSTALL
\ USES_TERMINAL_PATCH
\ USES_TERMINAL_TEST
\ USES_TERMINAL_UPDATE
\ WORKING_DIRECTORY

50
CMakeLists.txt
View File

@ -1,9 +1,14 @@
# 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.1...3.20 FATAL_ERROR)
cmake_minimum_required(VERSION 3.1...3.21 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)
if(POLICY CMP0129)
cmake_policy(SET CMP0129 NEW) # CMake 3.23
endif()
project(CMake)
unset(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX)
unset(CMAKE_USER_MAKE_RULES_OVERRIDE_C)
@ -633,7 +638,7 @@ macro (CMAKE_BUILD_UTILITIES)
message(FATAL_ERROR
"CMAKE_USE_SYSTEM_JSONCPP is ON but a JsonCpp is not found!")
endif()
if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|LCC|Clang")
set_property(TARGET JsonCpp::JsonCpp APPEND PROPERTY
INTERFACE_COMPILE_OPTIONS -Wno-deprecated-declarations)
endif()
@ -650,7 +655,7 @@ macro (CMAKE_BUILD_UTILITIES)
if(WIN32)
find_package(LibUV 1.38.0)
else()
find_package(LibUV 1.10.0)
find_package(LibUV 1.28.0)
endif()
if(NOT LIBUV_FOUND)
message(FATAL_ERROR
@ -665,23 +670,33 @@ macro (CMAKE_BUILD_UTILITIES)
#---------------------------------------------------------------------
# Use curses?
if (UNIX)
if(NOT DEFINED BUILD_CursesDialog)
if(NOT DEFINED BUILD_CursesDialog)
if (UNIX)
include(${CMake_SOURCE_DIR}/Source/Checks/Curses.cmake)
option(BUILD_CursesDialog "Build the CMake Curses Dialog ccmake" "${CMakeCheckCurses_COMPILED}")
set(BUILD_CursesDialog_DEFAULT "${CMakeCheckCurses_COMPILED}")
elseif(WIN32)
set(BUILD_CursesDialog_DEFAULT "OFF")
endif()
else ()
set(BUILD_CursesDialog 0)
option(BUILD_CursesDialog "Build the CMake Curses Dialog ccmake" "${BUILD_CursesDialog_DEFAULT}")
endif ()
if(BUILD_CursesDialog)
set(CURSES_NEED_NCURSES TRUE)
find_package(Curses)
if(NOT CURSES_FOUND)
message(WARNING
"'ccmake' will not be built because Curses was not found.\n"
"Turn off BUILD_CursesDialog to suppress this message."
)
set(BUILD_CursesDialog 0)
if(UNIX)
set(CURSES_NEED_NCURSES TRUE)
find_package(Curses)
if(NOT CURSES_FOUND)
message(WARNING
"'ccmake' will not be built because Curses was not found.\n"
"Turn off BUILD_CursesDialog to suppress this message."
)
set(BUILD_CursesDialog 0)
endif()
elseif(WIN32)
# FIXME: Add support for system-provided pdcurses.
add_subdirectory(Utilities/cmpdcurses)
set(CURSES_LIBRARY cmpdcurses)
set(CURSES_INCLUDE_PATH "") # cmpdcurses has usage requirements
set(CMAKE_USE_SYSTEM_FORM 0)
set(HAVE_CURSES_USE_DEFAULT_COLORS 1)
endif()
endif()
if(BUILD_CursesDialog)
@ -820,7 +835,8 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
(CMAKE_C_COMPILER_ID STREQUAL "Clang" AND
NOT "${CMAKE_C_COMPILER_VERSION}" VERSION_LESS 3.0 AND
NOT "x${CMAKE_C_SIMULATE_ID}" STREQUAL "xMSVC") OR
CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
CMAKE_C_COMPILER_ID STREQUAL "AppleClang" OR
CMAKE_C_COMPILER_ID STREQUAL "LCC")
set(C_FLAGS_LIST -Wcast-align -Werror-implicit-function-declaration -Wchar-subscripts
-Wall -W -Wpointer-arith -Wwrite-strings -Wformat-security
-Wmissing-format-attribute -fno-common -Wundef

4
Copyright.txt
View File

@ -1,5 +1,5 @@
CMake - Cross Platform Makefile Generator
Copyright 2000-2021 Kitware, Inc. and Contributors
Copyright 2000-2022 Kitware, Inc. and Contributors
All rights reserved.
Redistribution and use in source and binary forms, with or without
@ -62,7 +62,9 @@ The following individuals and institutions are among the Contributors:
* Helio Chissini de Castro <helio@kde.org>
* Ilya Lavrenov <ilya.lavrenov@itseez.com>
* Insight Software Consortium <insightsoftwareconsortium.org>
* Intel Corporation <www.intel.com>
* Jan Woetzel
* Jordan Williams <jordan@jwillikers.com>
* Julien Schueller
* Kelly Thompson <kgt@lanl.gov>
* Konstantin Podsvirov <konstantin@podsvirov.pro>

5
Help/command/FIND_XXX.txt
View File

@ -170,6 +170,11 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
or in the short-hand version of the command.
These are typically hard-coded guesses.
The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
:variable:`CMAKE_SYSTEM_IGNORE_PATH` and
:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
of the above locations to be ignored.
.. versionadded:: 3.16
Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable
various search locations.

44
Help/command/add_custom_command.rst
View File

@ -271,9 +271,47 @@ The options are:
``DEPFILE``
.. versionadded:: 3.7
Specify a ``.d`` depfile which holds dependencies for the custom command.
It is usually emitted by the custom command itself. This keyword may only
be used if the generator supports it, as detailed below.
Specify a depfile which holds dependencies for the custom command. It is
usually emitted by the custom command itself. This keyword may only be used
if the generator supports it, as detailed below.
The expected format, compatible with what is generated by ``gcc`` with the
option ``-M``, is independent of the generator or platform.
The formal syntax, as specified using
`BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with
the regular extensions, is the following:
.. raw:: latex
\begin{small}
.. productionlist:: depfile
depfile: `rule`*
rule: `targets` (`:` (`separator` `dependencies`?)?)? `eol`
targets: `target` (`separator` `target`)* `separator`*
target: `pathname`
dependencies: `dependency` (`separator` `dependency`)* `separator`*
dependency: `pathname`
separator: (space | line_continue)+
line_continue: '\' `eol`
space: ' ' | '\t'
pathname: `character`+
character: `std_character` | `dollar` | `hash` | `whitespace`
std_character: <any character except '$', '#' or ' '>
dollar: '$$'
hash: '\#'
whitespace: '\ '
eol: '\r'? '\n'
.. raw:: latex
\end{small}
.. note::
As part of ``pathname``, any slash and backslash is interpreted as
a directory separator.
.. versionadded:: 3.7
The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword

24
Help/command/add_test.rst
View File

@ -20,6 +20,9 @@ if necessary. See policy :policy:`CMP0110`. The options are:
automatically be replaced by the location of the executable created
at build time.
The command may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``CONFIGURATIONS``
Restrict execution of the test only to the named configurations.
@ -30,6 +33,9 @@ if necessary. See policy :policy:`CMP0110`. The options are:
directory set to the build directory corresponding to the
current source directory.
The working directory may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``COMMAND_EXPAND_LISTS``
.. versionadded:: 3.16
@ -48,9 +54,10 @@ unless the :prop_test:`PASS_REGULAR_EXPRESSION`,
.. versionadded:: 3.16
Added :prop_test:`SKIP_REGULAR_EXPRESSION` property.
The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator
expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions.
Tests added with the ``add_test(NAME)`` signature support using
:manual:`generator expressions <cmake-generator-expressions(7)>`
in test properties set by :command:`set_property(TEST)` or
:command:`set_tests_properties`.
Example usage:
@ -73,10 +80,15 @@ file produced by target ``myexe``.
---------------------------------------------------------------------
This command also supports a simpler, but less flexible, signature:
.. code-block:: cmake
add_test(<name> <command> [<arg>...])
Add a test called ``<name>`` with the given command-line. Unlike
the above ``NAME`` signature no transformation is performed on the
command-line to support target names or generator expressions.
Add a test called ``<name>`` with the given command-line.
Unlike the above ``NAME`` signature, target names are not supported
in the command-line. Furthermore, tests added with this signature do not
support :manual:`generator expressions <cmake-generator-expressions(7)>`
in the command-line or test properties.

34
Help/command/define_property.rst
View File

@ -8,15 +8,18 @@ Define and document custom properties.
define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
TEST | VARIABLE | CACHED_VARIABLE>
PROPERTY <name> [INHERITED]
BRIEF_DOCS <brief-doc> [docs...]
FULL_DOCS <full-doc> [docs...])
[BRIEF_DOCS <brief-doc> [docs...]]
[FULL_DOCS <full-doc> [docs...]]
[INITIALIZE_FROM_VARIABLE <variable>])
Defines one property in a scope for use with the :command:`set_property` and
:command:`get_property` commands. This is primarily useful to associate
documentation with property names that may be retrieved with the
:command:`get_property` command. The first argument determines the kind of
scope in which the property should be used. It must be one of the
following:
:command:`get_property` commands. It is mainly useful for defining the way
a property is initialized or inherited. Historically, the command also
associated documentation with a property, but that is no longer considered a
primary use case.
The first argument determines the kind of scope in which the property should
be used. It must be one of the following:
::
@ -55,5 +58,18 @@ out the contents to append to.
The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be
associated with the property as its brief and full documentation.
Corresponding options to the :command:`get_property` command will retrieve
the documentation.
CMake does not use this documentation other than making it available to the
project via corresponding options to the :command:`get_property` command.
.. versionchanged:: 3.23
The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are optional.
.. versionadded:: 3.23
The ``INITIALIZE_FROM_VARIABLE`` option specifies a variable from which the
property should be initialized. It can only be used with target properties.
The ``<variable>`` name must end with the property name and must not begin
with ``CMAKE_`` or ``_CMAKE_``. The property name must contain at least one
underscore. It is recommended that the property name have a prefix specific
to the project.

131
Help/command/export.rst
View File

@ -1,44 +1,62 @@
export
------
Export targets from the build tree for use by outside projects.
Export targets or packages for outside projects to use them directly
from the current project's build tree, without installation.
See the :command:`install(EXPORT)` command to export targets from an
install tree.
Synopsis
^^^^^^^^
.. parsed-literal::
export(`TARGETS`_ <target>... [...])
export(`EXPORT`_ <export-name> [...])
export(`PACKAGE`_ <PackageName>)
Exporting Targets
^^^^^^^^^^^^^^^^^
.. _`export(TARGETS)`:
.. _TARGETS:
.. code-block:: cmake
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
export(TARGETS <target>... [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
Creates a file ``<filename>`` that may be included by outside projects to
import targets from the current project's build tree. This is useful
during cross-compiling to build utility executables that can run on
the host platform in one project and then import them into another
project being compiled for the target platform. If the ``NAMESPACE``
option is given the ``<namespace>`` string will be prepended to all target
names written to the file.
Target installations are associated with the export ``<export-name>``
using the ``EXPORT`` option of the :command:`install(TARGETS)` command.
import targets named by ``<target>...`` from the current project's build tree.
This is useful during cross-compiling to build utility executables that can
run on the host platform in one project and then import them into another
project being compiled for the target platform.
The file created by this command is specific to the build tree and
should never be installed. See the :command:`install(EXPORT)` command to
export targets from an installation tree.
export targets from an install tree.
The properties set on the generated IMPORTED targets will have the
same values as the final values of the input TARGETS.
The options are:
.. code-block:: cmake
``NAMESPACE <namespace>``
Prepend the ``<namespace>`` string to all target names written to the file.
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
``APPEND``
Append to the file instead of overwriting it. This can be used to
incrementally export multiple targets to the same file.
This signature is similar to the ``EXPORT`` signature, but targets are listed
explicitly rather than specified as an export-name. If the APPEND option is
given the generated code will be appended to the file instead of overwriting it.
The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the
contents of the properties matching
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
policy CMP0022 is NEW. If a library target is included in the export
but a target to which it links is not included the behavior is
unspecified.
``EXPORT_LINK_INTERFACE_LIBRARIES``
Include the contents of the properties named with the pattern
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``
in the export, even when policy :policy:`CMP0022` is NEW. This is useful
to support consumers using CMake versions older than 2.8.12.
This signature requires all targets to be listed explicitly. If a library
target is included in the export, but a target to which it links is not
included, the behavior is unspecified. See the `export(EXPORT)`_ signature
to automatically export the same targets from the build tree as
:command:`install(EXPORT)` would from an install tree.
.. note::
@ -49,6 +67,50 @@ unspecified.
transitive usage requirements of other targets that link to the
object libraries in their implementation.
Exporting Targets to Android.mk
"""""""""""""""""""""""""""""""
.. code-block:: cmake
export(TARGETS <target>... ANDROID_MK <filename>)
.. versionadded:: 3.7
This signature exports cmake built targets to the android ndk build system
by creating an ``Android.mk`` file that references the prebuilt targets. The
Android NDK supports the use of prebuilt libraries, both static and shared.
This allows cmake to build the libraries of a project and make them available
to an ndk build system complete with transitive dependencies, include flags
and defines required to use the libraries. The signature takes a list of
targets and puts them in the ``Android.mk`` file specified by the
``<filename>`` given. This signature can only be used if policy
:policy:`CMP0022` is NEW for all targets given. A error will be issued if
that policy is set to OLD for one of the targets.
Exporting Targets matching install(EXPORT)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _`export(EXPORT)`:
.. _EXPORT:
.. code-block:: cmake
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
Creates a file ``<filename>`` that may be included by outside projects to
import targets from the current project's build tree. This is the same
as the `export(TARGETS)`_ signature, except that the targets are not
explicitly listed. Instead, it exports the targets associated with
the installation export ``<export-name>``. Target installations may be
associated with the export ``<export-name>`` using the ``EXPORT`` option
of the :command:`install(TARGETS)` command.
Exporting Packages
^^^^^^^^^^^^^^^^^^
.. _`export(PACKAGE)`:
.. _PACKAGE:
.. code-block:: cmake
export(PACKAGE <PackageName>)
@ -74,20 +136,3 @@ registry.
outside the source and build trees. Set the
:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories
to the CMake user package registry.
.. code-block:: cmake
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
.. versionadded:: 3.7
This signature exports cmake built targets to the android ndk build system
by creating an Android.mk file that references the prebuilt targets. The
Android NDK supports the use of prebuilt libraries, both static and shared.
This allows cmake to build the libraries of a project and make them available
to an ndk build system complete with transitive dependencies, include flags
and defines required to use the libraries. The signature takes a list of
targets and puts them in the Android.mk file specified by the ``<filename>``
given. This signature can only be used if policy CMP0022 is NEW for all
targets given. A error will be issued if that policy is set to OLD for one
of the targets.

5
Help/command/find_package.rst
View File

@ -363,6 +363,11 @@ enabled.
9. Search paths specified by the ``PATHS`` option. These are typically
hard-coded guesses.
The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
:variable:`CMAKE_SYSTEM_IGNORE_PATH` and
:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
of the above locations to be ignored.
.. versionadded:: 3.16
Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable
various search locations.

37
Help/command/if.rst
View File

@ -38,21 +38,29 @@ The following syntax applies to the ``condition`` argument of
the ``if``, ``elseif`` and :command:`while` clauses.
Compound conditions are evaluated in the following order of precedence:
Innermost parentheses are evaluated first. Next come unary tests such
as `EXISTS`_, `COMMAND`_, and `DEFINED`_. Then 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`_,
and `MATCHES`_. Then the boolean operators in the order `NOT`_, `AND`_,
and finally `OR`_.
1. Parentheses.
2. Unary tests such as `EXISTS`_, `COMMAND`_, 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`_,
and `MATCHES`_.
4. Unary logical operator `NOT`_.
5. Binary logical operators `AND`_ and `OR`_, from left to right,
without any short-circuit.
Basic Expressions
"""""""""""""""""
``if(<constant>)``
True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``,
or a non-zero number. False if the constant is ``0``, ``OFF``,
or a non-zero number (including floating point numbers).
False if the constant is ``0``, ``OFF``,
``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string,
or ends in the suffix ``-NOTFOUND``. Named boolean constants are
case-insensitive. If the argument is not one of these specific
@ -126,7 +134,16 @@ Existence Checks
``if(DEFINED <name>|CACHE{<name>}|ENV{<name>})``
True if a variable, cache variable or environment variable
with given ``<name>`` is defined. The value of the variable
does not matter. Note that macro arguments are not variables.
does not matter. Note the following caveats:
* Macro arguments are not variables.
* It is not possible to test directly whether a `<name>` is a non-cache
variable. The expression ``if(DEFINED someName)`` will evaluate to true
if either a cache or non-cache variable ``someName`` exists. In
comparison, the expression ``if(DEFINED CACHE{someName})`` will only
evaluate to true if a cache variable ``someName`` exists. Both expressions
need to be tested if you need to know whether a non-cache variable exists:
``if(DEFINED someName AND NOT DEFINED CACHE{someName})``.
.. versionadded:: 3.14
Added support for ``CACHE{<name>}`` variables.

87
Help/command/install.rst
View File

@ -132,7 +132,7 @@ Installing Targets
install(TARGETS targets... [EXPORT <export-name>]
[RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
[[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>]
[DESTINATION <dir>]
[PERMISSIONS permissions...]
[CONFIGURATIONS [Debug|Release|...]]
@ -204,6 +204,17 @@ that may be installed:
Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for
``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details.
``FILE_SET <set>``
.. versionadded:: 3.23
File sets are defined by the :command:`target_sources(FILE_SET)` command.
If the file set ``<set>`` exists and is ``PUBLIC`` or ``INTERFACE``, any
files in the set are installed under the destination (see below).
The directory structure relative to the file set's base directories is
preserved. For example, a file added to the file set as
``/blah/include/myproj/here.h`` with a base directory ``/blah/include``
would be installed to ``myproj/here.h`` below the destination.
For each of these arguments given, the arguments following them only apply
to the target or file type specified in the argument. If none is given, the
installation properties apply to all target types. If only one is given then
@ -214,30 +225,32 @@ For regular executables, static libraries and shared libraries, the
``DESTINATION`` argument is not required. For these target types, when
``DESTINATION`` is omitted, a default destination will be taken from the
appropriate variable from :module:`GNUInstallDirs`, or set to a built-in
default value if that variable is not defined. The same is true for the
public and private headers associated with the installed targets through the
:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties.
A destination must always be provided for module libraries, Apple bundles and
frameworks. A destination can be omitted for interface and object libraries,
but they are handled differently (see the discussion of this topic toward the
end of this section).
default value if that variable is not defined. The same is true for file
sets, and the public and private headers associated with the installed
targets through the :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER`
target properties. A destination must always be provided for module libraries,
Apple bundles and frameworks. A destination can be omitted for interface and
object libraries, but they are handled differently (see the discussion of this
topic toward the end of this section).
The following table shows the target types with their associated variables and
built-in defaults that apply when no destination is given:
================== =============================== ======================
Target Type GNUInstallDirs Variable Built-In Default
================== =============================== ======================
``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin``
``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
================== =============================== ======================
=============================== =============================== ======================
Target Type GNUInstallDirs Variable Built-In Default
=============================== =============================== ======================
``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin``
``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
``FILE_SET`` (type ``HEADERS``) ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
=============================== =============================== ======================
Projects wishing to follow the common practice of installing headers into a
project-specific subdirectory will need to provide a destination rather than
rely on the above.
project-specific subdirectory may prefer using file sets with appropriate
paths and base directories. Otherwise, they must provide a ``DESTINATION``
instead of being able to rely on the above (see next example below).
To make packages compliant with distribution filesystem layout policies, if
projects must specify a ``DESTINATION``, it is recommended that they use a
@ -246,7 +259,7 @@ This allows package maintainers to control the install destination by setting
the appropriate cache variables. The following example shows a static library
being installed to the default destination provided by
:module:`GNUInstallDirs`, but with its headers installed to a project-specific
subdirectory that follows the above recommendation:
subdirectory without using file sets:
.. code-block:: cmake
@ -338,6 +351,11 @@ top level:
See documentation of the :prop_tgt:`EXPORT_NAME` target property to change
the name of the exported target.
If ``EXPORT`` is used and the targets include ``PUBLIC`` or ``INTERFACE``
file sets, all of them must be specified with ``FILE_SET`` arguments. All
``PUBLIC`` or ``INTERFACE`` file sets associated with a target are included
in the export.
``INCLUDES DESTINATION``
This option specifies a list of directories which will be added to the
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
@ -478,6 +496,12 @@ Installing Files
.. _FILES:
.. _PROGRAMS:
.. note::
If installing header files, consider using file sets defined by
:command:`target_sources(FILE_SET)` instead. File sets associate
headers with a target and they install as part of the target.
.. code-block:: cmake
install(<FILES|PROGRAMS> files...
@ -534,7 +558,8 @@ file type if they wish to explicitly define the install destination.
Projects wishing to follow the common practice of installing headers into a
project-specific subdirectory will need to provide a destination rather than
rely on the above.
rely on the above. Using file sets for headers instead of ``install(FILES)``
would be even better (see :command:`target_sources(FILE_SET)`).
Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
@ -547,13 +572,14 @@ projects must specify a ``DESTINATION``, it is recommended that they use a
path that begins with the appropriate :module:`GNUInstallDirs` variable.
This allows package maintainers to control the install destination by setting
the appropriate cache variables. The following example shows how to follow
this advice while installing headers to a project-specific subdirectory:
this advice while installing an image to a project-specific documentation
subdirectory:
.. code-block:: cmake
include(GNUInstallDirs)
install(FILES mylib.h
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
install(FILES logo.png
DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj
)
.. versionadded:: 3.4
@ -572,6 +598,13 @@ Installing Directories
.. _`install(DIRECTORY)`:
.. _DIRECTORY:
.. note::
To install a directory sub-tree of headers, consider using file sets
defined by :command:`target_sources(FILE_SET)` instead. File sets not only
preserve directory structure, they also associate headers with a target
and install as part of the target.
.. code-block:: cmake
install(DIRECTORY dirs...
@ -623,10 +656,10 @@ any expression. For example, the code
.. code-block:: cmake
install(DIRECTORY src/ DESTINATION include/myproj
FILES_MATCHING PATTERN "*.h")
install(DIRECTORY src/ DESTINATION doc/myproj
FILES_MATCHING PATTERN "*.png")
will extract and install header files from a source tree.
will extract and install images from a source tree.
Some options may follow a ``PATTERN`` or ``REGEX`` expression as described
under :ref:`string(REGEX) <Regex Specification>` and are applied

15
Help/command/list.rst
View File

@ -128,7 +128,9 @@ Modification
list(APPEND <list> [<element> ...])
Appends elements to the list.
Appends elements to the list. If no variable named ``<list>`` exists in the
current scope its value is treated as empty and the elements are appended to
that empty list.
.. _FILTER:
@ -150,7 +152,12 @@ For more information on regular expressions look under
list(INSERT <list> <element_index> <element> [<element> ...])
Inserts elements to the list to the specified location.
Inserts elements to the list to the specified index. It is an
error to specify an out-of-range index. Valid indexes are 0 to `N`
where `N` is the length of the list, inclusive. An empty list
has length 0. If no variable named ``<list>`` exists in the
current scope its value is treated as empty and the elements are
inserted in that empty list.
.. _POP_BACK:
@ -186,7 +193,9 @@ to the given variables and then remove the first `N` values from
.. versionadded:: 3.15
Insert elements to the 0th position in the list.
Insert elements to the 0th position in the list. If no variable named
``<list>`` exists in the current scope its value is treated as empty and
the elements are prepended to that empty list.
.. _REMOVE_ITEM:

4
Help/command/set_property.rst
View File

@ -85,6 +85,10 @@ It must be one of the following:
Scope may name zero or more existing tests.
See also the :command:`set_tests_properties` command.
Test property values may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>`
for tests created by the :command:`add_test(NAME)` signature.
``CACHE``
Scope must name zero or more cache existing entries.

6
Help/command/set_tests_properties.rst
View File

@ -9,8 +9,10 @@ Set a property of the tests.
Sets a property for the tests. If the test is not found, CMake
will report an error.
:manual:`Generator expressions <cmake-generator-expressions(7)>` will be
expanded the same as supported by the test's :command:`add_test` call.
Test property values may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>`
for tests created by the :command:`add_test(NAME)` signature.
See also the :command:`set_property(TEST)` command.

3
Help/command/string.rst
View File

@ -490,6 +490,9 @@ specifiers:
``%S``
The second of the current minute. 60 represents a leap second. (00-60)
``%f``
The microsecond of the current second (000000-999999).
``%U``
The week number of the current year (00-53).

38
Help/command/target_include_directories.rst
View File

@ -27,14 +27,16 @@ The following arguments specify include directories.
.. versionadded:: 3.11
Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
Specified include directories may be absolute paths or relative paths.
Repeated calls for the same <target> append items in the order called. If
``SYSTEM`` is specified, the compiler will be told the
directories are meant as system include directories on some platforms
(signalling this setting might achieve effects such as the compiler
skipping warnings, or these fixed-install system files not being
considered in dependency calculations - see compiler docs). If ``SYSTEM``
is used together with ``PUBLIC`` or ``INTERFACE``, the
Repeated calls for the same ``<target>`` append items in the order called.
If ``SYSTEM`` is specified, the compiler will be told the directories
are meant as system include directories on some platforms. This may
have effects such as suppressing warnings or skipping the contained
headers in dependency calculations (see compiler documentation).
Additionally, system include directories are searched after normal
include directories regardless of the order specified.
If ``SYSTEM`` is used together with ``PUBLIC`` or ``INTERFACE``, the
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be
populated with the specified directories.
@ -43,12 +45,22 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
Specified include directories may be absolute paths or relative paths.
A relative path will be interpreted as relative to the current source
directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and converted to an
absolute path before storing it in the associated target property.
If the path starts with a generator expression, it will always be assumed
to be an absolute path (with one exception noted below) and will be used
unmodified.
Include directories usage requirements commonly differ between the build-tree
and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
generator expressions can be used to describe separate usage requirements
based on the usage location. Relative paths are allowed within the
``INSTALL_INTERFACE`` expression and are interpreted relative to the
installation prefix. For example:
and the install-tree. The :genex:`BUILD_INTERFACE` and
:genex:`INSTALL_INTERFACE` generator expressions can be used to describe
separate usage requirements based on the usage location. Relative paths
are allowed within the :genex:`INSTALL_INTERFACE` expression and are
interpreted as relative to the installation prefix. Relative paths should not
be used in :genex:`BUILD_INTERFACE` expressions because they will not be
converted to absolute. For example:
.. code-block:: cmake

151
Help/command/target_sources.rst
View File

@ -15,34 +15,143 @@ Specifies sources to use when building a target and/or its dependents.
The named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` or
:command:`add_custom_target` and must not be an
:ref:`ALIAS target <Alias Targets>`.
:ref:`ALIAS target <Alias Targets>`. The ``<items>`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
.. versionadded:: 3.20
``<target>`` can be a custom target.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the source file paths (``<items>``) that follow
them. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES`
property of ``<target>``, which are used when building the target itself.
``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used
when building dependents. A target created by :command:`add_custom_target`
can only have ``PRIVATE`` scope.
Repeated calls for the same ``<target>`` append items in the order called.
.. versionadded:: 3.3
Allow exporting targets with :prop_tgt:`INTERFACE_SOURCES`.
.. versionadded:: 3.11
Allow setting ``INTERFACE`` items on
:ref:`IMPORTED targets <Imported Targets>`.
.. versionchanged:: 3.13
Relative source file paths are interpreted as being relative to the current
source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).
See policy :policy:`CMP0076`.
.. versionadded:: 3.20
``<target>`` can be a custom target.
A path that begins with a generator expression is left unmodified.
When a target's :prop_tgt:`SOURCE_DIR` property differs from
:variable:`CMAKE_CURRENT_SOURCE_DIR`, use absolute paths in generator
expressions to ensure the sources are correctly assigned to the target.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the items following them. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`SOURCES` property of
``<target>``, which are used when building the target itself.
``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used
when building dependents.
The following arguments specify sources. Repeated calls for the same
``<target>`` append items in the order called. The targets created by
:command:`add_custom_target` can only have ``PRIVATE`` scope.
.. code-block:: cmake
.. versionadded:: 3.3
Allow exporting targets with :prop_tgt:`INTERFACE_SOURCES`.
# WRONG: starts with generator expression, but relative path used
target_sources(MyTarget "$<$<CONFIG:Debug>:dbgsrc.cpp>")
.. versionadded:: 3.11
Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
# CORRECT: absolute path used inside the generator expression
target_sources(MyTarget "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>")
Arguments to ``target_sources`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.
File Sets
^^^^^^^^^
.. versionadded:: 3.23
.. code-block:: cmake
target_sources(<target>
[<INTERFACE|PUBLIC|PRIVATE>
[FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]...
]...)
Adds a file set to a target, or adds files to an existing file set. Targets
have zero or more named file sets. Each file set has a name, a type, a scope of
``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and
files within those directories. The only acceptable type is ``HEADERS``. The
optional default file sets are named after their type. The target may not be a
custom target.
Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for
the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets
have their :prop_sf:`HEADER_FILE_ONLY` property set to ``TRUE``. Files in an
``INTERFACE`` or ``PUBLIC`` file set can be installed with the
:command:`install(TARGETS)` command, and exported with the
:command:`install(EXPORT)` and :command:`export` commands.
Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, or
``PRIVATE`` and accepts the following arguments:
``FILE_SET <set>``
The name of the file set to create or add to. It must contain only letters,
numbers and underscores. Names starting with a capital letter are reserved
for built-in file sets predefined by CMake. The only predefined set name is
``HEADERS``. All other set names must not start with a capital letter or
underscore.
``TYPE <type>``
Every file set is associated with a particular type of file. ``HEADERS``
is currently the only defined type and it is an error to specify anything
else. As a special case, if the name of the file set is ``HEADERS``, the
type does not need to be specified and the ``TYPE <type>`` arguments can be
omitted. For all other file set names, ``TYPE`` is required.
``BASE_DIRS <dirs>...``
An optional list of base directories of the file set. Any relative path
is treated as relative to the current source directory
(i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). If no ``BASE_DIRS`` are
specified when the file set is first created, the value of
:variable:`CMAKE_CURRENT_SOURCE_DIR` is added. This argument supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
No two base directories for a file set may be sub-directories of each other.
This requirement must be met across all base directories added to a file set,
not just those within a single call to ``target_sources()``.
``FILES <files>...``
An optional list of files to add to the file set. Each file must be in
one of the base directories, or a subdirectory of one of the base
directories. This argument supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
If relative paths are specified, they are considered relative to
:variable:`CMAKE_CURRENT_SOURCE_DIR` at the time ``target_sources()`` is
called. An exception to this is a path starting with ``$<``. Such paths
are treated as relative to the target's source directory after evaluation
of generator expressions.
The following target properties are set by ``target_sources(FILE_SET)``,
but they should not generally be manipulated directly:
* :prop_tgt:`HEADER_SETS`
* :prop_tgt:`INTERFACE_HEADER_SETS`
* :prop_tgt:`HEADER_SET`
* :prop_tgt:`HEADER_SET_<NAME>`
* :prop_tgt:`HEADER_DIRS`
* :prop_tgt:`HEADER_DIRS_<NAME>`
Target properties related to include directories are also modified by
``target_sources(FILE_SET)`` as follows:
:prop_tgt:`INCLUDE_DIRECTORIES`
If the ``TYPE`` is ``HEADERS``, and the scope of the file set is ``PRIVATE``
or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in
:genex:`$<BUILD_INTERFACE>` and appended to this property.
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
If the ``TYPE`` is ``HEADERS``, and the scope of the file set is
``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are
wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property.

8
Help/command/try_compile.rst
View File

@ -19,10 +19,6 @@ Try Compiling Whole Projects
Try building a project. The success or failure of the ``try_compile``,
i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.
.. versionadded:: 3.14
The name of the ``<resultVar>`` is defined by the user. Previously, it had
a fixed name ``RESULT_VAR``.
In this form, ``<srcdir>`` should contain a complete CMake project with a
``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>``
will not be deleted after this command is run. Specify ``<targetName>`` to
@ -51,10 +47,6 @@ Try building an executable or static library from one or more source files
variable). The success or failure of the ``try_compile``, i.e. ``TRUE`` or
``FALSE`` respectively, is returned in ``<resultVar>``.
.. versionadded:: 3.14
The name of the ``<resultVar>`` is defined by the user. Previously, it had
a fixed name ``RESULT_VAR``.
In this form, one or more source files must be provided. If
:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``,
the sources must include a definition for ``main`` and CMake will create a

5
Help/command/try_run.rst
View File

@ -30,11 +30,6 @@ executable was built, but failed to run, then ``<runResultVar>`` will be
set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for
information on how the test project is constructed to build the source file.
.. versionadded:: 3.14
The names of the result variables ``<runResultVar>`` and
``<compileResultVar>`` are defined by the user. Previously, they had
fixed names ``RUN_RESULT_VAR`` and ``COMPILE_RESULT_VAR``.
The options are:
``CMAKE_FLAGS <flags>...``

21
Help/cpack_gen/dmg.rst
View File

@ -54,6 +54,27 @@ on macOS:
Default behavior is to include a symlink to ``/Applications`` in the DMG.
Set this option to ``ON`` to avoid adding the symlink.
.. variable:: CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE
.. versionadded:: 3.23
Control whether :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a
non-default value, is used as the license agreement provided when
mounting the DMG. If ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`` is
not set, :manual:`cpack(1)` defaults to off.
In a CMake project that uses the :module:`CPack` module to generate
``CPackConfig.cmake``, ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE``
is automatically enabled by default if it is not set and
:variable:`CPACK_RESOURCE_FILE_LICENSE` is set to a non-default value.
.. note::
This option was added in response to macOS 12.0's deprecation of
the ``hdiutil udifrez`` command to make its use optional.
CPack 3.22 and below always use :variable:`CPACK_RESOURCE_FILE_LICENSE`,
if set to a non-default value, as the DMG license.
.. variable:: CPACK_DMG_SLA_DIR
.. versionadded:: 3.5

262
Help/cpack_gen/ifw.rst
View File

@ -24,12 +24,12 @@ Microsoft Windows, and macOS.
To make use of this generator, QtIFW needs to be installed.
The :module:`CPackIFW` module looks for the location of the
QtIFW command-line utilities, and defines several commands to
control the behavior of this generator.
control the behavior of this generator. See `Hints for Finding QtIFW`_.
Variables
^^^^^^^^^
You can use the following variables to change behavior of CPack ``IFW``
You can use the following variables to change the behavior of the CPack ``IFW``
generator.
Debug
@ -48,12 +48,12 @@ Package
.. variable:: CPACK_IFW_PACKAGE_TITLE
Name of the installer as displayed on the title bar.
By default used :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`.
If not specified, it defaults to :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`.
.. variable:: CPACK_IFW_PACKAGE_PUBLISHER
Publisher of the software (as shown in the Windows Control Panel).
By default used :variable:`CPACK_PACKAGE_VENDOR`.
If not specified, it defaults to :variable:`CPACK_PACKAGE_VENDOR`.
.. variable:: CPACK_IFW_PRODUCT_URL
@ -61,83 +61,93 @@ Package
.. variable:: CPACK_IFW_PACKAGE_ICON
Filename for a custom installer icon. The actual file is '.icns' (macOS),
'.ico' (Windows). No functionality on Unix.
Filename for a custom installer icon. It must be an absolute path.
This should be a ``.icns`` file on macOS and a ``.ico`` file on Windows.
It is ignored on other platforms.
.. variable:: CPACK_IFW_PACKAGE_WINDOW_ICON
Filename for a custom window icon in PNG format for the Installer
application.
application. It must be an absolute path.
.. variable:: CPACK_IFW_PACKAGE_LOGO
Filename for a logo is used as QWizard::LogoPixmap.
Filename for a logo image in PNG format, used as ``QWizard::LogoPixmap``.
It must be an absolute path.
.. variable:: CPACK_IFW_PACKAGE_WATERMARK
.. versionadded:: 3.8
Filename for a watermark is used as QWizard::WatermarkPixmap.
Filename for a watermark image in PNG format, used as
``QWizard::WatermarkPixmap``. It must be an absolute path.
.. variable:: CPACK_IFW_PACKAGE_BANNER
.. versionadded:: 3.8
Filename for a banner is used as QWizard::BannerPixmap.
Filename for a banner image in PNG format, used as ``QWizard::BannerPixmap``.
It must be an absolute path.
.. variable:: CPACK_IFW_PACKAGE_BACKGROUND
.. versionadded:: 3.8
Filename for an image used as QWizard::BackgroundPixmap (only used by MacStyle).
Filename for a background image in PNG format, used as
``QWizard::BackgroundPixmap`` (only used by ``MacStyle``). It must be an
absolute path.
.. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE
.. versionadded:: 3.8
Wizard style to be used ("Modern", "Mac", "Aero" or "Classic").
Wizard style to be used (``Modern``, ``Mac``, ``Aero`` or ``Classic``).
.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH
.. versionadded:: 3.8
Default width of the wizard in pixels. Setting a banner image will override this.
Default width of the wizard in pixels. Setting a banner image will override
this.
.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT
.. versionadded:: 3.8
Default height of the wizard in pixels. Setting a watermark image will override this.
Default height of the wizard in pixels. Setting a watermark image will
override this.
.. variable:: CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST
.. versionadded:: 3.20
Set to ``OFF`` if the widget listing installer pages on the left side of the wizard should not be shown.
Set to ``OFF`` if the widget listing installer pages on the left side of the
wizard should not be shown.
It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or later.
It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or
later.
.. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR
.. versionadded:: 3.8
Color of the titles and subtitles (takes an HTML color code, such as "#88FF33").
Color of the titles and subtitles (takes an HTML color code, such as
``#88FF33``).
.. variable:: CPACK_IFW_PACKAGE_STYLE_SHEET
.. versionadded:: 3.15
Filename for a stylesheet.
Filename for a stylesheet. It must be an absolute path.
.. variable:: CPACK_IFW_TARGET_DIRECTORY
Default target directory for installation.
By default used
"@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`"
(variables embedded in '@' are expanded by the
`QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_).
You can use predefined variables.
If :variable:`CPACK_PACKAGE_INSTALL_DIRECTORY` is set, this defaults to
``@ApplicationsDir@/${CPACK_PACKAGE_INSTALL_DIRECTORY}``. If that variable
isn't set either, the default used is ``@RootDir@/usr/local``.
Predefined variables of the form ``@...@`` are expanded by the
`QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_.
.. variable:: CPACK_IFW_ADMIN_TARGET_DIRECTORY
@ -155,29 +165,28 @@ Package
.. variable:: CPACK_IFW_PACKAGE_GROUP
The group, which will be used to configure the root package
The group, which will be used to configure the root package.
.. variable:: CPACK_IFW_PACKAGE_NAME
The root package name, which will be used if configuration group is not
specified
The root package name, which will be used if the configuration group is not
specified.
.. variable:: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY
.. versionadded:: 3.3
Name of the default program group for the product in the Windows Start menu.
By default used :variable:`CPACK_IFW_PACKAGE_NAME`.
If not specified, it defaults to :variable:`CPACK_IFW_PACKAGE_NAME`.
.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME
.. versionadded:: 3.3
Filename of the generated maintenance tool.
The platform-specific executable file extension is appended.
The platform-specific executable file extension will be appended.
By default used QtIFW defaults (``maintenancetool``).
If not specified, QtIFW provides a default name (``maintenancetool``).
.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE
@ -185,15 +194,15 @@ Package
Filename for the configuration of the generated maintenance tool.
By default used QtIFW defaults (``maintenancetool.ini``).
If not specified, QtIFW uses a default file name (``maintenancetool.ini``).
.. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS
.. versionadded:: 3.3
Set to ``ON`` if the installation path can contain non-ASCII characters.
Is ``ON`` for QtIFW less 2.0 tools.
Only supported for QtIFW 2.0 and later. Older QtIFW versions will always
allow non-ASCII characters.
.. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH
@ -203,6 +212,14 @@ Package
Is ``ON`` for QtIFW less 2.0 tools.
.. variable:: CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE
.. versionadded:: 3.23
Set to ``ON`` if command line interface features should be disabled.
It is ``OFF`` by default and will only have an effect if using QtIFW 4.0 or
later.
.. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT
.. versionadded:: 3.3
@ -213,10 +230,11 @@ Package
.. versionadded:: 3.7
List of additional resources ('.qrc' files) to include in the installer
binary.
List of additional resources (``.qrc`` files) to include in the installer
binary. They should be specified as absolute paths and no two resource files
can have the same file name.
You can use :command:`cpack_ifw_add_package_resources` command to resolve
You can use the :command:`cpack_ifw_add_package_resources` command to resolve
relative paths.
.. variable:: CPACK_IFW_PACKAGE_FILE_EXTENSION
@ -226,27 +244,117 @@ Package
The target binary extension.
On Linux, the name of the target binary is automatically extended with
'.run', if you do not specify the extension.
``.run``, if you do not specify the extension.
On Windows, the target is created as an application with the extension
'.exe', which is automatically added, if not supplied.
``.exe``, which is automatically added, if not supplied.
On Mac, the target is created as an DMG disk image with the extension
'.dmg', which is automatically added, if not supplied.
``.dmg``, which is automatically added, if not supplied.
.. variable:: CPACK_IFW_REPOSITORIES_ALL
The list of remote repositories.
The default value of this variable is computed by CPack and contains
all repositories added with command :command:`cpack_ifw_add_repository`
or updated with command :command:`cpack_ifw_update_repository`.
all repositories added with :command:`cpack_ifw_add_repository`
or updated with :command:`cpack_ifw_update_repository`.
.. variable:: CPACK_IFW_DOWNLOAD_ALL
If this is ``ON`` all components will be downloaded.
By default is ``OFF`` or used value
from ``CPACK_DOWNLOAD_ALL`` if set
If this is ``ON``, all components will be downloaded. If not set, the
behavior is determined by whether :command:`cpack_configure_downloads` has
been called with the ``ALL`` option or not.
.. variable:: CPACK_IFW_PACKAGE_PRODUCT_IMAGES
.. versionadded:: 3.23
A list of images to be shown on the ``PerformInstallationPage``. These
must be absolute paths and the images must be in PNG format.
This feature is available for QtIFW 4.0.0 and later.
.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM
.. versionadded:: 3.23
Command executed after the installer is finished, if the user accepts the
action. Provide the full path to the application, as found when installed.
This typically means the path should begin with the QtIFW predefined variable
``@TargetDir@``.
This feature is available for QtIFW 4.0.0 and later.
.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS
.. versionadded:: 3.23
List of arguments passed to the program specified in
:variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`.
This feature is available for QtIFW 4.0.0 and later.
.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION
.. versionadded:: 3.23
Text shown next to the check box for running the program after the
installation. If :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM` is set but no
description is provided, QtIFW will use a default message like
``Run <Name> now``.
This feature is available for QtIFW 4.0.0 and later.
.. variable:: CPACK_IFW_PACKAGE_SIGNING_IDENTITY
.. versionadded:: 3.23
Allows specifying a code signing identity to be used for signing the generated
app bundle. Only available on macOS, ignored on other platforms.
.. variable:: CPACK_IFW_ARCHIVE_FORMAT
.. versionadded:: 3.23
Set the format used when packaging new component data archives. If you omit
this option, the ``7z`` format will be used as a default. Supported formats:
* 7z
* zip
* tar.gz
* tar.bz2
* tar.xz
.. note::
If the Qt Installer Framework tools were built without libarchive support,
only ``7z`` format is supported.
This feature is available for QtIFW 4.2.0 and later.
.. variable:: CPACK_IFW_ARCHIVE_COMPRESSION
.. versionadded:: 3.23
Archive compression level. The allowable values are:
* 0 (*No compression*)
* 1 (*Fastest compression*)
* 3 (*Fast compression*)
* 5 (*Normal compression*)
* 7 (*Maximum compression*)
* 9 (*Ultra compression*)
If this variable is not set, QtIFW will use a default compression level,
which will typically be 5 (*Normal compression*).
.. note::
Some formats do not support all the possible values. For example ``zip``
compression only supports values from 1 to 7.
This feature is available for QtIFW 4.2.0 and later.
Components
""""""""""
@ -257,16 +365,17 @@ Components
.. variable:: CPACK_IFW_PACKAGES_DIRECTORIES
Additional prepared packages dirs that will be used to resolve
Additional prepared packages directories that will be used to resolve
dependent components.
.. variable:: CPACK_IFW_REPOSITORIES_DIRECTORIES
.. versionadded:: 3.10
Additional prepared repository dirs that will be used to resolve and
repack dependent components. This feature available only
since QtIFW 3.1.
Additional prepared repository directories that will be used to resolve and
repack dependent components.
This feature is available for QtIFW 3.1 and later.
QtIFW Tools
"""""""""""
@ -275,10 +384,11 @@ QtIFW Tools
.. versionadded:: 3.3
The version of used QtIFW tools.
The version of the QtIFW tools that will be used. This variable is set
by the :module:`CPackIFW` module.
The following variables provide the locations of the QtIFW
command-line tools as discovered by the module :module:`CPackIFW`.
command-line tools as discovered by the :module:`CPackIFW` module.
These variables are cached, and may be configured if needed.
.. variable:: CPACK_IFW_ARCHIVEGEN_EXECUTABLE
@ -306,30 +416,33 @@ These variables are cached, and may be configured if needed.
Hints for Finding QtIFW
"""""""""""""""""""""""
Generally, the CPack ``IFW`` generator automatically finds QtIFW tools,
but if you don't use a default path for installation of the QtIFW tools,
the path may be specified in either a CMake or an environment variable:
Generally, the CPack ``IFW`` generator automatically finds QtIFW tools.
The following (in order of precedence) can also be set to augment the
locations normally searched by :command:`find_program`:
.. variable:: CPACK_IFW_ROOT
.. versionadded:: 3.9
.. versionadded:: 3.9
An CMake variable which specifies the location of the QtIFW tool suite.
CMake variable
The variable will be cached in the ``CPackConfig.cmake`` file and used at
CPack runtime.
.. envvar:: CPACK_IFW_ROOT
.. versionadded:: 3.9
Environment variable
.. variable:: QTIFWDIR
An environment variable which specifies the location of the QtIFW tool
suite.
CMake variable
.. envvar:: QTIFWDIR
Environment variable
.. note::
The specified path should not contain "bin" at the end
(for example: "D:\\DevTools\\QtIFW2.0.5").
The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
the value of the :variable:`QTIFWDIR` variable.
The specified path should not contain ``bin`` at the end
(for example: ``D:\\DevTools\\QtIFW2.0.5``).
Other Settings
^^^^^^^^^^^^^^
@ -337,7 +450,7 @@ Other Settings
Online installer
""""""""""""""""
By default, this generator generates an *offline installer*. This means that
By default, this generator generates an *offline installer*. This means
that all packaged files are fully contained in the installer executable.
In contrast, an *online installer* will download some or all components from
@ -367,14 +480,13 @@ CMake script. This is an optional feature.
Installers created by QtIFW tools have built-in support for
internationalization and many phrases are localized to many languages,
but this does not apply to the description of the your components and groups
that will be distributed.
but this does not apply to the description of your components and groups.
Localization of the description of your components and groups is useful for
users of your installers.
A localized variable or argument can contain a single default value, and a
set of pairs the name of the locale and the localized value.
A localized variable or argument can contain a single default value, and
after that a set of pairs with the name of the locale and the localized value.
For example:
@ -392,16 +504,16 @@ See Also
Qt Installer Framework Manual:
* Index page:
http://doc.qt.io/qtinstallerframework/index.html
https://doc.qt.io/qtinstallerframework/index.html
* Component Scripting:
http://doc.qt.io/qtinstallerframework/scripting.html
https://doc.qt.io/qtinstallerframework/scripting.html
* Predefined Variables:
http://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables
https://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables
* Promoting Updates:
http://doc.qt.io/qtinstallerframework/ifw-updates.html
https://doc.qt.io/qtinstallerframework/ifw-updates.html
Download Qt Installer Framework for your platform from Qt site:
http://download.qt.io/official_releases/qt-installer-framework
https://download.qt.io/official_releases/qt-installer-framework

67
Help/cpack_gen/productbuild.rst
View File

@ -18,6 +18,14 @@ macOS using ProductBuild:
the automatically detected command (or specify its location if the
auto-detection fails to find it).
.. variable:: CPACK_PRODUCTBUILD_IDENTIFIER
.. versionadded:: 3.23
Set the unique (non-localized) product identifier to be associated with the
product (i.e., ``com.kitware.cmake``). Any component product names will be
appended to this value.
.. variable:: CPACK_PRODUCTBUILD_IDENTITY_NAME
.. versionadded:: 3.8
@ -78,6 +86,65 @@ macOS using ProductBuild:
:variable:`CPACK_RESOURCE_FILE_README`, and
:variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied.
.. variable:: CPACK_PRODUCTBUILD_DOMAINS
.. versionadded:: 3.23
This option enables more granular control over where the product may be
installed. When it is set to true, a ``domains`` element of the following
form will be added to the productbuild Distribution XML:
.. code-block:: xml
<domains enable_anywhere="true" enable_currentUserHome="false" enable_localSystem="true"/>
The default values are as shown above, but can be overridden with
:variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`,
:variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and
:variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT`.
.. variable:: CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE
.. versionadded:: 3.23
May be used to override the ``enable_anywhere`` attribute in the ``domains``
element of the Distribution XML. When set to true, the product can be
installed at the root of any volume, including non-system volumes.
:variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
to have any effect.
.. variable:: CPACK_PRODUCTBUILD_DOMAINS_USER
.. versionadded:: 3.23
May be used to override the ``enable_currentUserHome`` attribute in the
``domains`` element of the Distribution XML. When set to true, the product
can be installed into the current user's home directory. Note that when
installing into the user's home directory, the following additional
requirements will apply:
* The installer may not write outside the user's home directory.
* The install will be performed as the current user rather than as ``root``.
This may have ramifications for :variable:`CPACK_PREFLIGHT_<COMP>_SCRIPT`
and :variable:`CPACK_POSTFLIGHT_<COMP>_SCRIPT`.
* Administrative privileges will not be needed to perform the install.
:variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
to have any effect.
.. variable:: CPACK_PRODUCTBUILD_DOMAINS_ROOT
.. versionadded:: 3.23
May be used to override the ``enable_localSystem`` attribute in the
``domains`` element of the Distribution XML. When set to true, the product
can be installed in the root directory. This should normally be set to true
unless the product should only be installed to the user's home directory.
:variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
to have any effect.
Background Image
""""""""""""""""

8
Help/cpack_gen/wix.rst
View File

@ -320,3 +320,11 @@ Windows using WiX.
name is the plain namespace without the usual xmlns: prefix and url is an unquoted
namespace url. A list of commonly known WiX schemata can be found here:
https://wixtoolset.org/documentation/manual/v3/xsd/
.. variable:: CPACK_WIX_SKIP_WIX_UI_EXTENSION
.. versionadded:: 3.23
If this variable is set then the inclusion of WixUIExtensions is skipped,
i.e. the ``-ext "WixUIExtension"`` command line is not included during
the execution of the WiX light tool.

61
Help/dev/documentation.rst
View File

@ -513,7 +513,7 @@ bracket is excluded if and only if the line starts in ``#``.
Additional such ``.rst:`` comments may appear anywhere in the module file.
All such comments must start with ``#`` in the first column.
For example, a ``Findxxx.cmake`` module may contain:
For example, a ``FindXxx.cmake`` module may contain:
::
@ -540,13 +540,13 @@ For example, a ``Findxxx.cmake`` module may contain:
<code>
#[=======================================================================[.rst:
.. command:: xxx_do_something
.. command:: Xxx_do_something
This command does something for Xxx::
xxx_do_something(some arguments)
Xxx_do_something(some arguments)
#]=======================================================================]
macro(xxx_do_something)
macro(Xxx_do_something)
<code>
endmacro()
@ -559,3 +559,56 @@ documentation, simply leave out the ``Help/module/<module-name>.rst``
file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.
.. _`Bracket Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#bracket-comment
Module Functions and Macros
---------------------------
Modules may provide CMake functions and macros defined by the `function()`_
and `macro()`_ commands. To avoid conflicts across modules, name the
functions and macros using the prefix ``<ModuleName>_`` followed by the
rest of the name, where ``<ModuleName>`` is the exact-case spelling of
the module name. We have no convention for the portion of names after
the ``<ModuleName>_`` prefix.
For historical reasons, some modules that come with CMake do not follow
this prefix convention. When adding new functions to these modules,
discussion during review can decide whether to follow their existing
convention or to use the module name prefix.
Documentation of public functions and macros should be provided in
the module, typically in the main `module documentation`_ at the top.
For example, a ``MyModule`` module may document a function like this::
#[=======================================================================[.rst:
MyModule
--------
This is my module. It provides some functions.
.. command:: MyModule_Some_Function
This is some function:
.. code-block:: cmake
MyModule_Some_Function(...)
#]=======================================================================]
Documentation may alternatively be placed just before each definition.
For example, a ``MyModule`` module may document another function like this::
#[=======================================================================[.rst:
.. command:: MyModule_Other_Function
This is another function:
.. code-block:: cmake
MyModule_Other_Function(...)
#]=======================================================================]
function(MyModule_Other_Function ...)
# ...
endfunction()
.. _`function()`: https://cmake.org/cmake/help/latest/command/function.html
.. _`macro()`: https://cmake.org/cmake/help/latest/command/macro.html

4
Help/dev/maint.rst
View File

@ -270,8 +270,8 @@ Update ``Source/CMakeVersion.cmake`` to set the version to
set(CMake_VERSION_PATCH 0)
set(CMake_VERSION_RC 0)
Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the
actual version number:
Replace uses of ``DEVEL_CMAKE_VERSION`` in the source tree with
the literal release version number string ``"$major.$minor.0"``:
.. code-block:: shell

3
Help/envvar/CUDAARCHS.rst
View File

@ -6,8 +6,7 @@ CUDAARCHS
.. include:: ENV_VAR.txt
Value used to initialize :variable:`CMAKE_CUDA_ARCHITECTURES` on the first
configuration if it's not already defined. Subsequent runs will use the value
stored in the cache.
configuration. Subsequent runs will use the value stored in the cache.
This is a semicolon-separated list of architectures as described in
:prop_tgt:`CUDA_ARCHITECTURES`.

5
Help/envvar/CUDAHOSTCXX.rst
View File

@ -8,9 +8,8 @@ CUDAHOSTCXX
Preferred executable for compiling host code when compiling ``CUDA``
language files. Will only be used by CMake on the first configuration to
determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is
stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. For any
configuration run (including the first), the environment variable will be
ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined.
stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. This environment
variable is preferred over :variable:`CMAKE_CUDA_HOST_COMPILER`.
This environment variable is primarily meant for use with projects that
enable ``CUDA`` as a first-class language.

29
Help/envvar/DESTDIR.rst
View File

@ -5,17 +5,26 @@ DESTDIR
On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the
whole installation. ``DESTDIR`` means DESTination DIRectory. It is
commonly used by makefile users in order to install software at
non-default location. It is usually invoked like this:
commonly used by packagers to install software in a staging directory.
::
For example, running
make DESTDIR=/home/john install
.. code-block:: shell
which will install the concerned software using the installation
prefix, e.g. ``/usr/local`` prepended with the ``DESTDIR`` value which
finally gives ``/home/john/usr/local``.
make DESTDIR=/package/stage install
WARNING: ``DESTDIR`` may not be used on Windows because installation
prefix usually contains a drive letter like in ``C:/Program Files``
which cannot be prepended with some other prefix.
will install the software using the installation prefix, e.g. ``/usr/local``,
prepended with the ``DESTDIR`` value which gives ``/package/stage/usr/local``.
The packaging tool may then construct the package from the content of the
``/package/stage`` directory.
See the :variable:`CMAKE_INSTALL_PREFIX` variable to control the
installation prefix when configuring a build tree. Or, when using
the :manual:`cmake(1)` command-line tool's ``--install`` mode,
one may specify a different prefix using the ``--prefix`` option.
.. note::
``DESTDIR`` may not be used on Windows because installation
prefix usually contains a drive letter like in ``C:/Program Files``
which cannot be prepended with some other prefix.

130
Help/generator/Green Hills MULTI.rst
View File

@ -8,70 +8,125 @@ Green Hills MULTI
Generates Green Hills MULTI project files (experimental, work-in-progress).
Customizations are available through the following cache variables:
* ``GHS_CUSTOMIZATION``
* ``GHS_GPJ_MACROS``
.. versionadded:: 3.14
The buildsystem has predetermined build-configuration settings that can be controlled
via the :variable:`CMAKE_BUILD_TYPE` variable.
Toolset and Platform Selection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Platform Selection
^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.13
Customizations that are used to pick toolset and target system:
The variable ``GHS_PRIMARY_TARGET`` can be used to select the target platform.
* The ``-A <arch>`` can be supplied for setting the target architecture.
``<arch>`` usually is one of ``arm``, ``ppc``, ``86``, etcetera.
If the target architecture is not specified then
the default architecture of ``arm`` will be used.
| Sets ``primaryTarget`` entry in project file.
* The ``-T <toolset>`` option can be used to set the directory location of the toolset.
Both absolute and relative paths are valid. Relative paths use ``GHS_TOOLSET_ROOT``
as the root. If the toolset is not specified then the latest toolset found in
``GHS_TOOLSET_ROOT`` will be used.
For example:
Cache variables that are used for toolset and target system customization:
* ``cmake -G "Green Hills MULTI" -D GHS_PRIMARY_TARGET=ppc_integrity.tgt``
* ``GHS_TARGET_PLATFORM``
Otherwise the ``primaryTarget`` will be composed from the values of :variable:`CMAKE_GENERATOR_PLATFORM`
and ``GHS_TARGET_PLATFORM``. Defaulting to the value of ``arm_integrity.tgt``
* The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option.
| Typical values of ``arm``, ``ppc``, ``86``, etcetera, are used.
* The variable ``GHS_TARGET_PLATFORM`` may be set, perhaps via the :manual:`cmake(1)`
``-D`` option.
| Defaults to ``integrity``.
| Usual values are ``integrity``, ``threadx``, ``uvelosity``, ``velosity``,
``vxworks``, ``standalone``.
* ``GHS_PRIMARY_TARGET``
For example:
| Sets ``primaryTarget`` entry in project file.
| Defaults to ``<arch>_<GHS_TARGET_PLATFORM>.tgt``.
* ``cmake -G "Green Hills MULTI"`` for ``arm_integrity.tgt``.
* ``cmake -G "Green Hills MULTI" -A 86`` for ``86_integrity.tgt``.
* ``cmake -G "Green Hills MULTI" -D GHS_TARGET_PLATFORM=standalone`` for ``arm_standalone.tgt``.
* ``cmake -G "Green Hills MULTI" -A ppc -D GHS_TARGET_PLATFORM=standalone`` for ``ppc_standalone.tgt``.
* ``GHS_TOOLSET_ROOT``
Toolset Selection
^^^^^^^^^^^^^^^^^
| Root path for ``toolset`` searches.
.. versionadded:: 3.13
The generator searches for the latest compiler or can be given a location to use.
``GHS_TOOLSET_ROOT`` is the directory that is checked for the latest compiler.
* The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :manual:`cmake(1)` ``-T`` option, to specify the location of the toolset.
Both absolute and relative paths are valid. Paths are relative to ``GHS_TOOLSET_ROOT``.
* The variable ``GHS_TOOLSET_ROOT`` may be set, perhaps via the :manual:`cmake(1)`
``-D`` option.
| Root path for toolset searches and relative paths.
| Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux.
For example, setting a specific compiler:
* ``cmake -G "Green Hills MULTI" -T comp_201754`` for ``/usr/ghs/comp_201754``.
* ``cmake -G "Green Hills MULTI" -T comp_201754 -D GHS_TOOLSET_ROOT=/opt/ghs`` for ``/opt/ghs/comp_201754``.
* ``cmake -G "Green Hills MULTI" -T /usr/ghs/comp_201554``
* ``cmake -G "Green Hills MULTI" -T C:/ghs/comp_201754``
For example, searching for latest compiler:
* ``cmake -G "Green Hills MULTI"`` for searching ``/usr/ghs``.
* ``cmake -G "Green Hills MULTI -D GHS_TOOLSET_ROOT=/opt/ghs"`` for searching ``/opt/ghs``.
.. note::
The :variable:`CMAKE_GENERATOR_TOOLSET` should use CMake style paths.
OS and BSP Selection
^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.3
Certain target platforms, like Integrity, require an OS. The RTOS directory path
can be explicitly set using ``GHS_OS_DIR``. Otherwise ``GHS_OS_ROOT`` will be
searched for the latest Integrity RTOS.
If the target platform, like Integrity, requires a BSP name then it can be set via
the ``GHS_BSP_NAME`` variable.
* ``GHS_OS_DIR`` and ``GHS_OS_DIR_OPTION``
| Sets ``-os_dir`` entry in project file.
| ``GHS_OS_DIR_OPTION`` default value is ``-os_dir``.
.. versionadded:: 3.15
The ``GHS_OS_DIR_OPTION`` variable.
For example:
* ``cmake -G "Green Hills MULTI" -D GHS_OS_DIR=/usr/ghs/int1144``
* ``GHS_OS_ROOT``
| Root path for RTOS searches.
| Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux.
* ``GHS_OS_DIR`` and ``GHS_OS_DIR_OPTION``
For example:
| Sets ``-os_dir`` entry in project file.
| Defaults to latest platform OS installation at ``GHS_OS_ROOT``. Set this value if
a specific RTOS is to be used.
| ``GHS_OS_DIR_OPTION`` default value is ``-os_dir``.
.. versionadded:: 3.15
The ``GHS_OS_DIR_OPTION`` variable.
* ``cmake -G "Green Hills MULTI" -D GHS_OS_ROOT=/opt/ghs``
* ``GHS_BSP_NAME``
| Sets ``-bsp`` entry in project file.
| Defaults to ``sim<arch>`` for ``integrity`` platforms.
For example:
* ``cmake -G "Green Hills MULTI"`` for ``simarm`` on ``arm_integrity.tgt``.
* ``cmake -G "Green Hills MULTI" -A 86`` for ``sim86`` on ``86_integrity.tgt``.
* ``cmake -G "Green Hills MULTI" -A ppc -D GHS_BSP_NAME=sim800`` for ``sim800``
on ``ppc_integrity.tgt``.
* ``cmake -G "Green Hills MULTI" -D GHS_PRIMARY_TARGET=ppc_integrity.tgt -D GHS_BSP_NAME=fsl-t1040``
for ``fsl-t1040`` on ``ppc_integrity.tgt``.
Target Properties
^^^^^^^^^^^^^^^^^
@ -82,6 +137,17 @@ The following properties are available:
* :prop_tgt:`GHS_INTEGRITY_APP`
* :prop_tgt:`GHS_NO_SOURCE_GROUP_FILE`
MULTI Project Variables
^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.3
Adding a Customization file and macros are available through the use of the following
variables:
* ``GHS_CUSTOMIZATION`` - CMake path name to Customization File.
* ``GHS_GPJ_MACROS`` - CMake list of Macros.
.. note::
This generator is deemed experimental as of CMake |release|
and is still a work in progress. Future versions of CMake

14
Help/generator/Visual Studio 15 2017.rst
View File

@ -17,18 +17,8 @@ Instance Selection
.. versionadded:: 3.11
VS 2017 supports multiple installations on the same machine.
The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a
cache entry containing the absolute path to a Visual Studio instance.
If the value is not specified explicitly by the user or a toolchain file,
CMake queries the Visual Studio Installer to locate VS instances, chooses
one, and sets the variable as a cache entry to hold the value persistently.
When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment
variable is set and points to the ``Common7/Tools`` directory within
one of the instances, that instance will be used. Otherwise, if more
than one instance is installed we do not define which one is chosen
by default.
VS 2017 supports multiple installations on the same machine. The
:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one.
Platform Selection
^^^^^^^^^^^^^^^^^^

14
Help/generator/Visual Studio 16 2019.rst
View File

@ -15,18 +15,8 @@ Powershell, Python, etc.) are not supported.
Instance Selection
^^^^^^^^^^^^^^^^^^
VS 2019 supports multiple installations on the same machine.
The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a
cache entry containing the absolute path to a Visual Studio instance.
If the value is not specified explicitly by the user or a toolchain file,
CMake queries the Visual Studio Installer to locate VS instances, chooses
one, and sets the variable as a cache entry to hold the value persistently.
When CMake first chooses an instance, if the ``VS160COMNTOOLS`` environment
variable is set and points to the ``Common7/Tools`` directory within
one of the instances, that instance will be used. Otherwise, if more
than one instance is installed we do not define which one is chosen
by default.
VS 2019 supports multiple installations on the same machine. The
:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one.
Platform Selection
^^^^^^^^^^^^^^^^^^

14
Help/generator/Visual Studio 17 2022.rst
View File

@ -15,18 +15,8 @@ Powershell, Python, etc.) are not supported.
Instance Selection
^^^^^^^^^^^^^^^^^^
VS 2022 supports multiple installations on the same machine.
The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a
cache entry containing the absolute path to a Visual Studio instance.
If the value is not specified explicitly by the user or a toolchain file,
CMake queries the Visual Studio Installer to locate VS instances, chooses
one, and sets the variable as a cache entry to hold the value persistently.
When CMake first chooses an instance, if the ``VS170COMNTOOLS`` environment
variable is set and points to the ``Common7/Tools`` directory within
one of the instances, that instance will be used. Otherwise, if more
than one instance is installed we do not define which one is chosen
by default.
VS 2022 supports multiple installations on the same machine. The
:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one.
Platform Selection
^^^^^^^^^^^^^^^^^^

34
Help/guide/ide-integration/index.rst
View File

@ -65,6 +65,12 @@ run:
cmake -S /path/to/source -B /path/to/source/build -G Ninja
In cases where a preset contains lots of cache variables, and passing all of
them as ``-D`` flags would cause the command line length limit of the platform
to be exceeded, the IDE should instead construct a temporary cache script and
pass it with the ``-C`` flag. See :ref:`CMake Options` for details on how the
``-C`` flag is used.
While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is
straightforward, it is not trivial. In addition to the documentation, IDE
vendors may also wish to refer to the CMake source code and test cases for a
@ -124,3 +130,31 @@ obtain this information and use it to present the user with a list of tests.
IDEs should not invoke the ``test`` target of the generated buildsystem.
Instead, they should invoke :manual:`ctest(1)` directly.
IDEs with CMake integration
===========================
The following IDEs support CMake natively:
* `CLion`_
* `KDevelop`_
* `QtCreator`_
* `Vim`_ (via a plugin)
* `Visual Studio`_
* `VSCode`_ (via a plugin)
.. _CLion: https://www.jetbrains.com/clion/
.. _KDevelop: https://www.kdevelop.org/
.. _QtCreator: https://www.qt.io/product/development-tools
.. _Vim: https://www.vim.org/
.. _Visual Studio: https://visualstudio.microsoft.com/
.. _VSCode: https://code.visualstudio.com/
Additionally, CMake has builtin support for some IDEs:
* :ref:`IDE Build Tool Generators`:
Generate IDE native build systems such as Visual Studio or Xcode.
* :ref:`Extra Generators`:
Extend :ref:`Command-Line Build Tool Generators` to generate IDE
project files that hook into the command-line build system.
Superseded by the :manual:`File API <cmake-file-api(7)>`.

4
Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in
View File

@ -1,9 +1,9 @@
@PACKAGE_INIT@
set(_supported_components Addition SquareRoot)
set(_MathFunctions_supported_components Addition SquareRoot)
foreach(_comp ${MathFunctions_FIND_COMPONENTS})
if (NOT _comp IN_LIST _supported_components)
if (NOT _comp IN_LIST _MathFunctions_supported_components)
set(MathFunctions_FOUND False)
set(MathFunctions_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
endif()

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

@ -10,7 +10,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
# add compiler warning flags just when building this project via
# the BUILD_INTERFACE genex
set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>")
set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
target_compile_options(tutorial_compiler_flags INTERFACE
"$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
@ -88,6 +88,7 @@ include(InstallRequiredSystemLibraries)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
set(CPACK_SOURCE_GENERATOR "TGZ")
include(CPack)
# install the configuration targets

4
Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
View File

@ -62,6 +62,6 @@ if(TARGET SqrtLibrary)
list(APPEND installable_libs SqrtLibrary)
endif()
install(TARGETS ${installable_libs}
DESTINATION lib
EXPORT MathFunctionsTargets)
EXPORT MathFunctionsTargets
DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)

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

@ -22,8 +22,9 @@ That is all there is to it. We start by including
libraries that are needed by the project for the current platform. Next we set
some CPack variables to where we have stored the license and version
information for this project. The version information was set earlier in this
tutorial and the ``license.txt`` has been included in the top-level source
directory for this step.
tutorial and the ``License.txt`` has been included in the top-level source
directory for this step. The :variable:`CPACK_SOURCE_GENERATOR` variable
selects a file format for the source package.
Finally we include the :module:`CPack module <CPack>` which will use these
variables and some other properties of the current system to setup an
@ -44,7 +45,11 @@ To specify the generator, use the ``-G`` option. For multi-config builds, use
cpack -G ZIP -C Debug
To create a source distribution you would type:
For a list of available generators, see :manual:`cpack-generators(7)` or call
``cpack --help``. An :cpack_gen:`archive generator <CPack Archive Generator>`
like ZIP creates a compressed archive of all *installed* files.
To create an archive of the *full* source tree you would type:
.. code-block:: console

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

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

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

@ -8,7 +8,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
# add compiler warning flags just when building this project via
# the BUILD_INTERFACE genex
set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>")
set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
target_compile_options(tutorial_compiler_flags INTERFACE
"$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
@ -78,4 +78,5 @@ include(InstallRequiredSystemLibraries)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
set(CPACK_SOURCE_GENERATOR "TGZ")
include(CPack)

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

@ -8,7 +8,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
# add compiler warning flags just when building this project via
# the BUILD_INTERFACE genex
set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>")
set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
target_compile_options(tutorial_compiler_flags INTERFACE
"$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"

4
Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt
View File

@ -58,6 +58,6 @@ if(TARGET SqrtLibrary)
list(APPEND installable_libs SqrtLibrary)
endif()
install(TARGETS ${installable_libs}
DESTINATION lib
EXPORT MathFunctionsTargets)
EXPORT MathFunctionsTargets
DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)

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

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

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

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

6
Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
View File

@ -1,11 +1,11 @@
Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the
|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
Note that it is not advisable to populate the :genex:`INSTALL_INTERFACE` of
the |INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
directories of dependencies. That would hard-code into installed packages
the include directory paths for dependencies
**as found on the machine the package was made on**.
The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only
The :genex:`INSTALL_INTERFACE` of the |INTERFACE_PROPERTY_LINK| is only
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target

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

@ -675,7 +675,9 @@ listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the
dependency. This can result in omission of compiler warnings for headers
found in those directories. This behavior for :ref:`imported targets` may
be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target
property on the *consumers* of imported targets.
property on the *consumers* of imported targets, or by setting the
:prop_tgt:`IMPORTED_NO_SYSTEM` target property on the imported targets
themselves.
If a binary target is linked transitively to a macOS :prop_tgt:`FRAMEWORK`, the
``Headers`` directory of the framework is also treated as a usage requirement.

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

@ -115,6 +115,8 @@ of at-least C++ 11 (or C++ 14, C++ 17, ...), adding flags such as
``-std=gnu++11`` if necessary. This applies to sources within ``mylib``
as well as any dependents (that may include headers from ``mylib``).
.. include:: ../prop_gbl/CMAKE_LANG_STD_FLAGS.txt
Availability of Compiler Extensions
-----------------------------------

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

@ -425,7 +425,7 @@ Version 1 does not exist to avoid confusion with that from
{
"kind": "codemodel",
"version": { "major": 2, "minor": 2 },
"version": { "major": 2, "minor": 4 },
"paths": {
"source": "/path/to/top-level-source-dir",
"build": "/path/to/top-level-build-dir"
@ -758,6 +758,15 @@ with members:
``destination`` member is populated. This type has additional members
``runtimeDependencySetName`` and ``runtimeDependencySetType``.
``fileSet``
An :command:`install(TARGETS)` call with ``FILE_SET``.
The ``destination`` and ``paths`` members are populated.
The ``isOptional`` member may exist.
This type has additional members ``fileSetName``, ``fileSetType``,
``fileSetDirectories``, and ``fileSetTarget``.
This type was added in codemodel version 2.4.
``isExcludeFromAll``
Optional member that is present with boolean value ``true`` when
:command:`install` is called with the ``EXCLUDE_FROM_ALL`` option.
@ -835,6 +844,41 @@ with members:
Indicates that this installer installs dependencies that are macOS
frameworks.
``fileSetName``
Optional member that is present when ``type`` is ``fileSet``. The value is
a string with the name of the file set.
This field was added in codemodel version 2.4.
``fileSetType``
Optional member that is present when ``type`` is ``fileSet``. The value is
a string with the type of the file set.
This field was added in codemodel version 2.4.
``fileSetDirectories``
Optional member that is present when ``type`` is ``fileSet``. The value
is a list of strings with the file set's base directories (determined by
genex-evaluation of :prop_tgt:`HEADER_DIRS` or
:prop_tgt:`HEADER_DIRS_<NAME>`).
This field was added in codemodel version 2.4.
``fileSetTarget``
Optional member that is present when ``type`` is ``fileSet``. The value
is a JSON object with members:
``id``
A string uniquely identifying the target. This matches
the ``id`` member of the target in the main "codemodel"
object's ``targets`` array.
``index``
An unsigned integer 0-based index into the main "codemodel"
object's ``targets`` array for the target.
This field was added in codemodel version 2.4.
``scriptFile``
Optional member that is present when ``type`` is ``script``.
The value is a string specifying the path to the script file on disk,

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

@ -102,6 +102,8 @@ Other Generators
/generator/Green Hills MULTI
/generator/Xcode
.. _`Extra Generators`:
Extra Generators
================

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

@ -627,3 +627,45 @@ in list elements, thus flattening nested lists:
.. code-block:: cmake
set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"
In general, lists do not support elements containing ``;`` characters.
To avoid problems, consider the following advice:
* The interfaces of many CMake commands, variables, and properties accept
semicolon-separated lists. Avoid passing lists with elements containing
semicolons to these interfaces unless they document either direct support
or some way to escape or encode semicolons.
* When constructing a list, substitute an otherwise-unused placeholder
for ``;`` in elements when. Then substitute ``;`` for the placeholder
when processing list elements.
For example, the following code uses ``|`` in place of ``;`` characters:
.. code-block:: cmake
set(mylist a "b|c")
foreach(entry IN LISTS mylist)
string(REPLACE "|" ";" entry "${entry}")
# use "${entry}" normally
endforeach()
The :module:`ExternalProject` module's ``LIST_SEPARATOR`` option is an
example of an interface built using this approach.
* In lists of :manual:`generator expressions <cmake-generator-expressions(7)>`,
use the :genex:`$<SEMICOLON>` generator expression.
* In command calls, use `Quoted Argument`_ syntax whenever possible.
The called command will receive the content of the argument with
semicolons preserved. An `Unquoted Argument`_ will be split on
semicolons.
* In :command:`function` implementations, avoid ``ARGV`` and ``ARGN``,
which do not distinguish semicolons in values from those separating values.
Instead, prefer using named positional arguments and the ``ARGC`` and
``ARGV#`` variables.
When using :command:`cmake_parse_arguments` to parse arguments, prefer
its ``PARSE_ARGV`` signature, which uses the ``ARGV#`` variables.
Note that this approach does not apply to :command:`macro` implementations
because they reference arguments using placeholders, not real variables.

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

@ -446,10 +446,10 @@ be true. This can be tested with logic in the package configuration file:
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")
set(_supported_components Plot Table)
set(_ClimbingStats_supported_components Plot Table)
foreach(_comp ${ClimbingStats_FIND_COMPONENTS})
if (NOT ";${_supported_components};" MATCHES ";${_comp};")
if (NOT ";${_ClimbingStats_supported_components};" MATCHES ";${_comp};")
set(ClimbingStats_FOUND False)
set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
endif()

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

@ -51,6 +51,15 @@ 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.23
=================================
.. toctree::
:maxdepth: 1
CMP0129: Compiler id for MCST LCC compilers is now LCC, not GNU. </policy/CMP0129>
Policies Introduced by CMake 3.22
=================================

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

@ -12,18 +12,21 @@ Introduction
One problem that CMake users often face is sharing settings with other people
for common ways to configure a project. This may be done to support CI builds,
or for users who frequently use the same build. CMake supports two files,
or for users who frequently use the same build. CMake supports two main files,
``CMakePresets.json`` and ``CMakeUserPresets.json``, that allow users to
specify common configure options and share them with others.
specify common configure options and share them with others. CMake also
supports files included with the ``include`` field.
``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root
directory. They both have exactly the same format, and both are optional
(though at least one must be present if ``--preset`` is specified.)
``CMakePresets.json`` is meant to save project-wide builds, while
``CMakeUserPresets.json`` is meant for developers to save their own local
builds. ``CMakePresets.json`` may be checked into a version control system, and
``CMakeUserPresets.json`` should NOT be checked in. For example, if a project
is using Git, ``CMakePresets.json`` may be tracked, and
(though at least one must be present if ``--preset`` is specified).
``CMakePresets.json`` is meant to specify project-wide build details, while
``CMakeUserPresets.json`` is meant for developers to specify their own local
build details.
``CMakePresets.json`` may be checked into a version control system, and
``CMakeUserPresets.json`` should NOT be checked in. For example, if a
project is using Git, ``CMakePresets.json`` may be tracked, and
``CMakeUserPresets.json`` should be added to the ``.gitignore``.
Format
@ -39,7 +42,7 @@ The root object recognizes the following fields:
``version``
A required integer representing the version of the JSON schema.
The supported versions are ``1``, ``2``, and ``3``.
The supported versions are ``1``, ``2``, ``3``, and ``4``.
``cmakeMinimumRequired``
@ -58,6 +61,13 @@ The root object recognizes the following fields:
An optional integer representing the patch version.
``include``
An optional array of strings representing files to include. If the filenames
are not absolute, they are considered relative to the current file.
This is allowed in preset files specifying version ``4`` or above.
See `Includes`_ for discussion of the constraints on included files.
``vendor``
An optional map containing vendor-specific information. CMake does not
@ -82,6 +92,26 @@ The root object recognizes the following fields:
An optional array of `Test Preset`_ objects.
This is allowed in preset files specifying version ``2`` or above.
Includes
^^^^^^^^
``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files
with the ``include`` field in file version ``4`` and later. Files included
by these files can also include other files. If ``CMakePresets.json`` and
``CMakeUserPresets.json`` are both present, ``CMakeUserPresets.json``
implicitly includes ``CMakePresets.json``, even with no ``include`` field,
in all versions of the format.
If a preset file contains presets that inherit from presets in another file,
the file must include the other file either directly or indirectly.
Include cycles are not allowed among files. If ``a.json`` includes
``b.json``, ``b.json`` cannot include ``a.json``. However, a file may be
included multiple times from the same file or from different files.
Files directly or indirectly included from ``CMakePresets.json`` should be
guaranteed to be provided by the project. ``CMakeUserPresets.json`` may
include files from anywhere.
Configure Preset
^^^^^^^^^^^^^^^^
@ -108,16 +138,20 @@ that may contain the following fields:
``inherits``
An optional array of strings representing the names of presets to inherit
from. The preset will inherit all of the fields from the ``inherits``
from. This field can also be a string, which is equivalent to an array
containing one string.
The preset will inherit all of the fields from the ``inherits``
presets by default (except ``name``, ``hidden``, ``inherits``,
``description``, and ``displayName``), but can override them as
desired. If multiple ``inherits`` presets provide conflicting values for
the same field, the earlier preset in the ``inherits`` list will be
preferred. Presets in ``CMakePresets.json`` may not inherit from presets
in ``CMakeUserPresets.json``.
preferred.
This field can also be a string, which is equivalent to an array
containing one string.
A preset can only inherit from another preset that is defined in the
same file or in one of the files it includes (directly or indirectly).
Presets in ``CMakePresets.json`` may not inherit from presets in
``CMakeUserPresets.json``.
``condition``
@ -350,17 +384,21 @@ that may contain the following fields:
``inherits``
An optional array of strings representing the names of presets to
inherit from. The preset will inherit all of the fields from the
An optional array of strings representing the names of presets to inherit
from. This field can also be a string, which is equivalent to an array
containing one string.
The preset will inherit all of the fields from the
``inherits`` presets by default (except ``name``, ``hidden``,
``inherits``, ``description``, and ``displayName``), but can override
them as desired. If multiple ``inherits`` presets provide conflicting
values for the same field, the earlier preset in the ``inherits`` list
will be preferred. Presets in ``CMakePresets.json`` may not inherit from
presets in ``CMakeUserPresets.json``.
will be preferred.
This field can also be a string, which is equivalent to an array
containing one string.
A preset can only inherit from another preset that is defined in the
same file or in one of the files it includes (directly or indirectly).
Presets in ``CMakePresets.json`` may not inherit from presets in
``CMakeUserPresets.json``.
``condition``
@ -453,6 +491,42 @@ that may contain the following fields:
An optional bool. If true, equivalent to passing ``--clean-first`` on
the command line.
``resolvePackageReferences``
An optional string that specifies the package resolve mode. This is
allowed in preset files specifying version ``4`` or above.
Package references are used to define dependencies to packages from
external package managers. Currently only NuGet in combination with the
Visual Studio generator is supported. If there are no targets that define
package references, this option does nothing. Valid values are:
``on``
Causes package references to be resolved before attempting a build.
``off``
Package references will not be resolved. Note that this may cause
errors in some build environments, such as .NET SDK style projects.
``only``
Only resolve package references, but do not perform a build.
.. note::
The command line parameter ``--resolve-package-references`` will take
priority over this setting. If the command line parameter is not provided
and this setting is not specified, an environment-specific cache variable
will be evaluated to decide, if package restoration should be performed.
When using the Visual Studio generator, package references are defined
using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references
are restored using NuGet. It can be disabled by setting the
``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. This can also be
done from within a configure preset.
``verbose``
An optional bool. If true, equivalent to passing ``--verbose`` on the
@ -487,17 +561,21 @@ that may contain the following fields:
``inherits``
An optional array of strings representing the names of presets to
inherit from. The preset will inherit all of the fields from the
An optional array of strings representing the names of presets to inherit
from. This field can also be a string, which is equivalent to an array
containing one string.
The preset will inherit all of the fields from the
``inherits`` presets by default (except ``name``, ``hidden``,
``inherits``, ``description``, and ``displayName``), but can override
them as desired. If multiple ``inherits`` presets provide conflicting
values for the same field, the earlier preset in the ``inherits`` list
will be preferred. Presets in ``CMakePresets.json`` may not inherit from
presets in ``CMakeUserPresets.json``.
will be preferred.
This field can also be a string, which is equivalent to an array
containing one string.
A preset can only inherit from another preset that is defined in the
same file or in one of the files it includes (directly or indirectly).
Presets in ``CMakePresets.json`` may not inherit from presets in
``CMakeUserPresets.json``.
``condition``
@ -947,7 +1025,8 @@ Recognized macros include:
``${sourceDir}``
Path to the project source directory.
Path to the project source directory (i.e. the same as
:variable:`CMAKE_SOURCE_DIR`).
``${sourceParentDir}``
@ -974,6 +1053,11 @@ Recognized macros include:
:variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files
specifying version ``3`` or above.
``${fileDir}``
Path to the directory containing the preset file which contains the macro.
This is allowed in preset files specifying version ``4`` or above.
``${dollar}``
A literal dollar sign (``$``).

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

@ -191,6 +191,7 @@ Properties on Targets
/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY
/prop_tgt/DEPRECATION
/prop_tgt/DISABLE_PRECOMPILE_HEADERS
/prop_tgt/DOTNET_SDK
/prop_tgt/DOTNET_TARGET_FRAMEWORK
/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION
/prop_tgt/EchoString
@ -214,6 +215,11 @@ Properties on Targets
/prop_tgt/GHS_NO_SOURCE_GROUP_FILE
/prop_tgt/GNUtoMS
/prop_tgt/HAS_CXX
/prop_tgt/HEADER_DIRS
/prop_tgt/HEADER_DIRS_NAME
/prop_tgt/HEADER_SET
/prop_tgt/HEADER_SET_NAME
/prop_tgt/HEADER_SETS
/prop_tgt/HIP_ARCHITECTURES
/prop_tgt/HIP_EXTENSIONS
/prop_tgt/HIP_STANDARD
@ -239,6 +245,7 @@ Properties on Targets
/prop_tgt/IMPORTED_LOCATION_CONFIG
/prop_tgt/IMPORTED_NO_SONAME
/prop_tgt/IMPORTED_NO_SONAME_CONFIG
/prop_tgt/IMPORTED_NO_SYSTEM
/prop_tgt/IMPORTED_OBJECTS
/prop_tgt/IMPORTED_OBJECTS_CONFIG
/prop_tgt/IMPORTED_SONAME
@ -254,6 +261,7 @@ Properties on Targets
/prop_tgt/INTERFACE_COMPILE_DEFINITIONS
/prop_tgt/INTERFACE_COMPILE_FEATURES
/prop_tgt/INTERFACE_COMPILE_OPTIONS
/prop_tgt/INTERFACE_HEADER_SETS
/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES
/prop_tgt/INTERFACE_LINK_DEPENDS
/prop_tgt/INTERFACE_LINK_DIRECTORIES
@ -297,6 +305,7 @@ Properties on Targets
/prop_tgt/LINK_INTERFACE_MULTIPLICITY
/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG
/prop_tgt/LINK_LIBRARIES
/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS
/prop_tgt/LINK_OPTIONS
/prop_tgt/LINK_SEARCH_END_STATIC
/prop_tgt/LINK_SEARCH_START_STATIC
@ -425,6 +434,7 @@ Properties on Targets
/prop_tgt/XCODE_SCHEME_ARGUMENTS
/prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT
/prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
/prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
/prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
/prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
/prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE

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

@ -49,6 +49,7 @@ Variables that Provide Information
/variable/CMAKE_DEBUG_TARGET_PROPERTIES
/variable/CMAKE_DIRECTORY_LABELS
/variable/CMAKE_DL_LIBS
/variable/CMAKE_DOTNET_SDK
/variable/CMAKE_DOTNET_TARGET_FRAMEWORK
/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION
/variable/CMAKE_EDIT_COMMAND
@ -118,6 +119,7 @@ Variables that Provide Information
/variable/CMAKE_VS_DEVENV_COMMAND
/variable/CMAKE_VS_MSBUILD_COMMAND
/variable/CMAKE_VS_NsightTegra_VERSION
/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE
/variable/CMAKE_VS_PLATFORM_NAME
/variable/CMAKE_VS_PLATFORM_NAME_DEFAULT
/variable/CMAKE_VS_PLATFORM_TOOLSET
@ -210,6 +212,7 @@ Variables that Change Behavior
/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY
/variable/CMAKE_FRAMEWORK_PATH
/variable/CMAKE_IGNORE_PATH
/variable/CMAKE_IGNORE_PREFIX_PATH
/variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE
/variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE
/variable/CMAKE_INCLUDE_PATH
@ -220,6 +223,7 @@ Variables that Change Behavior
/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
/variable/CMAKE_LIBRARY_PATH
/variable/CMAKE_LINK_DIRECTORIES_BEFORE
/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS
/variable/CMAKE_MFC_FLAG
/variable/CMAKE_MAXIMUM_RECURSION_DEPTH
/variable/CMAKE_MESSAGE_CONTEXT
@ -247,6 +251,7 @@ Variables that Change Behavior
/variable/CMAKE_SYSTEM_APPBUNDLE_PATH
/variable/CMAKE_SYSTEM_FRAMEWORK_PATH
/variable/CMAKE_SYSTEM_IGNORE_PATH
/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH
/variable/CMAKE_SYSTEM_INCLUDE_PATH
/variable/CMAKE_SYSTEM_LIBRARY_PATH
/variable/CMAKE_SYSTEM_PREFIX_PATH
@ -262,6 +267,7 @@ Variables that Change Behavior
/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
/variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
@ -307,7 +313,7 @@ Variables that Describe the System
/variable/CMAKE_SYSTEM_PROCESSOR
/variable/CMAKE_SYSTEM_VERSION
/variable/CYGWIN
/variable/GHS-MULTI
/variable/GHSMULTI
/variable/IOS
/variable/MINGW
/variable/MSVC
@ -466,6 +472,7 @@ Variables that Control the Build
/variable/CMAKE_PCH_INSTANTIATE_TEMPLATES
/variable/CMAKE_PDB_OUTPUT_DIRECTORY
/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME
/variable/CMAKE_POSITION_INDEPENDENT_CODE
/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY
/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG
@ -578,8 +585,6 @@ Variables for Languages
/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES
/variable/CMAKE_LANG_LIBRARY_ARCHITECTURE
/variable/CMAKE_LANG_LINK_EXECUTABLE
/variable/CMAKE_LANG_LINKER_PREFERENCE
/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES
/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG
/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP
/variable/CMAKE_LANG_OUTPUT_EXTENSION
@ -668,6 +673,7 @@ Variables for CTest
/variable/CTEST_SCP_COMMAND
/variable/CTEST_SCRIPT_DIRECTORY
/variable/CTEST_SITE
/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT
/variable/CTEST_SUBMIT_URL
/variable/CTEST_SOURCE_DIRECTORY
/variable/CTEST_SVN_COMMAND
@ -723,6 +729,8 @@ are subject to change, and not recommended for use in project code.
/variable/CMAKE_LANG_COMPILER_ABI
/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID
/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL
/variable/CMAKE_LANG_LINKER_PREFERENCE
/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES
/variable/CMAKE_LANG_PLATFORM_ID
/variable/CMAKE_NOT_USING_CONFIG_FLAGS
/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION

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

@ -151,6 +151,33 @@ source and build trees and generate a buildsystem:
In all cases the ``<options>`` may be zero or more of the `Options`_ below.
The above styles for specifying the source and build trees may be mixed.
Paths specified with ``-S`` or ``-B`` are always classified as source or
build trees, respectively. Paths specified with plain arguments are
classified based on their content and the types of paths given earlier.
If only one type of path is given, the current working directory (cwd)
is used for the other. For example:
============================== ============ ===========
Command Line Source Dir Build Dir
============================== ============ ===========
``cmake src`` ``src`` `cwd`
``cmake build`` (existing) `loaded` ``build``
``cmake -S src`` ``src`` `cwd`
``cmake -S src build`` ``src`` ``build``
``cmake -S src -B build`` ``src`` ``build``
``cmake -B build`` `cwd` ``build``
``cmake -B build src`` ``src`` ``build``
``cmake -B build -S src`` ``src`` ``build``
============================== ============ ===========
.. versionchanged:: 3.23
CMake warns when multiple source paths are specified. This has never
been officially documented or supported, but older versions accidentally
accepted multiple source paths and used the last path specified.
Avoid passing multiple source path arguments.
After generating a buildsystem one may use the corresponding native
build tool to build the project. For example, after using the
:generator:`Unix Makefiles` generator one may run ``make`` directly:
@ -250,6 +277,21 @@ Options
See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging
a more local part of the project.
``--debug-find-pkg=<pkg>[,...]``
Put cmake find commands in a debug mode when running under calls
to :command:`find_package(\<pkg\>) <find_package>`, where ``<pkg>``
is an entry in the given comma-separated list of case-sensitive package
names.
Like ``--debug-find``, but limiting scope to the specified packages.
``--debug-find-var=<var>[,...]``
Put cmake find commands in a debug mode when called with ``<var>``
as the result variable, where ``<var>`` is an entry in the given
comma-separated list.
Like ``--debug-find``, but limiting scope to the specified variable names.
``--trace``
Put cmake in trace mode.
@ -449,6 +491,29 @@ following options:
Build target ``clean`` first, then build.
(To clean only, use ``--target clean``.)
``--resolve-package-references=<on|off|only>``
.. versionadded:: 3.23
Resolve remote package references from external package managers (e.g. NuGet)
before build. When set to ``on`` (default), packages will be restored before
building a target. When set to ``only``, the packages will be restored, but no
build will be performed. When set to ``off``, no packages will be restored.
If the target does not define any package references, this option does nothing.
This setting can be specified in a build preset (using
``resolvePackageReferences``). The preset setting will be ignored, if this
command line option is specified.
If no command line parameter or preset option are provided, an environment-
specific cache variable will be evaluated to decide, if package restoration
should be performed.
When using the Visual Studio generator, package references are defined
using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references
are restored using NuGet. It can be disabled by setting the
``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``.
``--use-stderr``
Ignored. Behavior is default in CMake >= 3.0.
@ -547,6 +612,8 @@ Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
Available commands are:
``capabilities``
.. versionadded:: 3.7
Report cmake capabilities in JSON format. The output is a JSON object
with the following keys:
@ -607,6 +674,8 @@ Available commands are:
Always false since CMake 3.20.
``cat <files>...``
.. versionadded:: 3.18
Concatenate files and print on the standard output.
``chdir <dir> <cmd> [<arg>...]``
@ -615,8 +684,11 @@ Available commands are:
``compare_files [--ignore-eol] <file1> <file2>``
Check if ``<file1>`` is same as ``<file2>``. If files are the same,
then returns ``0``, if not it returns ``1``. In case of invalid
arguments, it returns 2. The ``--ignore-eol`` option
implies line-wise comparison and ignores LF/CRLF differences.
arguments, it returns 2.
.. versionadded:: 3.14
The ``--ignore-eol`` option implies line-wise comparison and ignores
LF/CRLF differences.
``copy <file>... <destination>``
Copy files to ``<destination>`` (either file or directory).
@ -625,11 +697,21 @@ Available commands are:
``copy`` does follow symlinks. That means it does not copy symlinks,
but the files or directories it point to.
.. versionadded:: 3.5
Support for multiple input files.
``copy_directory <dir>... <destination>``
Copy content of ``<dir>...`` directories to ``<destination>`` directory.
If ``<destination>`` directory does not exist it will be created.
``copy_directory`` does follow symlinks.
.. versionadded:: 3.5
Support for multiple input directories.
.. versionadded:: 3.15
The command now fails when the source directory does not exist.
Previously it succeeded by creating an empty destination directory.
``copy_if_different <file>... <destination>``
Copy files to ``<destination>`` (either file or directory) if
they have changed.
@ -637,13 +719,21 @@ Available commands are:
directory and it must exist.
``copy_if_different`` does follow symlinks.
.. versionadded:: 3.5
Support for multiple input files.
``create_symlink <old> <new>``
Create a symbolic link ``<new>`` naming ``<old>``.
.. versionadded:: 3.13
Support for creating symlinks on Windows.
.. note::
Path to where ``<new>`` symbolic link will be created has to exist beforehand.
``create_hardlink <old> <new>``
.. versionadded:: 3.19
Create a hard link ``<new>`` naming ``<old>``.
.. note::
@ -657,12 +747,16 @@ Available commands are:
Displays arguments as text but no new line.
``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...``
.. versionadded:: 3.1
Run command in a modified environment.
``environment``
Display the current environment variables.
``false``
.. versionadded:: 3.16
Do nothing, with an exit code of 1.
``make_directory <dir>...``
@ -670,6 +764,9 @@ Available commands are:
directories too. If a directory already exists it will be
silently ignored.
.. versionadded:: 3.5
Support for multiple input directories.
``md5sum <file>...``
Create MD5 checksum of files in ``md5sum`` compatible format::
@ -677,30 +774,40 @@ Available commands are:
052f86c15bbde68af55c7f7b340ab639 file2.txt
``sha1sum <file>...``
.. versionadded:: 3.10
Create SHA1 checksum of files in ``sha1sum`` compatible format::
4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt
1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt
``sha224sum <file>...``
.. versionadded:: 3.10
Create SHA224 checksum of files in ``sha224sum`` compatible format::
b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt
6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt
``sha256sum <file>...``
.. versionadded:: 3.10
Create SHA256 checksum of files in ``sha256sum`` compatible format::
76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt
15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt
``sha384sum <file>...``
.. versionadded:: 3.10
Create SHA384 checksum of files in ``sha384sum`` compatible format::
acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt
668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt
``sha512sum <file>...``
.. versionadded:: 3.10
Create SHA512 checksum of files in ``sha512sum`` compatible format::
2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt
@ -723,16 +830,24 @@ Available commands are:
.. deprecated:: 3.17
Remove ``<dir>`` directories and their contents. If a directory does
not exist it will be silently ignored. If ``<dir>`` is a symlink to
a directory, just the symlink will be removed.
not exist it will be silently ignored.
Use ``rm`` instead.
.. versionadded:: 3.15
Support for multiple directories.
.. versionadded:: 3.16
If ``<dir>`` is a symlink to a directory, just the symlink will be removed.
``rename <oldname> <newname>``
Rename a file or directory (on one volume). If file with the ``<newname>`` name
already exists, then it will be silently replaced.
``rm [-rRf] <file> <dir>...``
Remove the files ``<file>`` or directories ``dir``.
.. versionadded:: 3.17
Remove the files ``<file>`` or directories ``<dir>``.
Use ``-r`` or ``-R`` to remove directories and their contents recursively.
If any of the listed files/directories do not exist, the command returns a
non-zero exit code, but no message is logged. The ``-f`` option changes
@ -743,6 +858,8 @@ Available commands are:
Launch :manual:`cmake-server(7)` mode.
``sleep <number>...``
.. versionadded:: 3.0
Sleep for given number of seconds.
``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]``
@ -751,45 +868,85 @@ Available commands are:
``c``
Create a new archive containing the specified files.
If used, the ``<pathname>...`` argument is mandatory.
``x``
Extract to disk from the archive.
The ``<pathname>...`` argument could be used to extract only selected files
or directories.
When extracting selected files or directories, you must provide their exact
names including the path, as printed by list (``-t``).
.. versionadded:: 3.15
The ``<pathname>...`` argument could be used to extract only selected files
or directories.
When extracting selected files or directories, you must provide their exact
names including the path, as printed by list (``-t``).
``t``
List archive contents.
The ``<pathname>...`` argument could be used to list only selected files
or directories.
.. versionadded:: 3.15
The ``<pathname>...`` argument could be used to list only selected files
or directories.
``v``
Produce verbose output.
``z``
Compress the resulting archive with gzip.
``j``
Compress the resulting archive with bzip2.
``J``
.. versionadded:: 3.1
Compress the resulting archive with XZ.
``--zstd``
.. versionadded:: 3.15
Compress the resulting archive with Zstandard.
``--files-from=<file>``
.. versionadded:: 3.1
Read file names from the given file, one per line.
Blank lines are ignored. Lines may not start in ``-``
except for ``--add-file=<name>`` to add files whose
names start in ``-``.
``--format=<format>``
.. versionadded:: 3.3
Specify the format of the archive to be created.
Supported formats are: ``7zip``, ``gnutar``, ``pax``,
``paxr`` (restricted pax, default), and ``zip``.
``--mtime=<date>``
.. versionadded:: 3.1
Specify modification time recorded in tarball entries.
``--``
.. versionadded:: 3.1
Stop interpreting options and treat all remaining arguments
as file names, even if they start with ``-``.
.. versionadded:: 3.1
LZMA (7zip) support.
.. versionadded:: 3.15
The command now continues adding files to an archive even if some of the
files are not readable. This behavior is more consistent with the classic
``tar`` tool. The command now also parses all flags, and if an invalid flag
was provided, a warning is issued.
``time <command> [<args>...]``
Run command and display elapsed time.
.. versionadded:: 3.5
The command now properly passes arguments with spaces or special characters
through to the child process. This may break scripts that worked around the
bug with their own extra quoting or escaping.
``touch <file>...``
Creates ``<file>`` if file do not exist.
If ``<file>`` exists, it is changing ``<file>`` access and modification times.
@ -799,6 +956,8 @@ Available commands are:
not exist it will be silently ignored.
``true``
.. versionadded:: 3.16
Do nothing, with an exit code of 0.
Windows-specific Command-Line Tools
@ -810,10 +969,14 @@ The following ``cmake -E`` commands are available only on Windows:
Delete Windows registry value.
``env_vs8_wince <sdkname>``
.. versionadded:: 3.2
Displays a batch file which sets the environment for the provided
Windows CE SDK installed in VS2005.
``env_vs9_wince <sdkname>``
.. versionadded:: 3.2
Displays a batch file which sets the environment for the provided
Windows CE SDK installed in VS2008.

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

@ -1353,6 +1353,13 @@ Configuration settings include:
* :module:`CTest` module variable: ``SUBMIT_URL`` if set,
else ``CTEST_SUBMIT_URL``
``SubmitInactivityTimeout``
The time to wait for the submission after which it is canceled
if not completed. Specify a zero value to disable timeout.
* `CTest Script`_ variable: :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT`
* :module:`CTest` module variable: ``CTEST_SUBMIT_INACTIVITY_TIMEOUT``
``TriggerSite``
Legacy option. Not used.

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

@ -1,10 +1,14 @@
{
"version": 3,
"version": 4,
"cmakeMinimumRequired": {
"major": 3,
"minor": 21,
"minor": 23,
"patch": 0
},
"include": [
"otherThings.json",
"moreThings.json"
],
"configurePresets": [
{
"name": "default",

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

@ -42,6 +42,21 @@
"testPresets": { "$ref": "#/definitions/testPresetsV3"}
},
"additionalProperties": false
},
{
"properties": {
"version": {
"const": 4,
"description": "A required integer representing the version of the JSON schema."
},
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
"vendor": { "$ref": "#/definitions/vendor" },
"configurePresets": { "$ref": "#/definitions/configurePresetsV3"},
"buildPresets": { "$ref": "#/definitions/buildPresetsV4"},
"testPresets": { "$ref": "#/definitions/testPresetsV3"},
"include": { "$ref": "#/definitions/include"}
},
"additionalProperties": false
}
],
"required": [
@ -412,9 +427,25 @@
"additionalProperties": false
}
},
"buildPresetsItemsV4": {
"type": "array",
"description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.",
"items": {
"type": "object",
"properties": {
"resolvePackageReferences": {
"type": "string",
"description": "An optional string specifying the package resolve behavior. Valid values are \"on\" (packages are resolved prior to the build), \"off\" (packages are not resolved prior to the build), and \"only\" (packages are resolved, but no build will be performed).",
"enum": [
"on", "off", "only"
]
}
}
}
},
"buildPresetsItemsV3": {
"type": "array",
"description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
"description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.",
"items": {
"type": "object",
"properties": {
@ -543,9 +574,44 @@
]
}
},
"buildPresetsV4": {
"type": "array",
"description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.",
"allOf": [
{ "$ref": "#/definitions/buildPresetsItemsV4" },
{ "$ref": "#/definitions/buildPresetsItemsV3" },
{ "$ref": "#/definitions/buildPresetsItemsV2" }
],
"items": {
"type": "object",
"properties": {
"name": {},
"hidden": {},
"inherits": {},
"configurePreset": {},
"vendor": {},
"displayName": {},
"description": {},
"inheritConfigureEnvironment": {},
"environment": {},
"jobs": {},
"targets": {},
"configuration": {},
"cleanFirst": {},
"resolvePackageReferences": {},
"verbose": {},
"nativeToolOptions": {},
"condition": {}
},
"required": [
"name"
],
"additionalProperties": false
}
},
"buildPresetsV3": {
"type": "array",
"description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
"description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.",
"allOf": [
{ "$ref": "#/definitions/buildPresetsItemsV3" },
{ "$ref": "#/definitions/buildPresetsItemsV2" }
@ -609,7 +675,7 @@
},
"testPresetsItemsV3": {
"type": "array",
"description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
"description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.",
"items": {
"type": "object",
"properties": {
@ -934,7 +1000,7 @@
},
"testPresetsV3": {
"type": "array",
"description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
"description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.",
"allOf": [
{ "$ref": "#/definitions/testPresetsItemsV2" },
{ "$ref": "#/definitions/testPresetsItemsV3" }
@ -1235,6 +1301,13 @@
"description": "Null indicates that the condition always evaluates to true and is not inherited."
}
]
},
"include": {
"type": "array",
"description": "An optional array of strings representing files to include. If the filenames are not absolute, they are considered relative to the current file.",
"items": {
"type": "string"
}
}
}
}

2
Help/policy/CMP0028.rst
View File

@ -13,6 +13,8 @@ on disk. Previously, if a target was not found with a matching name, the name
was considered to refer to a file on disk. This can lead to confusing error
messages if there is a typo in what should be a target name.
See also the :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target property.
The ``OLD`` behavior for this policy is to search for targets, then files on
disk, even if the search term contains double-colons. The ``NEW`` behavior
for this policy is to issue a ``FATAL_ERROR`` if a link dependency contains

3
Help/policy/CMP0126.rst
View File

@ -14,6 +14,9 @@ current scope in the following situations:
This can occur when the variable was set on the command line using a form
like ``cmake -DMYVAR=blah`` instead of ``cmake -DMYVAR:STRING=blah``.
* The ``FORCE`` or ``INTERNAL`` keywords were used when setting the cache
variable.
Note that the ``NEW`` behavior has an important difference to the similar
``NEW`` behavior of policy :policy:`CMP0077`. The :command:`set(CACHE)`
command always sets the cache variable if it did not exist previously,

34
Help/policy/CMP0129.rst Normal file
View File

@ -0,0 +1,34 @@
CMP0129
-------
.. versionadded:: 3.23
Compiler id for MCST LCC compilers is now ``LCC``, not ``GNU``.
CMake 3.23 and above recognize MCST LCC compiler as a different from ``GNU``,
with its own command line and set of capabilities.
CMake now prefers to present this to projects by setting the
:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``LCC`` instead
of ``GNU``. However, existing projects may assume the compiler id for
LCC is ``GNU`` as it was in CMake versions prior to 3.23.
Therefore this policy determines for MCST LCC compiler which
compiler id to report in the :variable:`CMAKE_<LANG>_COMPILER_ID`
variable after language ``<LANG>`` is enabled by the :command:`project`
or :command:`enable_language` command. The policy must be set prior
to the invocation of either command.
The ``OLD`` behavior for this policy is to use compiler id ``GNU`` (and set
:variable:`CMAKE_<LANG>_COMPILER_VERSION` to the supported GNU compiler version.)
``NEW`` behavior for this policy is to use compiler id ``LCC``, and set
:variable:`CMAKE_<LANG>_SIMULATE_ID` to ``GNU``, and
:variable:`CMAKE_<LANG>_SIMULATE_VERSION` to the supported GNU compiler version.
This policy was introduced in CMake version 3.23. Use the
:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` explicitly.
Unlike most policies, CMake version |release| does *not* warn
by default when this policy is not set and simply uses ``OLD`` behavior.
See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0129 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.
.. include:: DEPRECATED.txt

2
Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst
View File

@ -35,3 +35,5 @@ The features known to this version of CMake are:
.. versionadded:: 3.20
Compiler mode is at least CUDA/C++ 23.
.. include:: CMAKE_LANG_STD_FLAGS.txt

2
Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst
View File

@ -46,6 +46,8 @@ but it does not necessarily imply complete conformance to that standard.
Compiler mode is at least C++ 23.
.. include:: CMAKE_LANG_STD_FLAGS.txt
Low level individual compile features
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

2
Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst
View File

@ -39,6 +39,8 @@ High level meta features indicating C standard support
Compiler mode is at least C 23.
.. include:: CMAKE_LANG_STD_FLAGS.txt
Low level individual compile features
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

7
Help/prop_gbl/CMAKE_LANG_STD_FLAGS.txt Normal file
View File

@ -0,0 +1,7 @@
.. note::
If the compiler's default standard level is at least that
of the requested feature, CMake may omit the ``-std=`` flag.
The flag may still be added if the compiler's default extensions mode
does not match the :prop_tgt:`<LANG>_EXTENSIONS` target property,
or if the :prop_tgt:`<LANG>_STANDARD` target property is set.

4
Help/prop_sf/LANGUAGE.rst
View File

@ -7,8 +7,8 @@ A property that can be set to indicate what programming language the
source file is. If it is not set the language is determined based on
the file extension. Typical values are ``CXX`` (i.e. C++), ``C``,
``CSharp``, ``CUDA``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``. Setting
this property for a file means this file will be compiled. Do not set this
for headers or files that should not be compiled.
this property for a file means this file will be compiled, unless
:prop_sf:`HEADER_FILE_ONLY` is set.
.. versionchanged:: 3.20
Setting this property causes the source file to be compiled as the

8
Help/prop_test/ENVIRONMENT.rst
View File

@ -3,7 +3,7 @@ ENVIRONMENT
Specify environment variables that should be defined for running a test.
If set to a list of environment variables and values of the form
``MYVAR=value`` those environment variables will be defined while running
the test. The environment changes from this property do not affect other
tests.
Set to a :ref:`semicolon-separated list <CMake Language Lists>` list
of environment variables and values of the form ``MYVAR=value``.
Those environment variables will be defined while running the test.
The environment changes from this property do not affect other tests.

9
Help/prop_test/ENVIRONMENT_MODIFICATION.rst
View File

@ -7,10 +7,11 @@ Specify environment variables that should be modified for running a test. Note
that the operations performed by this property are performed after the
:prop_test:`ENVIRONMENT` property is already applied.
If set to a list of environment variables and values of the form
``MYVAR=OP:VALUE``, where ``MYVAR`` is the case-sensitive name of an
environment variable to be modified. Entries are considered in the
order specified in the property's value. The ``OP`` may be one of:
Set to a :ref:`semicolon-separated list <CMake Language Lists>` of
environment variables and values of the form ``MYVAR=OP:VALUE``,
where ``MYVAR`` is the case-sensitive name of an environment variable
to be modified. Entries are considered in the order specified in the
property's value. The ``OP`` may be one of:
- ``reset``: Reset to the unmodified value, ignoring all modifications to
``MYVAR`` prior to this entry. Note that this will reset the variable to

7
Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst
View File

@ -8,9 +8,10 @@ This command will be added as a prefix to :command:`add_test`,
:command:`add_custom_command`, and :command:`add_custom_target` commands
for built target system executables.
If this property contains a :ref:`semicolon-separated list <CMake Language
Lists>`, then the first value is the command and remaining values are its
arguments.
.. versionadded:: 3.15
If this property contains a :ref:`semicolon-separated list <CMake Language
Lists>`, then the first value is the command and remaining values are its
arguments.
This property is initialized by the value of the
:variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable if it is set when a target

14
Help/prop_tgt/CUDA_ARCHITECTURES.rst
View File

@ -20,6 +20,20 @@ variable if it is set when a target is created.
The ``CUDA_ARCHITECTURES`` target property must be set to a non-empty value on targets
that compile CUDA sources, or it is an error. See policy :policy:`CMP0104`.
The ``CUDA_ARCHITECTURES`` may be set to one of the following special values:
``all``
.. versionadded:: 3.23
Compile for all supported major and minor real architectures,
and the highest major virtual architecture.
``all-major``
.. versionadded:: 3.23
Compile for all supported major real architectures, and the highest
major virtual architecture.
Examples
^^^^^^^^

5
Help/prop_tgt/DEPRECATION.rst
View File

@ -7,3 +7,8 @@ Deprecation message from imported target's developer.
``DEPRECATION`` is the message regarding a deprecation status to be displayed
to downstream users of a target.
The message is formatted as follows:
* Lines that do not start in whitespace are wrapped as paragraph text.
* Lines that start in whitespace are preserved as preformatted text.

25
Help/prop_tgt/DOTNET_SDK.rst Normal file
View File

@ -0,0 +1,25 @@
DOTNET_SDK
----------
.. versionadded:: 3.23
Specify the .NET SDK for C# projects. For example: ``Microsoft.NET.Sdk``.
This property tells :ref:`Visual Studio Generators` for VS 2019 and
above to generate a .NET SDK-style project using the specified SDK.
The property is meaningful only to these generators, and only in C#
targets. It is ignored for C++ projects, even if they are managed
(e.g. using :prop_tgt:`COMMON_LANGUAGE_RUNTIME`).
This property must be a non-empty string to generate .NET SDK-style projects.
CMake does not perform any validations for the value of the property.
This property may be initialized for all targets using the
:variable:`CMAKE_DOTNET_SDK` variable.
.. note::
The :ref:`Visual Studio Generators` in this version of CMake have not
yet learned to support :command:`add_custom_command` in .NET SDK-style
projects. It is currently an error to attach a custom command to a
target with the ``DOTNET_SDK`` property set.

14
Help/prop_tgt/HEADER_DIRS.rst Normal file
View File

@ -0,0 +1,14 @@
HEADER_DIRS
-----------
.. versionadded:: 3.23
Semicolon-separated list of base directories of the target's default
header set (i.e. the file set with name and type ``HEADERS``). The property
supports :manual:`generator expressions <cmake-generator-expressions(7)>`.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See :prop_tgt:`HEADER_DIRS_<NAME>` for the list of base directories in
other header sets.

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

@ -0,0 +1,15 @@
HEADER_DIRS_<NAME>
------------------
.. versionadded:: 3.23
Semicolon-separated list of base directories of the target's ``<NAME>``
header set, which has the set type ``HEADERS``. The property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See :prop_tgt:`HEADER_DIRS` for the list of base directories in the
default header set. See :prop_tgt:`HEADER_SETS` for the file set names of all
header sets.

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

@ -0,0 +1,15 @@
HEADER_SET
----------
.. versionadded:: 3.23
Semicolon-separated list of files in the target's default header set,
(i.e. the file set with name and type ``HEADERS``). If any of the paths
are relative, they are computed relative to the target's source directory.
The property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See :prop_tgt:`HEADER_SET_<NAME>` for the list of files in other header sets.

16
Help/prop_tgt/HEADER_SETS.rst Normal file
View File

@ -0,0 +1,16 @@
HEADER_SETS
-----------
.. versionadded:: 3.23
List of the target's ``PRIVATE`` and ``PUBLIC`` header sets (i.e. all
file sets with the type ``HEADERS``). Files listed in these file sets
are treated as source files for the purpose of IDE integration.
The files also have their :prop_sf:`HEADER_FILE_ONLY` property set to
``TRUE``.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See also :prop_tgt:`HEADER_SET_<NAME>`, :prop_tgt:`HEADER_SET` and
:prop_tgt:`INTERFACE_HEADER_SETS`.

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

@ -0,0 +1,15 @@
HEADER_SET_<NAME>
-----------------
.. versionadded:: 3.23
Semicolon-separated list of files in the target's ``<NAME>`` header set,
which has the set type ``HEADERS``. If any of the paths are relative,
they are computed relative to the target's source directory. The property
supports :manual:`generator expressions <cmake-generator-expressions(7)>`.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See :prop_tgt:`HEADER_SET` for the list of files in the default header set.
See :prop_tgt:`HEADER_SETS` for the file set names of all header sets.

21
Help/prop_tgt/IMPORTED_NO_SYSTEM.rst Normal file
View File

@ -0,0 +1,21 @@
IMPORTED_NO_SYSTEM
------------------
.. versionadded:: 3.23
Specifies that an :ref:`Imported Target <Imported Targets>` is not
a ``SYSTEM`` library. This has the following effects:
* Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are not treated
as ``SYSTEM`` include directories when compiling consumers, as they
would be by default. Entries of
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected,
and will always be treated as ``SYSTEM`` include directories.
This property can also be enabled on a non-imported target. Doing so does
not affect the build system, but does tell the :command:`install(EXPORT)` and
:command:`export` commands to enable it on the imported targets they generate.
See the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property to set this
behavior on the target consuming the include directories rather than
providing them.

14
Help/prop_tgt/INTERFACE_HEADER_SETS.rst Normal file
View File

@ -0,0 +1,14 @@
INTERFACE_HEADER_SETS
---------------------
.. versionadded:: 3.23
List of the target's ``INTERFACE`` and ``PUBLIC`` header sets (i.e. all
file sets with the type ``HEADERS``). Files listed in these header sets
can be installed with :command:`install(TARGETS)` and exported with
:command:`install(EXPORT)` and :command:`export`.
This property is normally only set by :command:`target_sources(FILE_SET)`
rather than being manipulated directly.
See also :prop_tgt:`HEADER_SETS`.

7
Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
View File

@ -12,6 +12,13 @@ other target also. This property is overridden by the
:prop_tgt:`LINK_INTERFACE_LIBRARIES_<CONFIG>` property if policy
:policy:`CMP0022` is ``OLD`` or unset.
The value of this property is used by the generators when constructing
the link rule for a dependent target. A dependent target's direct
link dependencies, specified by its :prop_tgt:`LINK_LIBRARIES` target
property, are linked first, followed by indirect dependencies from the
transitive closure of the direct dependencies'
``INTERFACE_LINK_LIBRARIES`` properties. See policy :policy:`CMP0022`.
Contents of ``INTERFACE_LINK_LIBRARIES`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`

9
Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst
View File

@ -5,9 +5,12 @@ List of public system include directories for a library.
Targets may populate this property to publish the include directories
which contain system headers, and therefore should not result in
compiler warnings. The :command:`target_include_directories(SYSTEM)`
command signature populates this property with values given to the
``PUBLIC`` and ``INTERFACE`` keywords.
compiler warnings. Additionally, system include directories are searched
after normal include directories regardless of the order specified.
The :command:`target_include_directories(SYSTEM)` command signature
populates this property with values given to the ``PUBLIC`` and
``INTERFACE`` keywords.
Projects may also get and set the property directly, but must be aware that
adding directories to this property does not make those directories used

7
Help/prop_tgt/LANG_STANDARD.rst
View File

@ -15,6 +15,13 @@ newer standard is specified than is supported by the compiler, then it will
fallback to the latest supported standard. This "decay" behavior may be
controlled with the :prop_tgt:`<LANG>_STANDARD_REQUIRED` target property.
Note that the actual language standard used may be higher than that specified
by ``<LANG>_STANDARD``, regardless of the value of
:prop_tgt:`<LANG>_STANDARD_REQUIRED`. In particular,
:ref:`transitive usage requirements <Target Usage Requirements>` or the use of
:manual:`compile features <cmake-compile-features(7)>` can raise the required
language standard above what ``<LANG>_STANDARD`` specifies.
These properties are initialized by the value of the
:variable:`CMAKE_<LANG>_STANDARD` variable if it is set when a target is
created.

16
Help/prop_tgt/LANG_STANDARD_REQUIRED.rst
View File

@ -11,16 +11,22 @@ The variations are:
* :prop_tgt:`OBJCXX_STANDARD_REQUIRED`
These properties specify whether the value of :prop_tgt:`<LANG>_STANDARD` is a
requirement. When ``OFF`` or unset, the :prop_tgt:`<LANG>_STANDARD` target
requirement. When false or unset, the :prop_tgt:`<LANG>_STANDARD` target
property is treated as optional and may "decay" to a previous standard if the
requested is not available.
requested standard is not available. When ``<LANG>_STANDARD_REQUIRED`` is set
to true, :prop_tgt:`<LANG>_STANDARD` becomes a hard requirement and a fatal
error will be issued if that requirement cannot be met.
Note that the actual language standard used may be higher than that specified
by :prop_tgt:`<LANG>_STANDARD`, regardless of the value of
``<LANG>_STANDARD_REQUIRED``. In particular,
:ref:`transitive usage requirements <Target Usage Requirements>` or the use of
:manual:`compile features <cmake-compile-features(7)>` can raise the required
language standard above what :prop_tgt:`<LANG>_STANDARD` specifies.
These properties are initialized by the value of the
:variable:`CMAKE_<LANG>_STANDARD_REQUIRED` variable if it is set when a target
is created.
For supported CMake versions see the respective pages.
To control language standard versions see :prop_tgt:`<LANG>_STANDARD`.
See the :manual:`cmake-compile-features(7)` manual for information on
compile features and a list of supported compilers.

6
Help/prop_tgt/LINKER_LANGUAGE.rst
View File

@ -7,8 +7,10 @@ For executables, shared libraries, and modules, this sets the language
whose compiler is used to link the target (such as "C" or "CXX"). A
typical value for an executable is the language of the source file
providing the program entry point (main). If not set, the language
with the highest linker preference value is the default. See
documentation of :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables.
with the highest linker preference value is the default. Details of
the linker preferences are considered internal, but some limited
discussion can be found under the internal
:variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables.
If this property is not set by the user, it will be calculated at
generate-time by CMake.

7
Help/prop_tgt/LINK_LIBRARIES.rst
View File

@ -8,8 +8,11 @@ used for linking. In addition to accepting values from the
:command:`target_link_libraries` command, values may be set directly on
any target using the :command:`set_property` command.
The value of this property is used by the generators to set the link
libraries for the compiler.
The value of this property is used by the generators to construct the
link rule for the target. The direct link dependencies are linked first,
followed by indirect dependencies from the transitive closure of the
direct dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
See policy :policy:`CMP0022`.
Contents of ``LINK_LIBRARIES`` may use "generator expressions" with the
syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual

54
Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst Normal file
View File

@ -0,0 +1,54 @@
LINK_LIBRARIES_ONLY_TARGETS
---------------------------
.. versionadded:: 3.23
Enforce that link items that can be target names are actually existing targets.
Set this property to a true value to enable additional checks on the contents
of the :prop_tgt:`LINK_LIBRARIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES`
target properties, typically populated by :command:`target_link_libraries`.
CMake will verify that link items that might be target names actually name
existing targets. An item is considered a possible target name if:
* it does not contain a ``/`` or ``\``, and
* it does not start in ``-``, and
* (for historical reasons) it does not start in ``$`` or `````.
This property is initialized by the value of the
:variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable when a non-imported
target is created. The property may be explicitly enabled on an imported
target to check its link interface.
In the following example, CMake will halt with an error at configure time
because ``miLib`` is not a target:
.. code-block:: cmake
set(CMAKE_LINK_LIBRARIES_ONLY_TARGETS ON)
add_library(myLib STATIC myLib.c)
add_executable(myExe myExe.c)
target_link_libraries(myExe PRIVATE miLib) # typo for myLib
In order to link toolchain-provided libraries by name while still
enforcing ``LINK_LIBRARIES_ONLY_TARGETS``, use an
:ref:`imported <Imported Targets>`
:ref:`Interface Library <Interface Libraries>` with the
:prop_tgt:`IMPORTED_LIBNAME` target property:
.. code-block:: cmake
add_library(toolchain::m INTERFACE IMPORTED)
set_property(TARGET toolchain::m PROPERTY IMPORTED_LIBNAME "m")
target_link_libraries(myExe PRIVATE toolchain::m)
See also policy :policy:`CMP0028`.
.. note::
If :prop_tgt:`INTERFACE_LINK_LIBRARIES` contains generator expressions,
its actual list of link items may depend on the type and properties of
the consuming target. In such cases CMake may not always detect names
of missing targets that only appear for specific consumers.
A future version of CMake with improved heuristics may start triggering
errors on projects accepted by previous versions of CMake.

7
Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst
View File

@ -8,8 +8,13 @@ The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property
of imported targets are treated as ``SYSTEM`` includes by default. If this
property is enabled on a target, compilation of sources in that target will
not treat the contents of the ``INTERFACE_INCLUDE_DIRECTORIES`` of consumed
imported targets as system includes.
imported targets as system includes. Either way, entries of
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected,
and will always be treated as ``SYSTEM`` include directories.
This property is initialized by the value of the
:variable:`CMAKE_NO_SYSTEM_FROM_IMPORTED` variable if it is set when a target
is created.
See the :prop_tgt:`IMPORTED_NO_SYSTEM` target property to set this behavior
on the target providing the include directories rather than consuming them.

36
Help/prop_tgt/SOURCES.rst
View File

@ -1,6 +1,38 @@
SOURCES
-------
Source names specified for a target.
This specifies the list of paths to source files for the target.
The following commands all set or add to the ``SOURCES`` target property
and are the usual way to manipulate it:
List of sources specified for a target.
* :command:`add_executable`
* :command:`add_library`
* :command:`add_custom_target`
* :command:`target_sources`
Contents of ``SOURCES`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
If a path starts with a generator expression, it is expected to
evaluate to an absolute path. Not doing so is considered undefined behavior.
Paths that are for files generated by the build will be treated
as relative to the build directory of the target, if the path is not
already specified as an absolute path. Note that whether a file is seen as
generated may be affected by policy :policy:`CMP0118`.
If a path does not start with a generator expression, is not an
absolute path and is not a generated file, it will be treated as relative to
the location selected by the first of the following that matches:
* If a file by the specified path exists relative to the target's source
directory, use that file.
* If policy :policy:`CMP0115` is not set to ``NEW``, try appending each
known source file extension to the path and check if that exists
relative to the target's source directory.
* Repeat the above two steps, this time relative to the target's binary
directory instead.
Note that the above decisions are made at generation time, not build time.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.

6
Help/prop_tgt/XCODE_EMBED_type.rst
View File

@ -19,6 +19,12 @@ The supported values for ``<type>`` are:
The specified items will be added to the ``Embed App Extensions`` build phase.
They must be CMake target names.
``PLUGINS``
.. versionadded:: 3.23
The specified items will be added to the ``Embed PlugIns`` build phase.
They must be CMake target names.
See also :prop_tgt:`XCODE_EMBED_<type>_PATH`,
:prop_tgt:`XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY` and
:prop_tgt:`XCODE_EMBED_<type>_CODE_SIGN_ON_COPY`.

3
Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst
View File

@ -14,5 +14,8 @@ The supported values for ``<type>`` are:
``APP_EXTENSIONS``
.. versionadded:: 3.21
``PLUGINS``
.. versionadded:: 3.23
If a ``XCODE_EMBED_<type>_CODE_SIGN_ON_COPY`` property is not defined on the
target, no code signing on copy will be performed for that ``<type>``.

3
Help/prop_tgt/XCODE_EMBED_type_PATH.rst
View File

@ -16,3 +16,6 @@ The supported values for ``<type>`` are:
``APP_EXTENSIONS``
.. versionadded:: 3.21
``PLUGINS``
.. versionadded:: 3.23

3
Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst
View File

@ -18,3 +18,6 @@ The supported values for ``<type>`` are:
If the ``XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY`` property is not
defined, headers WILL be removed on copy by default.
``PLUGINS``
.. versionadded:: 3.23

1
Help/prop_tgt/XCODE_GENERATE_SCHEME.rst
View File

@ -38,6 +38,7 @@ The following target properties will be applied on the
- :prop_tgt:`XCODE_SCHEME_ARGUMENTS`
- :prop_tgt:`XCODE_SCHEME_DEBUG_AS_ROOT`
- :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING`
- :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE`
- :prop_tgt:`XCODE_SCHEME_ENVIRONMENT`
- :prop_tgt:`XCODE_SCHEME_EXECUTABLE`
- :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY`

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

@ -0,0 +1,15 @@
XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
------------------------------------------
.. versionadded:: 3.23
Property value for ``GPU Frame Capture`` in the Options section of
the generated Xcode scheme. Example values are `Metal` and
`Disabled`.
This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE`
if it is set when a target is created.
Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.

7
Help/release/3.21.rst
View File

@ -334,3 +334,10 @@ Changes made since CMake 3.21.0 include the following.
* The :generator:`Visual Studio 17 2022` generator is now based on the
"Visual Studio 2022" release candidates. Previously it was based on
preview versions.
3.21.5, 3.21.6
--------------
These versions made no changes to documented features or interfaces.
Some implementation updates were made to support ecosystem changes
and/or fix regressions.

22
Help/release/3.22.rst
View File

@ -142,3 +142,25 @@ Other Changes
This became available as of VS 16.10 (toolchain version 14.29.30037).
* The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.03 or later.
3.22.1
------
This version made no changes to documented features or interfaces.
Some implementation updates were made to support ecosystem changes
and/or fix regressions.
3.22.2
------
* The ``OLD`` behavior of :policy:`CMP0128` was fixed to add flags even when
the specified standard matches the compiler default.
3.22.3
------
* The :command:`while` command again ignores errors in condition evaluation
as CMake 3.21 and below did. This bug was fixed in 3.22.0, but exposed
errors in existing projects. The fix has been reverted to restore
compatibility. The fix may be restored in a future version of CMake
via a policy.

266
Help/release/3.23.rst Normal file
View File

@ -0,0 +1,266 @@
CMake 3.23 Release Notes
************************
.. only:: html
.. contents::
Changes made since CMake 3.22 include the following.
New Features
============
Presets
-------
* :manual:`cmake-presets(7)` files now support schema version ``4``.
* :manual:`cmake-presets(7)` files now have an optional ``include`` field,
which allows the files to include other files.
* :manual:`cmake-presets(7)` files now support a ``${fileDir}`` macro, which
contains the directory containing the preset file.
* :manual:`cmake-presets(7)` gained support for specifying the
``resolvePackageReferences`` command line option in a build preset to control
restoration behavior of package references from external package managers.
Currently this is only supported by the Visual Studio generator to support
restoring packages from NuGet. Other generators ignore this option.
Generators
----------
* The :ref:`Visual Studio Generators` for VS 2019 and above learned to
support .NET SDK-style project files (``.csproj``) for C# projects.
See the :prop_tgt:`DOTNET_SDK` target property and corresponding
:variable:`CMAKE_DOTNET_SDK` variable. :command:`add_custom_command`
is not yet supported in .NET SDK-style projects.
* The :ref:`Visual Studio Generators` for VS 2017 and above learned to
use portable instances of Visual Studio not known to the VS installer.
See the :variable:`CMAKE_GENERATOR_INSTANCE` variable.
Command-Line
------------
* The :manual:`cmake(1)` ``--build`` command, when used with
:ref:`Visual Studio Generators` on projects that set the
:prop_tgt:`VS_PACKAGE_REFERENCES` target property, now automatically
restores package references from NuGet. The cache variable
:variable:`CMAKE_VS_NUGET_PACKAGE_RESTORE` may be set to toggle this behavior
in a build tree. Use the ``--resolve-package-references=<on|off|only>``
command-line option to control the behavior on one invocation.
* The :manual:`cmake(1)` command line tool gained a ``--debug-find-pkg=``
option to enable debug messages under specific :command:`find_package`
calls.
* The :manual:`cmake(1)` command line tool gained a ``--debug-find-var=``
option to enable debug messages for ``find_*`` calls that use specific
result variables.
Compilers
---------
* The IBM Open XL C/C++ compiler, based on LLVM, is now supported with
compiler id ``IBMClang``.
* The MCST LCC compiler is now supported with compiler id ``LCC``.
See policy :policy:`CMP0129`.
File-Based API
--------------
* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field
has been updated to ``2.4``.
* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``directory``
object ``installers`` field gained a new ``fileSet`` installer type.
Commands
--------
* The :command:`define_property` command gained a new
``INITIALIZE_FROM_VARIABLE`` option to cause a target property to be
initialized from a variable when a target is created.
* The :command:`install(TARGETS)` command gained a new ``FILE_SET`` argument,
which can be used to install header file sets associated with a target.
* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` commands now
support the ``%f`` specifier for microseconds.
* The :command:`target_sources` command gained a new ``FILE_SET`` mode, which
can be used to add headers as header-only source files of a target.
Variables
---------
* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated
:prop_tgt:`CUDA_ARCHITECTURES` target property now support the
``all``, and ``all-major`` values for CUDA toolkit 7.0+.
* The :variable:`CMAKE_IGNORE_PREFIX_PATH` and
:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables were added
to tell the :command:`find_package`, :command:`find_program`,
:command:`find_library`, :command:`find_path`, and :command:`find_file`
commands to ignore specified prefixes.
* The :variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable and
corresponding :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target
property were added to optionally require that all link items
that can be target names are actually names of existing targets.
Properties
----------
* The :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` target
properties were added to list header sets associated with a target.
* The :prop_tgt:`HEADER_SET` and :prop_tgt:`HEADER_SET_<NAME>` target
properties were added to list files in the default header set
and named header sets, respectively.
* The :prop_tgt:`HEADER_DIRS` and :prop_tgt:`HEADER_DIRS_<NAME>` target
properties were added to specify the base directories of the default
header set and named header sets, respectively.
* The :prop_tgt:`IMPORTED_NO_SYSTEM` target property was added to
specify that an :ref:`Imported Target <Imported Targets>` should
not be treated as a system library (i.e. its include directories
are not automatically ``SYSTEM``).
* The :prop_tgt:`XCODE_EMBED_PLUGINS <XCODE_EMBED_<type>>` target property
was added to tell the :generator:`Xcode` generator what targets to put in
the ``Embed PlugIns`` build phase.
* The :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` target property
and supporting :variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE`
variable were added to tell the :generator:`Xcode` generator to enable
specifying the Xcode scheme option property ``GPU Frame Capture``.
Modules
-------
* The :module:`CheckPIESupported` module now supports the ``OBJC``,
``OBJCXX``, ``CUDA``, and ``HIP`` languages. It also now honors
:variable:`CMAKE_SYSROOT` and :variable:`CMAKE_OSX_SYSROOT`.
* The :module:`ExternalProject` module's :command:`ExternalProject_Add`
command gained support for a ``USES_TERMINAL_PATCH`` option to give
the patch step exclusive terminal access.
* The :module:`FindCUDAToolkit` module now provides a target for
``libcufft_static_nocallback``, if found.
* The :module:`FindGLUT` module now provides the ``GLUT_INCLUDE_DIRS``
result variable to conform with naming conventions documented in the
:manual:`cmake-developer(7)` manual. This supersedes the legacy
``GLUT_INCLUDE_DIR`` variable.
* The :module:`FindGTest` module now provides a target for GMock, if found.
* The :module:`FindVulkan` module now provides a ``Vulkan_VERSION`` result
variable reporting the version number.
CTest
-----
* :manual:`ctest(1)` gained a new :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT`
variable, which can be used to specify a timeout for submission inactivity.
CPack
-----
* The :cpack_gen:`CPack productbuild Generator` gained the new
:variable:`CPACK_PRODUCTBUILD_DOMAINS`,
:variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`,
:variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and
:variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT` variables for
adding the domains element to the Distribution XML. With these variables,
it is now possible to install products to the user's home directory
without requiring administrative privileges.
* The :cpack_gen:`CPack productbuild Generator` gained a new variable,
:variable:`CPACK_PRODUCTBUILD_IDENTIFIER`, used to customize the unique
product identifier associated with the product.
* The :cpack_gen:`CPack IFW Generator` gained the new
:variable:`CPACK_IFW_ARCHIVE_FORMAT` and
:variable:`CPACK_IFW_ARCHIVE_COMPRESSION` variables for setting the
format used when packaging new component data archives, and choosing
the compression level used.
These features are available for QtIFW 4.2 and newer.
* The :cpack_gen:`CPack IFW Generator` gained new
:variable:`CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE` variable to
prevent the user from passing any consumer command to the installer, like
``install``, ``update``, and ``remove``.
This feature is available for QtIFW 4.0 and newer.
* The :cpack_gen:`CPack IFW Generator` gained the new
:variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGES` variable for adding a
list of images to be shown on the ``PerformInstallationPage``.
This feature is available for QtIFW 4.0 and newer.
* The :cpack_gen:`CPack IFW Generator` gained the new
:variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`,
:variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS`, and
:variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION` variables for
executing a command after the installer is done if the user accepts
the action. This feature is available for QtIFW 4.0 and newer.
* The :cpack_gen:`CPack IFW Generator` gained the new
:variable:`CPACK_IFW_PACKAGE_SIGNING_IDENTITY` variable for specifying a
code signing identity to be used for signing the generated app bundle.
This feature is available on macOS only, and for QtIFW 3.0 and newer.
* The :cpack_gen:`CPack WIX Generator` gained a new variable,
:variable:`CPACK_WIX_SKIP_WIX_UI_EXTENSION`, to skip the inclusion
of WixUIExtensions.
Deprecated and Removed Features
===============================
* :manual:`cmake(1)` now warns when multiple source paths are specified,
as in ``cmake -S src1 src2``. This has never been officially documented
or supported, but older versions accidentally accepted multiple source
paths and used the last path specified. Update scripts to avoid
passing multiple source path arguments.
* The :manual:`cpack(1)` undocumented ``OSXX11`` generator has been removed.
Other Changes
=============
* The :cpack_gen:`CPack DragNDrop Generator` no longer attaches
:variable:`CPACK_RESOURCE_FILE_LICENSE` as the license agreement in
the generated ``.dmg`` unless explicitly activated by a
:variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option.
In CMake projects, the :module:`CPack` module enables the option
by default for compatibility.
* ``CUDA`` targets may now enable both :prop_tgt:`CUDA_SEPARABLE_COMPILATION`
and :prop_tgt:`CUDA_PTX_COMPILATION`.
* ``CUDA`` compiler detection now:
* issues an error in all cases when it's unable to compute the default
architecture(s) if required (see :policy:`CMP0104`),
* handles ``OFF`` for :variable:`CMAKE_CUDA_ARCHITECTURES` on Clang,
* supports the theoretical case of multiple default architectures, and
* tries to detect invalid architectures and issue an error.
* ``CUDA`` with Clang now implements policy :policy:`CMP0105` and
the ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>``
:manual:`generator expressions <cmake-generator-expressions(7)>`.
* The :command:`define_property` command's ``BRIEF_DOCS`` and ``FULL_DOCS``
arguments are now optional.
* :manual:`ccmake(1)` may now be enabled on Windows when building
CMake from source. This is experimental, and so is not included
in official distributions.

1
Help/release/index.rst
View File

@ -13,6 +13,7 @@ Releases
.. toctree::
:maxdepth: 1
3.23 <3.23>
3.22 <3.22>
3.21 <3.21>
3.20 <3.20>

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