// mcpp.plugins: the collection's shared library.

//

// Every member of this package is a module interface unit under rules/ or

// tools/, compiled as a host module of its own when the consumer's feature

// request names it. This unit is the lib root: it is compiled before every

// member, so a member may import it.

//

// IT HOLDS WHAT MORE THAN ONE MEMBER NEEDS, AND ONLY THAT.

//

// The lib root is the only unit every member can import. A second unit beside

// it in `[build] sources` is NOT compiled as a host module ahead of the

// members. Measured: a member importing a second lib-root unit failed with

//

// mcpp.plugins.surface: error: failed to read compiled module

// note: imports must be built before being imported

//

// because only the lib root is built first. So shared code lives here rather

// than in a file of its own, and a member that needs it writes

// `import mcpp.plugins;`.

module;

#include <cctype>

export module mcpp.plugins;

import std;

// NO `import mcpp;`. That module exists only inside a build program, and this

// unit has to compile into an ordinary binary too: `mcpp.tools.embed`'s

// executable form is what lets a generated `.S` be an ACTION's output, which

// is the only way the payload it embeds can be a declared input of the edge

// that assembles it. Measured before this: an ordinary build of this package

// failed with `mcpp: failed to read compiled module`.

//

// Everything this unit used to read from that module -- the target OS, whether

// the toolchain has a GAS assembler, the package's name -- is now a parameter.

// The members under rules/ still import it; they are feature-gated, so the

// tool's own build never compiles them.

export namespace mcpp::plugins {

// THIS MUST EQUAL `[package] version` IN mcpp.toml, AND CI CHECKS THAT IT DOES.

//

// It was `0.1.1` while the package was `0.2.6`, which nothing noticed because

// nothing read it. A value that is recorded and never read cannot be wrong in a

// way anyone sees, so the fix is not only to correct it: every rule now states

// it with `mcpp::fact`, which makes a build log answer "which collection

// produced these actions" and makes a stale constant a visible defect rather

// than a dormant one.

//

// One package, one version: the number lives in mcpp.toml, and the CI step

// `the collection states its own version` compares the two.

inline constexpr std::string_view version = "0.19.0";

} // namespace mcpp::plugins

// mcpp::plugins::stage -- what the engine wrote beside a staged tree.

//

// SHARED BECAUSE TWO DIST MEMBERS READ IT. `mcpp pack` writes

// `<staged tree>.stage-manifest` (mcpp's docs/50, "The stage manifest"): a

// header, one `needs` line per library name the closure read (mcpp

// 2026.9.14.2+), and the list of staged files. `dist-apk` reads it to trust the

// native libraries under `lib/`, and `dist-apple` reads it to tell the dylibs

// staged beside a program from the resources staged there. Only the header and

// the `needs` lines are parsed; the file list is not.

export namespace mcpp::plugins::stage {

struct need {

std::string name; // as the needing object spells it

std::string where; // a staged path relative to the tree, `platform` or `unresolved`

};

struct manifest {

bool found = false; // the file exists beside the tree

bool walked = true; // `closure = walked`

std::string reason; // `reason = ...`, with `closure = not-walked`

std::vector<need> needs;

};

inline manifest read_manifest(std::string tree) {

manifest m;

while (tree.size() > 1 && (tree.back() == '/' || tree.back() == '\\'))

tree.pop_back();

std::ifstream in(tree + ".stage-manifest", std::ios::binary);

if (!in) return m;

m.found = true;

std::string line;

while (std::getline(in, line)) {

if (!line.empty() && line.back() == '\r') line.pop_back();

if (line == "closure = not-walked") { m.walked = false; continue; }

if (line.starts_with("reason = ")) { m.reason = line.substr(9); continue; }

if (!line.starts_with("needs\t")) continue;

const auto second = line.find('\t', 6);

if (second == std::string::npos) continue;

m.needs.push_back({ line.substr(6, second - 6), line.substr(second + 1) });

}

return m;

}

} // namespace mcpp::plugins::stage

// mcpp::plugins::xml -- the XML two dist members read and write.

//

// SHARED BECAUSE TWO DIST MEMBERS READ IT. `dist-apk` merges library manifests

// into an application's, and `dist-apple` adds a project's Info.plist entries

// and reads the plist a provisioning profile carries. Neither needs more than

