You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/03-examples.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -81,7 +81,7 @@ the map; the table below is what each sub-example adds.
81
81
| example | first to introduce |
82
82
|---|---|
83
83
|[`08-build-rules`](../examples/08-build-rules/)| two rule packages and a project using both; `host-module = true`, `mcpp::action` with `role = "check"`|
84
-
|[`12-a-new-device-language`](../examples/12-a-new-device-language/)|`device_extensions` and `rule_module`: a rule package teaching mcpp a language the engine has never heard of |
84
+
|[`12-a-new-device-language`](../examples/12-a-new-device-language/)|`device_extensions` and `rule_module`: a rule package teaching mcpp a language the engine has never heard of, whose compiler is a package built through `tools = [...]` for the build machine|
85
85
86
86
[31 — Authoring a Rule Package](31-authoring-a-rule-package.md) is the reference
Copy file name to clipboardExpand all lines: docs/09-commands-by-scenario.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,7 +31,7 @@ them. Confusing them costs a full rebuild.
31
31
| Store | Scope | Growth trigger | Emptied by |
32
32
|---|---|---|---|
33
33
|`target/<triple>/<fingerprint>/`| one project | a configuration fingerprint changes and opens a new directory |`mcpp clean`, `mcpp clean --stale`|
34
-
| the build cache (`mcpp cache dir`) | the whole machine | any project compiles a dependency or a `std` module |`mcpp cache gc`, `mcpp cache prune`, `mcpp cache clean`|
34
+
| the build cache (`mcpp cache dir`) | the whole machine | any project compiles a dependency or a `std` module, or builds a host tool|`mcpp cache gc`, `mcpp cache prune`, `mcpp cache clean`|
35
35
36
36
`mcpp clean` removes `target/` entirely, and the next build recompiles
37
37
everything. `mcpp clean --stale` removes only the fingerprint directories that
Copy file name to clipboardExpand all lines: docs/31-authoring-a-rule-package.md
+78Lines changed: 78 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,6 +16,84 @@ which belong to `mcpp:plugins`. Examples:
16
16
[`12-a-new-device-language`](../examples/12-a-new-device-language/) adds a
17
17
language.
18
18
19
+
## The extension model
20
+
21
+
mcpp's build surface is extended from packages rather than from releases. Five
22
+
points do the extending, and the engine holds no name that comes through any of
23
+
them.
24
+
25
+
| extension point | effect | declared on |
26
+
|---|---|---|
27
+
|`mcpp::action`| one edge in the build graph: a command with declared inputs and outputs | a build program, or a rule module it imports |
28
+
|`device_extensions`| an extension the engine classifies as a **device source** instead of refusing it | a feature of a package |
29
+
|`rule_module`| the module a consumer's build program imports to reach the rule | the same feature |
30
+
|`tools = [...]`| a generator or compiler **built from source for the build machine**, reached with `mcpp::dep_bin`| a dependency edge |
31
+
|`[xlings]`, `[feature-xlings]`| a prebuilt tool the rule runs, installed on demand | the package, or one of its features |
32
+
33
+
What the ecosystem has built out of them:
34
+
35
+
| surface | package | points used |
36
+
|---|---|---|
37
+
| CUDA, HIP, SYCL, Ascend C |`mcpp:plugins`, one feature each ([42](42-heterogeneous-builds.md)) | actions driving a vendor compiler, plus payloads gated on the accelerator |
38
+
| Slang |`mcpp:plugins`' `rules-slang`|`device_extensions = [".slang"]` — the first language mcpp supports without naming it in the engine |
39
+
| GLSL and HLSL to SPIR-V, and the module over the result |`mcpp:plugins`' `rules-spirv`| one action per shader, plus a generated module |
40
+
| the island boundary between a device and C++ |`mcpp.tools.island`| a generator, plus `mcpp::generated`|
41
+
| an asset as a linkable object |[`08-build-rules`](../examples/08-build-rules/)|`role = "object"`|
42
+
| a check that can fail the build |[`08-build-rules`](../examples/08-build-rules/)|`role = "check"`|
43
+
| a language the engine has never heard of |[`12-a-new-device-language`](../examples/12-a-new-device-language/)|`device_extensions`, plus a compiler built through `tools = [...]`|
44
+
45
+
### The shapes the model expresses
46
+
47
+
**A new language, whatever compiles it.** A rule claims the extension, submits
48
+
one action per source, and declares the compiler among that action's inputs.
49
+
The compiler may be a vendor toolkit, an LLVM front end, an interpreter that
50
+
emits a device binary, or a program the rule package builds from source. Whether
51
+
it produces a device binary, an object or C++ is the action's `role` and nothing
52
+
else. The engine never learns the language: it learns that an extension is a
53
+
device source and that an action claims it.
54
+
55
+
**Preprocessing and code generation.** An action with `role = "source"` produces
56
+
C++ that the declaring package then compiles, and every compile edge of that
57
+
package waits for it. The input can be a template, an interface definition, a
58
+
table, or another action's output — chaining is ordinary, because actions are
59
+
ordered and fingerprinted by their files.
60
+
61
+
**A file that is partly C++ and partly another language.** Classification
62
+
happens before any rule runs, so a file with an extension the engine owns is
63
+
compiled as C++ and never reaches a rule. A source carrying a foreign block
64
+
therefore uses an extension the rule claims, and the rule splits it: the C++ it
65
+
extracts goes through `role = "source"`, the foreign half through its own
66
+
compiler, and the seam between the two is the `extern "C"` boundary of
67
+
[42 — Heterogeneous Builds](42-heterogeneous-builds.md). No package in this
68
+
repository ships that shape today.
69
+
70
+
### The boundary
71
+
72
+
**A declaration cannot reclassify what the engine already owns.** A dependency's
73
+
`device_extensions` is consulted *after* the built-in roles, so a rule package
74
+
cannot claim `.cpp`, `.cppm`, `.c` or `.S`. Those are the engine's own
75
+
vocabulary, and a package must not be able to move a file out of it. Claiming
76
+
one is not diagnosed and has no effect: measured by adding `".cpp"` to a rule's
77
+
`device_extensions`, after which the consumer's `main.cpp` was still compiled as
78
+
C++ and the build succeeded.
79
+
80
+
**Module-interface extensions are the project's axis, not a rule's.** A project
81
+
that spells its interfaces `.ixx` declares `[build] module_extensions`
82
+
([04 — The mcpp.toml Project File](04-mcpp-toml.md)). No rule-package key adds
83
+
one, because a module interface is scanned for imports, produces a BMI and joins
84
+
the link — three engine behaviours rather than a command to run.
85
+
86
+
**An extension in neither table is refused by name**, which is why a mistyped
87
+
`device_extensions` surfaces at once instead of dropping a source:
88
+
89
+
```
90
+
error: scanner errors:
91
+
.../orphan.zzz: 'orphan.zzz' is listed in [build] sources, and mcpp has no role
92
+
for the extension '.zzz'.
93
+
Its object would be compiled and then linked by nothing, so this is refused rather
0 commit comments