modules.cpp — Self-Hosting C++20 Modules Toolkit

modules.cpp is a self-contained C++20 project created by Pawel Wodnicki. It builds, tests, models, checks, and documents itself from source without a third-party build system, package manager, test framework, or documentation generator. The project uses C++20 modules instead of traditional header files and describes its source tree with its own MDY manifest format.

What began as a self-hosting toolkit now reaches from Linux hosts and emulators down to Raspberry Pi Pico firmware: one manifest tree produces host tools, cross-compiled targets, and bare-metal images.

The project is open source under Apache-2.0 and hosted at https://github.com/modules-cpp/modules.cpp.

Latest release: v1.3.2 (October 6, 2026) — portable file systems, SD-card and SPI-flash drivers, addressable RGB LEDs, and live camera preview on the Waveshare PICO-Cam-A.

Why It Exists

modules.cpp explores how small a modern C++ project can be when module interfaces, explicit dependency graphs, and project-owned tools replace layers of header processing and build-system configuration. Its guiding rule is that the current version must be able to build the next version.

A module publishes an interface directly:

export module example;

export int add(int left, int right)
{
    return left + right;
}

Consumers use import example; rather than copying declarations through #include directives.

Architecture

The project has four cooperating layers:

• MDY manifests — an mm.mdy file in each participating directory describes project structure, targets, sources, module names, libraries, and dependency relationships.
• Core modules — reusable mm.* modules under modules/mm/ implement parsing, dependency ordering, compilation, testing, modeling, and the project shell, plus portable device interfaces: mm.mcu, mm.stdio, mm.display, mm.gfx, mm.audio, mm.usb, mm.fs, mm.camera, mm.led, and more.
• Platforms and boards — SDK and board manifests bind those interfaces to real hardware and to Linux, with vendored SDKs (Pico SDK, littlefs, FatFs) consumed through external build bridges.
• Tools and applications — small command-line programs expose the build, configure, test, run, debug, flash, sketch, documentation, model, check, and shell workflows.

The bootstrap path first creates a minimal build program using the host compiler. That program builds the real build and configure tools, which then compile and install the complete project toolset. Generated programs, objects, module caches, and HTML documentation are written below out/ and the configured out-* trees.

What It Can Do Today

• Self-hosting toolchain — bootstrap, build, test, and document the whole project with nothing but a C++20 compiler and a POSIX shell. Compiling is strict: warnings are not allowed.
• Cross compilation — configure selects a compiler, build type, target, board, runner, and debugger; run and debug execute targets natively, under QEMU, or on hardware.
• Bare-metal firmware — Raspberry Pi Pico (RP2040 and RP2350, Arm and RISC-V) and an MPS2-AN385 Cortex-M emulator target, with flash for UF2 images.
• Arduino-style sketches — .ino sketches build as ordinary C++20 applications importing mm.sketch, inside the tree or outside it. See All Your Sketch Are Belong to modules.cpp.
• A shell of its own — from an allocation-free embedded shell on a Pico to a full host shell that runs the project's own scripts without /bin/sh.
• Devices and storage — GPIO, ADC, PWM, SPI, I2C, I2S audio, USB device and host, colour and e-paper displays, fonts and graphics, littlefs and FAT file systems, SD cards, SPI flash, WS2812B LEDs, and an HM01B0 camera.

Project Tools

Getting Started

The project requires a POSIX shell (Linux or macOS; WSL on Windows) and a C++20 compiler with module support. Self-hosted builds support GCC and Clang; GCC 15 or a recent Clang is recommended, and GCC 14 works. Bootstrap always uses the compiler named c++.

git clone https://github.com/modules-cpp/modules.cpp.git
cd modules.cpp
./bootstrap.sh
./configure --compiler gcc-15 --build debug
./build.sh
./test.sh
./document.sh

./clean.sh removes generated output so the bootstrap can be repeated from a clean source tree. Pico builds additionally require an Arm or RISC-V toolchain, the Pico SDK, and picotool; scripts/install-linux-deps.sh installs Ubuntu/Debian dependencies.

Documentation

The repository contains its developer guide, MDY format reference, abstract data model, supported C++20 language rules, and a document for every module and platform, all written as MDY:

• Developer guide
• MDY format
• Abstract data model
• C++20 project rules
• Platforms specification
• Sketches and the sketch runtime
• Changelog

Release History

modules.cpp publishes tagged GitHub releases. Each release adds one capability on top of the last:

Development on main continues toward the next release with library C sources (manifest version 1.4), littlefs and FAT on Linux, 4-bit SDIO for SD cards, and file commands in the shells.

Some newer board paths compile and link but are not yet qualified on hardware; each release's notes record exactly which.

Related Technologies

• C++20 modules — language-level module interfaces and imports.
• GCC and Clang — both supported for self-hosted builds; bootstrap uses GCC's modules implementation.
• Raspberry Pi Pico SDK — the vendored SDK behind the RP2040 and RP2350 firmware lanes.
• QEMU — runs m68k Linux and MPS2-AN385 targets during testing.
• MMCU — 32bitmicro's C++20 modular firmware scaffold for bare-metal MCU development.

Read the story behind the project in Compiler Is All You Need.

View modules.cpp on GitHub