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

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.build.test_targets;

import mcpp.diag;

import mcpp.build.plan;

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.manifest;

import mcpp.source_kind;

import mcpp.modgraph.scanner;

import mcpp.toolchain.post_install;

import mcpp.toolchain.stdmod;

import mcpp.platform.xlings;

import mcpp.platform.xlings.subos_info;

import mcpp.platform.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 {

// ─── 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.

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;

};

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

}

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

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 = {}) {

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;

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

}

}

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;

});

}

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

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

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

std::string ver = spec.isPath()

? "(path)"

: 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",

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,

ctx.profile, std::string(cache_mode_name(ctx.cacheMode)),

ctx.plan.runtimeBinding);

}

// The one place the --strict policy is settled. Degradations reported by

// the backend (e.g. a toolchain/platform combination that cannot emit a

// depfile, #257) are discovered during emission, so this has to come

// after the build rather than at the end of prepare_build. Without this

// call the whole diag channel would report and then be ignored — the

// exact failure mode it exists to prevent.

if (!mcpp::diag::flush(ctx.strict)) return 1;

// The descriptor comes from the knobs this build actually resolved, so it

// cannot disagree with the compiler flags the way the old hardcoded

// "release [optimized]" did.

{

const auto& bc = ctx.manifest.buildConfig;

std::string descriptor =

(bc.optLevel.empty() || bc.optLevel == "0") ? "unoptimized" : "optimized";

if (bc.debug) descriptor += " + debuginfo";

if (bc.lto) descriptor += " + lto";

mcpp::ui::finished(ctx.profile, r->elapsed, descriptor);

}

return 0;

}

// ─── P0 fast-path: skip prepare_build when build.ninja is fresh ──────

//

// On a successful build, we write `target/.build_cache` containing the

// outputDir path. On the next invocation, if build.ninja in that dir

// is newer than all source files and mcpp.toml, we invoke ninja directly

// without re-running the scanner, make_plan, or emit phases.

//

// This reduces no-change builds from ~10s to <0.5s.

// mcpp#225: is any tracked source file under `projectRoot` newer than

// `ninjaTime`? Shared by try_fast_build's and try_fast_run's freshness

// gates. Uses expand_glob's bounded ("src" prefix) + vcs/build-dir-excluded

// walk instead of a hand-rolled recursive_directory_iterator — the OLD

// staleness check here walked ALL of src/ unfiltered (harmless when src/ is

// the whole tree, but wasteful/wrong the moment a huge unrelated directory

// lives elsewhere under the project root and gets swept in by some other

// caller's broader glob; and it's the same choke-point fix as expand_glob

// itself, see scanner.cppm).

// `extTable` has no default ON PURPOSE. A default would let a future caller

// sweep with the built-in table while the project classifies with a wider one

// — the exact shape of the bug this converge is removing, reintroduced as a

// parameter default. Callers must say where their table came from.

