C++ Modules Usage & Examples

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 Example

EXPLORER

src

hello.mpp

main.cpp

xmake.lua

Lua xmake.lua

123456

add_rules("mode.release", "mode.debug")
set_languages("c++20")

target("hello")
    set_kind("binary")
    add_files("src/*.cpp", "src/*.mpp")

Class Example

Exporting classes in modules:

EXPLORER

src

main.cpp

math.mpp

xmake.lua

Lua xmake.lua

12345678

add_rules("mode.debug", "mode.release")

set_languages("c++20")

target("class_test")
    set_kind("binary")
    add_files("src/*.cpp")
    add_files("src/*.mpp")

Module Partitions

Using module partitions:

EXPLORER

src

hello_say.mpp

hello.mpp

main.cpp

xmake.lua

Lua xmake.lua

12345678

add_rules("mode.debug", "mode.release")

set_languages("c++20")

target("partition_test")
    set_kind("binary")
    add_files("src/*.cpp")
    add_files("src/*.mpp")

Shared Library Modules

Creating a shared library with modules:

EXPLORER

src

foo.mpp

main.cpp

xmake.lua

Lua xmake.lua

123456789101112

add_rules("mode.debug", "mode.release")

set_languages("c++20")

target("foo")
    set_kind("shared")
    add_files("src/foo.mpp")

target("test")
    set_kind("binary")
    add_deps("foo")
    add_files("src/main.cpp")

Cross-Target Dependency

Modules dependency between targets:

EXPLORER

src

bar.mpp

main.cpp

xmake.lua

Lua xmake.lua

123456789101112

add_rules("mode.debug", "mode.release")

set_languages("c++20")

target("bar")
    set_kind("static")
    add_files("src/bar.mpp")

target("app")
    set_kind("binary")
    add_deps("bar")
    add_files("src/main.cpp")

Private Module Fragment

Using private module fragment to hide implementation details:

EXPLORER

src

box.mpp

main.cpp

xmake.lua

Lua xmake.lua

12345678

add_rules("mode.debug", "mode.release")

set_languages("c++20")

target("box")
    set_kind("binary")
    add_files("src/*.cpp")
    add_files("src/*.mpp")

Module Implementation Unit

Separating module interface and implementation:

EXPLORER

src

implementation.cpp

interface.mpp

main.cpp

xmake.lua

Lua xmake.lua

12345678

add_rules("mode.debug", "mode.release")

set_languages("c++20")

target("app")
    set_kind("binary")
    add_files("src/*.cpp")
    add_files("src/*.mpp")

Module Aggregation

Using export import to aggregate submodules:

EXPLORER

src

circle.mpp

main.cpp

rect.mpp

shape.mpp

xmake.lua

Lua xmake.lua

12345678

add_rules("mode.debug", "mode.release")

set_languages("c++20")

target("app")
    set_kind("binary")
    add_files("src/*.cpp")
    add_files("src/*.mpp")

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:

EXPLORER

src

main.cpp

xmake.lua

Lua xmake.lua

123456789

add_rules("mode.debug", "mode.release")

set_languages("c++latest")

target("stdmodules_cpp_only")
    set_kind("binary")
    add_files("src/*.cpp")
    set_policy("build.c++.modules", true)

Headerunits Example

See headerunits example for how to use STL or custom headers as headerunits.

EXPLORER

src

hello.mpp

main.cpp

xmake.lua

Lua xmake.lua

1234567

add_rules("mode.release", "mode.debug")
set_languages("c++20")

target("stl_headerunit")
    set_kind("binary")
    add_files("src/*.cpp", "src/*.mpp")

C++23 Standard Library Modules

Support for C++23 stdmodules:

EXPLORER

src

my_module.cpp

my_module.mpp

test

test.cpp

xmake.lua

Lua xmake.lua

123456789101112

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")

Module Package Distribution

Define and distribute a C++ Modules package:

EXPLORER

src

foo.cpp

foo.mpp

main.cpp

xmake.lua

xmake.lua

Lua xmake.lua

12345678910

add_rules("mode.release", "mode.debug")
set_languages("c++20")

target("foo")
    set_kind("static")
    add_files("*.cpp")
    add_files("*.mpp", {
        defines = "FOO_EXPORT", 
        public = true
    })

Module Package Integration

Quickly integrate with add_requires("foo"):

EXPLORER

src

main.cpp

xmake.lua

Lua xmake.lua

1234567891011

add_rules("mode.release", "mode.debug")
set_languages("c++20")

add_repositories("my-repo repo") 
add_requires("foo")

target("app")
    set_kind("binary")
    add_packages("foo")
    add_files("src/*.cpp")
    set_policy("build.c++.modules", true)

More official examples: C++ Modules Examples