zh

用户文档目录

English | 简体中文

这棵树是 mcpp 已实现功能的使用手册。每一章陈述一个能力做什么、怎么写、 当前边界在哪里。设计理由、被否掉的替代方案、以及尚未发布的规划,不写在这里 —— 它们属于设计记录,而设计记录不是用户文档。

文档的归属

树	读者	内容
docs/**	手上有任务的人	mcpp 已实现的东西怎么用
docs/specs/**	对着机制做实现的人:索引作者、下游工具、贡献者	语义、约束与匹配规则,每条标注实现状态
.agents/docs/**	做过某次改动的人,以及以后问「为什么是这样」的人	推理、实测,以及什么被推翻了
.agents/skills/**	照流程执行的贡献者或 agent	带判据的步骤

章节引用规范以取得精确语义,但不引用设计记录:记录描述的是一个时刻,不带 稳定性承诺,因此读者需要的东西一律写在本树或规范里。

从这里开始

目标	阅读	运行
写一个程序	01、04 §1	01-hello、02-with-deps
写一个供他人 import 的库	11、06、04 §2.4	04-workspace、11-features
发布它	10、11、12	03-pack-static、05-lib-distribution
为另一台机器构建	21、24、40	06-openkal-cross、mcpp new … --template riscv-virt-rt
使用 GPU 或加速器	42、41	09-heterogeneous,从 boundary/ 开始
增加一条规则、一种语言或一个生成器	31、30	08-build-rules、12-a-new-device-language
向索引添加一个包	11、SPEC-001	09 —— 发布相关场景
为别人打包一个工具、一个驱动或一块板子	32、33、34	xim-pkgindex 与 mcpp-index 里的描述符
修改 mcpp 本身	90、92、51	—

课程也可以以项目模板的形式到达:模板由包提供,mcpp new --template 实例化 它。今天有文档的两个是 riscv-virt-rt(裸机)与 ocornut.imgui(图形应用), 用到它的章节会点名。

章节

首位数字就是部分,所以编号本身说明一章属于哪里:

0x	基础
1x	发布
2x	工具链与目标
3x	扩展 mcpp 与它的生态
4x	设备与加速器
5x	程序可以解析的契约
9x	mcpp 自身

同一部分内部的排列是阅读顺序,不是字母序。

0x —— 基础

• 00 —— mcpp 是什么 —— 它是什么、它做什么,以及一段真的跑过的会话
• 01 —— 快速开始 —— 安装、创建、构建、运行
• 02 —— 场景 —— mcpp 被用来做什么,以及每一类工作会用到它的哪些功能
• 03 —— 示例项目 —— 哪个示例教什么
• 04 —— mcpp.toml 工程文件指南 —— manifest 可以说什么
• 05 —— 依赖与解析 —— 依赖从哪里来,以及哪个版本胜出
• 06 —— Feature 与能力 —— 让包的一部分成为可选
• 07 —— 工作空间 —— 多个包,一次构建
• 08 —— 测试 —— 包括在本机跑不了的那些
• 09 —— 按场景选命令 —— 认识名词之后的查阅入口

1x —— 发布

• 10 —— 发布打包
• 11 —— 发布一个库到 mcpp-index
• 12 —— 分发预编译库

2x —— 工具链与目标

• 20 —— 工具链管理
• 21 —— 目标三元组
• 22 —— 目标侧
• 23 —— 项目环境
• 24 —— 基于 openkal 的交叉构建

3x —— 扩展 mcpp 与它的生态

• 30 —— 构建程序:build.mcpp —— 工程需要一步 mcpp 没有规则的工作
• 31 —— 编写规则包 —— 把那一步打包给别的工程用
• 32 —— 编写一个载荷 —— 由 mcpp 安装的工具或预编译库
• 33 —— 编写运行时适配包 —— 够到宿主提供的库
• 34 —— 编写板级支持包 —— 一块板子,以及抵达它的方式

4x —— 设备与加速器

• 40 —— 裸机与 freestanding 目标
• 41 —— 抵达一台设备
• 42 —— 异构硬件构建

5x —— 面向程序的契约

• 50 —— 机器可读输出
• 51 —— 受支持的版本与兼容性

9x —— mcpp 自身

• 90 —— 从源码构建与参与贡献
• 91 —— 工具链机制内幕
• 92 —— 发布 mcpp

反查

上面的章节表是阅读顺序。这里是另一种索引:从读者眼前的一个记号,查到拥有它的 那一章。

manifest 的表与键

	章节		章节
[package]、[targets.<n>]、[build]、[lib]	04	[profile.<n>]、[resources]、[runtime]	04
[dependencies]、[dev-dependencies]、[build-dependencies]	05	scan_overrides、module_extensions	04
[features]、[feature-deps.<f>]、provides / requires	06	[workspace]	07
[toolchain]、cxx_runtime	20	[target.<sel>]、cfg(…)	22
[xlings]、[xlings.workspace]、[feature-xlings.<f>]	23	[pack]	10
[build] accel、[package] accelerators、device_extensions	42	[hooks]	09
[package] platforms、[build] cache	04	[targets.<name>]、[profile.<name>]	04
runner、[target.<t>.runners]	41	rule_module	31

命令

	章节		章节
build、run	01	test	08
new、new --template	01	add、update、why	05
pack	10	publish、emit xpkg、xpkg parse	11
toolchain	20	clean、cache、index、self …	09

概念

	章节		章节
mcpp 是什么,以及那条保证	00	import std、模块接口、BMI	20、30
mcpp::action、构建程序	30	规则包	31
目标三元组、支持矩阵	21	runner、具名 runner	41
岛、接缝、accel、MCPP_EXPORT_C	42	描述符、索引	11
ABI tag、预建产物	12	退出码、JSON 输出	50
xim: 载荷、[xlings.workspace]	32、23	compat: 适配包、runtime.library_dirs	33

规范文档

规范性文档 —— 语义、约束与匹配规则,每条规则标注其实现状态。 面向索引作者、贡献者与下游工具。

• specs/ —— 全部规范的索引
  • SPEC-001 —— 包身份、[dependencies] 选择器与匹配
  • SPEC-002 —— 目标侧模型:保留命名空间、五层、三条规则
  • SPEC-003 —— 退出码契约
  • SPEC-004 —— mcpp.toml 的平面划分、条件化形状、解析轴与命名规约