https://github.com/naveen-seth updated https://github.com/llvm/llvm-project/pull/203387
>From 4f8bdd963829b319a6b4e189e86274fdfdfea63f Mon Sep 17 00:00:00 2001 From: Naveen Seth Hanig <[email protected]> Date: Thu, 11 Jun 2026 22:24:23 +0200 Subject: [PATCH] [clang][modules-driver] Add docs & release notes for -fmodules-driver feature This adds documentation and an entry in the release-notes for the new and experimental `-fmodules-driver` feature. --- clang/docs/ReleaseNotes.rst | 6 + clang/docs/StandardCPlusPlusModules.rst | 187 ++++++++++++++++++++++++ 2 files changed, 193 insertions(+) diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst index d8ab080cecbe6..7873ad98fcfba 100644 --- a/clang/docs/ReleaseNotes.rst +++ b/clang/docs/ReleaseNotes.rst @@ -393,6 +393,12 @@ New Compiler Flags a hostname when generates the hashes. Known issues -- does not remap the source file pathes within PCH/PCM files. +- Added experimental ``-fmodules-driver`` option to enable explicit module + builds using C++20 and/or Clang named modules, managed by the Clang driver. + This also supports the C++ standard library modules. +- Added ``-Rmodules-driver`` option to emit remarks for ``-fmodules-driver``, + such as the build graph with module dependencies as a DOT graph. + Deprecated Compiler Flags ------------------------- diff --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst index ec9c4a27a786b..50afcb68d909b 100644 --- a/clang/docs/StandardCPlusPlusModules.rst +++ b/clang/docs/StandardCPlusPlusModules.rst @@ -102,6 +102,8 @@ and the module declaration within a module unit. How to build projects using modules ----------------------------------- +.. _quick-start: + Quick Start ~~~~~~~~~~~ @@ -199,6 +201,15 @@ Then, back on the command line, invoke Clang with: We explain the options in the following sections. +Clang also offers the experimental ``-fmodules-driver`` flag which allows the Clang +driver to determine and manage the order in which modules are built. +See :ref:`Compiling Modules using the Clang Modules-Driver <modules-driver>` +for more details. + +.. code-block:: console + + $ clang++ -std=c++20 -fmodules-driver interface_part.cppm impl_part.cppm M.cppm Impl.cpp User.cpp + How to enable standard C++ modules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -521,6 +532,182 @@ fragment is disabled by default. These checks can be enabled by specifying and you encounter incorrect or missing diagnostics, please report them via the `community issue tracker <https://github.com/llvm/llvm-project/issues/>`_. +.. _modules-driver: + +Compiling Modules using the Clang Modules-Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: The ``-fmodules-driver`` feature is experimental. + +The ``-fmodules-driver`` option enables the Clang driver to automatically discover +module dependencies and manage the entire compilation process for builds using +Standard C++ named modules and/or Clang modules. This includes support for importing +the C++ Standard library modules ``std`` and ``std.compat``. + +Examples +^^^^^^^^ + +Let's use the simple "hello world" example from the +:ref:`Quick Start <quick-start>` section to demonstrate the usage with +``-fmodules-driver``. +Because the C++ Standard library modules can be used in combination with +``-fmodules-driver``, we import ``std`` instead of including ``<iostream>``: + +.. code-block:: c++ + + // HelloWorld.cppm + export module HelloWorld; + import std; + + export void helloWorld() { + std::cout << "Hello World!\n"; + } + + // use.cpp + import HelloWorld; + int main() { + helloWorld(); + } + +Then, invoke Clang like: + +.. code-block:: console + + $ clang++ -std=c++20 -fmodules-driver HelloWorld.cppm use.cpp + +For the more complex example from the Quick Start section, invoke Clang like: + +.. code-block:: console + + $ clang++ -std=c++20 -fmodules-driver interface_part.cppm impl_part.cppm M.cppm Impl.cpp User.cpp + +``-fmodules-driver`` can also be combined with ``-fmodules`` for Clang modules +support: + +.. code-block:: c++ + + // module.modulemap + module HelloUniverse { + header "HelloUniverse.h" + export * + } + + // HelloUniverse.h + #pragma once + #include <iostream> + inline void helloUniverse() { + std::cout << "Hello, Universe!\n"; + } + + // main.cpp + #include "HelloUniverse.h" + int main() { + helloUniverse(); + } + +Then, invoke Clang like: + +.. code-block:: console + + $ clang -fmodules -fmodules-driver -fmodule-map-file=module.modulemap main.cpp + +You can also combine Standard C++ named modules and Clang modules in the same +compilation: + +.. code-block:: c++ + + // module.modulemap + module HelloUniverse { + header "HelloUniverse.h" + export * + } + + // HelloUniverse.h + #pragma once + #include <iostream> + void helloUniverse() { + std::cout << "Hello, Universe!\n"; + } + + // HelloWorld.cppm + export module HelloWorld; + import std; + + export void helloWorld() { + std::cout << "Hello World!\n"; + } + + // main.cpp + #include "HelloUniverse.h" + import HelloWorld; + + int main() { + helloWorld(); + helloUniverse(); + } + +Then, invoke Clang like: + +.. code-block:: console + + $ clang++ -std=c++20 -fmodules -fmodules-driver -fmodule-map-file=module.modulemap HelloWorld.cppm main.cpp + +The build graph for any ``-fmodules-driver`` invocation can be printed in DOT +format using the ``-Rmodules-driver`` remark: + +.. code-block:: console + + $ clang++ -std=c++20 -fmodules -fmodules-driver -Rmodules-driver -fmodule-map-file=module.modulemap HelloWorld.cppm main.cpp + +In the resulting DOT graph, Standard C++ named modules are labeled just as +"Named module". + +.. graphviz:: + + digraph { + rankdir="BT"; + label="Module Dependency Graph"; + node [shape=Mrecord, colorscheme=set23, style=filled]; + + "_Builtin_float-7QLH939LP86YH5HP0PG8FH8FV" [fillcolor=1, label="{ Module type: Clang module | Module name: _Builtin_float | Hash: 7QLH939LP86YH5HP0PG8FH8FV }"]; + "_Builtin_limits-5CX6ZT8UA1ABH32C5FDC0IJ7S" [fillcolor=1, label="{ Module type: Clang module | Module name: _Builtin_limits | Hash: 5CX6ZT8UA1ABH32C5FDC0IJ7S }"]; + "_Builtin_stdarg-F18YUTXMGX9UNHPY8KDJBSQIK" [fillcolor=1, label="{ Module type: Clang module | Module name: _Builtin_stdarg | Hash: F18YUTXMGX9UNHPY8KDJBSQIK }"]; + "_Builtin_stddef-EV2KR1MCSB6QEU876DYYYKWXW" [fillcolor=1, label="{ Module type: Clang module | Module name: _Builtin_stddef | Hash: EV2KR1MCSB6QEU876DYYYKWXW }"]; + "_Builtin_stdint-30RFMCKWE59K7VQQPWKPCVBXW" [fillcolor=1, label="{ Module type: Clang module | Module name: _Builtin_stdint | Hash: 30RFMCKWE59K7VQQPWKPCVBXW }"]; + "_Builtin_inttypes-DUZ97LSOR7LR7AKS6D5AQ6P97" [fillcolor=1, label="{ Module type: Clang module | Module name: _Builtin_inttypes | Hash: DUZ97LSOR7LR7AKS6D5AQ6P97 }"]; + "HelloUniverse-75Y8BHODUL1O3IR5VBHWP0YM" [fillcolor=1, label="{ Module type: Clang module | Module name: HelloUniverse | Hash: 75Y8BHODUL1O3IR5VBHWP0YM }"]; + "std-x86_64-unknown-linux-gnu" [fillcolor=2, label="{ Filename: \<Standard library path\>/std.cppm | Module type: Named module | Module name: std | Triple: x86_64-unknown-linux-gnu }"]; + "HelloWorld-x86_64-unknown-linux-gnu" [fillcolor=2, label="{ Filename: HelloWorld.cppm | Module type: Named module | Module name: HelloWorld | Triple: x86_64-unknown-linux-gnu }"]; + "main.cpp-x86_64-unknown-linux-gnu" [fillcolor=3, label="{ Filename: main.cpp | Triple: x86_64-unknown-linux-gnu }"]; + + "_Builtin_float-7QLH939LP86YH5HP0PG8FH8FV" -> "std-x86_64-unknown-linux-gnu"; + "_Builtin_limits-5CX6ZT8UA1ABH32C5FDC0IJ7S" -> "std-x86_64-unknown-linux-gnu"; + "_Builtin_stdarg-F18YUTXMGX9UNHPY8KDJBSQIK" -> "HelloUniverse-75Y8BHODUL1O3IR5VBHWP0YM"; + "_Builtin_stdarg-F18YUTXMGX9UNHPY8KDJBSQIK" -> "std-x86_64-unknown-linux-gnu"; + "_Builtin_stddef-EV2KR1MCSB6QEU876DYYYKWXW" -> "HelloUniverse-75Y8BHODUL1O3IR5VBHWP0YM"; + "_Builtin_stddef-EV2KR1MCSB6QEU876DYYYKWXW" -> "std-x86_64-unknown-linux-gnu"; + "_Builtin_stdint-30RFMCKWE59K7VQQPWKPCVBXW" -> "_Builtin_inttypes-DUZ97LSOR7LR7AKS6D5AQ6P97"; + "_Builtin_stdint-30RFMCKWE59K7VQQPWKPCVBXW" -> "std-x86_64-unknown-linux-gnu"; + "_Builtin_inttypes-DUZ97LSOR7LR7AKS6D5AQ6P97" -> "std-x86_64-unknown-linux-gnu"; + "HelloUniverse-75Y8BHODUL1O3IR5VBHWP0YM" -> "main.cpp-x86_64-unknown-linux-gnu"; + "std-x86_64-unknown-linux-gnu" -> "HelloWorld-x86_64-unknown-linux-gnu"; + "HelloWorld-x86_64-unknown-linux-gnu" -> "main.cpp-x86_64-unknown-linux-gnu"; + } + +Limitations +^^^^^^^^^^^ + +- Modules are recompiled on each invocation. Caching support is planned for a + future release. +- Standard C++ named modules can import Clang modules, but importing Standard + C++ named modules into Clang modules is not yet supported. +- The ``-o`` option can only be used with a single input file. +- Using ``-fmodules-driver`` with ``-stdlib=libc++`` and ``-fmodules`` currently + doesn't work correctly when importing ``std``. + See `discussion in PR #193312 <https://github.com/llvm/llvm-project/pull/193312>`_. +- Flags such as ``-fsyntax-only`` are not supported when compiling multiple + input files. Using such flags would not be supported for the above examples. + Privacy Issue ------------- _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
