feat: mcpp.tools.embed, the first member of the tools half

A rule states how a translation unit is compiled by a compiler mcpp does
not drive; it submits an action and the engine schedules it. A tool
states something a build program needs that no compiler performs, and
does it while build.mcpp runs. `mcpp.tools.embed` writes a data file into
a header the program compiles in, as a byte array or a 32-bit word array,
with the same reason mcpp.rules.spirv gives for emitting a header rather
than a file beside the binary: the program's correctness stops depending
on its working directory and `mcpp pack` has nothing further to collect.

It does not rewrite an unchanged header. Writing identical bytes would
still move the mtime and rebuild every translation unit that includes it,
which is what makes the tool safe to call unconditionally from a build
program.

The fixture activates `tools-embed` alone, so it also asserts that a
feature adds exactly its own unit: the manifest names no rule and the
build program imports none. Its second run is the measurement the engine
fix in mcpp 2026.9.5.4 exists for -- editing the data file must reach the
binary -- which is why the workflow pins that version.

Author: speak-agent

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ on:
 env:
   # The mcpp release the consumers build with. Raising it is what admits a
   # member that relies on a newer engine; the README states each member's floor.
-  MCPP_VERSION: 2026.9.5.3
+  MCPP_VERSION: 2026.9.5.4
 
 jobs:
   consumers:
@@ -47,6 +47,21 @@ jobs:
           "$MCPP" run | tee run.log
           grep -q '^magic=07230203' run.log
 
+      # A tool, not a rule: the header is written while the build program runs,
+      # so there is no action to schedule. The second build is the measurement
+      # that matters -- editing the data file must reach the binary, which is
+      # the fast-path comparison mcpp 2026.9.5.4 added and the reason this job
+      # pins that version.
+      - name: tools-embed through a consumer
+        working-directory: tests/embed-consumer
+        run: |
+          "$MCPP" run | tee run.log
+          grep -q '^size=33 sum=3189 text=mcpp.tools.embed fixture payload' run.log
+          printf 'changed\n' > data/message.txt
+          "$MCPP" run | tee run2.log
+          grep -q '^size=8 ' run2.log
+          git checkout -- data/message.txt
+
       # Compiles the device unit on a machine with no GPU: the clang route
       # produces sm_89 code from the payload toolkit. Running it needs a
       # device, so the run is of the CPU variant, which the same seam serves.

.gitignore

@@ -1,4 +1,3 @@
 target/
-.mcpp/
-mcpp.lock
 compile_commands.json
+*.log

mcpp.toml

@@ -23,6 +23,7 @@ sources = ["src/plugins.cppm"]
 default     = []
 rules-cuda  = { sources = ["rules/cuda.cppm"] }
 rules-spirv = { sources = ["rules/spirv.cppm"] }
+tools-embed  = { sources = ["tools/embed.cppm"] }
 
 [targets.plugins]
 kind = "lib"

tests/cuda-consumer/.mcpp/.xlings.json

@@ -0,0 +1,14 @@
+{
+  "index_repos": [
+  ],
+  "deps": ["xim:cuda-cccl@12.9.27", "xim:cuda-cudart@12.9.79", "xim:cuda-nvcc@12.9.86", "xim:libcuda-host-link@0.0.1", "xim:libcurand@10.3.10.19"],
+  "workspace": {
+    "cuda-cccl": "xim:12.9.27",
+    "cuda-cudart": "xim:12.9.79",
+    "cuda-nvcc": "xim:12.9.86",
+    "libcuda-host-link": "xim:0.0.1",
+    "libcurand": "xim:10.3.10.19"
+  },
+  "lang": "en",
+  "mirror": "auto"
+}

tests/cuda-consumer/mcpp.lock

@@ -0,0 +1,13 @@
+# Auto-generated by mcpp. Do not edit by hand.
+# Records what this build resolved. It does not yet pin future builds:
+# index dependencies are re-resolved from their constraints each time.
+# dev-dependencies are excluded: only `mcpp test` resolves them, and this
+# file must not change depending on which command ran last.
+version = 2
+
+[package."compat.cuda-runtime"]
+namespace = "compat"
+version = "2026.09.05"
+source  = "index+compat@2026.09.05"
+hash    = "fnv1a:058be04055328f65"
+

tests/embed-consumer/build.mcpp

@@ -0,0 +1,10 @@
+import std;
+import mcpp;
+import mcpp.tools.embed;
+
+int main() {
+    mcpp::tools::embed::options opt;
+    opt.name_space     = "fixture";
+    opt.null_terminate = true;
+    return mcpp::tools::embed::file("data/message.txt", opt) ? 0 : 1;
+}

tests/embed-consumer/data/message.txt

@@ -0,0 +1 @@
+mcpp.tools.embed fixture payload

tests/embed-consumer/mcpp.toml

@@ -0,0 +1,20 @@
+# Fixture: a consumer that activates only `tools-embed`. It proves the second
+# half of the collection's naming rule -- a member that is not a rule, imported
+# under `mcpp.tools.<x>` -- and that a feature adds exactly its own unit: this
+# manifest never names a rule and the build program never imports one.
+[package]
+name        = "embed-consumer"
+version     = "0.1.0"
+description = "Fixture: embeds a data file through mcpp.tools.embed"
+
+[language]
+standard   = "c++23"
+modules    = true
+import_std = true
+
+[dependencies.mcpp]
+plugins = { path = "../..", features = ["tools-embed"], host-module = true }
+
+[targets.embed-consumer]
+kind = "bin"
+main = "src/main.cpp"

tests/embed-consumer/src/main.cpp

@@ -0,0 +1,11 @@
+#include <cstddef>
+#include <cstdio>
+#include "message_txt.h"
+
+int main() {
+    unsigned sum = 0;
+    for (std::size_t i = 0; i < fixture::message_txt_size; ++i) sum += fixture::message_txt[i];
+    std::printf("size=%zu sum=%u text=%s", fixture::message_txt_size, sum,
+                reinterpret_cast<const char*>(fixture::message_txt));
+    return fixture::message_txt[fixture::message_txt_size] == 0 ? 0 : 1;
+}

tests/spirv-consumer/.mcpp/.xlings.json

@@ -0,0 +1,10 @@
+{
+  "index_repos": [
+  ],
+  "deps": ["xim:glslang@15.1.0"],
+  "workspace": {
+    "glslang": "xim:15.1.0"
+  },
+  "lang": "en",
+  "mirror": "auto"
+}