feat(example): two routes for the CUDA example, and the pairings it refuses

The example took one route — nvcc driving the project's own compiler — and
that route has two constraints neither the engine nor the project controls.
Both now produce a sentence before anything is compiled, and a second route
exists that has neither.

**clang is the primary route.** `[toolchain] default = "llvm@22.1.8"` and the
device unit is compiled by the same compiler as the rest of the project
(`-x cuda --cuda-path=<payload>`). No second host compiler, no host-compiler
bound, no CUDA host header in the way. `MCPP_EXAMPLE_CUDA_ROUTE` selects the
other route, and the rule declares `rerun_if_env_changed` for it.

**nvcc is the alternate, and it refuses two pairings by name.** The host
compiler must satisfy the bound nvcc states in its own `crt/host_config.h`: the
rule uses the project's toolchain when it fits, otherwise a `xim:gcc` payload
the project declared, otherwise a refusal naming the declaration to add.
Measured — GCC 16 under nvcc 12.9 fails inside GCC's own `<type_traits>` even
with `-allow-unsupported-compiler`, which admits a compiler one step past the
bound and not a standard library two majors newer.

The second pairing is a toolkit older than the C library. Toolkit 12.9's
`crt/math_functions.h` redeclares the C23 functions `cospi`, `sinpi` and
`rsqrt` for the host without `noexcept`; glibc 2.41 and later declare them with
it, and since C++17 that is part of the function type. The compile stops with
six `exception specification is incompatible` errors naming a glibc header and
a CUDA header, and no decision. The rule reads the C library's
`bits/mathcalls.h` through `mcpp::toolchain_sysroot()` and states the pair it
cannot have, naming the 13.x toolkit as the way out.

**A CPU implementation behind the same seam.** `src/cpu/saxpy.cpp` is selected
by `cfg(not(accelerator = "cuda"))` while the `.cu` carries the accel its glob
is for, so `mcpp build --no-accel` compiles one and `mcpp build` the other,
with no hand-written condition on either side.

Measured on an RTX 4080, driver 550.144.03 reporting CUDA 12.4: `mcpp run` and
`mcpp run --no-accel` both print `12 24 36 48`, from different artifact
directories, and the second contains no `cudaMalloc`. The nvcc route is not
exercisable there — 12.9 meets the driver and not the C library, 13.3 meets the
C library and not the driver — and both refusals are the ones above.

Author: speak-agent

examples/09-cuda-kernel/README.md

@@ -6,14 +6,17 @@ What this example demonstrates, and what it does not.
 
 ```
 app/
-  src/kernels/saxpy.cu    the island: compiled by nvcc, never scanned, no BMI
+  src/kernels/saxpy.cu    the island: a device translation unit, never scanned,
+                          no BMI, and compiled only when the build asks for CUDA
+  src/cpu/saxpy.cpp       the same interface implemented for the host, compiled
+                          instead when it does not
   include/saxpy/saxpy.h   the island's interface: extern "C", no std types
   src/app.cppm            the seam: a module that turns the C interface back
                           into a C++ one
   src/main.cpp            an ordinary consumer, which imports the seam and
                           never sees the header
-  build.mcpp              names the sources and the architectures
-rules-cuda/               a build-rule package that knows how to run nvcc
+  build.mcpp              hands the device sources to the rule package
+rules-cuda/               a build-rule package that knows how to compile them
 ```
 
 Three properties are load-bearing.
@@ -24,16 +27,45 @@ imports, never producing a BMI. Its header is classified as a header, so
 editing one still invalidates the fast path.
 
 **The island's interface is `extern "C"` and free of standard-library types.**
-nvcc drives a host compiler that mcpp did not choose, so the two sides do not
-share a C++ ABI and must not exchange anything that depends on one. The island
-also uses no standard library itself, which keeps it from linking a second copy
-of the C++ runtime into a program whose own copy came from mcpp's toolchain.
+The device unit may be compiled by a compiler mcpp did not choose, so the two
+sides do not share a C++ ABI and must not exchange anything that depends on
+one. The island also uses no standard library itself, which keeps it from
+linking a second copy of the C++ runtime into a program whose own copy came
+from mcpp's toolchain.
 
 **The seam exists for backend substitution, not for the module boundary.** It
