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.

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

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 three cooperating layers:

MDY manifests — an mm.mdy file in each participating directory describes project structure, targets, sources, module names, and dependency relationships.
Core modules — reusable mm.app, mm.mdy, mm.build, mm.test, mm.model, and mm.shell modules implement parsing, dependency ordering, compilation, testing, modeling, and process support.
Tools and applications — small command-line programs expose the build, test, documentation, model, check, and shell workflows.

The bootstrap path first creates a minimal build program using the host compiler. That program builds a second-stage tool, which then compiles and installs the complete project toolset. Generated programs, objects, and HTML documentation are written below out/; GCC module state is kept in gcm.cache/.

Project Tools

Tool	Purpose
`build`	Walk MDY manifests, resolve module dependencies, and compile targets
`test`	Build and run unit, integration, regression, and expected-failure tests
`document` / `mdy`	Render MDY documentation as static HTML
`model`	Check the project tree against its abstract C++ model
`check`	Run the project's C++20 source rules through `cppcheck` when available
`shell`	Provide the project-owned wrapper for shell-based workflows

Getting Started

The project requires a POSIX shell and a C++20 compiler with module support. It is developed with GCC's -fmodules-ts implementation; GCC 14 or newer is recommended and GCC 15 is the currently documented test compiler. Clang and MSVC are not currently supported by the project workflow.

git clone https://github.com/modules-cpp/modules.cpp.git
cd modules.cpp
./bootstrap.sh
./test.sh
./document.sh

After bootstrap, ./build.sh rebuilds the project through its installed build tool. ./clean.sh removes generated output so the bootstrap can be repeated from a clean source tree.

Documentation

The repository contains its developer guide, MDY format reference, abstract data model, and supported C++20 language rules as MDY documents:

Versioning

modules.cpp is in early development. The project documentation identifies the current state as seed release 1.0, but the repository does not yet publish tagged GitHub releases.

Item	Detail
Project status	Seed release 1.0; early development
License	Apache-2.0
Compiler	GCC 14+ recommended; GCC 15 tested
Platform	POSIX shell environment
Repository	https://github.com/modules-cpp/modules.cpp

Related Technologies

C++20 modules — language-level module interfaces and imports.
GCC modules TS — the compiler implementation currently used by the project.
MMCU — 32bitmicro's C++20 modular firmware scaffold for bare-metal MCU development.
LLVM / Clang — an adjacent compiler ecosystem; not currently supported by the modules.cpp build workflow.

View modules.cpp on GitHub