New upstream version 3.28.0

ci/unstable
Timo Röhling 1 year ago
parent f622ac3441
commit cf677c087a

@ -3,15 +3,18 @@ Checks: "-*,\
bugprone-*,\ bugprone-*,\
-bugprone-assignment-in-if-condition,\ -bugprone-assignment-in-if-condition,\
-bugprone-easily-swappable-parameters,\ -bugprone-easily-swappable-parameters,\
-bugprone-empty-catch,\
-bugprone-implicit-widening-of-multiplication-result,\ -bugprone-implicit-widening-of-multiplication-result,\
-bugprone-macro-parentheses,\ -bugprone-macro-parentheses,\
-bugprone-misplaced-widening-cast,\ -bugprone-misplaced-widening-cast,\
-bugprone-narrowing-conversions,\ -bugprone-narrowing-conversions,\
-bugprone-switch-missing-default-case,\
-bugprone-too-small-loop-variable,\ -bugprone-too-small-loop-variable,\
-bugprone-unchecked-optional-access,\ -bugprone-unchecked-optional-access,\
misc-*,\ misc-*,\
-misc-confusable-identifiers,\ -misc-confusable-identifiers,\
-misc-const-correctness,\ -misc-const-correctness,\
-misc-include-cleaner,\
-misc-no-recursion,\ -misc-no-recursion,\
-misc-non-private-member-variables-in-classes,\ -misc-non-private-member-variables-in-classes,\
-misc-static-assert,\ -misc-static-assert,\
@ -20,14 +23,18 @@ modernize-*,\
-modernize-avoid-c-arrays,\ -modernize-avoid-c-arrays,\
-modernize-macro-to-enum,\ -modernize-macro-to-enum,\
-modernize-return-braced-init-list,\ -modernize-return-braced-init-list,\
-modernize-type-traits,\
-modernize-use-emplace,\ -modernize-use-emplace,\
-modernize-use-nodiscard,\ -modernize-use-nodiscard,\
-modernize-use-noexcept,\ -modernize-use-noexcept,\
-modernize-use-trailing-return-type,\ -modernize-use-trailing-return-type,\
-modernize-use-transparent-functors,\ -modernize-use-transparent-functors,\
performance-*,\ performance-*,\
-performance-avoid-endl,\
-performance-inefficient-vector-operation,\ -performance-inefficient-vector-operation,\
-performance-noexcept-swap,\
readability-*,\ readability-*,\
-readability-avoid-unconditional-preprocessor-if,\
-readability-convert-member-functions-to-static,\ -readability-convert-member-functions-to-static,\
-readability-function-cognitive-complexity,\ -readability-function-cognitive-complexity,\
-readability-function-size,\ -readability-function-size,\
@ -41,6 +48,7 @@ readability-*,\
-readability-redundant-declaration,\ -readability-redundant-declaration,\
-readability-redundant-member-init,\ -readability-redundant-member-init,\
-readability-simplify-boolean-expr,\ -readability-simplify-boolean-expr,\
-readability-static-accessed-through-instance,\
-readability-suspicious-call-argument,\ -readability-suspicious-call-argument,\
-readability-uppercase-literal-suffix,\ -readability-uppercase-literal-suffix,\
cmake-*,\ cmake-*,\

@ -22,20 +22,20 @@ set cpo&vim
syn region cmakeBracketArgument start="\[\z(=\?\|=[0-9]*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell syn region cmakeBracketArgument start="\[\z(=\?\|=[0-9]*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell
syn region cmakeComment start="#" end="$" contains=cmakeTodo,@Spell syn region cmakeComment start="#" end="$" contains=cmakeTodo,@Spell
syn region cmakeBracketComment start="#\[\z(=\?\|=[0-9]*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell syn region cmakeBracketComment start="\[\z(=*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell
syn match cmakeEscaped /\(\\\\\|\\"\|\\n\|\\t\)/ contained syn match cmakeEscaped /\(\\\\\|\\"\|\\n\|\\t\)/ contained
syn region cmakeRegistry start="\[" end="]" contained oneline contains=cmakeTodo,cmakeEscaped syn region cmakeRegistry start="\[" end="]" contained oneline contains=cmakeTodo,cmakeEscaped
syn region cmakeGeneratorExpression start="$<" end=">" contained oneline contains=cmakeVariableValue,cmakeProperty,cmakeGeneratorExpressions,cmakeTodo syn region cmakeGeneratorExpression start="$<" end=">" contained oneline contains=cmakeVariableValue,cmakeProperty,cmakeGeneratorExpressions,cmakeTodo
syn region cmakeString start='"' end='"' contained contains=cmakeTodo,cmakeVariableValue,cmakeEscaped syn region cmakeString start='"' end='"' contained contains=cmakeTodo,cmakeVariableValue,cmakeEscaped,@Spell
syn region cmakeVariableValue start="${" end="}" contained oneline contains=cmakeVariable,cmakeTodo,cmakeVariableValue syn region cmakeVariableValue start="${" end="}" contained oneline contains=cmakeVariable,cmakeTodo,cmakeVariableValue
syn region cmakeEnvironment start="$ENV{" end="}" contained oneline contains=cmakeTodo syn region cmakeEnvironment start="$ENV{" end="}" contained oneline contains=cmakeTodo
syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeGeneratorExpressions,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeGeneratorExpressions,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo,@Spell
syn case match syn case match

@ -16,10 +16,10 @@ my @modules;
my %keywords; # command => keyword-list my %keywords; # command => keyword-list
# find cmake/Modules/ | sed -rn 's/.*CMakeDetermine(.+)Compiler.cmake/\1/p' | sort # find cmake/Modules/ | sed -rn 's/.*CMakeDetermine(.+)Compiler.cmake/\1/p' | sort
my @languages = qw(ASM ASM_MASM ASM_NASM C CSharp CUDA CXX Fortran Java RC Swift); my @languages = qw(ASM ASM_MASM ASM_NASM C CSharp CUDA CXX Fortran Java RC Swift HIP);
# unwanted upper-cases # unwanted upper-cases
my %unwanted = map { $_ => 1 } qw(VS CXX IDE NOTFOUND NO_ DFOO DBAR NEW); my %unwanted = map { $_ => 1 } qw(VS CXX IDE NOTFOUND NO_ DFOO DBAR NEW GNU);
# cannot remove ALL - exists for add_custom_command # cannot remove ALL - exists for add_custom_command
# control-statements # control-statements
@ -30,7 +30,7 @@ my %loop = map { $_ => 1 } qw(foreach while endforeach endwhile);
my %deprecated = map { $_ => 1 } qw(build_name exec_program export_library_dependencies install_files install_programs install_targets link_libraries make_directory output_required_files remove subdir_depends subdirs use_mangled_mesa utility_source variable_requires write_file); my %deprecated = map { $_ => 1 } qw(build_name exec_program export_library_dependencies install_files install_programs install_targets link_libraries make_directory output_required_files remove subdir_depends subdirs use_mangled_mesa utility_source variable_requires write_file);
# add some (popular) modules # add some (popular) modules
push @modules, "ExternalProject"; push @modules, "ExternalProject", "FetchContent";
# variables # variables
open(CMAKE, "$cmake --help-variable-list|") or die "could not run cmake"; open(CMAKE, "$cmake --help-variable-list|") or die "could not run cmake";

File diff suppressed because it is too large Load Diff

@ -5,7 +5,7 @@
if(CPACK_GENERATOR MATCHES "NSIS") if(CPACK_GENERATOR MATCHES "NSIS")
set(CPACK_NSIS_INSTALL_ROOT "@CPACK_NSIS_INSTALL_ROOT@") set(CPACK_NSIS_INSTALL_ROOT "@CPACK_NSIS_INSTALL_ROOT@")
# set the install/unistall icon used for the installer itself # set the install/uninstall icon used for the installer itself
# There is a bug in NSI that does not handle full unix paths properly. # There is a bug in NSI that does not handle full unix paths properly.
set(CPACK_NSIS_MUI_ICON "@CMake_SOURCE_DIR@/Utilities/Release\\CMakeLogo.ico") set(CPACK_NSIS_MUI_ICON "@CMake_SOURCE_DIR@/Utilities/Release\\CMakeLogo.ico")
set(CPACK_NSIS_MUI_UNIICON "@CMake_SOURCE_DIR@/Utilities/Release\\CMakeLogo.ico") set(CPACK_NSIS_MUI_UNIICON "@CMake_SOURCE_DIR@/Utilities/Release\\CMakeLogo.ico")

@ -1,7 +1,7 @@
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying # Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details. # file Copyright.txt or https://cmake.org/licensing for details.
cmake_minimum_required(VERSION 3.13...3.25 FATAL_ERROR) cmake_minimum_required(VERSION 3.13...3.26 FATAL_ERROR)
set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake) set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake)
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake) set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake)
@ -131,6 +131,8 @@ if(CMake_BUILD_LTO)
endif() endif()
endif() endif()
option(CMake_BUILD_PCH "Compile CMake with precompiled headers" OFF)
# Check whether to build support for the debugger mode. # Check whether to build support for the debugger mode.
if(NOT CMake_TEST_EXTERNAL_CMAKE) if(NOT CMake_TEST_EXTERNAL_CMAKE)
if(NOT DEFINED CMake_ENABLE_DEBUGGER) if(NOT DEFINED CMake_ENABLE_DEBUGGER)
@ -153,7 +155,6 @@ endif()
# simply to improve readability of the main script # simply to improve readability of the main script
#----------------------------------------------------------------------- #-----------------------------------------------------------------------
macro(CMAKE_HANDLE_SYSTEM_LIBRARIES) macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
# Options have dependencies.
include(CMakeDependentOption) include(CMakeDependentOption)
# Allow the user to enable/disable all system utility library options by # Allow the user to enable/disable all system utility library options by
@ -324,6 +325,9 @@ configure_file(.clang-tidy .clang-tidy COPYONLY)
option(CMake_RUN_IWYU "Run include-what-you-use with the compiler." OFF) option(CMake_RUN_IWYU "Run include-what-you-use with the compiler." OFF)
if(CMake_RUN_IWYU) if(CMake_RUN_IWYU)
if(CMake_BUILD_PCH)
message(FATAL_ERROR "CMake_RUN_IWYU and CMake_BUILD_PCH are ON, but they are incompatible!")
endif()
find_program(IWYU_COMMAND NAMES include-what-you-use iwyu) find_program(IWYU_COMMAND NAMES include-what-you-use iwyu)
if(NOT IWYU_COMMAND) if(NOT IWYU_COMMAND)
message(FATAL_ERROR "CMake_RUN_IWYU is ON but include-what-you-use is not found!") message(FATAL_ERROR "CMake_RUN_IWYU is ON but include-what-you-use is not found!")

@ -211,7 +211,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``.
* |SYSTEM_ENVIRONMENT_PATH_XXX| * |SYSTEM_ENVIRONMENT_PATH_XXX|
* |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|
|SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|
6. Search cmake variables defined in the Platform files 6. Search cmake variables defined in the Platform files
for the current system. The searching of ``CMAKE_INSTALL_PREFIX`` and for the current system. The searching of ``CMAKE_INSTALL_PREFIX`` and

@ -24,6 +24,7 @@ The first signature is for adding a custom command to produce an output:
[COMMENT comment] [COMMENT comment]
[DEPFILE depfile] [DEPFILE depfile]
[JOB_POOL job_pool] [JOB_POOL job_pool]
[JOB_SERVER_AWARE <bool>]
[VERBATIM] [APPEND] [USES_TERMINAL] [VERBATIM] [APPEND] [USES_TERMINAL]
[COMMAND_EXPAND_LISTS] [COMMAND_EXPAND_LISTS]
[DEPENDS_EXPLICIT_ONLY]) [DEPENDS_EXPLICIT_ONLY])
@ -86,6 +87,11 @@ The options are:
:ref:`Target-dependent expressions <Target-Dependent Queries>` are not :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
permitted. permitted.
.. versionchanged:: 3.28
In targets using :ref:`file sets`, custom command byproducts are now
considered private unless they are listed in a non-private file set.
See policy :policy:`CMP0154`.
``COMMAND`` ``COMMAND``
Specify the command-line(s) to execute at build time. Specify the command-line(s) to execute at build time.
If more than one ``COMMAND`` is specified they will be executed in order, If more than one ``COMMAND`` is specified they will be executed in order,
@ -221,6 +227,19 @@ The options are:
Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
an error by ninja at build time. an error by ninja at build time.
``JOB_SERVER_AWARE``
.. versionadded:: 3.28
Specify that the command is GNU Make job server aware.
For the :generator:`Unix Makefiles`, :generator:`MSYS Makefiles`, and
:generator:`MinGW Makefiles` generators this will add the ``+`` prefix to the
recipe line. See the `GNU Make Documentation`_ for more information.
This option is silently ignored by other generators.
.. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html
``MAIN_DEPENDENCY`` ``MAIN_DEPENDENCY``
Specify the primary input source file to the command. This is Specify the primary input source file to the command. This is
treated just like any value given to the ``DEPENDS`` option treated just like any value given to the ``DEPENDS`` option
@ -256,6 +275,11 @@ The options are:
:ref:`Target-dependent expressions <Target-Dependent Queries>` are not :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
permitted. permitted.
.. versionchanged:: 3.28
In targets using :ref:`file sets`, custom command outputs are now
considered private unless they are listed in a non-private file set.
See policy :policy:`CMP0154`.
``USES_TERMINAL`` ``USES_TERMINAL``
.. versionadded:: 3.2 .. versionadded:: 3.2
@ -516,7 +540,7 @@ one of the keywords to make clear the behavior they expect.
Because generator expressions can be used in custom commands, Because generator expressions can be used in custom commands,
it is possible to define ``COMMAND`` lines or whole custom commands it is possible to define ``COMMAND`` lines or whole custom commands
which evaluate to empty strings for certain configurations. which evaluate to empty strings for certain configurations.
For **Visual Studio 11 2012 (and newer)** generators these command For **Visual Studio 12 2013 (and newer)** generators these command
lines or custom commands will be omitted for the specific lines or custom commands will be omitted for the specific
configuration and no "empty-string-command" will be added. configuration and no "empty-string-command" will be added.

@ -12,6 +12,7 @@ Add a target with no output so it will always be built.
[WORKING_DIRECTORY dir] [WORKING_DIRECTORY dir]
[COMMENT comment] [COMMENT comment]
[JOB_POOL job_pool] [JOB_POOL job_pool]
[JOB_SERVER_AWARE <bool>]
[VERBATIM] [USES_TERMINAL] [VERBATIM] [USES_TERMINAL]
[COMMAND_EXPAND_LISTS] [COMMAND_EXPAND_LISTS]
[SOURCES src1 [src2...]]) [SOURCES src1 [src2...]])
@ -62,6 +63,11 @@ The options are:
:ref:`Target-dependent expressions <Target-Dependent Queries>` are not :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
permitted. permitted.
.. versionchanged:: 3.28
In custom targets using :ref:`file sets`, byproducts are now
considered private unless they are listed in a non-private file set.
See policy :policy:`CMP0154`.
``COMMAND`` ``COMMAND``
Specify the command-line(s) to execute at build time. Specify the command-line(s) to execute at build time.
If more than one ``COMMAND`` is specified they will be executed in order, If more than one ``COMMAND`` is specified they will be executed in order,
@ -146,6 +152,19 @@ The options are:
Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
an error by ninja at build time. an error by ninja at build time.
``JOB_SERVER_AWARE``
.. versionadded:: 3.28
Specify that the command is GNU Make job server aware.
For the :generator:`Unix Makefiles`, :generator:`MSYS Makefiles`, and
:generator:`MinGW Makefiles` generators this will add the ``+`` prefix to the
recipe line. See the `GNU Make Documentation`_ for more information.
This option is silently ignored by other generators.
.. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html
``SOURCES`` ``SOURCES``
Specify additional source files to be included in the custom target. Specify additional source files to be included in the custom target.
Specified source files will be added to IDE project files for Specified source files will be added to IDE project files for