// elements, attributes and text, and neither interprets an entity, so this is

// that much and no more: no namespaces resolved, no DTD read, no validation.

export namespace mcpp::plugins::xml {

// A tree of elements and text. Comments, the XML declaration and a DOCTYPE are

// read and dropped: the documents this member writes from a tree are generated

// files, and a merged manifest carries no author to read a comment. Attribute

// values are kept exactly as written, entities included, because nothing here

// interprets them beyond comparing and substituting `${applicationId}`.

struct node {

std::string name; // empty: a text node

std::vector<std::pair<std::string, std::string>> attrs;

std::vector<node> children;

std::string text; // a text node's characters

};

struct reader {

std::string_view s;

std::size_t i = 0;

std::string error;

static bool space(char c) { return c == ' ' || c == '\t' || c == '\n' || c == '\r'; }

bool starts(std::string_view t) const { return s.substr(i, t.size()) == t; }

void skip_space() { while (i < s.size() && space(s[i])) ++i; }

bool skip_past(std::string_view end) {

const auto p = s.find(end, i);

if (p == std::string_view::npos) { i = s.size(); return false; }

i = p + end.size();

return true;

}

std::string name() {

const std::size_t b = i;

while (i < s.size() && !space(s[i]) && s[i] != '>' && s[i] != '/' && s[i] != '=') ++i;

return std::string(s.substr(b, i - b));

}

bool element(node& out) {

++i; // '<'

out.name = name();

if (out.name.empty()) { error = "an element without a name"; return false; }

for (;;) {

skip_space();

if (i >= s.size()) { error = "<" + out.name + "> is not terminated"; return false; }

if (starts("/>")) { i += 2; return true; }

if (s[i] == '>') { ++i; break; }

std::string attr = name();

skip_space();

if (attr.empty() || i >= s.size() || s[i] != '=') {

error = "an attribute of <" + out.name + "> has no value";

return false;

}

++i;

skip_space();

if (i >= s.size() || (s[i] != '"' && s[i] != '\'')) {

error = "attribute " + attr + " of <" + out.name + "> is not quoted";

return false;

}

const char quote = s[i++];

const auto end = s.find(quote, i);

if (end == std::string_view::npos) { error = "attribute " + attr + " is not terminated"; return false; }

out.attrs.emplace_back(std::move(attr), std::string(s.substr(i, end - i)));

i = end + 1;

}

for (;;) {

if (i >= s.size()) { error = "<" + out.name + "> is not closed"; return false; }

if (starts("</")) {

i += 2;

const std::string closing = name();

skip_space();

if (closing != out.name || i >= s.size() || s[i] != '>') {

error = "</" + closing + "> closes <" + out.name + ">";

return false;

}

++i;

return true;

}

if (starts("<!--")) { if (!skip_past("-->")) { error = "a comment is not terminated"; return false; } continue; }

if (starts("<?")) { if (!skip_past("?>")) { error = "a processing instruction is not terminated"; return false; } continue; }

if (starts("<![CDATA[")) {

const std::size_t b = i;

if (!skip_past("]]>")) { error = "a CDATA section is not terminated"; return false; }

node t;

t.text = std::string(s.substr(b, i - b));

out.children.push_back(std::move(t));

continue;

}

if (s[i] == '<') {

node child;

if (!element(child)) return false;

out.children.push_back(std::move(child));

continue;

}

const std::size_t b = i;

auto end = s.find('<', i);

if (end == std::string_view::npos) end = s.size();

i = end;

bool blank = true;

for (std::size_t j = b; j < end; ++j) if (!space(s[j])) { blank = false; break; }

if (!blank) {

node t;

t.text = std::string(s.substr(b, end - b));

out.children.push_back(std::move(t));

}

}

}

bool document(node& root) {

for (;;) {

skip_space();

if (starts("<?")) { skip_past("?>"); continue; }

if (starts("<!--")) { skip_past("-->"); continue; }

if (starts("<!DOCTYPE")) { skip_past(">"); continue; }

break;

}

if (i >= s.size() || s[i] != '<') { error = "no root element"; return false; }

if (!element(root)) return false;

return true;

}

};

inline bool parse(std::string_view text, node& root, std::string& error) {

reader r{text};

if (!r.document(root)) { error = r.error; return false; }

return true;

}

inline std::string trim_copy(const std::string& s) {

std::size_t b = 0, e = s.size();

while (b < e && reader::space(s[b])) ++b;

while (e > b && reader::space(s[e - 1])) --e;

return s.substr(b, e - b);

}

inline void write(const node& n, std::string& out, int depth) {

const std::string pad(static_cast<std::size_t>(depth) * 4, ' ');

if (n.name.empty()) { out += pad + trim_copy(n.text) + "\n"; return; }

out += pad + "<" + n.name;

for (auto const& a : n.attrs) out += " " + a.first + "=\"" + a.second + "\"";

if (n.children.empty()) { out += "/>\n"; return; }

if (n.children.size() == 1 && n.children.front().name.empty()) {

out += ">" + n.children.front().text + "</" + n.name + ">\n";

return;

}

out += ">\n";

for (auto const& c : n.children) write(c, out, depth + 1);

out += pad + "</" + n.name + ">\n";

}

inline std::string attr_of(const node& n, std::string_view key) {

for (auto const& a : n.attrs) if (a.first == key) return a.second;

return {};

}

inline void set_attr(node& n, const std::string& key, const std::string& value) {

for (auto& a : n.attrs) if (a.first == key) { a.second = value; return; }

n.attrs.emplace_back(key, value);

}

} // namespace mcpp::plugins::xml

