// mcpp.build.execute — drives a prepared BuildContext: ninja execution,

// build cache + fast-path rebuilds, and the run/test/clean pipelines.

// Bodies moved verbatim from the CLI layer. Zero behavior change.

module;

#include <cstdio>

#include <cstdlib>

#include <cerrno> // ENOENT/EACCES/ENOEXEC — the launcher status band

export module mcpp.build.execute;

import std;

import mcpp.build.build_program; // #359 glob inputs the mtime sweep cannot see

import mcpp.build.prepare;

import mcpp.pack; // #622 A10: mcpp::pack::Options / Format

import mcpp.pack.pipeline; // #622 A10: build_and_pack, for `run --format`

import mcpp.build.test_targets;

import mcpp.diag;

import mcpp.build.plan;

import mcpp.toolchain.triple;

import mcpp.freestanding.runner;

import mcpp.build.runner_lookup; // #544: where the runner's program is

import mcpp.home; // config.toml, for the machine's default toolchain

import mcpp.libs.toml;

import mcpp.toolchain.registry; // a payload's own runner (PayloadDescriptor::runner)

import mcpp.build.directives; // the device-slot table: run / flash / monitor / debug

import mcpp.freestanding.linkline;

import mcpp.build.graph_shape; // #407: which mode wrote this build.ninja

import mcpp.build.backend;

import mcpp.build.ninja;

import mcpp.build.runtime_validation;

import mcpp.bmi_cache;

import mcpp.bmi_cache.maintenance; // dir_size + human_bytes, for `clean --stale`

import mcpp.manifest;

import mcpp.source_kind;

import mcpp.modgraph.scanner;

import mcpp.toolchain.post_install;

import mcpp.toolchain.stdmod;

import mcpp.xlings;

import mcpp.xlings.subos_info;

import mcpp.runtime.binding;

import mcpp.log;

import mcpp.platform;

import mcpp.platform.capacity;

import mcpp.build.schedule.policy; // resolve_jobs — one answer to "how many at once"

import mcpp.fetcher.progress;

import mcpp.project;

import mcpp.ui;