@ -21,7 +21,8 @@ scopes created by the ``block()`` command are removed.
``POLICIES`` ``POLICIES``
Create a new policy scope. This is equivalent to Create a new policy scope. This is equivalent to
:command:`cmake_policy(PUSH)`. :command:`cmake_policy(PUSH)` with an automatic
:command:`cmake_policy(POP)` when leaving the block scope.
``VARIABLES`` ``VARIABLES``
Create a new variable scope. Create a new variable scope.

@ -146,6 +146,13 @@ queried. The list of queried values is stored in ``<variable>``.
See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`
``MSYSTEM_PREFIX``
.. versionadded:: 3.28
Available only on Windows hosts. In a MSYS or MinGW development
environment that sets the ``MSYSTEM`` environment variable, this
is its installation prefix. Otherwise, this is the empty string.
``DISTRIB_INFO`` ``DISTRIB_INFO``
.. versionadded:: 3.22 .. versionadded:: 3.22

@ -195,7 +195,7 @@ prints::
Immediate Message Immediate Message
Deferred Message Deferred Message
The ``Cancelled Message`` is never printed because its command is The ``Canceled Message`` is never printed because its command is
canceled. The ``deferred_message`` variable reference is not evaluated canceled. The ``deferred_message`` variable reference is not evaluated
until the call site, so it can be set after the deferred call is scheduled. until the call site, so it can be set after the deferred call is scheduled.

@ -24,9 +24,8 @@ The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
behavior. While setting policies individually is supported, we behavior. While setting policies individually is supported, we
encourage projects to set policies based on CMake versions: encourage projects to set policies based on CMake versions:
.. code-block:: cmake .. signature:: cmake_policy(VERSION <min>[...<max>])
:target: VERSION
cmake_policy(VERSION <min>[...<max>])
.. versionadded:: 3.12 .. versionadded:: 3.12
The optional ``<max>`` version. The optional ``<max>`` version.
@ -57,10 +56,8 @@ command implicitly calls ``cmake_policy(VERSION)`` too.
Setting Policies Explicitly Setting Policies Explicitly
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake .. signature:: cmake_policy(SET CMP<NNNN> NEW|OLD)
:target: SET
cmake_policy(SET CMP<NNNN> NEW)
cmake_policy(SET CMP<NNNN> OLD)
Tell CMake to use the ``OLD`` or ``NEW`` behavior for a given policy. Tell CMake to use the ``OLD`` or ``NEW`` behavior for a given policy.
Projects depending on the old behavior of a given policy may silence a Projects depending on the old behavior of a given policy may silence a
@ -73,9 +70,8 @@ policy state to ``NEW``.
Checking Policy Settings Checking Policy Settings
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake .. signature:: cmake_policy(GET CMP<NNNN> <variable>)
:target: GET
cmake_policy(GET CMP<NNNN> <variable>)
Check whether a given policy is set to ``OLD`` or ``NEW`` behavior. Check whether a given policy is set to ``OLD`` or ``NEW`` behavior.
The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the
@ -94,23 +90,27 @@ except when invoked with the ``NO_POLICY_SCOPE`` option
The ``cmake_policy`` command provides an interface to manage custom The ``cmake_policy`` command provides an interface to manage custom
entries on the policy stack: entries on the policy stack:
.. code-block:: cmake .. signature:: cmake_policy(PUSH)
:target: PUSH
cmake_policy(PUSH) Create a new entry on the policy stack.
cmake_policy(POP)
.. signature:: cmake_policy(POP)
:target: POP
Remove the last policy stack entry created with ``cmake_policy(PUSH)``.
Each ``PUSH`` must have a matching ``POP`` to erase any changes. Each ``PUSH`` must have a matching ``POP`` to erase any changes.
This is useful to make temporary changes to policy settings. This is useful to make temporary changes to policy settings.
Calls to the :command:`cmake_minimum_required(VERSION)`, Calls to the :command:`cmake_minimum_required(VERSION)`,
``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands :command:`cmake_policy(VERSION)`, or :command:`cmake_policy(SET)` commands
influence only the current top of the policy stack. influence only the current top of the policy stack.
.. versionadded:: 3.25 .. versionadded:: 3.25
The :command:`block` and :command:`endblock` commands offer a more flexible The :command:`block(SCOPE_FOR POLICIES)` command offers a more flexible
and more secure way to manage the policy stack. The pop action is done and more secure way to manage the policy stack. The pop action is done
automatically when the :command:`endblock` command is executed, so it avoid automatically when leaving the block scope, so there is no need to
to call the :command:`cmake_policy(POP)` command before each precede each :command:`return` with a call to :command:`cmake_policy(POP)`.
:command:`return` command.
.. code-block:: cmake .. code-block:: cmake

@ -1,6 +1,10 @@
exec_program exec_program
------------ ------------
.. versionchanged:: 3.28
This command is available only if policy :policy:`CMP0153` is not set to ``NEW``.
Port projects to the :command:`execute_process` command.
.. deprecated:: 3.0 .. deprecated:: 3.0
Use the :command:`execute_process` command instead. Use the :command:`execute_process` command instead.

@ -54,10 +54,7 @@ The options are:
to support consumers using CMake versions older than 2.8.12. to support consumers using CMake versions older than 2.8.12.
``CXX_MODULES_DIRECTORY <directory>`` ``CXX_MODULES_DIRECTORY <directory>``
.. versionadded:: 3.28
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Export C++ module properties to files under the given directory. Each file Export C++ module properties to files under the given directory. Each file
will be named according to the target's export name (without any namespace). will be named according to the target's export name (without any namespace).

@ -981,6 +981,11 @@ Path Conversion
if ``USERPROFILE`` is not defined. On all other platforms, only ``HOME`` if ``USERPROFILE`` is not defined. On all other platforms, only ``HOME``
is used. is used.
.. versionchanged:: 3.28
All symlinks are resolved before collapsing ``../`` components.
See policy :policy:`CMP0152`.
.. signature:: .. signature::
file(RELATIVE_PATH <variable> <directory> <file>) file(RELATIVE_PATH <variable> <directory> <file>)

@ -28,9 +28,11 @@ find_file
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE`` .. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
and ``PATH``. and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: .. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
This behavior was removed by CMake 3.28.
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`

@ -27,9 +27,11 @@ find_library
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``LIB`` .. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``LIB``
and ``PATH``. and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: .. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
This behavior was removed by CMake 3.28.
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
@ -60,6 +62,10 @@ path to the framework ``<fullPath>/A.framework``. When a full path to a
framework is used as a library, CMake will use a ``-framework A``, and a framework is used as a library, CMake will use a ``-framework A``, and a
``-F<fullPath>`` to link the framework to the target. ``-F<fullPath>`` to link the framework to the target.
.. versionadded:: 3.28
The library found can now be a ``.xcframework`` folder.
If the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable is set all If the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable is set all
search paths will be tested as normal, with the suffix appended, and with search paths will be tested as normal, with the suffix appended, and with
all matches of ``lib/`` replaced with all matches of ``lib/`` replaced with

@ -323,18 +323,27 @@ containing a configuration file:
In all cases the ``<name>`` is treated as case-insensitive and corresponds In all cases the ``<name>`` is treated as case-insensitive and corresponds
to any of the names specified (``<PackageName>`` or names given by ``NAMES``). to any of the names specified (``<PackageName>`` or names given by ``NAMES``).
Paths with ``lib/<arch>`` are enabled if the If at least one compiled language has been enabled, the architecture-specific
:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one ``lib/<arch>`` and ``lib*`` directories may be searched based on the compiler's
or more of the values ``lib64``, ``lib32``, ``libx32`` or ``lib`` (searched in target architecture, in the following order:
that order).
* Paths with ``lib64`` are searched on 64 bit platforms if the ``lib/<arch>``
Searched if the :variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set.
``lib64``
Searched on 64 bit platforms (:variable:`CMAKE_SIZEOF_VOID_P` is 8) and the
:prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` property is set to ``TRUE``. :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` property is set to ``TRUE``.
* Paths with ``lib32`` are searched on 32 bit platforms if the
``lib32``
Searched on 32 bit platforms (:variable:`CMAKE_SIZEOF_VOID_P` is 4) and the
:prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` property is set to ``TRUE``. :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` property is set to ``TRUE``.
* Paths with ``libx32`` are searched on platforms using the x32 ABI
``libx32``
Searched on platforms using the x32 ABI
if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``. if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``.
* The ``lib`` path is always searched.
``lib``
Always searched.
.. versionchanged:: 3.24 .. versionchanged:: 3.24
On ``Windows`` platform, it is possible to include registry queries as part On ``Windows`` platform, it is possible to include registry queries as part

