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
Create a new entry on the policy stack.
.. signature:: cmake_policy(POP)
:target: POP
cmake_policy(PUSH) Remove the last policy stack entry created with ``cmake_policy(PUSH)``.
cmake_policy(POP)
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::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
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::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
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
@ -346,7 +355,7 @@ that order).
``REGISTRY_VIEW`` can be specified to manage ``Windows`` registry queries ``REGISTRY_VIEW`` can be specified to manage ``Windows`` registry queries
specified as part of ``PATHS`` and ``HINTS``. specified as part of ``PATHS`` and ``HINTS``.
.. include:: FIND_XXX_REGISTRY_VIEW.txt .. include:: FIND_XXX_REGISTRY_VIEW.txt
If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each
(``W``) or (``U``) directory entry one-by-one. (``W``) or (``U``) directory entry one-by-one.

@ -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::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
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

File diff suppressed because it is too large Load Diff

@ -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
watchOS watchOS watchos watchsimulator visionOS visionOS xros xrsimulator
======= ================= ==================== ================ 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
======== ========

@ -9,9 +9,9 @@
"const": 1, "const": 1,
"description": "A required integer representing the version of the JSON schema." "description": "A required integer representing the version of the JSON schema."
}, },
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
"vendor": { "$ref": "#/definitions/vendor" }, "vendor": { "$ref": "#/definitions/vendor" },
"configurePresets": { "$ref": "#/definitions/configurePresetsV1"} "configurePresets": { "$ref": "#/definitions/configurePresetsV1" }
}, },
"additionalProperties": false "additionalProperties": false
}, },
@ -21,11 +21,11 @@
"const": 2, "const": 2,
"description": "A required integer representing the version of the JSON schema." "description": "A required integer representing the version of the JSON schema."
}, },
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
"vendor": { "$ref": "#/definitions/vendor" }, "vendor": { "$ref": "#/definitions/vendor" },
"configurePresets": { "$ref": "#/definitions/configurePresetsV1"}, "configurePresets": { "$ref": "#/definitions/configurePresetsV1" },
"buildPresets": { "$ref": "#/definitions/buildPresetsV2"}, "buildPresets": { "$ref": "#/definitions/buildPresetsV2" },
"testPresets": { "$ref": "#/definitions/testPresetsV2"} "testPresets": { "$ref": "#/definitions/testPresetsV2" }
}, },
"additionalProperties": false "additionalProperties": false
}, },
@ -35,11 +35,11 @@
"const": 3, "const": 3,
"description": "A required integer representing the version of the JSON schema." "description": "A required integer representing the version of the JSON schema."
}, },
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
"vendor": { "$ref": "#/definitions/vendor" }, "vendor": { "$ref": "#/definitions/vendor" },
"configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, "configurePresets": { "$ref": "#/definitions/configurePresetsV3" },
"buildPresets": { "$ref": "#/definitions/buildPresetsV3"}, "buildPresets": { "$ref": "#/definitions/buildPresetsV3" },
"testPresets": { "$ref": "#/definitions/testPresetsV3"} "testPresets": { "$ref": "#/definitions/testPresetsV3" }
}, },
"additionalProperties": false "additionalProperties": false
}, },
@ -49,12 +49,12 @@
"const": 4, "const": 4,
"description": "A required integer representing the version of the JSON schema." "description": "A required integer representing the version of the JSON schema."
}, },
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
"vendor": { "$ref": "#/definitions/vendor" }, "vendor": { "$ref": "#/definitions/vendor" },
"configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, "configurePresets": { "$ref": "#/definitions/configurePresetsV3" },
"buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, "buildPresets": { "$ref": "#/definitions/buildPresetsV4" },
"testPresets": { "$ref": "#/definitions/testPresetsV3"}, "testPresets": { "$ref": "#/definitions/testPresetsV3" },
"include": { "$ref": "#/definitions/include"} "include": { "$ref": "#/definitions/include" }
}, },
"additionalProperties": false "additionalProperties": false
}, },
@ -64,12 +64,12 @@
"const": 5, "const": 5,
"description": "A required integer representing the version of the JSON schema." "description": "A required integer representing the version of the JSON schema."
}, },
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
"vendor": { "$ref": "#/definitions/vendor" }, "vendor": { "$ref": "#/definitions/vendor" },
"configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, "configurePresets": { "$ref": "#/definitions/configurePresetsV3" },
"buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, "buildPresets": { "$ref": "#/definitions/buildPresetsV4" },
"testPresets": { "$ref": "#/definitions/testPresetsV5"}, "testPresets": { "$ref": "#/definitions/testPresetsV5" },
"include": { "$ref": "#/definitions/include"} "include": { "$ref": "#/definitions/include" }
}, },
"additionalProperties": false "additionalProperties": false
}, },
@ -79,14 +79,14 @@
"const": 6, "const": 6,
"description": "A required integer representing the version of the JSON schema." "description": "A required integer representing the version of the JSON schema."
}, },
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
"vendor": { "$ref": "#/definitions/vendor" }, "vendor": { "$ref": "#/definitions/vendor" },
"configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, "configurePresets": { "$ref": "#/definitions/configurePresetsV3" },
"buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, "buildPresets": { "$ref": "#/definitions/buildPresetsV4" },
"testPresets": { "$ref": "#/definitions/testPresetsV6"}, "testPresets": { "$ref": "#/definitions/testPresetsV6" },
"packagePresets": { "$ref": "#/definitions/packagePresetsV6"}, "packagePresets": { "$ref": "#/definitions/packagePresetsV6" },
"workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" }, "workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" },
"include": { "$ref": "#/definitions/include"} "include": { "$ref": "#/definitions/include" }
}, },
"additionalProperties": false "additionalProperties": false
}, },
@ -96,14 +96,32 @@
"const": 7, "const": 7,
"description": "A required integer representing the version of the JSON schema." "description": "A required integer representing the version of the JSON schema."
}, },
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
"vendor": { "$ref": "#/definitions/vendor" }, "vendor": { "$ref": "#/definitions/vendor" },
"configurePresets": { "$ref": "#/definitions/configurePresetsV7"}, "configurePresets": { "$ref": "#/definitions/configurePresetsV7" },
"buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, "buildPresets": { "$ref": "#/definitions/buildPresetsV4" },
"testPresets": { "$ref": "#/definitions/testPresetsV6"}, "testPresets": { "$ref": "#/definitions/testPresetsV6" },
"packagePresets": { "$ref": "#/definitions/packagePresetsV6"}, "packagePresets": { "$ref": "#/definitions/packagePresetsV6" },
"workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" }, "workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" },
"include": { "$ref": "#/definitions/include"} "include": { "$ref": "#/definitions/include" }
},
"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 "additionalProperties": false
} }
@ -112,6 +130,11 @@
"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