[libc++][doc] Updates module information.

[mordante]

Adds the std.compat module and add support for CMake 3.28.

[llvmbot]

@llvm/pr-subscribers-libcxx

Author: Mark de Wever (mordante)

Changes

Adds the std.compat module and add support for CMake 3.28.

---

Full diff: https://github.com/llvm/llvm-project/pull/75003.diff

1 Files Affected:

• (modified) libcxx/docs/Modules.rst (+22-17)

diff --git a/libcxx/docs/Modules.rst b/libcxx/docs/Modules.rst
index a16b3694cfae30..5099e6095582cf 100644
--- a/libcxx/docs/Modules.rst
+++ b/libcxx/docs/Modules.rst
@@ -38,8 +38,8 @@ What works
 ~~~~~~~~~~
 
  * Building BMIs
- * Running tests using the ``std`` module
- * Using the ``std`` module in external projects
+ * Running tests using the ``std`` and ``std.compat`` module
+ * Using the ``std``  and ``std.compat`` module in external projects
  * The following "parts disabled" configuration options are supported
 
    * ``LIBCXX_ENABLE_LOCALIZATION``
@@ -65,10 +65,9 @@ Some of the current limitations
  * Requires CMake 3.26 for C++23 support
  * Requires CMake 3.27 for C++26 support
  * Requires Ninja 1.11
- * Requires a recent Clang 17
+ * Requires Clang 17
  * The path to the compiler may not be a symlink, ``clang-scan-deps`` does
    not handle that case properly
- * Only C++23 and C++26 are tested
  * Libc++ is not tested with modules instead of headers
  * The module ``.cppm`` files are not installed
  * Clang supports modules using GNU extensions, but libc++ does not work using
@@ -127,9 +126,13 @@ This is a small sample program that uses the module ``std``. It consists of a
 
 .. code-block:: cpp
 
-  import std;
+  import std; // When importing std.compat it's not needed to import std.
+  import std.compat;
 
-  int main() { std::cout << "Hello modular world\n"; }
+  int main() {
+    std::cout << "Hello modular world\n";
+    ::printf("Hello compat modular world\n");
+  }
 
 .. code-block:: cmake
 
@@ -142,7 +145,6 @@ This is a small sample program that uses the module ``std``. It consists of a
   # 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.
@@ -153,12 +155,16 @@ This is a small sample program that uses the module ``std``. It consists of a
   #
 
   # 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")
+  if(CMAKE_VERSION VERSION_LESS "3.28.0")
+    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)
   else()
-    set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "aa1f7df0-828a-4fcd-9afc-2dc80491aca7")
+    cmake_policy(VERSION 3.28)
   endif()
-  set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP 1)
 
   #
   # Import the modules from libc++
@@ -169,18 +175,16 @@ This is a small sample program that uses the module ``std``. It consists of a
     std
     URL "file://${LIBCXX_BUILD}/modules/c++/v1/"
     DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+    SYSTEM
   )
-  FetchContent_GetProperties(std)
-  if(NOT std_POPULATED)
-    FetchContent_Populate(std)
-    add_subdirectory(${std_SOURCE_DIR} ${std_BINARY_DIR} EXCLUDE_FROM_ALL)
-  endif()
+  FetchContent_MakeAvailable(std)
 
   #
   # 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>:-fprebuilt-module-path=${CMAKE_BINARY_DIR}/_deps/std-build/CMakeFiles/std.compat.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>.
@@ -194,8 +198,9 @@ This is a small sample program that uses the module ``std``. It consists of a
   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
+  # Linking against the standard c++ library is required for CMake to get the proper dependencies.
   link_libraries(std c++)
+  link_libraries(std.compat c++)
 
   #
   # Add the project