// mcpp::plugins::json -- the JSON two dist members read.

//

// SHARED BECAUSE TWO DOCUMENTS ARE READ WITH IT. `dist-apk` reads coursier's

// resolution report, and `mcpp::plugins::graph` below reads the engine's graph

// document for `dist-apk` and `dist-apple`. A second parser for the second

// document is how two readers come to disagree about one file, so there is one.

// It reads objects, arrays, strings (with `\u` escapes, surrogate pairs

// included, and a refusal for a surrogate that is not part of one), numbers,

// `true`, `false` and `null`; a number keeps its spelling in `text`.

export namespace mcpp::plugins::json {

struct value {

enum class kind { null, boolean, number, string, array, object };

kind type = kind::null;

std::string text; // string, number or boolean spelling

std::vector<value> items;

std::vector<std::pair<std::string, value>> members;

const value* get(std::string_view key) const {

for (auto const& m : members) if (m.first == key) return &m.second;

return nullptr;

}

};

struct reader {

std::string_view s;

std::size_t i = 0;

void skip_space() {

while (i < s.size() && (s[i] == ' ' || s[i] == '\t' || s[i] == '\n' || s[i] == '\r')) ++i;

}

// The four hexadecimal digits of one `\u` escape, `i` already past the `u`.

bool hex4(unsigned& cp) {

if (i + 4 > s.size()) return false;

cp = 0;

for (int k = 0; k < 4; ++k) {

const char h = s[i++];

cp <<= 4;

if (h >= '0' && h <= '9') cp |= static_cast<unsigned>(h - '0');

else if (h >= 'a' && h <= 'f') cp |= static_cast<unsigned>(h - 'a' + 10);

else if (h >= 'A' && h <= 'F') cp |= static_cast<unsigned>(h - 'A' + 10);

else return false;

}

return true;

}

bool string(std::string& out) {

if (i >= s.size() || s[i] != '"') return false;

++i;

while (i < s.size() && s[i] != '"') {

if (s[i] != '\\') { out += s[i++]; continue; }

if (++i >= s.size()) return false;

const char e = s[i++];

switch (e) {

case 'n': out += '\n'; break;

case 't': out += '\t'; break;

case 'r': out += '\r'; break;

case 'b': out += '\b'; break;

case 'f': out += '\f'; break;

case 'u': {

// A code point above U+FFFF reaches JSON as a surrogate

// PAIR, which is two `\u` escapes. Encoding each half on its

// own produces two three-byte sequences holding unpaired

// surrogates -- not UTF-8, and accepted by nothing that

// reads the manifest this value is written into. The pair is

// combined here, and a surrogate that is not part of one is

// refused, so a malformed document is a refusal rather than

// a silently corrupted string.

unsigned cp = 0;

if (!hex4(cp)) return false;

if (cp >= 0xd800 && cp <= 0xdbff) {

if (i + 6 > s.size() || s[i] != '\\' || s[i + 1] != 'u') return false;

i += 2;

unsigned lo = 0;

if (!hex4(lo)) return false;

if (lo < 0xdc00 || lo > 0xdfff) return false;

cp = 0x10000 + ((cp - 0xd800) << 10) + (lo - 0xdc00);

} else if (cp >= 0xdc00 && cp <= 0xdfff) {

return false; // a low surrogate with no high half

}

if (cp < 0x80) out += static_cast<char>(cp);

else if (cp < 0x800) { out += static_cast<char>(0xc0 | (cp >> 6)); out += static_cast<char>(0x80 | (cp & 0x3f)); }

else if (cp < 0x10000) { out += static_cast<char>(0xe0 | (cp >> 12)); out += static_cast<char>(0x80 | ((cp >> 6) & 0x3f)); out += static_cast<char>(0x80 | (cp & 0x3f)); }

else {

out += static_cast<char>(0xf0 | (cp >> 18));

out += static_cast<char>(0x80 | ((cp >> 12) & 0x3f));

out += static_cast<char>(0x80 | ((cp >> 6) & 0x3f));

out += static_cast<char>(0x80 | (cp & 0x3f));

}

break;

}

default: out += e;

}

}

if (i >= s.size()) return false;

++i;

return true;

}

bool parse_value(value& out) {

skip_space();

if (i >= s.size()) return false;

const char c = s[i];

if (c == '"') { out.type = value::kind::string; return string(out.text); }

if (c == '{') {

out.type = value::kind::object;

++i;

skip_space();

if (i < s.size() && s[i] == '}') { ++i; return true; }

for (;;) {

skip_space();

std::string key;

if (!string(key)) return false;

skip_space();

if (i >= s.size() || s[i] != ':') return false;

++i;

value v;

if (!parse_value(v)) return false;

out.members.emplace_back(std::move(key), std::move(v));

skip_space();

if (i < s.size() && s[i] == ',') { ++i; continue; }

if (i < s.size() && s[i] == '}') { ++i; return true; }

return false;

}

}

if (c == '[') {

out.type = value::kind::array;

++i;

skip_space();

if (i < s.size() && s[i] == ']') { ++i; return true; }

for (;;) {

value v;

if (!parse_value(v)) return false;

out.items.push_back(std::move(v));

skip_space();

if (i < s.size() && s[i] == ',') { ++i; continue; }

if (i < s.size() && s[i] == ']') { ++i; return true; }

return false;

}

}

const std::size_t b = i;

while (i < s.size() && s[i] != ',' && s[i] != '}' && s[i] != ']' &&

s[i] != ' ' && s[i] != '\n' && s[i] != '\r' && s[i] != '\t') ++i;

out.text = std::string(s.substr(b, i - b));

if (out.text == "null") out.type = value::kind::null;

else if (out.text == "true" || out.text == "false") out.type = value::kind::boolean;

else out.type = value::kind::number;

return !out.text.empty();

}

};

// The whole text is one value, with nothing but white space after it.

inline bool parse_json(std::string_view text, value& out) {

reader r{text};

if (!r.parse_value(out)) return false;

r.skip_space();

return r.i == r.s.size();

}

// A string member of an object, or empty when absent or not a string.

inline std::string string_of(const value* v) {

return v && v->type == value::kind::string ? v->text : std::string();

}

} // namespace mcpp::plugins::json

