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 and macOS ARM64:

• 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

Option 1: 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

Option 2: one-line install script

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

Installs into ~/.mcpp/ and adds it to your shell PATH. Deleting ~/.mcpp uninstalls cleanly.

Option 3: let an AI assistant install it for you

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

# mcpp.toml
[package]
name = "hello"

[targets.hello]
kind = "bin"
main = "src/main.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.

✅ supported ｜ 🔄 planned

default: the default toolchain on Linux is musl-gcc; release binaries are fully static musl builds. The default toolchain on macOS ARM64 / Windows x86_64 is LLVM/Clang.

¹ On Windows, Clang/LLVM currently requires an existing MSVC BuildTools or Visual Studio installation (providing the UCRT, Windows SDK, and MSVC STL). A zero-MSVC llvm-mingw route is planned (discussion).

• 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.

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, implement and verify (mcpp build + E2E tests)
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