[libcxx-commits] [libcxx] [libc++][doc] Use installed std modules in external projects. (PR #80601)

[Mark de Wever via libcxx-commits]

================
@@ -225,6 +231,137 @@ Building this project is done with the following steps, assuming the files
 .. note:: The ``std`` dependencies of ``std.compat`` is not always resolved when
           building the ``std`` target using multiple jobs.
 
+This is another small sample program that uses the module ``std`` from
+installation directory. It consists of a ``CMakeLists.txt``, an
+``std.cmake``, and a ``main.cpp`` file. The ``main.cpp`` is the same as
+the previous example.
+
+.. code-block:: cmake
+
+  # CMakeLists.txt
+  cmake_minimum_required(VERSION 3.26.0 FATAL_ERROR)
+  project("module"
+    LANGUAGES CXX
+  )
+
+  #
+  # Set language version used
+  #
+
+  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.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()
+    cmake_policy(VERSION 3.28)
+  endif()
+
+  #
+  # Import the modules from libc++
+  #
+  include(std.cmake)
+
+  add_executable(main main.cpp)
+
+.. code-block:: cmake
+
+  # std.cmake
+  include(FetchContent)
+  FetchContent_Declare(
+    std_module
+    URL "file://${LIBCXX_INSTALLED_DIR}/share/libc++/v1"
+    DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+    SYSTEM
+  )
+
+  if (NOT std_module_POPULATED)
+    FetchContent_Populate(std_module)
+  endif()
----------------
mordante wrote:

This is the preferred way for CMake to do this.
```suggestion
  FetchContent_MakeAvailable(std_module)
```

https://github.com/llvm/llvm-project/pull/80601