[libcxx-commits] [libcxx] [libc++][doc] Updates module build instructions. (PR #89413)

Mark de Wever via libcxx-commits libcxx-commits at lists.llvm.org
Tue Apr 23 10:54:02 PDT 2024 

https://github.com/mordante updated https://github.com/llvm/llvm-project/pull/89413

>From 1a5d1632cbfa3dfacea27497a85fa5144502a35d Mon Sep 17 00:00:00 2001
From: Mark de Wever <koraq at xs4all.nl>
Date: Fri, 19 Apr 2024 18:24:31 +0200
Subject: [PATCH 1/3] [lib++][doc] Updates module build instructions.

CMake has landed experimental support for using the Standard modules. This
will be part of the CMake 3.30 release. This updates the build
instructions to use modules with CMake.

The changes have been tested locally.
---
 libcxx/docs/Modules.rst | 73 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 67 insertions(+), 6 deletions(-)

diff --git a/libcxx/docs/Modules.rst b/libcxx/docs/Modules.rst
index 5b027ed1bd0729..fd37394725e1ea 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 CMake 3.30. This
+    method requires you or your distribution to enable module installation.
+
+Using the local build
+~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: bash
 
@@ -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,62 @@ 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("module"
+    LANGUAGES CXX
+  )
+
+  #
+  # Set language version used
+  #
+
+  set(CMAKE_CXX_STANDARD 23)
+  set(CMAKE_CXX_STANDARD_REQUIRED YES)
+  # This seems to be required to be on.
+  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>`__.
 

>From 829bd90909550f5a9838dbf3b54f50d0bab658e0 Mon Sep 17 00:00:00 2001
From: Mark de Wever <zar-rpg at xs4all.nl>
Date: Sun, 21 Apr 2024 11:43:34 +0200
Subject: [PATCH 2/3] Update libcxx/docs/Modules.rst

Co-authored-by: Will Hawkins <whh8b at obs.cr>
---
 libcxx/docs/Modules.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libcxx/docs/Modules.rst b/libcxx/docs/Modules.rst
index fd37394725e1ea..5c2d16ffbd4f54 100644
--- a/libcxx/docs/Modules.rst
+++ b/libcxx/docs/Modules.rst
@@ -109,7 +109,7 @@ Currently there are two ways to build modules
     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 CMake 3.30. This
+    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

>From e5aae311a2e6ce08fdae28819c91a3300eb18d1e Mon Sep 17 00:00:00 2001
From: Mark de Wever <koraq at xs4all.nl>
Date: Sun, 21 Apr 2024 11:48:51 +0200
Subject: [PATCH 3/3] Updates patch

- Addresses review comment.
- Updates CMake status regarding disabling compiler extensions.
---
 libcxx/docs/Modules.rst | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/libcxx/docs/Modules.rst b/libcxx/docs/Modules.rst
index 5c2d16ffbd4f54..352a198f3774d4 100644
--- a/libcxx/docs/Modules.rst
+++ b/libcxx/docs/Modules.rst
@@ -142,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
   )
 
@@ -223,14 +223,14 @@ Building this project is done with the following steps, assuming the files
 Using the installed modules
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-CMake has added experimental support for importing the standard modules. This
+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``
+``CMakeLists.txt``:
 
 .. code-block:: cmake
 
@@ -243,7 +243,7 @@ The example uses the same ``main.cpp`` as above. It uses the following
   set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")
   set(CMAKE_CXX_MODULE_STD ON)
 
-  project("module"
+  project("example"
     LANGUAGES CXX
   )
 
@@ -253,7 +253,9 @@ The example uses the same ``main.cpp`` as above. It uses the following
 
   set(CMAKE_CXX_STANDARD 23)
   set(CMAKE_CXX_STANDARD_REQUIRED YES)
-  # This seems to be required to be on.
+  # 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)

More information about the libcxx-commits mailing list