Skip to content

Commit 0d7e02a

Browse files
SunrisepeakSunrisepeak
authored
docs: README 重设计 — 核心特性、AI 辅助上手、贡献者指南 (#42)
* docs: redesign README — highlights, AI onboarding, contributor guide - Rewrite tagline: emphasize pure C++23 modules + self-hosted - Add core features section (5 bullets) - Add "why mcpp" section focused on module-first experience - Add AI-assisted install (方式三) and AI learning prompt - Add contributor section with AI Agent workflow guidance - Reorganize feature overview into collapsible sections - Update platform matrix (Clang/LLVM now supported) - Move WIP notice to end of file - Add Release + Self-hosted badges * docs: update README + add agent skills (contributing, usage) - Move WIP notice from bottom to after "why mcpp" section - Soften "Linux上体验最好的选择" wording - Change AI prompts to copyable code blocks with repo URL - Simplify contributing section, reference .agents/skills/ - Add .agents/skills/contributing.md (agent contribution guide) - Add .agents/skills/mcpp-usage.md (agent usage guide) * docs: restructure skills to standard directory format - .agents/skills/contributing.md → .agents/skills/mcpp-contributing/SKILL.md - .agents/skills/mcpp-usage.md → .agents/skills/mcpp-usage/SKILL.md - Both skills now have YAML frontmatter (name, description) - Update README references to new skill paths * docs: add modular library usage example to README * docs: add contribution invitation to early-version notice * docs: add demo GIF to README
1 parent 128be31 commit 0d7e02a

3 files changed

Lines changed: 506 additions & 47 deletions

File tree

‎.agents/skills/mcpp-contributing/SKILL.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
name: mcpp-contributing
3+
description: Use when contributing to the mcpp project — submitting bug fixes, new features, code optimizations, documentation improvements, or any PR. Covers issue creation, branch conventions, build verification, CI requirements, and PR workflow using gh and git.
4+
---
5+
6+
# mcpp 项目开发贡献
7+
8+
## Overview
9+
10+
mcpp 项目的贡献流程：先创建 Issue → 实现改动 → 提交 PR → CI 通过 → Review 合入。
11+
12+
- 仓库：https://github.com/mcpp-community/mcpp
13+
- 构建：`mcpp build`（C++23 模块自举）
14+
- 测试：`tests/e2e/` 下的 bash 脚本
15+
- CI：GitHub Actions，base 为 `main` 的 PR 自动触发
16+
17+
## 贡献流程
18+
19+
### 1. 创建 Issue（必须）
20+
21+
所有贡献先创建 Issue，特别是新功能。避免重复工作，留下讨论记录。
22+
23+
**Bug 修复**
24+
25+
```bash
26+
gh issue create \
27+
--title "fix: 简短描述" \
28+
--body "## 复现步骤
29+
1. ...
30+
31+
## 期望行为
32+
...
33+
34+
## 实际行为
35+
...
36+
37+
## 环境
38+
- mcpp 版本：\`mcpp --version\`
39+
- OS："
40+
```
41+
42+
**新功能**
43+
44+
```bash
45+
gh issue create \
46+
--title "feat: 简短描述" \
47+
--body "## 动机
48+
...
49+
50+
## 设计思路
51+
...
52+
53+
## 涉及模块
54+
..."
55+
```
56+
57+
**代码优化**
58+
59+
```bash
60+
gh issue create \
61+
--title "refactor: 简短描述" \
62+
--body "## 当前问题
63+
...
64+
65+
## 优化方案
66+
..."
67+
```
68+
69+
### 2. 实现改动
70+
71+
**分支**
72+
73+
```bash
74+
git checkout main && git pull origin main
75+
git checkout -b <type>/<short-description>
76+
# type: feat / fix / refactor / test / docs
77+
```
78+
79+
**开发要求**
80+
- 遵循现有代码风格（查看相邻代码）
81+
- 模块导入用 `import std;` 和 `import mcpp.xxx;`
82+
- 只改需要改的，不顺手重构不相关代码
83+
84+
**构建验证**
85+
86+
```bash
87+
# 找到 mcpp 二进制
88+
ls target/x86_64-linux-gnu/*/bin/mcpp
89+
# 构建
90+
<mcpp-binary> build
91+
```
92+
93+
**测试**
94+
95+
```bash
96+
bash tests/e2e/01_help_and_version.sh # 基础测试
97+
bash tests/e2e/<relevant-test>.sh # 相关测试
98+
# 新功能应创建对应 E2E 测试
99+
```
100+
101+
### 3. 提交 PR
102+
103+
**提交信息**：`feat:` / `fix:` / `refactor:` / `test:` / `docs:` 前缀
104+
105+
```bash
106+
git push -u origin <branch>
107+
gh pr create \
108+
--title "<type>: 简短描述" \
109+
--body "## Summary
110+
- 改动点
111+
112+
Closes #<issue>
113+
114+
## Test plan
115+
- [ ] mcpp build 通过
116+
- [ ] E2E 测试通过"
117+
```
118+
119+
### 4. CI 必须通过
120+
121+
CI 不通过的 PR 不会被合入。
122+
123+
```bash
124+
gh pr checks <pr-number> # 查看状态
125+
gh run view <run-id> --log-failed # 查看失败日志
126+
```
127+
128+
CI 内容：mcpp 自举构建 + E2E 测试。只有 base 为 `main` 的 PR 触发。
129+
130+
### 5. Review & 合入
131+
132+
维护者 review → 反馈修改 → CI 重跑 → Squash merge。
133+
134+
## 项目结构
135+
136+
```
137+
src/
138+
├── cli.cppm ← 命令行入口
139+
├── config.cppm ← 全局配置
140+
├── manifest.cppm ← mcpp.toml 解析
141+
├── build/ ← 构建系统（ninja 后端）
142+
├── pm/ ← 包管理子系统
143+
├── toolchain/ ← 编译器检测管理
144+
├── modgraph/ ← 模块图扫描验证
145+
├── pack/ ← 打包发布
146+
└── xlings.cppm ← xlings 抽象层
147+
tests/e2e/ ← E2E 测试脚本
148+
docs/ ← 用户文档
149+
.agents/docs/ ← 设计文档
150+
.agents/skills/ ← Agent 技能文档
151+
```
152+
153+
## 注意事项
154+
155+
- C++23 模块项目，修改模块时注意 import 依赖顺序
156+
- E2E 测试应独立运行，不依赖网络
157+
- 不确定方向时先在 Issue 讨论再动手

‎.agents/skills/mcpp-usage/SKILL.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
name: mcpp-usage
3+
description: Use when helping users install, configure, or use mcpp — the C++23 modular build tool. Covers installation, project creation, building, dependency management, toolchain management, workspace setup, packaging, diagnostics, and troubleshooting.
4+
---
5+
6+
# mcpp 基础用法
7+
8+
## Overview
9+
10+
mcpp 是一个现代 C++ 模块化构建工具，纯 C++23 模块编写，已实现自举。一条命令安装，`import std` 开箱即用。
11+
12+
- 仓库：https://github.com/mcpp-community/mcpp
13+
- 文档：https://github.com/mcpp-community/mcpp/tree/main/docs
14+
- 包索引：https://github.com/mcpp-community/mcpp-index
15+
- 模块化库：https://github.com/mcpplibs
16+
17+
## Quick Reference
18+
19+
| 命令 | 用途 |
20+
|---|---|
21+
| `mcpp new <name>` | 创建项目 |
22+
| `mcpp build` | 构建 |
23+
| `mcpp run [-- args]` | 构建并运行 |
24+
| `mcpp test [-- args]` | 运行测试 |
25+
| `mcpp add <pkg>[@ver]` | 添加依赖 |
26+
| `mcpp remove <pkg>` | 移除依赖 |
27+
| `mcpp update [pkg]` | 更新依赖 |
28+
| `mcpp search <keyword>` | 搜索包 |
29+
| `mcpp toolchain list` | 查看工具链 |
30+
| `mcpp toolchain install gcc 16` | 安装工具链 |
31+
| `mcpp pack` | 打包 |
32+
| `mcpp self doctor` | 环境诊断 |
33+
| `mcpp explain <CODE>` | 错误码解释 |
34+
35+
## 安装
36+
37+
```bash
38+
# 推荐
39+
xlings install mcpp -y
40+
41+
# 或一键脚本
42+
curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
43+
```
44+
45+
安装到 `~/.mcpp/`，自动加入 PATH。首次运行自动安装 GCC 工具链到隔离沙盒。
46+
47+
## 创建项目
48+
49+
```bash
50+
mcpp new hello && cd hello
51+
mcpp build
52+
mcpp run
53+
```
54+
55+
生成的 `mcpp.toml`：
56+
57+
```toml
58+
[package]
59+
name = "hello"
60+
61+
[targets.hello]
62+
kind = "bin"
63+
main = "src/main.cpp"
64+
```
65+
66+
## mcpp.toml 配置
67+
68+
```toml
69+
[package]
70+
name = "myapp"
71+
version = "0.1.0"
72+
73+
[targets.myapp]
74+
kind = "bin" # bin / lib / shared / test
75+
main = "src/main.cpp"
76+
77+
[dependencies]
78+
gtest = "1.15.2" # SemVer: ^, ~, 范围, 精确
79+
80+
[toolchain]
81+
default = "gcc@16.1.0"
82+
```
83+
84+
更多配置：https://github.com/mcpp-community/mcpp/blob/main/docs/05-mcpp-toml.md
85+
86+
## 工具链
87+
88+
```bash
89+
mcpp toolchain list # 查看已装
90+
mcpp toolchain install gcc 16 # 装 GCC 16
91+
mcpp toolchain install llvm 20 # 装 LLVM 20
92+
mcpp toolchain default gcc@16.1.0 # 设默认
93+
```
94+
95+
## 工作空间
96+
97+
```toml
98+
[workspace]
99+
members = ["libs/*", "apps/*"]
100+
101+
[workspace.dependencies]
102+
gtest = "1.15.2"
103+
```
104+
105+
```bash
106+
mcpp build -p member-name # 构建指定成员
107+
```
108+
109+
## 自定义索引
110+
111+
```toml
112+
[indices]
113+
my-index = "git@gitlab.example.com:team/index.git"
114+
local = { path = "/path/to/index" }
115+
116+
[dependencies.my-index]
117+
internal-lib = "1.0.0"
118+
```
119+
120+
## 常见问题
121+
122+
| 问题 | 解决 |
123+
|---|---|
124+
| 首次构建慢 | 正常，需下载工具链。后续使用缓存 |
125+
| command not found | 重启终端或 `source ~/.bashrc` |
126+
| 编译错误 | `mcpp clean && mcpp build`，确认 `mcpp toolchain list` |
127+
| 依赖找不到 | `mcpp index update`，确认 `mcpp search <name>` |
128+
129+
## 问题反馈
130+
131+
1. **项目 Issue**：https://github.com/mcpp-community/mcpp/issues
132+
- 描述复现步骤、期望/实际行为、mcpp 版本和 OS
133+
- 可用 `gh issue create` 提交
134+
135+
2. **社区论坛**：https://forum.d2learn.org/category/20
136+
- 使用疑问和讨论
137+
138+
如果 AI Agent 无法直接创建 Issue，请提示用户手动创建并提供整理好的问题描述。

0 commit comments

Comments
 (0)