A modern C++ module-first build tool — written in pure C++23 modules, fully self-hosted

English | 简体中文

Documentation · Getting Started · mcpp.toml Guide · Examples · Toolchains
Package index mcpp-index · Module libraries mcpplibs · Community Forum · Issues · Releases

• Native C++23 module support — import std handled automatically, file-level incremental builds, automatic module dependency analysis, zero manual configuration
• Pure modular self-hosting — mcpp itself consists of 43+ C++23 modules and builds itself; the module pipeline is battle-tested
• Works out of the box — one-command install, bundled GCC 16 / LLVM 20 toolchains downloaded into an isolated sandbox, never polluting your system
• Integrated dependency management — SemVer constraint resolution, lockfile, cross-project BMI cache, custom package indices
• Multi-package workspaces — unified lockfile and version management for larger projects

mcpp is built specifically for C++23 module-first development. If you want to use import std, module interface units (.cppm), module partitions, and other modern C++ features in your project, mcpp gives you a smooth, friendly experience on Linux, macOS ARM64, and Windows x86_64:

• Modular by default — projects created by mcpp new use C++23 modules directly; import std just works
• File-level incremental builds — three-layer optimization based on P1689 dyndep (front-end dirty check + per-file scanning + BMI restat); only the modules that actually changed get recompiled
• Create & build in one go — mcpp new hello && cd hello && mcpp build; toolchains install automatically, no compiler or build-system setup required
• A modular ecosystem — mcpplibs offers a growing set of directly import-able C++ module libraries, plus support for custom package indices

Install via xlings (recommended)

xlings install mcpp -y

Linux / macOS

curl -fsSL https://d2learn.org/xlings-install.sh | bash

Windows — PowerShell

irm https://d2learn.org/xlings-install.ps1.txt | iex

More about xlings → xlings.d2learn.org

xlings install mcpp-short-cmd -y

Registers 30 shims, so mcpp build becomes mbuild. Naming rule: initial of every word but the last, plus the last word in full — mcpp self doctor → msdoctor. mp is bare mcpp. They alias the mcpp shim rather than a fixed binary, so xlings use mcpp <ver> switches them too.

Other options

curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash

This installer does not support Windows; use the PowerShell xlings route above. It installs into ~/.mcpp/ and adds it to your shell PATH. Deleting ~/.mcpp uninstalls cleanly.

brew install mcpp-community/mcpp/mcpp-m

One command — it taps mcpp-community/homebrew-mcpp and installs the same prebuilt release binary. macOS needs Apple silicon + macOS 14; per-user data lives in ~/.mcpp/.

Homebrew's mcpp is an unrelated C preprocessor, hence the mcpp-m formula name — the command it installs is still mcpp.

Homebrew 6 gates third-party taps. The fully-qualified command above is read as explicit intent and works as-is, but every other spelling — the short brew install mcpp-m, the mcpp alias, and later upgrades — is refused with:

Refusing to load formula mcpp-community/mcpp/mcpp-m from untrusted tap
mcpp-community/mcpp.

Trust the tap once and all of them work:

brew trust mcpp-community/mcpp

yay -S mcpp-bin      # prebuilt release binary
yay -S mcpp-m        # or build from source (bootstrapped with mcpp-bin)

Installs the mcpp command system-wide; per-user data still lives in ~/.mcpp/. On Arch the name mcpp is an unrelated C preprocessor, so the packages are mcpp-bin / mcpp-m (see scripts/aur/). Stable-release automation reconciles mcpp-bin only; mcpp-m and mcpp-git remain manually maintained and may intentionally lag.

Copy the following prompt to your AI coding assistant (Claude Code / Cursor / Copilot, etc.):

Read the README of https://github.com/mcpp-community/mcpp,
then install mcpp for me and create a C++23 module project, build and run it.
The repo's .agents/skills/mcpp-usage/SKILL.md has a detailed usage guide.

mcpp new hello
cd hello
mcpp build
mcpp run

Note: the first build initializes the environment and fetches the toolchain, which may take a while.

hello/
├── mcpp.toml             ← project manifest
├── src/
│   └── main.cpp          ← import std; works directly
└── tests/
    └── test_smoke.cpp    ← discovered by `mcpp test`

# mcpp.toml
[package]
name        = "hello"
version     = "0.1.0"
description = "A modular C++23 package"
license     = "Apache-2.0"

The built-in scaffold relies on convention: it does not write [targets.hello]. src/main.cpp infers the binary target, and mcpp test automatically discovers tests/test_smoke.cpp.

Add a two-line dependency to mcpp.toml to pull in a community module library from mcpplibs:

[dependencies]
cmdline = "0.0.2"

Then import it directly in your code:

import mcpplibs.cmdline;