namespace mcpp::build {

// ─── The exit status of a run ────────────────────────────────────────

//

// `mcpp run` REPORTS THE PROGRAM'S OWN EXIT STATUS, AND NOTHING BELOW 125

// BELONGS TO mcpp.

//

// It used to fold every non-zero status to 1, so that 2 could mean "could not

// start" as distinct from "ran and failed". The distinction was worth keeping;

// the price was not. Measured before the change: a program whose `main` returns

// 3 made `mcpp run` exit 1, and a bare-metal image that qemu reported as 3

// arrived as 1 as well. A command that cannot report a status is one nobody can

// use in a script, and this ecosystem tells people that running on a device is

// like running hosted.

//

// The band is the one `env`, `timeout` and `nice` already use and that shells

// document, so 126 and 127 arrive with their usual meanings rather than as

// numbers this project allocated:

//

// 127 the program was not found

// 126 it was found and could not be executed (permission, wrong format)

// 125 the launcher itself failed for some other reason

//

// A program that legitimately exits 125-127 is indistinguishable from these,

// which is the residual cost and the reason the message on stderr is not

// optional: a launcher failure always prints why, a program's own status never

// does.

int launcher_status(int spawnErrno) {

switch (spawnErrno) {

case ENOENT:

case ESRCH: return 127;

case EACCES:

case EPERM:

case ENOEXEC:

case EISDIR: return 126;

default: return 125;

}

}

// ─── P0: build cache for fast-path rebuilds ─────────────────────────

constexpr std::string_view kBuildCacheFile = "target/.build_cache";

// P3: LRU capacity. Entries are keyed by (target triple, profile), so the

// working set is now targets × profiles rather than targets alone — 4 was

// enough for one profile, not for a dev/release/dist rotation across a host

// and a cross target.

constexpr int kBuildCacheMaxEntries = 8;

// P3: one entry per (target, fingerprint) pair.

// THE INPUTS THAT CHOOSE A TOOLCHAIN AND ARE NOT IN THE MANIFEST.

//

// The fast path replays a recorded build when the request matches the entry

// that recorded it. `--toolchain` (arriving as MCPP_TOOLCHAIN) and the

// machine's default (`mcpp toolchain default`, stored in config.toml) both

// choose the compiler, and neither was compared. Measured 2026-09-12: after

// `mcpp build` with gcc, `mcpp build --toolchain llvm@22.1.8` printed

// `Finished dev in 0.00s` and left the gcc artefact in place, skipping every

// resolution-time check with it. The manifest's own `[toolchain]` needs no

// entry here: the freshness check already declines when mcpp.toml is newer

// than the recorded build.

//

// THE NAMED SET. A recorded build is replayed only for the same target triple,

// profile, cache mode, requested features and toolchain request. The other

// global options change how a resolution is fetched (`--offline`), checked

// (`--locked`) or executed (`--jobs`), not what it chooses, and are not

// compared.

std::string toolchain_request_identity() {

std::string cli;

if (const char* e = std::getenv("MCPP_TOOLCHAIN"); e) cli = e;

std::string machineDefault;

std::error_code ec;

const auto configFile = mcpp::home::root() / "config.toml";

if (std::filesystem::exists(configFile, ec)) {

if (auto doc = mcpp::libs::toml::parse_file(configFile))

machineDefault = doc->get_string("toolchain.default").value_or("");

}

return std::format("cli={};default={}", cli, machineDefault);

}

struct BuildCacheEntry {

std::string targetTriple; // "" for default target

std::string outputDir;

std::string ninjaProgram;

std::string fingerprint; // outputDir basename

std::string runtimeEnvKey; // "-" means intentionally empty; "" means old cache

std::string runtimeEnvValue;

// mcpp#225 (E2): resolved binary run-targets, cached alongside the

// fingerprint so `mcpp run` can skip prepare_build (toolchain

// resolution + modgraph scan) on a cache hit — see build_run_target's

// fast path. name -> exe path relative to outputDir. Caches written

// before this field existed leave it empty, which the run fast-path

// treats as a miss (falls back to prepare_build once, never crashes).

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

// The process environment needed to exec those targets (e.g.

// LD_LIBRARY_PATH for dep .so's not covered by the exe's own RUNPATH),

// cached the same way as runtimeEnvKey/Value above but for RUNNING the

// binary rather than invoking the toolchain. "" (default-constructed)

// means old cache / not yet resolved — the run fast-path exec's with no

// extra env in that case, matching prepare_build's behavior when

// plan.runtimeLibraryDirs is empty.

std::string runEnvKey;

std::string runEnvValue;

// The subos this build's toolchain belongs to (mcpp#352). The DIRECTORY,

// never the resolved variables: the environment is the subos's property

// and must be re-read on every run, while WHICH subos is the build's

// property and would otherwise be unknowable on the fast path -- which

// has no toolchain to derive it from.

std::string subosDir;

// Was the line present at all? An EMPTY subosDir is a legitimate answer

// (a system toolchain outside the xpkgs store has no subos), so it cannot

// stand in for "this cache predates the field" -- and those two need

// opposite treatment: the first runs, the second must rebuild once.

bool subosRecorded = false;

// The resolved profile this entry was built for. Entries used to be keyed

// by target triple alone, and the fast paths only refuse to run when an

// EXPLICIT --profile/--dev/--release is passed — so a bare `mcpp build`

// after `mcpp build --release` took the fast path against the release

// build.ninja and reported success without ever rebuilding at -O0 -g.

// Empty means "cache predates this field" and is treated as a miss (a

// bare rebuild once, never a wrong artifact).

std::string profile;

// The global-cache mode this build.ninja was generated under. A graph built

// under `global` contains stage_file edges reading the cache; replaying it

// for a request that asked for `local` would use the cache the manifest just

// said not to use — and ruling the cache out is `local`'s entire purpose.

// Same back-compat contract as `profile`: empty ⇒ miss.

std::string cacheMode;

// Exact immutable snapshot used by the build. Optional distinguishes a

// current cache from one written by an older mcpp (or a corrupt payload).

std::optional<mcpp::platform::runtime::RuntimeBinding> runtimeBinding;

// Source trees outside `projectRoot` that this build read — `path`

// dependencies, which is what workspace members are to each other. The

// staleness sweep has to cover them or a NEW FILE appearing in one is

// invisible: ninja has no edge for a file that did not exist when

// build.ninja was written, so `mcpp build` replays the stale graph and

// reports success. See BuildContext::depSourceRoots.

std::vector<std::string> depSourceRoots;

// Was the block present at all? An EMPTY list is a legitimate answer — a

// project with no path dependencies has none — so it cannot stand in for

// "this cache predates the field", and the two need opposite treatment:

// the first takes the fast path, the second must fall through once so the

// list gets written. Same discipline as `subosRecorded` above, and for the

// same reason.

bool depSourceRootsRecorded = false;

// Did the build this entry records have a runner declared for its target

// (#544)? The run fast path executes the artifact bare and has no manifest

// to read a template from, so an entry with a runner is a miss for it —

// the prepare path then consults choose_runner as the first `mcpp run`

// did. Absent on caches written before the field: false, which is the

// pre-#544 behaviour and correct for every entry such a cache could hold

// (a hosted runner was never consulted then, so none was ever used).

bool runnerDeclared = false;

// Did the graph declare a tool on the `when = "run"` tier that this build

// did NOT provision?

//

// A BUILD INSTALLS LESS THAN A RUN NEEDS, WHICH IS THE POINT OF THE

// TIER AND ALSO ITS ONE HAZARD. `mcpp build` requests the build tier; a

// later `mcpp run` requests more. The fast path exists precisely to skip

// the pass that would install the difference, so an entry written by a

// build that saw run-tier entries is a miss for it — exactly as an entry

// recording a runner is.

//

// Absent on caches written before the field: false, which is correct for

// every entry such a cache could hold, because no manifest could express

// the tier.

bool runTierPending = false;

// THE FEATURE SET THIS ENTRY'S ARTEFACTS WERE BUILT WITH.

//

// The entry is keyed on (target, profile, cache mode) and was matched on

// those three alone, while the OUTPUT DIRECTORY is keyed on a fingerprint

// that includes the features. So `mcpp build --features loud` wrote an

// entry pointing at the loud output directory, and the next plain

// `mcpp build` matched it and reported success in 0.00s — serving the

// featured artefact to a request that asked for none.

//

// Measured before this field existed: three builds of one project printed

// `quiet`, `LOUD`, `LOUD`. The third had no feature on.

//

// Absent on caches written before the field: empty, which reads as "no

// features" — correct for every entry such a cache could hold whose

// request also has none, and a miss otherwise, which is the safe direction.

std::string features;

// The toolchain request this entry was built for; see

// toolchain_request_identity. Recorded is kept apart from the value

// because a cache written before the field existed must decline once,

// not match a request whose inputs it never saw.

std::string toolchainRequest;

bool toolchainRecorded = false;

};

std::vector<BuildCacheEntry> read_build_cache(const std::filesystem::path& projectRoot) {

auto path = projectRoot / kBuildCacheFile;

std::ifstream f(path);

if (!f) return {};

std::string firstLine;

if (!std::getline(f, firstLine) || firstLine.empty()) return {};

// Detect legacy format (first line is an absolute path, not "[target=...]").

if (firstLine[0] != '[') {

// Legacy 4-line format: outputDir, ninjaProgram, target, fingerprint.

BuildCacheEntry e;

e.outputDir = firstLine;

std::getline(f, e.ninjaProgram);

std::getline(f, e.targetTriple);

std::getline(f, e.fingerprint);

if (e.outputDir.empty() || e.ninjaProgram.empty()) return {};

return {e};

}

// P3 multi-entry format: sections of [target=<triple>] + 3 mandatory

// lines, plus optional runtime-env lines added after toolenv moved out of

// build.ninja. Old cache entries omit them and are treated as stale.

std::vector<BuildCacheEntry> entries;

std::string line = firstLine;

while (true) {

// Parse [target=<triple>]

if (line.size() < 9 || !line.starts_with("[target=") || line.back() != ']')

break;

BuildCacheEntry e;

e.targetTriple = line.substr(8, line.size() - 9);

if (!std::getline(f, e.outputDir) || e.outputDir.empty()) break;

if (!std::getline(f, e.ninjaProgram) || e.ninjaProgram.empty()) break;

std::getline(f, e.fingerprint);

bool haveNextLine = static_cast<bool>(std::getline(f, line));

if (haveNextLine && !line.starts_with("[target=")

&& !line.starts_with("runTargets=")) {

e.runtimeEnvKey = line;

std::getline(f, e.runtimeEnvValue);

haveNextLine = static_cast<bool>(std::getline(f, line));

}

// mcpp#225 (E2): optional runTargets block. Absent on caches written

// before this field existed (or truncated/corrupt mid-block) — in

// either case e.runTargets stays empty, which the run fast-path

// treats as a miss, never a crash.

if (haveNextLine && line.starts_with("runTargets=")) {

std::size_t n = 0;

try { n = std::stoul(line.substr(11)); } catch (...) { n = 0; }

for (std::size_t i = 0; i < n && std::getline(f, line); ++i) {

auto tab = line.find('\t');

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

e.runTargets.emplace_back(line.substr(0, tab), line.substr(tab + 1));

}

haveNextLine = static_cast<bool>(std::getline(f, line));

}

// mcpp#225 (E2): optional run-env block (the process env needed to

// exec a cached run-target, e.g. LD_LIBRARY_PATH). Same back-compat

// contract as runTargets above.

if (haveNextLine && line.starts_with("runEnv=")) {

e.runEnvKey = line.substr(7);

std::getline(f, e.runEnvValue);

haveNextLine = static_cast<bool>(std::getline(f, line));

}

// Optional subos line. Same back-compat contract: absent ⇒ empty ⇒

// the run fast path treats the entry as a miss, exactly as it already

// does for a cache written before runtimeEnvKey existed. Running with

// a DIFFERENT environment than the full path would be worse than not

// using the cache at all -- the program would work once and then

// silently stop finding its runtime data.

if (haveNextLine && line.starts_with("subos=")) {

e.subosDir = line.substr(6);

e.subosRecorded = true;

haveNextLine = static_cast<bool>(std::getline(f, line));

}

if (haveNextLine && line.starts_with("runtimeBinding=")) {

auto decoded = mcpp::platform::runtime::deserialize_runtime_binding(

line.substr(15));

if (decoded) e.runtimeBinding = std::move(*decoded);

haveNextLine = static_cast<bool>(std::getline(f, line));

}

// Optional profile line. Same back-compat contract as the two blocks

// above: absent ⇒ e.profile stays empty ⇒ every fast path treats the

// entry as a miss and falls through to prepare_build.

if (haveNextLine && line.starts_with("profile=")) {

e.profile = line.substr(8);

haveNextLine = static_cast<bool>(std::getline(f, line));

}

if (haveNextLine && line.starts_with("cacheMode=")) {

e.cacheMode = line.substr(10);

haveNextLine = static_cast<bool>(std::getline(f, line));

}

// Count-prefixed, like `runTargets=` above and for the same reason: a

// zero-length list and an absent block must not read the same. Absent

// means the cache predates the field, and the fast path then declines

// once so the next write records it.

if (haveNextLine && line.starts_with("depSourceRoots=")) {

std::size_t n = 0;

try { n = std::stoul(line.substr(15)); } catch (...) { n = 0; }

for (std::size_t i = 0; i < n && std::getline(f, line); ++i)

e.depSourceRoots.push_back(line);

e.depSourceRootsRecorded = true;

haveNextLine = static_cast<bool>(std::getline(f, line));

}

// Optional `runner=0|1` (#544). Absent ⇒ false; see the field.

if (haveNextLine && line.starts_with("runner=")) {

e.runnerDeclared = (line.substr(7) == "1");

haveNextLine = static_cast<bool>(std::getline(f, line));

}

// Optional `runtier=0|1`. Absent ⇒ false; see the field.

if (haveNextLine && line.starts_with("runtier=")) {

e.runTierPending = (line.substr(8) == "1");

haveNextLine = static_cast<bool>(std::getline(f, line));

}

// Optional `features=<list>`. Absent ⇒ empty; see the field.

if (haveNextLine && line.starts_with("features=")) {

e.features = line.substr(9);

haveNextLine = static_cast<bool>(std::getline(f, line));

}

// Optional `toolchain=<request>`. Absent means the entry predates the

// field, and every fast path declines it once; see the field.

if (haveNextLine && line.starts_with("toolchain=")) {

e.toolchainRequest = line.substr(10);

e.toolchainRecorded = true;

haveNextLine = static_cast<bool>(std::getline(f, line));

}

entries.push_back(std::move(e));

if (!haveNextLine || line.empty()) break;

}

return entries;

}

// Serialize the P3 format. Declared ahead of its single caller so the reader

// and the writer of this file sit next to each other.

void write_build_cache_entries(const std::filesystem::path& path,

const std::vector<BuildCacheEntry>& entries);

// `a, b` and `b a` are one request. Normalised on both sides of the comparison

// — the entry stores this form and the fast path computes it — so a cache hit

// depends on the SET rather than on how it was typed.

std::string normalize_features(std::string_view raw) {

std::vector<std::string> toks;

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

auto c = raw.find_first_of(", ", i);

auto t = raw.substr(i, c == std::string_view::npos ? c : c - i);

if (!t.empty()) toks.emplace_back(t);

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

i = c + 1;

}

std::ranges::sort(toks);

toks.erase(std::unique(toks.begin(), toks.end()), toks.end());

std::string out;

for (auto const& t : toks) { if (!out.empty()) out += ','; out += t; }

return out;

}

