C++20

Testing C++20 Modules: Direct Commands, Then CMake and CTest

The modules guide builds a C++20 module with CMake. This guide tests it. Direct compiler commands come first, because they work on compilers the CMake path cannot use yet. Then the CMake path, with its compiler floor stated plainly: module dependency scanning needs GCC 14 or newer, so the same project configures under GCC 16 and fails at configure under GCC 13. Every command below was run, including the two that fail first.

Written November 6, 2026 · Tested with GCC 13.3.0 · 11 min read

By the end of this guide
  • What you will test
  • The files
  • Leg 1: direct GCC 13
  • Leg 2: direct Clang 18
What you need
The CMake manual states the floor directly. These are the compilers for which CMake supports scanning sources for C++ modules: MSVC toolset 14.34 and newer, LLVM/Clang 16.0 and newer, and GCC 14 and newer.

What you will test

The same small math module from the modules guide: add and sub in a named module, checked by four plain asserts. The test file imports the module, asserts four results, and prints one line when all four pass. No test framework is involved. That is deliberate: the plain assert pattern is the verified floor, and no framework leg was probed for this guide.

Four legs, run in order. The first two use direct compiler commands. The last two use CMake and CTest, and they disagree with each other on purpose: the CMake path has a compiler floor the direct path does not.

Leg Command path Compiler Result
1 Direct g++ GCC 13.3.0 Pass, 4/4
2 Direct clang++ Clang 18.1.3 Pass, 4/4
3 CMake and CTest GCC 13.3.0 Fails at configure
4 CMake and CTest GCC 16.2.0 Pass, CTest 1/1

Tested with CMake 3.28.3 and Ninja 1.13.2 on Ubuntu 24.04.

The files

Three files. The module is two exported functions. The test imports the module and asserts four results. The CMake file is the same shape as the modules guide: a library with a CXX_MODULES file set, an executable linked against it, and one CTest entry.

