0.3.0: one surface for every embedded payload, a rule for Slang, and a generated island boundary

[Sunrisepeak]

0.3.0. One surface for every embedded payload, a rule for Slang, a generator for
an island's extern "C" boundary, and the two declarations that let a rule
package introduce a device language without an engine release.

Requires mcpp 2026.9.7.1.

The surface: a payload is reached by importing a module

mcpp::plugins::surface is in the lib root because three rules produce the same
declarations for a consumer and a fourth copy would drift. It writes, from one
description, either a C header or a C++ module interface:

export module myapp.shaders;

extern "C" {
const unsigned int* mcpp_embed_scale_comp_data();
unsigned long       mcpp_embed_scale_comp_size();
}

export namespace myapp::shaders {
struct payload { const unsigned int* code; unsigned long size_bytes; };
inline payload scale_comp() { return { mcpp_embed_scale_comp_data(),
                                       mcpp_embed_scale_comp_size() }; }
}

The consumer writes import myapp.shaders; and myapp::shaders::scale_comp().
Nothing in a project names a generated file, so the rule is free to change where
it writes and how it stores the words.

The interface names no standard-library type, and that is measured rather
than stylistic: an interface carrying std::span puts that header's templates
into every consumer's BMI, at 727 times the size of the std-free form on GCC 16.

The accessor answers with the address and the byte count together. sizeof
is not merely awkward at this boundary, it is unanswerable: under object storage
there is no array to take the size of, and under null_terminate neither
sizeof nor the declared _size is the payload's length.

From a file name to a call

shaders/a/scale.comp becomes myapp::shaders::a::scale_comp(). The directory
below the group's base is part of the namespace, which is what makes two shaders
with one stem in two directories two things rather than a collision -- the
fixture asserts they are DISTINCT objects, because a build that collapsed them
would still print two correct lines. GCC's #pragma once treats two files of the
same size and content as the same file, so before the namespace reached the
symbol name the second include silently did nothing and both accessors returned
one array.

Three storages behind it

header, object and sidecar, each with a fixture that builds and runs. The
crossover is around 1 MB: below it the header is faster to compile than the
assembler round trip; above it the compiler's own parse dominates.

mcpp.rules.slang

Slang is a language rather than a second driver for GLSL, so it has its own rule
and its own extension. -source-embed-style u32, with the output named
<base>_embed.h because slangc appends .h to whatever -o names.

Each rule declares what it compiles, and who compiles it

[features.rules-slang]
sources           = ["rules/slang.cppm"]
device_extensions = [".slang"]
rule_module       = "mcpp.rules.slang"

mcpp 2026.9.7.1 reads both. The engine holds no package name, no feature
spelling and no module name, and .slang is not in its built-in table --
tests/slang-consumer builds and runs anyway, which is the whole criterion.
With the two keys declared, a project that names the feature needs no
build.mcpp at all: tests/spirv-zero-config has neither a build program nor
host-module, and asserts both absences.

mcpp.tools.island: the extern "C" boundary, generated

A member behind tools-island, like tools-embed: nothing in this collection
uses it, a project does.

Entry points are marked where they are defined:

MCPP_EXPORT_C
int saxpy_device(float a, const float* x, const float* y, float* out, unsigned n) { ... }

scan reads the marked declarations, emit writes the boundary header the
island's compiler reads and the module the C++ side imports. The module
re-exports NAMES (export using ::saxpy_device;) rather than restating
signatures, because a second copy of a signature is the thing this exists to
remove.

A seam has two halves, and scan is where they are compared. A device island
and a host fallback implement one boundary and exactly one is in any link. Both
are handed to scan unconditionally; entries merge by name, and two definitions
that declare one name differently are refused there, naming both files and both
signatures. Nothing else catches that: the two never meet at the link and C
language linkage does not mangle, so a disagreement builds cleanly and the
artifact reads its arguments by whichever signature it was compiled with.

The island writes no #include. force_include_flags returns the flags that
make the compiler read the generated header before the island's first line. Those
flags now have somewhere to go: cuda, hip and sycl gained the
options::flags pass-through ascendc already had, because the island is
compiled by a driver mcpp did not invoke and inherits nothing from mcpp::cflag.

The project-wide channels are not merely too wide for that job, they are wrong
for it: cxxflag would force the header into every C++ translation unit,
including a seam .cppm, and a module interface unit must begin with
export module.

The module root is the package's name

module_root_from_package derived it from the leaf of MCPP_MANIFEST_DIR --
a directory name -- because that was the only thing a build program was told.
mcpp 2026.9.7.1 answers the right question, so it reads mcpp::package_name().

Every fixture had a package name equal to its directory name, so neither
derivation was observable. tests/spirv-module-consumer now declares
name = "shader-app" while keeping its directory, and imports
shader_app.shaders; reverting the function makes that import unresolvable.

A generated name may not be a C++ keyword

Six sites ran the same character filter -- letters, digits and _ survive,
everything else becomes _, a leading digit gets a _ -- and none asked whether
the result is reserved. shaders/default/ is an ordinary shader directory name,
and it produced namespace default { in a generated file: an error on a line the
author of that directory has never opened.

surface::identifier owns all three transformations now, with a TRAILING
underscore for a keyword because a leading one is itself reserved at namespace
scope. The accessor is sanitised where it is EMITTED rather than in each
producer -- a rule that builds the name from a file stem cannot know it has
produced my-shader_comp or default until it reaches the line that writes the
function's name.

A module_name whose segment is not an identifier is refused where it was
written, naming the segment and the spelling that would work, rather than in a
generated file.

Four CI criteria that read text where they meant code

Each of these failed and none was about the package.

• The all-rules-compile DENOMINATOR read [features] inline keys, and 0.3.0
  spells features as sub-tables, so it printed
  package: sources sources sources sources and reported the fixture as
  incomplete while the extractor was what broke.
• The duplicate-stem step asserted a refusal this release deliberately removed:
  the directory is now part of the name, so two shaders sharing a stem are two
  payloads. It asserts that instead.
• Two steps grepped a fixture for a symbol or a key that the fixture EXPLAINS in
  a comment it does not use, so each reported the file for saying what it does.
  Comment lines are stripped first now.
• Going the other way, grep 'include' build.mcpp matched that program's own
  comments and its mcpp::include_dir line, so it would have passed with the
  forced include removed. It names force_include_flags.

The last one was found by reading all eighteen assertions that grep a source
file at once, rather than by waiting for another round trip.

Fixtures

Ten, all building and running locally against the 2026.9.7.1 engine:
spirv-consumer, spirv-module-consumer, spirv-zero-config,
spirv-object-storage, spirv-sidecar, embed-consumer,
embed-module-consumer, island-interface, slang-consumer,
all-rules-compile.