1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
CMake Experimental Features Guide
*********************************
The following is a guide to CMake experimental features that are
under development and not yet included in official documentation.
See documentation on `CMake Development`_ for more information.
.. _`CMake Development`: README.rst
Features are gated behind ``CMAKE_EXPERIMENTAL_`` variables which must be set
to specific values in order to enable their gated behaviors. Note that the
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: ``2182bf5c-ef0d-489a-91da-49dbc3090d2a``
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.
``CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP``
Set this to ``1`` in order to activate this undocumented experimental
infrastructure. This is **intended to make the functionality available
to compiler writers** so they can use it to develop and test their
dependency scanning tool.
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
set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP 1)
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
|