bool sources_newer_than(const std::filesystem::path& projectRoot,

std::filesystem::file_time_type ninjaTime,

const std::vector<std::filesystem::path>& resourceScripts,

const mcpp::ExtensionTable& extTable) {

std::error_code ec;

// The root build.mcpp is a build input too — its directives shape

// build.ninja (flags, generated/selected sources). A changed program must

// abandon the fast path and fall through to prepare_build, where the

// declared-input cache decides whether it actually re-runs. Without this

// the documented "re-runs when the build.mcpp source itself changes" was

// unreachable behind a fresh build.ninja.

if (auto bp = projectRoot / "build.mcpp"; std::filesystem::exists(bp, ec)) {

auto bt = std::filesystem::last_write_time(bp, ec);

if (ec || bt > ninjaTime) return true;

}

// #359: a GLOB input changes without any existing file's mtime changing —

// a new .proto appears and every timestamp below is unmoved. The mtime

// sweep therefore cannot see it, and the fast path would report

// "Finished dev in 0.00s" while the new file is never generated. Same

// question as the build.mcpp check above, different kind of input.

if (mcpp::build::glob_inputs_stale(projectRoot)) return true;

// mcpp#365: an author-written `.rc` is a third input of the same kind. It

// is not under src/ and has no C++ extension, so the sweep below cannot see

// it — and unlike the icon or a header the script includes, editing it can

// change WHAT THE GRAPH SHOULD BE: the implicit-input set comes from

// scanning the script, and the "your VERSIONINFO is named by string"

// diagnostic is produced while scanning. Both happen in prepare_build, so a

// fresh build.ninja made the edit invisible — the resource itself rebuilt

// (ninja tracks it), but a newly added `#include "ids.h"` went untracked and

// the diagnostic never fired again after the first build.

//

// Only `files` is swept. `icon` and `extra-inputs` are already ninja

// implicit inputs and changing them cannot change the shape of the graph,

// so forcing a full prepare on every icon tweak would buy nothing.

for (auto const& f : resourceScripts) {

auto p = f.is_absolute() ? f : (projectRoot / f);

auto ft = std::filesystem::last_write_time(p, ec);

if (ec) { ec.clear(); continue; } // missing → prepare_build reports it

if (ft > ninjaTime) return true;

}

// The one place classification is legitimately re-derived: this runs

// BEFORE prepare, so there is no plan to read a kind from. It uses the

// SAME table the scanner will use (this project's manifest), so the two

// cannot drift — which is exactly what the old hand-written list did.

//

// The question here is NOT "did a file change" (ninja answers that) but

// "could the SHAPE of the graph have changed". A `.ixx` missing from the

// old list meant a new `import` inside one never invalidated the fast

// path: ninja recompiled the object, the dyndep edges stayed stale, and

// nothing reported anything.

for (auto& f : mcpp::modgraph::expand_glob(projectRoot, "src/**/*")) {

if (!mcpp::affects_graph_shape(mcpp::classify(f, extTable))) continue;

auto ft = std::filesystem::last_write_time(f, ec);

if (ec || ft > ninjaTime) return true;

}

return false;

}

// mcpp#225: run ninja quietly against an already-verified-fresh build.ninja.

// Shared by try_fast_build (which just reports "Finished" on success) and

// try_fast_run (which goes on to locate + exec a binary). Returns nullopt

// when ninja's failure looks like a stale-graph signature — the caller

// should abandon the fast path and fall back to a full prepare_build — or

// an exit code otherwise (0 success; 1 hard failure, diagnostics already

// printed to stderr).

std::optional<int> run_ninja_fast(const std::string& ninjaProgram,

const std::filesystem::path& outputDir,

const std::filesystem::path& ninjaPath,

bool verbose,

const std::string& runtimeEnvKey,

const std::string& runtimeEnvValue,

std::chrono::milliseconds* elapsedOut = nullptr) {

std::vector<std::string> argv{ninjaProgram};

if (!verbose) argv.push_back("--quiet");

argv.push_back("-C");

argv.push_back(outputDir.string());

if (verbose) argv.push_back("-v");

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

if (runtimeEnvKey == "@env") {

// Multi-var encoding (MSVC INCLUDE/LIB/PATH/VSLANG + optional runtime

// pair): \x1f-separated k=v records in the single value slot.

std::string_view rest = runtimeEnvValue;

while (!rest.empty()) {

auto sep = rest.find('\x1f');

auto rec = rest.substr(0, sep);

if (auto eq = rec.find('='); eq != std::string_view::npos && eq > 0)

childEnv.emplace_back(std::string(rec.substr(0, eq)),

std::string(rec.substr(eq + 1)));

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

rest.remove_prefix(sep + 1);

}

} else if (runtimeEnvKey != "-" && !runtimeEnvValue.empty()) {

childEnv.emplace_back(runtimeEnvKey, runtimeEnvValue);

}

auto t0 = std::chrono::steady_clock::now();

// capture_exec merges stderr into the captured output (replacing `2>&1`),

// so is_stale_ninja_failure / filter_ninja_output still see ninja errors.

auto r = mcpp::platform::process::capture_exec(argv, childEnv);

std::string out = r.output;

int status = r.exit_code;

if (status != 0) {

if (is_stale_ninja_failure(out))

return std::nullopt;

std::fflush(stdout);

mcpp::ui::error("build failed");

auto prefixes = read_ninja_command_prefixes(ninjaPath);

auto diagnostics = verbose ? out : mcpp::build::filter_ninja_output(out, prefixes);

if (!diagnostics.empty()) {

std::fputs(diagnostics.c_str(), stderr);

if (diagnostics.back() != '\n')

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

}

return 1;

}

if (verbose && !out.empty())

std::fputs(out.c_str(), stdout);

if (elapsedOut) {

*elapsedOut = std::chrono::duration_cast<std::chrono::milliseconds>(

std::chrono::steady_clock::now() - t0);

}

return 0;

}