void write_build_cache(const std::filesystem::path& projectRoot,

const std::filesystem::path& outputDir,

const std::string& ninjaProgram,

const std::string& targetTriple,

const std::string& fingerprintHex = "",

const std::string& runtimeEnvKey = "-",

const std::string& runtimeEnvValue = "",

std::vector<std::pair<std::string, std::string>> runTargets = {},

const std::string& runEnvKey = "",

const std::string& runEnvValue = "",

const std::string& profile = "",

const std::string& cacheMode = "",

const mcpp::platform::runtime::RuntimeBinding& runtimeBinding = {},

std::vector<std::string> depSourceRoots = {},

bool runnerDeclared = false,

bool runTierPending = false,

const std::string& features = {},

const std::string& toolchainRequest = {}) {

auto path = projectRoot / kBuildCacheFile;

auto entries = read_build_cache(projectRoot);

// Remove the existing entry for this (target, profile) pair. Keying on the

// triple alone made a release build evict the dev entry and vice versa, so

// switching profiles back and forth could never be incremental AND the

// surviving entry pointed at the other profile's build dir.

std::erase_if(entries, [&](const BuildCacheEntry& e) {

return e.targetTriple == targetTriple && e.profile == profile;

});

// Insert at front (MRU).

BuildCacheEntry newEntry{targetTriple, outputDir.string(), ninjaProgram, fingerprintHex,

runtimeEnvKey, runtimeEnvValue, std::move(runTargets),

runEnvKey, runEnvValue, runtimeBinding.subosDir.string(),

/*subosRecorded=*/true,

profile, cacheMode};

newEntry.runtimeBinding = runtimeBinding;

newEntry.depSourceRoots = std::move(depSourceRoots);

newEntry.depSourceRootsRecorded = true;

newEntry.runnerDeclared = runnerDeclared;

newEntry.runTierPending = runTierPending;

newEntry.features = features;

newEntry.toolchainRequest = toolchainRequest;

newEntry.toolchainRecorded = true;

entries.insert(entries.begin(), std::move(newEntry));

// Trim to LRU capacity.

if ((int)entries.size() > kBuildCacheMaxEntries)

entries.resize(kBuildCacheMaxEntries);

write_build_cache_entries(path, entries);

}

