Skip to content

2026-05-16-readme-draft.md

Latest commit

 

History

History
263 lines (185 loc) · 9.51 KB

2026-05-16-readme-draft.md

File metadata and controls

263 lines (185 loc) · 9.51 KB
Raw

mcpp

一个 现代C++ 模块化构建工具 — 纯 C++23 模块编写，已实现自举

A modular C++ build tool — written in pure C++23 modules, fully self-hosted.

Release C++23 Self-hosted Module License

核心特性

  • C++23 模块原生支持 — import std 自动处理，文件级增量构建，模块依赖自动分析，零手动配置
  • 纯模块化自举 — mcpp 自身由 43+ 个 C++23 模块组成，用自己构建自己，模块系统经实战验证
  • 开箱即用 — 一条命令安装，内置 GCC 16 / LLVM 20 工具链，自动下载到隔离沙盒，不污染系统
  • 集成依赖管理 — SemVer 约束解析、锁文件、跨项目 BMI 缓存、自定义包索引
  • 多包工作空间 — Workspace 统一锁文件与版本管理，适合大型项目

为什么选择 mcpp

mcpp 专门为 C++23 模块化开发 打造。如果你想在项目中使用 import std、模块接口单元（.cppm）、模块分区等现代 C++ 特性，mcpp 可能是目前 Linux 上体验最好的选择：

  • 默认模块化 — mcpp new 创建的项目模板直接使用 C++23 模块，import std 开箱即用
  • 文件级增量构建 — 基于 P1689 dyndep 的三层优化（前端脏检查 + 逐文件扫描 + BMI restat），只重编真正变化的模块
  • 一键创建 & 构建 — mcpp new hello && cd hello && mcpp build，工具链自动安装，无需手动配 CMake/ninja/编译器
  • 模块化生态 — mcpplibs 提供一系列可直接 import 的 C++ 模块化库，支持自定义包索引

快速开始

安装

方式一：使用 xlings 安装（推荐）

xlings install mcpp -y
还没有 xlings？点击查看安装命令

Linux / macOS

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

Windows — PowerShell

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

xlings 详情 → xlings.d2learn.org

方式二：一键安装脚本

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

安装到 ~/.mcpp/，自动加进 shell PATH。删除 ~/.mcpp 即可干净卸载。

方式三：让 AI 助手帮你安装

将以下内容发给你的 AI 编码助手（Claude Code / Cursor / Copilot 等）：

帮我安装 mcpp C++ 构建工具：curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash，然后用 mcpp new hello 创建一个 C++23 模块项目，mcpp build 构建，mcpp run 运行。

创建项目 & 构建运行

mcpp new hello
cd hello
mcpp build
mcpp run

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

项目结构

hello/
├── mcpp.toml             ← 工程描述（3 行即可）
└── src/
    └── main.cpp          ← import std; 直接可用

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

[targets.hello]
kind = "bin"
main = "src/main.cpp"

功能概览

构建系统
  • C++20/23 模块原生支持（接口单元、实现单元、模块分区）
  • import std / import std.compat 全自动预编译与缓存
  • 三层增量优化：前端脏检查 + 逐文件 P1689 dyndep + BMI copy-if-different restat
  • 指纹化 BMI 缓存：按编译器/标志/标准库哈希，跨项目共享
  • Ninja 后端：自动生成 build.ninja，并行编译
  • compile_commands.json 自动生成（clangd / ccls 即用）
  • C 语言一等支持：.c 文件自动检测，混合 C/C++ 项目
  • 用户自定义 cflags / cxxflags / c_standard
工具链管理
  • 内置 GCC 16.1.0 + LLVM/Clang 20.1.7，一键安装
  • musl-gcc 全静态工具链（默认）
  • 多版本共存：mcpp toolchain install gcc 16 / mcpp toolchain install llvm 20
  • 隔离沙盒：所有工具链在 ~/.mcpp/registry/，不影响系统
  • 按平台指定：linux = "gcc@16", macos = "llvm@20"
  • GCC + Clang 编译管线平权（BmiTraits 抽象层驱动）
