// The payload is a C array in generated source, compiled into the program.

// No assembler involved, so it works on every toolchain including MSVC.

header,

// The payload is a section in an object, reached through `.incbin` in a

// generated `.S`. The bytes never pass through the C++ compiler.

//

// Requires a GAS-capable assembler. Every gcc and clang toolchain has one

// on all three platforms; MSVC does not, and mcpp refuses `.S` under it, so

// the emitter falls back to `header` there and says so once.

object,

// The payload is written beside the artifact and read at run time. The

// program's correctness then depends on its working directory, which is the

// reason this is not the default -- but it is what shader hot-reload needs,

// and what a payload too large to link needs.

sidecar,

// The C++ identifier, already sanitised by the caller: `blur_comp`.

std::string identifier;

// Namespace segments BELOW the group's own, from the payload's directory

// relative to its root: `{"post"}` for `shaders/post/tonemap.frag`. This is

// what keeps two payloads with one stem from colliding, and what makes the

// name a consumer writes say where the payload came from.

std::vector<std::string> name_space;

// The generated data header this payload's bytes arrive in, AS AN

// `#include` WRITES IT -- relative to the directory the caller put on the

// include path, not an absolute path and not a bare file name. The

// generated tree mirrors the payload tree, so two payloads sharing a stem

// in different directories reach different headers, and a bare file name

// could not tell them apart.

std::string data_header;

// The array that header declares, qualified if it sits in a namespace.

// Unused under `storage::object`, where the linker symbol is derived from

// the accessor name instead, and under `storage::sidecar`.

std::string data_symbol;

// The payload file itself, as an absolute path. Required by `object`, whose

// generated `.S` names it in `.incbin`, and by `sidecar`, which copies it.

// The file need not exist yet: `.incbin` resolves its argument at assembly

// time, which is after the action that writes it has run, and that is what

// lets the whole surface be written at plan time.

std::string payload_path;

// Where a sidecar payload is found at run time, relative to the artifact.

std::string sidecar_name;

// The payload's size IN BYTES, as an expression valid where the generated

// implementation writes it. Empty means `sizeof <data_symbol>`.

//

// IT EXISTS BECAUSE `sizeof` IS NOT ALWAYS THE ANSWER. `mcpp.tools.embed`

// can append a terminating zero byte that its own `_size` constant does not

// count, so `sizeof` and `_size` differ by one and only one of them is what

// the payload is. Measured: a group of null-terminated text payloads

// reported one byte too many and the fixture's comparison failed on a

// trailing NUL. A caller that knows the difference states it here rather

// than letting the generator guess.

std::string data_size_expr;

kind surface = kind::module_;

storage store = storage::header;

element elem = element::word32;

// The module a consumer imports, e.g. `myapp.shaders`. The namespace is

// this name with `.` replaced by `::`, which is why there is no second

// field for it: two spellings of one identity drift.

std::string module_name;

// Where the generated interface and implementation are written. The caller

// adds this to the include path when the surface is `c_header`.

std::string out_dir;

// A short phrase naming what produced the payloads, for the generated

// files' first line: "mcpp.rules.spirv".

std::string produced_by;

// ── What this generator is NOT allowed to find out for itself ───────────

//

// THE TWO FIELDS BELOW ARE WHY THIS MODULE IMPORTS ONLY `std`.

//

// They were `mcpp::target_os()` and `mcpp::compiler()`, read here. That

// made the generator unusable anywhere except inside a build program --

// which is the one place it must NOT be the only usable form, because a

// payload dependency can only enter the build graph if the generation is

// an ACTION, and an action's command is a binary. A binary cannot import

// the build-program module: measured, an ordinary build of this package

// fails with "mcpp: failed to read compiled module".

//

// So they are parameters. The caller has both answers already, and a

// generator that takes its inputs rather than reading its environment is

// the same code in a build program and in a tool.

// The target's operating system, as mcpp spells it -- what decides the

// assembly dialect: the section directive and whether a symbol carries a