void write_build_cache_entries(const std::filesystem::path& path,

const std::vector<BuildCacheEntry>& entries) {

std::error_code ec;

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

std::ofstream f(path, std::ios::trunc);

if (!f) return;

for (auto& e : entries) {

f << "[target=" << e.targetTriple << "]\n";

f << e.outputDir << '\n';

f << e.ninjaProgram << '\n';

f << e.fingerprint << '\n';

f << (e.runtimeEnvKey.empty() ? "-" : e.runtimeEnvKey) << '\n';

f << e.runtimeEnvValue << '\n';

// mcpp#225 (E2): run-targets + their exec env, always written (even

// when empty) so a reader never has to guess whether a missing

// block means "no targets" vs "cache predates this field" — the

// count-prefixed block is unambiguous either way, and back-compat

// for OLD caches (no such block at all) is handled on the read side.

f << "runTargets=" << e.runTargets.size() << '\n';

for (auto& [name, exe] : e.runTargets) f << name << '\t' << exe << '\n';

f << "runEnv=" << e.runEnvKey << '\n';

f << e.runEnvValue << '\n';

f << "subos=" << e.subosDir << '\n';

if (e.runtimeBinding)

f << "runtimeBinding="

<< mcpp::platform::runtime::serialize_runtime_binding(*e.runtimeBinding)

<< '\n';

f << "profile=" << e.profile << '\n';

f << "cacheMode=" << e.cacheMode << '\n';

f << "depSourceRoots=" << e.depSourceRoots.size() << '\n';

for (auto& r : e.depSourceRoots) f << r << '\n';

f << "runner=" << (e.runnerDeclared ? 1 : 0) << '\n';

f << "runtier=" << (e.runTierPending ? 1 : 0) << '\n';

f << "features=" << e.features << '\n';

f << "toolchain=" << e.toolchainRequest << '\n';

}

}

std::vector<std::string> read_ninja_command_prefixes(const std::filesystem::path& ninjaPath) {

std::ifstream f(ninjaPath);

if (!f) return {};

std::vector<std::string> prefixes;

std::string line;

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

auto eq = line.find('=');

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

auto key = line.substr(0, eq);

while (!key.empty() && std::isspace(static_cast<unsigned char>(key.back())))

key.pop_back();

// `mcpp` drives the dyndep + stage_file rules; treating it as a command

// prefix filters the echoed command line while keeping the diagnostic

// mcpp itself printed (#311).

if (key != "cxx" && key != "cc" && key != "ar" && key != "scan_deps"

&& key != "mcpp")

continue;

std::string value = line.substr(eq + 1);

while (!value.empty() && std::isspace(static_cast<unsigned char>(value.front())))

value.erase(value.begin());

while (!value.empty() && std::isspace(static_cast<unsigned char>(value.back())))

value.pop_back();

if (!value.empty())

prefixes.push_back(std::move(value));

}

return prefixes;

}