// mcpp::plugins::graph -- the resolved dependency graph the engine states.

//

// mcpp 2026.9.16.1 gives the ROOT project's build program `MCPP_GRAPH_FILE`

// (`mcpp::graph_file()`), a document naming every package of the resolved graph,

// dependencies before their requesters, each with its manifest directory and its

// `[package.metadata]` verbatim (mcpp docs/30, "Reading the resolved graph"). A

// member that merges what libraries contribute reads a table of its own out of

// that metadata: `[package.metadata.dist-apk]`, `[package.metadata.dist-apple]`.

//

// READ THROUGH THE ENVIRONMENT, NOT `mcpp::graph_file()`. This unit does not

// import `mcpp` (see the top of this file), and a member that called the

// accessor would not compile against an engine older than the one that added it.

// An unset or empty variable is an older engine, or a dependency's program, and

// reads as a graph with no packages, which leaves every member's behaviour as it

// was.

export namespace mcpp::plugins::graph {

struct package {

std::string canonical; // `namespace.name@version`

std::string name;

std::string namespace_;

std::string version;

bool root = false;

std::string manifest_dir; // absolute

json::value metadata; // the package's [package.metadata], an object

};

struct document {

bool present = false; // MCPP_GRAPH_FILE named a file

std::string path;

std::vector<package> packages; // dependencies before requesters

};

// The graph this build program was given, or the reason it cannot be read. A

// variable naming a file that is missing or not a `mcpp.graph` document is an

// error rather than an empty graph: the engine promised a document, and reading

// nothing would silently drop every contribution.

inline std::expected<document, std::string> read() {

document d;

const char* env = std::getenv("MCPP_GRAPH_FILE");

if (!env || !*env) return d;

d.present = true;

d.path = env;

std::ifstream in(d.path, std::ios::binary);

if (!in)

return std::unexpected(std::format("the graph document {} cannot be read", d.path));

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

json::value doc;

if (!json::parse_json(text, doc) || doc.type != json::value::kind::object)

return std::unexpected(std::format("the graph document {} is not JSON", d.path));

if (json::string_of(doc.get("kind")) != "mcpp.graph")

return std::unexpected(std::format("the graph document {} is not a mcpp.graph document", d.path));

const json::value* list = doc.get("packages");

if (!list || list->type != json::value::kind::array)

return std::unexpected(std::format("the graph document {} has no packages array", d.path));

for (auto const& entry : list->items) {

if (entry.type != json::value::kind::object) continue;

package p;

if (const json::value* id = entry.get("package")) {

p.canonical = json::string_of(id->get("canonical"));

p.name = json::string_of(id->get("name"));

p.namespace_ = json::string_of(id->get("namespace"));

p.version = json::string_of(id->get("version"));

}

if (const json::value* r = entry.get("root"))

p.root = r->type == json::value::kind::boolean && r->text == "true";

p.manifest_dir = json::string_of(entry.get("manifest_dir"));

if (const json::value* m = entry.get("metadata"); m && m->type == json::value::kind::object)

p.metadata = *m;

d.packages.push_back(std::move(p));

}

return d;

}

// The package's `[package.metadata.<tool>]` table, or null.

inline const json::value* table_of(const package& p, std::string_view tool) {

const json::value* t = p.metadata.get(tool);

return t && t->type == json::value::kind::object ? t : nullptr;

}

// A path a package states, made absolute against its manifest directory.

inline std::string resolve(const package& p, const std::string& path) {

if (path.empty() || std::filesystem::path(path).is_absolute()) return path;

return (std::filesystem::path(p.manifest_dir) / path).lexically_normal().string();

}

// How a diagnostic names a package: its canonical identity, or its name.

inline std::string label_of(const package& p) {

return !p.canonical.empty() ? p.canonical : p.name;

}

} // namespace mcpp::plugins::graph