// Which profile does this invocation mean? The fast paths exist precisely to

// avoid prepare_build, where the profile is normally settled — so they settle

// it here from the same pure rule (resolve_profile_name), which needs nothing

// but the manifest. nullopt = manifest unreadable ⇒ no fast path.

//

// Without this, an entry matched on target triple alone could have been built

// for a different profile, and the fast path would run ninja against that

// profile's build.ninja: `mcpp build --release` then a bare `mcpp build`

// reported success in 0.00s and left -O2 artifacts where -O0 -g was asked for.

struct FastPathIdentity {

std::string profile;

std::string cacheMode;

// mcpp#365: author-written resource scripts, for the freshness sweep. They

// ride along here because this is the one place on the fast path that

// already parses the manifest — re-reading it to answer a second question

// would be a second derivation of the same fact.

std::vector<std::filesystem::path> resourceScripts;

// Same argument one field down: the freshness sweep has to know which

// extensions are module interfaces in THIS project, and this is already

// the only manifest read on the fast path.

mcpp::ExtensionTable extTable;

};

std::optional<FastPathIdentity>

fast_path_identity(const std::filesystem::path& projectRoot,

std::string_view profileOverride = "") {

auto m = mcpp::manifest::load(projectRoot / "mcpp.toml");

if (!m) return std::nullopt;

return FastPathIdentity{

mcpp::build::resolve_profile_name(*m, profileOverride),

std::string(mcpp::build::cache_mode_name(

mcpp::build::resolve_cache_mode(*m, ""))),

m->resources.files,

mcpp::extension_table_for(m->buildConfig.moduleExtensions),

};

}

// Try to fast-path: if build.ninja is newer than all inputs, just run ninja.

// Returns exit code on fast-path, or nullopt if full rebuild needed.

export std::optional<int> try_fast_build(const std::filesystem::path& projectRoot,

bool verbose, bool no_cache,

std::string_view currentTarget = "") {

if (no_cache) return std::nullopt;

auto want = fast_path_identity(projectRoot);

if (!want) return std::nullopt;

// P3: read multi-entry cache and find the entry matching this

// (target, profile, cache mode) triple. Matching on the target alone served

// the wrong profile's artifacts, and ignoring the cache mode replayed a

// cache-reading graph for a request that asked not to read the cache.

auto entries = read_build_cache(projectRoot);

const BuildCacheEntry* match = nullptr;

for (auto& e : entries) {

if (e.targetTriple == currentTarget && e.profile == want->profile

&& e.cacheMode == want->cacheMode) {

match = &e;

break;

}

}

if (!match) return std::nullopt;

if (!match->runtimeBinding) return std::nullopt;

auto outputDirStr = match->outputDir;

auto ninjaProgram = match->ninjaProgram;

// Legacy caches stored a shell-quoted path; execvp needs the raw path.

if (ninjaProgram.size() >= 2 && ninjaProgram.front() == '\''

&& ninjaProgram.back() == '\'')

ninjaProgram = ninjaProgram.substr(1, ninjaProgram.size() - 2);

auto cachedFingerprint = match->fingerprint;

auto runtimeEnvKey = match->runtimeEnvKey;

auto runtimeEnvValue = match->runtimeEnvValue;

if (runtimeEnvKey.empty())

return std::nullopt; // old cache entry; regenerate build.ninja once

// P1: verify fingerprint matches the outputDir basename.

if (!cachedFingerprint.empty()) {

auto dirBasename = std::filesystem::path(outputDirStr).filename().string();

if (dirBasename != cachedFingerprint) {

return std::nullopt;

}

}

std::error_code ec;

std::filesystem::path outputDir(outputDirStr);

auto ninjaPath = outputDir / "build.ninja";

if (!std::filesystem::exists(ninjaPath, ec)) return std::nullopt;

// #407. Freshness is measured against the SOURCES, which says nothing

// about what kind of graph this is. `mcpp test` and

// `mcpp build --configure-only` write their plan — dev-deps, test targets,

// `default` naming the test binaries and NOT the package's target — into

// this same file, because the fingerprint covers neither input. Replaying

// that for a plain build linked the tests, never linked the target, and

// printed `Finished`; and a broken file under tests/ (never scanned here)

// failed a plain `mcpp build` outright.

if (!mcpp::build::is_plain_build_graph(ninjaPath)) return std::nullopt;

auto ninjaTime = std::filesystem::last_write_time(ninjaPath, ec);

if (ec) return std::nullopt;

auto runtimeManifest = match->runtimeBinding->subosDir / ".xlings.json";

auto runtimeTime = std::filesystem::last_write_time(runtimeManifest, ec);

if (ec || runtimeTime > ninjaTime) return std::nullopt;

// Check mcpp.toml

auto tomlPath = projectRoot / "mcpp.toml";

auto tomlTime = std::filesystem::last_write_time(tomlPath, ec);

if (ec || tomlTime > ninjaTime) return std::nullopt;

// mcpp#225: bounded + vcs/build-dir-excluded walk (see sources_newer_than)

// instead of a hand-rolled recursive_directory_iterator over src/.

if (sources_newer_than(projectRoot, ninjaTime, want->resourceScripts,

want->extTable)) return std::nullopt;

auto validatedBefore =

mcpp::build::runtime_validation::validated_artifact_snapshot(

outputDir, *match->runtimeBinding);

if (!validatedBefore) return std::nullopt;

// All inputs are older than build.ninja → fast-path: just run ninja.

std::chrono::milliseconds elapsed{};

auto rc = run_ninja_fast(ninjaProgram, outputDir, ninjaPath, verbose,

runtimeEnvKey, runtimeEnvValue, &elapsed);

if (!rc) return std::nullopt;

if (*rc != 0) return rc;

if (!mcpp::build::runtime_validation::artifact_snapshot_unchanged(

*validatedBefore))

return std::nullopt; // relinked: full path reconstructs + validates closure

mcpp::ui::finished(want->profile, elapsed);

return 0;

}