bool is_stale_ninja_failure(std::string_view output) {

return output.find("loading 'build.ninja'") != std::string_view::npos

|| output.find("loading build.ninja") != std::string_view::npos

|| output.find("unknown target") != std::string_view::npos

|| output.find("manifest 'build.ninja' still dirty") != std::string_view::npos

// A cached build.ninja can reference an input (e.g. a dependency

// source under the registry) that moved or was reinstalled since the

// graph was generated — the build fingerprint does not yet cover

// registry dep state, so the stale graph is reused. Ninja then aborts

// with this signature. Treat it as stale → drop to a full regen

// instead of hard-failing and forcing the user to `mcpp clean`.

|| output.find("missing and no known rule to make") != std::string_view::npos;

}

// mcpp#225 (E2): the (name, exe-path-relative-to-outputDir) pairs for every

// binary link unit in a resolved plan, cached alongside the build

// fingerprint so `mcpp run` can locate an executable without re-running

// prepare_build (see BuildCacheEntry::runTargets / try_fast_run below).

// TestBinary/library link units never run via `mcpp run`, so only Binary

// link units are collected.

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

compute_run_targets(const mcpp::build::BuildPlan& plan) {

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

for (auto& lu : plan.linkUnits) {

if (lu.kind != mcpp::build::LinkUnit::Binary) continue;

out.emplace_back(lu.targetName, lu.output.generic_string());

}

return out;

}

// mcpp#225 (E2): the process env needed to exec a run-target (e.g.

// LD_LIBRARY_PATH for dep .so's not covered by the exe's own RUNPATH).

// Shared between build_run_target's normal (prepare_build) path and its

// cached fast path so both derive the same env from the same source.

std::pair<std::string, std::string>

compute_run_env(const mcpp::build::BuildPlan& plan) {

auto key = mcpp::platform::env::runtime_library_path_key();

auto value = mcpp::platform::env::prepend_path_list(key, plan.runtimeLibraryDirs);

if (key.empty() || value.empty()) return {"", ""};

return {key, value};

}

// The environment captured by this build's selected RuntimeBinding (mcpp#352).

//

// A GL application needs three things and mcpp only ever supplied two: the

// binary links (bootstrap), it finds its libraries (RPATH), and then it has to

// be told which driver module to load and which GL vendors exist. That third

// one is a set of environment variables, xlings's graphics packages declare

// them into the subos, and until now nothing carried them to a program mcpp

// launched — `xlings subos use` applied them, `mcpp run` did not. Hence a

// binary that links fine and exits 255 with no output.

//

// The declarations are snapshotted with the build and serialized into the

// fast-path cache. A changed SubOS manifest invalidates that cache and causes a

// fresh prepare; no invocation mixes newly read run state with old objects.

//

// mcpp does not know what any of these variables MEAN, and that is the design:

// when the ecosystem gains a Vulkan loader or a new driver bridge, the

// declaration changes and this code does not.

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

compute_subos_env(const mcpp::build::BuildPlan& plan) {

return mcpp::platform::runtime::resolve_runtime_environment(

plan.runtimeBinding,

[](std::string_view v) -> std::optional<std::string> {

if (const char* e = std::getenv(std::string(v).c_str()))

return std::string(e);

return std::nullopt;

});

}

// THE FILES A RUNNER HAS TO CARRY WITH THE ARTIFACT (#634 A6).

//

// A runner receives the artifact's path and nothing else, and for a runner

// that executes the artifact on this machine that is enough: the files beside

// it are beside it. A runner that moves the artifact -- `adb-run` pushes the

// program to a device -- moved only the program, and a test reading its

// deployed data then failed on the emulator with `open failed:

// /data/local/tmp/data/data.txt` while passing on the host and on the iOS

// simulator, which reads the host's filesystem.

//

// THE LIST IS WHAT THE ARTIFACT LOADS OR READS FROM ITS OWN DIRECTORY, AS THE

// BUILD LAID IT OUT: every `[runtime] deploy` and `deploy_files` entry, and

// every shared library the plan links, which consumers find beside them

// through `$ORIGIN` or `@loader_path`. A test of a package whose dependency is

// shared on a row (#634 A1) needs that library on the device as much as its

// data. The staged copy in the output tree is named, not the declared source:

// it is the file the artifact reads when it runs here.

//

// One line per file: the destination relative to the artifact's directory,

// with `/` separators, a TAB, and the absolute path of the file. A TAB,

// because a Windows user directory commonly contains a space. A destination

// begins with `../` when the artifact sits below the tree's root, as a test

// discovered in a subdirectory does. The file exists for every runner

// invocation and is empty when there is nothing to carry, so a runner can

// tell an engine that states "nothing" from one that predates the variable.

constexpr std::string_view kRuntimeFilesEnv = "MCPP_RUNTIME_FILES";

std::vector<std::pair<std::string, std::filesystem::path>>

runtime_files_for(const mcpp::build::BuildContext& ctx,

const std::filesystem::path& artifact) {

std::vector<std::pair<std::string, std::filesystem::path>> out;

const auto artifactDir = artifact.parent_path().lexically_normal();

const auto artifactNorm = artifact.lexically_normal();

std::set<std::string> seen;

auto add = [&](const std::filesystem::path& relToOutputDir) {

const auto staged = (ctx.outputDir / relToOutputDir).lexically_normal();

if (staged == artifactNorm) return;

auto dest = staged.lexically_relative(artifactDir).generic_string();

if (dest.empty() || !seen.insert(dest).second) return;

out.emplace_back(std::move(dest), staged);

};

for (auto const& d : ctx.plan.runtimeDeployFiles) add(d.dest);

for (auto const& lu : ctx.plan.linkUnits) {

if (lu.kind != mcpp::build::LinkUnit::SharedLibrary) continue;

add(lu.output);

for (auto const& alias : lu.runtimeAliases) add(alias);

}

return out;

}

// Writes the list for `artifact` under the output tree and returns its path.