包管理与依赖
  • SemVer 约束解析：^、~、范围、精确版本
  • 三级解析：约束合并 → 多版本 mangling 回退 → 精确匹配
  • 锁文件 mcpp.lock（v2 格式：索引快照 + 命名空间）
  • 命名空间系统：[dependencies.myteam] foo = "1.0"
  • 自定义包索引：[indices] acme = "git@..." / { path = "..." }
  • 项目级索引隔离（.mcpp/ 目录，不污染全局）
  • 依赖来源：索引 / Git / 本地路径
工作空间
  • [workspace] members = ["libs/*", "apps/*"]
  • 统一锁文件 + 统一 target 目录
  • 版本集中管理：[workspace.dependencies] + .workspace = true
  • 选择性构建：mcpp build -p member-name
  • 配置继承：工具链、构建标志、索引从根级联到成员
打包与发布
  • mcpp pack：三种模式 — static（musl全静态）/ bundle-project / bundle-all
  • musl 全静态二进制：单文件可分发，无 glibc 依赖
  • mcpp publish：生成 xpkg.lua + 发布到包索引
  • 自动 patchelf 修正 RPATH
开发体验
  • mcpp new — 创建模块化项目模板
  • mcpp run [-- args] — 构建并运行
  • mcpp test [-- args] — 自动发现并运行测试
  • mcpp search — 搜索包索引
  • mcpp add / remove / update — 依赖管理
  • mcpp explain E0001 — 错误码详细解释
  • mcpp self doctor — 环境自诊断

平台支持

OS / arch GCC (glibc) GCC (musl) Clang / LLVM MSVC
Linux x86_64 ✅ ✅ 默认 ✅ —
Linux aarch64 🔄 🔄 🔄 —
macOS — — 🔄 —
Windows — — 🔄 🔄

✅ 已支持 ｜ 🔄 计划中

默认：release 二进制走 musl 全静态，Linux x86_64 可直接运行，无 glibc 依赖。

文档

任意命令的完整选项可通过 mcpp <cmd> --help 查阅。

AI 辅助学习：你可以将本仓库地址或上述文档链接发给 AI 编码助手，让它帮你快速了解 mcpp 的使用方式：

阅读 https://github.com/mcpp-community/mcpp 的文档，告诉我如何用 mcpp 创建一个带依赖的 C++23 模块项目。

参与贡献

欢迎通过 issue 和 PR 参与项目开发。

使用 AI Agent 参与贡献

mcpp 项目支持并鼓励开发者使用 AI 编码助手（Claude Code、Cursor、Copilot 等）参与开发。推荐流程：

报告 Bug / 提出需求

  1. 让 AI 助手阅读相关代码和文档，梳理问题上下文
  2. 使用 gh issue create 或在 issues 页面提交
  3. 描述清楚：复现步骤、期望行为、实际行为

提交修复 / 功能 PR

  1. Fork 仓库，创建功能分支
  2. 让 AI 助手阅读项目文档和相关源码，理解现有架构
  3. 实现改动并通过 mcpp build 验证编译
  4. 运行 E2E 测试：bash tests/e2e/01_help_and_version.sh
  5. 使用 gh pr create 提交 PR

给 AI 助手的上下文

将以下信息提供给你的 AI 助手，帮助它快速理解项目：

这是 mcpp 项目（https://github.com/mcpp-community/mcpp），一个纯 C++23 模块化的构建工具。 项目文档在 docs/ 目录，设计文档在 .agents/docs/ 目录。 用 mcpp build 编译，E2E 测试在 tests/e2e/ 下。

后续我们也会在 .agents/ 目录下提供更多 Skill 和文档，方便 AI Agent 更高效地理解和使用 mcpp 生态。

贡献指南

  • 代码风格：遵循现有代码模式
  • 提交信息：feat: / fix: / test: / docs: 前缀
  • PR 要求：编译通过 + 相关 E2E 测试通过

社区 & 生态

致谢

项目依赖和灵感来源：

Note

早期版本 — mcpp 仍在积极开发中，接口和行为可能在后续版本调整。 问题 / 反馈 / 想法欢迎在 issues 留言。