C++
// math.cppm
export module math;
export int add(int a, int b) { return a + b; }
export int sub(int a, int b) { return a - b; }
C++
// test_math.cpp
import math;
#include <cassert>
#include <cstdio>
int main() {
  assert(add(2, 3) == 5);
  assert(add(-1, 1) == 0);
  assert(sub(5, 3) == 2);
  assert(sub(0, 0) == 0);
  std::printf("modules-test-ok 4/4\n");
  return 0;
}
CMake
# CMakeLists.txt
cmake_minimum_required(VERSION 3.28)
project(modules_test CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_library(math)
target_sources(math PUBLIC FILE_SET CXX_MODULES FILES math.cppm)
add_executable(test_math test_math.cpp)
target_link_libraries(test_math PRIVATE math)
enable_testing()
add_test(NAME math_tests COMMAND test_math)

Leg 1: direct GCC 13

Compile the module first, then the test file, then link. The module compile needs two flags that are easy to drop: -fmodules-ts and -x c++. The -fmodules-ts flag turns on GCC 13 module support. The -x c++ flag tells GCC the .cppm file is C++ source. Both flags are in every command below because the commands fail without them.

Terminal
$ g++ -std=c++20 -fmodules-ts -x c++ -c math.cppm -o math.o
$ g++ -std=c++20 -fmodules-ts -c test_math.cpp -o test_math.o
$ g++ math.o test_math.o -o test_math
$ ./test_math
modules-test-ok 4/4

Every step returns 0. The module compile also writes gcm.cache/math.gcm, the compiled module interface GCC produces as a side effect. That file is what the test compile reads when it sees import math;.

The trap: bare g++ -c math.cppm silently produces nothing

Run the module compile without -x c++ and GCC accepts it, returns 0, and produces no object file and no module interface:

Terminal
$ g++ -std=c++20 -fmodules-ts -c math.cppm -o math.o
g++: warning: math.cppm: linker input file unused because linking not done
$ ls
math.cppm  test_math.cpp

The warning is the only sign. There is no error and no output file. The failure shows up one step later, when the test compile cannot find the module interface:

Output
In module imported at test_math.cpp:1:1:
math: error: failed to read compiled module: No such file or directory
math: note: compiled module file is 'gcm.cache/math.gcm'
math: note: imports must be built before being imported

A return code of 0 does not mean the compile did anything. If the module step produces no gcm.cache directory, the -x c++ flag is missing.

Leg 2: direct Clang 18

Clang's module flow has two steps, not one. First precompile the module interface to a .pcm file. Then compile the module object and the test file with -fmodule-file= pointing at that file. The flag takes the form -fmodule-file=math=math.pcm: the module name, then the file.

Terminal
$ clang++ -std=c++20 --precompile math.cppm -o math.pcm
$ clang++ -std=c++20 -fmodule-file=math=math.pcm -c math.cppm -o math.o
$ clang++ -std=c++20 -fmodule-file=math=math.pcm -c test_math.cpp -o test_math.o
$ clang++ math.o test_math.o -o test_math
$ ./test_math
modules-test-ok 4/4

Every step returns 0. The precompile step produces the .pcm file. The second step compiles the module itself into an object file. The third step compiles the test file against the precompiled interface. The -fmodule-file= flag is needed on both compiles: without it, the compiler has no module interface to read.

The trap: a single-step Clang compile leaves the import unanswered

Compile the module with a plain -c, then compile the test file, and the import fails:

Terminal
$ clang++ -std=c++20 -c math.cppm -o math.o
$ clang++ -std=c++20 -c test_math.cpp -o test_math.o
test_math.cpp:1:8: fatal error: module 'math' not found
    1 | import math;
      | ~~~~~~~^~~~
1 error generated.

The first command returns 0, same as the GCC trap above. A plain -c on the module file does not produce a usable module interface, so the importing file has nothing to import. The fix is the two-step flow: --precompile first, then -fmodule-file= on every compile that touches the module.

This leg used Clang 18.1.3 with the system libstdc++ 13. That pairing matters for the last section of this guide, where the module claim and the standard library claim come apart.

Leg 3: CMake with GCC 13 fails at configure

The same three files, driven by CMake. Configure with the system GCC:

Terminal
$ cmake -S . -B . -G Ninja -DCMAKE_CXX_COMPILER=g++ -DCMAKE_MAKE_PROGRAM=/home/user/ninja-venv/bin/ninja
-- The CXX compiler identification is GNU 13.3.0
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/g++ - skipped
-- Detecting CXX compile features - done
-- Configuring done (0.2s)
CMake Error in CMakeLists.txt:
  The target named "math" has C++ sources that may use modules, but the
  compiler does not provide a way to discover the import graph dependencies.
  See the cmake-cxxmodules(7) manual for details.  Use the
  CMAKE_CXX_SCAN_FOR_MODULES variable to enable or disable scanning.

-- Generating done (0.0s)
CMake Generate step failed.  Build files cannot be regenerated correctly.

Configure returns 1. There is no build to run: no build.ninja file is written, so cmake --build . fails and CTest reports the test as not run. The error is the whole diagnosis. CMake needs the compiler to scan sources for module dependencies before it can order the build, and GCC 13 provides no way to do that. The CMake manual for C++ modules explains the scanning design: the compiler scans each source, CMake collates the results into ordering constraints, and the build tool updates the build graph from them. Without a compiler that can scan, there is nothing to collate.

This is a configure failure, not a compile failure. Nothing in the module or the test is wrong. The same files pass under direct commands on the same compiler, in leg 1. The CMake path asks the compiler for something extra, and GCC 13 cannot supply it.

Leg 4: CMake with GCC 16 passes

Same project, same CMake file, one change: the compiler. Point CMake at GCC 16.2.0:

Terminal
$ cmake -S . -B cmake-build16 -G Ninja -DCMAKE_CXX_COMPILER=/home/user/gcc16/usr/bin/g++-16 -DCMAKE_MAKE_PROGRAM=/home/user/ninja-venv/bin/ninja
-- The CXX compiler identification is GNU 16.2.0
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /home/user/gcc16/usr/bin/g++-16 - skipped
-- Detecting CXX compile features - done
-- Configuring done (0.2s)
-- Generating done (0.0s)
-- Build files have been written to: /home/user/veldica-probes/modules-test/cmake-build16

Configure returns 0. The build shows the scanning steps in its output:

Terminal
$ cmake --build cmake-build16
[1/8] Scanning /home/user/veldica-probes/modules-test/cmake-build16/math.cppm for CXX dependencies
[2/8] Generating CXX dyndep file CMakeFiles/math.dir/CXX.dd
[3/8] Scanning /home/user/veldica-probes/modules-test/cmake-build16/test_math.cpp for CXX dependencies
[4/8] Generating CXX dyndep file CMakeFiles/test_math.dir/CXX.dd
[5/8] Building CXX object CMakeFiles/math.dir/math.cppm.o
[6/8] Building CXX object CMakeFiles/test_math.dir/test_math.cpp.o
[7/8] Linking CXX static library libmath.a
[8/8] Linking CXX executable test_math

Build returns 0. Then CTest:

Terminal
$ ctest --test-dir cmake-build16 --output-on-failure
Test project /home/user/veldica-probes/modules-test/cmake-build16
    Start 1: math_tests
1/1 Test #1: math_tests .......................   Passed    0.00 sec

100% tests passed, 0 tests failed out of 1

Total Test time (real) =   0.00 sec

CTest returns 0 with 1/1 passed. One detail worth knowing before you read that output: CTest does not echo the test binary's stdout on a pass. The modules-test-ok 4/4 line never appears in the CTest output above. Use --output-on-failure as shown, or -V for verbose output, when you want to see what the test printed.

The compiler floor

The CMake manual states the floor directly. These are the compilers for which CMake supports scanning sources for C++ modules: MSVC toolset 14.34 and newer, LLVM/Clang 16.0 and newer, and GCC 14 and newer. The Ninja generator is the one used here; the manual also requires Ninja 1.11 or newer.

Compiler Manual floor Verified in this guide
GCC 14 and newer 16.2.0 passes; 13.3.0 fails at configure
Clang 16.0 and newer Direct commands only, 18.1.3; CMake path not run
MSVC Toolset 14.34 and newer Not tested; no MSVC toolchain on this box

Read the table carefully. The floor belongs to the CMake path, not to modules. Direct commands test a module fine on GCC 13 and Clang 18, as legs 1 and 2 show. It is the FILE_SET CXX_MODULES plus CTest path that needs a compiler with module dependency scanning. GCC 14 and 15 were not installed, so the floor is verified here only for GCC 16.2.0 on the passing side and GCC 13.3.0 on the failing side. The GCC 14 floor itself comes from the manual, not from a run.

Two separate claims

"Modules work" and "a standard library feature works" are separate claims, and a compiler matrix should keep them separate. An earlier probe found the split in the other direction: Clang 18 with libstdc++ 13 can test modules, as leg 2 shows, but the same pairing cannot compile <expected>. That failure is a headers and concepts failure, not a modules failure. A guide that reports "Clang 18 cannot do modules" from the <expected> failure would be wrong, and a guide that reports "Clang 18 does modules" as if every standard library feature followed would be wrong too. Name the standard library pairing next to the compiler version whenever a claim depends on it.

The same discipline applies to the CMake path. "CMake supports modules" is true for a given compiler and generator pair, not in general. The manual lists Ninja and the Visual Studio generators as the ones that support scanning, and it lists header units as unsupported for all generators. A claim about the CMake path should name the compiler, the generator, and the CMake version, as the legs above do.

Frequently asked questions

Why plain asserts and no test framework?

No framework leg was probed. Catch2 and GoogleTest were not installed, and importing a test framework as a module was not attempted. The plain assert pattern is the verified floor: four asserts, one printed line, exit code 0 on pass and a failed assert on failure. A framework leg would need the framework fetched and its module import tested first.

Can I use import std; instead of including headers?

Not from this guide. The manual limits import std to specific toolchain and standard library combinations, and it sits behind an experimental gate (CMAKE_EXPERIMENTAL_CXX_IMPORT_STD). Keep the headers and the import math; line as shown.

Why does CTest not show my test output?

CTest reports pass or fail by default and keeps the test binary's stdout to itself on a pass. Pass --output-on-failure to see output when a test fails, or -V to see it always. The test binary still prints its line when run directly.

Does this work with header units?

No. The CMake manual lists header units as unsupported for all generators. This guide uses named modules only.

Where does this sit?

The modules guide, C++20 Modules with CMake 3.28 and Ninja, builds the module project this guide tests. The presets guide, CMakePresets and vcpkg on a Real C++20 Modules Project, carries the same project into dependency management. This guide answers the testing question: how to run the module's tests with direct commands and with CMake.

Sources

  • Kitware, import CMake; C++20 Modules, the compilation order problem for modules, the compiled module interface as a build side effect, and the fact that CMake's own module tests cover module builds rather than user tests of modules.
  • CMake, cmake-cxxmodules(7), the scanning strategy, the compiler support table with the GCC 14 and newer floor, the Ninja generator requirement, the import std limits, and the header units limitation.

Keep Exploring