// `carried` is empty for a distributable, which holds its own files.

std::expected<std::filesystem::path, std::string>

write_runtime_files_list(

const mcpp::build::BuildContext& ctx,

const std::filesystem::path& artifact,

const std::vector<std::pair<std::string, std::filesystem::path>>& carried) {

namespace fs = std::filesystem;

std::error_code ec;

auto rel = artifact.lexically_normal().lexically_relative(

ctx.outputDir.lexically_normal());

if (rel.empty() || *rel.begin() == "..")

rel = fs::path("distributable") / artifact.filename();

auto listPath = ctx.outputDir / ".mcpp-runtime-files" / rel;

listPath += ".tsv";

fs::create_directories(listPath.parent_path(), ec);

std::ofstream os(listPath, std::ios::binary | std::ios::trunc);

for (auto const& [dest, source] : carried)

os << dest << '\t' << source.string() << '\n';

os.flush();

if (!os)

return std::unexpected(std::format(

"could not write the runtime-files list '{}' a runner receives as {}",

listPath.string(), kRuntimeFilesEnv));

return listPath;

}

// Compile a prepared BuildContext. Shared between `mcpp build` and `mcpp run`

// so the latter doesn't call prepare_build twice (and re-print the toolchain

// resolution banner).

// How many compiles to run at once.

// Concurrency and the module-edge schedule are resolved together in

// mcpp.build.schedule.policy and stamped onto the plan, so this reads one value

// instead of re-deriving it. `scheduleNinjaJobs` is NOT the compiler cap under

// detach-codegen: a detached compiler stops holding a ninja slot, so ninja is

// handed a larger number on purpose.

// THE read point for "how is this artifact executed".

//

// One function, two callers (`mcpp run` and `mcpp test`). Deriving it twice is

// the shape this codebase has paid for repeatedly (#233/#240/#242/#344): it

// does not fail when you add the second derivation, it fails later, when one

// of them gains a rule the other does not.

//

// Returns an empty argv when nothing is declared — the caller runs the

// artifact directly.

//

// Read for EVERY target (#544). The freestanding predicate used to gate this

// read, which is how a runner declared under a hosted cross triple

// (`[target.aarch64-linux-musl].runner` on an x86_64 host) was parsed,

// validated, documented and never consulted: `mcpp run` exec'd the artifact

// bare, the kernel refused it with ENOEXEC, and nothing said so. The

// predicate now decides exactly one thing — whether an absent runner is fatal

// before any spawn is attempted — and `RunnerChoice::freestanding` keeps that

// meaning. Whether THIS host can execute a hosted artifact is not predicted

// here or anywhere: mcpp does what the project declared, or attempts the

// launch and reports what the kernel answered (design §3, P1).

struct RunnerChoice {

std::vector<std::string> tmpl; // empty = execute the artifact directly

bool freestanding = false; // an EMPTY tmpl is fatal when true

bool fromManifest = false; // the consumer overrode a dependency's

bool ignored = false; // --no-runner dropped a declared template

bool longLived = false; // declared by the package; no natural end

bool fromPayload = false; // the toolchain payload's runner, nothing declared

// The spelling that names this target in the manifest: the canonical form,

// which is also the output directory's name and the key every

// `[target.<triple>]` reader resolves. Every diagnostic below prints this

// rather than `tc.targetTriple`, because each one either names the key the

// author wrote or prints a key to paste, and the driver's own spelling is

// neither — on macOS it is `arm64-apple-darwin24.6.0`, which no

// `[target.…]` lookup matches. Derived here, once, so the lookup and the

// message it produces cannot disagree about which target they mean.

std::string tripleKey;

};

// ONE READER FOR FOUR SLOTS, PARAMETERISED BY THE SLOT.

//

// `run`, `flash`, `monitor` and `debug` resolve identically: a dependency

// supplies a template, the project may override it on the same axis, the

// override is reported, and the canonical triple spelling is the lookup key.

// Every one of those four facts was learned the hard way for `runner` alone

// (#544, and the macOS `arm64-apple-darwin24.6.0` mismatch measured on CI).

// Copying the function three times would copy the four facts three times and

// let them drift apart — the shape this file's own header warns about.

//

// `which` selects the slot; everything else is shared.