// mcpp::plugins::names -- the derivations that turn a path into a C++ name.

//

// THESE ARE SHARED BECAUSE THEY WERE COPIED. `common_base_dir` and

// `namespace_of` were written in `rules/spirv.cppm` and written again in

// `rules/slang.cppm`, and `mcpp.tools.island` is the third caller needing the

// same answers. Two copies that agree today are still two copies: a directory

// named `default` or `2d` has to get ONE answer, and one function is how that

// is guaranteed rather than two files that happen to say the same thing.

export namespace mcpp::plugins::names {

// `a` made relative to the directory `b`, as strings: separators unified, and

// the prefix stripped when `a` lies under `b`; `a` unchanged otherwise.

//

// NOTHING IN THIS PACKAGE INSTANTIATES `std::filesystem::path`'s ITERATOR --

// see `components()` below for the compiler that refuses it. The members'

// relative-path arithmetic is this string function, defined once here.

inline std::string relative_to(std::string a, std::string b) {

for (auto& c : a) if (c == '\\') c = '/';

for (auto& c : b) if (c == '\\') c = '/';

while (!b.empty() && b.back() == '/') b.pop_back();

if (!b.empty() && a.starts_with(b + "/")) return a.substr(b.size() + 1);

return a;

}

// A GENERATED NAME THE C++ COMPILER WILL ACCEPT.

//

// Three transformations, and the third is the one every hand-rolled copy of

// this function was missing. Non-identifier characters become `_`; a leading

// digit gets a `_` in front; and a result that is a KEYWORD gets a trailing `_`.

//

// The keyword case is not hypothetical. The first two rules accept `default`,

// `template`, `operator`, `private` and `union` unchanged -- they are valid

// identifiers to a character filter and reserved to the compiler -- and

// `shaders/default/` is an ordinary name for a shader directory. What it

// produced was `namespace default {` in a generated file, and an error naming a

// line its author never wrote.

//

// TRAILING `_`, not a prefix: `_default` is reserved at namespace scope

// (a leading underscore in the global namespace), and prefixing would trade one

// reserved name for another.

//

// The list is the keywords of the standard this collection targets. A word that

// is contextual rather than reserved (`final`, `override`, `import`, `module`)

// is a legal identifier and is left alone.

inline bool is_cxx_keyword(std::string_view w) {

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;

}

// `fallback` is used when the input sanitises to nothing, which a file named

// only in punctuation does.

//

// INDEXED RATHER THAN A RANGE-FOR over the string, for the reason recorded in

// `mcpp.tools.island`: iterating a `std::string` inside an exported inline

// function makes GCC 16 instantiate its iterator in this BMI, and a consumer's

// build program then fails to compile on `always_inline` in a header naming

// neither this file nor this loop.

inline std::string identifier(std::string_view raw, std::string_view fallback) {

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;

}

// ---- internals -------------------------------------------------------------

inline std::vector<std::string> split_module_name(std::string_view name) {

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;

}

// THE BASE DIRECTORY IS DERIVED, NOT ASKED FOR.

//

// A payload's namespace comes from where it sits relative to the tree the

// project globbed, so something has to say where that tree starts. Asking the

// project would put a second spelling of the glob in the manifest, and the two

// would disagree the first time a glob moved. The shallowest directory every

// path shares is the same answer without the second spelling: for

// `shaders/*.comp` it is `shaders` and every namespace is empty; for

// `shaders/a/x.comp` and `shaders/b/y.comp` it is still `shaders`, and the two

// land in `::a` and `::b`.

//

// A single path has no common prefix with anything, so its own directory is the

// base and its namespace is empty -- which is the same answer the general case

// gives once a second file appears beside it.

// A path's components as strings: both separators split, empty and `.`

// components dropped. This is the one place the lib root reads a path apart,

// and it does so WITHOUT `std::filesystem::path`'s iterator on purpose:

//

// A MODULE THAT INSTANTIATES `_Path_iterator` POISONS ITS IMPORTERS UNDER MSVC

// 14.52. Measured on xrgui's CI (14.52.36629 and .36725): this unit compiled

// while it iterated paths, and every member importing it that then touched

// `std::filesystem` at all failed inside the STL --

//

// include\filesystem(1572): error C2801: '..._Path_iterator<...>::operator =='

// must be a non-static member

//

// -- the iterator's hidden-friend comparison, refused when the importer meets

// it both through `import std` and through this module's BMI. Removing the

// calls from the members changed nothing; the instantiation had to leave the

// lib root. Component comparison is what `lexically_relative` bought in 0.5.2

// (a Windows separator bug), and splitting on both separators keeps that.

inline std::vector<std::string> components(std::string_view path) {

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

std::string cur;

auto flush = [&] { if (!cur.empty() && cur != ".") out.push_back(cur); cur.clear(); };

for (char c : path) { if (c == '/' || c == '\\') flush(); else cur += c; }

flush();

return out;

}

// The directory part of a path, as written: everything before the last

// separator, or empty when there is none.

inline std::string_view parent_of(std::string_view path) {

const auto slash = path.find_last_of("/\\");

return slash == std::string_view::npos ? std::string_view{} : path.substr(0, slash);

}

inline std::string common_base_dir(std::span<const std::string> paths) {

std::vector<std::string> prefix;

bool first = true;

for (auto const& src : paths) {

auto segs = components(parent_of(src));

if (first) { prefix = std::move(segs); first = false; continue; }

std::size_t keep = 0;

while (keep < prefix.size() && keep < segs.size() && prefix[keep] == segs[keep]) ++keep;

prefix.resize(keep);

}

std::string out;

for (auto const& s : prefix) { if (!out.empty()) out += '/'; out += s; }

return out;

}

// The namespace segments a file sits in, below the group's own: the path from

// the base directory to the file, sanitised one segment at a time.

//

// RELATIVE BY PATH ARITHMETIC, NOT BY STRING SURGERY, AND THAT IS A WINDOWS

// FIX. This trimmed `base` off the front of the directory as a STRING and

// iterated what was left. On Windows the two spellings differ even when the

// two paths are the same: a caller states a root with forward slashes, and

// `directory_iterator` appends with the preferred separator, so the leftover

// was `\image` rather than `image`. Iterating that yields the ROOT DIRECTORY

// as its first component, which sanitised to `_` -- and the payload landed in

// `myapp::shaders::_::image`, a namespace no consumer writes. Measured: the

// island fixture failed to compile on windows-2022 with `no member named

// 'image' in namespace 'island_interface::kernels'`, while the same fixture

// passed on Linux and macOS.

//

// COMPONENTS are compared, so the separator a caller happened to write is not

// part of the question -- `components()` splits on both. A base that is not a

// prefix is a caller error rather than a namespace; it answers with no

// segments rather than with the whole absolute path, which is what the first

// string form produced. (Through `components()` rather than

// `lexically_relative` for the reason stated on it.)

inline std::vector<std::string> namespace_of(std::string_view src, std::string_view base) {

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

auto dir = components(parent_of(src));

if (!base.empty()) {

const auto b = components(base);

if (b.size() > dir.size()) return out;

for (std::size_t i = 0; i < b.size(); ++i) if (b[i] != dir[i]) return out;

dir.erase(dir.begin(), dir.begin() + static_cast<std::ptrdiff_t>(b.size()));

}

for (auto const& s : dir) {

if (s == "..") continue;

// `shaders/default/` is an ordinary directory name and

// `namespace default {` is not a namespace.

out.push_back(identifier(s, "dir"));

}

return out;

}

} // namespace mcpp::plugins::names

