Installing a Header-Only C++20 Modules Library with CMake
A header-only library has no compiled objects, so the natural shape is an INTERFACE target. With C++20 modules that shape fails: CMake rejects an INTERFACE library carrying a CXX_MODULES file set, and on CMake 3.28.3 the failure is an internal error, not a clean diagnostic. This guide shows that failure, then installs the same module as a static library built from the module file alone, and consumes it from a separate project with find_package. Every command below was run, and every error quoted is a real one.
Written November 6, 2026 · Tested with CMake 3.28.3 · 10 min read
- The module
- The INTERFACE attempt, and what it returns
- The shape that works: a static library from the module file alone
- The consumer
What you will build
A small math module with two exported functions, add and sub, installed as a library that a second project consumes through find_package and import math;. The consumer prints a confirmation line and exits zero. The library itself is a static library built from the module interface file alone: there is no .cpp file, and the archive holds only the module initializer object. The module interface file is what gets installed and rebuilt by the consumer.
The files:
| File | Role |
| math.cppm | Primary module interface unit for math |
| main.cpp | The consumer program, imports math |
| CMakeLists.txt | Library, install rules, and export (provider side) |
| mathConfig.cmake.in | Package config template for find_package |
| test_math.cpp | The provider-side test program, imports math |
| CMakeLists.txt | Consumer project, separate directory |
Tested with CMake 3.28.3 and Ninja 1.13.2 on Ubuntu 24.04. The INTERFACE failure was run with GCC 13.3.0. The install and the consumer were run with GCC 16.2.0, because the CMake module path needs GCC 14 or newer for dependency scanning. The cross-compiler check was run with Clang 18.1.3. MSVC was not available for this guide.
The module
export module math;
export int add(int a, int b) { return a + b; }
export int sub(int a, int b) { return a - b; }
The consumer:
import math;
#include <cassert>
#include <cstdio>
int main() {
assert(add(2, 3) == 5);
assert(sub(5, 3) == 2);
std::printf("headeronly-consumer-ok 2/2\n");
return 0;
}
The INTERFACE attempt, and what it returns
A header-only library in CMake is normally an INTERFACE target, so the first attempt is the obvious one:
cmake_minimum_required(VERSION 3.28)
project(headeronly_test CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_library(math INTERFACE)
target_compile_features(math INTERFACE cxx_std_20)
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)
Configure fails. The output is two errors at once, and the first one is not a normal diagnostic:
CMake Internal Error (please report a bug) in CMakeLists.txt:
cmGeneratorTarget::GetOutputInfo called for math which has type
INTERFACE_LIBRARY
A stack trace follows, then a second error:
CMake Error in CMakeLists.txt:
The target named "math" has C++ sources that use modules, but does not
include "cxx_std_20" (or newer) among its `target_compile_features`; no C++
standard found.
That second error is misleading here: the CMakeLists.txt above declares cxx_std_20 on the target, and the same pair of errors appears with and without that line. The rejection is about the target type, not the standard. An INTERFACE library has no build output for CMake to attach the module compilation to, and CMake 3.28.3 answers with an internal error instead of a clean message.
This is the same conclusion the CMake Discourse thread on header-only libraries and C++20 modules reaches: CMake currently rejects an INTERFACE file set of type CXX_MODULES. The reason given there is the module initializer symbol. Every module has one, it must be provided exactly once so that global initializers run in the right order, and providing it in a library is the reliable way to do that. The thread has no posted workaround, and the question is still open.
The shape that works: a static library from the module file alone
The working shape keeps the header-only distribution idea but drops the INTERFACE target. Build a static library whose only source is the module interface unit:
cmake_minimum_required(VERSION 3.28)
project(headeronly_static3 CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
include(CMakePackageConfigHelpers)
add_library(math STATIC)
target_compile_features(math PUBLIC cxx_std_20)
target_sources(math PUBLIC FILE_SET CXX_MODULES FILES math.cppm)
install(TARGETS math EXPORT mathTargets
FILE_SET CXX_MODULES DESTINATION include/math)
install(EXPORT mathTargets FILE mathTargets.cmake
NAMESPACE math:: DESTINATION lib/cmake/math)
configure_package_config_file(
${CMAKE_CURRENT_SOURCE_DIR}/mathConfig.cmake.in
${CMAKE_CURRENT_BINARY_DIR}/mathConfig.cmake
INSTALL_DESTINATION lib/cmake/math)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/mathConfig.cmake
DESTINATION lib/cmake/math)
add_executable(test_math test_math.cpp)
target_link_libraries(test_math PRIVATE math)
Two lines in that file are doing work that is easy to miss, and both are covered in the traps section below: target_compile_features(math PUBLIC cxx_std_20) and the mathConfig.cmake generation. Leave either one out and the consumer fails.
Configure, build, and run in the provider project:
-- Configuring done (0.3s)
-- Generating done (0.0s)
[1/8] Scanning math.cppm for CXX dependencies
[2/8] Generating CXX dyndep file CMakeFiles/math.dir/CXX.dd
[3/8] Building CXX object CMakeFiles/math.dir/math.cppm.o
[4/8] Scanning test_math.cpp for CXX dependencies
[5/8] Generating CXX dyndep file CMakeFiles/test_math.dir/CXX.dd
[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
headeronly-test-ok 2/2
Install it:
-- Installing: prefix/lib/libmath.a
-- Installing: prefix/include/math/math.cppm
-- Installing: prefix/lib/cmake/math/mathTargets.cmake
-- Installing: prefix/lib/cmake/math/mathTargets-noconfig.cmake
-- Installing: prefix/lib/cmake/math/mathConfig.cmake
Five files land in the prefix. The archive holds only the module initializer object. The interface file, math.cppm, is installed as source under include/math/, and the consumer rebuilds the module interface from it. Nothing binary about the module crosses the install boundary.
The package config template is three lines:
@PACKAGE_INIT@
include("${CMAKE_CURRENT_LIST_DIR}/mathTargets.cmake")
check_required_components(math)
The consumer
A separate project, pointed at the install prefix:
cmake_minimum_required(VERSION 3.28)
project(headeronly_consumer CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(math REQUIRED)
add_executable(consumer main.cpp)
target_link_libraries(consumer PRIVATE math::math)
Configure, build, and run:
-- Configuring done (0.3s)
-- Generating done (0.0s)
headeronly-consumer-ok 2/2
That is the whole round trip: the provider builds a static library from one module file, installs the module source with the export, and a separate project finds it and imports the module. The consumer never sees the provider's build directory.
Two traps, both measured
install(EXPORT ...) alone does not make find_package work. The first version of the provider file installed the export but generated no config file. The consumer then failed at configure with:CMake Error at CMakeLists.txt:5 (find_package):
By not providing "Findmath.cmake" in CMAKE_MODULE_PATH this project has
asked CMake to find a package configuration file provided by "math", but
CMake did not find one.
Could not find a package configuration file provided by "math" with any of
the following names:
mathConfig.cmake
math-config.cmake
install(EXPORT ...) writes only mathTargets.cmake. find_package looks for mathConfig.cmake (or math-config.cmake), so the provider must generate and install one. The configure_package_config_file call in the working listing does that.
Trap 2: the C++ standard must be declared on the library, not just in the project. The provider sets CMAKE_CXX_STANDARD 20 for its own build, but that setting does not travel through the export. With the standard missing from the export, the consumer failed at the generate step with:
CMake Error in CMakeLists.txt:
The target named "math__math@synth_a26dacc80753" has C++ sources that use
modules, but does not include "cxx_std_20" (or newer) among its
`target_compile_features`; no C++ standard found.
The math__math@synth_... target is the synthesized target CMake creates for the imported module. Declaring the standard on the consumer's own executable did not fix it either; the requirement has to come from the library. Adding target_compile_features(math PUBLIC cxx_std_20) to the provider fixed the consumer, and the export file then carries the requirement: cxx_std_20 appears in the installed mathTargets.cmake. Declare the standard with target_compile_features on every module library you export. A project-wide CMAKE_CXX_STANDARD is not a substitute.
Do not ship the BMI
It is tempting to install the compiled module interface alongside the library and skip the consumer rebuild. Do not. Module interfaces are compiler-specific, and a BMI built by one compiler is not readable by another. A module compiled with GCC 16.2.0 produces gcm.cache/math.gcm; Clang 18.1.3 asked to consume it fails with:
test_math.cpp:1:1: fatal error: file 'gcm.cache/math.gcm' is not a valid precompiled module file: file too small to contain AST file magic
1 | import math;
| ^
1 error generated.
The CMake module documentation states the same boundary from the other side for the Visual Studio generators: exporting or installing BMI or module information is not supported there, and CMake's install support for module targets installs the interface sources, not BMIs. Ship the .cppm source and let each consumer build its own interface. That is also why the static-library shape costs so little: the archive is only the initializer object, and the real work — compiling the interface — happens in the consumer, with its own compiler and flags.
What breaks, and the fix
| Error | Cause | Fix |
| CMake Internal Error ... GetOutputInfo called for math which has type INTERFACE_LIBRARY | INTERFACE library with a CXX_MODULES file set, CMake 3.28.3 | Use a static library built from the module file alone |
| The target named "math" has C++ sources that use modules, but does not include "cxx_std_20" on an INTERFACE target | Same rejection, reported as a missing standard | Same fix; the standard line is not the cause here |
| Could not find a package configuration file provided by "math" | install(EXPORT ...) writes targets only, no config file | Generate and install mathConfig.cmake with configure_package_config_file |
| The target named "math__math@synth_..." has C++ sources that use modules, but does not include "cxx_std_20" | Exported library never declared the standard | target_compile_features(math PUBLIC cxx_std_20) on the provider library |
| file 'gcm.cache/math.gcm' is not a valid precompiled module file | GCC BMI handed to Clang | Install the .cppm source, never the BMI |
Frequently asked questions
Can the consumer rebuild with different flags than the provider?
Yes, and that is the point of shipping the module source. The consumer compiles math.cppm with its own compiler, standard level, and optimization flags. The provider's archive contributes only the initializer object. Keep the module's exported interface free of anything that depends on the provider's flags.
Does the static archive matter at all, then?
Yes. It carries the module initializer symbol, which must exist exactly once so global initializers run in dependency order. That is the reason the Discourse thread gives for CMake rejecting the INTERFACE shape: without a library there is nowhere reliable to put that symbol. A static archive built from the module file alone is the smallest thing that provides it.
What about MSVC?
Not tested here. The CMake documentation lists MSVC support for modules, but no MSVC toolchain was available. The INTERFACE rejection and the workaround were verified only with the GCC and Clang versions listed at the top.
Where does this sit?
The companion guide on C++20 Modules with CMake 3.28 and Ninja builds a multi-target module project and covers the compiler floor for CMake module scanning. This guide answers the follow-on question that guide leaves open: how to package a module library for other projects. The ranges and views pipeline guide, C++ Ranges and Views Pipeline, is the next build in the series.
Related guides on this site
- Testing C++20 Modules: Direct Commands, Then CMake and CTest
- C++20 Modules with CMake 3.28 and Ninja
- CMakePresets and vcpkg on a Real C++20 Modules Project
- Migrating a Template Library from SFINAE to C++20 Concepts
Source
- CMake, cmake-cxxmodules(7) — scanning strategy, compiler and generator support,
import stdrequirements, and the statement that, for the Visual Studio generators, exporting or installing BMI or module information is not supported. - CMake Discourse, Header-only libraries and C++20 modules — the unresolved thread this guide answers: the
INTERFACErefusal, the module initializer symbol, and the open question of building the object file in the consumer. - CMake Discourse, Distributing C++20 modules as source — the same header-only problem from the Boost side: static archives holding little more than the initializer, and modules built entirely by the consuming project.
Keep Exploring
Seven tips and seven puzzles so far, each one a short runnable example with the fix explained.
Paste an AddressSanitizer, UBSan, or ThreadSanitizer report and get the bug, the file and line, and the fix \u2014 in plain language.
C++20 and C++23 features, migration paths, and measured trade-offs.
The full C++ hub \u2014 language basics, the standard library, coroutines, and measured comparisons.
Paste a [Service] section and get a plain-language verdict on every sandboxing setting it finds.