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.

cxx-modules.md 3.2 KB Historia Raaka