mcpp-community mcpp 基础用法
Overview
mcpp 是一个现代 C++ 模块化构建工具，纯 C++23 模块编写，已实现自举。一条命令安装，import std 开箱即用。
- 仓库：https://github.com/mcpp-community/mcpp
- 文档：https://github.com/mcpp-community/mcpp/tree/main/docs
- 包索引：https://github.com/mcpp-community/mcpp-index
- 模块化库：https://github.com/mcpplibs
Quick Reference
| 命令 | 用途 |
|---|---|
mcpp new <name> |
创建项目 |
mcpp build |
构建 |
mcpp run [-- args] |
构建并运行 |
mcpp test [pattern] [-- args] |
发现并运行 tests/**/*.cpp 测试 |
mcpp add <pkg>[@ver] |
添加依赖 |
mcpp remove <pkg> |
移除依赖 |
mcpp update [pkg] |
更新依赖 |
mcpp search <keyword> |
搜索包 |
mcpp toolchain list |
查看工具链 |
mcpp toolchain install gcc 16 |
安装工具链 |
mcpp pack |
打包 |
mcpp why [toolchain｜runtime｜deps] |
解释解析出的构建决策 |
mcpp --offline |
只使用已有本地状态 |
mcpp self doctor |
环境诊断 |
mcpp explain <CODE> |
错误码解释 |
安装
# 推荐；Windows 请在 PowerShell 中运行
xlings install mcpp -y
# 或 Unix release 一键脚本（仅 Linux x86_64/aarch64 与 macOS ARM64）
curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
一键脚本不支持 Windows；Windows 使用 PowerShell 的 xlings 安装命令。安装到
~/.mcpp/ 后会自动加入 PATH。首次使用时，mcpp 按宿主选择默认工具链并
安装到隔离沙盒：Linux 通常为 GCC，macOS 为 LLVM，Windows 在有可用 MSVC
时为 LLVM，否则为面向 x86_64-windows-gnu 的 MinGW-w64 GCC。
创建项目
mcpp new hello && cd hello
mcpp build
mcpp run
生成的项目包含最小 manifest 和可立即运行的 smoke test：
[package]
name = "hello"
version = "0.1.0"
description = "A modular C++23 package"
license = "Apache-2.0"
src/main.cpp 会自动推断为 binary target，tests/test_smoke.cpp 会由
mcpp test 自动发现；无需手写 [targets.hello]。
mcpp.toml 配置
[package]
name = "myapp"
version = "0.1.0"
[targets.myapp]
kind = "bin" # bin / lib / shared; tests are discovered from tests/**/*.cpp
main = "src/main.cpp"
[dev-dependencies]
gtest = "1.15.2" # 仅测试使用；SemVer: ^, ~, 范围, 精确
[toolchain]
default = "gcc@16.1.0"
更多配置：https://github.com/mcpp-community/mcpp/blob/main/docs/05-mcpp-toml.md
工具链
mcpp toolchain list # 查看已装
mcpp toolchain install gcc 16 # 装 GCC 16
mcpp toolchain install llvm 20 # 装 LLVM 20
mcpp toolchain default gcc@16.1.0 # 设默认
mcpp build --target x86_64-linux-musl # 需要全静态 Linux 产物时显式选择
工作空间
[workspace]
members = ["libs/*", "apps/*"]
[workspace.dependencies]
gtest = "1.15.2"
mcpp build -p member-name # 构建指定成员
自定义索引
[indices]
my-index = "git@gitlab.example.com:team/index.git"
local = { path = "/path/to/index" }
[dependencies.my-index]
internal-lib = "1.0.0"
常见问题
| 问题 | 解决 |
|---|---|
| 首次构建慢 | 正常，需下载工具链。后续使用缓存 |
| command not found | 重开终端。Unix release 安装脚本应确认 ~/.mcpp/bin 在当前 shell 的 PATH 中；经 xlings 安装则确认 xlings 当前激活的 bin 目录。Windows 不要执行 source，重开 PowerShell 后用 Get-Command mcpp.exe 验证命令已激活。 |
| 编译错误 | mcpp clean && mcpp build，确认 mcpp toolchain list |
| 依赖找不到 | mcpp index update，确认 mcpp search <name> |
| 需要无网络构建 | 使用 mcpp --offline 或设置 MCPP_OFFLINE=1；缺失的工具链/依赖会直接报错 |
问题反馈
项目 Issue：https://github.com/mcpp-community/mcpp/issues
- 描述复现步骤、期望/实际行为、mcpp 版本和 OS
- 可用
gh issue create提交
社区论坛：https://forum.d2learn.org/category/20
- 使用疑问和讨论
如果 AI Agent 无法直接创建 Issue，请提示用户手动创建并提供整理好的问题描述。