// mcpp.plugins.surface -- the interface a consumer names for an embedded payload.

//

// WHY THIS IS SHARED RATHER THAN PER-RULE.

//

// `mcpp.rules.spirv` and `mcpp.rules.slang` produce the same kind of thing: a

// block of bytes the program hands to a device API. `mcpp.tools.embed` produces

// it from a file that was already there. The three differ in who produces the

// bytes and disagree about nothing else, so the declaration a consumer reads is

// written once, here, and the shape is identical whichever produced it. A rule

// that wrote its own would be a second copy of a decision, and the two would

// drift the way the two shader compilers' headers drifted before 0.2.6.

//

// THE INTERFACE IS A FUNCTION, NOT A VARIABLE.

//

// A variable cannot keep one shape across the ways bytes can be stored, because

// `constexpr` and `extern` are mutually exclusive: an array compiled into a

// translation unit can be constant-evaluated and one living in a section cannot.

// A function can, so where the bytes live stays an option a project revises

// without touching a consumer.

//

// THE INTERFACE NAMES NO STANDARD-LIBRARY TYPE, AND THAT IS MEASURED.

//

// The same 1 MB payload, reached four ways, compiled with GCC 16.1:

//

// data in the module (`export inline constexpr`) BMI 6 282 240 B

// data in a header source 3 145 728 B

