English | 简体中文
This tree is the usage manual for what mcpp implements. Each chapter states what a capability does, how it is written, and what its current limits are. The reasoning behind a design, the alternatives that were rejected, and work that is planned rather than shipped are deliberately absent — they belong to the design records, which are not user documentation.
| tree | reader | contents |
|---|---|---|
docs/** |
someone with a task in hand | how to use what mcpp implements |
docs/specs/** |
someone implementing against a mechanism: index authors, downstream tools, contributors | semantics, constraints and matching rules, each tagged with its implementation status |
.agents/docs/** |
whoever made a change, and whoever later asks why it is that way | the reasoning, the measurements, and what was refuted |
.agents/skills/** |
a contributor or agent following a procedure | ordered steps with criteria |
A chapter cites a specification for exact semantics. It does not cite a design record: a record describes a moment and carries no stability promise, so anything a reader needs is written here or in a specification instead.
| To | Read | Run |
|---|---|---|
| write a program | 01, 04 §1 | 01-hello, 02-with-deps |
| write a library others import | 11, 06, 04 §2.4 | 04-workspace, 11-features |
| publish it | 10, 11, 12 | 03-pack-static, 05-lib-distribution |
| build for another machine | 21, 24, 40 | 06-openkal-cross, mcpp new … --template riscv-virt-rt |
| use a GPU or an accelerator | 42, 41 | 09-heterogeneous, starting at boundary/ |
| add a rule, a language or a generator | 31, 30 | 08-build-rules, 12-a-new-device-language |
| add a package to the index | 11, SPEC-001 | 09 — the publishing scenarios |
| package a tool, a driver or a board for others | 32, 33, 34 | the descriptors in xim-pkgindex and mcpp-index |
| change mcpp itself | 90, 92, 51 | — |
Lessons also arrive as project templates, which a package ships and mcpp new --template instantiates. riscv-virt-rt (bare metal) and ocornut.imgui
(a graphical application) are the two documented today; the chapter that uses
one names it.
The first digit is the part, so a number says where a chapter belongs:
0x |
the fundamentals |
1x |
publishing |
2x |
toolchains and targets |
3x |
extending mcpp and its ecosystem |
4x |
devices and accelerators |
5x |
the contracts a program may parse |
9x |
mcpp itself |
Within a part the order is a reading order, not an alphabet.
- 00 — What mcpp Is — what it is, what it does, and one session that has been run
- 01 — Getting Started — install, create, build, run
- 02 — Scenarios — what mcpp is used for, and which features each kind of work uses
- 03 — Examples — which example teaches what
- 04 — The mcpp.toml Manifest — what a manifest may say
- 05 — Dependencies and Resolution — where a dependency comes from, and which version wins
- 06 — Features and Capabilities — making part of a package optional
- 07 — Workspaces — several packages, one build
- 08 — Testing — including what does not run on this machine
- 09 — Commands by Scenario — the lookup, once the nouns are known
- 10 — Packaging an Application for Release
- 11 — Publishing a Library to mcpp-index
- 12 — Distributing a Prebuilt Library
- 20 — Toolchain Management
- 21 — The Target Triple
- 22 — The Target Side
- 23 — The Project Environment
- 24 — Cross-Compilation Over openkal
- 30 — Build Programs:
build.mcpp— a project that needs a step mcpp has no rule for - 31 — Authoring a Rule Package — packaging that step for other projects
- 32 — Authoring a Payload — a tool or a prebuilt library mcpp installs
- 33 — Authoring a Runtime Adapter — reaching a library the host supplies
- 34 — Authoring a Board-Support Package — a board, and the way in
The chapter list above is a reading order. This is the other index: from a token in front of a reader to the chapter that owns it.
Manifest tables and keys
| chapter | chapter | ||
|---|---|---|---|
[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 |
Commands
| chapter | chapter | ||
|---|---|---|---|
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 |
Concepts
| chapter | chapter | ||
|---|---|---|---|
| what mcpp is, and the guarantee | 00 | import std, module interfaces, BMIs |
20, 30 |
mcpp::action, a build program |
30 | a rule package | 31 |
| a target triple, the support matrix | 21 | a runner, a named runner | 41 |
an island, a seam, accel, MCPP_EXPORT_C |
42 | a descriptor, an index | 11 |
| an ABI tag, a prebuilt artifact | 12 | exit codes, JSON output | 50 |
an xim: payload, [xlings.workspace] |
32, 23 | a compat: adapter, runtime.library_dirs |
33 |
Normative documents — semantics, constraints and matching rules, each rule tagged with its implementation status. For index authors, contributors and downstream tooling.