// mcpp#225 (E2): `mcpp run`'s fast path. Mirrors try_fast_build's

// fingerprint/freshness gate against the SAME cache entry `mcpp build`

// wrote (targetTriple == "" — `mcpp run` never takes a --target flag), then

// on a hit runs ninja and execs the cached run-target directly — skipping

// prepare_build (toolchain resolution + full modgraph scan) entirely.

// Returns nullopt when there's no usable cache entry (build_run_target

// falls back to the full prepare_build path, which also refreshes the

// cache for next time), an exit code otherwise.

std::optional<int> try_fast_run(const std::filesystem::path& projectRoot,

const std::optional<std::string>& targetName,

std::span<const std::string> passthrough) {

auto want = fast_path_identity(projectRoot);

if (!want) return std::nullopt;

auto entries = read_build_cache(projectRoot);

const BuildCacheEntry* match = nullptr;

for (auto& e : entries) {

if (e.targetTriple.empty() && e.profile == want->profile

&& e.cacheMode == want->cacheMode) {

match = &e;

break;

}

}

if (!match || match->runTargets.empty()) return std::nullopt;

auto outputDirStr = match->outputDir;

auto ninjaProgram = match->ninjaProgram;

// Legacy caches stored a shell-quoted path; execvp needs the raw path.

if (ninjaProgram.size() >= 2 && ninjaProgram.front() == '\''

&& ninjaProgram.back() == '\'')

ninjaProgram = ninjaProgram.substr(1, ninjaProgram.size() - 2);

if (match->runtimeEnvKey.empty())

return std::nullopt; // old cache entry; go through prepare_build once

// Written before this mcpp knew about subos environments (mcpp#352). Taking

// the fast path here would run the program without them -- which is the

// defect this field exists to fix, surviving an upgrade.

//

// It survives it for a long time, too: the fast path's identity is the

// profile, the cache mode and the resource list, and its fingerprint check

// compares a cached entry against ITSELF. Neither notices that a different

// mcpp wrote the entry, so without this line an upgraded mcpp would reuse a

// pre-upgrade build until something else happened to invalidate it. Measured

// on a real upgrade from 2026.8.7.1, not reasoned about.

if (!match->runtimeBinding)

return std::nullopt; // predates the immutable snapshot; rebuild once

// P1: verify fingerprint matches the outputDir basename.

if (!match->fingerprint.empty()) {

auto dirBasename = std::filesystem::path(outputDirStr).filename().string();

if (dirBasename != match->fingerprint) return std::nullopt;

}

// Locate the requested run-target before doing any filesystem freshness

// work — an unrecognized name falls back to prepare_build, which gives

// a proper "no binary target 'x' found" error instead of a silent miss.

const std::pair<std::string, std::string>* chosen = nullptr;

for (auto& rt : match->runTargets) {

if (targetName && rt.first != *targetName) continue;

chosen = &rt;

if (targetName) break;

}

if (!chosen) return std::nullopt;

std::error_code ec;

std::filesystem::path outputDir(outputDirStr);

auto ninjaPath = outputDir / "build.ninja";

if (!std::filesystem::exists(ninjaPath, ec)) return std::nullopt;

// #407, same reason as try_fast_build: a test-shaped graph does not build

// the run target at all, so running ninja against it would report success

// and then exec a stale (or absent) binary.

if (!mcpp::build::is_plain_build_graph(ninjaPath)) return std::nullopt;

auto ninjaTime = std::filesystem::last_write_time(ninjaPath, ec);

if (ec) return std::nullopt;

auto runtimeManifest = match->runtimeBinding->subosDir / ".xlings.json";

auto runtimeTime = std::filesystem::last_write_time(runtimeManifest, ec);

if (ec || runtimeTime > ninjaTime) return std::nullopt;

auto tomlPath = projectRoot / "mcpp.toml";

auto tomlTime = std::filesystem::last_write_time(tomlPath, ec);

if (ec || tomlTime > ninjaTime) return std::nullopt;

if (sources_newer_than(projectRoot, ninjaTime, want->resourceScripts,

want->extTable)) return std::nullopt;

auto validatedBefore =

mcpp::build::runtime_validation::validated_artifact_snapshot(

outputDir, *match->runtimeBinding);

if (!validatedBefore) return std::nullopt;

// Fresh → run ninja (picks up any incremental object/link work) then

// exec the cached exe path directly.

auto rc = run_ninja_fast(ninjaProgram, outputDir, ninjaPath, /*verbose=*/false,

match->runtimeEnvKey, match->runtimeEnvValue);

if (!rc) return std::nullopt;

if (*rc != 0) return rc;

if (!mcpp::build::runtime_validation::artifact_snapshot_unchanged(

*validatedBefore))

return std::nullopt; // never execute an artifact not validated for this binding

auto exe = outputDir / chosen->second;

auto pathCtx = mcpp::fetcher::make_path_ctx(/*cfg=*/nullptr, projectRoot);

mcpp::ui::status("Running",

std::format("`{}`", mcpp::ui::shorten_path(exe, pathCtx)));

std::println("");

std::fflush(stdout);

std::vector<std::string> argv;

argv.push_back(exe.string());

for (auto& a : passthrough) argv.push_back(a);

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

if (!match->runEnvKey.empty() && !match->runEnvValue.empty())

childEnv.emplace_back(match->runEnvKey, match->runEnvValue);

// ...and exactly the environment declaration snapshot used by the build.

// Installing/changing a provider invalidates the fast path via the SubOS

// manifest mtime check; this invocation never mixes a new run contract

// with objects built under the old one.

for (auto& kv : mcpp::platform::runtime::resolve_runtime_environment(

*match->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;

}))