// data in an object, interface returns std::span BMI 1 313 968 B

// data in an object, interface returns a std-free POD BMI 1 808 B

//

// The third row is 727 times the fourth, and its cost is FIXED rather than

// proportional to the payload: the 1.28 MB is `<span>`'s templates, present

// whether the payload is 16 KB or 16 MB. A consumer that wants a `std::span`

// constructs one from the two members, and `<span>` is then included by the

// consumer that uses it rather than by every consumer that imports this.

//

// There is a second, independent reason for the same decision. `import std;`

// requires `std.gcm` to have been built, which a project with

// `modules = true, import_std = false` has not done. A std-free interface needs

// neither.

//

// WHY THE ACCESSORS HAVE C LANGUAGE LINKAGE.

//

// A function declared in a module interface has module linkage and can only be

// defined by a unit attached to that module. Defining them would therefore need

// a module implementation unit, and the definitions include the generated data

// headers -- which would put the arrays back into the interface's own

// compilation. Declaring the accessors `extern "C"` instead gives them external

// linkage, so an ordinary translation unit defines them, the module interface

// holds two declarations and one inline call per payload, and the bytes are

// never seen by the interface at all.

//

// It also removes a portability question: module implementation units are the

// least exercised corner of every implementation this package supports, and

// nothing here needs them.

