C++20 Modules and import std
xclang builds C++20 named modules and the standard library modules (import std and import std.compat) in CMake, Bazel and plain clang++, for the host or any cross target, without CMake's experimental switches. Each module interface compiles to a precompiled module file (BMI, .pcm in clang), which every importer reads.
Usage
The example in examples/modules defines a module math with a partition math:ops and an executable that imports both math and std. The CMake and plain clang++ commands below run in that directory inside pixi shell after pixi install, which places xclang's bin/ first in PATH.
math-ops.cppm is the module partition:
export module math:ops;
import std;
export int perimeter(std::span<const int> sides) {
return std::accumulate(sides.begin(), sides.end(), 0);
}math.cppm is the primary module interface, which re-exports :ops:
export module math;
export import :ops;
import std;
export std::string describe(std::string_view name, std::span<const int> sides) {
return std::format("{}: {} sides, perimeter {}", name, sides.size(), perimeter(sides));
}main.cpp imports both modules:
import std;
import math;
int main() {
std::vector<int> triangle{3, 4, 5};
std::println("{}", describe("triangle", triangle));
}Every build below produces a program with this output:
triangle: 3 sides, perimeter 12CMake
xclang::std is a static library containing the std and std.compat modules of libc++, compiled from the module sources named in the compiler's module manifest for the active target. Link xclang::std to use import std and import std.compat, and list your own module interfaces in a FILE_SET CXX_MODULES. cmake_minimum_required(VERSION 3.28) enables clang-scan-deps module scanning on C++20 and later targets (CMP0155):
cmake_minimum_required(VERSION 3.28)
project(shapes LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_EXTENSIONS OFF)
find_package(xclang REQUIRED CONFIG)
add_library(math STATIC)
target_sources(math PUBLIC FILE_SET CXX_MODULES FILES math.cppm math-ops.cppm)
target_link_libraries(math PUBLIC xclang::std)
add_executable(shapes main.cpp)
target_link_libraries(shapes PRIVATE math xclang::std)cmake -G Ninja -B build -DCMAKE_CXX_COMPILER=clang++
cmake --build build
./build/shapesBecause clang rejects a module file compiled with different language options than its importer (Behavior):
xclang::stdis compiled with the settings of the directory that calledfind_package(xclang), evaluated at the end of that directory'sCMakeLists.txt:CMAKE_CXX_STANDARD,CMAKE_CXX_EXTENSIONS,CMAKE_CXX_FLAGSandadd_compile_options(). Set language options project-wide rather than on individual CMake targets.xclang::stdis C++23, or theCMAKE_CXX_STANDARDof that directory if it is 20 or later, and asks the same standard of its importers.When a target needs different language options, create a separate
stdmodule target withxclang_add_std(<name>)and attachPUBLICcompile options to it so both thatstdlibrary and its importers use them:cmakexclang_add_std(std_noexcept) target_compile_options(std_noexcept PUBLIC -fno-exceptions)
To cross-compile for another target, pass the toolchain file and XCLANG_TARGET (CMake); xclang::std is then built for that target as well:
XCLANG=$PWD/.pixi/envs/default/opt/xclang
cmake -G Ninja -B build-x86_64-w64-mingw32 --toolchain "$XCLANG/lib/cmake/xclang/toolchain.cmake" \
-DXCLANG_TARGET=x86_64-w64-mingw32
cmake --build build-x86_64-w64-mingw32Bazel
@xclang//bazel:std provides the std and std.compat modules. List a library's module interfaces in module_interfaces, and enable features = ["cpp_modules"] on every target that compiles or imports a C++20 module:
load("@rules_cc//cc:cc_binary.bzl", "cc_binary")
load("@rules_cc//cc:cc_library.bzl", "cc_library")
cc_library(
name = "math",
features = ["cpp_modules"],
module_interfaces = [
"math.cppm",
"math-ops.cppm",
],
deps = ["@xclang//bazel:std"],
)
cc_binary(
name = "shapes",
srcs = ["main.cpp"],
features = ["cpp_modules"],
deps = [
":math",
"@xclang//bazel:std",
],
)MODULE.bazel and .bazelrc
module(name = "shapes")
bazel_dep(name = "rules_cc", version = "0.2.25")
bazel_dep(name = "xclang", version = "23.1.2.8")The .bazelrc adds the registry (Bazel), --experimental_cpp_modules, and the --cxxopt flags shared by @xclang//bazel:std and its importers:
common --registry=https://bazel.clice.io/
common --registry=https://bcr.bazel.build/
common --enable_platform_specific_config
# The C++ toolchain is xclang's; rules_cc's detection of another is off.
common --repo_env=BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1
# import std: libc++'s modules are built with these options, and so are
# their importers.
common --cxxopt=-std=c++23 --host_cxxopt=-std=c++23
common --experimental_cpp_modules
common:windows --enable_runfiles@xclang//bazel:std is compiled with the --cxxopt of the build. Because clang requires matching language options between a module file and its importers (Behavior), put language flags such as -std=c++23, -fno-exceptions and -fno-rtti in --cxxopt rather than in the copts of a single target.
Run the program on the host, or pass --platforms to cross-compile it (here for Windows x64, writing bazel-bin/shapes.exe):
bazel run //:shapes
bazel build --platforms=@xclang//platforms:x86_64-w64-mingw32 //:shapesPlain Clang
Each module interface compiles in one step to both an object file and a .pcm module file (-fmodule-output=<file>.pcm). Pass -fprebuilt-module-path=. so importers find std.pcm, math.pcm, and math-ops.pcm for the partition math:ops:
std=$(dirname "$(clang++ -print-library-module-manifest-path)")/../share/libc++/v1/std.cppm
clang++ -std=c++23 -O2 -Wno-reserved-module-identifier -c "$std" -fmodule-output=std.pcm -o std.o
clang++ -std=c++23 -O2 -fprebuilt-module-path=. -c math-ops.cppm -fmodule-output=math-ops.pcm -o math-ops.o
clang++ -std=c++23 -O2 -fprebuilt-module-path=. -c math.cppm -fmodule-output=math.pcm -o math.o
clang++ -std=c++23 -O2 -fprebuilt-module-path=. -c main.cpp -o main.o
clang++ main.o math.o math-ops.o std.o -o shapes
./shapesclang++ -print-library-module-manifest-path prints the path of libc++.modules.json, which records ../share/libc++/v1/std.cppm as the source-path of std. Add --target=<target> to every command, including the manifest lookup, to cross-compile for another target. Because clang searches for libc++.a when printing the manifest path, it reports no path for the MSVC targets (libc++-<arch>.lib); their module source is at $XCLANG/<target>/share/libc++/v1/std.cppm (archive layout).
Options
| CMake | Bazel | Plain Clang | |
|---|---|---|---|
import std and import std.compat | target_link_libraries(<target> PRIVATE xclang::std) | deps = ["@xclang//bazel:std"] | compile std.cppm and std.compat.cppm with -fmodule-output= |
| C++20 modules of a library | target_sources(<lib> PUBLIC FILE_SET CXX_MODULES FILES ...) | module_interfaces = [...], features = ["cpp_modules"] | -fmodule-output=<name>.pcm, -fprebuilt-module-path=<dir> |
Language options of std | directory options where find_package(xclang) was called | the build's --cxxopt | flags passed when compiling std.cppm |
Additional std target with custom options | xclang_add_std(<name>) | ||
| Requirements | CMake 3.28+, Ninja 1.11+, Ninja or Ninja Multi-Config | Bazel 9, rules_cc 0.2.25+, --experimental_cpp_modules |
Full option lists are in the CMake API and the Bazel API.
Behavior
- Dependency scanning: an importer must compile after the
.pcmfiles of the modules it imports. CMake and Bazel runclang-scan-deps, which writes the module dependencies of each source file in the P1689 format. - Matching language options:
clangrejects a.pcmbuilt with different language options than its importer:-std, GNU extensions,-fno-exceptions,-fno-rtti, and other flags that change language semantics. Macros (-D), include paths and optimization levels may differ. Importing astdmodule built with C++23 from a target compiled with-std=c++26fails withC++26 was disabled in precompiled file. stdis built per build: because a precompiled.pcmonly serves importers compiled with matching language options, xclang shipsstd.cppmandstd.compat.cppmas sources and compiles them as a static library target inside each build. When runtimes from source are enabled,xclang::stdand@xclang//bazel:stdcompile against that runtime variant.- No experimental CMake switch: CMake's built-in
import stdis gated behindCMAKE_EXPERIMENTAL_CXX_IMPORT_STD, whose UUID changes across CMake versions.xclang::stdis a regularSTATIClibrary with aCXX_MODULESfile set, so it needs only the module support of CMake 3.28. - Embedded sources in Bazel: a module file embeds its sources (the
modules_embed_all_filesfeature, on by default). An importer compiled with-greads them, and in the sandbox it has the module file but not the source. - No header units: neither CMake nor Bazel builds header units (
import <vector>;).
Build Caches and Modules
A compile cache keyed only on the source file, the compiler command line and #included headers misses imported .pcm files. The command line names module files only by path (in CMake, inside a @<source>.modmap response file). If the cache does not hash the contents of the .pcm files, it returns a stale object file after an imported module interface changes.
xclang's CI runs the CMake compile commands for a module interface and its importer (-fmodule-output=a.pcm, and -fmodule-file=a=a.pcm inside @b.modmap) three times under two ccache versions: the first build, a rebuild, and a rebuild after an exported constant changed from 1 to 2:
| module interface | importer, unchanged | importer, after the interface changed | |
|---|---|---|---|
| ccache 4.13.6 | never cached (unsupported_source_language) | cache hit | cache hit: stale object returned, program returns 1 |
| ccache 4.14.1 | never cached | cache hit | cache miss, recompiled: program returns 2 |
With ccache 4.13 or older, a C++20 module build can silently link stale code. With ccache 4.14 or later, importers are invalidated when .pcm files change, though module interfaces themselves are never cached.
Bazel's action cache hashes every declared input of an action, including the .pcm files an importer reads. Changing a module interface produces a new .pcm and invalidates its importers. Because xclang's Bazel toolchains pass -fmodule-file-home-is-cwd, .pcm files record paths relative to the execution root and can be shared across checkouts and machines through a remote or disk cache.
Platform Notes
With -stdlib=platform (-DXCLANG_STDLIB=platform in CMake, --@xclang//bazel:stdlib=platform in Bazel), xclang::std and @xclang//bazel:std use the platform C++ library's module sources instead of xclang's libc++ (cross-compiling):
- MSVC targets:
xclang::stdand@xclang//bazel:stdcompile Microsoft's STL module sources (std.ixxandstd.compat.ixxfrom the fetched Windows SDK or Visual Studio, with<malloc.h>included before the module onarm64so_allocais not declared twice). - Linux and MinGW targets: in CMake,
xclang::stduses the module manifest reported byclang++ -stdlib=platform -print-library-module-manifest-pathwhen present (such as GCC 15'slibstdc++), andfind_package(xclang)stops if the system C++ library has no manifest. The Bazel module refuses-stdlib=platformfor these targets: their library comes from a sysroot outside the toolchain. - macOS targets: Apple's macOS SDK ships no module manifest or module sources for its
libc++, soimport stdis not available with-stdlib=platform(find_package(xclang)fails in CMake, and@xclang//bazel:stdis marked incompatible in Bazel).
