mcpp

一款现代 C++ 模块优先的构建工具 —— 使用纯 C++23 模块编写，完全自托管

English | 简体中文

文档 · 快速入门 · mcpp.toml 指南 · 示例 · 工具链
软件包索引 mcpp-index · 模块库 mcpplibs · 社区论坛 · 问题 · 发布版本

亮点

• 原生 C++23 模块支持 — import std 自动处理，文件级增量构建，自动模块依赖分析，零手动配置
• 纯模块化自举 — mcpp 本身由 43+ 个 C++23 模块组成并构建自身；模块流水线经过实战检验
• 开箱即用 — 单命令安装，捆绑的 GCC 16 / LLVM 20 工具链下载至隔离沙箱，绝不污染您的系统
• 集成依赖管理 — SemVer 约束解析，锁文件，跨项目 BMI 缓存，自定义软件包索引
• 多软件包工作区 — 为大型项目提供统一的锁文件和版本管理

为什么选择 mcpp

mcpp 专为 C++23 模块优先开发 而构建。如果您希望在项目中使用 import std、模块接口单元（.cppm）、模块分区以及其他现代 C++ 特性，mcpp 在 Linux、macOS ARM64 和 Windows x86_64 上为您提供流畅、友好的体验：

• 默认模块化 — 由 mcpp new 创建的项目直接使用 C++23 模块；import std 开箱即用
• 文件级增量构建 — 基于 P1689 dyndep 的三层优化（前端脏检查 + 逐文件扫描 + BMI 重新统计）；仅重新编译实际发生变化的模块
• 一键创建与构建 — mcpp new hello && cd hello && mcpp build；工具链自动安装，无需配置编译器或构建系统
• 模块化生态系统 — mcpplibs 提供一套不断增长的、可直接 import 的 C++ 模块库，并支持自定义软件包索引

[!NOTE] 早期阶段项目 — mcpp 正处于积极开发中；接口和行为可能会在未来版本中发生变化。 欢迎对现代 C++ 模块优先构建工具感兴趣的开发者 contribute。 问题 / 反馈 / 建议 — 请在 issues 中留言。

快速入门

安装

通过 xlings 安装（推荐）

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

其他选项

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

注意：首次构建会初始化环境并获取工具链，这可能需要一些时间。

项目布局

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"

内置脚手架依赖约定：它不会写入 [targets.hello]。 src/main.cpp 推断二进制目标，并且 mcpp test 自动发现 tests/test_smoke.cpp。

使用模块库

在 mcpp.toml 中添加两行依赖，以从 mcpplibs 引入社区模块库：

[dependencies]
cmdline = "0.0.2"

然后直接在代码中 import：

import mcpplibs.cmdline;

有关更多依赖选项（版本约束、命名空间、Git 引用、本地路径等），请参阅 mcpp.toml 指南 — 依赖管理。

功能概览

平台支持

mcpp 的身份模型有两个正交维度：工具链是 family@version（family ∈ gcc | llvm | msvc），目标是一个三元组 arch-os[-env]。交叉编译仅仅是 mcpp build --target <triple> —— 正确的工具链负载会被自动解析并安装。 mcpp toolchain list 显示您机器上的实时状态。

主机（mcpp 本身运行的环境）：Linux x86_64 / aarch64，macOS arm64，Windows x86_64。

目标（--target 接受的对象；此表镜像了代码中的词汇表）：

✅ 已验证 —— CI 构建并执行了端到端的产物（包括 qemu/wine） ｜ 🔄 计划中

Linux 发布二进制文件是 x86_64 和 aarch64 的完全静态 musl 构建 （x86_64-linux-musl 和 aarch64-linux-musl）。 旧拼写 — x86_64-w64-mingw32、gcc@16.1.0-musl、mingw-cross@…、 musl-gcc@… — 将永久作为别名接受，并规范化为 上述标准形式。

¹ 在 Windows 上，llvm 针对 MSVC ABI，因此需要一个现有的 MSVC BuildTools 或 Visual Studio（UCRT、Windows SDK、MSVC STL）。你无 需自行配置：首次运行时 mcpp 会检查可用的 MSVC， 若未找到，则默认使用 x86_64-windows-gnu（winlibs MinGW-w64）—— 完全 自包含，无需 Visual Studio，包含 import std。无需安装 或配置；mcpp new && mcpp build 在标准 Windows 系统上即可正常工作。 mcpp.toml 中显式指定的 [toolchain] 始终按原样尊重 — mcpp 会修改其自身默认值，而不会修改你的设置。

文档

• 入门指南 — 安装 → 新建 → 构建 → 运行，仅需 5 分钟
• 示例
• 打包与发布
• 工具链管理
• 从源码构建
• mcpp.toml 指南
• 工作区

任何命令的完整选项均可通过 mcpp <cmd> --help 获取。

AI 辅助学习：将以下提示发送给 AI 编程助手，即可快速上手 mcpp：

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.

谁在使用 mcpp

使用 mcpp 构建的真实项目 — 可import的 C++23 模块及其所依赖的工具链：

更多模块化库 → mcpplibs · 包索引 → mcpp-index

贡献

欢迎通过 issue 和 PR 进行贡献。该项目接受由 AI 代理开发的贡献。

基本工作流

1. 打开一个 issue — 对于 bug 修复、新功能或改进，请先在 issues 中发起讨论
2. 实现更改 — fork 仓库，创建分支，并根据范围进行验证（行为变更需mcpp build及相关测试；仅文档变更需提供示例和链接）
3. 提交 PR — 使用 gh pr create 并确保 CI 通过
4. CI 必须通过 — CI 未通过的 PR 不会被合并

提交信息约定：feat: / fix: / test: / docs: / refactor: 前缀

AI 代理贡献：仓库中的 .agents/skills/mcpp-contributing/SKILL.md 提供了完整的代理贡献工作流和项目结构指南。只需将此提示发送给你的 AI 助手：

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.

社区与生态系统

• 社区论坛 — 聊天群组 (QQ: 1067245099)
• mcpp-index — 默认软件包索引
• mcpplibs — 模块化 C++ 库集合

致谢

依赖项与灵感来源：

• xlings — 工具链 / 软件包管理基础
• mcpplibs.cmdline — CLI 框架
• ninja — 底层构建引擎
• xmake — 跨平台构建工具
• cargo — Rust 软件包管理器