// leading underscore. Required under `storage::object`; ignored otherwise.

std::string target_os;

// Whether a GAS-compatible assembler exists for this toolchain. False

// under MSVC, which has none, and where mcpp refuses `.S` outright. It is

// the CALLER's answer because the caller knows the compiler; this

// generator degrades `object` to `header` when it is false and reports

// that through `emitted::store` rather than by printing.

bool has_gas_assembler = true;

// The interface unit: a `.cppm` under `module_`, a `.h` under `c_header`.

std::string interface_file;

// The generated `.S` under `storage::object`, empty otherwise. The caller

// adds it to the build the same way it adds the implementation.

std::string assembly_file;

// The storage actually used. Differs from what was asked for when the

// toolchain cannot assemble: MSVC has no GAS, so `object` degrades to

// `header` and this says so rather than leaving the caller to assume.

storage store = storage::header;

// The translation unit defining the accessors. Always a plain `.cpp`.

std::string impl_file;

// Non-empty under `module_`: what the interface unit provides, which the

// caller declares with `mcpp::action::provides` or lets the scan find.

std::string module_name;

// Non-empty under `c_header`: the directory to put on the include path.

std::string include_dir;

std::vector<std::string> out;

for (std::size_t i = 0; i <= name.size();) {

auto dot = name.find('.', i);

auto one = dot == std::string_view::npos ? name.substr(i) : name.substr(i, dot - i);

if (!one.empty()) out.emplace_back(one);

if (dot == std::string_view::npos) break;

i = dot + 1;

}

return out;

std::string s = "mcpp_embed";

auto add = [&](std::string_view part) {

s += '_';

for (char c : part)

s += (std::isalnum(static_cast<unsigned char>(c)) || c == '_') ? c : '_';

};

for (auto const& seg : split_module_name(opt.module_name)) add(seg);

for (auto const& seg : it.name_space) add(seg);

add(it.identifier);

return s;

static constexpr std::string_view kWords[] = {

"alignas", "alignof", "and", "and_eq", "asm", "auto", "bitand", "bitor",

"bool", "break", "case", "catch", "char", "char8_t", "char16_t",

"char32_t", "class", "compl", "concept", "const", "consteval",

"constexpr", "constinit", "const_cast", "continue", "co_await",

"co_return", "co_yield", "decltype", "default", "delete", "do", "double",

"dynamic_cast", "else", "enum", "explicit", "export", "extern", "false",

"float", "for", "friend", "goto", "if", "inline", "int", "long",

"mutable", "namespace", "new", "noexcept", "not", "not_eq", "nullptr",

"operator", "or", "or_eq", "private", "protected", "public", "register",

"reinterpret_cast", "requires", "return", "short", "signed", "sizeof",

"static", "static_assert", "static_cast", "struct", "switch",

"template", "this", "thread_local", "throw", "true", "try", "typedef",

"typeid", "typename", "union", "unsigned", "using", "virtual", "void",

"volatile", "wchar_t", "while", "xor", "xor_eq",

};

for (auto k : kWords) if (k == w) return true;

return false;

std::string s;

for (std::size_t i = 0; i < raw.size(); ++i) {

const char c = raw[i];

s += (std::isalnum(static_cast<unsigned char>(c)) || c == '_') ? c : '_';

}

if (s.empty()) s = std::string(fallback);

if (!s.empty() && std::isdigit(static_cast<unsigned char>(s.front())))

s.insert(s.begin(), '_');

if (is_cxx_keyword(s)) s += '_';

return s;

std::error_code ec;

std::filesystem::create_directories(std::filesystem::path(path).parent_path(), ec);

