Skip to content

README.md

Latest commit

 

History

History
338 lines (245 loc) · 14.4 KB

README.md

File metadata and controls

338 lines (245 loc) · 14.4 KB
Raw

mcpp

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

English | 简体中文

Release C++23 Module License

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

mcpp demo

Highlights

  • 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

Why mcpp

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

Note

Early-stage project — mcpp is under active development; interfaces and behavior may change in future releases. Developers interested in modern C++ module-first build tooling are welcome to contribute. Questions / feedback / ideas — drop a note in issues.

Getting Started

Install

Install via xlings (recommended)

xlings install mcpp -y
Don't have xlings yet? Click for the install command

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

Other options

Option 1 — 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 2 — Arch Linux (AUR) 
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/).

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.

Create, build & run a project

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.

Project layout

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"

Using module libraries

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.

Feature Overview

Build system
  • Native C++20/23 module support (interface units, implementation units, module partitions)
  • 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)
  • First-class C support: .c files auto-detected, mixed C/C++ projects
  • User-defined cflags / cxxflags / ldflags / c_standard
Toolchain management
  • Bundled GCC 16.1.0 + LLVM/Clang 20.1.7, one-command install
  • Fully static musl-gcc toolchain (default)
  • 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)
Package & dependency management
  • 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
Workspaces
  • [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
Packaging & publishing
  • mcpp pack: three Linux release modes — static (fully static musl) / bundle-project / bundle-all
  • Fully static musl binaries: single-file distribution, no glibc dependency (Linux x86_64)
  • mcpp publish: generates xpkg.lua + publishes to a package index
  • Automatic RPATH fix-up via patchelf (Linux)
Developer experience
  • mcpp new — create a modular project; --template <pkg>[@ver][:<tmpl>] uses a library-provided template (e.g. --template imgui); --list-templates <pkg> lists them
  • mcpp run [-- args] — build and run
  • mcpp test [-- args] — auto-discover and run tests
  • mcpp search — search package indices
  • mcpp add / remove / update — dependency management
  • mcpp explain E0001 — detailed error-code explanations
  • mcpp self doctor — environment self-diagnosis

Platform Support

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):

Target Convention toolchain Status
x86_64-linux-gnu gcc (Linux default) or llvm ✅
x86_64-linux-musl gcc 16, fully static ✅
aarch64-linux-musl gcc 16, fully static — cross from x86_64 (qemu-verified) or native ✅
x86_64-windows-gnu gcc 16 MinGW-w64 — native on Windows, cross from Linux (wine-verified) ✅
x86_64-windows-msvc msvc@system (detected VS/BuildTools) or llvm ¹ (Windows default) ✅
aarch64-macos llvm (macOS default) ✅
riscv64-linux-musl — 🔄
aarch64-linux-gnu — 🔄
x86_64-macos — 🔄

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

Release binaries for Linux are fully static musl builds (x86_64-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 requires an existing MSVC BuildTools or Visual Studio (UCRT, Windows SDK, MSVC STL). The MinGW route (--target x86_64-windows-gnu, or mcpp toolchain default gcc@16 --target x86_64-windows-gnu) needs no Visual Studio at all.

Documentation

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.

Who's Using mcpp

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

Project Description
mcpp mcpp itself — 43+ C++23 modules, fully self-hosted
xlings Toolchain & package-management foundation mcpp builds on
tinyhttps Minimal C++23 HTTP/HTTPS client with SSE streaming
llmapi Modern C++ LLM API client (OpenAI-compatible)
imgui-m Dear ImGui as a C++23 module package
cmdline Command-line parsing library / framework (mcpp uses it)

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

Contributing

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 & Ecosystem

Acknowledgements

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