//

// ONE COPY OF THE BYTES.

//

// A generated data header declares `static const uint32_t <sym>[]`, so every

// translation unit that includes it gets its own copy. Under this surface

// exactly one translation unit includes it -- the generated implementation --

// and every consumer reaches the same array through the accessor.

export namespace mcpp::plugins::surface {

// The name derivations live in `mcpp::plugins::names`. They are reachable under

// this namespace as well, because every rule in this collection already spells

// them this way -- one definition under two spellings is not two definitions.

using names::identifier;

using names::split_module_name;

using names::common_base_dir;

using names::namespace_of;

// How a consumer names the payloads.

//

// `module_` is the default where the project builds C++ modules, and

// `c_header` is what a project without them gets. The choice does not change

// any declaration's shape: the same struct, the same function names, the same

// namespaces. Only the file a consumer reaches them through differs.

enum class kind { module_, c_header };

// WHICH HALF OF THE SURFACE A CALL WRITES.

//

// The two are separate because their INPUTS are. The interface is a function of

// the item list: names, namespaces, the accessor declarations. The body is a

// function of the item list AND, under `storage::object`, of the payloads

// themselves -- the assembly names each one in `.incbin`, and the object it

// produces is those bytes.

//

// Declaring them as one action would make a payload change rewrite the

// interface too, and rebuild every BMI that imports it. Declaring them

// separately states what is true and costs a consumer nothing.

enum class half { interface_, body };

// The element the accessor hands back. `word32` is what an API taking

// `const uint32_t*` wants -- `vkCreateShaderModule` is the case this package

// has -- and asking for it here is cheaper than a reinterpret_cast at every

// call site, which is undefined behaviour on an under-aligned byte array.

enum class element { byte_, word32 };

// WHERE THE BYTES LIVE. Orthogonal to `kind`, which decides how a consumer

// NAMES them: the declarations are identical under all three, so a project

// changes this and no consumer changes.

//

// WHICH ONE TO USE IS A MEASUREMENT, NOT A PREFERENCE. With GCC 16.1 on this

// project's own fixtures, 100 payloads of 16 KB each:

//

// header route compile 0.64s + link 0.44s = 1.10s

// object route convert 1.28s + compile 0.44s + link 0.46s = 2.17s

//

// The header route is faster, because at a real shader's size neither route has

// a measurable marginal cost and the total is decided by how many processes

// start -- and one compiler invocation absorbs many headers. The crossover is

// the TOTAL embedded byte count, not the payload count: below about 1 MB the

// header route wins, and above about 4 MB the compiler's slightly superlinear

// curve loses by an order of magnitude (2.31s against 0.116s at 4 MB). Source

// expansion is a constant 2.75x, which is the second half of the same reason.

//

// So `header` is the default and `object` is what a project reaches for when it

// has more payload than that, not what it reaches for because objects sound

// tidier.

enum class storage {

// 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,

};

// One payload in a group.

struct item {

// 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;

};

struct options {

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;

};

// What the caller hands back to mcpp.

struct emitted {

// 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;

};

// The linker symbol an accessor carries. It is derived from the module name and

// the payload's full namespace path rather than from the identifier alone,

// because two groups in one link unit -- a project with shaders and with

// embedded data -- would otherwise define the same symbol twice and the second

// definition would be the one nobody expected.

inline std::string accessor_base(const options& opt, const item& it) {

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;

}

inline const char* element_type(element e) {

return e == element::word32 ? "unsigned int" : "unsigned char";

}

// `unsigned int` is 32 bits on every target this package supports, and the

// generated implementation asserts it rather than assuming it: a target where

// it is not would otherwise hand a Vulkan driver a pointer into misread data,

// and the failure would be a device error naming nothing.

inline const char* element_width_assertion(element e) {

return e == element::word32

? "static_assert(sizeof(unsigned int) == 4,\n"

" \"mcpp.plugins.surface: element::word32 assumes a 32-bit `unsigned int`\");\n"

: "";

}