diff options
| -rw-r--r-- | libcxx/docs/Modules.rst | 77 |
1 files changed, 70 insertions, 7 deletions
diff --git a/libcxx/docs/Modules.rst b/libcxx/docs/Modules.rst index 5b027ed..352a198 100644 --- a/libcxx/docs/Modules.rst +++ b/libcxx/docs/Modules.rst @@ -69,8 +69,6 @@ Some of the current limitations * The path to the compiler may not be a symlink, ``clang-scan-deps`` does not handle that case properly * Libc++ is not tested with modules instead of headers - * 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 @@ -105,9 +103,17 @@ Users need to be able to build their own BMI files. 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. +Currently there are two ways to build modules + + * Use a local build of modules from the build directory. This requires + Clang 17 or later and CMake 3.26 or later. + + * Use the installed modules. This requires Clang 18.1.2 or later and + a recent build of CMake. The CMake changes will be part of CMake 3.30. This + method requires you or your distribution to enable module installation. + +Using the local build +~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -136,7 +142,7 @@ This is a small sample program that uses the module ``std``. It consists of a .. code-block:: cmake cmake_minimum_required(VERSION 3.26.0 FATAL_ERROR) - project("module" + project("example" LANGUAGES CXX ) @@ -146,7 +152,6 @@ This is a small sample program that uses the module ``std``. It consists of a set(CMAKE_CXX_STANDARD 23) set(CMAKE_CXX_STANDARD_REQUIRED YES) - # Libc++ doesn't support compiler extensions for modules. set(CMAKE_CXX_EXTENSIONS OFF) # @@ -214,6 +219,64 @@ Building this project is done with the following steps, assuming the files ``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]`` + +Using the installed modules +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CMake has added experimental support for importing the Standard modules. This +is available in the current nightly builds and will be part of the 3.30 +release. Currently CMake only supports importing the Standard modules in C++23 +and later. Enabling this for C++20 is on the TODO list of the CMake +developers. + +The example uses the same ``main.cpp`` as above. It uses the following +``CMakeLists.txt``: + +.. code-block:: cmake + + # This requires a recent nightly build. + # This will be part of CMake 3.30.0. + cmake_minimum_required(VERSION 3.29.0 FATAL_ERROR) + + # Enables the Standard module support. This needs to be done + # before selecting the languages. + set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "0e5b6991-d74f-4b3d-a41c-cf096e0b2508") + set(CMAKE_CXX_MODULE_STD ON) + + project("example" + LANGUAGES CXX + ) + + # + # Set language version used + # + + set(CMAKE_CXX_STANDARD 23) + set(CMAKE_CXX_STANDARD_REQUIRED YES) + # Currently CMake requires extensions enabled when using import std. + # https://gitlab.kitware.com/cmake/cmake/-/issues/25916 + # https://gitlab.kitware.com/cmake/cmake/-/issues/25539 + set(CMAKE_CXX_EXTENSIONS ON) + + 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> -DCMAKE_CXX_FLAGS=-stdlib=libc++ + $ ninja -C build + $ build/main + +.. warning:: ``<path-to-compiler>`` should point point to the real binary and + not to a symlink. + If you have questions about modules feel free to ask them in the ``#libcxx`` channel on `LLVM's Discord server <https://discord.gg/jzUbyP26tQ>`__. |