childEnv.push_back(std::move(kv));

return mcpp::platform::process::run_exec(argv, childEnv) == 0 ? 0 : 1;

}

// `mcpp run` driver: build, locate the binary target, exec it with the

// resolved runtime environment. `package_filter` (`-p`/`--package`) scopes

// a workspace invocation to one member — single-member only, no

// `--workspace` fan-out (running N binaries in one invocation isn't a

// coherent "run"). Threaded straight to prepare_build's BuildOverrides,

// which already does the member switch (basename OR member path — the same

// rule mcpp::project::resolve_member_dir documents for build/test).

export int build_run_target(const std::optional<std::string>& targetName,

std::span<const std::string> passthrough,

const std::string& package_filter = {},

const std::string& cache_mode = {},

bool no_cache = false) {

// mcpp#225 (E2): reuse the resolved build cache when it's still fresh,

// skipping prepare_build's toolchain resolution + modgraph scan

// entirely — mirrors cmd_build's try_fast_build fast path. The cached

// entry was written for whichever package occupied the project root

// last time; a `-p` filter always needs prepare_build's member switch,

// so skip the fast path in that case (mirrors cmd_build's fast-path

// bypass whenever ov.package_filter is set).

// A --cache/--no-cache override also bypasses the fast path, for the same

// reason --profile does: the cached build.ninja was generated under the

// previous mode, so reusing it would silently ignore the flag.