285 lines · plain
1.. _ModulesInLibcxx:2 3=================4Modules in libc++5=================6 7.. warning:: Modules are an experimental feature. It has additional build8 requirements and not all libc++ configurations are supported yet.9 10 The work is still in an early development state and not11 considered stable nor complete12 13This page contains information regarding C++23 module support in libc++.14There are two kinds of modules available in Clang15 16 * `Clang specific modules <https://clang.llvm.org/docs/Modules.html>`_17 * `C++ modules <https://clang.llvm.org/docs/StandardCPlusPlusModules.html>`_18 19This page mainly discusses the C++ modules. In C++20 there are also header units,20these are not part of this document.21 22Overview23========24 25The module sources are stored in ``.cppm`` files. Modules need to be available26as BMIs, which are ``.pcm`` files for Clang. BMIs are not portable, they depend27on the compiler and the compilation flags used. Therefore there needs to be a28way to distribute the ``.cppm`` files to the user and offer a way for them to29build and use the ``.pcm`` files. It is expected this will be done by build30systems in the future. To aid early adaptor and build system vendors libc++31currently ships a CMake project to aid building modules.32 33.. note:: This CMake file is intended to be a temporary solution and will34 be removed in the future. The timeline for the removal depends35 on the availability of build systems with proper module support.36 37What works38~~~~~~~~~~39 40 * Building BMIs41 * Running tests using the ``std`` and ``std.compat`` module42 * Using the ``std`` and ``std.compat`` module in external projects43 * The following "parts disabled" configuration options are supported44 45 * ``LIBCXX_ENABLE_LOCALIZATION``46 * ``LIBCXX_ENABLE_WIDE_CHARACTERS``47 * ``LIBCXX_ENABLE_THREADS``48 * ``LIBCXX_ENABLE_FILESYSTEM``49 * ``LIBCXX_ENABLE_RANDOM_DEVICE``50 * ``LIBCXX_ENABLE_UNICODE``51 * ``LIBCXX_ENABLE_EXCEPTIONS`` [#note-no-windows]_52 53 * A C++20 based extension54 55.. note::56 57 .. [#note-no-windows] This configuration will probably not work on Windows58 due to hard-coded compilation flags.59 60Some of the current limitations61~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~62 63 * There is no official build system support, libc++ has experimental CMake support64 * Requires CMake 3.26 for C++20 support65 * Requires CMake 3.26 for C++23 support66 * Requires CMake 3.27 for C++26 support67 * Requires Ninja 1.1168 * Requires Clang 1769 * The path to the compiler may not be a symlink, ``clang-scan-deps`` does70 not handle that case properly71 * Libc++ is not tested with modules instead of headers72 * Clang:73 * Including headers after importing the ``std`` module may fail. This is74 hard to solve and there is a work-around by first including all headers75 `bug report <https://llvm.org/PR61465>`__.76 77Blockers78~~~~~~~~79 80 * libc++81 82 * Currently the tests only test with modules enabled, but do not import83 modules instead of headers. When converting tests to using modules there84 are still failures. These are under investigation.85 86 * It has not been determined how to fully test libc++ with modules instead87 of headers.88 89 * Clang90 91 * Some concepts do not work properly `bug report <https://llvm.org/PR61465>`__.92 93 94Using in external projects95==========================96 97Users need to be able to build their own BMI files.98 99.. note:: The requirements for users to build their own BMI files will remain100 true for the foreseeable future. For now this needs to be done manually.101 Once libc++'s implementation is more mature we will reach out to build102 system vendors, with the goal that building the BMI files is done by103 the build system.104 105Currently there are two ways to build modules106 107 * Use a local build of modules from the build directory. This requires108 Clang 17 or later and CMake 3.26 or later.109 110 * Use the installed modules. This requires Clang 18.1.2 or later and111 a recent build of CMake. The CMake changes will be part of CMake 3.30. This112 method requires you or your distribution to enable module installation.113 114Using the local build115~~~~~~~~~~~~~~~~~~~~~116 117.. code-block:: bash118 119 $ git clone https://github.com/llvm/llvm-project.git120 $ cd llvm-project121 $ mkdir build122 $ cmake -G Ninja -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind"123 $ ninja -C build124 125The above ``build`` directory will be referred to as ``<build>`` in the126rest of these instructions.127 128This is a small sample program that uses the module ``std``. It consists of a129``CMakeLists.txt`` and a ``main.cpp`` file.130 131.. code-block:: cpp132 133 import std; // When importing std.compat it's not needed to import std.134 import std.compat;135 136 int main() {137 std::cout << "Hello modular world\n";138 ::printf("Hello compat modular world\n");139 }140 141.. code-block:: cmake142 143 cmake_minimum_required(VERSION 3.26.0 FATAL_ERROR)144 project("example"145 LANGUAGES CXX146 )147 148 #149 # Set language version used150 #151 152 set(CMAKE_CXX_STANDARD 23)153 set(CMAKE_CXX_STANDARD_REQUIRED YES)154 set(CMAKE_CXX_EXTENSIONS OFF)155 156 #157 # Enable modules in CMake158 #159 160 # This is required to write your own modules in your project.161 if(CMAKE_VERSION VERSION_LESS "3.28.0")162 if(CMAKE_VERSION VERSION_LESS "3.27.0")163 set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "2182bf5c-ef0d-489a-91da-49dbc3090d2a")164 else()165 set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "aa1f7df0-828a-4fcd-9afc-2dc80491aca7")166 endif()167 set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP 1)168 else()169 cmake_policy(VERSION 3.28)170 endif()171 172 #173 # Import the modules from libc++174 #175 176 include(FetchContent)177 FetchContent_Declare(178 std179 URL "file://${LIBCXX_BUILD}/modules/c++/v1/"180 DOWNLOAD_EXTRACT_TIMESTAMP TRUE181 SYSTEM182 )183 FetchContent_MakeAvailable(std)184 185 #186 # Add the project187 #188 189 add_executable(main)190 add_dependencies(main std.compat)191 target_link_libraries(main std.compat)192 target_sources(main193 PRIVATE194 main.cpp195 )196 197Building this project is done with the following steps, assuming the files198``main.cpp`` and ``CMakeLists.txt`` are copied in the current directory.199 200.. code-block:: bash201 202 $ mkdir build203 $ cmake -G Ninja -S . -B build -DCMAKE_CXX_COMPILER=<path-to-compiler> -DLIBCXX_BUILD=<build>204 $ ninja -C build205 $ build/main206 207.. warning:: ``<path-to-compiler>`` should point point to the real binary and208 not to a symlink.209 210.. warning:: When using these examples in your own projects make sure the211 compilation flags are the same for the ``std`` module and your212 project. Some flags will affect the generated code, when these213 are different the module cannot be used. For example using214 ``-pthread`` in your project and not in the module will give215 errors like216 217 ``error: POSIX thread support was disabled in PCH file but is currently enabled``218 219 ``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]``220 221 222Using the installed modules223~~~~~~~~~~~~~~~~~~~~~~~~~~~224 225CMake has added experimental support for importing the Standard modules. This226is available in the current nightly builds and will be part of the 3.30227release. Currently CMake only supports importing the Standard modules in C++23228and later. Enabling this for C++20 is on the TODO list of the CMake229developers.230 231The example uses the same ``main.cpp`` as above. It uses the following232``CMakeLists.txt``:233 234.. code-block:: cmake235 236 # This requires a recent nightly build.237 # This will be part of CMake 3.30.0.238 cmake_minimum_required(VERSION 3.29.0 FATAL_ERROR)239 240 # Enables the Standard module support. This needs to be done241 # before selecting the languages.242 set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")243 set(CMAKE_CXX_MODULE_STD ON)244 245 project("example"246 LANGUAGES CXX247 )248 249 #250 # Set language version used251 #252 253 set(CMAKE_CXX_STANDARD 23)254 set(CMAKE_CXX_STANDARD_REQUIRED YES)255 # Currently CMake requires extensions enabled when using import std.256 # https://gitlab.kitware.com/cmake/cmake/-/issues/25916257 # https://gitlab.kitware.com/cmake/cmake/-/issues/25539258 set(CMAKE_CXX_EXTENSIONS ON)259 260 add_executable(main)261 target_sources(main262 PRIVATE263 main.cpp264 )265 266Building this project is done with the following steps, assuming the files267``main.cpp`` and ``CMakeLists.txt`` are copied in the current directory.268 269.. code-block:: bash270 271 $ mkdir build272 $ cmake -G Ninja -S . -B build -DCMAKE_CXX_COMPILER=<path-to-compiler> -DCMAKE_CXX_FLAGS=-stdlib=libc++273 $ ninja -C build274 $ build/main275 276.. warning:: ``<path-to-compiler>`` should point point to the real binary and277 not to a symlink.278 279If you have questions about modules feel free to ask them in the ``#libcxx``280channel on `LLVM's Discord server <https://discord.gg/jzUbyP26tQ>`__.281 282If you think you've found a bug please it using the `LLVM bug tracker283<https://github.com/llvm/llvm-project/issues>`_. Please make sure the issue284you found is not one of the known bugs or limitations on this page.285