-is the one place where the island underneath could become HIP or a CPU
-fallback without any consumer of `app.saxpy` changing, and the one place a
-`cfg(accelerator = ...)` section has to apply. Remove it and every importer
-becomes backend-specific.
+is the one place where the island underneath becomes a CPU implementation, or
+could become HIP, without any consumer of `app.saxpy` changing, and the one
+place a `cfg(accelerator = ...)` section has to apply. Remove it and every
+importer becomes backend-specific.
+
+## Two builds from one source tree
+
+The device axis is written once, in the manifest, and the source set follows
+it:
+
+```toml
+[build]
+accel   = "cuda12.9+{sm_89} ptx>=89"
+sources = [
+  "src/*.cppm",
+  "src/*.cpp",
+  { glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" },
+]
+
+[target.'cfg(not(accelerator = "cuda"))'.build]
+sources = ["src/cpu/*.cpp"]
+```
+
+A glob may carry the accelerator it is for. `mcpp build` compiles the `.cu`
+and the CPU file is absent; `mcpp build --no-accel` compiles the CPU file and
+the `.cu` is absent — not excluded by a hand-written condition, but by the
+constraint the glob states. The two land in different artifact directories
+because the device axis is part of the build's identity, so switching between
+them does not rebuild from scratch.
+
+An `--accel` that does not cover a constrained glob is refused before anything
+is compiled, with `accel-mismatch` on the machine-readable channel.
 
 ## Where the toolkit comes from
 
@@ -45,59 +77,120 @@ The project names it:
 "xim:cuda-cudart" = "12.9.79"
 ```
 
-These are payloads, so the version is the project's choice and not the machine's.
-The rule package resolves them with `mcpp::xpkg_dir` and builds the whole
-invocation from what it finds — the compiler, the include directories and the
-library search paths. **No path in this example is absolute**, and a build here
-touches nothing of the host's CUDA:
+These are payloads, so the version is the project's choice and not the
+machine's. The rule package resolves them with `mcpp::xpkg_dir` and builds the
+whole invocation from what it finds — the compiler, the include directories
+and the library search paths. No path in this example is absolute, and a build
+here touches nothing of the host's CUDA:
 
 ```
 $ mcpp build -v | grep -c '/usr/local/cuda\|/usr/bin/nvcc'
 0
 ```
 
-Host locations remain in the rule as a last fallback, so a machine that has only
-a distribution toolkit still builds. They are a fallback, not the design.
-
-⚠️ **The payload's headers have to be named.** nvcc adds
+**The payload's headers have to be named.** nvcc adds
 `<its own directory>/../include` by itself, and on the 12.x line that holds
-`crt/` but not `cuda_runtime.h` — which lives in the `cuda-cudart` component. An
+`crt/` but not `cuda_runtime.h`, which lives in the `cuda-cudart` component. An
 earlier revision of this rule left it out, and nvcc resolved `cuda_runtime.h`
-from `/usr/include` and then read the **host's** `crt/host_config.h` beside it.
-The build failed with the host toolkit's complaint while using the payload's
+from `/usr/include` and then read the host's `crt/host_config.h` beside it. The
+build failed with the host toolkit's complaint while using the payload's
 compiler.
 
-## The rule package, and why nvcc's host compiler is its problem
+## Two routes, and why the primary one is clang
+
+The rule package compiles the device unit either way:
+
+- **clang** (`-x cuda --cuda-path=<payload>`) is the default and what
+  `[toolchain] default = "llvm@22.1.8"` selects. The compiler that builds the
+  rest of the project builds the device unit too. There is no second host
+  compiler, no host-compiler bound, and no CUDA host header in the way.
+- **nvcc** (`-ccbin <host g++>`) is taken when the project's toolchain is GCC.
+  It drives a second compiler, and that is where its constraints come from.
+
+`MCPP_EXAMPLE_CUDA_ROUTE=clang|nvcc` overrides the choice, and the rule
+declares `rerun_if_env_changed` for it.
+
+Two pairings nvcc cannot have, both stated before the compile rather than
+discovered inside it:
+
+- **A host compiler past the bound.** nvcc states a maximum GCC major in its
+  own `crt/host_config.h`. The rule reads it, uses the project's toolchain when
+  it fits, otherwise a `xim:gcc` payload the project declared for this purpose,
+  and otherwise refuses naming the declaration to add. Measured: GCC 16 under
+  nvcc 12.9 fails inside GCC's own `<type_traits>` even with
+  `-allow-unsupported-compiler` — that escape hatch admits a compiler one step
+  past the bound, not a standard library two majors newer.
+- **An old toolkit and a new C library.** Toolkit 12.9's
+  `crt/math_functions.h` redeclares the C23 functions `cospi`, `sinpi` and
+  `rsqrt` for the host without `noexcept`; glibc 2.41 and later declare them
+  with it, and since C++17 that is part of the function type. The compile stops
+  with six `exception specification is incompatible` errors naming a glibc
+  header and a CUDA header, and no decision. The rule reads the C library's
+  `bits/mathcalls.h` through `mcpp::toolchain_sysroot()` and refuses the pair,
+  naming the 13.x toolkit as the way out. The clang route does not include that
+  header at all.
+
+A second compiler also has to be told where it is. `mcpp::toolchain_sysroot()`
+and `mcpp::toolchain_binutils_dir()` are the `--sysroot` and `-B` mcpp passes
+to its own compiler; without forwarding them, NVIDIA's `crt/host_config.h`
+stops at `features.h: No such file or directory`.
+
+Everything about a compiler's spelling lives in the rule package. The engine
+owns the graph, the artifact's identity and the architecture set; it does not
+own `-gencode` or `--cuda-gpu-arch`.
+
+## What the rule reports before the first compile
+
+The rule states machine facts through the build program's own channel, and mcpp
+compares them:
+
+```
+mcpp:fact=cuda.driver=12.4
+mcpp:floor=cuda.driver >= 12.0
+```
 
-nvcc refuses host compilers newer than a bound it states in its own
-`crt/host_config.h`, and mcpp's toolchain payload is routinely newer than that
-bound. The rule reads the bound — from the payload, which states a newer one
-than a distribution toolkit does — selects a host compiler that satisfies it,
-and says which one it chose:
+The fact comes from opening the driver's own library through the
+`libcuda-host-link` sentinel and asking it for its version; the floor comes
+from the toolkit the project named. mcpp refuses a build whose floor is not met
+and says so in one sentence, because the failure it prevents is not a build
+failure:
 
 ```
