diff options
Diffstat (limited to 'Help')
20 files changed, 23 insertions, 219 deletions
diff --git a/Help/command/export.rst b/Help/command/export.rst index 2e14a10..cc927bc 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -54,10 +54,7 @@ The options are: to support consumers using CMake versions older than 2.8.12. ``CXX_MODULES_DIRECTORY <directory>`` - - .. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + .. versionadded:: 3.28 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). diff --git a/Help/command/install.rst b/Help/command/install.rst index 4de3ce1..b0698dd 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -232,10 +232,7 @@ Signatures would be installed to ``myproj/here.h`` below the destination. ``CXX_MODULES_BMI`` - - .. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + .. versionadded:: 3.28 Any module files from C++ modules from ``PUBLIC`` sources in a file set of type ``CXX_MODULES`` will be installed to the given ``DESTINATION``. All @@ -843,10 +840,7 @@ Signatures and defines required to use the libraries. ``CXX_MODULES_DIRECTORY`` - - .. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + .. versionadded:: 3.28 Specify a subdirectory to store C++ module information for targets in the export set. This directory will be populated with files which add the diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 86bf7fb..40755c5 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -84,10 +84,7 @@ files within those directories. The acceptable types include: Sources intended to be used via a language's ``#include`` mechanism. ``CXX_MODULES`` - - .. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + .. versionadded:: 3.28 Sources which contain C++ interface module or partition units (i.e., those using the ``export`` keyword). This file set type may not have an diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index bc2b0af..0255b4d 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -261,14 +261,11 @@ The options for the above signatures are: 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. - .. note :: - - Experimental. Sources of type ``CXX_MODULE`` are gated by - ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` - The default type of sources is ``NORMAL``. ``<LANG>_STANDARD <std>`` diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst index 046d214..87ac031 100644 --- a/Help/dev/experimental.rst +++ b/Help/dev/experimental.rst @@ -13,133 +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 feature is in use and that the affected behavior in the project is not part of CMake's stability guarantees. - -C++20 Module APIs -================= - -Variable: ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` -Value: ``ac01f462-0f5f-432a-86aa-acef252918a6`` - -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. - -In order to support ``IMPORTED`` targets with associated C++20 module sources, -the ``CMAKE_EXPERIMENTAL_CXX_MODULE_BMI_ONLY_FLAG`` variable must be provided -to have the compiler only output a BMI instead of a BMI and an object file. - -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>") - set(CMAKE_EXPERIMENTAL_CXX_MODULE_BMI_ONLY_FLAG - "-fmodule-only") - -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 diff --git a/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst b/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst index 5b704dc..d10969a 100644 --- a/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst +++ b/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst @@ -1,7 +1,7 @@ CXX_SCAN_FOR_MODULES -------------------- -.. versionadded:: 3.26 +.. versionadded:: 3.28 ``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan 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 target and the source uses the ``CXX`` language. Scanning for modules in 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. diff --git a/Help/prop_tgt/CXX_MODULE_DIRS.rst b/Help/prop_tgt/CXX_MODULE_DIRS.rst index a32b5b1..6c5dd3a 100644 --- a/Help/prop_tgt/CXX_MODULE_DIRS.rst +++ b/Help/prop_tgt/CXX_MODULE_DIRS.rst @@ -1,11 +1,7 @@ CXX_MODULE_DIRS --------------- -.. versionadded:: 3.25 - -.. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` +.. versionadded:: 3.28 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 diff --git a/Help/prop_tgt/CXX_MODULE_DIRS_NAME.rst b/Help/prop_tgt/CXX_MODULE_DIRS_NAME.rst index 9190991..8b6e4dd 100644 --- a/Help/prop_tgt/CXX_MODULE_DIRS_NAME.rst +++ b/Help/prop_tgt/CXX_MODULE_DIRS_NAME.rst @@ -1,11 +1,7 @@ CXX_MODULE_DIRS_<NAME> ---------------------- -.. versionadded:: 3.25 - -.. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` +.. versionadded:: 3.28 Semicolon-separated list of base directories of the target's ``<NAME>`` C++ module set, which has the set type ``CXX_MODULES``. The property supports diff --git a/Help/prop_tgt/CXX_MODULE_SET.rst b/Help/prop_tgt/CXX_MODULE_SET.rst index f5cd8b2..851de86 100644 --- a/Help/prop_tgt/CXX_MODULE_SET.rst +++ b/Help/prop_tgt/CXX_MODULE_SET.rst @@ -1,11 +1,7 @@ CXX_MODULE_SET -------------- -.. versionadded:: 3.25 - -.. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` +.. versionadded:: 3.28 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 diff --git a/Help/prop_tgt/CXX_MODULE_SETS.rst b/Help/prop_tgt/CXX_MODULE_SETS.rst index 0e8945a..2165027 100644 --- a/Help/prop_tgt/CXX_MODULE_SETS.rst +++ b/Help/prop_tgt/CXX_MODULE_SETS.rst @@ -1,11 +1,7 @@ CXX_MODULE_SETS --------------- -.. versionadded:: 3.25 - -.. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` +.. versionadded:: 3.28 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 diff --git a/Help/prop_tgt/CXX_MODULE_SET_NAME.rst b/Help/prop_tgt/CXX_MODULE_SET_NAME.rst index 5674c99..e73e28a 100644 --- a/Help/prop_tgt/CXX_MODULE_SET_NAME.rst +++ b/Help/prop_tgt/CXX_MODULE_SET_NAME.rst @@ -1,11 +1,7 @@ CXX_MODULE_SET_<NAME> --------------------- -.. versionadded:: 3.25 - -.. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` +.. versionadded:: 3.28 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 diff --git a/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst b/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst index 93a1b73..791914e 100644 --- a/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst +++ b/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst @@ -1,7 +1,7 @@ CXX_SCAN_FOR_MODULES -------------------- -.. versionadded:: 3.26 +.. versionadded:: 3.28 ``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan C++ 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 target. Scanning for modules in the target's 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. diff --git a/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS.rst b/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS.rst index 88687b2..b068191 100644 --- a/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS.rst +++ b/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS.rst @@ -3,10 +3,6 @@ IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS .. versionadded:: 3.28 -.. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` - Preprocessor definitions for compiling an ``IMPORTED`` target's C++ module sources. diff --git a/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_FEATURES.rst b/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_FEATURES.rst index c3eb7fb..cea359f 100644 --- a/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_FEATURES.rst +++ b/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_FEATURES.rst @@ -3,10 +3,6 @@ IMPORTED_CXX_MODULES_COMPILE_FEATURES .. versionadded:: 3.28 -.. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` - Compiler features enabled for this ``IMPORTED`` target's C++ modules. The value of this property is used by the generators to set the include diff --git a/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_OPTIONS.rst b/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_OPTIONS.rst index 5c62c77..cf7bc5b 100644 --- a/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_OPTIONS.rst +++ b/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_OPTIONS.rst @@ -3,10 +3,6 @@ IMPORTED_CXX_MODULES_COMPILE_OPTIONS .. versionadded:: 3.28 -.. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` - List of options to pass to the compiler for this ``IMPORTED`` target's C++ modules. diff --git a/Help/prop_tgt/IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES.rst index 08a993d..46d74ea 100644 --- a/Help/prop_tgt/IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES.rst @@ -3,10 +3,6 @@ IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES .. versionadded:: 3.28 -.. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` - List of preprocessor include file search directories when compiling C++ modules for ``IMPORTED`` targets. diff --git a/Help/prop_tgt/IMPORTED_CXX_MODULES_LINK_LIBRARIES.rst b/Help/prop_tgt/IMPORTED_CXX_MODULES_LINK_LIBRARIES.rst index 5111dc5..ff5cec8 100644 --- a/Help/prop_tgt/IMPORTED_CXX_MODULES_LINK_LIBRARIES.rst +++ b/Help/prop_tgt/IMPORTED_CXX_MODULES_LINK_LIBRARIES.rst @@ -3,9 +3,5 @@ IMPORTED_CXX_MODULES_LINK_LIBRARIES .. versionadded:: 3.28 -.. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` - List of direct dependencies to use for usage requirements for C++ modules in the target's C++ modules. diff --git a/Help/prop_tgt/INTERFACE_CXX_MODULE_SETS.rst b/Help/prop_tgt/INTERFACE_CXX_MODULE_SETS.rst index c7ed46d..fd6e34b 100644 --- a/Help/prop_tgt/INTERFACE_CXX_MODULE_SETS.rst +++ b/Help/prop_tgt/INTERFACE_CXX_MODULE_SETS.rst @@ -1,11 +1,7 @@ INTERFACE_CXX_MODULE_SETS ------------------------- -.. versionadded:: 3.25 - -.. note :: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` +.. versionadded:: 3.28 Read-only list of the target's ``PUBLIC`` C++ module sets (i.e. all file sets with the type ``CXX_MODULES``). Files listed in these C++ module sets can be diff --git a/Help/release/dev/cxxmodules-no-longer-experimental.rst b/Help/release/dev/cxxmodules-no-longer-experimental.rst new file mode 100644 index 0000000..3ad45fe --- /dev/null +++ b/Help/release/dev/cxxmodules-no-longer-experimental.rst @@ -0,0 +1,8 @@ +cxxmodules-no-longer-experimental +--------------------------------- + +* C++ 20 named modules are now supported by :ref:`Ninja Generators` + and :ref:`Visual Studio Generators` for VS 2022 and newer, in combination + with the MSVC 14.34 toolset (provided with VS 17.4) and newer, LLVM/Clang + 16.0 and newer, and GCC 14 (after the 2023-09-20 daily bump) and newer. + See :manual:`cmake-cxxmodules(7)` for details. diff --git a/Help/variable/CMAKE_CXX_SCAN_FOR_MODULES.rst b/Help/variable/CMAKE_CXX_SCAN_FOR_MODULES.rst index a40bf75..28601ba 100644 --- a/Help/variable/CMAKE_CXX_SCAN_FOR_MODULES.rst +++ b/Help/variable/CMAKE_CXX_SCAN_FOR_MODULES.rst @@ -1,15 +1,10 @@ CMAKE_CXX_SCAN_FOR_MODULES -------------------------- -.. versionadded:: 3.26 +.. versionadded:: 3.28 Whether to scan C++ source files for module dependencies. This variable is used to initialize the :prop_tgt:`CXX_SCAN_FOR_MODULES` property on all the targets. See that target property for additional information. - -.. note :: - - This setting is meaningful only when experimental support for C++ modules - has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate. |