**读者:**在挑一个起点,或者在找一个与自己形状相近的工程的人。
**本章回答的那一个问题:**哪个示例教什么,以及它们以什么顺序相互叠加。
**不在这里:**任何一个示例的内容 —— 每个示例自带 README,只解释它新增的部分。 在此之前:01 —— 快速开始。在此之后: 04 —— mcpp.toml 工程文件指南。
examples/ 目录是一套课程。每个工程都可以单独跑起来,而且每个
工程都教一件更早的示例没有教过的事。本章说明那件事是什么,于是你可以按自己
需要的深度进入,而不必从头读起。
git clone https://github.com/mcpp-community/mcpp
cd mcpp/examples/01-hello
mcpp build && mcpp run每个示例自带 README,只解释它新增的部分。安装与工具链初始化在 01 —— 快速开始,不在示例里重复。
| 示例 | 首次引入的内容 |
|---|---|
01-hello |
一个包、import std、mcpp build 与 mcpp run |
02-with-deps |
[dependencies]、锁文件、mcpp add |
04-workspace |
[workspace]、path 依赖、mcpp build --workspace |
11-features |
声明 feature 而不是消费它,[feature-deps]、[dev-dependencies]、[profile.<name>]、mcpp::has_feature |
| 示例 | 首次引入的内容 |
|---|---|
03-pack-static |
mcpp pack --mode static、[target.<triple>]、[pack] |
05-lib-distribution |
一个库的接口与它的预编译二进制;从同一份源产出 C 头文件与 C++ 模块 |
| 示例 | 首次引入的内容 |
|---|---|
07-project-subos |
[xlings]、[xlings.workspace],以及 PATH 来自工程声明环境的构建程序 |
| 示例 | 首次引入的内容 |
|---|---|
06-openkal-cross |
--target,同一份源在任意宿主上为四台机器构建 |
裸机由模板而不是本目录里的一个工程来教 —— 见下面的以模板形式到达的课程。
09-heterogeneous 按顺序读。它的 README 是
地图;下表是每个子示例新增的部分。
| 示例 | 首次引入的内容 |
|---|---|
…/boundary |
单独的岛边界:消费者 import 一个生成的模块,工程里没有接缝也没有头文件。不需要设备 |
…/cuda |
设备编译器、生成边界之上的接缝、把驱动陈述为 fact 与 floor |
…/vulkan |
一个 compute shader,其 SPIR-V 载荷以模块到达 |
…/sycl |
第二个编译器,自带它自己的标准库 |
…/hip |
手写的边界 —— 与 boundary/ 和 cuda/ 的对照 |
…/cann |
NVIDIA 与 Khronos 谱系之外的厂商 |
…/multi-backend |
多个后端进同一个产物,运行期选择 |
10-graphics/offscreen |
结果是像素的渲染管线,并与软件光栅器逐像素比对 |
| 示例 | 首次引入的内容 |
|---|---|
08-build-rules |
两个规则包与同时使用它们的工程;host-module = true、role = "check" 的 mcpp::action |
12-a-new-device-language |
device_extensions 与 rule_module:规则包教会 mcpp 一门引擎从未听说过的语言,而它的编译器是一个经 tools = [...] 为构建机构建出来的包 |
13-platform-targets |
一份源码、零个 cfg,只改 --target 就为 Linux、WebAssembly 和两个 Android ABI 构建;min_api_level 作为工程自己的决定,以及一条不能被覆盖的能力钉 |
31 —— 编写规则包 是这两个示例所演示内容的参考。
一个包可以提供 templates/<name>/,由 mcpp new --template 实例化。那是与本目录
和章节并列的第三个教学面;当被教的东西属于某个包而不属于 mcpp 时,课程就落在那里。
| 模板 | 课程 | 章节 |
|---|---|---|
riscv-virt-rt |
一个裸机工程、它的板级支持与它的 runner | 40 |
riscv-virt-rt:nolibc |
同上,但没有 C 库 | 40 |
ocornut.imgui |
一个带窗口与渲染栈的图形应用 | 20 |
mcpp new blinky --template riscv-virt-rt一个示例目录是 mcpp.toml + src/ + README.md,编号接在最后一个之后。什么时候
值得新增一个示例:当一个能力改变工程的形状 —— 它包含的文件、它声明的 manifest、
或者作者敲的命令。如果一个能力只是既有示例工程里的一行,它属于对应章节里的一个
代码块;如果它只经由命令到达,它属于
09 —— 按场景选命令。
README 要写明这个示例第一个教什么,以及判断它是否成立的判据。贡献流程见 90 —— 从源码构建 & 参与贡献。