RunnerChoice choose_device_action(const BuildContext& ctx,

std::string_view which,

bool noRunner = false) {

RunnerChoice c;

const bool isDefault = which.empty();

const auto ft = mcpp::toolchain::triple::parse(ctx.tc.targetTriple);

if (ft) c.freestanding = ft->is_freestanding();

c.tripleKey = ft ? ft->str() : ctx.tc.targetTriple;

// The graph's answer: the default runner, or a named one a package supplied.

if (isDefault) {

c.tmpl = ctx.manifest.buildConfig.runner;

} else if (auto it = ctx.manifest.buildConfig.namedRunners.find(std::string(which));

it != ctx.manifest.buildConfig.namedRunners.end()) {

c.tmpl = it->second.argv;

c.longLived = it->second.longLived;

}

// The manifest key is the CANONICAL spelling — `aarch64-macos`, the name

// of the output directory and the key every other `[target.<triple>]`

// reader uses (prepare.cppm resolves overrides by `t.str()`). The

// toolchain's own `targetTriple` is what the driver reported, which on a

// Linux host happens to be the canonical spelling and on macOS is

// `arm64-apple-darwin24.6.0`. Looking up the raw spelling alone matched on

// Linux and never on macOS (measured on CI, 2026-09-02); the raw form is

// kept as a fallback for a triple the parser does not know.

auto lookup = [&](std::string_view key) {

auto it = ctx.manifest.targetOverrides.find(std::string(key));

const mcpp::manifest::TargetEntry* none = nullptr;

if (it == ctx.manifest.targetOverrides.end()) return none;

if (isDefault) return it->second.runner.empty() ? none : &it->second;

auto nr = it->second.namedRunners.find(std::string(which));

return (nr != it->second.namedRunners.end() && !nr->second.empty())

? &it->second : none;

};

const mcpp::manifest::TargetEntry* entry = lookup(c.tripleKey);

if (!entry && c.tripleKey != ctx.tc.targetTriple)

entry = lookup(ctx.tc.targetTriple);

if (entry) {

if (isDefault) {

c.fromManifest = !ctx.manifest.buildConfig.runner.empty();

c.tmpl = entry->runner;

} else {

c.fromManifest = ctx.manifest.buildConfig.namedRunners.contains(

std::string(which));

c.tmpl = entry->namedRunners.at(std::string(which));

}

}

// AND THE TOOLCHAIN'S OWN ANSWER, WHEN THE PROJECT AND ITS GRAPH GAVE NONE.

//

// The third source and the last. A project's `[target.<triple>] runner`

// and a package's `mcpp::runner(...)` both outrank it, because they are

// statements about THIS program; the payload's is a statement about

// everything its compiler produces. Measured 2026-09-12 in a sandbox with

// no `node` on PATH: an Emscripten artefact built correctly and then

// stopped at `#!/usr/bin/env node`, while the node the payload had

// declared sat in its store. See `PayloadDescriptor::runner`.

//

// The run slot only. `flash`, `monitor` and `debug` name actions a board

// package owns, and a compiler has no opinion about them.

if (isDefault && c.tmpl.empty()) {

c.tmpl = mcpp::toolchain::payload_default_runner(ctx.tc.binaryPath);

c.fromPayload = !c.tmpl.empty();

}

// `--no-runner` is the operator on THIS host stating a host fact the

// manifest cannot carry: the triple is native here. On a freestanding

// target that leaves nothing to execute, and the caller's existing

// no-runner error is the correct answer.

if (noRunner && !c.tmpl.empty()) { c.tmpl.clear(); c.ignored = true; }

return c;

}

RunnerChoice choose_runner(const BuildContext& ctx, bool noRunner) {

return choose_device_action(ctx, std::string_view{}, noRunner);

}

RunnerChoice choose_runner(const BuildContext& ctx) {

return choose_device_action(ctx, std::string_view{}, false);

}

// The capacity number, printed because capacity is the constraint.

//

// After `Finished`, not instead of it: the build succeeded either way, and a

// size line that replaced the outcome would be a different kind of message.

// Silent on every hosted target and whenever the tool is absent — an

// informational line has no standing to fail a build.

void report_freestanding_size(const BuildContext& ctx) {

auto ft = mcpp::toolchain::triple::parse(ctx.tc.targetTriple);

if (!ft || !ft->is_freestanding()) return;

auto tool = mcpp::freestanding::resolve_size_tool(ctx.tc.binaryPath);

if (tool.empty()) return;

for (auto const& lu : ctx.plan.linkUnits) {

if (lu.kind != mcpp::build::LinkUnit::Binary) continue;

auto art = ctx.outputDir / lu.output;

std::error_code ec;

if (!std::filesystem::exists(art, ec)) continue;

// An argument vector rather than a `2>/dev/null` command string,

// which cmd.exe cannot open on a Windows host.

auto out = mcpp::platform::process::capture_stdout(

{tool.string(), art.string()});

if (out.exit_code != 0 && out.output.empty()) continue;

auto s = mcpp::freestanding::parse_size_output(out.output);

if (!s) continue;

mcpp::ui::info("Size", std::format(

"{} text {} data {} bss {} total {}",

lu.targetName, s->text, s->data, s->bss,

mcpp::freestanding::size_total(*s)));

}

}