if (std::ifstream in(path, std::ios::binary); in) {

std::string old((std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>());

if (old == text) return true;

}

std::ofstream out(path, std::ios::binary | std::ios::trunc);

if (!out) return false;

out.write(text.data(), static_cast<std::streamsize>(text.size()));

return static_cast<bool>(out);

std::string s;

for (auto const& one : segs) s += "namespace " + one + " {\n";

return s;

std::string s;

for (auto i = segs.rbegin(); i != segs.rend(); ++i) s += "} // namespace " + *i + "\n";

return s;

const char* elem = element_type(opt.elem);

std::string s = "extern \"C\" {\n";

for (auto const& it : items) {

const auto base = accessor_base(opt, it);

s += std::format("const {}* {}_data();\n", elem, base);

s += std::format("unsigned long {}_size();\n", base);

}

s += "}\n";

return s;

const char* elem = element_type(opt.elem);

std::string s;

s += std::format(

"// The payload, as the device API wants it. Free of standard-library\n"

"// types on purpose: see mcpp.plugins.surface.\n"

"struct payload {{\n"

" const {}* code; // e.g. VkShaderModuleCreateInfo::pCode\n"

" unsigned long size_bytes; // e.g. VkShaderModuleCreateInfo::codeSize\n"

"}};\n\n", elem);

// Grouped by namespace path so a directory's payloads are emitted together

// and each namespace is opened once.

std::vector<std::string> openNow;

auto reopen = [&](const std::vector<std::string>& want) {

if (openNow == want) return;

s += close_namespaces(openNow);

s += open_namespaces(want);

openNow = want;

};

for (auto const& it : items) {

reopen(it.name_space);

const auto base = accessor_base(opt, it);

// THROUGH `identifier`, HERE RATHER THAN IN EACH PRODUCER. This is the

// one line that turns `item::identifier` into something a compiler

// parses, and a rule that builds the field from a file stem cannot know

// it has produced `my-shader_comp` or `default` until it gets here.

s += std::format("inline payload {}() {{ return {{ {}_data(), {}_size() }}; }}\n",

identifier(it.identifier, "payload"), base, base);

}

reopen({});

return s;

if (targetOs == "macos" || targetOs == "macosx" || targetOs == "darwin")

return { ".section __TEXT,__const", "_" };

if (targetOs == "windows") return { ".section .rdata,\"dr\"", "" };

return { ".section .rodata", "" };

std::string_view targetOs) {

const auto d = dialect_for(targetOs);

std::string s =

"// Generated by mcpp.plugins.surface. Do not edit.\n"

"//\n"

"// The payloads, as sections rather than as C arrays. `.incbin` resolves\n"

"// its argument when this file is assembled, which is after the actions\n"

"// that write those files have run.\n";

for (auto const& it : items) {

const auto base = accessor_base(opt, it);

s += std::format("\n {}\n"

" .globl {}{}_begin\n"

" .balign 4\n"

"{}{}_begin:\n"

" .incbin \"{}\"\n"

" .globl {}{}_end\n"

"{}{}_end:\n",

d.section,

d.symbol_prefix, base,

d.symbol_prefix, base,

it.payload_path,

d.symbol_prefix, base,

d.symbol_prefix, base);

}

return s;

emitted out;

out.store = opt.store;

// MSVC HAS NO GAS, AND mcpp REFUSES `.S` UNDER IT. `src/build/prepare.cppm`

// says so outright: "GAS assembly sources (.S/.s) are not supported by the

// MSVC toolchain". Object storage degrades to header storage there rather

// than producing a file the build will refuse, and the SURFACE does not

// change -- the declarations are identical under both.

if (out.store == storage::object && !opt.has_gas_assembler)

out.store = storage::header;

const auto dir = std::filesystem::path(opt.out_dir);

out.interface_file = (dir / (opt.module_name

+ (opt.surface == kind::module_ ? ".cppm" : ".h"))).string();

out.impl_file = (dir / (opt.module_name + ".impl.cpp")).string();

// Named only under the storage that produces one, so a caller can test the

// string rather than having to test the storage a second time.

if (out.store == storage::object)

out.assembly_file = (dir / (opt.module_name + ".payload.S")).string();

if (opt.surface == kind::module_) out.module_name = opt.module_name;

else out.include_dir = dir.string();

return out;

if (items.empty()) return true;

if (opt.module_name.empty()) {

std::cerr << "mcpp.plugins.surface: options::module_name is required; it names both "

"the module a consumer imports and the namespace the declarations sit in\n";

return false;

}

if (opt.out_dir.empty()) {

std::cerr << "mcpp.plugins.surface: options::out_dir is required\n";

return false;

}

const auto segs = split_module_name(opt.module_name);

// REFUSED HERE, NOT IN THE GENERATED FILE. The module name is the one part

// of this surface a project writes itself, and each of its segments becomes

// a namespace. A segment that is not an identifier -- empty, starting with

// a digit, carrying a `-`, or reserved -- produces a generated file that

// does not parse, and the error then names a line nobody wrote.

for (std::size_t i = 0; i < segs.size(); ++i) {

if (segs[i] == identifier(segs[i], "")) continue;

std::cerr << std::format(

"mcpp.plugins.surface: `{}` is not a usable module name: the segment `{}` "

"is not a C++ identifier.\n Each segment becomes a namespace, so it has "

"to be one; `{}` would work.\n",

opt.module_name, segs[i], identifier(segs[i], "part"));

return false;

}

const auto by = opt.produced_by.empty() ? std::string("mcpp.plugins.surface")

: opt.produced_by;

// ONE derivation of the names, shared with the caller. Recomputing them

// here would be the second copy of a decision that this package has paid

// for before.

const emitted out = outputs(opt);

const auto dir = std::filesystem::path(opt.out_dir);

const auto body = declarations(items, opt);

// ---- interface ----

if (which == half::interface_) {

std::string iface;

iface += std::format("// Generated by mcpp.plugins.surface for {}. Do not edit.\n", by);

if (opt.surface == kind::module_)

iface += std::format("export module {};\n\n", opt.module_name);

else

iface += "#pragma once\n\n";

iface += extern_c_declarations(items, opt);

iface += "\n";

// `export` on the opening namespace exports everything the block

// contains, including the nested namespaces a payload's directory

// produced.

if (opt.surface == kind::module_) iface += "export ";

iface += open_namespaces(segs);

iface += "\n" + body + "\n";

iface += close_namespaces(segs);

if (!write_if_different(out.interface_file, iface)) {

std::cerr << std::format("mcpp.plugins.surface: cannot write {}\n",

out.interface_file);

return false;

}

return true;

}

// ---- implementation ---- (half::body from here down)

//

// The one translation unit that defines the accessors. A plain `.cpp` under

// every surface and every storage, because the accessors have C language

// linkage and so need no attachment to the module. What differs between the

// three storages is only where it reads the bytes from.

const char* elem = element_type(opt.elem);

std::string impl;

impl += std::format("// Generated by mcpp.plugins.surface for {}. Do not edit.\n", by);

if (out.store == storage::header) {

impl += "//\n"

"// The only translation unit that includes the generated data headers.\n"

"// Each declares a `static` array, so this is also the only copy of the\n"

"// bytes in the program.\n";

for (auto const& it : items) impl += std::format("#include \"{}\"\n", it.data_header);

impl += "\n";

impl += element_width_assertion(opt.elem);

impl += "\n";

for (auto const& it : items) {

const auto base = accessor_base(opt, it);

const auto size = it.data_size_expr.empty()

? std::format("sizeof {}", it.data_symbol)

: it.data_size_expr;

impl += std::format(

"extern \"C\" const {0}* {1}_data() {{ return {2}; }}\n"

"extern \"C\" unsigned long {1}_size() {{ return {3}; }}\n",

elem, base, it.data_symbol, size);

}

} else if (out.store == storage::object) {

impl += "//\n"

"// The bytes are in a section written by the generated `.S`. This file\n"

"// only names its two boundary symbols, so nothing here parses a payload\n"

"// and the C++ compiler never sees one.\n"

"//\n"

"// The symbols are declared as arrays of the element type rather than as\n"

"// `char`: the assembly aligned the section to four bytes, and a\n"

"// declaration that said `char` would let a consumer reach it through an\n"

"// under-aligned pointer with nothing to notice.\n";

impl += "\n";

impl += element_width_assertion(opt.elem);

impl += "\nextern \"C\" {\n";

for (auto const& it : items) {

const auto base = accessor_base(opt, it);

impl += std::format("extern const {0} {1}_begin[];\n"

"extern const {0} {1}_end[];\n", elem, base);

}

impl += "}\n\n";

for (auto const& it : items) {

const auto base = accessor_base(opt, it);

impl += std::format(

"extern \"C\" const {0}* {1}_data() {{ return {1}_begin; }}\n"

"extern \"C\" unsigned long {1}_size() {{\n"

" return static_cast<unsigned long>(({1}_end - {1}_begin) * sizeof({0}));\n"

"}}\n", elem, base);

}

} else {

impl += "//\n"

"// The payloads are files beside the artifact, read on first use. The\n"

"// path is resolved against the WORKING DIRECTORY, which is the property\n"

"// that makes this storage the one a project opts into rather than the\n"

"// default: a program started from elsewhere finds nothing.\n"

"//\n"

"// Read once and kept: an accessor that reloaded would hand two callers\n"

"// two different pointers to the same payload, and a device API given\n"

"// the second after the first was freed is a defect with no message.\n";

impl += "#include <cstdio>\n#include <cstdlib>\n#include <cstring>\n\n";

impl += element_width_assertion(opt.elem);

impl += std::format(R"IMPL(

)IMPL", elem);

impl += "\n";

for (auto const& it : items) {

const auto base = accessor_base(opt, it);

impl += std::format(

"static blob {0}_blob;\n"

"extern \"C\" const {1}* {0}_data() {{\n"

" return load(\"{2}\", {0}_blob).data;\n"

"}}\n"

"extern \"C\" unsigned long {0}_size() {{\n"

" return load(\"{2}\", {0}_blob).size;\n"

"}}\n", base, elem, it.sidecar_name);

}

}

if (!write_if_different(out.impl_file, impl)) {

std::cerr << std::format("mcpp.plugins.surface: cannot write {}\n", out.impl_file);

return false;

}

if (out.store == storage::object) {

// A CALLER THAT ASKS FOR THIS STORAGE MUST HAVE SAID WHERE THE BYTES

// ARE, AND THE REFUSAL IS WHAT KEEPS THAT TRUE.

//

// `item::payload_path` is documented as required under `object`, and

// today only `mcpp.rules.spirv` reaches this storage and only it sets

// the field. That is a COINCIDENCE, not a guarantee: the first caller

// to give `rules-slang` or `tools-embed` a storage option would get an

// `.incbin ""` in a generated `.S`, and the declaration below would

// then name an empty dependency -- so the build would be wrong in

// exactly the silent way this whole change exists to remove.

//

// A constraint written only in a comment has nothing enforcing it,

// which is a shape this project has recorded before. This is the

// enforcement.

for (auto const& it : items) {

if (!it.payload_path.empty()) continue;

std::cerr << std::format(

"mcpp.plugins.surface: `{}` was given storage::object with no "

"payload_path.\n"

" Under this storage the generated assembly names the payload "

"in `.incbin`, so\n"

" the caller has to say where it is. Set `item::payload_path`, "

"or use storage::header.\n",

it.identifier);

return false;

}

if (!write_if_different(out.assembly_file,

assembly_for(items, opt, opt.target_os))) {

std::cerr << std::format("mcpp.plugins.surface: cannot write {}\n",

out.assembly_file);

return false;

}

}

// `storage::sidecar` needs no counterpart, and that was checked rather than

// assumed. Its payload is never read by a compile: the accessor opens the

// file at RUN time, so a rebuilt payload is picked up by the next run with

// nothing in the build graph to keep current.

return true;

std::string_view fallback = {}) {

std::string leaf{package_name};

if (leaf.empty()) leaf = std::string(fallback);

return identifier(leaf, "app");