For more dependency options (version constraints, namespaces, Git references, local paths, etc.), see the mcpp.toml guide — dependency management.

• Native C++20/23/26 module support (interface units, implementation units, module partitions), plus c++latest / c++fly experimental modes
• Fully automatic precompilation and caching of import std / import std.compat
• Three-layer incremental optimization: front-end dirty check + per-file P1689 dyndep + BMI copy-if-different restat
• Fingerprinted BMI cache: hashed by compiler/flags/standard library, shared across projects
• Ninja backend: auto-generated build.ninja, parallel compilation
• compile_commands.json generated automatically (ready for clangd / ccls); use mcpp build --configure-only to refresh it before ordinary sources compile
• First-class C support: .c files auto-detected, mixed C/C++ projects
• User-defined cflags / cxxflags / ldflags / c_standard

• Bundled GCC 16.1.0 + LLVM/Clang 20.1.7, one-command install
• Host-aware defaults: native glibc GCC on Linux x86_64, musl GCC on other Linux architectures, LLVM on macOS and on Windows with usable MSVC, MinGW-w64 GCC on bare Windows
• Multiple versions side by side: mcpp toolchain install gcc 16 / mcpp toolchain install llvm 20
• Isolated sandbox: all toolchains live in ~/.mcpp/registry/, leaving the system untouched
• Per-platform selection: linux = "gcc@16", macos = "llvm@20"
• GCC and Clang compile pipelines at parity (driven by the BmiTraits abstraction layer)

• SemVer constraint resolution: ^, ~, ranges, exact versions
• Three-stage resolution: constraint merging → multi-version mangling fallback → exact match
• Lockfile mcpp.lock (v2 format: index snapshot + namespaces)
• Namespace system: [dependencies.myteam] foo = "1.0"
• Custom package indices: [indices] acme = "git@..." / { path = "..." }
• Project-level index isolation (.mcpp/ directory, no global pollution)
• Dependency sources: index / Git / local path

• [workspace] members = ["libs/*", "apps/*"]
• Unified lockfile + unified target directory
• Centralized version management: [workspace.dependencies] + .workspace = true
• Selective builds: mcpp build -p member-name
• Config inheritance: toolchains, build flags, and indices cascade from root to members

• mcpp pack: four Linux release modes — system / vendored (default) / self-contained / static; bundle-project and bundle-all remain compatibility aliases
• Fully static musl binaries: single-file distribution, no glibc dependency (matching Linux x86_64 or aarch64 target)
• mcpp publish: generates xpkg.lua + publishes to a package index
• Automatic RPATH fix-up via patchelf (Linux)

• mcpp new — create a modular project; --template [ns.]name[@version][:tname] uses a package-provided template with the same exact identity style as mcpp add. A sole template is the default even without default = true; --list-templates [ns.]name[@version] lists ambiguous sets
• mcpp run [-- args] — build and run
• mcpp test [pattern] [-- args] — auto-discover and run tests (filter by name; --list, --timeout <s>, --message-format json)
• mcpp search — search package indices
• mcpp add / remove / update — dependency management
• mcpp why [toolchain|runtime|deps] — explain resolved build decisions
• mcpp --offline / MCPP_OFFLINE=1 — use only already available local state
• mcpp explain E0001 — detailed error-code explanations
• mcpp self doctor — environment self-diagnosis

Building mcpp itself — 137 module interface units, 57k lines, every one of them import std; — with four engines handed the same compiler binary. Each cell is the median of 3 samples and how many times faster it is than cmake. Every column comes from one run.

cold nothing built yet · noop nothing at all · touch-hub mtime only, content unchanged · edit-body a real edit inside a function body · edit-comment a comment added to a hub interface.

mcpp = mcpp@2026.8.13.1, the build under test · mcpp +opt = the SAME binary as mcpp, with the opt-in key [build] bmi_schedule = "on" (off by default) · mcpp (old) = mcpp@2026.8.11.3, the previously published release.
Linux x86_64 · i9-13900K · gcc 16.1.0 · n=3 · pinned workload a749e9f · cmake 4.4.2 / xmake 3.1.0 · - would mean not measured, and there is none here · min/max sit within 4% of every median above 1s · data: standard-20260814-linux-x86_64.

• Cascade suppression accounts for the touch-hub and edit-comment rows. cmake and xmake decide by timestamp and rebuild every downstream unit. mcpp compares the BMI the compiler has just produced against the previous one and skips the cascade when the interface is unchanged. This is default behaviour and requires no configuration. The mcpp (old) column measures the previous release at 81.72s, level with cmake, so the effect is new in this revision.