@ -27,9 +27,11 @@ find_path
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE`` .. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
and ``PATH``. and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: .. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
This behavior was removed by CMake 3.28.
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`

@ -23,7 +23,7 @@ find_program
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_APPBUNDLE_PATH` .. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_APPBUNDLE_PATH`
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` itself. .. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` itself.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts no extra search paths are included .. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: \
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
|CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|

@ -12,7 +12,8 @@ Get a property.
SOURCE <source> SOURCE <source>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] | [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> | INSTALL <file> |
TEST <test> | TEST <test>
[DIRECTORY <dir>] |
CACHE <entry> | CACHE <entry> |
VARIABLE > VARIABLE >
PROPERTY <name> PROPERTY <name>
@ -73,6 +74,16 @@ It must be one of the following:
Scope must name one existing test. Scope must name one existing test.
See also the :command:`get_test_property` command. See also the :command:`get_test_property` command.
.. versionadded:: 3.28
Directory scope can be overridden with the following sub-option:
``DIRECTORY <dir>``
The test property will be read from the ``<dir>`` directory's
scope. CMake must already know about the directory, either by having added
it through a call to :command:`add_subdirectory` or ``<dir>`` being the top
level directory. Relative paths are treated as relative to the current
source directory. ``<dir>`` may reference a binary directory.
``CACHE`` ``CACHE``
Scope must name one cache entry. Scope must name one cache entry.

@ -5,7 +5,7 @@ Get a property of the test.
.. code-block:: cmake .. code-block:: cmake
get_test_property(test property VAR) get_test_property(test property [DIRECTORY <dir>] VAR)
Get a property from the test. The value of the property is stored in Get a property from the test. The value of the property is stored in
the variable ``VAR``. If the test property is not found, the behavior the variable ``VAR``. If the test property is not found, the behavior
@ -19,6 +19,17 @@ an empty string.
For a list of standard properties you can type For a list of standard properties you can type
:option:`cmake --help-property-list`. :option:`cmake --help-property-list`.
.. versionadded:: 3.28
Directory scope can be overridden with the following sub-option:
``DIRECTORY <dir>``
The test property will be read from the ``<dir>`` directory's
scope. CMake must already know about that source directory, either by
having added it through a call to :command:`add_subdirectory` or ``<dir>``
being the top level source directory. Relative paths are treated as
relative to the current source directory. ``<dir>`` may reference a binary
directory.
See Also See Also
^^^^^^^^ ^^^^^^^^

@ -228,36 +228,36 @@ Comparisons
.. signature:: if(<variable|string> LESS <variable|string>) .. signature:: if(<variable|string> LESS <variable|string>)
:target: LESS :target: LESS
True if the given string or variable's value is a valid number and less True if the given string or variable's value parses as a real number
than that on the right. (like a C ``double``) and less than that on the right.
.. signature:: if(<variable|string> GREATER <variable|string>) .. signature:: if(<variable|string> GREATER <variable|string>)
:target: GREATER :target: GREATER
True if the given string or variable's value is a valid number and greater True if the given string or variable's value parses as a real number
than that on the right. (like a C ``double``) and greater than that on the right.
.. signature:: if(<variable|string> EQUAL <variable|string>) .. signature:: if(<variable|string> EQUAL <variable|string>)
:target: EQUAL :target: EQUAL
True if the given string or variable's value is a valid number and equal True if the given string or variable's value parses as a real number
to that on the right. (like a C ``double``) and equal to that on the right.
.. signature:: if(<variable|string> LESS_EQUAL <variable|string>) .. signature:: if(<variable|string> LESS_EQUAL <variable|string>)
:target: LESS_EQUAL :target: LESS_EQUAL
.. versionadded:: 3.7 .. versionadded:: 3.7
True if the given string or variable's value is a valid number and less True if the given string or variable's value parses as a real number
than or equal to that on the right. (like a C ``double``) and less than or equal to that on the right.
.. signature:: if(<variable|string> GREATER_EQUAL <variable|string>) .. signature:: if(<variable|string> GREATER_EQUAL <variable|string>)
:target: GREATER_EQUAL :target: GREATER_EQUAL
.. versionadded:: 3.7 .. versionadded:: 3.7
True if the given string or variable's value is a valid number and greater True if the given string or variable's value parses as a real number
than or equal to that on the right. (like a C ``double``) and greater than or equal to that on the right.
.. signature:: if(<variable|string> STRLESS <variable|string>) .. signature:: if(<variable|string> STRLESS <variable|string>)
:target: STRLESS :target: STRLESS

@ -1,6 +1,10 @@
install install
------- -------
.. only:: html
.. contents::
Specify rules to run at install time. Specify rules to run at install time.
Synopsis Synopsis
@ -34,12 +38,14 @@ are executed in order during installation.
The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
default copying behavior of ``install()``. default copying behavior of ``install()``.
.. _`common options`:
There are multiple signatures for this command. Some of them define There are multiple signatures for this command. Some of them define
installation options for files and targets. Options common to installation options for files and targets. Options common to
multiple signatures are covered here but they are valid only for multiple signatures are covered here but they are valid only for
signatures that specify them. The common options are: signatures that specify them. The common options are:
``DESTINATION`` ``DESTINATION <dir>``
Specify the directory on disk to which a file will be installed. Specify the directory on disk to which a file will be installed.
Arguments can be relative or absolute paths. Arguments can be relative or absolute paths.
@ -58,32 +64,28 @@ signatures that specify them. The common options are:
:variable:`CMAKE_INSTALL_PREFIX`; this prefix is used by default if :variable:`CMAKE_INSTALL_PREFIX`; this prefix is used by default if
the DESTINATION is a relative path. the DESTINATION is a relative path.
``PERMISSIONS`` ``PERMISSIONS <permission>...``
Specify permissions for installed files. Valid permissions are Specify permissions for installed files. Valid permissions are
``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``, ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``,
``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, ``WORLD_WRITE``, ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, ``WORLD_WRITE``,
``WORLD_EXECUTE``, ``SETUID``, and ``SETGID``. Permissions that do ``WORLD_EXECUTE``, ``SETUID``, and ``SETGID``. Permissions that do
not make sense on certain platforms are ignored on those platforms. not make sense on certain platforms are ignored on those platforms.
``CONFIGURATIONS`` If this option is used multiple times in a single call, its list
Specify a list of build configurations for which the install rule of permissions accumulates. If an :command:`install(TARGETS)` call
applies (Debug, Release, etc.). Note that the values specified for uses `\<artifact-kind\>`_ arguments, a separate list of permissions
this option only apply to options listed AFTER the ``CONFIGURATIONS`` is accumulated for each kind of artifact.
option. For example, to set separate install paths for the Debug and
Release configurations, do the following:
.. code-block:: cmake
install(TARGETS target ``CONFIGURATIONS <config>...``
CONFIGURATIONS Debug Specify a list of build configurations for which the install rule
RUNTIME DESTINATION Debug/bin) applies (Debug, Release, etc.).
install(TARGETS target
CONFIGURATIONS Release
RUNTIME DESTINATION Release/bin)
Note that ``CONFIGURATIONS`` appears BEFORE ``RUNTIME DESTINATION``. If this option is used multiple times in a single call, its list
of configurations accumulates. If an :command:`install(TARGETS)`
call uses `\<artifact-kind\>`_ arguments, a separate list of
configurations is accumulated for each kind of artifact.
``COMPONENT`` ``COMPONENT <component>``
Specify an installation component name with which the install rule Specify an installation component name with which the install rule
is associated, such as ``Runtime`` or ``Development``. During is associated, such as ``Runtime`` or ``Development``. During
component-specific installation only install rules associated with component-specific installation only install rules associated with
@ -99,7 +101,7 @@ signatures that specify them. The common options are:
Specify that the file is excluded from a full installation and only Specify that the file is excluded from a full installation and only
installed as part of a component-specific installation installed as part of a component-specific installation
``RENAME`` ``RENAME <name>``
Specify a name for an installed file that may be different from the Specify a name for an installed file that may be different from the
original file. Renaming is allowed only when a single file is original file. Renaming is allowed only when a single file is
installed by the command. installed by the command.
@ -121,32 +123,43 @@ signatures that specify them. The common options are:
they will be created according to the uname rules on Unix-like platforms. they will be created according to the uname rules on Unix-like platforms.
Windows platforms are unaffected. Windows platforms are unaffected.
Installing Targets Signatures
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^
.. signature::
install(TARGETS <target>... [...])
.. _`install(TARGETS)`: Install target :ref:`Output Artifacts` and associated files:
.. _TARGETS:
.. code-block:: cmake
install(TARGETS <target>... [EXPORT <export-name>]
[RUNTIME_DEPENDENCIES <arg>...|RUNTIME_DEPENDENCY_SET <set-name>]
[<artifact-option>...]
[<artifact-kind> <artifact-option>...]...
[INCLUDES DESTINATION [<dir> ...]]
)
where ``<artifact-option>...`` group may contain:
.. code-block:: cmake .. code-block:: cmake
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|FILE_SET <set-name>|CXX_MODULES_BMI]
[DESTINATION <dir>] [DESTINATION <dir>]
[PERMISSIONS permissions...] [PERMISSIONS <permission>...]
[CONFIGURATIONS [Debug|Release|...]] [CONFIGURATIONS <config>...]
[COMPONENT <component>] [COMPONENT <component>]
[NAMELINK_COMPONENT <component>] [NAMELINK_COMPONENT <component>]
[OPTIONAL] [EXCLUDE_FROM_ALL] [OPTIONAL] [EXCLUDE_FROM_ALL]
[NAMELINK_ONLY|NAMELINK_SKIP] [NAMELINK_ONLY|NAMELINK_SKIP]
] [...]
[INCLUDES DESTINATION [<dir> ...]]
)
The ``TARGETS`` form specifies rules for installing targets from a The first ``<artifact-option>...`` group applies to target
project. There are several kinds of target :ref:`Output Artifacts` :ref:`Output Artifacts` that do not have a dedicated group specified
that may be installed: later in the same call.
.. _`<artifact-kind>`:
Each ``<artifact-kind> <artifact-option>...`` group applies to
:ref:`Output Artifacts` of the specified artifact kind:
``ARCHIVE`` ``ARCHIVE``
Target artifacts of this kind include: Target artifacts of this kind include:
@ -207,22 +220,19 @@ that may be installed:
Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for
``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details. ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details.
``FILE_SET <set>`` ``FILE_SET <set-name>``
.. versionadded:: 3.23 .. versionadded:: 3.23
File sets are defined by the :command:`target_sources(FILE_SET)` command. File sets are defined by the :command:`target_sources(FILE_SET)` command.
If the file set ``<set>`` exists and is ``PUBLIC`` or ``INTERFACE``, any If the file set ``<set-name>`` exists and is ``PUBLIC`` or ``INTERFACE``,
files in the set are installed under the destination (see below). any files in the set are installed under the destination (see below).
The directory structure relative to the file set's base directories is The directory structure relative to the file set's base directories is
preserved. For example, a file added to the file set as preserved. For example, a file added to the file set as
``/blah/include/myproj/here.h`` with a base directory ``/blah/include`` ``/blah/include/myproj/here.h`` with a base directory ``/blah/include``
would be installed to ``myproj/here.h`` below the destination. would be installed to ``myproj/here.h`` below the destination.
``CXX_MODULES_BMI`` ``CXX_MODULES_BMI``
.. versionadded:: 3.28
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Any module files from C++ modules from ``PUBLIC`` sources in a file set of Any module files from C++ modules from ``PUBLIC`` sources in a file set of
type ``CXX_MODULES`` will be installed to the given ``DESTINATION``. All type ``CXX_MODULES`` will be installed to the given ``DESTINATION``. All
@ -230,10 +240,6 @@ that may be installed:
derived from the names of the modules. An empty ``DESTINATION`` may be used derived from the names of the modules. An empty ``DESTINATION`` may be used
to suppress installing these files (for use in generic code). to suppress installing these files (for use in generic code).
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.
For regular executables, static libraries and shared libraries, the For regular executables, static libraries and shared libraries, the
``DESTINATION`` argument is not required. For these target types, when ``DESTINATION`` argument is not required. For these target types, when
``DESTINATION`` is omitted, a default destination will be taken from the ``DESTINATION`` is omitted, a default destination will be taken from the
@ -292,7 +298,7 @@ subdirectory without using file sets:
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
) )
In addition to the common options listed above, each target can accept In addition to the `common options`_ listed above, each target can accept
the following additional arguments: the following additional arguments:
``NAMELINK_COMPONENT`` ``NAMELINK_COMPONENT``
@ -316,24 +322,8 @@ the following additional arguments:
the linker import file created, on macOS, for shared libraries with the linker import file created, on macOS, for shared libraries with
:prop_tgt:`ENABLE_EXPORTS` enabled. :prop_tgt:`ENABLE_EXPORTS` enabled.
Consider the following example: See the `Example: Install Targets with Per-Artifact Components`_
for an example using ``NAMELINK_COMPONENT``.
.. code-block:: cmake
install(TARGETS mylib
LIBRARY
COMPONENT Libraries
NAMELINK_COMPONENT Development
PUBLIC_HEADER
COMPONENT Development
)
In this scenario, if you choose to install only the ``Development``
component, both the headers and namelink will be installed without the
library. (If you don't also install the ``Libraries`` component, the
namelink will be a dangling symlink, and projects that link to the library
will have build errors.) If you install only the ``Libraries`` component,
only the library will be installed, without the headers and namelink.
This option is typically used for package managers that have separate This option is typically used for package managers that have separate
runtime and development packages. For example, on Debian systems, the runtime and development packages. For example, on Debian systems, the
@ -377,13 +367,14 @@ the following additional arguments:
is not recommended to use ``NAMELINK_SKIP`` in conjunction with is not recommended to use ``NAMELINK_SKIP`` in conjunction with
``NAMELINK_COMPONENT``. ``NAMELINK_COMPONENT``.
The `install(TARGETS)`_ command can also accept the following options at the The :command:`install(TARGETS)` command can also accept the following
top level: options at the top level:
``EXPORT`` ``EXPORT``
This option associates the installed target files with an export called This option associates the installed target files with an export called
``<export-name>``. It must appear before any target options. To actually ``<export-name>``. It must appear before any target options.
install the export file itself, call `install(EXPORT)`_, documented below. To actually install the export file itself, call
:command:`install(EXPORT)`, documented below.
See documentation of the :prop_tgt:`EXPORT_NAME` target property to change See documentation of the :prop_tgt:`EXPORT_NAME` target property to change
the name of the exported target. the name of the exported target.
@ -395,22 +386,22 @@ top level:
``INCLUDES DESTINATION`` ``INCLUDES DESTINATION``
This option specifies a list of directories which will be added to the This option specifies a list of directories which will be added to the
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
``<targets>`` when exported by the `install(EXPORT)`_ command. If a ``<targets>`` when exported by the :command:`install(EXPORT)` command.
relative path is specified, it is treated as relative to the If a relative path is specified, it is treated as relative to the
:genex:`$<INSTALL_PREFIX>`. :genex:`$<INSTALL_PREFIX>`.
``RUNTIME_DEPENDENCY_SET`` ``RUNTIME_DEPENDENCY_SET <set-name>``
.. versionadded:: 3.21 .. versionadded:: 3.21
This option causes all runtime dependencies of installed executable, shared This option causes all runtime dependencies of installed executable, shared
library, and module targets to be added to the specified runtime dependency library, and module targets to be added to the specified runtime dependency
set. This set can then be installed with an set. This set can then be installed with an
`install(RUNTIME_DEPENDENCY_SET)`_ command. :command:`install(RUNTIME_DEPENDENCY_SET)` command.
This keyword and the ``RUNTIME_DEPENDENCIES`` keyword are mutually This keyword and the ``RUNTIME_DEPENDENCIES`` keyword are mutually
exclusive. exclusive.
``RUNTIME_DEPENDENCIES`` ``RUNTIME_DEPENDENCIES <arg>...``
.. versionadded:: 3.21 .. versionadded:: 3.21
This option causes all runtime dependencies of installed executable, shared This option causes all runtime dependencies of installed executable, shared
@ -425,11 +416,11 @@ top level:
.. code-block:: cmake .. code-block:: cmake
install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>) install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>)
install(RUNTIME_DEPENDENCY_SET <set-name> args...) install(RUNTIME_DEPENDENCY_SET <set-name> <arg>...)
where ``<set-name>`` will be a randomly generated set name. where ``<set-name>`` will be a randomly generated set name.
The ``args...`` may include any of the following keywords supported by ``<arg>...`` may include any of the following keywords supported by
the `install(RUNTIME_DEPENDENCY_SET)`_ command: the :command:`install(RUNTIME_DEPENDENCY_SET)` command:
* ``DIRECTORIES`` * ``DIRECTORIES``
* ``PRE_INCLUDE_REGEXES`` * ``PRE_INCLUDE_REGEXES``
@ -442,26 +433,6 @@ top level:
The ``RUNTIME_DEPENDENCIES`` and ``RUNTIME_DEPENDENCY_SET`` keywords are The ``RUNTIME_DEPENDENCIES`` and ``RUNTIME_DEPENDENCY_SET`` keywords are
mutually exclusive. mutually exclusive.
One or more groups of properties may be specified in a single call to
the ``TARGETS`` form of this command. A target may be installed more than
once to different locations. Consider hypothetical targets ``myExe``,
``mySharedLib``, and ``myStaticLib``. The code:
.. code-block:: cmake
install(TARGETS myExe mySharedLib myStaticLib
RUNTIME DESTINATION bin
LIBRARY DESTINATION lib
ARCHIVE DESTINATION lib/static)
install(TARGETS mySharedLib DESTINATION /some/full/path)
will install ``myExe`` to ``<prefix>/bin`` and ``myStaticLib`` to
``<prefix>/lib/static``. On non-DLL platforms ``mySharedLib`` will be
installed to ``<prefix>/lib`` and ``/some/full/path``. On DLL platforms
the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and
``/some/full/path`` and its import library will be installed to
``<prefix>/lib/static`` and ``/some/full/path``.
:ref:`Interface Libraries` may be listed among the targets to install. :ref:`Interface Libraries` may be listed among the targets to install.
They install no artifacts but will be included in an associated ``EXPORT``. They install no artifacts but will be included in an associated ``EXPORT``.
If :ref:`Object Libraries` are listed but given no destination for their If :ref:`Object Libraries` are listed but given no destination for their
@ -478,7 +449,7 @@ set to ``TRUE`` has undefined behavior.
:manual:`cmake-generator-expressions(7)` manual for available expressions. :manual:`cmake-generator-expressions(7)` manual for available expressions.
.. versionadded:: 3.13 .. versionadded:: 3.13
`install(TARGETS)`_ can install targets that were created in :command:`install(TARGETS)` can install targets that were created in
other directories. When using such cross-directory install rules, running other directories. When using such cross-directory install rules, running
``make install`` (or similar) from a subdirectory will not guarantee that ``make install`` (or similar) from a subdirectory will not guarantee that
targets from other directories are up-to-date. You can use targets from other directories are up-to-date. You can use
@ -486,22 +457,21 @@ set to ``TRUE`` has undefined behavior.
to ensure that such out-of-directory targets are built before the to ensure that such out-of-directory targets are built before the
subdirectory-specific install rules are run. subdirectory-specific install rules are run.
Installing Imported Runtime Artifacts .. signature::
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])
.. _`install(IMPORTED_RUNTIME_ARTIFACTS)`:
.. _IMPORTED_RUNTIME_ARTIFACTS:
.. versionadded:: 3.21 .. versionadded:: 3.21
Install runtime artifacts of imported targets:
.. code-block:: cmake .. code-block:: cmake
install(IMPORTED_RUNTIME_ARTIFACTS targets... install(IMPORTED_RUNTIME_ARTIFACTS <target>...
[RUNTIME_DEPENDENCY_SET <set-name>] [RUNTIME_DEPENDENCY_SET <set-name>]
[[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE] [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
[DESTINATION <dir>] [DESTINATION <dir>]
[PERMISSIONS permissions...] [PERMISSIONS <permission>...]
[CONFIGURATIONS [Debug|Release|...]] [CONFIGURATIONS <config>...]
[COMPONENT <component>] [COMPONENT <component>]
[OPTIONAL] [EXCLUDE_FROM_ALL] [OPTIONAL] [EXCLUDE_FROM_ALL]
] [...] ] [...]
@ -522,15 +492,11 @@ entire directory is installed.
The ``RUNTIME_DEPENDENCY_SET`` option causes the runtime artifacts of the The ``RUNTIME_DEPENDENCY_SET`` option causes the runtime artifacts of the
imported executable, shared library, and module library ``targets`` to be imported executable, shared library, and module library ``targets`` to be
added to the ``<set-name>`` runtime dependency set. This set can then be added to the ``<set-name>`` runtime dependency set. This set can then be
installed with an `install(RUNTIME_DEPENDENCY_SET)`_ command. installed with an :command:`install(RUNTIME_DEPENDENCY_SET)` command.
Installing Files
^^^^^^^^^^^^^^^^
.. _`install(FILES)`: .. signature::
.. _`install(PROGRAMS)`: install(FILES <file>... [...])
.. _FILES: install(PROGRAMS <program>... [...])
.. _PROGRAMS:
.. note:: .. note::
@ -538,12 +504,14 @@ Installing Files
:command:`target_sources(FILE_SET)` instead. File sets associate :command:`target_sources(FILE_SET)` instead. File sets associate
headers with a target and they install as part of the target. headers with a target and they install as part of the target.
Install files or programs:
.. code-block:: cmake .. code-block:: cmake
install(<FILES|PROGRAMS> files... install(<FILES|PROGRAMS> <file>...
TYPE <type> | DESTINATION <dir> TYPE <type> | DESTINATION <dir>
[PERMISSIONS permissions...] [PERMISSIONS <permission>...]
[CONFIGURATIONS [Debug|Release|...]] [CONFIGURATIONS <config>...]
[COMPONENT <component>] [COMPONENT <component>]
[RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL]) [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
@ -628,11 +596,8 @@ subdirectory:
use "generator expressions" with the syntax ``$<...>``. See the use "generator expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions. :manual:`cmake-generator-expressions(7)` manual for available expressions.
Installing Directories .. signature::
^^^^^^^^^^^^^^^^^^^^^^ install(DIRECTORY <dir>... [...])
.. _`install(DIRECTORY)`:
.. _DIRECTORY:
.. note:: .. note::
@ -641,18 +606,20 @@ Installing Directories
preserve directory structure, they also associate headers with a target preserve directory structure, they also associate headers with a target
and install as part of the target. and install as part of the target.
Install the contents of one or more directories:
.. code-block:: cmake .. code-block:: cmake
install(DIRECTORY dirs... install(DIRECTORY dirs...
TYPE <type> | DESTINATION <dir> TYPE <type> | DESTINATION <dir>
[FILE_PERMISSIONS permissions...] [FILE_PERMISSIONS <permission>...]
[DIRECTORY_PERMISSIONS permissions...] [DIRECTORY_PERMISSIONS <permission>...]
[USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
[CONFIGURATIONS [Debug|Release|...]] [CONFIGURATIONS <config>...]
[COMPONENT <component>] [EXCLUDE_FROM_ALL] [COMPONENT <component>] [EXCLUDE_FROM_ALL]
[FILES_MATCHING] [FILES_MATCHING]
[[PATTERN <pattern> | REGEX <regex>] [[PATTERN <pattern> | REGEX <regex>]
[EXCLUDE] [PERMISSIONS permissions...]] [...]) [EXCLUDE] [PERMISSIONS <permission>...]] [...])
The ``DIRECTORY`` form installs contents of one or more directories to a The ``DIRECTORY`` form installs contents of one or more directories to a
given destination. The directory structure is copied verbatim to the given destination. The directory structure is copied verbatim to the
@ -766,13 +733,11 @@ the appropriate cache variables.
The list of ``dirs...`` given to ``DIRECTORY`` may use The list of ``dirs...`` given to ``DIRECTORY`` may use
"generator expressions" too. "generator expressions" too.
Custom Installation Logic .. signature::
^^^^^^^^^^^^^^^^^^^^^^^^^ install(SCRIPT <file> [...])
install(CODE <code> [...])
.. _`install(CODE)`: Invoke CMake scripts or code during installation:
.. _`install(SCRIPT)`:
.. _CODE:
.. _SCRIPT:
.. code-block:: cmake .. code-block:: cmake
@ -805,18 +770,17 @@ will print a message during installation.
name, not the file's contents). See the name, not the file's contents). See the
:manual:`cmake-generator-expressions(7)` manual for available expressions. :manual:`cmake-generator-expressions(7)` manual for available expressions.
Installing Exports .. signature::
^^^^^^^^^^^^^^^^^^ install(EXPORT <export-name> [...])
.. _`install(EXPORT)`: Install a CMake file exporting targets for dependent projects:
.. _EXPORT:
.. code-block:: cmake .. code-block:: cmake
install(EXPORT <export-name> DESTINATION <dir> install(EXPORT <export-name> DESTINATION <dir>
[NAMESPACE <namespace>] [FILE <name>.cmake] [NAMESPACE <namespace>] [FILE <name>.cmake]
[PERMISSIONS permissions...] [PERMISSIONS <permission>...]
[CONFIGURATIONS [Debug|Release|...] [CONFIGURATIONS <config>...]
[CXX_MODULES_DIRECTORY <directory>] [CXX_MODULES_DIRECTORY <directory>]
[EXPORT_LINK_INTERFACE_LIBRARIES] [EXPORT_LINK_INTERFACE_LIBRARIES]
[COMPONENT <component>] [COMPONENT <component>]
@ -826,7 +790,7 @@ Installing Exports
The ``EXPORT`` form generates and installs a CMake file containing code to The ``EXPORT`` form generates and installs a CMake file containing code to
import targets from the installation tree into another project. import targets from the installation tree into another project.
Target installations are associated with the export ``<export-name>`` Target installations are associated with the export ``<export-name>``
using the ``EXPORT`` option of the `install(TARGETS)`_ signature using the ``EXPORT`` option of the :command:`install(TARGETS)` signature
documented above. The ``NAMESPACE`` option will prepend ``<namespace>`` to documented above. The ``NAMESPACE`` option will prepend ``<namespace>`` to
the target names as they are written to the import file. By default the target names as they are written to the import file. By default
the generated file will be called ``<export-name>.cmake`` but the ``FILE`` the generated file will be called ``<export-name>.cmake`` but the ``FILE``
@ -876,10 +840,7 @@ library is always installed if the headers and CMake export file are present.
and defines required to use the libraries. and defines required to use the libraries.
``CXX_MODULES_DIRECTORY`` ``CXX_MODULES_DIRECTORY``
.. versionadded:: 3.28
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Specify a subdirectory to store C++ module information for targets in the Specify a subdirectory to store C++ module information for targets in the
export set. This directory will be populated with files which add the export set. This directory will be populated with files which add the
@ -913,43 +874,42 @@ executable from the installation tree using the imported target name
:command:`install_files`, and :command:`install_programs` commands :command:`install_files`, and :command:`install_programs` commands
is not defined. is not defined.
Installing Runtime Dependencies .. signature::
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ install(RUNTIME_DEPENDENCY_SET <set-name> [...])
.. _`install(RUNTIME_DEPENDENCY_SET)`:
.. _RUNTIME_DEPENDENCY_SET:
.. versionadded:: 3.21 .. versionadded:: 3.21
Installs a runtime dependency set:
.. code-block:: cmake .. code-block:: cmake
install(RUNTIME_DEPENDENCY_SET <set-name> install(RUNTIME_DEPENDENCY_SET <set-name>
[[LIBRARY|RUNTIME|FRAMEWORK] [[LIBRARY|RUNTIME|FRAMEWORK]
[DESTINATION <dir>] [DESTINATION <dir>]
[PERMISSIONS permissions...] [PERMISSIONS <permission>...]
[CONFIGURATIONS [Debug|Release|...]] [CONFIGURATIONS <config>...]
[COMPONENT <component>] [COMPONENT <component>]
[NAMELINK_COMPONENT <component>] [NAMELINK_COMPONENT <component>]
[OPTIONAL] [EXCLUDE_FROM_ALL] [OPTIONAL] [EXCLUDE_FROM_ALL]
] [...] ] [...]
[PRE_INCLUDE_REGEXES regexes...] [PRE_INCLUDE_REGEXES <regex>...]
[PRE_EXCLUDE_REGEXES regexes...] [PRE_EXCLUDE_REGEXES <regex>...]
[POST_INCLUDE_REGEXES regexes...] [POST_INCLUDE_REGEXES <regex>...]
[POST_EXCLUDE_REGEXES regexes...] [POST_EXCLUDE_REGEXES <regex>...]
[POST_INCLUDE_FILES files...] [POST_INCLUDE_FILES <file>...]
[POST_EXCLUDE_FILES files...] [POST_EXCLUDE_FILES <file>...]
[DIRECTORIES directories...] [DIRECTORIES <dir>...]
) )
Installs a runtime dependency set previously created by one or more Installs a runtime dependency set previously created by one or more
`install(TARGETS)`_ or `install(IMPORTED_RUNTIME_ARTIFACTS)`_ commands. The :command:`install(TARGETS)` or :command:`install(IMPORTED_RUNTIME_ARTIFACTS)`
dependencies of targets belonging to a runtime dependency set are installed in commands. The dependencies of targets belonging to a runtime dependency set
the ``RUNTIME`` destination and component on DLL platforms, and in the are installed in the ``RUNTIME`` destination and component on DLL platforms,
``LIBRARY`` destination and component on non-DLL platforms. macOS frameworks and in the ``LIBRARY`` destination and component on non-DLL platforms.
are installed in the ``FRAMEWORK`` destination and component. macOS frameworks are installed in the ``FRAMEWORK`` destination and component.
Targets built within the build tree will never be installed as runtime Targets built within the build tree will never be installed as runtime
dependencies, nor will their own dependencies, unless the targets themselves dependencies, nor will their own dependencies, unless the targets themselves
are installed with `install(TARGETS)`_. are installed with :command:`install(TARGETS)`.
The generated install script calls :command:`file(GET_RUNTIME_DEPENDENCIES)` The generated install script calls :command:`file(GET_RUNTIME_DEPENDENCIES)`
on the build-tree files to calculate the runtime dependencies. The build-tree on the build-tree files to calculate the runtime dependencies. The build-tree
@ -969,13 +929,105 @@ arguments to :command:`file(GET_RUNTIME_DEPENDENCIES)` (for those that provide
a non-empty list of directories, regular expressions or files). They all a non-empty list of directories, regular expressions or files). They all
support :manual:`generator expressions <cmake-generator-expressions(7)>`. support :manual:`generator expressions <cmake-generator-expressions(7)>`.
* ``DIRECTORIES <directories>`` * ``DIRECTORIES <dir>...``
* ``PRE_INCLUDE_REGEXES <regexes>`` * ``PRE_INCLUDE_REGEXES <regex>...``
* ``PRE_EXCLUDE_REGEXES <regexes>`` * ``PRE_EXCLUDE_REGEXES <regex>...``
* ``POST_INCLUDE_REGEXES <regexes>`` * ``POST_INCLUDE_REGEXES <regex>...``
* ``POST_EXCLUDE_REGEXES <regexes>`` * ``POST_EXCLUDE_REGEXES <regex>...``
* ``POST_INCLUDE_FILES <files>`` * ``POST_INCLUDE_FILES <file>...``
* ``POST_EXCLUDE_FILES <files>`` * ``POST_EXCLUDE_FILES <file>...``
Examples
^^^^^^^^
Example: Install Targets with Per-Artifact Components
"""""""""""""""""""""""""""""""""""""""""""""""""""""
Consider a project that defines targets with different artifact kinds:
.. code-block:: cmake
add_executable(myExe myExe.c)
add_library(myStaticLib STATIC myStaticLib.c)
target_sources(myStaticLib PUBLIC FILE_SET HEADERS FILES myStaticLib.h)
add_library(mySharedLib SHARED mySharedLib.c)
target_sources(mySharedLib PUBLIC FILE_SET HEADERS FILES mySharedLib.h)
set_property(TARGET mySharedLib PROPERTY SOVERSION 1)
We may call :command:`install(TARGETS)` with `\<artifact-kind\>`_ arguments
to specify different options for each kind of artifact:
.. code-block:: cmake
install(TARGETS
myExe
mySharedLib
myStaticLib
RUNTIME # Following options apply to runtime artifacts.
COMPONENT Runtime
LIBRARY # Following options apply to library artifacts.
COMPONENT Runtime
NAMELINK_COMPONENT Development
ARCHIVE # Following options apply to archive artifacts.
COMPONENT Development
DESTINATION lib/static
FILE_SET HEADERS # Following options apply to file set HEADERS.
COMPONENT Development
)
This will:
* Install ``myExe`` to ``<prefix>/bin``, the default RUNTIME artifact
destination, as part of the ``Runtime`` component.
* On non-DLL platforms:
* Install ``libmySharedLib.so.1`` to ``<prefix>/lib``, the default
LIBRARY artifact destination, as part of the ``Runtime`` component.
* Install the ``libmySharedLib.so`` "namelink" (symbolic link) to
``<prefix>/lib``, the default LIBRARY artifact destination, as part
of the ``Development`` component.
* On DLL platforms:
* Install ``mySharedLib.dll`` to ``<prefix>/bin``, the default RUNTIME
artifact destination, as part of the ``Runtime`` component.
* Install ``mySharedLib.lib`` to ``<prefix>/lib/static``, the specified
ARCHIVE artifact destination, as part of the ``Development`` component.
* Install ``myStaticLib`` to ``<prefix>/lib/static``, the specified
ARCHIVE artifact destination, as part of the ``Development`` component.
* Install ``mySharedLib.h`` and ``myStaticLib.h`` to ``<prefix>/include``,
the default destination for a file set of type HEADERS, as part of the
``Development`` component.
Example: Install Targets to Per-Config Destinations
"""""""""""""""""""""""""""""""""""""""""""""""""""
Each :command:`install(TARGETS)` call installs a given target
:ref:`output artifact <Output Artifacts>` to at most one ``DESTINATION``,
but the install rule itself may be filtered by the ``CONFIGURATIONS`` option.
In order to install to a different destination for each configuration, one
call per configuration is needed. For example, the code:
.. code-block:: cmake
install(TARGETS myExe
CONFIGURATIONS Debug
RUNTIME
DESTINATION Debug/bin
)
install(TARGETS myExe
CONFIGURATIONS Release
RUNTIME
DESTINATION Release/bin
)
will install ``myExe`` to ``<prefix>/Debug/bin`` in the Debug configuration,
and to ``<prefix>/Release/bin`` in the Release configuration.
Generated Installation Script Generated Installation Script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

@ -27,11 +27,12 @@ Set Normal Variable
If the ``PARENT_SCOPE`` option is given the variable will be set in If the ``PARENT_SCOPE`` option is given the variable will be set in
the scope above the current scope. Each new directory or :command:`function` the scope above the current scope. Each new directory or :command:`function`
command creates a new scope. A scope can also be created with the command creates a new scope. A scope can also be created with the
:command:`block` command. This command will set the value of a variable into :command:`block` command. ``set(PARENT_SCOPE)`` will set the value
the parent directory, calling function or encompassing scope (whichever is of a variable into the parent directory, calling function, or
applicable to the case at hand). The previous state of the variable's value encompassing scope (whichever is applicable to the case at hand).
stays the same in the current scope (e.g., if it was undefined before, it is The previous state of the variable's value stays the same in the
still undefined and if it had a value, it is still that value). current scope (e.g., if it was undefined before, it is still undefined
and if it had a value, it is still that value).
The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands
can be used as an alternate method to the :command:`set(PARENT_SCOPE)` can be used as an alternate method to the :command:`set(PARENT_SCOPE)`

@ -12,7 +12,8 @@ Set a named property in a given scope.
[DIRECTORY <dirs> ...] [DIRECTORY <dirs> ...]
[TARGET_DIRECTORY <targets> ...] | [TARGET_DIRECTORY <targets> ...] |
INSTALL [<file1> ...] | INSTALL [<file1> ...] |
TEST [<test1> ...] | TEST [<test1> ...]
[DIRECTORY <dir>] |
CACHE [<entry1> ...] > CACHE [<entry1> ...] >
[APPEND] [APPEND_STRING] [APPEND] [APPEND_STRING]
PROPERTY <name> [<value1> ...]) PROPERTY <name> [<value1> ...])
@ -91,6 +92,17 @@ It must be one of the following:
:manual:`generator expressions <cmake-generator-expressions(7)>` :manual:`generator expressions <cmake-generator-expressions(7)>`
for tests created by the :command:`add_test(NAME)` signature. for tests created by the :command:`add_test(NAME)` signature.
.. versionadded:: 3.28
Visibility can be set in other directory scopes using the following sub-option:
``DIRECTORY <dir>``
The test property will be set in the ``<dir>`` directory's scope. CMake must
already know about this directory, either by having added it through a call
to :command:`add_subdirectory` or it being the top level source directory.
Relative paths are treated as relative to the current source directory.
``<dir>`` may reference a binary directory.
``CACHE`` ``CACHE``
Scope must name zero or more existing cache entries. Scope must name zero or more existing cache entries.

@ -14,10 +14,20 @@ Test property values may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>` :manual:`generator expressions <cmake-generator-expressions(7)>`
for tests created by the :command:`add_test(NAME)` signature. for tests created by the :command:`add_test(NAME)` signature.
.. versionadded:: 3.28
Visibility can be set in other directory scopes using the following option:
``DIRECTORY <dir>``
The test properties will be set in the ``<dir>`` directory's scope.
CMake must already know about this directory, either by having added it
through a call to :command:`add_subdirectory` or it being the top level
source directory. Relative paths are treated as relative to the current
source directory. ``<dir>`` may reference a binary directory.
See Also See Also
^^^^^^^^ ^^^^^^^^
* :command:`add_test` * :command:`add_test`
* :command:`define_property` * :command:`define_property`
* the more general :command:`set_property` command * the more general :command:`set_property` command
* :ref:`Target Properties` for the list of properties known to CMake * :ref:`Test Properties` for the list of properties known to CMake

