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

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

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

xlings install mcpp-short-cmd -y

Other options

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

brew install mcpp-community/mcpp/mcpp-m

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

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.

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, [email protected], 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.

• 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