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
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
.. _ModulesInLibcxx:
=================
Modules in libc++
=================
.. warning:: Modules are an experimental feature. It has additional build
requirements and not all libc++ configurations are supported yet.
The work is still in an early developement state and not
considered stable nor complete
This page contains information regarding C++23 module support in libc++.
There are two kinds of modules available in Clang
* `Clang specific modules <https://clang.llvm.org/docs/Modules.html>`_
* `C++ modules <https://clang.llvm.org/docs/StandardCPlusPlusModules.html>`_
This page mainly discusses the C++ modules. In C++20 there are also header units,
these are not part of this document.
Overview
========
The module sources are stored in ``.cppm`` files. Modules need to be available
as BMIs, which are ``.pcm`` files for Clang. BMIs are not portable, they depend
on the compiler used and its compilation flags. Therefore there needs to be a
way to distribute the ``.cppm`` files to the user and offer a way for them to
build and use the ``.pcm`` files. It is expected this will be done by build
systems in the future. To aid early adaptor and build system vendors libc++
currently ships a CMake project to aid building modules.
.. note:: This CMake file is intended to be a temporary solution and will
be removed in the future. The timeline for the removal depends
on the availability of build systems with proper module support.
What works
~~~~~~~~~~
* Building BMIs
* Running tests using the ``std`` module
* Using the ``std`` module in external projects
* The following "parts disabled" configuration options are supported
* ``LIBCXX_ENABLE_LOCALIZATION``
* ``LIBCXX_ENABLE_WIDE_CHARACTERS``
Some of the current limitations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* There is no official build system support, libc++ has experimental CMake support
* Requires CMake 3.26
* Requires Ninja 1.11
* Requires a recent Clang 17
* The path to the compiler may not be a symlink, ``clang-scan-deps`` does
not handle that case properly
* Only C++23 is tested
* Libc++ is not tested with modules instead of headers
* The module ``.cppm`` files are not installed
* The experimental ``PSTL`` library is not supported
* Clang supports modules using GNU extensions, but libc++ does not work using
GNU extensions.
* Clang:
* Including headers after importing the ``std`` module may fail. This is
hard to solve and there is a work-around by first including all headers
`bug report <https://github.com/llvm/llvm-project/issues/61465>`__.
Blockers
~~~~~~~~
* libc++
* Currently the tests only test with modules enabled, but do not import
modules instead of headers. When converting tests to using modules there
are still failures. These are under investigation.
* It has not been determined how to fully test libc++ with modules instead
of headers.
* Clang
* Some concepts do not work properly
`bug report <https://github.com/llvm/llvm-project/issues/62943>`__.
Using in external projects
==========================
Users need to be able to build their own BMI files.
.. note:: The requirements for users to build their own BMI files will remain
true for the forseeable future. For now this needs to be done manually.
Once libc++'s implementation is more mature we will reach out to build
system vendors, with the goal that building the BMI files is done by
the build system.
Currently this requires a local build of libc++ with modules enabled. Since
modules are not part of the installation yet, they are used from the build
directory. First libc++ needs to be build with module support enabled.
.. code-block:: bash
$ git clone https://github.com/llvm/llvm-project.git
$ cd llvm-project
$ mkdir build
$ cmake -G Ninja -S runtimes -B build -DLIBCXX_ENABLE_STD_MODULES=ON -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind"
$ ninja -C build
The above ``build`` directory will be referred to as ``<build>`` in the
rest of these instructions.
This is a small sample program that uses the module ``std``. It consists of a
``CMakeLists.txt`` and a ``main.cpp`` file.
.. code-block:: cpp
import std;
int main() { std::cout << "Hello modular world\n"; }
.. code-block:: cmake
cmake_minimum_required(VERSION 3.26.0 FATAL_ERROR)
project("module"
LANGUAGES CXX
)
#
# Set language version used
#
# At the moment only C++23 is tested.
set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED YES)
# Libc++ doesn't support compiler extensions for modules.
set(CMAKE_CXX_EXTENSIONS OFF)
#
# Enable modules in CMake
#
# This is required to write your own modules in your project.
if(CMAKE_VERSION VERSION_LESS "3.27.0")
set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "2182bf5c-ef0d-489a-91da-49dbc3090d2a")
else()
set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "aa1f7df0-828a-4fcd-9afc-2dc80491aca7")
endif()
set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP 1)
#
# Import the modules from libc++
#
include(FetchContent)
FetchContent_Declare(
std
URL "file://${LIBCXX_BUILD}/modules/c++/v1/"
DOWNLOAD_EXTRACT_TIMESTAMP TRUE
)
FetchContent_GetProperties(std)
if(NOT std_POPULATED)
FetchContent_Populate(std)
add_subdirectory(${std_SOURCE_DIR} ${std_BINARY_DIR} EXCLUDE_FROM_ALL)
endif()
#
# Adjust project compiler flags
#
add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-fprebuilt-module-path=${CMAKE_BINARY_DIR}/_deps/std-build/CMakeFiles/std.dir/>)
add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-nostdinc++>)
# The include path needs to be set to be able to use macros from headers.
# For example from, the headers <cassert> and <version>.
add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-isystem>)
add_compile_options($<$<COMPILE_LANGUAGE:CXX>:${LIBCXX_BUILD}/include/c++/v1>)
#
# Adjust project linker flags
#
add_link_options($<$<COMPILE_LANGUAGE:CXX>:-nostdlib++>)
add_link_options($<$<COMPILE_LANGUAGE:CXX>:-L${LIBCXX_BUILD}/lib>)
add_link_options($<$<COMPILE_LANGUAGE:CXX>:-Wl,-rpath,${LIBCXX_BUILD}/lib>)
# Linking against std is required for CMake to get the proper dependencies
link_libraries(std c++)
#
# Add the project
#
add_executable(main)
target_sources(main
PRIVATE
main.cpp
)
Building this project is done with the following steps, assuming the files
``main.cpp`` and ``CMakeLists.txt`` are copied in the current directory.
.. code-block:: bash
$ mkdir build
$ cmake -G Ninja -S . -B build -DCMAKE_CXX_COMPILER=<path-to-compiler> -DLIBCXX_BUILD=<build>
$ ninja -C build
$ build/main
.. warning:: ``<path-to-compiler>`` should point point to the real binary and
not to a symlink.
.. warning:: When using these examples in your own projects make sure the
compilation flags are the same for the ``std`` module and your
project. Some flags will affect the generated code, when these
are different the module cannot be used. For example using
``-pthread`` in your project and not in the module will give
errors like
``error: POSIX thread support was disabled in PCH file but is currently enabled``
``error: module file _deps/std-build/CMakeFiles/std.dir/std.pcm cannot be loaded due to a configuration mismatch with the current compilation [-Wmodule-file-config-mismatch]``
If you have questions about modules feel free to ask them in the ``#libcxx``
channel on `LLVM's Discord server <https://discord.gg/jzUbyP26tQ>`__.
If you think you've found a bug please it using the `LLVM bug tracker
<https://github.com/llvm/llvm-project/issues>`_. Please make sure the issue
you found is not one of the known bugs or limitations on this page.
|