@ -66,6 +66,12 @@ Each ``<item>`` may be:
:ref:`usage requirement <Target Usage Requirements>`. This has the same :ref:`usage requirement <Target Usage Requirements>`. This has the same
effect as passing the framework directory as an include directory. effect as passing the framework directory as an include directory.
.. versionadded:: 3.28
The library file may point to a ``.xcframework`` folder on macOS. If it
does, the target will get the selected library's ``Headers`` directory as
a usage requirement.
.. versionadded:: 3.8 .. versionadded:: 3.8
On :ref:`Visual Studio Generators` for VS 2010 and above, library files On :ref:`Visual Studio Generators` for VS 2010 and above, library files
ending in ``.targets`` will be treated as MSBuild targets files and ending in ``.targets`` will be treated as MSBuild targets files and

@ -33,7 +33,7 @@ property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
Repeated calls for the same ``<target>`` will append items in the order called. Repeated calls for the same ``<target>`` will append items in the order called.
Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets
that will be :ref:`exported <install(EXPORT)>`, or they should at least use that will be :command:`exported <install(EXPORT)>`, or they should at least use
the :genex:`$<BUILD_INTERFACE:...>` generator expression to prevent precompile the :genex:`$<BUILD_INTERFACE:...>` generator expression to prevent precompile
headers from appearing in an installed exported target. Consumers of a target headers from appearing in an installed exported target. Consumers of a target
should typically be in control of what precompile headers they use, not have should typically be in control of what precompile headers they use, not have
@ -94,7 +94,7 @@ Reusing Precompile Headers
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
The command also supports a second signature which can be used to specify that The command also supports a second signature which can be used to specify that
one target re-uses a precompiled header file artifact from another target one target reuses a precompiled header file artifact from another target
instead of generating its own: instead of generating its own:
.. code-block:: cmake .. code-block:: cmake

