C++ Modules Usage & Examples
1. Introduction
Xmake uses .mpp
as the default module extension, but also supports .ixx
, .cppm
, .mxx
, etc. It fully supports C++20 Modules with gcc11/clang/msvc, and can automatically analyze module dependencies for maximum parallel compilation.
Basic usage:
set_languages("c++20")
target("class")
set_kind("binary")
add_files("src/*.cpp", "src/*.mpp")
More official examples: C++ Modules Examples
2. Advanced Usage
2.1 Cpp-only Project with Modules
From v2.7.1, Headerunits are supported. Normally, at least one .mpp
file is needed to enable modules, but you can also force it:
add_rules("mode.debug", "mode.release")
target("test")
set_kind("binary")
add_files("src/*.cpp")
set_languages("c++20")
set_policy("build.c++.modules", true)
2.2 Headerunits Example
See headerunits example for how to use STL or custom headers as headerunits.
3. Module Package Distribution & Integration
3.1 Distributing C++ Modules as Packages
Specify {install = true}
for module files to be distributed:
add_rules("mode.release", "mode.debug")
set_languages("c++20")
target("foo")
set_kind("static")
add_files("*.cpp")
add_files("*.mpp", { install = true })
You can make it a package for xmake-repo or local/private repo.
Local package example:
package("foo")
set_sourcedir(path.join(os.scriptdir(), "src"))
on_install(function(package)
import("package.tools.xmake").install(package, {})
end)
3.2 Integrating C++ Modules Packages
Quickly integrate with add_requires("foo")
:
add_rules("mode.release", "mode.debug")
set_languages("c++20")
add_repositories("my-repo my-repo")
add_requires("foo", "bar")
target("packages")
set_kind("binary")
add_files("src/*.cpp")
add_packages("foo", "bar")
set_policy("build.c++.modules", true)
4. C++23 Standard Library Modules
Support for C++23 stdmodules:
add_rules("mode.debug", "mode.release")
set_languages("c++latest")
target("mod")
set_kind("static")
add_files("src/*.cpp")
add_files("src/*.mpp", {public = true})
target("stdmodules")
set_kind("binary")
add_files("test/*.cpp")
add_deps("mod")
// my_module.mpp
export module my_module;
import std;
export auto my_sum(std::size_t a, std::size_t b) -> std::size_t;
5. More C++ Modules Example Collection
The official C++ Modules Example Collection provides a variety of C++20/23 Modules projects, each subdirectory is a standalone example:
- basic: Basic module usage
- class: Exporting classes in modules
- headerunits: Using headerunits
- import_std: Standard library modules
- partition: Module partitions
- packages: Module package distribution & integration
- stdmodules: C++23 standard library modules
Each example contains a complete xmake.lua
and source code for in-depth learning and reference.