-example.rules.cuda: nvcc …/xpkgs/xim-x-cuda-nvcc/12.9.86/bin/nvcc with -ccbin …
+error: `cuda-saxpy` requires cuda.driver >= 13.0, and this machine has 12.4.
 ```
 
-`mcpp self doctor` reports the same pairing independently, and reads the same
-payload.
+A separate advisory covers PTX: embedded PTX emitted by a toolkit newer than
+the driver cannot be JIT-compiled by that driver, so hardware outside the named
+architecture set will not run. The named architectures still do, so this is a
+warning rather than a refusal.
 
-Everything about nvcc's spelling lives in the rule package. The engine owns the
-graph, the artifact's identity and the architecture set; it does not own
-`-gencode`.
+The engine holds no vendor name for any of this. `cuda.driver` is a string
+flowing from a declaration to a comparison; a second backend needs no engine
+change. A unit test refuses vendor probes in `src/`.
 
 ## Verified
 
-On an NVIDIA RTX 4080 (compute capability 8.9) with CUDA 12.0 and driver
-550.144.03:
+On an NVIDIA RTX 4080 (compute capability 8.9), driver 550.144.03 reporting
+CUDA 12.4, with an LLVM 22.1.8 toolchain:
 
 ```
 $ mcpp run
-     Running `target/.../bin/cuda-saxpy`
+     Running `target/x86_64-linux-gnu/<accel>/bin/cuda-saxpy`
+12 24 36 48
+
+$ mcpp run --no-accel
+     Running `target/x86_64-linux-gnu/<host>/bin/cuda-saxpy`
 12 24 36 48
 ```
 
-which is `2.0 * [1,2,3,4] + [10,20,30,40]` computed on the device.
+which is `2.0 * [1,2,3,4] + [10,20,30,40]`, computed on the device in the first
+case and on the host in the second. The two artifact directories differ, and
+the CPU one contains no `cudaMalloc`.
+
+The nvcc route is not exercisable on that machine: the 12.9 toolkit meets the
+driver and not the C library, and the 13.3 toolkit meets the C library and not
+the driver. Both refusals are the ones described above, and both name the way
+out.
 
 ## Where the driver comes from
 

examples/09-cuda-kernel/app/build.mcpp

@@ -2,19 +2,20 @@ import std;
 import mcpp;
 import example.rules.cuda;
 
+// Everything the rule needs is in the manifest: the architectures in
+// `[build] accel`, the device sources in the constrained glob, the toolkit
+// under `[xlings.workspace]`. This program names the island's include
+// directory and says "go".
+//
+// The route follows the project's toolchain (clang for an LLVM toolchain,
+// nvcc for a GCC one); MCPP_EXAMPLE_CUDA_ROUTE=nvcc|clang overrides it, which
+// is how the alternate route is measured without editing the manifest.
 int main() {
-    mcpp::rerun_if_changed_glob("src/kernels/**/*.cu");
-    mcpp::rerun_if_changed_glob("include/**/*.h");
-
+    mcpp::rerun_if_env_changed("MCPP_EXAMPLE_CUDA_ROUTE");
     example::rules::cuda::options opt;
-    // RTX 4080 is compute capability 8.9. Named rather than detected: what a
-    // build compiles for is a decision, and a machine's own hardware is a poor
-    // default for it — the artifact would run here and nowhere else.
-    opt.archs = { "sm_89" };
-    // Embed the portable form as well, so the same object runs on hardware
-    // newer than this one.
-    opt.ptx      = "89";
     opt.includes = { "include" };
-    const std::vector<std::string> sources{ "src/kernels/saxpy.cu" };
-    return example::rules::cuda::compile(sources, opt) ? 0 : 1;
+    if (const char* r = std::getenv("MCPP_EXAMPLE_CUDA_ROUTE"); r && *r)
+        opt.which = std::string_view(r) == "nvcc" ? example::rules::cuda::route::nvcc
+                                                   : example::rules::cuda::route::clang;
+    return example::rules::cuda::compile(opt) ? 0 : 1;
 }

examples/09-cuda-kernel/app/mcpp.toml

@@ -2,63 +2,71 @@
 name         = "cuda-saxpy"
 namespace    = "example"
 version      = "0.1.0"
-description  = "A CUDA kernel behind a seam module"
+description  = "A CUDA kernel behind a seam module, with a CPU fallback"
 accelerators = ["cuda"]
 
 [language]
 standard   = "c++23"
 modules    = true
 import_std = true
 
+# The primary route is clang: the toolchain's own clang++ compiles the device
+# unit (`-x cuda`), so there is no second host compiler and no host-compiler
+# bound to satisfy. With a GCC toolchain the rule package takes the nvcc route
+# instead, driving that GCC and reading the bound nvcc states for it.
+[toolchain]
+default = "llvm@22.1.8"
+
 [dependencies]
 rules-cuda = { path = "../rules-cuda", host-module = true }
 
 # The driver's userspace library, reached through an index package that owns
 # the one hop mcpp needs: a directory on the artifact's runtime search path.
 # mcpp's private loader does not consult /usr/lib, so without it the statically
-# linked CUDA runtime cannot dlopen the driver.
+# linked CUDA runtime cannot dlopen the driver. It is the one CUDA component
+# that cannot be an ordinary payload -- the licence forbids redistributing it
+# and it is in ABI lockstep with the kernel module.
 [dependencies.compat]
 cuda-runtime = "2026.09.05"
 
-# The driver's userspace library, reached through the sentinel package.
-#
-# It is the one CUDA component that cannot be an ordinary payload: NVIDIA's
-# driver licence forbids redistributing it, and it is in ABI lockstep with the
-# kernel module, so a version of it is meaningless outside the machine it came
-# from. The sentinel installs a symlink to whatever the host has, which gives
-# mcpp a path it can put on the artifact's runtime search path — mcpp's private
-# loader does not consult /usr/lib, so without this the statically linked CUDA
-# runtime cannot dlopen the driver and reports it as missing.
-# The toolkit this project builds with, named rather than discovered.
-#
-# ⭐ These are PAYLOADS, so the version is the project's choice and not the
-# machine's. The 12.9 line is named on purpose: a runtime must not be newer than
-# the driver it will meet, and 12.x reaches every driver from r525 onward.
-# `mcpp self doctor` reports the pairing.
-#
-# The 12.x `cuda-nvcc` carries its own NVVM back end; on the 13.x line that is a
-# separate `libnvvm` alongside `cuda-crt`, and `cuda-nvcc`'s install hook brings
-# them. Either way the project names the compiler and gets a working one.
+# The toolkit this project builds with, named rather than discovered. These
+# are PAYLOADS, so the version is the project's choice and not the machine's.
+# The 12.9 line is named on purpose: a runtime must not be newer than the
+# driver it will meet, and 12.x reaches every driver from r525 onward. The
+# rule package states the driver relation and mcpp compares it before the
+# first compile.
 [xlings.workspace]
 "xim:cuda-nvcc"         = "12.9.86"
 "xim:cuda-cudart"       = "12.9.79"
 "xim:libcuda-host-link" = { linux = "0.0.1" }
 
 [build]
-# The CUDA runtime is linked STATICALLY. mcpp refuses a dynamic link against
-# the host's libcudart because its private loader does not consult /usr/lib,
-# and it is right to: such an artifact is not self-contained. Linking the
-# redistributable half in leaves exactly one host dependency, libcuda.so.1,
-# which is the driver and genuinely cannot be redistributed — that is what the
-# libcuda-host-link sentinel package in xim exists for.
-accel    = "cuda12.9+{sm_89} ptx>=89"
+# What this build compiles device code FOR. Written once, here: the rule
+# package derives its own flags (`--cuda-gpu-arch`, `-gencode`) from it.
+accel = "cuda12.9+{sm_89} ptx>=89"
+# The device sources carry the accel they are for. Under `--no-accel` the glob
+# is left out and the CPU fallback below takes its place; under an accel that
+# does not cover it the build is refused naming both.
+sources = [
+  "src/*.cppm",
+  "src/*.cpp",
+  { glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" },
+]
 include_dirs = ["include"]
-# ⭐ NO ABSOLUTE PATHS. The CUDA runtime comes from the `cuda-cudart` payload
-# named above, and the rule package puts its library directory on the link line
-# from `mcpp::xpkg_dir` -- so this manifest names libraries, never locations.
-# The one host component left is `libcuda.so.1`, which the driver owns and the
-# `compat.cuda-runtime` dependency reaches.
-ldflags  = ["-lcudart_static", "-lrt", "-lpthread", "-ldl"]
+
+# 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
+# the link line from `mcpp::xpkg_dir`, so this manifest names libraries only.
+[target.'cfg(accelerator = "cuda")'.build]
+ldflags = ["-lcudart_static", "-lrt", "-lpthread", "-ldl"]
+
+# The CPU-only variant: the same seam, a host implementation behind it. This
+# is what `mcpp build --no-accel` produces, and what a machine with no device
+# runs.
+[target.'cfg(not(accelerator = "cuda"))'.build]
+sources = ["src/cpu/*.cpp"]
 
 [targets.cuda-saxpy]
 kind = "bin"

examples/09-cuda-kernel/app/src/cpu/saxpy.cpp

@@ -0,0 +1,11 @@
+// The CPU implementation behind the same seam. Compiled only when the build
+// asks for no accelerator (`mcpp build --no-accel`), through the
+// `cfg(not(accelerator = "cuda"))` section of the manifest; the device island
+// and this file define the same symbol and are never in one link.
+#include "saxpy/saxpy.h"
+
+extern "C" int saxpy_device(float a, const float* x, const float* y,
+                            float* out, unsigned n) {
+    for (unsigned i = 0; i < n; ++i) out[i] = a * x[i] + y[i];
+    return 0;
+}

examples/09-cuda-kernel/rules-cuda/mcpp.toml

@@ -2,5 +2,5 @@
 name        = "rules-cuda"
 namespace   = "example"
 version     = "0.1.0"
-description = "Compile CUDA device translation units with nvcc (role = object)"
+description = "Compile CUDA device translation units: clang -x cuda by default, nvcc as the alternate route (role = object)"
 license     = "Apache-2.0"