@ -60,6 +60,8 @@ expressions to ensure the sources are correctly assigned to the target.
See the :manual:`cmake-buildsystem(7)` manual for more on defining See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties. buildsystem properties.
.. _`File Sets`:
File Sets File Sets
^^^^^^^^^ ^^^^^^^^^
@ -82,10 +84,7 @@ files within those directories. The acceptable types include:
Sources intended to be used via a language's ``#include`` mechanism. Sources intended to be used via a language's ``#include`` mechanism.
``CXX_MODULES`` ``CXX_MODULES``
.. versionadded:: 3.28
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Sources which contain C++ interface module or partition units (i.e., those Sources which contain C++ interface module or partition units (i.e., those
using the ``export`` keyword). This file set type may not have an using the ``export`` keyword). This file set type may not have an

@ -65,6 +65,7 @@ Try Compiling Source Files
.. code-block:: cmake .. code-block:: cmake
try_compile(<compileResultVar> try_compile(<compileResultVar>
[SOURCES_TYPE <type>]
<SOURCES <srcfile...> | <SOURCES <srcfile...> |
SOURCE_FROM_CONTENT <name> <content> | SOURCE_FROM_CONTENT <name> <content> |
SOURCE_FROM_VAR <name> <var> | SOURCE_FROM_VAR <name> <var> |
@ -143,7 +144,12 @@ single output directory, such that you can only debug one such ``try_compile``
call at a time. Use of the newer signature is recommended to simplify call at a time. Use of the newer signature is recommended to simplify
debugging of multiple ``try_compile`` operations. debugging of multiple ``try_compile`` operations.
The options are: .. _`try_compile Options`:
Options
^^^^^^^
The options for the above signatures are:
``CMAKE_FLAGS <flags>...`` ``CMAKE_FLAGS <flags>...``
Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed
@ -244,6 +250,24 @@ The options are:
``SOURCE_FROM_VAR`` may be specified multiple times. ``SOURCE_FROM_VAR`` may be specified multiple times.
``SOURCES_TYPE <type>``
.. versionadded:: 3.28
Sources may be classified using the ``SOURCES_TYPE`` argument. Once
specified, all subsequent sources specified will be treated as that type
until another ``SOURCES_TYPE`` is given. Available types are:
``NORMAL``
Sources are not added to any ``FILE_SET`` in the generated project.
``CXX_MODULE``
.. versionadded:: 3.28
Sources are added to a ``FILE_SET`` of type ``CXX_MODULES`` in the
generated project.
The default type of sources is ``NORMAL``.
``<LANG>_STANDARD <std>`` ``<LANG>_STANDARD <std>``
.. versionadded:: 3.8 .. versionadded:: 3.8

@ -13,6 +13,7 @@ Try Compiling and Running Source Files
.. code-block:: cmake .. code-block:: cmake
try_run(<runResultVar> <compileResultVar> try_run(<runResultVar> <compileResultVar>
[SOURCES_TYPE <type>]
<SOURCES <srcfile...> | <SOURCES <srcfile...> |
SOURCE_FROM_CONTENT <name> <content> | SOURCE_FROM_CONTENT <name> <content> |
SOURCE_FROM_VAR <name> <var> | SOURCE_FROM_VAR <name> <var> |
@ -77,6 +78,11 @@ The signature above is recommended for clarity.
[ARGS <args>...] [ARGS <args>...]
) )
.. _`try_run Options`:
Options
^^^^^^^
The options specific to ``try_run`` are: The options specific to ``try_run`` are:
``COMPILE_OUTPUT_VARIABLE <var>`` ``COMPILE_OUTPUT_VARIABLE <var>``

@ -19,9 +19,9 @@ be used on FreeBSD, DragonflyBSD, NetBSD, OpenBSD, but also on Linux or OSX,
depending on the installed package-management tools -- using :module:`CPack`. depending on the installed package-management tools -- using :module:`CPack`.
The CPack FreeBSD generator is a :module:`CPack` generator and uses the The CPack FreeBSD generator is a :module:`CPack` generator and uses the
:variable:`!CPACK_XXX` variables used by :module:`CPack`. It tries to re-use packaging :variable:`!CPACK_XXX` variables used by :module:`CPack`. It tries to reuse packaging
information that may already be specified for Debian packages for the information that may already be specified for Debian packages for the
:cpack_gen:`CPack DEB Generator`. It also tries to re-use RPM packaging :cpack_gen:`CPack DEB Generator`. It also tries to reuse RPM packaging
information when Debian does not specify. information when Debian does not specify.
The CPack FreeBSD generator should work on any host with libpkg installed. The The CPack FreeBSD generator should work on any host with libpkg installed. The

@ -431,6 +431,7 @@ The section header underline character hierarchy is
* ``-``: Subsection or `CMake Domain`_ object document title * ``-``: Subsection or `CMake Domain`_ object document title
* ``^``: Subsubsection or `CMake Domain`_ object document section * ``^``: Subsubsection or `CMake Domain`_ object document section
* ``"``: Paragraph or `CMake Domain`_ object document subsection * ``"``: Paragraph or `CMake Domain`_ object document subsection
* ``~``: `CMake Domain`_ object document subsubsection
Style: Whitespace Style: Whitespace
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^

@ -13,127 +13,3 @@ specific values will change over time to reinforce their experimental nature.
When used, a warning will be generated to indicate that an experimental When used, a warning will be generated to indicate that an experimental
feature is in use and that the affected behavior in the project is not part of feature is in use and that the affected behavior in the project is not part of
CMake's stability guarantees. CMake's stability guarantees.
C++20 Module APIs
=================
Variable: ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Value: ``aa1f7df0-828a-4fcd-9afc-2dc80491aca7``
In order to support C++20 modules, there are a number of behaviors that have
CMake APIs to provide the required features to build and export them from a
project.
Limitations
-----------
There are a number of known limitations of the current C++20 module support in
CMake. This does not document known limitations or bugs in compilers as these
can change over time.
For all generators:
- Only in-project modules may be used. While there is some support for
exporting module information, there is no mechanism for using it at the
moment.
For the Ninja Generators:
- ``ninja`` 1.10 or newer is required.
For the Visual Studio Generators:
- Only Visual Studio 2022 and toolchains newer than 19.34 (Visual Studio
17.4).
- No support for exporting or installing BMI or module information.
- No diagnosis of using modules provided by ``PRIVATE`` sources from
``PUBLIC`` module sources.
C++20 Module Dependencies
=========================
The Ninja generator has experimental infrastructure supporting C++20 module
dependency scanning. This is similar to the Fortran modules support, but
relies on external tools to scan C++20 translation units for module
dependencies. The approach is described by Kitware's `D1483r1`_ paper.
In order to activate CMake's experimental support for C++20 module
dependencies, set the following variables:
``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Set this to the UUID documented above.
Some compilers already have support for module dependency scanning:
* MSVC 19.34 and newer (provided with Visual Studio 17.4 and newer)
* LLVM/Clang 16.0 and newer
For those, only the above variables need to be set by project code.
For compilers with in-development support, additional variables must
be set as follows.
``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE``
Set this to tell CMake how to invoke the C++20 module dependency
scanning tool.
``CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FORMAT``
Set this for compilers that generate module maps. See below.
``CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FLAG``
Set this for compilers that generate module maps. See below.
For example, add code like the following to a test project:
.. code-block:: cmake
string(CONCAT CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE
"<CMAKE_CXX_COMPILER> <DEFINES> <INCLUDES> <FLAGS> <SOURCE>"
" -MT <DYNDEP_FILE> -MD -MF <DEP_FILE>"
" ${flags_to_scan_deps} -fdep-file=<DYNDEP_FILE> -fdep-output=<OBJECT>"
)
The tool specified by ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` is
expected to process the translation unit, write preprocessor dependencies
to the file specified by the ``<DEP_FILE>`` placeholder, and write module
dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The
``CMAKE_EXPERIMENTAL_CXX_SCANDEP_DEPFILE_FORMAT`` file may be set to ``msvc``
for scandep rules which use ``msvc``-style dependency reporting.
The module dependencies should be written in the format described
by the `P1689r5`_ paper.
Compiler writers may try out their scanning functionality using
the `cxx-modules-sandbox`_ test project, modified to set variables
as above for their compiler.
For compilers that generate module maps, tell CMake as follows:
.. code-block:: cmake
set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FORMAT "gcc")
set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FLAG
"${compiler_flags_for_module_map} -fmodule-mapper=<MODULE_MAP_FILE>")
Currently, the only supported formats are, ``clang``, ``gcc``, and ``msvc``.
The ``gcc`` format is described in the GCC documentation, but the relevant
section for the purposes of CMake is:
A mapping file consisting of space-separated module-name, filename
pairs, one per line. Only the mappings for the direct imports and any
module export name need be provided. If other mappings are provided,
they override those stored in any imported CMI files. A repository
root may be specified in the mapping file by using ``$root`` as the
module name in the first active line.
-- GCC module mapper documentation
The ``msvc`` format is a response file containing flags required to compile
any module interfaces properly as well as find any required files to satisfy
``import`` statements as required for Microsoft's Visual Studio toolchains.
Similarly, the ``clang`` format is a response file containing flags using
Clang's module flags.
.. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html
.. _`P1689r5`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html
.. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox

@ -338,7 +338,7 @@ policies added for that version. Commit with a message such as::
export: Increase maximum policy version in exported files to $prev export: Increase maximum policy version in exported files to $prev
The files generatd by `install(EXPORT)` and `export()` commands The files generated by `install(EXPORT)` and `export()` commands
are known to work with policies as of CMake $prev, so enable them are known to work with policies as of CMake $prev, so enable them
in sufficiently new CMake versions. in sufficiently new CMake versions.

@ -0,0 +1,11 @@
CMAKE_CROSSCOMPILING_EMULATOR
-----------------------------
.. versionadded:: 3.28
.. include:: ENV_VAR.txt
The default value for :variable:`CMAKE_CROSSCOMPILING_EMULATOR` when there
is no explicit configuration given on the first run while creating a new
build tree. On later runs in an existing build tree the value persists in
the cache as :variable:`CMAKE_CROSSCOMPILING_EMULATOR`.

@ -8,8 +8,10 @@ CUDAHOSTCXX
Preferred executable for compiling host code when compiling ``CUDA`` Preferred executable for compiling host code when compiling ``CUDA``
language files. Will only be used by CMake on the first configuration to language files. Will only be used by CMake on the first configuration to
determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is
stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. This environment stored in the cache as
variable is preferred over :variable:`CMAKE_CUDA_HOST_COMPILER`. :variable:`CMAKE_CUDA_HOST_COMPILER <CMAKE_<LANG>_HOST_COMPILER>`.
This environment variable is preferred over
:variable:`CMAKE_CUDA_HOST_COMPILER <CMAKE_<LANG>_HOST_COMPILER>`.
This environment variable is primarily meant for use with projects that This environment variable is primarily meant for use with projects that
enable ``CUDA`` as a first-class language. enable ``CUDA`` as a first-class language.

@ -0,0 +1,19 @@
HIPHOSTCXX
-----------
.. versionadded:: 3.28
.. include:: ENV_VAR.txt
Preferred executable for compiling host code when compiling ``HIP``
language files with the NVIDIA CUDA Compiler. Will only be used by CMake
on the first configuration to determine ``HIP`` host compiler, after which
the value for ``HIPHOSTCXX`` is stored in the cache as
:variable:`CMAKE_HIP_HOST_COMPILER <CMAKE_<LANG>_HOST_COMPILER>`.
This environment variable is primarily meant for use with projects that
enable ``HIP`` as a first-class language.
.. note::
Ignored when using :ref:`Visual Studio Generators`.

@ -3,6 +3,6 @@ Visual Studio 10 2010
Removed. This once generated Visual Studio 10 2010 project files, but Removed. This once generated Visual Studio 10 2010 project files, but
the generator has been removed since CMake 3.25. It is still possible the generator has been removed since CMake 3.25. It is still possible
to build with VS 10 2010 tools using the :generator:`Visual Studio 12 2013` to build with VS 10 2010 tools using the :generator:`Visual Studio 14 2015`
(or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to (or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to
``v100``, or by using the :generator:`NMake Makefiles` generator. ``v100``, or by using the :generator:`NMake Makefiles` generator.

@ -1,57 +1,8 @@
Visual Studio 11 2012 Visual Studio 11 2012
--------------------- ---------------------
Deprecated. Generates Visual Studio 11 (VS 2012) project files. Removed. This once generated Visual Studio 11 2012 project files, but
the generator has been removed since CMake 3.28. It is still possible
.. note:: to build with VS 11 2012 tools using the :generator:`Visual Studio 14 2015`
This generator is deprecated and will be removed in a future version (or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v110``,
of CMake. It will still be possible to build with VS 11 2012 tools or by using the :generator:`NMake Makefiles` generator.
using the :generator:`Visual Studio 12 2013` (or above) generator
with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v110``, or by
using the :generator:`NMake Makefiles` generator.
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name "Visual Studio 11" without the year component.
Project Types
^^^^^^^^^^^^^
Only Visual C++ and C# projects may be generated (and Fortran with
Intel compiler integration). Other types of projects (JavaScript,
Database, Website, etc.) are not supported.
Platform Selection
^^^^^^^^^^^^^^^^^^
The default target platform name (architecture) is ``Win32``.
.. versionadded:: 3.1
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :option:`cmake -A` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 11 2012" -A Win32``
* ``cmake -G "Visual Studio 11 2012" -A x64``
* ``cmake -G "Visual Studio 11 2012" -A ARM``
* ``cmake -G "Visual Studio 11 2012" -A <WinCE-SDK>``
(Specify a target platform matching a Windows CE SDK name.)
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of the generator name.
This is supported only for:
``Visual Studio 11 2012 Win64``
Specify target platform ``x64``.
``Visual Studio 11 2012 ARM``
Specify target platform ``ARM``.
``Visual Studio 11 2012 <WinCE-SDK>``
Specify target platform matching a Windows CE SDK name.
Toolset Selection
^^^^^^^^^^^^^^^^^
The ``v110`` toolset that comes with Visual Studio 11 2012 is selected by
default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :option:`cmake -T` option, to specify another toolset.

@ -1,7 +1,14 @@
Visual Studio 12 2013 Visual Studio 12 2013
--------------------- ---------------------
Generates Visual Studio 12 (VS 2013) project files. Deprecated. Generates Visual Studio 12 (VS 2013) project files.
.. note::
This generator is deprecated and will be removed in a future version
of CMake. It will still be possible to build with VS 12 2013 tools
using the :generator:`Visual Studio 14 2015` (or above) generator
with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v120``, or by
using the :generator:`NMake Makefiles` generator.
For compatibility with CMake versions prior to 3.0, one may specify this For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name "Visual Studio 12" without the year component. generator using the name "Visual Studio 12" without the year component.

@ -6,7 +6,7 @@ Deprecated. Generates Visual Studio 9 2008 project files.
.. note:: .. note::
This generator is deprecated and will be removed in a future version This generator is deprecated and will be removed in a future version
of CMake. It will still be possible to build with VS 9 2008 tools of CMake. It will still be possible to build with VS 9 2008 tools
using the :generator:`Visual Studio 12 2013` generator (or above, using the :generator:`Visual Studio 14 2015` generator (or above,
and with VS 10 2010 also installed) with and with VS 10 2010 also installed) with
:variable:`CMAKE_GENERATOR_TOOLSET` set to ``v90``, :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v90``,
or by using the :generator:`NMake Makefiles` generator. or by using the :generator:`NMake Makefiles` generator.

@ -102,7 +102,14 @@ Then call that build system to actually compile/link the project:
cmake --build . cmake --build .
Finally, try to use the newly built ``Tutorial`` with these commands: For multi-config generators (e.g. Visual Studio), first navigate to the
appropriate subdirectory, for example:
.. code-block:: console
cd Debug
Finally, try to use the newly built ``Tutorial``:
.. code-block:: console .. code-block:: console
@ -110,6 +117,11 @@ Finally, try to use the newly built ``Tutorial`` with these commands:
Tutorial 10 Tutorial 10
Tutorial Tutorial
**Note:** Depending on the shell, the correct syntax may be ``Tutorial``,
``./Tutorial`` or ``.\Tutorial``. For simplicity, the exercises will use
``Tutorial`` throughout.
Solution Solution
-------- --------

@ -149,8 +149,8 @@ interface library.
Lastly, we only want these warning flags to be used during builds. Consumers Lastly, we only want these warning flags to be used during builds. Consumers
of our installed project should not inherit our warning flags. To specify of our installed project should not inherit our warning flags. To specify
this, we wrap our flags in a generator expression using the ``BUILD_INTERFACE`` this, we wrap our flags from TODO 3 in a generator expression using the
condition. The resulting full code looks like the following: ``BUILD_INTERFACE`` condition. The resulting full code looks like the following:
.. raw:: html .. raw:: html

@ -127,7 +127,7 @@ Remove this line:
</details> </details>
And the lines: And remove ``EXTRA_INCLUDES`` from ``target_include_directories``:
.. raw:: html .. raw:: html
@ -143,23 +143,6 @@ And the lines:
</details> </details>
The remaining code looks like:
.. raw:: html
<details><summary>Click to show/hide the resulting code</summary>
.. literalinclude:: Step4/CMakeLists.txt
:caption: Remaining code after removing EXTRA_INCLUDES
:name: CMakeLists.txt-after-removing-EXTRA_INCLUDES
:language: cmake
:start-after: add_subdirectory(MathFunctions)
.. raw:: html
</details>
Notice that with this technique, the only thing our executable target does to Notice that with this technique, the only thing our executable target does to
use our library is call :command:`target_link_libraries` with the name use our library is call :command:`target_link_libraries` with the name
of the library target. In larger projects, the classic method of specifying of the library target. In larger projects, the classic method of specifying
@ -262,10 +245,9 @@ then use :command:`target_compile_features` to add the compiler feature
</details> </details>
Finally, with our interface library set up, we need to link our Finally, with our interface library set up, we need to link our
executable ``Target``, our ``MathFunctions`` library, and our ``SqrtLibrary`` executable ``Tutorial``, our ``SqrtLibrary`` library and our ``MathFunctions``
library to our new library to our new ``tutorial_compiler_flags`` library. Respectively, the code
``tutorial_compiler_flags`` library. Respectively, the code will look like will look like this:
this:
.. raw:: html .. raw:: html
@ -292,7 +274,7 @@ this:
:caption: TODO 6: MathFunctions/CMakeLists.txt :caption: TODO 6: MathFunctions/CMakeLists.txt
:name: MathFunctions-CMakeLists.txt-target_link_libraries-step4 :name: MathFunctions-CMakeLists.txt-target_link_libraries-step4
:language: cmake :language: cmake
:start-after: # link our compiler flags interface library :start-after: # link SqrtLibrary to tutorial_compiler_flags
:end-before: target_link_libraries(MathFunctions :end-before: target_link_libraries(MathFunctions
.. raw:: html .. raw:: html
@ -309,8 +291,7 @@ and this:
:caption: TODO 7: MathFunctions/CMakeLists.txt :caption: TODO 7: MathFunctions/CMakeLists.txt
:name: MathFunctions-SqrtLibrary-target_link_libraries-step4 :name: MathFunctions-SqrtLibrary-target_link_libraries-step4
:language: cmake :language: cmake
:start-after: target_link_libraries(SqrtLibrary :start-after: # link MathFunctions to tutorial_compiler_flags
:end-before: endif()
.. raw:: html .. raw:: html

@ -96,7 +96,7 @@ a library target called ``MathFunctions`` with :command:`add_library`. The
source files for the library are passed as an argument to source files for the library are passed as an argument to
:command:`add_library`. This looks like the following line: :command:`add_library`. This looks like the following line:
.. raw:: html/ .. raw:: html
<details><summary>TODO 1: Click to show/hide answer</summary> <details><summary>TODO 1: Click to show/hide answer</summary>
@ -184,7 +184,7 @@ Now let's use our library. In ``tutorial.cxx``, include ``MathFunctions.h``:
</details> </details>
Lastly, replace ``sqrt`` with our library function ``mathfunctions::mysqrt``. Lastly, replace ``sqrt`` with the wrapper function ``mathfunctions::sqrt``.
.. raw:: html .. raw:: html

@ -33,10 +33,13 @@ if(USE_MYMATH)
POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
) )
# link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary) target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif() endif()
# link MathFunctions to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# define the symbol stating we are using the declspec(dllexport) when # define the symbol stating we are using the declspec(dllexport) when

@ -44,7 +44,18 @@ SqrtLibrary to be ``True`` when building shared libraries.
:caption: MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-POSITION_INDEPENDENT_CODE :name: MathFunctions/CMakeLists.txt-POSITION_INDEPENDENT_CODE
:language: cmake :language: cmake
:lines: 37-42 :start-at: # state that SqrtLibrary need PIC when the default is shared libraries
:end-at: )
Define ``EXPORTING_MYMATH`` stating we are using ``declspec(dllexport)`` when
building on Windows.
.. literalinclude:: Step11/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-dll-export
:language: cmake
:start-at: # define the symbol stating we are using the declspec(dllexport) when
:end-at: target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
**Exercise**: We modified ``MathFunctions.h`` to use dll export defines. **Exercise**: We modified ``MathFunctions.h`` to use dll export defines.
Using CMake documentation can you find a helper module to simplify this? Using CMake documentation can you find a helper module to simplify this?

@ -26,10 +26,13 @@ if(USE_MYMATH)
${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}
) )
# link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary) target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif() endif()
# link MathFunctions to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# install libs # install libs

@ -31,10 +31,13 @@ if(USE_MYMATH)
POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
) )
# link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary) target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif() endif()
# link MathFunctions to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# define the symbol stating we are using the declspec(dllexport) when # define the symbol stating we are using the declspec(dllexport) when

@ -33,10 +33,13 @@ if(USE_MYMATH)
POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
) )
# link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary) target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif() endif()
# link MathFunctions to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# define the symbol stating we are using the declspec(dllexport) when # define the symbol stating we are using the declspec(dllexport) when

@ -16,7 +16,7 @@ if (USE_MYMATH)
# TODO 7: Link SqrtLibrary to tutorial_compiler_flags # TODO 7: Link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC SqrtLibrary) target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif() endif()
# TODO 6: Link MathFunctions to tutorial_compiler_flags # TODO 6: Link MathFunctions to tutorial_compiler_flags

@ -17,10 +17,11 @@ if (USE_MYMATH)
mysqrt.cxx mysqrt.cxx
) )
# link our compiler flags interface library # link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
target_link_libraries(MathFunctions PUBLIC SqrtLibrary)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif() endif()
# link our compiler flags interface library # link MathFunctions to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)

@ -16,12 +16,13 @@ if (USE_MYMATH)
mysqrt.cxx mysqrt.cxx
) )
# link our compiler flags interface library # link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary) target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif() endif()
# link our compiler flags interface library # link MathFunctions to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# TODO 1: Create a variable called installable_libs that is a list of all # TODO 1: Create a variable called installable_libs that is a list of all

@ -16,11 +16,13 @@ if (USE_MYMATH)
mysqrt.cxx mysqrt.cxx
) )
# link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary) target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif() endif()
# link our compiler flags interface library # link MathFunctions to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# install libs # install libs

@ -16,6 +16,7 @@ if (USE_MYMATH)
mysqrt.cxx mysqrt.cxx
) )
# link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
# TODO 1: Include CheckCXXSourceCompiles # TODO 1: Include CheckCXXSourceCompiles
@ -41,7 +42,7 @@ if (USE_MYMATH)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary) target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif() endif()
# link our compiler flags interface library # link MathFunctions to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# install libs # install libs

@ -10,6 +10,7 @@ if (USE_MYMATH)
mysqrt.cxx mysqrt.cxx
) )
# link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
# does this system provide the log and exp functions? # does this system provide the log and exp functions?
@ -45,7 +46,7 @@ target_include_directories(MathFunctions
INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
) )
# link our compiler flags interface library # link MathFunctions to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# install libs # install libs

@ -25,10 +25,13 @@ if (USE_MYMATH)
${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}
) )
# link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary) target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif() endif()
# link MathFunctions to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# install libs # install libs

@ -58,6 +58,7 @@ Reference Manuals
/manual/cmake-commands.7 /manual/cmake-commands.7
/manual/cmake-compile-features.7 /manual/cmake-compile-features.7
/manual/cmake-configure-log.7 /manual/cmake-configure-log.7
/manual/cmake-cxxmodules.7
/manual/cmake-developer.7 /manual/cmake-developer.7
/manual/cmake-env-variables.7 /manual/cmake-env-variables.7
/manual/cmake-file-api.7 /manual/cmake-file-api.7

@ -105,11 +105,15 @@
.. option:: --toolchain <path-to-file> .. option:: --toolchain <path-to-file>
.. versionadded:: 3.21
Specify the cross compiling toolchain file, equivalent to setting Specify the cross compiling toolchain file, equivalent to setting
:variable:`CMAKE_TOOLCHAIN_FILE` variable. :variable:`CMAKE_TOOLCHAIN_FILE` variable.
.. option:: --install-prefix <directory> .. option:: --install-prefix <directory>
.. versionadded:: 3.21
Specify the installation directory, used by the Specify the installation directory, used by the
:variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path. :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path.

@ -11,6 +11,21 @@
Usage describes the basic command line interface and its options. Usage describes the basic command line interface and its options.
.. option:: --help <keyword> [<file>]
Print help for one CMake keyword.
``<keyword>`` can be a property, variable, command, policy, generator
or module.
The relevant manual entry for ``<keyword>`` is
printed in a human-readable text format.
|file|
.. versionchanged:: 3.28
Prior to CMake 3.28, this option supported command names only.
.. option:: --help-full [<file>] .. option:: --help-full [<file>]
Print all help manuals and exit. Print all help manuals and exit.

@ -0,0 +1,74 @@
.. cmake-manual-description: CMake C++ Modules Support Reference
cmake-cxxmodules(7)
*******************
.. versionadded:: 3.28
C++ 20 introduced the concept of "modules" to the language. The design
requires build systems to order compilations among each other to satisfy
``import`` statements reliably. CMake's implementation asks the compiler
to scan source files for module dependencies during the build, collates
scanning results to infer ordering constraints, and tells the build tool
how to dynamically update the build graph.
Scanning Control
================
Whether or not sources get scanned for C++ module usage is dependent on the
following queries. The first query that provides a yes/no answer is used.
- If the source file belongs to a file set of type ``CXX_MODULES``, it will
be scanned.
- If the target does not use at least C++ 20, it will not be scanned.
- If the source file is not the language ``CXX``, it will not be scanned.
- If the :prop_sf:`CXX_SCAN_FOR_MODULES` source file property is set, its
value will be used.
- If the :prop_tgt:`CXX_SCAN_FOR_MODULES` target property is set, its value
will be used. Set the :variable:`CMAKE_CXX_SCAN_FOR_MODULES` variable
to initialize this property on all targets as they are created.
- Otherwise, the source file will be scanned if the compiler and generator
support scanning. See policy :policy:`CMP0155`.
Compiler Support
================
Compilers which CMake natively supports module dependency scanning include:
* MSVC toolset 14.34 and newer (provided with Visual Studio 17.4 and newer)
* LLVM/Clang 16.0 and newer
* GCC 14 (for the in-development branch, after 2023-09-20) and newer
Generator Support
=================
The list of generators which support scanning sources for C++ modules include:
- :generator:`Ninja`
- :generator:`Ninja Multi-Config`
- :generator:`Visual Studio 17 2022`
Limitations
-----------
There are a number of known limitations of the current C++ module support in
CMake. This does not document known limitations or bugs in compilers as these
can change over time.
For all generators:
- Header units are not supported.
- No builtin support for ``import std;`` or other compiler-provided modules.
For the Ninja Generators:
- ``ninja`` 1.11 or newer is required.
For the :ref:`Visual Studio Generators`:
- Only Visual Studio 2022 and MSVC toolsets 14.34 (Visual Studio
17.4) and newer.
- No support for exporting or installing BMI or module information.
- No support for compiling BMIs from ``IMPORTED`` targets with C++ modules.
- No diagnosis of using modules provided by ``PRIVATE`` sources from
``PUBLIC`` module sources.

@ -43,6 +43,7 @@ Environment Variables that Control the Build
/envvar/CMAKE_COLOR_DIAGNOSTICS /envvar/CMAKE_COLOR_DIAGNOSTICS
/envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIGURATION_TYPES
/envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_CONFIG_TYPE
/envvar/CMAKE_CROSSCOMPILING_EMULATOR
/envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_EXPORT_COMPILE_COMMANDS
/envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR
/envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_INSTANCE
@ -83,6 +84,7 @@ Environment Variables for Languages
/envvar/FFLAGS /envvar/FFLAGS
/envvar/HIPCXX /envvar/HIPCXX
/envvar/HIPFLAGS /envvar/HIPFLAGS
/envvar/HIPHOSTCXX
/envvar/ISPC /envvar/ISPC
/envvar/ISPCFLAGS /envvar/ISPCFLAGS
/envvar/OBJC /envvar/OBJC

@ -195,6 +195,12 @@ Two forms of conditional generator expressions are supported:
if ``condition`` is ``0``. Any other value for ``condition`` results in an if ``condition`` is ``0``. Any other value for ``condition`` results in an
error. error.
.. versionadded:: 3.28
This generator expression short-circuits such that generator expressions in
``false_string`` will not evaluate when ``condition`` is ``1``, and generator
expressions in ``true_string`` will not evaluate when condition is ``0``.
Typically, the ``condition`` is itself a generator expression. For instance, Typically, the ``condition`` is itself a generator expression. For instance,
the following expression expands to ``DEBUG_MODE`` when the ``Debug`` the following expression expands to ``DEBUG_MODE`` when the ``Debug``
configuration is used, and the empty string for all other configurations: configuration is used, and the empty string for all other configurations:
@ -252,6 +258,11 @@ The common boolean logic operators are supported:
``condition`` must be ``0`` or ``1``. The result of the expression is ``condition`` must be ``0`` or ``1``. The result of the expression is
``0`` if ``condition`` is ``1``, else ``1``. ``0`` if ``condition`` is ``1``, else ``1``.
.. versionadded:: 3.28
Logical operators short-circuit such that generator expressions in the
arguments list will not be evaluated once a return value can be determined.
.. _`Comparison Expressions`: .. _`Comparison Expressions`:
Primary Comparison Expressions Primary Comparison Expressions

@ -72,7 +72,6 @@ These modules are loaded using the :command:`include` command.
/module/CTestCoverageCollectGCOV /module/CTestCoverageCollectGCOV
/module/CTestScriptMode /module/CTestScriptMode
/module/CTestUseLaunchers /module/CTestUseLaunchers
/module/Dart
/module/DeployQt4 /module/DeployQt4
/module/ExternalData /module/ExternalData
/module/ExternalProject /module/ExternalProject
@ -82,14 +81,12 @@ These modules are loaded using the :command:`include` command.
/module/FindPackageMessage /module/FindPackageMessage
/module/FortranCInterface /module/FortranCInterface
/module/GenerateExportHeader /module/GenerateExportHeader
/module/GetPrerequisites
/module/GNUInstallDirs /module/GNUInstallDirs
/module/GoogleTest /module/GoogleTest
/module/InstallRequiredSystemLibraries /module/InstallRequiredSystemLibraries
/module/ProcessorCount /module/ProcessorCount
/module/SelectLibraryConfigurations /module/SelectLibraryConfigurations
/module/SquishTestScript /module/SquishTestScript
/module/TestBigEndian
/module/TestForANSIForScope /module/TestForANSIForScope
/module/TestForANSIStreamHeaders /module/TestForANSIStreamHeaders
/module/TestForSSTREAM /module/TestForSSTREAM
@ -127,7 +124,6 @@ They are normally called through the :command:`find_package` command.
/module/FindCVS /module/FindCVS
/module/FindCxxTest /module/FindCxxTest
/module/FindCygwin /module/FindCygwin
/module/FindDart
/module/FindDCMTK /module/FindDCMTK
/module/FindDevIL /module/FindDevIL
/module/FindDoxygen /module/FindDoxygen
@ -276,8 +272,11 @@ Deprecated Utility Modules
/module/CMakeExpandImportedTargets /module/CMakeExpandImportedTargets
/module/CMakeForceCompiler /module/CMakeForceCompiler
/module/CMakeParseArguments /module/CMakeParseArguments
/module/Dart
/module/Documentation /module/Documentation
/module/GetPrerequisites
/module/MacroAddFileDependencies /module/MacroAddFileDependencies
/module/TestBigEndian
/module/TestCXXAcceptsFlag /module/TestCXXAcceptsFlag
/module/UseJavaClassFilelist /module/UseJavaClassFilelist
/module/UseJavaSymlinks /module/UseJavaSymlinks
@ -293,6 +292,7 @@ Deprecated Find Modules
:maxdepth: 1 :maxdepth: 1
/module/FindCUDA /module/FindCUDA
/module/FindDart
/module/FindITK /module/FindITK
/module/FindPythonInterp /module/FindPythonInterp
/module/FindPythonLibs /module/FindPythonLibs

@ -51,6 +51,17 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
to determine whether to report an error on use of deprecated macros or to determine whether to report an error on use of deprecated macros or
functions. functions.
Policies Introduced by CMake 3.28
=================================
.. toctree::
:maxdepth: 1
CMP0155: C++ sources in targets with at least C++20 are scanned for imports when supported. </policy/CMP0155>
CMP0154: Generated files are private by default in targets using file sets. </policy/CMP0154>
CMP0153: The exec_program command should not be called. </policy/CMP0153>
CMP0152: file(REAL_PATH) resolves symlinks before collapsing ../ components. </policy/CMP0152>
Policies Introduced by CMake 3.27 Policies Introduced by CMake 3.27
================================= =================================

@ -41,6 +41,15 @@ The files are a JSON document with an object as the root:
The root object recognizes the following fields: The root object recognizes the following fields:
``$schema``
An optional string that provides a URI to the JSON schema that describes the
structure of this JSON document. This field is used for validation and
autocompletion in editors that support JSON schema. It doesn't affect the
behavior of the document itself. If this field is not specified, the JSON
document will still be valid, but tools that use JSON schema for validation
and autocompletion may not function correctly.
This is allowed in preset files specifying version ``8`` or above.
``version`` ``version``
A required integer representing the version of the JSON schema. A required integer representing the version of the JSON schema.
The supported versions are: The supported versions are:
@ -66,6 +75,9 @@ The root object recognizes the following fields:
``7`` ``7``
.. versionadded:: 3.27 .. versionadded:: 3.27
``8``
.. versionadded:: 3.28
``cmakeMinimumRequired`` ``cmakeMinimumRequired``
An optional object representing the minimum version of CMake needed to An optional object representing the minimum version of CMake needed to
build this project. This object consists of the following fields: build this project. This object consists of the following fields:

@ -240,6 +240,11 @@ Properties on Targets
/prop_tgt/IMPORTED /prop_tgt/IMPORTED
/prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME
/prop_tgt/IMPORTED_CONFIGURATIONS /prop_tgt/IMPORTED_CONFIGURATIONS
/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS
/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_FEATURES
/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_OPTIONS
/prop_tgt/IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES
/prop_tgt/IMPORTED_CXX_MODULES_LINK_LIBRARIES
/prop_tgt/IMPORTED_GLOBAL /prop_tgt/IMPORTED_GLOBAL
/prop_tgt/IMPORTED_IMPLIB /prop_tgt/IMPORTED_IMPLIB
/prop_tgt/IMPORTED_IMPLIB_CONFIG /prop_tgt/IMPORTED_IMPLIB_CONFIG
@ -257,7 +262,6 @@ Properties on Targets
/prop_tgt/IMPORTED_LOCATION_CONFIG /prop_tgt/IMPORTED_LOCATION_CONFIG
/prop_tgt/IMPORTED_NO_SONAME /prop_tgt/IMPORTED_NO_SONAME
/prop_tgt/IMPORTED_NO_SONAME_CONFIG /prop_tgt/IMPORTED_NO_SONAME_CONFIG
/prop_tgt/IMPORTED_NO_SYSTEM
/prop_tgt/IMPORTED_OBJECTS /prop_tgt/IMPORTED_OBJECTS
/prop_tgt/IMPORTED_OBJECTS_CONFIG /prop_tgt/IMPORTED_OBJECTS_CONFIG
/prop_tgt/IMPORTED_SONAME /prop_tgt/IMPORTED_SONAME
@ -290,7 +294,6 @@ Properties on Targets
/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
/prop_tgt/INTERPROCEDURAL_OPTIMIZATION /prop_tgt/INTERPROCEDURAL_OPTIMIZATION
/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG
/prop_tgt/IOS_INSTALL_COMBINED
/prop_tgt/ISPC_HEADER_DIRECTORY /prop_tgt/ISPC_HEADER_DIRECTORY
/prop_tgt/ISPC_HEADER_SUFFIX /prop_tgt/ISPC_HEADER_SUFFIX
/prop_tgt/ISPC_INSTRUCTION_SETS /prop_tgt/ISPC_INSTRUCTION_SETS
@ -439,7 +442,6 @@ Properties on Targets
/prop_tgt/VS_USER_PROPS /prop_tgt/VS_USER_PROPS
/prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
/prop_tgt/VS_WINRT_COMPONENT /prop_tgt/VS_WINRT_COMPONENT
/prop_tgt/VS_WINRT_EXTENSIONS
/prop_tgt/VS_WINRT_REFERENCES /prop_tgt/VS_WINRT_REFERENCES
/prop_tgt/WATCOM_RUNTIME_LIBRARY /prop_tgt/WATCOM_RUNTIME_LIBRARY
/prop_tgt/WIN32_EXECUTABLE /prop_tgt/WIN32_EXECUTABLE
@ -503,6 +505,7 @@ Properties on Tests
/prop_test/FIXTURES_CLEANUP /prop_test/FIXTURES_CLEANUP
/prop_test/FIXTURES_REQUIRED /prop_test/FIXTURES_REQUIRED
/prop_test/FIXTURES_SETUP /prop_test/FIXTURES_SETUP
/prop_test/GENERATED_RESOURCE_SPEC_FILE
/prop_test/LABELS /prop_test/LABELS
/prop_test/MEASUREMENT /prop_test/MEASUREMENT
/prop_test/PASS_REGULAR_EXPRESSION /prop_test/PASS_REGULAR_EXPRESSION
@ -634,8 +637,11 @@ Deprecated Properties on Targets
:maxdepth: 1 :maxdepth: 1
/prop_tgt/COMPILE_DEFINITIONS_CONFIG /prop_tgt/COMPILE_DEFINITIONS_CONFIG
/prop_tgt/IMPORTED_NO_SYSTEM
/prop_tgt/IOS_INSTALL_COMBINED
/prop_tgt/POST_INSTALL_SCRIPT /prop_tgt/POST_INSTALL_SCRIPT
/prop_tgt/PRE_INSTALL_SCRIPT /prop_tgt/PRE_INSTALL_SCRIPT
/prop_tgt/VS_WINRT_EXTENSIONS
Deprecated Properties on Source Files Deprecated Properties on Source Files

@ -14,7 +14,7 @@ CMake can find and use Qt 4 and Qt 5 libraries. The Qt 4 libraries are found
by the :module:`FindQt4` find-module shipped with CMake, whereas the by the :module:`FindQt4` find-module shipped with CMake, whereas the
Qt 5 libraries are found using "Config-file Packages" shipped with Qt 5. See Qt 5 libraries are found using "Config-file Packages" shipped with Qt 5. See
:manual:`cmake-packages(7)` for more information about CMake packages, and :manual:`cmake-packages(7)` for more information about CMake packages, and
see `the Qt cmake manual <https://contribute.qt-project.org/doc/qt-5/cmake-manual.html>`_ see `the Qt cmake manual <https://doc.qt.io/qt-5/cmake-manual.html>`_
for your Qt version. for your Qt version.
Qt 4 and Qt 5 may be used together in the same Qt 4 and Qt 5 may be used together in the same

@ -573,12 +573,12 @@ See also target properties:
* :prop_tgt:`ANDROID_SKIP_ANT_STEP` * :prop_tgt:`ANDROID_SKIP_ANT_STEP`
* :prop_tgt:`ANDROID_STL_TYPE` * :prop_tgt:`ANDROID_STL_TYPE`
.. _`Cross Compiling for iOS, tvOS, or watchOS`: .. _`Cross Compiling for iOS, tvOS, visionOS, or watchOS`:
Cross Compiling for iOS, tvOS, or watchOS Cross Compiling for iOS, tvOS, visionOS, or watchOS
----------------------------------------- ---------------------------------------------------
For cross-compiling to iOS, tvOS, or watchOS, the :generator:`Xcode` For cross-compiling to iOS, tvOS, visionOS, or watchOS, the :generator:`Xcode`
generator is recommended. The :generator:`Unix Makefiles` or generator is recommended. The :generator:`Unix Makefiles` or
:generator:`Ninja` generators can also be used, but they require the :generator:`Ninja` generators can also be used, but they require the
project to handle more areas like target CPU selection and code signing. project to handle more areas like target CPU selection and code signing.
@ -591,13 +591,14 @@ a different SDK (e.g. a simulator) can be selected by setting the
necessary (see :ref:`Switching Between Device and Simulator` below). necessary (see :ref:`Switching Between Device and Simulator` below).
A list of available SDKs can be obtained by running ``xcodebuild -showsdks``. A list of available SDKs can be obtained by running ``xcodebuild -showsdks``.
======= ================= ==================== ================ ======== ================= ==================== ================
OS CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK OS CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK
======= ================= ==================== ================ ======== ================= ==================== ================
iOS iOS iphoneos iphonesimulator iOS iOS iphoneos iphonesimulator
tvOS tvOS appletvos appletvsimulator tvOS tvOS appletvos appletvsimulator
visionOS visionOS xros xrsimulator
watchOS watchOS watchos watchsimulator watchOS watchOS watchos watchsimulator
======= ================= ==================== ================ ======== ================= ==================== ================
For example, to create a CMake configuration for iOS, the following For example, to create a CMake configuration for iOS, the following
command is sufficient: command is sufficient:
@ -608,7 +609,7 @@ command is sufficient:
Variable :variable:`CMAKE_OSX_ARCHITECTURES` can be used to set architectures Variable :variable:`CMAKE_OSX_ARCHITECTURES` can be used to set architectures
for both device and simulator. Variable :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` for both device and simulator. Variable :variable:`CMAKE_OSX_DEPLOYMENT_TARGET`
can be used to set an iOS/tvOS/watchOS deployment target. can be used to set an iOS/tvOS/visionOS/watchOS deployment target.
Next configuration will install fat 5 architectures iOS library Next configuration will install fat 5 architectures iOS library
and add the ``-miphoneos-version-min=9.3``/``-mios-simulator-version-min=9.3`` and add the ``-miphoneos-version-min=9.3``/``-mios-simulator-version-min=9.3``

@ -590,6 +590,7 @@ Variables for Languages
/variable/CMAKE_Fortran_MODOUT_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG
/variable/CMAKE_HIP_ARCHITECTURES /variable/CMAKE_HIP_ARCHITECTURES
/variable/CMAKE_HIP_EXTENSIONS /variable/CMAKE_HIP_EXTENSIONS
/variable/CMAKE_HIP_PLATFORM
/variable/CMAKE_HIP_STANDARD /variable/CMAKE_HIP_STANDARD
/variable/CMAKE_HIP_STANDARD_REQUIRED /variable/CMAKE_HIP_STANDARD_REQUIRED
/variable/CMAKE_ISPC_HEADER_DIRECTORY /variable/CMAKE_ISPC_HEADER_DIRECTORY
@ -627,6 +628,7 @@ Variables for Languages
/variable/CMAKE_LANG_FLAGS_RELEASE_INIT /variable/CMAKE_LANG_FLAGS_RELEASE_INIT
/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO
/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT
/variable/CMAKE_LANG_HOST_COMPILER
/variable/CMAKE_LANG_IGNORE_EXTENSIONS /variable/CMAKE_LANG_IGNORE_EXTENSIONS
/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES
/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES

@ -309,6 +309,8 @@ Options
.. option:: --debug-find .. option:: --debug-find
.. versionadded:: 3.17
Put cmake find commands in a debug mode. Put cmake find commands in a debug mode.
Print extra find call information during the cmake run to standard Print extra find call information during the cmake run to standard
@ -318,6 +320,8 @@ Options
.. option:: --debug-find-pkg=<pkg>[,...] .. option:: --debug-find-pkg=<pkg>[,...]
.. versionadded:: 3.23
Put cmake find commands in a debug mode when running under calls Put cmake find commands in a debug mode when running under calls
to :command:`find_package(\<pkg\>) <find_package>`, where ``<pkg>`` to :command:`find_package(\<pkg\>) <find_package>`, where ``<pkg>``
is an entry in the given comma-separated list of case-sensitive package is an entry in the given comma-separated list of case-sensitive package
@ -328,6 +332,8 @@ Options
.. option:: --debug-find-var=<var>[,...] .. option:: --debug-find-var=<var>[,...]
.. versionadded:: 3.23
Put cmake find commands in a debug mode when called with ``<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 as the result variable, where ``<var>`` is an entry in the given
comma-separated list. comma-separated list.
@ -349,6 +355,8 @@ Options
.. option:: --trace-format=<format> .. option:: --trace-format=<format>
.. versionadded:: 3.17
Put cmake in trace mode and sets the trace output format. Put cmake in trace mode and sets the trace output format.
``<format>`` can be one of the following values. ``<format>`` can be one of the following values.
@ -471,12 +479,16 @@ Options
.. option:: --compile-no-warning-as-error .. option:: --compile-no-warning-as-error
.. versionadded:: 3.24
Ignore target property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and variable Ignore target property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and variable
:variable:`CMAKE_COMPILE_WARNING_AS_ERROR`, preventing warnings from being :variable:`CMAKE_COMPILE_WARNING_AS_ERROR`, preventing warnings from being
treated as errors on compile. treated as errors on compile.
.. option:: --profiling-output=<path> .. option:: --profiling-output=<path>
.. versionadded:: 3.18
Used in conjunction with Used in conjunction with
:option:`--profiling-format <cmake --profiling-format>` to output to a :option:`--profiling-format <cmake --profiling-format>` to output to a
given path. given path.
@ -1325,6 +1337,8 @@ autoconf-based projects (via ``share/aclocal/cmake.m4``).
Run a Workflow Preset Run a Workflow Preset
===================== =====================
.. versionadded:: 3.25
.. program:: cmake .. program:: cmake
:manual:`CMake Presets <cmake-presets(7)>` provides a way to execute multiple :manual:`CMake Presets <cmake-presets(7)>` provides a way to execute multiple

@ -1820,6 +1820,25 @@ The following variables are passed to the test process:
uppercase in the ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` environment uppercase in the ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` environment
variable. variable.
.. _`ctest-resource-dynamically-generated-spec-file`:
Dynamically-Generated Resource Specification File
-------------------------------------------------
.. versionadded:: 3.28
A project may optionally specify a single test which will be used to
dynamically generate the resource specification file that CTest will use for
scheduling tests that use resources. The test that generates the file must
have the :prop_test:`GENERATED_RESOURCE_SPEC_FILE` property set, and must have
exactly one fixture in its :prop_test:`FIXTURES_SETUP` property. This fixture
is considered by CTest to have special meaning: it's the fixture that generates
the resource spec file. The fixture may have any name. If such a fixture
exists, all tests that have :prop_test:`RESOURCE_GROUPS` set must have the
fixture in their :prop_test:`FIXTURES_REQUIRED`, and a resource spec file may
not be specified with the ``--resource-spec-file`` argument or the
:variable:`CTEST_RESOURCE_SPEC_FILE` variable.
See Also See Also
======== ========

@ -106,12 +106,35 @@
"include": { "$ref": "#/definitions/include" } "include": { "$ref": "#/definitions/include" }
}, },
"additionalProperties": false "additionalProperties": false
},
{
"properties": {
"$schema": { "$ref": "#/definitions/$schema" },
"version": {
"const": 8,
"description": "A required integer representing the version of the JSON schema."
},
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
"vendor": { "$ref": "#/definitions/vendor" },
"configurePresets": { "$ref": "#/definitions/configurePresetsV7" },
"buildPresets": { "$ref": "#/definitions/buildPresetsV4" },
"testPresets": { "$ref": "#/definitions/testPresetsV6" },
"packagePresets": { "$ref": "#/definitions/packagePresetsV6" },
"workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" },
"include": { "$ref": "#/definitions/include" }
},
"additionalProperties": false
} }
], ],
"required": [ "required": [
"version" "version"
], ],
"definitions": { "definitions": {
"$schema": {
"type": "string",
"description": "The schema against which to verify this document.",
"format": "uri-reference"
},
"cmakeMinimumRequired": { "cmakeMinimumRequired": {
"type": "object", "type": "object",
"description": "An optional object representing the minimum version of CMake needed to build this project.", "description": "An optional object representing the minimum version of CMake needed to build this project.",

@ -0,0 +1,20 @@
CMP0152
-------
.. versionadded:: 3.28
:command:`file(REAL_PATH)` resolves symlinks before collapsing ../ components.
In CMake 3.27 and below, :command:`file(REAL_PATH)` collapsed any ``../``
components in a path before resolving symlinks. This produced incorrect
results when the ``../`` collapsed away a symlink.
The ``OLD`` behavior for this policy is to collapse ``../`` components before
resolving symlinks.
The ``NEW`` behavior for this policy is to resolve all symlinks before
collapsing ``../`` components.
This policy was introduced in CMake version 3.28. Use the
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt

@ -0,0 +1,14 @@
CMP0153
-------
.. versionadded:: 3.28
The :command:`exec_program` command should not be called.
This command has long been superseded by the :command:`execute_process`
command and has been deprecated since CMake 3.0.
.. |disallowed_version| replace:: 3.28
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt

@ -0,0 +1,59 @@
CMP0154
-------
.. versionadded:: 3.28
Generated files are private by default in targets using :ref:`file sets`.
CMake 3.27 and below assume that any file generated as an output or byproduct
of :command:`add_custom_command` or :command:`add_custom_target` may be a
public header file meant for inclusion by dependents' source files. This
requires :ref:`Ninja Generators` to add conservative order-only dependencies
that prevent a target's source files from compiling before custom commands
from the target's dependencies are finished, even if those custom commands
only produce sources private to their own target.
:ref:`File Sets`, introduced by CMake 3.23, provide a way to express the
visibility of generated header files. CMake 3.28 and above prefer to
assume that, in targets using file sets, generated files are private to
their own target by default. Generated public headers must be specified
as members of a ``PUBLIC`` (or ``INTERFACE``) ``FILE_SET``, typically of
type ``HEADERS``. With this information, :ref:`Ninja Generators` may omit
the above-mentioned conservative dependencies and produce more efficient
build graphs.
Additionally, if the custom command's output is a member of a file set of type
``CXX_MODULES``, it will additionally not be required to exist before
compiling other sources in the same target. Since these files should not be
included at compile time directly, they may not be implicitly required to
exist for other compilation rules.
This policy provides compatibility for projects using file sets in targets
with generated header files that have not been updated. Such projects
should be updated to express generated public headers in a file set.
For example:
.. code-block:: cmake
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h
...
)
target_sources(foo
PUBLIC FILE_SET HEADERS
BASE_DIRS ${CMAKE_CURRENT_BINARY_DIR}
FILES ${CMAKE_CURRENT_BINARY_DIR}/foo.h
)
The ``OLD`` behavior for this policy is to assume generated files are
public, even in targets using file sets, and for :ref:`Ninja Generators`
to produce conservative build graphs. The ``NEW`` behavior for this
policy is to assume generated files are private in targets using file sets,
and for :ref:`Ninja Generators` to produce more efficient build graphs.
This policy was introduced in CMake version 3.28. Use the
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
Unlike many policies, CMake version |release| does *not* warn
when this policy is not set and simply uses ``OLD`` behavior.
.. include:: DEPRECATED.txt

@ -0,0 +1,28 @@
CMP0155
-------
.. versionadded:: 3.28
C++ sources in targets with at least C++20 are scanned for imports
when supported.
CMake 3.27 and below assume that C++ sources do not ``import`` modules.
CMake 3.28 and above prefer to assume that C++ sources in targets using C++20
or higher might ``import`` modules, and must be scanned before compiling,
unless explicitly disabled. This policy provides compatibility for projects
that use C++20 or higher, without modules, that have not been updated to turn
off scanning, e.g., via the :variable:`CMAKE_CXX_SCAN_FOR_MODULES` variable.
See the :manual:`cmake-cxxmodules(7)` manual for more details on C++ module
support.
The ``OLD`` behavior for this policy is to assume that C++ 20 and newer
sources do not import modules. The ``NEW`` behavior for this policy is to
assume that C++ 20 and newer files may import modules if the compiler
understands how to scan for their dependencies, and need to be scanned.
This policy was introduced in CMake version 3.28. Use the
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
Unlike many policies, CMake version |release| does *not* warn
when this policy is not set and simply uses ``OLD`` behavior.
.. include:: DEPRECATED.txt

@ -16,8 +16,8 @@ generator emits the ``EFFECTIVE_PLATFORM_NAME`` variable:
- If set to ``ON`` it will always be emitted - If set to ``ON`` it will always be emitted
- If set to ``OFF`` it will never be emitted - If set to ``OFF`` it will never be emitted
- If unset (the default) it will only be emitted when the project was - If unset (the default) it will only be emitted when the project was
configured for an embedded Xcode SDK like iOS, tvOS, watchOS or any configured for an embedded Xcode SDK like iOS, tvOS, visionOS, watchOS
of the simulators. or any of the simulators.
.. note:: .. note::

@ -1,7 +1,7 @@
CXX_SCAN_FOR_MODULES CXX_SCAN_FOR_MODULES
-------------------- --------------------
.. versionadded:: 3.26 .. versionadded:: 3.28
``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan the ``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan the
source for C++ module dependencies. See also the source for C++ module dependencies. See also the
@ -16,8 +16,3 @@ consulted.
Note that scanning is only performed if C++20 or higher is enabled for the Note that scanning is only performed if C++20 or higher is enabled for the
target and the source uses the ``CXX`` language. Scanning for modules in target and the source uses the ``CXX`` language. Scanning for modules in
sources belonging to file sets of type ``CXX_MODULES`` is always performed. sources belonging to file sets of type ``CXX_MODULES`` is always performed.
.. note ::
This setting is meaningful only when experimental support for C++ modules
has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate.

@ -0,0 +1,7 @@
GENERATED_RESOURCE_SPEC_FILE
----------------------------
.. versionadded:: 3.28
Path to the :ref:`dynamically-generated resource spec file
<ctest-resource-dynamically-generated-spec-file>` generated by this test.

@ -1,7 +1,7 @@
COMPATIBLE_INTERFACE_NUMBER_MIN COMPATIBLE_INTERFACE_NUMBER_MIN
------------------------------- -------------------------------
Properties whose maximum value from the link interface will be used. Properties whose minimum value from the link interface will be used.
The ``COMPATIBLE_INTERFACE_NUMBER_MIN`` property may contain a list of The ``COMPATIBLE_INTERFACE_NUMBER_MIN`` property may contain a list of
properties for this target whose minimum value may be read at generate properties for this target whose minimum value may be read at generate

@ -1,11 +1,7 @@
CXX_MODULE_DIRS CXX_MODULE_DIRS
--------------- ---------------
.. versionadded:: 3.25 .. versionadded:: 3.28
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Semicolon-separated list of base directories of the target's default Semicolon-separated list of base directories of the target's default
C++ module set (i.e. the file set with name and type ``CXX_MODULES``). The C++ module set (i.e. the file set with name and type ``CXX_MODULES``). The

@ -1,11 +1,7 @@
CXX_MODULE_DIRS_<NAME> CXX_MODULE_DIRS_<NAME>
---------------------- ----------------------
.. versionadded:: 3.25 .. versionadded:: 3.28
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Semicolon-separated list of base directories of the target's ``<NAME>`` C++ Semicolon-separated list of base directories of the target's ``<NAME>`` C++
module set, which has the set type ``CXX_MODULES``. The property supports module set, which has the set type ``CXX_MODULES``. The property supports

@ -1,11 +1,7 @@
CXX_MODULE_SET CXX_MODULE_SET
-------------- --------------
.. versionadded:: 3.25 .. versionadded:: 3.28
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Semicolon-separated list of files in the target's default C++ module set, Semicolon-separated list of files in the target's default C++ module set,
(i.e. the file set with name and type ``CXX_MODULES``). If any of the paths (i.e. the file set with name and type ``CXX_MODULES``). If any of the paths

@ -1,11 +1,7 @@
CXX_MODULE_SETS CXX_MODULE_SETS
--------------- ---------------
.. versionadded:: 3.25 .. versionadded:: 3.28
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Read-only list of the target's ``PRIVATE`` and ``PUBLIC`` C++ module sets (i.e. Read-only list of the target's ``PRIVATE`` and ``PUBLIC`` C++ module sets (i.e.
all file sets with the type ``CXX_MODULES``). Files listed in these file sets all file sets with the type ``CXX_MODULES``). Files listed in these file sets

@ -1,11 +1,7 @@
CXX_MODULE_SET_<NAME> CXX_MODULE_SET_<NAME>
--------------------- ---------------------
.. versionadded:: 3.25 .. versionadded:: 3.28
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Semicolon-separated list of files in the target's ``<NAME>`` C++ module set, Semicolon-separated list of files in the target's ``<NAME>`` C++ module set,
which has the set type ``CXX_MODULES``. If any of the paths are relative, they which has the set type ``CXX_MODULES``. If any of the paths are relative, they

@ -1,7 +1,7 @@
CXX_SCAN_FOR_MODULES CXX_SCAN_FOR_MODULES
-------------------- --------------------
.. versionadded:: 3.26 .. versionadded:: 3.28
``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan C++ ``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan C++
sources in the target for module dependencies. See also the sources in the target for module dependencies. See also the
@ -20,8 +20,3 @@ scan the target's ``CXX`` sources at build time.
Note that scanning is only performed if C++20 or higher is enabled for the Note that scanning is only performed if C++20 or higher is enabled for the
target. Scanning for modules in the target's sources belonging to file sets target. Scanning for modules in the target's sources belonging to file sets
of type ``CXX_MODULES`` is always performed. of type ``CXX_MODULES`` is always performed.
.. note ::
This setting is meaningful only when experimental support for C++ modules
has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate.

@ -3,8 +3,8 @@ DLL_NAME_WITH_SOVERSION
.. versionadded:: 3.27 .. versionadded:: 3.27
This property control whether the :prop_tgt:`SOVERSION` target This property controls whether the :prop_tgt:`SOVERSION` target
property are added to the filename of generated DLL filenames property is added to the filename of generated DLL filenames
for the Windows platform, which is selected when the for the Windows platform, which is selected when the
:variable:`WIN32` variable is set. :variable:`WIN32` variable is set.

@ -3,7 +3,8 @@ HIP_ARCHITECTURES
.. versionadded:: 3.21 .. versionadded:: 3.21
List of AMD GPU architectures to generate device code for. List of GPU architectures to for which to generate device code.
Architecture names are interpreted based on :variable:`CMAKE_HIP_PLATFORM`.
A non-empty false value (e.g. ``OFF``) disables adding architectures. A non-empty false value (e.g. ``OFF``) disables adding architectures.
This is intended to support packagers and rare cases where full control This is intended to support packagers and rare cases where full control

@ -0,0 +1,10 @@
IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS
----------------------------------------
.. versionadded:: 3.28
Preprocessor definitions for compiling an ``IMPORTED`` target's C++ module
sources.
CMake will automatically drop some definitions that are not supported
by the native build tool.

@ -0,0 +1,9 @@
IMPORTED_CXX_MODULES_COMPILE_FEATURES
-------------------------------------
.. versionadded:: 3.28
Compiler features enabled for this ``IMPORTED`` target's C++ modules.
The value of this property is used by the generators to set the include
paths for the compiler.

@ -0,0 +1,9 @@
IMPORTED_CXX_MODULES_COMPILE_OPTIONS
------------------------------------
.. versionadded:: 3.28
List of options to pass to the compiler for this ``IMPORTED`` target's C++
modules.
.. include:: ../command/OPTIONS_SHELL.txt

@ -0,0 +1,10 @@
IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES
----------------------------------------
.. versionadded:: 3.28
List of preprocessor include file search directories when compiling C++
modules for ``IMPORTED`` targets.
The value of this property is used by the generators to set the include
paths for the compiler.

@ -0,0 +1,7 @@
IMPORTED_CXX_MODULES_LINK_LIBRARIES
-----------------------------------
.. versionadded:: 3.28
List of direct dependencies to use for usage requirements for C++ modules in
the target's C++ modules.

@ -11,6 +11,12 @@ This property may be set:
* On macOS, to an import file (e.g. ``.tbd``) created for shared libraries (see * On macOS, to an import file (e.g. ``.tbd``) created for shared libraries (see
the :prop_tgt:`ENABLE_EXPORTS` target property). For frameworks this is the the :prop_tgt:`ENABLE_EXPORTS` target property). For frameworks this is the
location of the ``.tbd`` file symlink just inside the framework folder. location of the ``.tbd`` file symlink just inside the framework folder.
* .. versionadded:: 3.28
On non-DLL platforms, to the location of a shared library.
When set without also specifying an :prop_tgt:`IMPORTED_LOCATION`,
the library is considered to be a stub, and its location will not
be added as a runtime search path to dependents that link it.
The ``IMPORTED_IMPLIB`` target property may be overridden for a The ``IMPORTED_IMPLIB`` target property may be overridden for a
given configuration ``<CONFIG>`` by the configuration-specific given configuration ``<CONFIG>`` by the configuration-specific

@ -15,6 +15,17 @@ is the location of the ``.dll`` part of the library. For ``UNKNOWN``
libraries this is the location of the file to be linked. Ignored for libraries this is the location of the file to be linked. Ignored for
non-imported targets. non-imported targets.
.. versionadded:: 3.28
For frameworks on macOS, this may be the location of the framework folder
itself.
.. versionadded:: 3.28
This may be the location of a ``.xcframework`` folder on macOS. If it is,
any target that links against it will get the selected library's ``Headers``
directory as a usage requirement.
The ``IMPORTED_LOCATION`` target property may be overridden for a The ``IMPORTED_LOCATION`` target property may be overridden for a
given configuration ``<CONFIG>`` by the configuration-specific given configuration ``<CONFIG>`` by the configuration-specific
:prop_tgt:`IMPORTED_LOCATION_<CONFIG>` target property. Furthermore, :prop_tgt:`IMPORTED_LOCATION_<CONFIG>` target property. Furthermore,

@ -31,7 +31,7 @@ once per architecture for each source file. Unlike the other generators,
it does not generate universal object file binaries. it does not generate universal object file binaries.
A further complication with the :generator:`Xcode` generator is that when A further complication with the :generator:`Xcode` generator is that when
targeting device platforms (iOS, tvOS or watchOS), the :generator:`Xcode` targeting device platforms (iOS, tvOS, visionOS or watchOS), the :generator:`Xcode`
generator has the ability to use either the device or simulator SDK without generator has the ability to use either the device or simulator SDK without
needing CMake to be re-run. The SDK can be selected at build time. needing CMake to be re-run. The SDK can be selected at build time.
But since some architectures can be supported by both the device and the But since some architectures can be supported by both the device and the

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

Loading…
Cancel
Save