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
docs(examples): a real compiler for the device language, and the extension model
`.toy` was "one integer per line, and the entry point returns their sum",
compiled by a shell script. That is not a language, and not a shape any
ecosystem author meets.
THE LANGUAGE. `.toy` now has `let`, assignment, `if`/`else`, `while`, calls
between kernels, and the arithmetic and comparison operators. The grammar is
stated in the README and at the top of `compile.cppm`. The sample source is
Euclid's algorithm and a caller.
THE COMPILER. `toyc/` is an ordinary mcpp package: a lexer, a recursive-descent
parser, semantic checks and a C++ emitter, in three modules and a driver. It is
built FOR THE BUILD MACHINE through `tools = ["toyc"]` + `reexport = true`, and
the rule reaches it with `mcpp::dep_bin`. This is the repository's first
example of a dependency producing a host tool, a capability that until now
existed only in prose.
Four criteria measured: the `.toy` compiles and joins the link
(`answer() = 42`); the language is executed rather than pattern-matched
(`gcd(1071, 462) = 21`, computed by the emitted loop); editing the `.toy`
reaches the artifact (42 to 63); and with the feature removed the build stops
at the module import with no `toyc` in the tool store.
AND ONE BOUNDARY MEASURED. Editing the compiler's SOURCE does not reach the
artifact. The tool store's key is the package identity, version, host triple,
compiler identity, profile, features and the versions of its transitive
dependencies -- it holds no source content. That is exact for a tool from an
index, because a published version is immutable, and not exact for a `path`
dependency being edited: `mcpp run` reported `Finished dev in 0.00s` and
printed the previous answer. Chapter 30 now states it with the two ways out.
CHAPTER 31 GAINS "THE EXTENSION MODEL", which answers what mcpp's plugin system
is and where it is already used: the five extension points with their effect
and where each is declared; seven things the ecosystem has built from them; the
three shapes the model expresses (a new language whatever compiles it,
preprocessing and code generation, and a file that is partly C++ and partly
another language); and the boundary, measured rather than asserted -- a
declaration cannot reclassify an extension the engine owns (adding `.cpp` to a
rule's `device_extensions` is not diagnosed and has no effect), module-interface
extensions are the project's axis, and an extension in neither table is refused
by name, quoted from the run.
build_examples.sh lists `toyc` in BUILD and states why it and the app are two
signals rather than one. 12 of 12.
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