kit

build.c (106875B)

---

 #include <kit/build.h>
 #include <kit/compile.h>
 #include <kit/core.h>
 #include <kit/link.h>
 #include <kit/object.h>
 #include <kit/preprocess.h>
 #include <stdint.h>
 #include <string.h>
 
 #include "archive_engine.h"
 #include "cflags.h"
 #include "driver.h"
 #include "hosted.h"
 #include "lib_resolve.h"
 #include "link_flags.h"
 #include "link_inputs.h"
 #include "runtime.h"
 
 /* `kit build-exe` / `build-lib` / `build-obj` — the kit-native build verbs.
  *
  * Each command is polyglot (C / asm / wasm resolved per file), compiles
  * entirely in memory, and writes no intermediate files. They share one
  * parse+run parameterized by output kind:
  *
  *   build-exe   link an executable           (link session, OUTPUT_EXE)
  *   build-lib   static .a / single C TU      (archive of compiled objects,
  *                                             semantic C amalgamation, or DSO)
  *   build-obj   one object; or a relocatable  (compile each source / link
  *               combine of N sources; or       session, OUTPUT_RELOCATABLE)
  *               --emit=asm|c|ir; -fsyntax-only
  *
  * build-obj fully replaces the retired `compile` tool. Two flag tiers:
  *   - global / per-output flags apply to the whole build (target, -O/-g, link
  *     flags, output flags); they may appear anywhere outside a --group.
  *   - scopable flags (-I/-isystem/-D/-U, -x, -X<lang>) form a global baseline
  *     and may be overridden inside a `--group [flags] -- sources...` block.
  *
  * Per-language frontend flags route through `-X<lang> FLAG` (e.g.
  * `-Xwasm -mfeature=simd128`). */
 
 /* Stand-in for "no -x; resolve language from the path suffix at compile time."
  */
 #define BUILD_LANG_AUTO KIT_LANG_AUTO
 
 typedef enum BuildOutputKind {
   BUILD_OUT_EXE,
   BUILD_OUT_LIB,
   BUILD_OUT_OBJ,
 } BuildOutputKind;
 
 typedef enum BuildEmit {
   BUILD_EMIT_OBJ = 0,
   BUILD_EMIT_ASM,
   BUILD_EMIT_C,
   BUILD_EMIT_IR,
 } BuildEmit;
 
 /* The link-input model (link items + object/archive/dso/lib arrays) is shared
  * with the cc driver; see driver/lib/link_inputs.h. */
 
 typedef struct BuildSource {
   const char* path; /* argv-borrowed */
   uint32_t group;   /* index into o->groups[]; 0 = global/bare baseline */
 } BuildSource;
 
 /* One -X<lang> frontend flag token, scoped to a language. */
 typedef struct BuildFeFlag {
   KitLanguage lang;
   char* tok; /* argv-borrowed */
 } BuildFeFlag;
 
 /* A compile-flag scope: the global baseline (groups[0]) plus one entry per
  * `--group`. Each carries its own preprocessor delta, language override, and
  * per-language frontend flags. */
 typedef struct BuildGroup {
   DriverCflags cf;
   int cf_inited;
   KitLanguage forced_lang; /* BUILD_LANG_AUTO if -x not set */
   BuildFeFlag* fe;
   uint32_t nfe;
   /* Merged preprocessor view (group delta over the global baseline), filled
    * after parsing. For groups[0] this borrows cf directly; for real groups it
    * points at the m_* arrays below. */
   KitPreprocessOptions pp;
   const char** m_inc;
   uint32_t m_ninc;
   const char** m_sys;
   uint32_t m_nsys;
   KitDefine* m_def;
   uint32_t m_ndef;
   uint32_t
       m_def_cap; /* allocation size; m_ndef <= cap once globals are shadowed */
   KitSlice* m_und;
   uint32_t m_nund;
 } BuildGroup;
 
 typedef struct BuildOptions {
   DriverEnv* env;
   KitFrontendRegistry* frontends;
   const char* tool;        /* "build-exe" | "build-lib" | "build-obj" */
   int kind;                /* BuildOutputKind */
   const char* driver_path; /* argv[0] */
   size_t argv_bound;
 
   /* Output / per-output state. */
   int emit; /* BuildEmit (build-obj) */
   int syntax_only;
   int opt_level;
   int debug_info;
   int dynamic;                /* -dynamic / -shared */
   int shared_requested;       /* -shared spelling, for build-exe diagnostics */
   int shared;                 /* computed: kind==lib && dynamic */
   int static_link;            /* -static */
   int pie;                    /* -pie */
   int pic_explicit;           /* -fPIC/-fPIE/-static/-pie/-no-pie */
   int function_sections;      /* -ffunction-sections */
   int data_sections;          /* -fdata-sections */
   int auto_var_init;          /* -ftrivial-auto-var-init= (KitAutoVarInit) */
   int stack_protector;        /* KitStackProtectorMode */
   int lto;                    /* -flto/-fno-lto */
   uint64_t disabled_backend_features;
   uint8_t default_visibility; /* KitSymVis */
   int warnings_are_errors;
   uint32_t max_errors;
   const char* output_path;
 
   KitTargetSpec target;
   DriverTargetFeatures target_features;
 
   /* Link-session options and owned -Wl state. */
   DriverLinkFlags link;
   uint64_t epoch;
 
   /* Hosted libc / sysroot state. */
   const char* sysroot;
   const char* support_dir;
   int freestanding;
   int nostdinc;
   int no_stdlib;
   int no_defaultlibs;
   int no_startfiles;
   int wants_hosted_libc;
   DriverHostedPlan hosted;
 
   /* Sources + compile-flag scopes. */
   BuildSource* sources;
   uint32_t nsources;
   BuildGroup* groups;
   uint32_t ngroups;
   uint32_t cur_group; /* scope for newly seen sources */
 
   /* Shared link-input model (build-exe / dynamic build-lib):
    * object/archive/dso/ lib arrays, the ordered link item list, -L search
    * paths, and the owned
    * `<sysroot>/lib` Windows slot. */
   DriverLinkInputSet inputs;
 } BuildOptions;
 
 static int build_record_framework(BuildOptions* o, const char* name);
 
 /* ===================================================================== */
 /* small parse helpers                                                    */
 /* ===================================================================== */
 
 static int build_lang_from_name(BuildOptions* o, const char* name,
                                 KitLanguage* out) {
   /* Resolve off the compile-time default frontend set (no compiler exists at
    * arg-parse time). Value-equivalent to the former explicit map:
    * c->C, asm/s->ASM, wasm/wat->WASM. */
   KitLanguage lang = kit_frontend_registry_language_for_name(o->frontends, name);
   if (lang == KIT_LANG_UNKNOWN) return 1;
   *out = lang;
   return 0;
 }
 
 static void build_err_unknown_language(BuildOptions* o, const char* flag,
                                        const char* value) {
   const char* const known[] = {"c", "asm", "assembler", "s",
                                "toy", "wasm", "wat"};
   const char* candidates[sizeof known / sizeof known[0]];
   DriverSuggestion suggestions[3];
   size_t i, count = 0, n;
   for (i = 0; i < sizeof known / sizeof known[0]; ++i) {
     KitLanguage lang;
     if (build_lang_from_name(o, known[i], &lang) == 0)
       candidates[count++] = known[i];
   }
   n = driver_suggest_values(value, candidates, count, suggestions, 3);
   if (n)
     driver_errf(o->tool, "unsupported %s language: %s; did you mean '%s'?",
                 flag, value, suggestions[0].value);
   else
     driver_errf(o->tool, "unsupported %s language: %s", flag, value);
 }
 
 /* ===================================================================== */
 /* allocation / lifetime                                                  */
 /* ===================================================================== */
 
 static int build_group_cf_init(BuildOptions* o, BuildGroup* g) {
   if (g->cf_inited) return 0;
   if (driver_cflags_init(&g->cf, o->env,
                          (int)(o->argv_bound + DRIVER_HOSTED_MAX_DEFINES +
                                DRIVER_HOSTED_MAX_INCLUDES)) != 0)
     return 1;
   g->cf_inited = 1;
   g->forced_lang = BUILD_LANG_AUTO;
   g->fe = driver_alloc_zeroed(o->env, o->argv_bound * sizeof(*g->fe));
   return g->fe ? 0 : 1;
 }
 
 static int build_alloc(BuildOptions* o, int argc) {
   size_t bound = (size_t)argc + 16u;
   o->argv_bound = bound;
   o->sources = driver_alloc_zeroed(o->env, bound * sizeof(*o->sources));
   o->groups = driver_alloc_zeroed(o->env, bound * sizeof(*o->groups));
   if (!o->sources || !o->groups) {
     driver_errf(o->tool, "out of memory");
     return 1;
   }
   if (driver_link_inputs_init(&o->inputs, o->env, o->tool, bound) != 0)
     return 1;
   /* groups[0] is the global / bare baseline. */
   o->ngroups = 1;
   if (driver_link_flags_init(&o->link, o->env, o->tool, (uint32_t)bound) != 0 ||
       build_group_cf_init(o, &o->groups[0]) != 0 ||
       driver_target_features_init(&o->target_features, o->env, argc) != 0) {
     driver_errf(o->tool, "out of memory");
     return 1;
   }
   return 0;
 }
 
 static void build_release(BuildOptions* o) {
   uint32_t i;
   size_t bound = o->argv_bound;
   for (i = 0; i < o->ngroups; ++i) {
     BuildGroup* g = &o->groups[i];
     if (g->cf_inited) driver_cflags_fini(&g->cf, o->env);
     if (g->fe) driver_free(o->env, g->fe, bound * sizeof(*g->fe));
     if (g->m_inc) driver_free(o->env, g->m_inc, g->m_ninc * sizeof(*g->m_inc));
     if (g->m_sys) driver_free(o->env, g->m_sys, g->m_nsys * sizeof(*g->m_sys));
     if (g->m_def)
       driver_free(o->env, g->m_def, g->m_def_cap * sizeof(*g->m_def));
     if (g->m_und) driver_free(o->env, g->m_und, g->m_nund * sizeof(*g->m_und));
   }
   driver_link_inputs_fini(&o->inputs);
   driver_hosted_plan_fini(o->env, &o->hosted);
   driver_link_flags_fini(&o->link);
   driver_target_features_fini(&o->target_features, o->env);
   if (o->sources) driver_free(o->env, o->sources, bound * sizeof(*o->sources));
   if (o->groups) driver_free(o->env, o->groups, bound * sizeof(*o->groups));
 }
 
 /* ===================================================================== */
 /* positional classification                                              */
 /* ===================================================================== */
 
 /* Routed through the shared driver_path_is_source authority (canonical
  * extension registry, headers excluded), so adding a frontend extension reaches
  * cc/build/run/dbg at once. build still treats .h as a header, not a source —
  * the helper excludes it. */
 static int build_is_source(BuildOptions* o, const char* s) {
   return kit_frontend_registry_path_kind(o->frontends, s, NULL) ==
          KIT_FRONTEND_PATH_SOURCE;
 }
 
 /* The language forced (via -x) for sources in group `gi`: the group's own -x,
  * else the global baseline's, else -1 (resolve by suffix). */
 static int build_scope_forced_lang(const BuildOptions* o, uint32_t gi) {
   if (gi != 0 && o->groups[gi].forced_lang != BUILD_LANG_AUTO)
     return (int)o->groups[gi].forced_lang;
   if (o->groups[0].forced_lang != BUILD_LANG_AUTO)
     return (int)o->groups[0].forced_lang;
   return -1;
 }
 
 static int build_classify_positional(BuildOptions* o, const char* a) {
   if (driver_streq(a, "-")) {
     driver_errf(o->tool, "stdin ('-') is not supported; pass a source file");
     return 1;
   }
   /* Explicit link-input suffixes are always link inputs — never reinterpreted
    * as sources, even when -x forces a language. */
   if (driver_has_suffix(a, ".o") || driver_has_suffix(a, ".obj")) {
     o->inputs.object_files[o->inputs.nobject_files++] = a;
     driver_link_inputs_push(&o->inputs, DRIVER_LINK_OBJECT,
                             o->inputs.nobject_files - 1u);
     return 0;
   }
   if (driver_has_suffix(a, ".a")) {
     DriverArchiveInput* ar = &o->inputs.archives[o->inputs.narchives++];
     ar->path = a;
     ar->whole_archive = o->inputs.cur_whole_archive;
     ar->link_mode = o->inputs.cur_link_mode;
     ar->group_id = o->inputs.cur_group_id;
     driver_link_inputs_push(&o->inputs, DRIVER_LINK_ARCHIVE,
                             o->inputs.narchives - 1u);
     return 0;
   }
   if (driver_is_dso_path(a)) {
     DriverDsoInput* d = &o->inputs.dsos[o->inputs.ndsos++];
     d->path = a;
     driver_link_inputs_push(&o->inputs, DRIVER_LINK_DSO, o->inputs.ndsos - 1u);
     return 0;
   }
   /* Otherwise a source: a recognized source suffix, or any file at all when a
    * language is forced in scope (so `-x c mykernel` compiles an extensionless
    * or odd-suffix file). */
   if (build_is_source(o, a) || build_scope_forced_lang(o, o->cur_group) >= 0) {
     BuildSource* s = &o->sources[o->nsources];
     s->path = a;
     s->group = o->cur_group;
     driver_link_inputs_push(&o->inputs, DRIVER_LINK_SOURCE, o->nsources);
     o->nsources++;
     return 0;
   }
   driver_errf(o->tool,
               "input does not have a recognized suffix: %.*s (use -x LANG)",
               KIT_SLICE_ARG(kit_slice_cstr(a)));
   return 1;
 }
 
 /* ===================================================================== */
 /* scopable-flag parsing (shared by global context and --group blocks)    */
 /* ===================================================================== */
 
 /* Try to consume a scopable flag (-I/-isystem/-D/-U, -x, -X<lang>) at argv[*i]
  * into group `g`. Returns 1 consumed, 0 not a scopable flag, -1 on error. */
 static int build_try_scopable(BuildOptions* o, BuildGroup* g, int argc,
                               char** argv, int* i) {
   const char* a = argv[*i];
   int r = driver_cflags_try_consume(&g->cf, o->env, o->tool, argc, argv, i);
   if (r != 0) return r;
 
   if (driver_streq(a, "-x")) {
     KitLanguage lang;
     if (++(*i) >= argc) {
       driver_errf(o->tool, "-x requires an argument");
       return -1;
     }
     if (driver_streq(argv[*i], "--")) {
       driver_errf(o->tool, "-x requires an argument before `--`");
       return -1;
     }
     if (build_lang_from_name(o, argv[*i], &lang) != 0) {
       build_err_unknown_language(o, "-x", argv[*i]);
       return -1;
     }
     g->forced_lang = lang;
     return 1;
   }
   if (driver_strneq(a, "-X", 2) && a[2] != '\0') {
     KitLanguage lang;
     BuildFeFlag* f;
     if (build_lang_from_name(o, a + 2, &lang) != 0) {
       build_err_unknown_language(o, "-X", a + 2);
       return -1;
     }
     if (++(*i) >= argc) {
       driver_errf(o->tool, "%.*s requires a following flag",
                   KIT_SLICE_ARG(kit_slice_cstr(a)));
       return -1;
     }
     if (driver_streq(argv[*i], "--")) {
       driver_errf(o->tool, "%.*s requires a following flag before `--`",
                   KIT_SLICE_ARG(kit_slice_cstr(a)));
       return -1;
     }
     f = &g->fe[g->nfe++];
     f->lang = lang;
     f->tok = argv[*i];
     return 1;
   }
   return 0;
 }
 
 /* Recognize the global / per-output flags, so a --group block can flag them as
  * misplaced with a pointed diagnostic. */
 static int build_is_global_flag(const char* a) {
   return driver_streq(a, "-o") || driver_strneq(a, "--output", 8) ||
          driver_strneq(a, "-O", 2) || driver_streq(a, "-g") ||
          driver_streq(a, "-S") || driver_strneq(a, "--emit=", 7) ||
          driver_streq(a, "-fsyntax-only") || driver_strneq(a, "-fPIC", 5) ||
          driver_strneq(a, "-fpic", 5) || driver_strneq(a, "-fPIE", 5) ||
          driver_strneq(a, "-fpie", 5) ||
          driver_streq(a, "-arch") || driver_streq(a, "-platform_version") ||
          driver_streq(a, "-macosx_version_min") ||
          driver_streq(a, "-ios_version_min") ||
          driver_streq(a, "-iphoneos_version_min") ||
          driver_streq(a, "-ios_simulator_version_min") ||
          driver_streq(a, "-iphonesimulator_version_min") ||
          driver_strneq(a, "-fvisibility=", 13) ||
          driver_streq(a, "-ffunction-sections") ||
          driver_streq(a, "-fdata-sections") ||
          driver_strneq(a, "-ftrivial-auto-var-init=", 24) ||
          driver_streq(a, "-fno-builtin") ||
          driver_strneq(a, "-fno-builtin-", 13) ||
          driver_streq(a, "-fno-stack-protector") ||
          driver_strneq(a, "-fstack-protector", 17) ||
          driver_streq(a, "-flto") || driver_streq(a, "-fno-lto") ||
          driver_streq(a, "-static") || driver_streq(a, "-dynamic") ||
          driver_streq(a, "-shared") || driver_streq(a, "-pie") ||
          driver_streq(a, "-no-pie") || driver_streq(a, "-target") ||
          driver_strneq(a, "--target", 8) || driver_strneq(a, "-l", 2) ||
          driver_strneq(a, "-L", 2) || driver_strneq(a, "-F", 2) ||
          driver_streq(a, "-framework") || driver_streq(a, "-e") ||
          driver_streq(a, "-T") ||
          driver_streq(a, "-Ttext") || driver_strneq(a, "-Ttext=", 7) ||
          driver_streq(a, "--gc-sections") ||
          driver_streq(a, "--no-gc-sections") ||
          driver_streq(a, "--no-undefined") ||
          driver_streq(a, "--allow-undefined") ||
          driver_streq(a, "--allow-shlib-undefined") ||
          driver_streq(a, "-z") ||
          (a[0] == '-' && a[1] == 'z' && a[2] != '\0') ||
          driver_streq(a, "--map") || driver_strneq(a, "--map=", 6) ||
          driver_streq(a, "-Map") || driver_strneq(a, "-Map=", 5) ||
          driver_streq(a, "--symbols") ||
          driver_strneq(a, "--symbols=", 10) ||
          driver_strneq(a, "--symbols-format=", 17) ||
          driver_strneq(a, "-Wl,", 4) || driver_strneq(a, "--build-id", 10) ||
          driver_streq(a, "-Werror") || driver_strneq(a, "-fmax-errors=", 13) ||
          driver_strneq(a, "-m", 2);
 }
 
 /* ===================================================================== */
 /* main parser                                                            */
 /* ===================================================================== */
 
 static int build_parse_group(BuildOptions* o, int argc, char** argv, int* i) {
   BuildGroup* g;
   uint32_t gid = o->ngroups++;
   g = &o->groups[gid];
   if (build_group_cf_init(o, g) != 0) {
     driver_errf(o->tool, "out of memory");
     return 1;
   }
   ++(*i); /* past --group */
   /* scopable flag section, terminated by `--` */
   for (; *i < argc && !driver_streq(argv[*i], "--"); ++(*i)) {
     int r = build_try_scopable(o, g, argc, argv, i);
     if (r < 0) return 1;
     if (r > 0) continue;
     if (build_is_global_flag(argv[*i])) {
       driver_errf(o->tool,
                   "%.*s is a per-output flag; place it before any --group",
                   KIT_SLICE_ARG(kit_slice_cstr(argv[*i])));
       return 1;
     }
     driver_errf(o->tool, "unsupported flag in --group: %.*s",
                 KIT_SLICE_ARG(kit_slice_cstr(argv[*i])));
     return 1;
   }
   if (*i >= argc) {
     driver_errf(o->tool, "--group requires `--` before its sources");
     return 1;
   }
   ++(*i);             /* past `--` */
   o->cur_group = gid; /* subsequent sources belong to this group */
   return 0;
 }
 
 static int build_parse(int argc, char** argv, BuildOptions* o) {
   int i;
   o->target = driver_host_target();
 
   for (i = 1; i < argc; ++i) {
     const char* a = argv[i];
 
     if (driver_streq(a, "--group")) {
       if (build_parse_group(o, argc, argv, &i) != 0) return 1;
       --i; /* parse_group leaves i at the next token; loop's ++i re-reads it */
       continue;
     }
 
     /* Scopable flags in the global context feed the baseline (groups[0]). */
     {
       int r = build_try_scopable(o, &o->groups[0], argc, argv, &i);
       if (r < 0) return 1;
       if (r > 0) continue;
     }
 
     /* Output form. */
     if (driver_streq(a, "-c")) {
       o->emit = BUILD_EMIT_OBJ;
       continue;
     }
     if (driver_streq(a, "-S") || driver_streq(a, "--emit=asm")) {
       o->emit = BUILD_EMIT_ASM;
       continue;
     }
     if (driver_streq(a, "--emit=obj")) {
       o->emit = BUILD_EMIT_OBJ;
       continue;
     }
     if (driver_streq(a, "--emit=c")) {
       o->emit = BUILD_EMIT_C;
       continue;
     }
     if (driver_streq(a, "--emit=ir")) {
       o->emit = BUILD_EMIT_IR;
       continue;
     }
     if (driver_streq(a, "-fsyntax-only")) {
       o->syntax_only = 1;
       continue;
     }
     if (driver_streq(a, "-o")) {
       if (++i >= argc) {
         driver_errf(o->tool, "-o requires an argument");
         return 1;
       }
       o->output_path = argv[i];
       continue;
     }
     if (driver_strneq(a, "-o", 2)) {
       o->output_path = a + 2;
       continue;
     }
     if (driver_strneq(a, "--output=", 9)) {
       o->output_path = a + 9;
       continue;
     }
     if (driver_streq(a, "--output")) {
       if (++i >= argc) {
         driver_errf(o->tool, "--output requires an argument");
         return 1;
       }
       o->output_path = argv[i];
       continue;
     }
 
     /* Optimization / debug / codegen knobs. */
     if (driver_streq(a, "-g")) {
       o->debug_info = 1;
       continue;
     }
     if (driver_streq(a, "-O0")) {
       o->opt_level = 0;
       continue;
     }
     if (driver_streq(a, "-O1")) {
       o->opt_level = 1;
       continue;
     }
     if (driver_streq(a, "-O2") || driver_streq(a, "-O") ||
         driver_streq(a, "-O3") || driver_streq(a, "-Os") ||
         driver_streq(a, "-Oz") || driver_streq(a, "-Ofast")) {
       o->opt_level = 1;
       continue;
     }
     if (driver_streq(a, "-Werror") || driver_strneq(a, "-Werror=", 8)) {
       o->warnings_are_errors = 1;
       continue;
     }
     if (driver_strneq(a, "-fmax-errors=", 13)) {
       uint64_t v;
       if (driver_parse_u64(a + 13, &v) != 0 || v > 0xFFFFFFFFu) {
         driver_errf(o->tool, "-fmax-errors= requires a non-negative integer");
         return 1;
       }
       o->max_errors = (uint32_t)v;
       continue;
     }
     if (driver_streq(a, "-fPIC") || driver_streq(a, "-fpic")) {
       o->target.pic = KIT_PIC_PIC;
       o->pic_explicit = 1;
       continue;
     }
     if (driver_streq(a, "-fPIE") || driver_streq(a, "-fpie")) {
       o->target.pic = KIT_PIC_PIE;
       o->pic_explicit = 1;
       continue;
     }
     if (driver_streq(a, "-fno-PIC") || driver_streq(a, "-fno-pic") ||
         driver_streq(a, "-fno-PIE") || driver_streq(a, "-fno-pie")) {
       o->target.pic = KIT_PIC_NONE;
       o->pic_explicit = 1;
       continue;
     }
     if (driver_streq(a, "-fvisibility=hidden")) {
       o->default_visibility = KIT_SV_HIDDEN;
       continue;
     }
     if (driver_streq(a, "-fvisibility=default")) {
       o->default_visibility = KIT_SV_DEFAULT;
       continue;
     }
     if (driver_strneq(a, "-fvisibility=", 13)) {
       driver_errf(o->tool, "unsupported visibility: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(a + 13)));
       return 1;
     }
     if (driver_streq(a, "-ffunction-sections")) {
       o->function_sections = 1;
       continue;
     }
     if (driver_streq(a, "-fno-function-sections")) {
       o->function_sections = 0;
       continue;
     }
     if (driver_streq(a, "-fdata-sections")) {
       o->data_sections = 1;
       continue;
     }
     if (driver_strneq(a, "-ftrivial-auto-var-init=", 24)) {
       const char* mode = a + 24;
       if (driver_streq(mode, "zero")) {
         o->auto_var_init = KIT_AUTOVAR_ZERO;
       } else if (driver_streq(mode, "uninitialized")) {
         o->auto_var_init = KIT_AUTOVAR_UNINIT;
       } else if (driver_streq(mode, "pattern")) {
         driver_errf(o->tool,
                     "-ftrivial-auto-var-init=pattern is not yet supported; "
                     "use =zero");
         return 1;
       } else {
         driver_errf(o->tool,
                     "-ftrivial-auto-var-init=: unknown mode '%s' "
                     "(expected zero, pattern, or uninitialized)",
                     mode);
         return 1;
       }
       continue;
     }
     if (driver_streq(a, "-fno-data-sections")) {
       o->data_sections = 0;
       continue;
     }
     if (driver_streq(a, "-fno-builtin") ||
         driver_strneq(a, "-fno-builtin-", 13)) {
       continue;
     }
     if (driver_streq(a, "-fno-stack-protector")) {
       o->stack_protector = KIT_STACK_PROTECTOR_NONE;
       continue;
     }
     if (driver_streq(a, "-fstack-protector")) {
       o->stack_protector = KIT_STACK_PROTECTOR_BASIC;
       continue;
     }
     if (driver_streq(a, "-fstack-protector-strong")) {
       o->stack_protector = KIT_STACK_PROTECTOR_STRONG;
       continue;
     }
     if (driver_streq(a, "-fstack-protector-all")) {
       o->stack_protector = KIT_STACK_PROTECTOR_ALL;
       continue;
     }
     if (driver_strneq(a, "-fstack-protector", 17)) {
       driver_errf(o->tool, "unsupported stack protector mode: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(a)));
       return 1;
     }
     if (driver_streq(a, "-flto")) {
       o->lto = 1;
       continue;
     }
     if (driver_streq(a, "-fno-lto")) {
       o->lto = 0;
       continue;
     }
     if (driver_streq(a, "-ffreestanding")) {
       o->freestanding = 1;
       continue;
     }
     if (driver_streq(a, "-fhosted")) {
       o->freestanding = 0;
       continue;
     }
     if (driver_streq(a, "-nostdinc")) {
       o->nostdinc = 1;
       continue;
     }
     if (driver_streq(a, "-nostdlib")) {
       o->no_stdlib = 1;
       continue;
     }
     if (driver_streq(a, "-nodefaultlibs")) {
       o->no_defaultlibs = 1;
       continue;
     }
     if (driver_streq(a, "-nostartfiles")) {
       o->no_startfiles = 1;
       continue;
     }
 
     /* Link kind. */
     if (driver_streq(a, "-static")) {
       o->static_link = 1;
       o->target.pic = KIT_PIC_NONE;
       o->pic_explicit = 1;
       o->inputs.cur_link_mode = KIT_LM_STATIC;
       continue;
     }
     if (driver_streq(a, "-dynamic")) {
       o->dynamic = 1;
       continue;
     }
     if (driver_streq(a, "-shared")) {
       o->dynamic = 1;
       o->shared_requested = 1;
       continue;
     }
     if (driver_streq(a, "-pie")) {
       o->target.pic = KIT_PIC_PIE;
       o->pie = 1;
       o->pic_explicit = 1;
       continue;
     }
     if (driver_streq(a, "-no-pie")) {
       o->target.pic = KIT_PIC_NONE;
       o->pie = 0;
       o->pic_explicit = 1;
       continue;
     }
 
     /* Link inputs / flags. */
     if (driver_strneq(a, "-L", 2)) {
       const char* dir = a[2] ? a + 2 : (++i < argc ? argv[i] : NULL);
       if (!dir) {
         driver_errf(o->tool, "-L requires an argument");
         return 1;
       }
       o->inputs.lib_search_paths[o->inputs.nlib_search_paths++] = dir;
       continue;
     }
     if (driver_strneq(a, "-F", 2)) {
       const char* dir = a[2] ? a + 2 : (++i < argc ? argv[i] : NULL);
       if (!dir) {
         driver_errf(o->tool, "-F requires an argument");
         return 1;
       }
       o->inputs.framework_search_paths[o->inputs.nframework_search_paths++] =
           dir;
       continue;
     }
     if (driver_strneq(a, "-l", 2)) {
       const char* name = a[2] ? a + 2 : (++i < argc ? argv[i] : NULL);
       if (!name) {
         driver_errf(o->tool, "-l requires an argument");
         return 1;
       }
       if (driver_streq(name, "c") && !o->no_stdlib && !o->no_defaultlibs) {
         o->wants_hosted_libc = 1;
         continue;
       }
       {
         DriverPendingLib* pl =
             &o->inputs.pending_libs[o->inputs.npending_libs++];
         pl->name = name;
         pl->whole_archive = o->inputs.cur_whole_archive;
         pl->link_mode = o->inputs.cur_link_mode;
         pl->group_id = o->inputs.cur_group_id;
         driver_link_inputs_push(&o->inputs, DRIVER_LINK_LIB,
                                 o->inputs.npending_libs - 1u);
       }
       continue;
     }
     if (driver_streq(a, "-framework")) {
       if (++i >= argc) {
         driver_errf(o->tool, "-framework requires an argument");
         return 1;
       }
       if (build_record_framework(o, argv[i]) != 0) return 1;
       continue;
     }
     if (driver_streq(a, "-e")) {
       if (++i >= argc) {
         driver_errf(o->tool, "-e requires an argument");
         return 1;
       }
       o->link.entry = argv[i];
       continue;
     }
     if (driver_streq(a, "-T")) {
       if (++i >= argc) {
         driver_errf(o->tool, "-T requires an argument");
         return 1;
       }
       o->link.linker_script = argv[i];
       continue;
     }
     if (driver_streq(a, "-Ttext")) {
       if (++i >= argc) {
         driver_errf(o->tool, "-Ttext requires an argument");
         return 1;
       }
       if (driver_link_flags_record_text_base(&o->link, argv[i]) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "-Ttext=", 7)) {
       if (driver_link_flags_record_text_base(&o->link, a + 7) != 0) return 1;
       continue;
     }
     if (driver_streq(a, "-Tdata") || driver_streq(a, "-Tbss")) {
       const char* secname = driver_streq(a, "-Tdata") ? ".data" : ".bss";
       if (++i >= argc) {
         driver_errf(o->tool, "%s requires an address", a);
         return 1;
       }
       if (driver_link_flags_record_section_addr(&o->link, secname, argv[i]) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "-Tdata=", 7)) {
       if (driver_link_flags_record_section_addr(&o->link, ".data", a + 7) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "-Tbss=", 6)) {
       if (driver_link_flags_record_section_addr(&o->link, ".bss", a + 6) != 0)
         return 1;
       continue;
     }
     if (driver_streq(a, "--defsym")) {
       if (++i >= argc) {
         driver_errf(o->tool, "--defsym requires NAME=EXPR");
         return 1;
       }
       if (driver_link_flags_record_defsym(&o->link, argv[i],
                                           driver_strlen(argv[i])) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "--defsym=", 9)) {
       if (driver_link_flags_record_defsym(&o->link, a + 9,
                                           driver_strlen(a + 9)) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "--section-start=", 16)) {
       if (driver_link_flags_record_section_start(&o->link, a + 16,
                                                  driver_strlen(a + 16)) != 0)
         return 1;
       continue;
     }
     if (driver_streq(a, "--section-start")) {
       if (++i >= argc) {
         driver_errf(o->tool, "--section-start requires .NAME=ADDR");
         return 1;
       }
       if (driver_link_flags_record_section_start(&o->link, argv[i],
                                                  driver_strlen(argv[i])) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "--orphan-handling=", 18)) {
       if (driver_link_flags_record_orphan_handling(
               &o->link, a + 18, driver_strlen(a + 18)) != 0)
         return 1;
       continue;
     }
     if (driver_streq(a, "--orphan-handling")) {
       if (++i >= argc) {
         driver_errf(o->tool, "--orphan-handling requires a mode");
         return 1;
       }
       if (driver_link_flags_record_orphan_handling(
               &o->link, argv[i], driver_strlen(argv[i])) != 0)
         return 1;
       continue;
     }
     if (driver_streq(a, "--fatal-warnings")) {
       o->link.fatal_warnings = 1;
       continue;
     }
     if (driver_streq(a, "--no-fatal-warnings")) {
       o->link.fatal_warnings = 0;
       continue;
     }
     if (driver_streq(a, "--print-memory-usage")) {
       o->link.print_memory_usage = 1;
       continue;
     }
     if (driver_streq(a, "--cref")) {
       if (++i >= argc) {
         driver_errf(o->tool, "--cref requires a path");
         return 1;
       }
       if (driver_link_flags_record_cref(&o->link, argv[i],
                                         driver_strlen(argv[i])) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "--cref=", 7)) {
       if (driver_link_flags_record_cref(&o->link, a + 7,
                                         driver_strlen(a + 7)) != 0)
         return 1;
       continue;
     }
     if (driver_streq(a, "--gc-sections")) {
       o->link.gc_sections = 1;
       continue;
     }
     if (driver_streq(a, "--no-gc-sections")) {
       o->link.gc_sections = 0;
       continue;
     }
     if (driver_streq(a, "--no-undefined")) {
       o->link.allow_undefined = 0;
       continue;
     }
     if (driver_streq(a, "--allow-undefined") ||
         driver_streq(a, "--allow-shlib-undefined")) {
       o->link.allow_undefined = 1;
       continue;
     }
     if (driver_streq(a, "-z")) {
       if (++i >= argc) {
         driver_errf(o->tool, "-z requires an argument");
         return 1;
       }
       if (driver_link_flags_record_z(&o->link, argv[i],
                                      driver_strlen(argv[i])) != 0)
         return 1;
       continue;
     }
     if (a[0] == '-' && a[1] == 'z' && a[2] != '\0') {
       if (driver_link_flags_record_z(&o->link, a + 2,
                                      driver_strlen(a + 2)) != 0)
         return 1;
       continue;
     }
     if (driver_streq(a, "--map") || driver_streq(a, "-Map")) {
       if (++i >= argc) {
         driver_errf(o->tool, "%.*s requires an argument",
                     KIT_SLICE_ARG(kit_slice_cstr(a)));
         return 1;
       }
       if (driver_link_flags_record_map(&o->link, argv[i],
                                        driver_strlen(argv[i])) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "--map=", 6)) {
       if (driver_link_flags_record_map(&o->link, a + 6,
                                        driver_strlen(a + 6)) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "-Map=", 5)) {
       if (driver_link_flags_record_map(&o->link, a + 5,
                                        driver_strlen(a + 5)) != 0)
         return 1;
       continue;
     }
     if (driver_streq(a, "--symbols")) {
       if (++i >= argc) {
         driver_errf(o->tool, "--symbols requires an argument");
         return 1;
       }
       if (driver_link_flags_record_symbols(&o->link, argv[i],
                                            driver_strlen(argv[i])) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "--symbols=", 10)) {
       if (driver_link_flags_record_symbols(&o->link, a + 10,
                                            driver_strlen(a + 10)) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "--symbols-format=", 17)) {
       if (driver_link_flags_record_symbols_format(
               &o->link, a + 17, driver_strlen(a + 17)) != 0)
         return 1;
       continue;
     }
     if (driver_strneq(a, "-Wl,", 4)) {
       if (driver_link_flags_record_wl(&o->link, a + 4) != 0) return 1;
       continue;
     }
     if (driver_streq(a, "-Xlinker")) {
       if (++i >= argc) {
         driver_errf(o->tool, "-Xlinker requires an argument");
         return 1;
       }
       if (driver_link_flags_record_wl(&o->link, argv[i]) != 0) return 1;
       continue;
     }
     if (driver_strneq(a, "--build-id=", 11)) {
       if (driver_link_flags_record_build_id(&o->link, a + 11) != 0) return 1;
       continue;
     }
     if (driver_streq(a, "--build-id")) {
       if (driver_link_flags_record_build_id(&o->link, "sha256") != 0) return 1;
       continue;
     }
     if (driver_streq(a, "-mwindows")) {
       o->link.pe_subsystem = KIT_PE_SUBSYSTEM_WINDOWS_GUI;
       continue;
     }
     if (driver_streq(a, "-mconsole")) {
       o->link.pe_subsystem = KIT_PE_SUBSYSTEM_WINDOWS_CUI;
       continue;
     }
     if (driver_strneq(a, "-mcmodel=", 9)) {
       if (driver_record_mcmodel(&o->target, o->tool, a + 9) != 0) return 1;
       continue;
     }
     if (driver_streq(a, "-mno-red-zone")) {
       o->disabled_backend_features |= KIT_CG_BACKEND_RED_ZONE;
       continue;
     }
     if (driver_streq(a, "-mred-zone")) {
       o->disabled_backend_features &= ~KIT_CG_BACKEND_RED_ZONE;
       continue;
     }
     if (driver_streq(a, "-mgeneral-regs-only")) {
       o->disabled_backend_features |= KIT_CG_BACKEND_SIMD;
       continue;
     }
     if (driver_streq(a, "-mno-general-regs-only")) {
       o->disabled_backend_features &= ~KIT_CG_BACKEND_SIMD;
       continue;
     }
 
     /* Target. */
     {
       int dr = driver_darwin_platform_try_consume(
           o->tool, argc, argv, &i, &o->target, o->pic_explicit);
       if (dr < 0) return 1;
       if (dr > 0) continue;
     }
     if (driver_streq(a, "-target") || driver_streq(a, "--target")) {
       KitTargetSpec t;
       uint8_t pic;
       if (++i >= argc) {
         driver_errf(o->tool, "%.*s requires an argument",
                     KIT_SLICE_ARG(kit_slice_cstr(a)));
         return 1;
       }
       if (driver_target_from_triple(argv[i], &t) != 0) {
         driver_err_unknown_target(o->tool, argv[i]);
         return 1;
       }
       pic = o->target.pic;
       o->target = t;
       if (o->pic_explicit)
         o->target.pic = pic;
       else
         o->target.pic = driver_default_pic(o->target.obj, o->target.os);
       continue;
     }
     if (driver_strneq(a, "--target=", 9)) {
       KitTargetSpec t;
       uint8_t pic;
       if (driver_target_from_triple(a + 9, &t) != 0) {
         driver_err_unknown_target(o->tool, a + 9);
         return 1;
       }
       pic = o->target.pic;
       o->target = t;
       if (o->pic_explicit)
         o->target.pic = pic;
       else
         o->target.pic = driver_default_pic(o->target.obj, o->target.os);
       continue;
     }
     {
       int tr = driver_target_features_try_consume(&o->target_features, o->env,
                                                   o->tool, argc, argv, &i);
       if (tr < 0) return 1;
       if (tr > 0) continue;
     }
 
     /* Support dir / sysroot. */
     if (driver_streq(a, "-isysroot") || driver_streq(a, "--sysroot")) {
       if (++i >= argc) {
         driver_errf(o->tool, "%.*s requires an argument",
                     KIT_SLICE_ARG(kit_slice_cstr(a)));
         return 1;
       }
       o->sysroot = argv[i];
       continue;
     }
     if (driver_strneq(a, "--sysroot=", 10)) {
       o->sysroot = a + 10;
       continue;
     }
     if (driver_streq(a, "--support-dir")) {
       if (++i >= argc) {
         driver_errf(o->tool, "--support-dir requires an argument");
         return 1;
       }
       o->support_dir = argv[i];
       continue;
     }
     if (driver_strneq(a, "--support-dir=", 14)) {
       o->support_dir = a + 14;
       continue;
     }
 
     if (driver_streq(a, "--")) {
       for (++i; i < argc; ++i)
         if (build_classify_positional(o, argv[i]) != 0) return 1;
       break;
     }
     if (a[0] == '-' && a[1] != '\0') {
       driver_errf(o->tool, "unknown flag: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(a)));
       return 1;
     }
     if (build_classify_positional(o, a) != 0) return 1;
   }
   return 0;
 }
 
 /* ===================================================================== */
 /* hosted libc / runtime orchestration (build-exe; shared build-lib)      */
 /* ===================================================================== */
 
 static int build_is_link_output(const BuildOptions* o) {
   if (o->kind == BUILD_OUT_EXE && o->target.obj == KIT_OBJ_WASM) return 0;
   return o->kind == BUILD_OUT_EXE || (o->kind == BUILD_OUT_LIB && o->dynamic);
 }
 
 /* A sysroot on its own engages the hosted compiler profile (matching
  * clang/gcc). -ffreestanding / -nostdinc opt out of hosted headers; the
  * -nostdlib family only suppresses link additions. */
 static void build_enable_hosted_for_sysroot(BuildOptions* o) {
   if (o->wants_hosted_libc) return;
   if (o->shared && !driver_target_shared_uses_hosted(o->target)) return;
   if (!o->sysroot || !o->sysroot[0]) return;
   if (o->freestanding || o->nostdinc) return;
   o->wants_hosted_libc = 1;
 }
 
 static void build_apply_default_hosted_profile(BuildOptions* o) {
   KitTargetSpec host;
   int native_macos;
   if (!driver_target_default_hosted_profile(o->target)) return;
   if (o->wants_hosted_libc) return;
   if (o->freestanding || o->nostdinc) return;
   host = driver_host_target();
   native_macos = host.os == KIT_OS_MACOS && o->target.os == KIT_OS_MACOS;
   if ((!o->sysroot || !o->sysroot[0]) && !native_macos) return;
   o->wants_hosted_libc = 1;
 }
 
 static int build_apply_hosted_profile(BuildOptions* o) {
   int link_action;
   int shared_hosted = o->shared && driver_target_shared_uses_hosted(o->target);
   if (!o->wants_hosted_libc || (o->shared && !shared_hosted)) return 0;
   link_action = build_is_link_output(o) && !o->no_stdlib && !o->no_defaultlibs;
   /* Hosted defines/includes apply to every build-* compile. Only an executable
    * or dynamic-library output consumes CRT/libc link inputs. */
   return driver_link_inputs_apply_hosted(
       &o->inputs, &o->hosted, &o->groups[0].cf, &o->link, o->target, o->sysroot,
       o->static_link, o->shared, o->no_startfiles, link_action);
 }
 
 /* ===================================================================== */
 /* merged preprocessor view per group                                     */
 /* ===================================================================== */
 
 static int build_group_build_pp(BuildOptions* o, uint32_t gi) {
   BuildGroup* g = &o->groups[gi];
   BuildGroup* gl = &o->groups[0];
   uint32_t k;
   if (gi == 0) {
     driver_cflags_fill_pp(&gl->cf, &g->pp);
     return 0;
   }
   /* include = group then global (group searched first). */
   g->m_ninc = g->cf.ninclude_dirs + gl->cf.ninclude_dirs;
   g->m_nsys = g->cf.nsystem_include_dirs + gl->cf.nsystem_include_dirs;
   g->m_def_cap = gl->cf.ndefines + g->cf.ndefines;
   g->m_nund = gl->cf.nundefines + g->cf.nundefines;
   if (g->m_ninc)
     g->m_inc = driver_alloc_zeroed(o->env, g->m_ninc * sizeof(*g->m_inc));
   if (g->m_nsys)
     g->m_sys = driver_alloc_zeroed(o->env, g->m_nsys * sizeof(*g->m_sys));
   if (g->m_def_cap)
     g->m_def = driver_alloc_zeroed(o->env, g->m_def_cap * sizeof(*g->m_def));
   if (g->m_nund)
     g->m_und = driver_alloc_zeroed(o->env, g->m_nund * sizeof(*g->m_und));
   if ((g->m_ninc && !g->m_inc) || (g->m_nsys && !g->m_sys) ||
       (g->m_def_cap && !g->m_def) || (g->m_nund && !g->m_und)) {
     driver_errf(o->tool, "out of memory");
     return 1;
   }
   {
     uint32_t p = 0, j;
     for (k = 0; k < g->cf.ninclude_dirs; ++k)
       g->m_inc[p++] = g->cf.include_dirs[k];
     for (k = 0; k < gl->cf.ninclude_dirs; ++k)
       g->m_inc[p++] = gl->cf.include_dirs[k];
     p = 0;
     for (k = 0; k < g->cf.nsystem_include_dirs; ++k)
       g->m_sys[p++] = g->cf.system_include_dirs[k];
     for (k = 0; k < gl->cf.nsystem_include_dirs; ++k)
       g->m_sys[p++] = gl->cf.system_include_dirs[k];
     /* defines: each global define survives only if the group does not redefine
      * the same name; the group's defines then follow. This realizes "a group
      * -D of an already-defined name overrides it for that group" without
      * emitting a duplicate (which the preprocessor rejects as a conflicting
      * redefinition). */
     p = 0;
     for (k = 0; k < gl->cf.ndefines; ++k) {
       int shadowed = 0;
       for (j = 0; j < g->cf.ndefines; ++j) {
         if (kit_slice_eq(gl->cf.defines[k].name, g->cf.defines[j].name)) {
           shadowed = 1;
           break;
         }
       }
       if (!shadowed) g->m_def[p++] = gl->cf.defines[k];
     }
     for (k = 0; k < g->cf.ndefines; ++k) g->m_def[p++] = g->cf.defines[k];
     g->m_ndef = p;
     p = 0;
     for (k = 0; k < gl->cf.nundefines; ++k) g->m_und[p++] = gl->cf.undefines[k];
     for (k = 0; k < g->cf.nundefines; ++k) g->m_und[p++] = g->cf.undefines[k];
   }
   {
     KitPreprocessOptions z = {0};
     g->pp = z;
     g->pp.include_dirs = g->m_inc;
     g->pp.ninclude_dirs = g->m_ninc;
     g->pp.system_include_dirs = g->m_sys;
     g->pp.nsystem_include_dirs = g->m_nsys;
     g->pp.defines = g->m_def;
     g->pp.ndefines = g->m_ndef;
     g->pp.undefines = g->m_und;
     g->pp.nundefines = g->m_nund;
   }
   return 0;
 }
 
 /* ===================================================================== */
 /* compile one source                                                     */
 /* ===================================================================== */
 
 static KitLanguage build_resolve_lang(BuildOptions* o, KitCompiler* compiler,
                                       uint32_t si) {
   uint32_t gi = o->sources[si].group;
   if (gi != 0 && o->groups[gi].forced_lang != BUILD_LANG_AUTO)
     return o->groups[gi].forced_lang;
   if (o->groups[0].forced_lang != BUILD_LANG_AUTO)
     return o->groups[0].forced_lang;
   return kit_language_for_path(compiler, o->sources[si].path);
 }
 
 /* Collect the -X<lang> frontend tokens for a source into a fresh argv:
  * global (groups[0]) tokens first, then the source's group's. */
 static int build_collect_fe_argv(BuildOptions* o, uint32_t si, KitLanguage lang,
                                  char*** out_argv, uint32_t* out_n) {
   uint32_t gi = o->sources[si].group;
   uint32_t n = 0, k, p = 0;
   char** argv;
   for (k = 0; k < o->groups[0].nfe; ++k)
     if (o->groups[0].fe[k].lang == lang) n++;
   if (gi != 0)
     for (k = 0; k < o->groups[gi].nfe; ++k)
       if (o->groups[gi].fe[k].lang == lang) n++;
   *out_argv = NULL;
   *out_n = 0;
   if (n == 0) return 0;
   argv = driver_alloc_zeroed(o->env, n * sizeof(*argv));
   if (!argv) {
     driver_errf(o->tool, "out of memory");
     return 1;
   }
   for (k = 0; k < o->groups[0].nfe; ++k)
     if (o->groups[0].fe[k].lang == lang)
       argv[p++] = o->groups[0].fe[k].tok;
   if (gi != 0)
     for (k = 0; k < o->groups[gi].nfe; ++k)
       if (o->groups[gi].fe[k].lang == lang)
         argv[p++] = o->groups[gi].fe[k].tok;
   *out_argv = argv;
   *out_n = n;
   return 0;
 }
 
 /* Compile source[si]; emit to `emit_out` (per-source output) or return a
  * builder via `obj_out` (link/archive). Exactly one of the two is non-NULL. */
 static int build_compile_source(BuildOptions* o, KitCompiler* compiler,
                                 const KitContext* ctx, uint32_t si,
                                 const KitCodeOptions* code,
                                 const KitDiagnosticOptions* diag,
                                 KitWriter* emit_out, KitObjBuilder** obj_out) {
   const char* path = o->sources[si].path;
   uint32_t gi = o->sources[si].group;
   DriverLoad load = {0};
   KitSlice bytes = {0};
   KitLanguage lang;
   char** fe_argv = NULL;
   uint32_t fe_n = 0;
   void* lang_extra = NULL;
   KitStatus st;
   int rc = 1;
 
   if (driver_load_bytes(ctx->file_io, o->tool, path, &load, &bytes) != 0)
     return 1;
 
   lang = build_resolve_lang(o, compiler, si);
   if (lang == KIT_LANG_UNKNOWN) {
     driver_errf(o->tool, "cannot determine language for %.*s (use -x LANG)",
                 KIT_SLICE_ARG(kit_slice_cstr(path)));
     goto out;
   }
   if (build_collect_fe_argv(o, si, lang, &fe_argv, &fe_n) != 0) goto out;
   if (fe_n) {
     if (kit_frontend_parse_options(compiler, lang, (int)fe_n, fe_argv,
                                    &lang_extra) != KIT_OK) {
       driver_errf(
           o->tool, "unsupported -X%.*s frontend flag: %.*s",
           KIT_SLICE_ARG(kit_slice_cstr(kit_language_name(compiler, lang))),
           KIT_SLICE_ARG(kit_slice_cstr(fe_argv[0])));
       goto out;
     }
   }
 
   st = kit_build_compile_one(compiler, lang, code, diag, &o->groups[gi].pp,
                              lang_extra, kit_slice_cstr(path), &bytes, emit_out,
                              obj_out);
   rc = (st == KIT_OK) ? 0 : 1;
 
 out:
   if (lang_extra) kit_frontend_free_options(compiler, lang, lang_extra);
   if (fe_argv) driver_free(o->env, fe_argv, fe_n * sizeof(*fe_argv));
   driver_release_bytes(ctx->file_io, &load);
   return rc;
 }
 
 static void build_fill_code(const BuildOptions* o, KitCodeOptions* code) {
   KitCodeOptions z = {0};
   *code = z;
   code->opt_level = o->syntax_only ? 0 : o->opt_level;
   code->debug_info = o->debug_info ? true : false;
   code->check_only = o->syntax_only ? true : false;
   code->default_visibility = o->default_visibility;
   code->function_sections = o->function_sections ? true : false;
   code->data_sections = o->data_sections ? true : false;
   code->disabled_backend_features = o->disabled_backend_features;
   code->trivial_auto_var_init = (uint8_t)o->auto_var_init;
   code->stack_protector = (uint8_t)o->stack_protector;
   code->lto = o->lto ? true : false;
   code->epoch = o->epoch;
 }
 
 /* ===================================================================== */
 /* default output naming                                                  */
 /* ===================================================================== */
 
 static char* build_default_obj_name(DriverEnv* env, const BuildOptions* o,
                                     const char* src, size_t* out_size) {
   const char* ext;
   size_t ext_len, srclen = driver_strlen(src), dot = driver_strlen(src),
                   slash = 0, k;
   switch ((BuildEmit)o->emit) {
     case BUILD_EMIT_ASM:
       ext = ".s";
       ext_len = 2u;
       break;
     case BUILD_EMIT_IR:
       ext = ".ir";
       ext_len = 3u;
       break;
     case BUILD_EMIT_C:
       ext = ".c";
       ext_len = 2u;
       break;
     default:
       driver_default_obj_ext(o->target, &ext, &ext_len);
       break;
   }
   for (k = srclen; k > 0; --k) {
     if (src[k - 1] == '.') {
       dot = k - 1;
       break;
     }
     if (src[k - 1] == '/') break;
   }
   for (k = dot; k > 0; --k) {
     if (src[k - 1] == '/') {
       slash = k;
       break;
     }
   }
   {
     size_t name_len = dot - slash;
     size_t bufsz = name_len + ext_len + 1u;
     char* buf = driver_alloc(env, bufsz);
     if (!buf) return NULL;
     driver_memcpy(buf, src + slash, name_len);
     driver_memcpy(buf + name_len, ext, ext_len);
     buf[name_len + ext_len] = '\0';
     *out_size = bufsz;
     return buf;
   }
 }
 
 /* Open the output: a file, or stdout for "-". */
 static int build_open_output(const KitContext* ctx, DriverEnv* env,
                              const char* tool, const char* path,
                              KitWriter** out) {
   if (driver_streq(path, "-")) {
     *out = driver_stdout_writer(env);
     if (!*out) {
       driver_errf(tool, "out of memory");
       return 1;
     }
     return 0;
   }
   if (ctx->file_io->open_writer(ctx->file_io->user, path, out) != KIT_OK) {
     driver_errf(tool, "failed to open output: %.*s",
                 KIT_SLICE_ARG(kit_slice_cstr(path)));
     return 1;
   }
   return 0;
 }
 
 typedef struct BuildSourceBatch {
   DriverLoad* loads;
   KitBuildSource* sources;
   void** lang_extras;
 } BuildSourceBatch;
 
 static void build_source_batch_fini(BuildOptions* o, KitCompiler* compiler,
                                     const KitContext* ctx,
                                     BuildSourceBatch* batch) {
   uint32_t i;
   if (batch->lang_extras && batch->sources) {
     for (i = 0; i < o->nsources; ++i)
       if (batch->lang_extras[i])
         kit_frontend_free_options(compiler, batch->sources[i].lang,
                                   batch->lang_extras[i]);
   }
   if (batch->loads)
     for (i = 0; i < o->nsources; ++i)
       driver_release_bytes(ctx->file_io, &batch->loads[i]);
   if (batch->lang_extras)
     driver_free(o->env, batch->lang_extras,
                 o->nsources * sizeof(*batch->lang_extras));
   if (batch->sources)
     driver_free(o->env, batch->sources,
                 o->nsources * sizeof(*batch->sources));
   if (batch->loads)
     driver_free(o->env, batch->loads, o->nsources * sizeof(*batch->loads));
   memset(batch, 0, sizeof *batch);
 }
 
 /* Load and resolve every source while retaining its independent preprocessing
  * and frontend options. Both object batching and single-TU C emission consume
  * this shape. */
 static int build_source_batch_init(BuildOptions* o, KitCompiler* compiler,
                                    const KitContext* ctx,
                                    BuildSourceBatch* batch) {
   uint32_t i;
 
   memset(batch, 0, sizeof *batch);
   if (o->nsources == 0) return 0;
 
   batch->loads =
       driver_alloc_zeroed(o->env, o->nsources * sizeof(*batch->loads));
   batch->sources =
       driver_alloc_zeroed(o->env, o->nsources * sizeof(*batch->sources));
   batch->lang_extras = driver_alloc_zeroed(
       o->env, o->nsources * sizeof(*batch->lang_extras));
   if (!batch->loads || !batch->sources || !batch->lang_extras) {
     driver_errf(o->tool, "out of memory");
     build_source_batch_fini(o, compiler, ctx, batch);
     return 1;
   }
 
   for (i = 0; i < o->nsources; ++i) {
     const char* path = o->sources[i].path;
     uint32_t gi = o->sources[i].group;
     KitLanguage lang;
     char** fe_argv = NULL;
     uint32_t fe_n = 0;
 
     if (driver_load_bytes(ctx->file_io, o->tool, path, &batch->loads[i],
                           &batch->sources[i].bytes) != 0) {
       build_source_batch_fini(o, compiler, ctx, batch);
       return 1;
     }
     lang = build_resolve_lang(o, compiler, i);
     if (lang == KIT_LANG_UNKNOWN) {
       driver_errf(o->tool, "cannot determine language for %.*s (use -x LANG)",
                   KIT_SLICE_ARG(kit_slice_cstr(path)));
       build_source_batch_fini(o, compiler, ctx, batch);
       return 1;
     }
     batch->sources[i].lang = lang;
     if (build_collect_fe_argv(o, i, lang, &fe_argv, &fe_n) != 0) {
       if (fe_argv) driver_free(o->env, fe_argv, fe_n * sizeof(*fe_argv));
       build_source_batch_fini(o, compiler, ctx, batch);
       return 1;
     }
     if (fe_n) {
       if (kit_frontend_parse_options(compiler, lang, (int)fe_n, fe_argv,
                                      &batch->lang_extras[i]) != KIT_OK) {
         driver_errf(
             o->tool, "unsupported -X%.*s frontend flag: %.*s",
             KIT_SLICE_ARG(kit_slice_cstr(kit_language_name(compiler, lang))),
             KIT_SLICE_ARG(kit_slice_cstr(fe_argv[0])));
         if (fe_argv) driver_free(o->env, fe_argv, fe_n * sizeof(*fe_argv));
         build_source_batch_fini(o, compiler, ctx, batch);
         return 1;
       }
     }
     if (fe_argv) driver_free(o->env, fe_argv, fe_n * sizeof(*fe_argv));
     batch->sources[i].name = kit_slice_cstr(path);
     batch->sources[i].pp = &o->groups[gi].pp;
     batch->sources[i].lang_extra = batch->lang_extras[i];
   }
   return 0;
 }
 
 /* Compile every source to an in-memory builder; objs[] is caller-owned. */
 static int build_compile_all(BuildOptions* o, KitCompiler* compiler,
                              const KitContext* ctx, const KitCodeOptions* code,
                              const KitDiagnosticOptions* diag,
                              KitObjBuilder** objs, uint32_t* source_obj_index,
                              uint8_t* source_order_keep,
                              const KitBuildBatchOptions* batch,
                              KitBuildPendingLto* pending_lto,
                              uint32_t* nobjs_out) {
   BuildSourceBatch sources;
   KitBuildObjects out;
   KitStatus st;
 
   if (nobjs_out) *nobjs_out = 0;
   if (o->nsources == 0) return 0;
   if (build_source_batch_init(o, compiler, ctx, &sources) != 0) return 1;
 
   memset(&out, 0, sizeof out);
   out.objs = objs;
   out.source_obj_index = source_obj_index;
   out.source_order_keep = source_order_keep;
   out.pending_lto = pending_lto;
   st = kit_build_compile(compiler, code, diag, sources.sources, o->nsources,
                          batch, &out);
   if (nobjs_out) *nobjs_out = out.nobjs;
   build_source_batch_fini(o, compiler, ctx, &sources);
   return st == KIT_OK ? 0 : 1;
 }
 
 typedef struct BuildPreservedVec {
   KitHeap* heap;
   KitCgSym* syms;
   uint32_t nsyms;
   uint32_t cap;
   int oom;
 } BuildPreservedVec;
 
 static void build_preserved_vec_add(void* user, KitCgSym sym) {
   BuildPreservedVec* v = (BuildPreservedVec*)user;
   KitCgSym* ns;
   uint32_t ncap;
   if (!v || v->oom) return;
   if (v->nsyms == v->cap) {
     ncap = v->cap ? v->cap * 2u : 32u;
     ns = (KitCgSym*)v->heap->realloc(
         v->heap, v->syms, sizeof(*v->syms) * v->cap,
         sizeof(*v->syms) * ncap, _Alignof(KitCgSym));
     if (!ns) {
       v->oom = 1;
       return;
     }
     v->syms = ns;
     v->cap = ncap;
   }
   v->syms[v->nsyms++] = sym;
 }
 
 static KitStatus build_link_add_inputs(KitLinkSession* link,
                                        const KitLinkInputs* in) {
   KitStatus st = KIT_OK;
   uint32_t i;
   if (!link || !in) return KIT_INVALID;
   for (i = 0; i < in->norder && st == KIT_OK; ++i) {
     const KitLinkInputOrder* ord = &in->order[i];
     switch ((KitLinkInputOrderKind)ord->kind) {
       case KIT_LINK_INPUT_OBJ:
         st = kit_link_session_add_obj(link, in->objs[ord->index]);
         break;
       case KIT_LINK_INPUT_OBJ_BYTES:
         st = kit_link_session_add_obj_bytes(link, in->obj_names[ord->index],
                                             &in->obj_bytes[ord->index]);
         break;
       case KIT_LINK_INPUT_ARCHIVE:
         st =
             kit_link_session_add_archive_bytes(link, &in->archives[ord->index]);
         break;
       case KIT_LINK_INPUT_DSO:
         st = kit_link_session_add_dso_bytes(link, in->dso_names[ord->index],
                                             &in->dso_bytes[ord->index]);
         break;
     }
   }
   return st;
 }
 
 static int build_write_link_report(BuildOptions* o, const KitContext* ctx,
                                    KitLinkSession* link, const char* path,
                                    int symbols) {
   KitWriter* w = NULL;
   KitStatus st;
   if (!path) return 0;
   if (build_open_output(ctx, o->env, o->tool, path, &w) != 0) return 1;
   st = symbols ? kit_link_session_write_symbols(link, o->link.symbols_format, w)
                : kit_link_session_write_map(link, w);
   if (st == KIT_OK) st = kit_writer_status(w);
   kit_writer_close(w);
   if (st != KIT_OK) {
     driver_errf(o->tool, "failed to write %s: %.*s",
                 symbols ? "symbols" : "map",
                 KIT_SLICE_ARG(kit_slice_cstr(path)));
     return 1;
   }
   return 0;
 }
 
 static KitStatus build_link_with_lto_reports(
     BuildOptions* o, KitCompiler* compiler, const KitContext* ctx,
     const KitLinkSessionOptions* lopts, const KitLinkInputs* in,
     KitBuildPendingLto* pending_lto, const KitBuildBatchOptions* batch,
     KitWriter* out) {
   KitLinkSession* link = NULL;
   BuildPreservedVec preserved;
   KitStatus st;
   if (!compiler || !lopts || !in || !out) {
     if (pending_lto && pending_lto->active) kit_build_lto_abort(pending_lto);
     return KIT_INVALID;
   }
   memset(&preserved, 0, sizeof preserved);
   preserved.heap = o->env->heap;
   st = kit_link_session_new(compiler, lopts, &link);
   if (st == KIT_OK) st = build_link_add_inputs(link, in);
   if (st == KIT_OK && pending_lto && pending_lto->active) {
     st = kit_link_session_visit_lto_preserved(
         link, pending_lto->obj, pending_lto->cg, build_preserved_vec_add,
         &preserved);
     if (st == KIT_OK && preserved.oom) st = KIT_NOMEM;
     if (st == KIT_OK)
       st = kit_build_lto_finish(pending_lto, batch, preserved.syms,
                                 preserved.nsyms);
   }
   if (st == KIT_OK) st = kit_link_session_emit(link, out);
   if (st == KIT_OK &&
       build_write_link_report(o, ctx, link, o->link.map_path, 0) != 0)
     st = KIT_ERR;
   if (st == KIT_OK &&
       build_write_link_report(o, ctx, link, o->link.symbols_path, 1) != 0)
     st = KIT_ERR;
   /* --cref FILE: cross-reference table side file. */
   if (st == KIT_OK && o->link.cref_path) {
     KitWriter* w = NULL;
     if (build_open_output(ctx, o->env, o->tool, o->link.cref_path, &w) != 0) {
       st = KIT_ERR;
     } else {
       KitStatus cst = kit_link_session_write_cref(link, w);
       if (cst == KIT_OK) cst = kit_writer_status(w);
       kit_writer_close(w);
       if (cst != KIT_OK) {
         driver_errf(o->tool, "failed to write cref: %.*s",
                     KIT_SLICE_ARG(kit_slice_cstr(o->link.cref_path)));
         st = KIT_ERR;
       }
     }
   }
   /* --print-memory-usage: GNU-ld-style per-region summary to stdout. */
   if (st == KIT_OK && o->link.print_memory_usage) {
     KitWriter* w = NULL;
     if (build_open_output(ctx, o->env, o->tool, "-", &w) != 0) {
       st = KIT_ERR;
     } else {
       KitStatus mst = kit_link_session_write_memory_usage(link, w);
       if (mst == KIT_OK) mst = kit_writer_status(w);
       kit_writer_close(w);
       if (mst != KIT_OK) {
         driver_errf(o->tool, "failed to print memory usage");
         st = KIT_ERR;
       }
     }
   }
   kit_link_session_free(link);
   if (preserved.syms)
     preserved.heap->free(preserved.heap, preserved.syms,
                          sizeof(*preserved.syms) * preserved.cap);
   if (st != KIT_OK && pending_lto && pending_lto->active)
     kit_build_lto_abort(pending_lto);
   return st;
 }
 
 /* build-exe / shared build-lib: compile sources, load link inputs, link. */
 static int build_run_link(BuildOptions* o, KitCompiler* compiler,
                           const KitContext* ctx, const KitCodeOptions* code,
                           const KitDiagnosticOptions* diag,
                           uint8_t output_kind) {
   DriverEnv* env = o->env;
   const KitFileIO* io = ctx->file_io;
   KitWriter* out_w = NULL;
   DriverLoad* obj_lf = NULL;
   DriverLoad* arch_lf = NULL;
   DriverLoad* dso_lf = NULL;
   DriverLoad script_lf = {0};
   KitSlice* obj_in = NULL;
   KitSlice* obj_names = NULL;
   KitLinkArchiveInput* arch_in = NULL;
   KitSlice* dso_in = NULL;
   KitSlice* dso_names = NULL;
   KitLinkInputOrder* order = NULL;
   KitObjBuilder** objs = NULL;
   KitBuildPendingLto pending_lto = {0};
   uint32_t* source_obj_index = NULL;
   uint8_t* source_order_keep = NULL;
   KitLinkScript* script = NULL;
   KitSlice* rpath_slices = NULL;
   KitBuildBatchOptions lto_batch;
   uint32_t nobjs = 0;
   uint32_t i;
   uint32_t norder = 0;
   int rc = 1;
   /* Strict-by-default freestanding policy: a `*-none-*` target, or an explicit
    * -ffreestanding static non-PIE executable, must reject dynamic-link
    * artifacts and cross-input target/format mismatches. Computed once here (the
    * pie value mirrors what driver_link_flags_fill_options derives for lopts.pie)
    * so the per-input arch/format guard below and lopts.freestanding_strict
    * agree on the trigger — otherwise the hosted -ffreestanding path would set
    * strict yet skip the guard. The relocatable partial-link lane never imposes
    * it. */
   int freestanding_strict =
       output_kind == KIT_LINK_OUTPUT_EXE &&
       (o->target.os == KIT_OS_FREESTANDING ||
        (o->freestanding && o->static_link &&
         !driver_link_pie(o->target, o->pie, o->shared, 0)));
 
   if (o->nsources) {
     objs = driver_alloc_zeroed(env, o->nsources * sizeof(*objs));
     source_obj_index =
         driver_alloc_zeroed(env, o->nsources * sizeof(*source_obj_index));
     source_order_keep =
         driver_alloc_zeroed(env, o->nsources * sizeof(*source_order_keep));
     if (!objs || !source_obj_index || !source_order_keep) goto oom;
   }
   if (o->inputs.nobject_files) {
     obj_lf =
         driver_alloc_zeroed(env, o->inputs.nobject_files * sizeof(*obj_lf));
     obj_in =
         driver_alloc_zeroed(env, o->inputs.nobject_files * sizeof(*obj_in));
     obj_names =
         driver_alloc_zeroed(env, o->inputs.nobject_files * sizeof(*obj_names));
     if (!obj_lf || !obj_in || !obj_names) goto oom;
   }
   if (o->inputs.narchives) {
     arch_lf = driver_alloc_zeroed(env, o->inputs.narchives * sizeof(*arch_lf));
     arch_in = driver_alloc_zeroed(env, o->inputs.narchives * sizeof(*arch_in));
     if (!arch_lf || !arch_in) goto oom;
   }
   if (o->inputs.ndsos) {
     dso_lf = driver_alloc_zeroed(env, o->inputs.ndsos * sizeof(*dso_lf));
     dso_in = driver_alloc_zeroed(env, o->inputs.ndsos * sizeof(*dso_in));
     dso_names = driver_alloc_zeroed(env, o->inputs.ndsos * sizeof(*dso_names));
     if (!dso_lf || !dso_in || !dso_names) goto oom;
   }
   if (o->inputs.nlink_items) {
     order = driver_alloc_zeroed(env, o->inputs.nlink_items * sizeof(*order));
     if (!order) goto oom;
   }
 
   for (i = 0; i < o->inputs.nobject_files; ++i) {
     if (driver_load_bytes(io, o->tool, o->inputs.object_files[i], &obj_lf[i],
                           &obj_in[i]) != 0)
       goto out;
     obj_names[i] = kit_slice_cstr(o->inputs.object_files[i]);
   }
   /* Strict freestanding policy: pre-built object inputs must agree with the
    * link target's arch and object format (a freestanding exe link must not
    * silently accept a foreign-arch object). Gated on the same trigger as
    * lopts.freestanding_strict so the hosted -ffreestanding -static -no-pie path
    * runs this guard too (not only the `*-none-*` target). */
   if (freestanding_strict) {
     for (i = 0; i < o->inputs.nobject_files; ++i) {
       KitTargetSpec t;
       if (kit_detect_target(obj_in[i].data, obj_in[i].len, &t) != KIT_OK)
         continue;
       if (t.arch != o->target.arch || t.obj != o->target.obj) {
         driver_errf(o->tool,
                     "freestanding link: input '%s' arch/format does not match "
                     "the link target",
                     o->inputs.object_files[i]);
         goto out;
       }
     }
   }
   for (i = 0; i < o->inputs.narchives; ++i) {
     if (driver_load_bytes(io, o->tool, o->inputs.archives[i].path, &arch_lf[i],
                           &arch_in[i].bytes) != 0)
       goto out;
     arch_in[i].name = kit_slice_cstr(o->inputs.archives[i].path);
     arch_in[i].link_mode = o->inputs.archives[i].link_mode;
     arch_in[i].whole_archive =
         o->inputs.archives[i].whole_archive ? true : false;
     arch_in[i].group_id = o->inputs.archives[i].group_id;
   }
   for (i = 0; i < o->inputs.ndsos; ++i) {
     if (driver_load_bytes(io, o->tool, o->inputs.dsos[i].path, &dso_lf[i],
                           &dso_in[i]) != 0)
       goto out;
     dso_names[i] = kit_slice_cstr(o->inputs.dsos[i].path);
   }
   if (o->link.linker_script) {
     KitSlice dummy;
     if (driver_load_bytes(io, o->tool, o->link.linker_script, &script_lf,
                           &dummy) != 0)
       goto out;
   }
 
   if (script_lf.loaded) {
     KitSlice text = {.s = (const char*)script_lf.fd.data,
                      .len = script_lf.fd.size};
     if (kit_link_script_parse(ctx, text, &script) != KIT_OK) goto out;
   }
 
   {
     memset(&lto_batch, 0, sizeof lto_batch);
     lto_batch.output_kind = output_kind == KIT_LINK_OUTPUT_SHARED
                                 ? KIT_CG_OUTPUT_SHARED
                                 : KIT_CG_OUTPUT_EXECUTABLE;
     lto_batch.interposition_policy =
         output_kind == KIT_LINK_OUTPUT_SHARED
             ? KIT_CG_INTERPOSITION_DEFAULT_VISIBILITY
             : KIT_CG_INTERPOSITION_DEFAULT;
     lto_batch.defer_lto_finish = 1;
     if (build_compile_all(o, compiler, ctx, code, diag, objs, source_obj_index,
                           source_order_keep, &lto_batch, &pending_lto,
                           &nobjs) != 0)
       goto out;
   }
 
   if (build_open_output(ctx, env, o->tool, o->output_path, &out_w) != 0)
     goto out;
 
   /* Translate the recorded link order into KitLinkInputOrder. (build never
    * records SOURCE_MEMORY items, so nsource_files is immaterial here.) */
   norder = driver_link_inputs_build_order(
       &o->inputs, source_obj_index, source_order_keep, o->nsources, order);
 
   {
     KitLinkSessionOptions lopts;
     KitLinkInputs li;
     KitStatus st;
     if (driver_link_flags_fill_options(
             &o->link, o->target, o->pie, o->shared,
             output_kind == KIT_LINK_OUTPUT_RELOCATABLE, output_kind, script,
             &lopts, &rpath_slices) != 0)
       goto out;
     /* Reject dynamic-link artifacts (PT_INTERP, .dynamic/.dynsym, PLT/GOT
      * imports, DSO inputs) for the strict freestanding link. Same trigger as
      * the per-input arch/format guard above (freestanding_strict). */
     if (freestanding_strict) lopts.freestanding_strict = true;
     memset(&li, 0, sizeof(li));
     li.objs = objs;
     li.nobjs = nobjs;
     li.obj_names = obj_names;
     li.obj_bytes = obj_in;
     li.nobj_bytes = o->inputs.nobject_files;
     li.archives = arch_in;
     li.narchives = o->inputs.narchives;
     li.dso_names = dso_names;
     li.dso_bytes = dso_in;
     li.ndsos = o->inputs.ndsos;
     li.order = order;
     li.norder = norder;
     st = build_link_with_lto_reports(o, compiler, ctx, &lopts, &li,
                                      &pending_lto, &lto_batch, out_w);
     rc = (st == KIT_OK) ? 0 : 1;
   }
 
 out:
   if (out_w) kit_writer_close(out_w);
   if (rc == 0 && output_kind == KIT_LINK_OUTPUT_EXE &&
       !driver_streq(o->output_path, "-")) {
     if (driver_mark_executable_output(o->output_path) != 0) {
       driver_errf(o->tool, "failed to set executable mode: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(o->output_path)));
       rc = 1;
     }
   }
   if (script) kit_link_script_free(ctx, script);
   kit_build_lto_abort(&pending_lto);
   driver_link_flags_free_rpath_slices(&o->link, rpath_slices);
   driver_release_bytes(io, &script_lf);
   if (arch_lf)
     for (i = 0; i < o->inputs.narchives; ++i)
       driver_release_bytes(io, &arch_lf[i]);
   if (dso_lf)
     for (i = 0; i < o->inputs.ndsos; ++i) driver_release_bytes(io, &dso_lf[i]);
   if (obj_lf)
     for (i = 0; i < o->inputs.nobject_files; ++i)
       driver_release_bytes(io, &obj_lf[i]);
   if (arch_in)
     driver_free(env, arch_in, o->inputs.narchives * sizeof(*arch_in));
   if (arch_lf)
     driver_free(env, arch_lf, o->inputs.narchives * sizeof(*arch_lf));
   if (dso_in) driver_free(env, dso_in, o->inputs.ndsos * sizeof(*dso_in));
   if (dso_names)
     driver_free(env, dso_names, o->inputs.ndsos * sizeof(*dso_names));
   if (dso_lf) driver_free(env, dso_lf, o->inputs.ndsos * sizeof(*dso_lf));
   if (order) driver_free(env, order, o->inputs.nlink_items * sizeof(*order));
   if (obj_in)
     driver_free(env, obj_in, o->inputs.nobject_files * sizeof(*obj_in));
   if (obj_names)
     driver_free(env, obj_names, o->inputs.nobject_files * sizeof(*obj_names));
   if (obj_lf)
     driver_free(env, obj_lf, o->inputs.nobject_files * sizeof(*obj_lf));
   /* The link session borrows the per-source builders (it frees only its own
    * pointer array), so the caller still owns and must release them. */
   if (objs) {
     for (i = 0; i < nobjs; ++i) kit_obj_builder_free(objs[i]);
     driver_free(env, objs, o->nsources * sizeof(*objs));
   }
   if (source_order_keep)
     driver_free(env, source_order_keep,
                 o->nsources * sizeof(*source_order_keep));
   if (source_obj_index)
     driver_free(env, source_obj_index, o->nsources * sizeof(*source_obj_index));
   return rc;
 
 oom:
   driver_errf(o->tool, "out of memory");
   goto out;
 }
 
 /* build-obj multi-source: combine into one relocatable object (ld -r). */
 static int build_run_relocatable(BuildOptions* o, KitCompiler* compiler,
                                  const KitContext* ctx,
                                  const KitCodeOptions* code,
                                  const KitDiagnosticOptions* diag) {
   DriverEnv* env = o->env;
   KitObjBuilder** objs = NULL;
   uint32_t* source_obj_index = NULL;
   uint8_t* source_order_keep = NULL;
   KitLinkInputOrder* order = NULL;
   KitBuildPendingLto pending_lto = {0};
   KitWriter* out_w = NULL;
   KitBuildBatchOptions lto_batch;
   uint32_t nobjs = 0;
   uint32_t norder = 0;
   uint32_t i;
   int rc = 1;
 
   objs = driver_alloc_zeroed(env, o->nsources * sizeof(*objs));
   source_obj_index =
       driver_alloc_zeroed(env, o->nsources * sizeof(*source_obj_index));
   source_order_keep =
       driver_alloc_zeroed(env, o->nsources * sizeof(*source_order_keep));
   order = driver_alloc_zeroed(env, o->nsources * sizeof(*order));
   if (!objs || !source_obj_index || !source_order_keep || !order) {
     driver_errf(o->tool, "out of memory");
     goto out;
   }
   {
     memset(&lto_batch, 0, sizeof lto_batch);
     lto_batch.output_kind = KIT_CG_OUTPUT_RELOCATABLE;
     lto_batch.interposition_policy = KIT_CG_INTERPOSITION_DEFAULT;
     lto_batch.defer_lto_finish = 1;
     if (build_compile_all(o, compiler, ctx, code, diag, objs, source_obj_index,
                           source_order_keep, &lto_batch, &pending_lto,
                           &nobjs) != 0)
       goto out;
   }
   for (i = 0; i < o->nsources; ++i) {
     if (!source_order_keep[i]) continue;
     order[norder].kind = KIT_LINK_INPUT_OBJ;
     order[norder].index = source_obj_index[i];
     ++norder;
   }
   if (build_open_output(ctx, env, o->tool, o->output_path, &out_w) != 0)
     goto out;
   {
     KitLinkSessionOptions lopts;
     KitLinkInputs li;
     KitStatus st;
     memset(&lopts, 0, sizeof(lopts));
     lopts.output_kind = KIT_LINK_OUTPUT_RELOCATABLE;
     lopts.allow_undefined = 1;
     lopts.strip_debug = o->link.strip_debug ? true : false;
     memset(&li, 0, sizeof(li));
     li.objs = objs;
     li.nobjs = nobjs;
     li.order = order;
     li.norder = norder;
     st = kit_build_link_with_lto(compiler, &lopts, &li, &pending_lto,
                                  &lto_batch, out_w);
     rc = (st == KIT_OK) ? 0 : 1;
   }
 
 out:
   if (out_w) kit_writer_close(out_w);
   kit_build_lto_abort(&pending_lto);
   if (order) driver_free(env, order, o->nsources * sizeof(*order));
   /* The link session borrows the builders; release them here (see
    * build_run_link). */
   if (objs) {
     for (i = 0; i < nobjs; ++i) kit_obj_builder_free(objs[i]);
     driver_free(env, objs, o->nsources * sizeof(*objs));
   }
   if (source_order_keep)
     driver_free(env, source_order_keep,
                 o->nsources * sizeof(*source_order_keep));
   if (source_obj_index)
     driver_free(env, source_obj_index, o->nsources * sizeof(*source_obj_index));
   return rc;
 }
 
 /* build-obj wasm multi-source: merge all inputs into one .wasm via CG merge. */
 static int build_run_wasm_module(BuildOptions* o, KitCompiler* compiler,
                                  const KitContext* ctx,
                                  const KitCodeOptions* code,
                                  const KitDiagnosticOptions* diag) {
   DriverEnv* env = o->env;
   KitObjBuilder** objs = NULL;
   uint32_t* source_obj_index = NULL;
   uint8_t* source_order_keep = NULL;
   KitWriter* out_w = NULL;
   KitCodeOptions code2 = *code;
   uint32_t nobjs = 0;
   uint32_t i;
   int rc = 1;
 
   code2.lto = true;
 
   objs = driver_alloc_zeroed(env, o->nsources * sizeof(*objs));
   source_obj_index =
       driver_alloc_zeroed(env, o->nsources * sizeof(*source_obj_index));
   source_order_keep =
       driver_alloc_zeroed(env, o->nsources * sizeof(*source_order_keep));
   if (!objs || !source_obj_index || !source_order_keep) {
     driver_errf(o->tool, "out of memory");
     goto out;
   }
   {
     KitBuildBatchOptions batch;
     memset(&batch, 0, sizeof batch);
     batch.output_kind = KIT_CG_OUTPUT_RELOCATABLE;
     batch.interposition_policy = KIT_CG_INTERPOSITION_DEFAULT;
     if (build_compile_all(o, compiler, ctx, &code2, diag, objs,
                           source_obj_index, source_order_keep, &batch, NULL,
                           &nobjs) != 0)
       goto out;
   }
   if (nobjs != 1) {
     driver_errf(o->tool,
                 "build-obj: wasm multi-input expects a single merged module");
     goto out;
   }
   if (build_open_output(ctx, env, o->tool, o->output_path, &out_w) != 0)
     goto out;
   rc = (kit_obj_builder_emit(objs[0], out_w) == KIT_OK) ? 0 : 1;
 
 out:
   if (out_w) kit_writer_close(out_w);
   if (objs) {
     for (i = 0; i < nobjs; ++i) kit_obj_builder_free(objs[i]);
     driver_free(env, objs, o->nsources * sizeof(*objs));
   }
   if (source_order_keep)
     driver_free(env, source_order_keep,
                 o->nsources * sizeof(*source_order_keep));
   if (source_obj_index)
     driver_free(env, source_obj_index, o->nsources * sizeof(*source_obj_index));
   return rc;
 }
 
 /* build-exe wasm: merge all sources into one .wasm with DCE/internalization. */
 static int build_run_wasm_exe(BuildOptions* o, KitCompiler* compiler,
                               const KitContext* ctx, const KitCodeOptions* code,
                               const KitDiagnosticOptions* diag) {
   DriverEnv* env = o->env;
   KitObjBuilder** objs = NULL;
   uint32_t* source_obj_index = NULL;
   uint8_t* source_order_keep = NULL;
   KitBuildPendingLto pending_lto = {0};
   KitWriter* out_w = NULL;
   KitCodeOptions code2 = *code;
   uint32_t nobjs = 0;
   uint32_t i;
   int rc = 1;
 
   code2.lto = true;
 
   objs = driver_alloc_zeroed(env, o->nsources * sizeof(*objs));
   source_obj_index =
       driver_alloc_zeroed(env, o->nsources * sizeof(*source_obj_index));
   source_order_keep =
       driver_alloc_zeroed(env, o->nsources * sizeof(*source_order_keep));
   if (!objs || !source_obj_index || !source_order_keep) {
     driver_errf(o->tool, "out of memory");
     goto out;
   }
   {
     KitBuildBatchOptions batch;
     memset(&batch, 0, sizeof batch);
     batch.output_kind = KIT_CG_OUTPUT_EXECUTABLE;
     batch.interposition_policy = KIT_CG_INTERPOSITION_NONE;
     batch.defer_lto_finish = 1;
     if (build_compile_all(o, compiler, ctx, &code2, diag, objs,
                           source_obj_index, source_order_keep, &batch,
                           &pending_lto, &nobjs) != 0)
       goto out;
   }
   if (nobjs != 1) {
     driver_errf(o->tool, "build-exe: wasm expects a single merged module");
     goto out;
   }
   {
     const char* entry_name = o->link.entry ? o->link.entry : "main";
     KitSym entry_interned =
         kit_sym_intern(compiler, kit_slice_cstr(entry_name));
     KitObjSymbol entry_sym = KIT_OBJ_SYMBOL_NONE;
     KitBuildBatchOptions batch2;
     KitCgSym csym;
 
     if (!entry_interned ||
         kit_obj_builder_find_symbol(pending_lto.obj, entry_interned,
                                     &entry_sym) != KIT_OK) {
       driver_errf(o->tool, "build-exe: entry symbol '%s' not found in module",
                   entry_name);
       goto out;
     }
     csym = (KitCgSym)entry_sym;
     memset(&batch2, 0, sizeof batch2);
     batch2.output_kind = KIT_CG_OUTPUT_EXECUTABLE;
     batch2.interposition_policy = KIT_CG_INTERPOSITION_NONE;
     if (kit_build_lto_finish(&pending_lto, &batch2, &csym, 1) !=
         KIT_OK) {
       driver_errf(o->tool, "build-exe: LTO finish failed");
       goto out;
     }
     kit_obj_builder_wasm_add_custom(objs[0], KIT_SLICE_LIT("kit-entry"),
                                     kit_slice_cstr(entry_name));
   }
   if (build_open_output(ctx, env, o->tool, o->output_path, &out_w) != 0)
     goto out;
   rc = (kit_obj_builder_emit(objs[0], out_w) == KIT_OK) ? 0 : 1;
 
 out:
   if (out_w) kit_writer_close(out_w);
   if (pending_lto.active) kit_build_lto_abort(&pending_lto);
   if (objs) {
     for (i = 0; i < nobjs; ++i) kit_obj_builder_free(objs[i]);
     driver_free(env, objs, o->nsources * sizeof(*objs));
   }
   if (source_order_keep)
     driver_free(env, source_order_keep,
                 o->nsources * sizeof(*source_order_keep));
   if (source_obj_index)
     driver_free(env, source_obj_index, o->nsources * sizeof(*source_obj_index));
   return rc;
 }
 
 /* build-lib static: archive every compiled source object. */
 static int build_run_archive(BuildOptions* o, KitCompiler* compiler,
                              const KitContext* ctx, const KitCodeOptions* code,
                              const KitDiagnosticOptions* diag) {
   DriverEnv* env = o->env;
   KitObjBuilder** objs = NULL;
   uint32_t* source_obj_index = NULL;
   uint8_t* source_order_keep = NULL;
   KitSlice* names = NULL;
   char** owned_names = NULL;
   size_t* owned_name_sizes = NULL;
   KitWriter* out_w = NULL;
   uint32_t nobjs = 0;
   uint32_t i;
   int rc = 1;
 
   objs = driver_alloc_zeroed(env, o->nsources * sizeof(*objs));
   source_obj_index =
       driver_alloc_zeroed(env, o->nsources * sizeof(*source_obj_index));
   source_order_keep =
       driver_alloc_zeroed(env, o->nsources * sizeof(*source_order_keep));
   names = driver_alloc_zeroed(env, o->nsources * sizeof(*names));
   owned_names = driver_alloc_zeroed(env, o->nsources * sizeof(*owned_names));
   owned_name_sizes =
       driver_alloc_zeroed(env, o->nsources * sizeof(*owned_name_sizes));
   if (!objs || !source_obj_index || !source_order_keep || !names ||
       !owned_names || !owned_name_sizes) {
     driver_errf(o->tool, "out of memory");
     goto out;
   }
   {
     KitBuildBatchOptions batch;
     memset(&batch, 0, sizeof batch);
     batch.output_kind = KIT_CG_OUTPUT_ARCHIVE_MEMBER;
     batch.interposition_policy = KIT_CG_INTERPOSITION_DEFAULT;
     if (build_compile_all(o, compiler, ctx, code, diag, objs, source_obj_index,
                           source_order_keep, &batch, NULL, &nobjs) != 0)
       goto out;
   }
   /* build-lib always emits objects (validated), so build_default_obj_name
    * yields the right `.o`/`.obj` member name. */
   for (i = 0; i < o->nsources; ++i) {
     uint32_t oi;
     if (!source_order_keep[i]) continue;
     oi = source_obj_index[i];
     owned_names[oi] = build_default_obj_name(env, o, o->sources[i].path,
                                              &owned_name_sizes[oi]);
     if (!owned_names[oi]) {
       driver_errf(o->tool, "out of memory");
       goto out;
     }
     names[oi] = kit_slice_cstr(owned_names[oi]);
   }
   if (build_open_output(ctx, env, o->tool, o->output_path, &out_w) != 0)
     goto out;
   rc = driver_archive_emit(env, ctx, o->tool, objs, names, nobjs, o->epoch,
                            out_w);
 
 out:
   if (out_w) kit_writer_close(out_w);
   if (objs)
     for (i = 0; i < nobjs; ++i) kit_obj_builder_free(objs[i]);
   if (owned_names) {
     for (i = 0; i < o->nsources; ++i)
       if (owned_names[i]) driver_free(env, owned_names[i], owned_name_sizes[i]);
   }
   if (objs) driver_free(env, objs, o->nsources * sizeof(*objs));
   if (source_order_keep)
     driver_free(env, source_order_keep,
                 o->nsources * sizeof(*source_order_keep));
   if (source_obj_index)
     driver_free(env, source_obj_index, o->nsources * sizeof(*source_obj_index));
   if (names) driver_free(env, names, o->nsources * sizeof(*names));
   if (owned_names)
     driver_free(env, owned_names, o->nsources * sizeof(*owned_names));
   if (owned_name_sizes)
     driver_free(env, owned_name_sizes, o->nsources * sizeof(*owned_name_sizes));
   return rc;
 }
 
 /* build-lib --emit=c: merge semantic sources into one C translation unit. */
 static int build_run_c_tu(BuildOptions* o, KitCompiler* compiler,
                           const KitContext* ctx, const KitCodeOptions* code,
                           const KitDiagnosticOptions* diag) {
   BuildSourceBatch sources;
   KitBuildBatchOptions batch;
   KitWriter* out_w = NULL;
   uint32_t i;
   int rc = 1;
 
   if (build_source_batch_init(o, compiler, ctx, &sources) != 0) return 1;
   for (i = 0; i < o->nsources; ++i) {
     KitFrontendCaps caps;
     memset(&caps, 0, sizeof caps);
     if (kit_frontend_caps(compiler, sources.sources[i].lang, &caps) != KIT_OK ||
         caps.lto_mode != KIT_FRONTEND_LTO_CG) {
       driver_errf(o->tool,
                   "cannot emit C for %.*s: the %.*s frontend is object-only",
                   KIT_SLICE_ARG(sources.sources[i].name),
                   KIT_SLICE_ARG(kit_slice_cstr(kit_language_name(
                       compiler, sources.sources[i].lang))));
       goto out;
     }
   }
   if (build_open_output(ctx, o->env, o->tool, o->output_path, &out_w) != 0)
     goto out;
 
   memset(&batch, 0, sizeof batch);
   batch.output_kind = KIT_CG_OUTPUT_ARCHIVE_MEMBER;
   batch.interposition_policy = KIT_CG_INTERPOSITION_DEFAULT;
   if (kit_build_emit_c(compiler, code, diag, sources.sources, o->nsources,
                        &batch, out_w) != KIT_OK) {
     driver_errf(o->tool, "failed to emit C translation unit");
     goto out;
   }
   rc = 0;
 
 out:
   if (out_w) kit_writer_close(out_w);
   build_source_batch_fini(o, compiler, ctx, &sources);
   return rc;
 }
 
 /* build-obj per-source: check-only, or one output per source (obj/asm/c/ir). */
 static int build_run_per_source(BuildOptions* o, KitCompiler* compiler,
                                 const KitContext* ctx,
                                 const KitCodeOptions* code_in,
                                 const KitDiagnosticOptions* diag) {
   DriverEnv* env = o->env;
   KitCodeOptions code = *code_in;
   uint32_t i;
 
   code.emit_asm_source = (o->emit == BUILD_EMIT_ASM) ? true : false;
   code.emit_c_source = (o->emit == BUILD_EMIT_C) ? true : false;
   code.emit_ir = (o->emit == BUILD_EMIT_IR) ? true : false;
 
   for (i = 0; i < o->nsources; ++i) {
     if (o->syntax_only) {
       KitObjBuilder* ob = NULL;
       int rc =
           build_compile_source(o, compiler, ctx, i, &code, diag, NULL, &ob);
       kit_obj_builder_free(ob);
       if (rc != 0) return rc;
       continue;
     }
     {
       const char* out_path = o->output_path;
       char* owned = NULL;
       size_t owned_size = 0;
       KitWriter* w = NULL;
       int rc;
       if (!out_path) {
         owned = build_default_obj_name(env, o, o->sources[i].path, &owned_size);
         if (!owned) {
           driver_errf(o->tool, "out of memory");
           return 1;
         }
         out_path = owned;
       }
       if (build_open_output(ctx, env, o->tool, out_path, &w) != 0) {
         if (owned) driver_free(env, owned, owned_size);
         return 1;
       }
       rc = build_compile_source(o, compiler, ctx, i, &code, diag, w, NULL);
       kit_writer_close(w);
       if (owned) driver_free(env, owned, owned_size);
       if (rc != 0) return rc;
     }
   }
   return 0;
 }
 
 /* ===================================================================== */
 /* validation                                                             */
 /* ===================================================================== */
 
 static int build_validate(BuildOptions* o) {
   uint32_t total_link = o->inputs.nobject_files + o->inputs.narchives +
                         o->inputs.ndsos + o->inputs.npending_libs +
                         o->inputs.npending_frameworks;
 
   if (o->nsources == 0 && total_link == 0) {
     driver_errf(o->tool, "no input files");
     return 1;
   }
   if (o->kind != BUILD_OUT_EXE && (o->link.map_path || o->link.symbols_path)) {
     driver_errf(o->tool, "--map/--symbols are only valid for build-exe");
     return 1;
   }
 
   /* -dynamic selects the default executable link mode for build-exe and the
    * not-yet-supported shared-library mode for build-lib. -shared is the GCC
    * spelling for producing a shared library, so build-exe rejects it. */
 
   if (o->kind == BUILD_OUT_EXE) {
     if (o->shared_requested) {
       driver_errf(o->tool, "-shared is not valid for build-exe");
       return 1;
     }
     if (o->emit != BUILD_EMIT_OBJ || o->syntax_only) {
       driver_errf(o->tool, "--emit/-S/-fsyntax-only are build-obj options");
       return 1;
     }
     if (!o->output_path) {
       o->output_path = (o->target.obj == KIT_OBJ_WASM)
                            ? "a.wasm"
                            : driver_default_exe_name(o->target);
     }
     if (o->target.obj == KIT_OBJ_WASM) {
       uint32_t total_link = o->inputs.nobject_files + o->inputs.narchives +
                             o->inputs.ndsos + o->inputs.npending_libs +
                             o->inputs.npending_frameworks;
       if (total_link) {
         driver_errf(o->tool,
                     "build-exe -target wasm32-none accepts only source files "
                     "(no .o / .a / -l inputs)");
         return 1;
       }
       if (o->link.map_path || o->link.symbols_path) {
         driver_errf(o->tool,
                     "--map/--symbols require the native linker path");
         return 1;
       }
     }
     return 0;
   }
 
   if (o->kind == BUILD_OUT_LIB) {
     if ((o->emit != BUILD_EMIT_OBJ && o->emit != BUILD_EMIT_C) ||
         o->syntax_only) {
       driver_errf(o->tool,
                   "build-lib supports object output or --emit=c; "
                   "-S/--emit=ir/-fsyntax-only are build-obj options");
       return 1;
     }
     if (o->emit == BUILD_EMIT_C && o->dynamic) {
       driver_errf(o->tool, "--emit=c is incompatible with -dynamic/-shared");
       return 1;
     }
     if (total_link != 0) {
       driver_errf(o->tool,
                   "build-lib takes only sources; pass .o/.a/-l to build-exe");
       return 1;
     }
     if (o->nsources == 0) {
       driver_errf(o->tool, "no source files");
       return 1;
     }
     if (!o->output_path) {
       driver_errf(o->tool, "-o is required (no default library name)");
       return 1;
     }
     return 0;
   }
 
   /* build-obj */
   if (total_link != 0) {
     driver_errf(o->tool,
                 "build-obj takes only sources; pass .o/.a/-l to build-exe");
     return 1;
   }
   if (o->nsources == 0) {
     driver_errf(o->tool, "no source files");
     return 1;
   }
   if (o->dynamic) {
     driver_errf(o->tool, "-dynamic/-shared is only valid for build-lib");
     return 1;
   }
   if (o->syntax_only) {
     if (o->output_path) {
       driver_errf(o->tool, "-o is incompatible with -fsyntax-only");
       return 1;
     }
     return 0;
   }
   if (o->emit == BUILD_EMIT_IR && o->opt_level < 1) {
     driver_errf(o->tool,
                 "--emit=ir requires -O1 or higher (the IR tape is only "
                 "recorded when the optimizer runs)");
     return 1;
   }
   if (o->emit == BUILD_EMIT_OBJ && o->nsources > 1) {
     /* relocatable combine */
     if (!o->output_path) {
       driver_errf(o->tool,
                   "-o is required to combine multiple sources into one object");
       return 1;
     }
     return 0;
   }
   /* per-source emit (single obj, or asm/c/ir) */
   if (o->output_path && o->nsources > 1) {
     driver_errf(o->tool, "-o cannot be used with multiple sources");
     return 1;
   }
   if (o->emit == BUILD_EMIT_C && !o->output_path) {
     driver_errf(o->tool, "--emit=c requires -o");
     return 1;
   }
   return 0;
 }
 
 /* ===================================================================== */
 /* driver                                                                 */
 /* ===================================================================== */
 
 static int build_apply_env(BuildOptions* o) {
   const char* sde = driver_getenv("SOURCE_DATE_EPOCH");
   if (sde && driver_parse_u64(sde, &o->epoch) != 0) {
     driver_errf(o->tool, "invalid SOURCE_DATE_EPOCH: %.*s",
                 KIT_SLICE_ARG(kit_slice_cstr(sde)));
     return 1;
   }
   return 0;
 }
 
 static int build_record_framework(BuildOptions* o, const char* name) {
   DriverPendingFramework* pf;
   if (!name || !name[0]) {
     driver_errf(o->tool, "-framework requires an argument");
     return 1;
   }
   pf = &o->inputs.pending_frameworks[o->inputs.npending_frameworks++];
   pf->name = name;
   driver_link_inputs_push(&o->inputs, DRIVER_LINK_FRAMEWORK,
                           o->inputs.npending_frameworks - 1u);
   return 0;
 }
 
 static int build_main(int argc, char** argv, int kind, const char* tool,
                       const KitDriverExtension* ext) {
   DriverEnv env;
   BuildOptions o = {0};
   DriverRuntimeSupport runtime = {0};
   int runtime_resolved = 0;
   KitContext ctx;
   KitTarget* target = NULL;
   KitCompiler* compiler = NULL;
   KitCodeOptions code;
   KitDiagnosticOptions diag = {0};
   uint32_t gi;
   int rc = 2;
 
   driver_env_init(&env);
   ctx = driver_env_to_context(&env);
   o.env = &env;
   o.tool = tool;
   o.kind = kind;
   o.driver_path = argv[0];
 
   if (kit_frontend_registry_new(&ctx, &o.frontends) != KIT_OK ||
       kit_frontend_registry_add_builtin(o.frontends) != KIT_OK ||
       (ext && ext->register_frontends &&
        ext->register_frontends(o.frontends) != KIT_OK)) {
     driver_errf(tool, "failed to initialize frontend registry");
     rc = 1;
     goto done;
   }
 
   if (build_alloc(&o, argc) != 0) {
     rc = 2;
     goto done;
   }
   if (build_parse(argc, argv, &o) != 0) goto done;
   if (build_apply_env(&o) != 0) goto done;
 
   o.shared = (o.kind == BUILD_OUT_LIB && o.dynamic &&
               o.emit == BUILD_EMIT_OBJ);
   if (o.shared && !o.pic_explicit) o.target.pic = KIT_PIC_PIC;
   if (o.shared && o.target.obj != KIT_OBJ_ELF) {
     driver_errf(tool, "-shared output is supported only for ELF targets in v1");
     goto done;
   }
   if (o.shared && o.target.pic == KIT_PIC_NONE) {
     driver_errf(tool, "-shared requires PIC input; remove -fno-pic/-static");
     goto done;
   }
 
   if (build_validate(&o) != 0) goto done;
 
   /* Freestanding runtime headers so C/asm #includes resolve (mirrors compile);
    * for link outputs, also the runtime archive + hosted libc wiring. */
   if (driver_runtime_resolve(&env, o.support_dir, o.driver_path, &runtime) ==
       0) {
     runtime_resolved = 1;
   } else {
     driver_errf(tool, "support dir not found");
     rc = 1;
     goto done;
   }
 
   /* Hosted defines/includes are a compile property and therefore apply to
    * build-obj/build-lib as well as executable links.  Link-only search paths,
    * CRT objects, and libraries stay inside the link-output branch below. */
   build_enable_hosted_for_sysroot(&o);
   build_apply_default_hosted_profile(&o);
   if (build_apply_hosted_profile(&o) != 0) {
     rc = 1;
     goto done;
   }
   /* Hosted system headers precede Kit's freestanding fallback headers. This
    * keeps <stdlib.h> on the native SDK while retaining compiler builtins that
    * the SDK does not provide. */
   if (!o.nostdinc &&
       (o.hosted.profile_name
            ? driver_runtime_append_freestanding_headers(&runtime,
                                                          &o.groups[0].cf)
            : driver_runtime_add_freestanding_headers(&runtime,
                                                       &o.groups[0].cf)) != 0) {
     driver_errf(tool, "failed to add freestanding headers");
     rc = 1;
     goto done;
   }
 
   if (build_is_link_output(&o)) {
     if (driver_link_inputs_append_windows_lib_dirs(&o.inputs, &o.sysroot,
                                                    o.target) != 0) {
       rc = 1;
       goto done;
     }
     if (driver_link_inputs_append_sysroot_framework_dirs(&o.inputs, &o.sysroot,
                                                          o.target) != 0) {
       rc = 1;
       goto done;
     }
     if (driver_link_inputs_resolve_pending(&o.inputs, o.target,
                                            o.static_link) != 0) {
       rc = 1;
       goto done;
     }
     if (o.target.os == KIT_OS_FREESTANDING && o.inputs.ndsos) {
       driver_errf(tool, "freestanding executable links do not accept DSO inputs");
       rc = 1;
       goto done;
     }
     if ((!o.shared || driver_target_shared_uses_hosted(o.target)) &&
         !o.no_stdlib && !o.no_defaultlibs) {
       DriverRuntimeArchive rt = {0};
       if (driver_runtime_prepare_archive(&env, tool, &runtime, o.target,
                                          o.epoch, &rt) != 0) {
         driver_runtime_archive_fini(&env, &rt);
         rc = 1;
         goto done;
       }
       driver_link_inputs_insert_runtime_archives(
           &o.inputs, &rt, o.target, o.hosted.nfinal, o.hosted.nafter);
       driver_runtime_archive_fini(&env, &rt);
     }
   } else if (o.inputs.npending_libs || o.inputs.npending_frameworks) {
     driver_errf(tool, "-l/-framework are only valid for build-exe");
     rc = 1;
     goto done;
   }
 
   /* Build per-group merged preprocessor views now that the global baseline
    * (groups[0]) holds the runtime/hosted includes and defines. */
   for (gi = 0; gi < o.ngroups; ++gi) {
     if (build_group_build_pp(&o, gi) != 0) {
       rc = 1;
       goto done;
     }
   }
 
   if (driver_target_new(&ctx, o.target, &o.target_features, tool, &target) !=
       KIT_OK) {
     driver_errf(tool, "failed to initialize compiler");
     rc = 1;
     goto done;
   }
   {
     KitCompilerOptions copts;
     memset(&copts, 0, sizeof copts);
     copts.frontends = o.frontends;
     if (kit_compiler_new_ex(target, &ctx, &copts, &compiler) != KIT_OK) {
       driver_errf(tool, "failed to initialize compiler");
       rc = 1;
       goto done;
     }
     driver_diag_set_compiler(compiler);
   }
 
   build_fill_code(&o, &code);
   diag.warnings_are_errors = o.warnings_are_errors ? true : false;
   diag.max_errors = o.max_errors;
 
   if (o.kind == BUILD_OUT_EXE) {
     if (o.target.obj == KIT_OBJ_WASM)
       rc = build_run_wasm_exe(&o, compiler, &ctx, &code, &diag);
     else
       rc =
           build_run_link(&o, compiler, &ctx, &code, &diag, KIT_LINK_OUTPUT_EXE);
   } else if (o.kind == BUILD_OUT_LIB) {
     if (o.emit == BUILD_EMIT_C)
       rc = build_run_c_tu(&o, compiler, &ctx, &code, &diag);
     else if (o.shared)
       rc = build_run_link(&o, compiler, &ctx, &code, &diag,
                           KIT_LINK_OUTPUT_SHARED);
     else
       rc = build_run_archive(&o, compiler, &ctx, &code, &diag);
   } else if (o.syntax_only) {
     rc = build_run_per_source(&o, compiler, &ctx, &code, &diag);
   } else if (o.emit == BUILD_EMIT_OBJ && o.nsources > 1 &&
              o.target.obj == KIT_OBJ_WASM) {
     rc = build_run_wasm_module(&o, compiler, &ctx, &code, &diag);
   } else if (o.emit == BUILD_EMIT_OBJ && o.nsources > 1) {
     rc = build_run_relocatable(&o, compiler, &ctx, &code, &diag);
   } else {
     rc = build_run_per_source(&o, compiler, &ctx, &code, &diag);
   }
 
   if (rc == 0 &&
       driver_diag_finish(&env, tool, o.warnings_are_errors, o.max_errors))
     rc = 1;
 
 done:
   if (compiler) driver_compiler_free(compiler);
   kit_target_free(target);
   if (runtime_resolved) driver_runtime_support_fini(&env, &runtime);
   build_release(&o);
   if (o.frontends) kit_frontend_registry_free(o.frontends);
   driver_env_fini(&env);
   return rc;
 }
 
 /* ===================================================================== */
 /* help + entry points                                                    */
 /* ===================================================================== */
 
 void driver_help_build_exe(void) {
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "kit build-exe — link a polyglot source set into an executable\n"
           "\n"
           "USAGE\n"
           "  kit build-exe [options] inputs...\n"
           "\n"
           "DESCRIPTION\n"
           "  Compiles registered source languages (language per file) in memory\n"
           "  and links them with any .o/.a/.so inputs into one executable. No\n"
           "  intermediate files. For -target wasm32-none, inputs must be\n"
           "  sources supplied in this invocation; .o/.a/-l Wasm linking is not\n"
           "  a v1 feature.\n"
           "\n"
           "INPUTS\n"
           "  Registered sources are C (.c), assembly (.s/.S), and WebAssembly\n"
           "  (.wat/.wasm), selected by suffix or -x. Native links may also\n"
           "  consume target-compatible .o, .a, and ELF .so inputs.\n"
           "\n"
           "OPTIONS\n"
           "  -o PATH               Output (default a.out / a.exe)\n"
           "  -O0 -O1 -O2  -g       Optimization / debug info (-O2 aliases "
           "-O1)\n"
           "  -target TRIPLE        Cross-compile target\n"
           "  --sysroot DIR         User-supplied hosted cross sysroot\n"
           "  -isysroot DIR         Hosted SDK/sysroot include root\n"
           "  --support-dir DIR     Kit distribution support root\n"
           "  -arch ARCH            Darwin-style target architecture\n"
           "  -platform_version P MIN SDK\n"
           "                        Darwin-style target platform\n"
           "  -flto                 Link-time optimization for source inputs\n"
           "  -static               Fully static executable\n"
           "  -l NAME  -L DIR       Link a library / add a search dir\n"
           "  -framework NAME  -F DIR\n"
           "                        Link a Darwin framework / add a search dir\n"
           "  -e SYM  -T script.ld  Entry symbol / linker script\n"
           "  -Wl,...               Linker pass-through\n"
           "  --group [flags] -- sources...   Scope compile flags to sources\n"
           "  -X<lang> FLAG         Per-language frontend flag\n"
           "  -h, --help            Show this help\n"
           "  --version             Show Kit version\n"
           "\n"
           "DISCOVERY AND REQUIREMENTS\n"
           "  Relocated distributions discover sibling support automatically;\n"
           "  --support-dir remains an authoritative override. Native macOS uses\n"
           "  the discovered SDK by default. Hosted cross builds require --sysroot.\n"
           "\n"
           "EXAMPLES\n"
           "  kit build-exe main.c util.c -o app\n"
           "\n"
           "  # Flag-scoped C groups plus an assembly source.\n"
           "  kit build-exe --group -DLEFT=20 -- left.c \\\n"
           "    --group -DRIGHT=22 -- right.c main.c helper.s -o grouped\n"
           "\n"
           "  # Freestanding: provide startup code and a linker script.\n"
           "  kit build-exe \\\n"
           "    -target aarch64-none-elf -T link.ld -e _start \\\n"
           "    start.s kernel.c -o kernel.elf\n"
           "\n"
           "EXIT CODES\n"
           "  0   success    1   compile/link/I/O error    2   bad usage\n")));
 }
 
 void driver_help_build_lib(void) {
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "kit build-lib — build a library or one C translation unit\n"
           "\n"
           "USAGE\n"
           "  kit build-lib -o LIB.a [options] sources...\n"
           "  kit build-lib --emit=c -o LIB.c [options] sources...\n"
           "  kit build-lib -dynamic -o LIB.so [options] sources...\n"
           "\n"
           "DESCRIPTION\n"
           "  Compiles a polyglot source set in memory and archives the "
           "objects\n"
           "  into a static library (.a), or links an ELF shared library with\n"
           "  -dynamic/-shared. --emit=c merges semantic sources into one\n"
           "  target-locked C translation unit. Non-ELF shared-library output\n"
           "  is rejected.\n"
           "\n"
           "INPUTS\n"
           "  Registered sources are C (.c), assembly (.s/.S), and WebAssembly\n"
           "  (.wat/.wasm), selected by suffix or -x. --emit=c accepts semantic\n"
           "  frontends (C, Toy, Wasm), not standalone assembly. Native ELF\n"
           "  dynamic links may also consume compatible link inputs.\n"
           "\n"
           "OPTIONS\n"
           "  -o PATH               Output path (required)\n"
           "  --emit=c              Emit one C translation unit\n"
           "  -dynamic, -shared     Build an ELF shared library\n"
           "  -fPIC                 Position-independent code\n"
           "  -O0 -O1 -O2  -g       Optimization / debug info (-O2 aliases "
           "-O1)\n"
           "  -flto                 Link-time optimization for source inputs\n"
           "  -target TRIPLE        Cross-compile target\n"
           "  --sysroot DIR         User-supplied hosted cross sysroot\n"
           "  -isysroot DIR         Hosted SDK/sysroot include root\n"
           "  --support-dir DIR     Kit distribution support root\n"
           "  -L DIR, -l NAME       Shared-link library search/input\n"
           "  --group [flags] -- sources...   Scope compile flags to sources\n"
           "  -X<lang> FLAG         Per-language frontend flag\n"
           "  -h, --help            Show this help\n"
           "  --version             Show Kit version\n"
           "\n"
           "DISCOVERY AND REQUIREMENTS\n"
           "  Relocated distributions discover sibling support automatically.\n"
           "  Native macOS discovers its SDK; hosted cross targets require an\n"
           "  explicit sysroot. Static .a output is the portable library shape;\n"
           "  -dynamic/-shared is ELF-only. Generated C must be compiled for the\n"
           "  same target selected here because its layouts are target-locked.\n"
           "\n"
           "EXAMPLES\n"
           "  kit build-lib \\\n"
           "    -o libanswer.a answer.c helper.s\n"
           "\n"
           "  kit build-lib --emit=c -o answer_amalgam.c answer.c helper.c\n"
           "\n"
           "  # Replace SYSROOT with a supplied x86-64 Linux sysroot.\n"
           "  SYSROOT=/replace/with/x86_64-linux-sysroot\n"
           "  kit build-lib \\\n"
           "    -target x86_64-linux-gnu --sysroot \"$SYSROOT\" \\\n"
           "    -dynamic -fPIC -o libanswer.so answer.c\n"
           "\n"
           "EXIT CODES\n"
           "  0   success    1   compile/link/I/O error    2   bad usage\n")));
 }
 
 void driver_help_build_obj(void) {
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "kit build-obj — compile sources to an object (or asm / C / IR)\n"
           "\n"
           "USAGE\n"
           "  kit build-obj [options] sources...\n"
           "\n"
           "DESCRIPTION\n"
           "  Compiles each source (registered language by suffix or -x) to an\n"
           "  object. Multiple sources with --emit=obj combine into one\n"
           "  relocatable object (ld -r), except -target wasm32-none merges the\n"
           "  same source batch into one final wasm32 module. Separate Wasm\n"
           "  object/static linking is not a v1 feature. The kit-native\n"
           "  replacement for the retired `compile` tool.\n"
           "\n"
           "REGISTERED LANGUAGES\n"
           "  C (.c), assembly (.s/.S), and WebAssembly (.wat/.wasm), selected\n"
           "  by suffix or -x c|asm|wat|wasm. Frontend-specific options use\n"
           "  -X<lang> FLAG.\n"
           "\n"
           "OPTIONS\n"
           "  -o PATH               Output (default <base>.o; required for a\n"
           "                        multi-source combine and for --emit=c)\n"
           "  --emit=obj|asm|c|ir   Output form (ir requires -O1+)\n"
           "  -S                    Alias for --emit=asm\n"
           "  -fsyntax-only         Check only; write no output\n"
           "  -O0 -O1 -O2  -g       Optimization / debug info (-O2 aliases "
           "-O1)\n"
           "  -flto                 Link-time optimization for multi-source "
           "obj\n"
           "  -target TRIPLE        Cross-compile target\n"
           "  --sysroot DIR         User-supplied hosted cross sysroot\n"
           "  -isysroot DIR         Hosted SDK/sysroot include root\n"
           "  --support-dir DIR     Kit distribution support root\n"
           "  -I/-isystem/-D/-U     Preprocessor flags (C/asm frontends)\n"
           "  -x LANG               Force a registered language\n"
           "  --group [flags] -- sources...   Scope compile flags to sources\n"
           "  -X<lang> FLAG         Per-language frontend flag\n"
           "  -o -                  Write the emit to stdout\n"
           "  -h, --help            Show this help\n"
           "  --version             Show Kit version\n"
           "\n"
           "OUTPUT AND RELEASE NOTES\n"
           "  One-source object/assembly output defaults to <base>.o/.s. -o is\n"
           "  required for multi-source object combination and --emit=c; use\n"
           "  -o for stable IR filenames. -fsyntax-only writes nothing. A\n"
           "  relocated distribution discovers sibling support automatically.\n"
           "  Native macOS discovers its SDK; hosted cross targets require an\n"
           "  explicit sysroot. Portable-C output uses the\n"
           "  -O0 semantic pipeline; -O1/-O2 are accepted and normalized to -O0.\n"
           "\n"
           "EXAMPLES\n"
           "  kit build-obj main.c\n"
           "  kit build-obj \\\n"
           "    main.c helper.c -o combined.o\n"
           "  kit build-obj \\\n"
           "    --emit=asm source.c -o source.s\n"
           "  kit build-obj \\\n"
           "    --emit=c -O0 source.c -o portable.c\n"
           "  kit build-obj \\\n"
           "    --emit=ir -O1 source.c -o source.ir\n"
           "  kit build-obj \\\n"
           "    -fsyntax-only -I include source.c\n"
           "\n"
           "EXIT CODES\n"
           "  0   success    1   frontend/link/I/O error    2   bad usage\n")));
 }
 
 int driver_build_exe_ex(int argc, char** argv, const KitDriverExtension* ext) {
   if (argc < 2 || driver_argv_wants_help(argc, argv, 1)) {
     driver_help_build_exe();
     return 0;
   }
   return build_main(argc, argv, BUILD_OUT_EXE, "build-exe", ext);
 }
 
 int driver_build_lib_ex(int argc, char** argv, const KitDriverExtension* ext) {
   if (argc < 2 || driver_argv_wants_help(argc, argv, 1)) {
     driver_help_build_lib();
     return 0;
   }
   return build_main(argc, argv, BUILD_OUT_LIB, "build-lib", ext);
 }
 
 int driver_build_obj_ex(int argc, char** argv, const KitDriverExtension* ext) {
   if (argc < 2 || driver_argv_wants_help(argc, argv, 1)) {
     driver_help_build_obj();
     return 0;
   }
   return build_main(argc, argv, BUILD_OUT_OBJ, "build-obj", ext);
 }
 
 int driver_build_exe(int argc, char** argv) {
   return driver_build_exe_ex(argc, argv, NULL);
 }
 
 int driver_build_lib(int argc, char** argv) {
   return driver_build_lib_ex(argc, argv, NULL);
 }
 
 int driver_build_obj(int argc, char** argv) {
   return driver_build_obj_ex(argc, argv, NULL);
 }