• edit-body measures the case where the cascade is genuinely owed — and whether an edit owes one depends on where the body lives:

  the function body is in…	editing it	this row
  a .cppm, and the edit moves lines	GCC records declaration positions, so the BMI changes → cascade owed	what is measured: 1.1x, and 2.9x with +opt
  a .cppm, edited in place (same line count)	GCC does not serialise non-template bodies → BMI unchanged → no cascade	~200x, like touch-hub
  a separate .cpp implementation unit	that file has no BMI at all → no cascade, on every compiler	~200x

  The perturbation here inserts a statement, so it takes the first row: every engine has to rebuild the importers, and one that did not would be skipping work. +opt does not skip it either — it does the same work 2.9x faster. Splitting interface from implementation is the sturdiest of the three, because it does not depend on GCC's body handling or on avoiding line shifts. Measured in .agents/docs/2026-08-15-module-edit-granularity.md.

• bmi_schedule is opt-in and disabled by default (auto resolves to off). It moves code generation off the critical path, so it helps only where a cascade is required: cold 86.69s → 35.73s, edit-body 80.87s → 29.83s. On the two rows where mcpp already skips the cascade it yields no improvement. An incorrect scheduling change fails silently rather than loudly, so the default is not changed on the evidence of a single machine.

📊 Methodology, pinned versions, and the full data → bench/README.md · 简体中文

mcpp's identity model has two orthogonal axes: a toolchain is family@version (family ∈ gcc | llvm | msvc), a target is a triple arch-os[-env]. Cross-compiling is just mcpp build --target <triple> — the right toolchain payload is resolved and installed automatically. mcpp toolchain list shows live status on your machine.

Hosts (where mcpp itself runs): Linux x86_64 / aarch64, macOS arm64, Windows x86_64.

Targets (what --target accepts; this table mirrors the in-code vocabulary):

✅ verified — CI builds and executes the artifact end-to-end (qemu/wine included) ｜ 🔄 planned

Linux release binaries are fully static musl builds for x86_64 and aarch64 (x86_64-linux-musl and aarch64-linux-musl). Legacy spellings — x86_64-w64-mingw32, gcc@16.1.0-musl, mingw-cross@…, musl-gcc@… — stay permanently accepted as aliases and normalize to the canonical forms above.

¹ On Windows, llvm targets the MSVC ABI and therefore requires an existing MSVC BuildTools or Visual Studio (UCRT, Windows SDK, MSVC STL). You do not have to arrange this: on first run mcpp checks for a usable MSVC and, finding none, defaults to x86_64-windows-gnu (winlibs MinGW-w64) — fully self-contained, no Visual Studio, import std included. Nothing to install or configure; mcpp new && mcpp build just works on a stock Windows box. An explicit [toolchain] in mcpp.toml is always respected as written — mcpp revises its own default, never yours.

² The bare-metal rows carry no operating system: clang and lld are cross-compilers by construction, so any host that can install the LLVM payload produces these targets. The C library, startup code, memory layout and emulator travel with a board-support package rather than with mcpp — see docs/13 — Bare-Metal and Freestanding Targets.

• Getting Started — install → new → build → run in 5 minutes
• Examples
• Packaging & Release
• Toolchain Management
• Building from Source
• mcpp.toml Guide
• Workspaces

Full options for any command are available via mcpp <cmd> --help.

AI-assisted learning: send the following prompt to an AI coding assistant to get up to speed with mcpp quickly:

Read .agents/skills/mcpp-usage/SKILL.md and the docs/ directory of the
https://github.com/mcpp-community/mcpp repository,
then tell me how to create a C++23 module project with dependencies using mcpp.

Real projects built with mcpp — import-able C++23 modules and the toolchain it builds on:

More modular libraries → mcpplibs · package index → mcpp-index

Contributions via issues and PRs are welcome. The project accepts contributions developed with AI agents.

Basic workflow

1. Open an issue — for bug fixes, new features, or improvements, start a discussion in issues first
2. Implement the change — fork the repo, create a branch, and verify according to scope (mcpp build plus relevant tests for behavior changes; examples and links for documentation-only changes)
3. Submit a PR — use gh pr create and make sure CI passes
4. CI must pass — PRs with failing CI will not be merged

Commit message convention: feat: / fix: / test: / docs: / refactor: prefixes

AI agent contributions: the repo's .agents/skills/mcpp-contributing/SKILL.md provides a complete agent contribution workflow and project structure guide. Just send this prompt to your AI assistant:

Read .agents/skills/mcpp-contributing/SKILL.md of the
https://github.com/mcpp-community/mcpp repository,
then follow the guide to help me submit a contribution to mcpp.

• Community Forum — chat group (QQ: 1067245099)
• mcpp-index — default package index
• mcpplibs — collection of modular C++ libraries

Dependencies and sources of inspiration:

• xlings — toolchain / package-management foundation
• mcpplibs.cmdline — CLI framework
• ninja — underlying build engine
• xmake — cross-platform build tool
• cargo — Rust package manager