export int run_build_plan(BuildContext& ctx, bool verbose, bool no_cache,

std::string_view targetOverride = "") {

// `--cache=off` means a cold build: no global cache, and target/ cleared —

// which is exactly what `--no-cache` has always done, hence the alias.

const bool coldBuild = no_cache || ctx.cacheMode == CacheMode::Off;

if (coldBuild) {

std::error_code ec;

std::filesystem::remove_all(ctx.outputDir, ec);

}

// The generated `*link:` spec lives in the output directory, and the line

// above is allowed to delete that directory. prepare wrote the file before

// this point, so a cold build reached ninja with a link command naming a

// spec that no longer existed -- `g++: fatal error: cannot read spec file`,

// on every `--no-cache` build with gcc.

//

// Regenerating here rather than reordering: the invariant worth holding is

// "the spec exists when ninja runs", and stating it as an invariant

// survives the next thing that clears target/ (a user with `rm -rf`, for

// one). The write is idempotent, so the warm path costs one stat.

if (!ctx.plan.gccCleanSpecs.empty()) {

std::error_code ec;

if (!std::filesystem::exists(ctx.plan.gccCleanSpecs, ec))

ctx.plan.gccCleanSpecs = mcpp::toolchain::write_clean_link_specs(

ctx.tc.binaryPath, ctx.outputDir);

}

auto be = mcpp::build::make_ninja_backend();

// M5.0: print "Inferred" banner when defaults / target inference fired.

for (auto& note : ctx.manifest.inferredNotes) {

mcpp::ui::status("Inferred", note);

}

// Announce the package being built (and any deps). A dep served from the

// global cache says "Cached" and HOW MANY translation units that saved. The

// count is the point: the bare word "Cached" was printed for three months

// while ninja recompiled every one of those units behind it, and no output

// contradicted it. A number that has to match the edges ninja actually skips

// cannot be quietly wrong in the same way.

std::map<std::string, std::size_t> cachedUnits;

for (auto& dep : ctx.cachedDeps) cachedUnits[dep.name] = dep.units;

std::set<std::string> announced;

announced.insert(ctx.manifest.package.name);

mcpp::ui::status("Compiling",

std::format("{} v{} (.)",

ctx.manifest.package.name, ctx.manifest.package.version));

for (auto& [name, spec] : ctx.manifest.dependencies) {

if (announced.contains(name)) continue;

announced.insert(name);

// Two keys that resolved to one identity (#634, A2) are one package

// and one compile, so they are announced once.

if (!spec.shortName.empty()

&& !announced.insert(std::format("identity:{}.{}", spec.namespace_,

spec.shortName)).second)

continue;

// `spec.version` is the constraint the manifest WROTE. Announcing it

// printed "Compiling compat.imgui v^1.92.8" — a banner naming a version

// that does not exist (mcpp#363). prepare_build hands the resolution

// result over in ctx.resolvedVersions; fall back to the spec only for

// deps that never went through resolution (git, or an exact pin).

auto rit = ctx.resolvedVersions.find(name);

// A git dependency has no version to announce: `spec.version` is empty

// for it, and the banner used to read "Compiling spike.fw v" (#649 E7).

// It names the reference the manifest wrote instead, shortening a

// commit to the length `git` itself abbreviates to.

auto gitReference = [&] {

std::string ref = spec.gitRev;

if (spec.gitRefKind == "rev" && ref.size() > 12) ref.resize(12);

return std::format("(git {} {})",

spec.gitRefKind.empty() ? "rev" : spec.gitRefKind, ref);

};

std::string ver = spec.isPath()

? "(path)"

: spec.isGit()

? gitReference()

: std::string("v") + (rit != ctx.resolvedVersions.end() ? rit->second

: spec.version);

auto it = cachedUnits.find(name);

if (it == cachedUnits.end()) {

mcpp::ui::status("Compiling", std::format("{} {}", name, ver));

} else {

mcpp::ui::status("Cached", std::format("{} {} ({} unit{})",

name, ver, it->second, it->second == 1 ? "" : "s"));

}

}

// RECLAIM THE STALE CONCURRENCY TOKENS, HERE AND NOT IN prepare.

//

// detach-codegen bounds real compiler concurrency with a semaphore of

// directories under `<build dir>/.mcpp-sched`, released by the supervisor

// holding each token. A supervisor that never runs its cleanup — Ctrl-C on

// the build, the OOM killer, a reboot — leaves its directory behind, and

// nothing else deletes one. Every such event permanently lowers the cap for

// that build directory; after `cap` of them the next build waits for a token

// that can never be released and hangs with no output at all.

//

// This was first placed in prepare, beside the schedule decision, and an

// e2e that plants a full set of stale tokens showed it never running: an

// incremental build takes the project-level fast path, which replays

// build.ninja without re-deriving the plan. The reclaim has to sit on the

// path EVERY build takes, which is the line below this one.

//

// Safe here because ninja has not been spawned yet, so no token in the

// directory can have a live owner.

if (ctx.plan.scheduleTag == "detach-codegen") {

std::error_code semEc;

std::filesystem::remove_all(

std::filesystem::path(ctx.plan.outputDir) / ".mcpp-sched", semEc);

}

mcpp::build::BuildOptions opts;

opts.verbose = verbose;

opts.parallelJobs = static_cast<std::size_t>(ctx.plan.scheduleNinjaJobs);

auto r = be->build(ctx.plan, opts);

if (!r) {

std::fflush(stdout);

mcpp::ui::error(r.error().message);

if (!r.error().diagnosticOutput.empty()) {

std::fputs(r.error().diagnosticOutput.c_str(), stderr);

if (r.error().diagnosticOutput.back() != '\n')

std::fputc('\n', stderr);

}

return 1;

}

// Populate the global cache for deps that did NOT hit. prepare_build leaves

// depsToPopulate empty under --cache=local|off, so the mode gate is already

// enforced there; asserting it again here keeps the write side legible on

// its own terms rather than as a consequence of something in prepare.

if (ctx.cacheMode != CacheMode::Global) ctx.depsToPopulate.clear();

for (auto& task : ctx.depsToPopulate) {

auto pr = mcpp::bmi_cache::populate_from(task.key, ctx.outputDir, task.artifacts);

if (!pr) {

mcpp::ui::warning(std::format(

"bmi cache populate failed for {}@{}: {}",

task.key.packageName, task.key.version, pr.error()));

}

}

// P1.5: warn if fingerprint changed from last build (explains full rebuild).

// Compared against the entry for the SAME profile: the profile is now a

// fingerprint input, so a dev↔release switch always changes the fp. That is

// exactly what the user asked for, and warning about it turns a useful

// signal ("something you didn't expect invalidated your build dir") into

// noise on every profile switch.

{

auto entries = read_build_cache(ctx.projectRoot);

for (auto& e : entries) {

if (e.targetTriple == targetOverride && e.profile == ctx.profile

&& e.cacheMode == cache_mode_name(ctx.cacheMode)

&& !e.fingerprint.empty()) {

auto newFp = ctx.outputDir.filename().string();

if (e.fingerprint != newFp) {

mcpp::ui::warning(std::format(

"fingerprint changed ({} → {}), full rebuild; "

"`mcpp clean --stale` drops the directories no build still uses",

e.fingerprint, newFp));

}

break;

}

}

}

// P0: save build cache for fast-path on next invocation.

if (!coldBuild && !r->ninjaProgram.empty()) {

auto fpHex = ctx.outputDir.filename().string();

auto runTargets = compute_run_targets(ctx.plan);

auto [runEnvKey, runEnvValue] = compute_run_env(ctx.plan);

write_build_cache(ctx.projectRoot, ctx.outputDir, r->ninjaProgram,

std::string(targetOverride), fpHex,

r->runtimeEnvKey.empty() ? "-" : r->runtimeEnvKey,

r->runtimeEnvValue,

std::move(runTargets), runEnvKey, runEnvValue,