0.1.1: mcpp.tools.embed, and the decorative markers removed (#2)

* chore: 0.1.1 removes the decorative markers from the rule sources

The rules moved here from the mcpp examples carried the warning and star
markers the sweep removed everywhere else. A consumer compiles these
files, so the version moves with them: mcpp.toml, mcpp::plugins::version
and the README example all read 0.1.1.

No behaviour changes; the edits remove a marker and the space it
occupied.

* 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.

* docs: the README lists the tools member and its floor

---------

Co-authored-by: speak-agent <x.d2learn.org@gmail.com>

Author: Sunrisepeak

.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,5 @@
 target/
-.mcpp/
-mcpp.lock
 compile_commands.json
+mcpp.lock
+.mcpp/
+*.log

README.md

@@ -6,7 +6,7 @@ imports each one from `build.mcpp` under the module name the member declares.
 
 ```toml
 [dependencies.mcpp]
-plugins = { version = "0.1.0", features = ["rules-spirv"], host-module = true }
+plugins = { version = "0.1.1", features = ["rules-spirv"], host-module = true }
 ```
 
 ```cpp
@@ -40,10 +40,12 @@ engine's own module family and is not used here.
 |---|---|---|---|
 | `rules-cuda` | `mcpp.rules.cuda` | 2026.9.5.2 | the toolkit named in `[xlings.workspace]` (`xim:cuda-nvcc`, `xim:cuda-cudart`, and `xim:libcurand` for the clang route, whose wrapper includes a cuRAND header unconditionally), `[build] accel = "cuda…"`, a constrained glob for `*.cu`; the clang route with an LLVM toolchain, the nvcc route with a GCC one |
 | `rules-spirv` | `mcpp.rules.spirv` | 2026.9.5.3 | `xim:glslang` in `[xlings.workspace]`, `[build] accel = "vulkan1.2"`, a constrained glob for the shader stages; emits one header per shader through a `role = "source"` action |
+| `tools-embed` | `mcpp.tools.embed` | 2026.9.5.4 | nothing beyond mcpp: it reads a file and writes a header while the build program runs. The floor is the release whose fast path compares a declared file input, without which an edit to the data does not reach the binary |
 
 The floor is the mcpp release whose engine carries what the member relies on:
 `rules-spirv` needs the device-source table that classifies shader extensions,
-which 2026.9.5.3 introduced. The index descriptor states the floor; a project
+which 2026.9.5.3 introduced, and `tools-embed` needs the fast path to compare a
+declared file input, which 2026.9.5.4 introduced. The index descriptor states the floor; a project
 on an older mcpp is refused at resolution rather than at the first shader.
 
 ## How the engine sees this package

mcpp.toml

@@ -1,7 +1,7 @@
 [package]
 name        = "plugins"
 namespace   = "mcpp"
-version     = "0.1.0"
+version     = "0.1.1"
 description = "Official mcpp build plugins: rule packages under mcpp.rules.*, build-time utilities under mcpp.tools.*, each member selected by a feature"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]
@@ -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"

rules/cuda.cppm

@@ -54,7 +54,7 @@ struct options {
     // Header search paths for the island. Relative entries resolve against the
     // package root; an ABSOLUTE entry is passed through unchanged.
     //
-    // ⭐ THE ABSOLUTE FORM IS FOR A DEPENDENCY'S HEADERS. A device compiler is
+    // THE ABSOLUTE FORM IS FOR A DEPENDENCY'S HEADERS. A device compiler is
     // a separate driver and inherits nothing from the C++ side's include
     // configuration, so a package whose device code includes a dependency's
     // header -- ggml's CUDA backend includes `cublas_v2.h` -- has to name that
@@ -322,7 +322,7 @@ inline bounds read_bounds(std::string_view headerPath) {
 // Does the C library this build compiles against declare the C23 functions
 // `cospi`, `sinpi` and `rsqrt`?
 //
-// ⚠️ Measured 2026-09-05 against glibc 2.44. Toolkit 12.9's
+// Measured 2026-09-05 against glibc 2.44. Toolkit 12.9's
 // `crt/math_functions.h` declares those same names for the host WITHOUT
 // `noexcept`; glibc declares them WITH it, and since C++17 that is part of the
 // function type. nvcc's front end stops with six `exception specification is
@@ -470,7 +470,7 @@ inline std::vector<edge> plan(std::span<const std::string> sources, options opt
         }
         front = { driver_cc, "-x", "cuda", "-std=c++17", "-O2", "-fPIC",
                   "--cuda-path=" + tk->nvcc_root, "-Wno-unknown-cuda-version",
-                  // ⚠️ NVIDIA'S HEADER REFUSES libc++, AND THE REFUSAL IS
+                  // NVIDIA'S HEADER REFUSES libc++, AND THE REFUSAL IS
                   // ABOUT nvcc RATHER THAN ABOUT THIS COMPILER.
                   //
                   //   crt/host_defines.h:67: error: "libc++ is not supported

rules/spirv.cppm

@@ -162,7 +162,7 @@ inline std::string run_and_capture(const std::string& cmd) {
     return text;
 }
 
-// ⚠️ THE OPTIMISER IS OPTIONAL AND ITS ABSENCE IS NOT A BUILD ERROR.
+// THE OPTIMISER IS OPTIONAL AND ITS ABSENCE IS NOT A BUILD ERROR.
 //
 // glslang links spirv-opt only when built with `ENABLE_OPT`, and the payload
 // this ecosystem publishes today is not:
@@ -236,7 +236,7 @@ inline std::string symbol_of(std::string_view stem, std::string_view stage) {
     return s;
 }
 
-// ⚠️ NEWLINE-SEPARATED, not `;`. A path may contain a semicolon and cannot
+// NEWLINE-SEPARATED, not `;`. A path may contain a semicolon and cannot
 // contain a newline, which is why the engine chose it — and why a splitter
 // that guesses wrong still works for exactly one shader and silently produces
 // one impossible path for two.
@@ -305,7 +305,7 @@ inline bool compile(std::span<const std::string> shaders, options opt = {}) {
         const auto input  = std::filesystem::path(src).is_absolute()
                           ? src : root + "/" + src;
 
-        // ⚠️ `id` and `description` are raw pointers the action reads at
+        // `id` and `description` are raw pointers the action reads at
         // `submit()`; `arg`/`input`/`output` copy, these two do not. Held in
         // named strings for the life of the statement that submits.
         const std::string id   = "spirv:" + src;

src/plugins.cppm

@@ -11,6 +11,6 @@ import std;
 
 export namespace mcpp::plugins {
 
-inline constexpr std::string_view version = "0.1.0";
+inline constexpr std::string_view version = "0.1.1";
 
 } // namespace mcpp::plugins

tests/cuda-consumer/mcpp.toml

@@ -64,7 +64,7 @@ include_dirs = ["include"]
 # The CUDA runtime is linked STATICALLY, and only when a device build asks for
 # it. Linking the redistributable half in leaves exactly one host dependency,
 # libcuda.so.1, which the driver owns and the sentinel package reaches.
-# ⭐ NO ABSOLUTE PATHS: the rule package puts the payload's library directory on
+# NO ABSOLUTE PATHS: the rule package puts the payload's library directory on
 # the link line from `mcpp::xpkg_dir`, so this manifest names libraries only.
 [target.'cfg(accelerator = "cuda")'.build]
 ldflags = ["-lcudart_static", "-lrt", "-lpthread", "-ldl"]

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