kit

run.c (40343B)

---

 #include <kit/compile.h>
 #include <kit/core.h>
 #include <kit/interp.h>
 #include <kit/jit.h>
 #include <kit/link.h>
 #include <stdint.h>
 #include <stdlib.h>
 #include <string.h>
 
 #include "backtrace.h"
 #include "cflags.h"
 #include "driver.h"
 #include "hosted.h"
 #include "inputs.h"
 #include "wasm_run.h"
 
 /* `kit run` — JIT-compile one or more inputs and invoke the entry symbol
  * (default `main`) in-process. Args after `--` are passed to the JITed
  * program as argv. Mirrors the cc front-end for input shape (.c / - sources,
  * .o objects, .a archives) and target/diagnostic flag surface; libkit's
  * JIT path forces PIC regardless of `-fPIC`/`-fPIE`/`-mcmodel`.
  *
  * Native host-symbol fallback (so JITed C/Toy/object code can call libc) goes
  * through driver_dlsym_resolver in driver/env.c. Wasm source inputs do not get
  * that fallback; host access is controlled by the Wasm import policy. The
  * driver returns whatever the entry returns, or 1 on a compile/link/lookup
  * error. The native entry is invoked as `int(*)(int, char**)`. */
 
 #define RUN_TOOL "run"
 
 typedef struct RunOptions {
   DriverEnv* env;
   size_t argv_bound;
 
   int opt_level;
   int no_jit; /* --no-jit: execute the entry via the IR interpreter */
   int debug_info;
   int metrics;
   int bench_time;
   int warnings_are_errors; /* -Werror     */
   uint32_t max_errors;     /* -fmax-errors=N */
   const char* entry;       /* -e, default "main" */
   const char* sysroot;     /* --sysroot   */
   int wants_hosted_libc;   /* -lc         */
   KitTargetSpec target;    /* -target / host */
   DriverTargetFeatures target_features;
   DriverHostedPlan hosted;
 
   DriverCflags cf;
   DriverInputs inputs;
   DriverWasmRunOptions wasm;
 
   char** prog_argv; /* args after `--`     */
   uint32_t prog_argc;
 } RunOptions;
 
 /* Buffered metrics sink. The hot path (scope_begin/end/count called from
  * libkit during compile/link/JIT) does no I/O: each event is appended to
  * a segmented event log, and scopes maintain only a small live stack to
  * carry the start_ns across to scope_end. All formatting and stderr writes
  * happen once in run_metrics_finish at the very end of the run.
  *
  * Storage is a singly-linked list of fixed-size segments. Each segment is
  * allocated once and never moves — geometric vector growth would amortize
  * to O(log N) copies, but with a chunk list we get zero copies and the
  * hot path is just an index increment + 24-byte store. We only ever drain
  * the log sequentially, so a segment table is unnecessary. */
 
 #define RUN_METRIC_MAX_DEPTH 64u
 #define RUN_METRIC_SEG_EVENTS 256u
 
 typedef enum RunMetricEventKind {
   RUN_METRIC_EVENT_SCOPE = 0,
   RUN_METRIC_EVENT_COUNT = 1,
 } RunMetricEventKind;
 
 typedef struct RunMetricEvent {
   const char* name; /* aliased; callers pass string literals */
   uint64_t value;   /* SCOPE: elapsed_ns; COUNT: count value */
   uint16_t depth;   /* nesting depth at emit time (0-based) */
   uint16_t kind;
 } RunMetricEvent;
 
 typedef struct RunMetricSeg {
   struct RunMetricSeg* next;
   uint32_t nused;
   RunMetricEvent events[RUN_METRIC_SEG_EVENTS];
 } RunMetricSeg;
 
 typedef struct RunMetricFrame {
   const char* name;
   uint64_t start_ns;
 } RunMetricFrame;
 
 typedef struct RunMetrics {
   KitMetrics iface;
   RunMetricFrame stack[RUN_METRIC_MAX_DEPTH];
   uint32_t depth;
   int bench_time;
 
   DriverEnv* env;
   RunMetricSeg* head;
   RunMetricSeg* tail;
   int oom; /* sticky: drop further events after an allocation failure */
 } RunMetrics;
 
 static void run_metrics_push_event(RunMetrics* m, RunMetricEventKind kind,
                                    const char* name, uint64_t value,
                                    uint32_t depth) {
   RunMetricSeg* seg;
   RunMetricEvent* ev;
   if (m->oom) return;
   seg = m->tail;
   if (!seg || seg->nused == RUN_METRIC_SEG_EVENTS) {
     RunMetricSeg* ns = driver_alloc_zeroed(m->env, sizeof(RunMetricSeg));
     if (!ns) {
       m->oom = 1;
       return;
     }
     if (m->tail)
       m->tail->next = ns;
     else
       m->head = ns;
     m->tail = ns;
     seg = ns;
   }
   ev = &seg->events[seg->nused++];
   ev->name = name;
   ev->value = value;
   ev->depth = (uint16_t)depth;
   ev->kind = (uint16_t)kind;
 }
 
 static void run_metrics_scope_begin(void* user, const char* name) {
   RunMetrics* m = (RunMetrics*)user;
   if (!m || m->depth >= RUN_METRIC_MAX_DEPTH) return;
   m->stack[m->depth].name = name;
   m->stack[m->depth].start_ns = driver_now_ns();
   m->depth++;
 }
 
 static void run_metrics_scope_end(void* user, const char* name) {
   RunMetrics* m = (RunMetrics*)user;
   RunMetricFrame f;
   uint64_t end_ns;
   uint64_t elapsed;
   uint32_t depth;
   const char* scope_name;
   if (!m || m->depth == 0) return;
   m->depth--;
   depth = m->depth;
   f = m->stack[depth];
   end_ns = driver_now_ns();
   elapsed = (end_ns >= f.start_ns) ? (end_ns - f.start_ns) : 0;
   scope_name = f.name ? f.name : name;
   run_metrics_push_event(m, RUN_METRIC_EVENT_SCOPE, scope_name, elapsed, depth);
 }
 
 static void run_metrics_count(void* user, const char* name, uint64_t value) {
   RunMetrics* m = (RunMetrics*)user;
   if (!m) return;
   run_metrics_push_event(m, RUN_METRIC_EVENT_COUNT, name, value, m->depth);
 }
 
 static void run_metrics_init(RunMetrics* m, DriverEnv* env, int bench_time) {
   m->iface.scope_begin = run_metrics_scope_begin;
   m->iface.scope_end = run_metrics_scope_end;
   m->iface.count = run_metrics_count;
   m->iface.user = m;
   m->depth = 0;
   m->bench_time = bench_time;
   m->env = env;
   m->head = NULL;
   m->tail = NULL;
   m->oom = 0;
 }
 
 static void run_metrics_begin(RunMetrics* m, const char* name) {
   if (m) m->iface.scope_begin(m->iface.user, name);
 }
 
 static void run_metrics_end(RunMetrics* m, const char* name) {
   if (m) m->iface.scope_end(m->iface.user, name);
 }
 
 /* Close any still-open scopes (early-return paths emit synthesized ends),
  * then walk the segmented event log in push order and format each event
  * to stderr. Free segments after draining. Called exactly once per run. */
 static void run_metrics_finish(RunMetrics* m) {
   RunMetricSeg* seg;
   if (!m) return;
   while (m->depth) {
     const char* name = m->stack[m->depth - 1u].name;
     run_metrics_scope_end(m, name);
   }
   for (seg = m->head; seg; seg = seg->next) {
     uint32_t i;
     for (i = 0; i < seg->nused; ++i) {
       const RunMetricEvent* e = &seg->events[i];
       if (e->kind == RUN_METRIC_EVENT_SCOPE) {
         if (m->bench_time) {
           driver_logf("kit-run %.*s -- %.3f msec",
                       KIT_SLICE_ARG(kit_slice_cstr(e->name)),
                       (double)e->value / 1000000.0);
         } else {
           driver_logf("%*s%.*s %.3f ms", (int)((unsigned)e->depth * 2u), "",
                       KIT_SLICE_ARG(kit_slice_cstr(e->name)),
                       (double)e->value / 1000000.0);
         }
       } else {
         driver_logf("%*s%.*s=%llu", (int)((unsigned)e->depth * 2u), "",
                     KIT_SLICE_ARG(kit_slice_cstr(e->name)),
                     (unsigned long long)e->value);
       }
     }
   }
   if (m->oom) {
     driver_logf("(metrics: event buffer allocation failed; some events lost)");
   }
   seg = m->head;
   while (seg) {
     RunMetricSeg* next = seg->next;
     driver_free(m->env, seg, sizeof(RunMetricSeg));
     seg = next;
   }
   m->head = NULL;
   m->tail = NULL;
 }
 
 static void run_bench_time(const char* name, uint64_t ns) {
   driver_logf("kit-run %.*s -- %.3f msec", KIT_SLICE_ARG(kit_slice_cstr(name)),
               (double)ns / 1000000.0);
 }
 
 static void run_usage(void) {
   driver_errf(RUN_TOOL, "%.*s",
               KIT_SLICE_ARG(KIT_SLICE_LIT(
                   "usage: kit run [options] inputs... [-- prog-arg...]\n"
                   "       kit run --help    for full option reference")));
 }
 
 void driver_help_run(void) {
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "kit run — JIT-compile inputs and invoke the entry symbol "
           "in-process\n"
           "\n"
           "USAGE\n"
           "  kit run [options] inputs... [-- prog-arg...]\n"
           "\n"
           "DESCRIPTION\n"
           "  Compiles and JIT-links every input, looks up the entry symbol\n"
           "  (default `main`), and calls it as `int(*)(int, char**)`. Args\n"
           "  after `--` are passed to the JITed program as argv. The driver\n"
           "  returns the entry's exit code, or 1 on a compile/link/lookup\n"
           "  error.\n"
           "\n"
           "  Inputs are classified by suffix:\n"
           "    .c .cc .cpp     C source\n"
           "    .wat .wasm      WebAssembly source module\n"
           "    .o .obj         object file\n"
           "    .a              static archive\n"
           "    -               read C source from stdin (single source only)\n"
           "\n"
           "  Native JITed code may call any host symbol resolvable via "
           "dlsym(RTLD_DEFAULT)\n"
           "  — typically libc. Wasm source inputs do not use this fallback.\n"
           "  The JIT path forces PIC; -fPIC / -fPIE / "
           "-mcmodel\n"
           "  are accepted but have no observable effect.\n"
           "\n"
           "COMPILE OPTIONS\n"
           "  -O0 -O1 -O2       Optimization level (default -O0)\n"
           "  --no-jit          Execute the entry through the IR interpreter\n"
           "                    instead of JIT-compiled native code (forces "
           "-O1\n"
           "                    minimum so the optimizer IR is available)\n"
           "  -g                Emit DWARF debug info\n"
           "  --time, --metrics Emit scoped compile/link/JIT timing to stderr\n"
           "  --bench-time      Emit parseable compile/JIT/execution timings\n"
           "  -e SYMBOL         Entry symbol (default `main`)\n"
           "  -target TRIPLE    Cross-compile target (see `kit cc --help`)\n"
           "  --sysroot DIR     Hosted libc sysroot for headers/defines with "
           "-lc\n"
           "  -lc               Enable hosted libc headers/defines; calls "
           "resolve "
           "via host dlsym\n"
           "  -fPIC -fpic       Position-independent code (no-op for the JIT)\n"
           "  -fPIE -fpie       Position-independent executable (no-op for the "
           "JIT)\n"
           "  -mcmodel=MODEL    small | medium | large (no-op for the JIT)\n"
           "  -Werror           Treat warnings as errors\n"
           "  -fmax-errors=N    Stop after N errors (0 = unlimited)\n"
           "\n"
           "PREPROCESSOR\n"
           "  -I DIR            Add quoted-include search path\n"
           "  -isystem DIR      Add system-include search path\n"
           "  -D NAME[=BODY]    Define a macro\n"
           "  -U NAME           Undefine a builtin/predefined macro\n"
           "\n")));
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "WASM SANDBOX\n"
           "  Wasm inputs run with a deny-by-default host-import policy. "
           "No host\n"
           "  symbol or test-import fallback is enabled unless an explicit "
           "flag\n"
           "  below requests it.\n"
           "  --wasm-memory-max=SIZE\n"
           "                    Maximum total linear-memory reservation "
           "(default 1G)\n"
           "  --wasm-instance-max=SIZE\n"
           "                    Maximum runtime instance size (default 64M)\n"
           "  --wasm-memories-max=N\n"
           "                    Maximum declared linear-memory count\n"
           "  --wasm-imports=deny|wasi|test\n"
           "                    Import resolver policy (default deny). `test` "
           "binds\n"
           "                    only the in-tree env.host_add test shim.\n"
           "                    `wasi` binds the configured WASI Preview1 "
           "shim.\n"
           "  --wasm-wasi       Alias for --wasm-imports=wasi\n"
           "  --wasm-env=none|allowlist|inherit\n"
           "  --wasm-env-pass=NAME, --wasm-env-set=NAME=VALUE\n"
           "                    Guest environment policy for WASI env imports\n"
           "  --wasm-fs=none    Filesystem disabled (default)\n"
           "  --wasm-map-dir=HOST=GUEST[:ro|rw]\n"
           "  --wasm-map-file=HOST=GUEST[:ro|rw]\n"
           "  --wasm-cwd=GUEST  Guest cwd exposed through the WASI config\n"
           "  --wasm-stdio=null|inherit\n"
           "  --wasm-clock=none|monotonic|realtime\n"
           "  --wasm-random=none|host|seed:HEX\n"
           "                    WASI host-resource policy; default is none\n"
           "\n")));
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "ARGV PASSTHROUGH\n"
           "  --                End of `kit run` options. Tokens after `--` "
           "are\n"
           "                    passed to the JITed program's main(argc, argv)\n"
           "                    starting at argv[1]. argv[0] is synthesized "
           "from\n"
           "                    the first input (path, `<stdin>`, .o, or .a) "
           "so\n"
           "                    JITed code can index argv[0] like a hosted\n"
           "                    program. Without `--` the program receives\n"
           "                    argc==1 with argv[0] set and argv[1]==NULL.\n"
           "  --script FILE     Run FILE as the sole source, passing every\n"
           "                    later token to the program as argv (an "
           "implicit\n"
           "                    `--` after FILE). Implies -lc (hosted libc),\n"
           "                    since scripts are usually hosted; on macOS "
           "that\n"
           "                    still needs --sysroot for header resolution.\n"
           "                    Intended for `#!` script use:\n"
           "                      #!/usr/bin/env -S kit run --script\n"
           "                    Make the .c file executable and run it "
           "directly;\n"
           "                    the kernel appends the path + the user's args.\n"
           "                    Add compile flags before --script, e.g.\n"
           "                      #!/usr/bin/env -S kit run -g --script\n"
           "\n"
           "GETTING HELP\n"
           "  -h, --help        Show this help and exit\n"
           "\n"
           "EXAMPLES\n"
           "  kit run hello.c\n"
           "  kit run -O2 -DNDEBUG main.c util.c\n"
           "  kit run main.c -- arg1 arg2\n"
           "  kit run --script script.c arg1 arg2   (as a #! interpreter)\n"
           "\n"
           "EXIT CODES\n"
           "  Returns the exit code of the JITed entry, or 1 on internal "
           "failure.\n"
           "  2 on bad command-line usage.\n")));
 }
 
 static int run_alloc_arrays(RunOptions* o, int argc) {
   size_t bound = (size_t)argc;
   o->argv_bound = bound;
   o->prog_argv = driver_alloc_zeroed(o->env, bound * sizeof(*o->prog_argv));
   if (!o->prog_argv) {
     driver_errf(RUN_TOOL, "out of memory");
     return 1;
   }
   if (driver_inputs_init(&o->inputs, o->env, RUN_TOOL, argc) != 0) return 1;
   if (driver_cflags_init(
           &o->cf, o->env,
           argc + DRIVER_HOSTED_MAX_INCLUDES + DRIVER_HOSTED_MAX_DEFINES) != 0) {
     driver_errf(RUN_TOOL, "out of memory");
     return 1;
   }
   if (driver_target_features_init(&o->target_features, o->env, argc) != 0) {
     driver_errf(RUN_TOOL, "out of memory");
     return 1;
   }
   if (driver_wasm_run_options_init(&o->wasm, o->env, bound) != 0) return 1;
   return 0;
 }
 
 /* Decimal uint64 parse for -fmax-errors=N. Mirrors cc's helper. */
 static int run_parse_u64(const char* s, uint64_t* out) {
   uint64_t v = 0;
   int any = 0;
   if (!s) return 1;
   while (*s) {
     unsigned d;
     if (*s < '0' || *s > '9') return 1;
     d = (unsigned)(*s - '0');
     if (v > (UINT64_MAX - d) / 10u) return 1;
     v = v * 10u + d;
     any = 1;
     s++;
   }
   if (!any) return 1;
   *out = v;
   return 0;
 }
 
 static int run_record_mcmodel(RunOptions* o, const char* val) {
   if (driver_streq(val, "small")) {
     o->target.code_model = KIT_CM_SMALL;
     return 0;
   }
   if (driver_streq(val, "medium")) {
     o->target.code_model = KIT_CM_MEDIUM;
     return 0;
   }
   if (driver_streq(val, "large")) {
     o->target.code_model = KIT_CM_LARGE;
     return 0;
   }
   if (driver_streq(val, "medlow")) {
     o->target.code_model = KIT_CM_SMALL;
     return 0;
   }
   if (driver_streq(val, "medany")) {
     o->target.code_model = KIT_CM_MEDIUM;
     return 0;
   }
   driver_errf(RUN_TOOL, "unknown -mcmodel value: %.*s",
               KIT_SLICE_ARG(kit_slice_cstr(val)));
   return 1;
 }
 
 static int run_classify_positional(RunOptions* o, const char* a) {
   int r = driver_inputs_classify(&o->inputs, a);
   if (r < 0) return 1;
   if (r == 0) {
     driver_errf(RUN_TOOL, "input does not have a recognized suffix: %.*s",
                 KIT_SLICE_ARG(kit_slice_cstr(a)));
     return 1;
   }
   return 0;
 }
 
 static int run_path_is_wasm_source(const char* path) {
   return driver_has_suffix(path, ".wat") || driver_has_suffix(path, ".wasm");
 }
 
 /* Scan raw wasm bytes for a custom section named `want`.
  * On success sets *len_out and returns a pointer into `p`; returns NULL on
  * miss or malformed input. The returned pointer is valid only while `p` is. */
 static const char* wasm_scan_custom(const uint8_t* p, size_t total,
                                     const char* want, uint32_t* len_out) {
   const uint8_t* end = p + total;
   uint8_t id;
   uint32_t size, shift;
   const uint8_t* sec_end;
   if (total < 8) return NULL;
   p += 8; /* skip magic + version */
   while (p < end) {
     uint8_t b;
     id = *p++;
     size = 0; shift = 0;
     for (;;) {
       if (p >= end) return NULL;
       b = *p++;
       size |= (uint32_t)(b & 0x7f) << shift;
       if (!(b & 0x80)) break;
       shift += 7;
       if (shift > 28) return NULL;
     }
     if ((uint32_t)(end - p) < size) return NULL;
     sec_end = p + size;
     if (id == 0) {
       uint32_t nlen = 0;
       shift = 0;
       for (;;) {
         if (p >= sec_end) { p = sec_end; goto next_section; }
         b = *p++;
         nlen |= (uint32_t)(b & 0x7f) << shift;
         if (!(b & 0x80)) break;
         shift += 7;
         if (shift > 28) { p = sec_end; goto next_section; }
       }
       if ((uint32_t)(sec_end - p) >= nlen) {
         size_t wlen = driver_strlen(want);
         if (nlen == (uint32_t)wlen && memcmp(p, want, wlen) == 0) {
           p += nlen;
           *len_out = (uint32_t)(sec_end - p);
           return (const char*)p;
         }
       }
     }
     next_section:
     p = sec_end;
   }
   return NULL;
 }
 
 static int run_inputs_have_wasm_source(const DriverInputs* in) {
   uint32_t i;
   for (i = 0; i < in->nsources; ++i)
     if (run_path_is_wasm_source(in->sources[i])) return 1;
   return 0;
 }
 
 static int run_inputs_have_non_wasm(const DriverInputs* in) {
   uint32_t i;
   if (in->nsource_memory || in->nobject_files || in->narchives) return 1;
   for (i = 0; i < in->nsources; ++i)
     if (!run_path_is_wasm_source(in->sources[i])) return 1;
   return 0;
 }
 
 static int run_apply_hosted_profile(RunOptions* o) {
   DriverHostedRequest req;
   uint32_t i;
   if (!o->wants_hosted_libc) return 0;
   {
     DriverHostedRequest z = {0};
     req = z;
   }
   req.env = o->env;
   req.tool = RUN_TOOL;
   req.target = o->target;
   req.sysroot = o->sysroot;
   req.static_link = 0;
   req.link_inputs = 0;
   if (driver_hosted_resolve(&req, &o->hosted) != 0) return 1;
   for (i = 0; i < o->hosted.nsystem_includes; ++i) {
     o->cf.system_include_dirs[o->cf.nsystem_include_dirs++] =
         o->hosted.system_includes[i];
   }
   for (i = 0; i < o->hosted.ndefines; ++i) {
     o->cf.defines[o->cf.ndefines++] = o->hosted.defines[i];
   }
   return 0;
 }
 
 static int run_parse(int argc, char** argv, RunOptions* o) {
   int i;
   int after_dash_dash = 0;
   if (run_alloc_arrays(o, argc) != 0) return 1;
   o->target = driver_host_target();
 
   /* Reserve argv[0] for a synthetic program name filled in below. User
    * args after `--` start at argv[1]. */
   o->prog_argc = 1;
 
   for (i = 1; i < argc; ++i) {
     const char* a = argv[i];
 
     if (after_dash_dash) {
       o->prog_argv[o->prog_argc++] = argv[i];
       continue;
     }
     if (driver_streq(a, "--")) {
       after_dash_dash = 1;
       continue;
     }
     /* `--script FILE`: shebang entry point. The kernel's `#!` mechanism
      * appends the script path and the user's arguments after our flags, with
      * no way to inject a `--` between them. `--script` names the sole source
      * file (the next argv element, supplied by the kernel) and routes every
      * later token — flag-shaped or not — to the program's argv, exactly like
      * an implicit `--` after the script. See driver_help_run / DRIVER.md. */
     if (driver_streq(a, "--script")) {
       if (++i >= argc) {
         driver_errf(RUN_TOOL, "--script requires a source-file argument");
         return 1;
       }
       /* Scripts are overwhelmingly hosted programs, so default `--script` to
        * hosted libc — under the JIT that only enables libc headers/macros
        * (symbols resolve at run time via host dlsym), so the only added cost
        * is needing a sysroot for #include resolution. An earlier explicit
        * -lc is a harmless no-op; this just spares every shebang line from
        * repeating it. */
       o->wants_hosted_libc = 1;
       if (run_classify_positional(o, argv[i]) != 0) return 1;
       after_dash_dash = 1;
       continue;
     }
 
     {
       int wr = driver_wasm_run_try_consume(&o->wasm, RUN_TOOL, argc, argv, &i);
       if (wr < 0) return 1;
       if (wr > 0) continue;
     }
 
     {
       int r =
           driver_cflags_try_consume(&o->cf, o->env, RUN_TOOL, argc, argv, &i);
       if (r < 0) return 1;
       if (r > 0) continue;
     }
 
     if (driver_streq(a, "-g")) {
       o->debug_info = 1;
       continue;
     }
     if (driver_streq(a, "--bench-time")) {
       o->bench_time = 1;
       continue;
     }
     if (driver_streq(a, "--time") || driver_streq(a, "--metrics")) {
       o->metrics = 1;
       continue;
     }
     if (driver_streq(a, "--no-jit")) {
       o->no_jit = 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")) {
       o->opt_level = 2;
       continue;
     }
 
     if (driver_streq(a, "-Werror")) {
       o->warnings_are_errors = 1;
       continue;
     }
     if (driver_strneq(a, "-fmax-errors=", 13)) {
       uint64_t v;
       if (run_parse_u64(a + 13, &v) != 0 || v > 0xFFFFFFFFu) {
         driver_errf(RUN_TOOL, "-fmax-errors= requires a non-negative integer");
         return 1;
       }
       o->max_errors = (uint32_t)v;
       continue;
     }
 
     if (driver_streq(a, "-fPIC")) {
       o->target.pic = KIT_PIC_PIC;
       continue;
     }
     if (driver_streq(a, "-fpic")) {
       o->target.pic = KIT_PIC_PIC;
       continue;
     }
     if (driver_streq(a, "-fPIE")) {
       o->target.pic = KIT_PIC_PIE;
       continue;
     }
     if (driver_streq(a, "-fpie")) {
       o->target.pic = KIT_PIC_PIE;
       continue;
     }
 
     if (driver_strneq(a, "-mcmodel=", 9)) {
       if (run_record_mcmodel(o, a + 9) != 0) return 1;
       continue;
     }
     {
       int tr = driver_target_features_try_consume(&o->target_features, o->env,
                                                   RUN_TOOL, argc, argv, &i);
       if (tr < 0) return 1;
       if (tr > 0) continue;
     }
 
     if (driver_streq(a, "-target")) {
       if (++i >= argc) {
         driver_errf(RUN_TOOL, "-target requires an argument");
         return 1;
       }
       if (driver_target_from_triple(argv[i], &o->target) != 0) {
         driver_errf(RUN_TOOL, "unrecognized target triple: %.*s",
                     KIT_SLICE_ARG(kit_slice_cstr(argv[i])));
         return 1;
       }
       continue;
     }
     if (driver_streq(a, "--sysroot") || driver_streq(a, "-isysroot")) {
       if (++i >= argc) {
         driver_errf(RUN_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, "-lc")) {
       o->wants_hosted_libc = 1;
       continue;
     }
     if (driver_streq(a, "-l")) {
       if (++i >= argc) {
         driver_errf(RUN_TOOL, "-l requires an argument");
         return 1;
       }
       if (!driver_streq(argv[i], "c")) {
         driver_errf(RUN_TOOL, "unsupported hosted library for JIT: -l%.*s",
                     KIT_SLICE_ARG(kit_slice_cstr(argv[i])));
         return 1;
       }
       o->wants_hosted_libc = 1;
       continue;
     }
     if (driver_strneq(a, "-l", 2)) {
       if (!driver_streq(a + 2, "c")) {
         driver_errf(RUN_TOOL, "unsupported hosted library for JIT: %.*s",
                     KIT_SLICE_ARG(kit_slice_cstr(a)));
         return 1;
       }
       o->wants_hosted_libc = 1;
       continue;
     }
 
     if (driver_streq(a, "-e")) {
       if (++i >= argc) {
         driver_errf(RUN_TOOL, "-e requires an argument");
         return 1;
       }
       o->entry = argv[i];
       continue;
     }
 
     if (driver_streq(a, "-")) {
       if (run_classify_positional(o, a) != 0) return 1;
       continue;
     }
     if (a[0] == '-' && a[1] != '\0') {
       driver_errf(RUN_TOOL, "unknown flag: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(a)));
       return 1;
     }
 
     if (run_classify_positional(o, a) != 0) return 1;
   }
 
   if (driver_inputs_count(&o->inputs) == 0) {
     driver_errf(RUN_TOOL, "no input files");
     run_usage();
     return 1;
   }
   if (run_inputs_have_wasm_source(&o->inputs) &&
       run_inputs_have_non_wasm(&o->inputs)) {
     driver_errf(RUN_TOOL,
                 "sandboxed wasm run does not support mixed native inputs");
     return 1;
   }
   if (!o->entry && run_inputs_have_wasm_source(&o->inputs) &&
       !run_inputs_have_non_wasm(&o->inputs) &&
       o->inputs.nsources == 1) {
     DriverLoad lf = {0};
     KitSlice bytes = {0};
     if (driver_load_bytes(&o->env->file_io, RUN_TOOL,
                           o->inputs.sources[0], &lf, &bytes) == 0) {
       uint32_t elen = 0;
       const char* ep = wasm_scan_custom((const uint8_t*)bytes.s,
                                         (size_t)bytes.len,
                                         "kit-entry", &elen);
       if (ep && elen > 0 && elen < 256) {
         char* buf = (char*)o->env->heap->alloc(o->env->heap, elen + 1u, 1);
         if (buf) {
           memcpy(buf, ep, elen);
           buf[elen] = '\0';
           o->entry = buf;
         }
       }
       driver_release_bytes(&o->env->file_io, &lf);
     }
   }
   if (!o->entry) o->entry = "main";
   if (run_apply_hosted_profile(o) != 0) return 1;
 
   /* Synthetic argv[0]. Hosted programs conventionally read argv[0] as
    * the program name; under `kit run` there is no executable path, so
    * use the first input's display name. */
   o->prog_argv[0] = (char*)driver_inputs_first_name(&o->inputs);
   o->wasm.args = (const char* const*)o->prog_argv;
   o->wasm.nargs = o->prog_argc;
   return 0;
 }
 
 static void run_options_release(RunOptions* o) {
   size_t bound = o->argv_bound;
   driver_hosted_plan_fini(o->env, &o->hosted);
   driver_wasm_run_options_fini(&o->wasm);
   driver_inputs_release(&o->inputs);
   driver_target_features_fini(&o->target_features, o->env);
   driver_cflags_fini(&o->cf, o->env);
   driver_free(o->env, o->prog_argv, bound * sizeof(*o->prog_argv));
 }
 
 static void run_fill_compile_opts(const RunOptions* o,
                                   KitCCompileOptions* copts) {
   KitCCompileOptions z = {0};
   *copts = z;
   /* The interpreter consumes the O1 PReg-path IR; force at least -O1 so the
    * optimizer runs and each function is captured into the InterpProgram. */
   copts->code.opt_level = (o->no_jit && o->opt_level < 1) ? 1 : o->opt_level;
   copts->code.debug_info = o->debug_info;
   copts->diagnostics.warnings_are_errors = o->warnings_are_errors;
   copts->diagnostics.max_errors = o->max_errors;
 }
 
 /* Compile every C source through the caller-owned compiler, load .o/.a
  * inputs, and JIT-link. On success *out_jit owns the JIT image; caller
  * releases via kit_jit_free. The compiler must outlive the JIT — it
  * backs jit->c, which kit_jit_lookup dereferences. */
 static int run_compile_and_jit(RunOptions* o, KitCompiler* compiler,
                                const KitJitHost* host, KitJit** out_jit) {
   KitCCompileOptions copts;
   KitPreprocessOptions pp;
   void* (*extern_resolver)(void*, KitSlice) = driver_dlsym_resolver;
   run_fill_compile_opts(o, &copts);
   driver_cflags_fill_pp(&o->cf, &pp);
   if (run_inputs_have_wasm_source(&o->inputs) ||
       driver_wasm_run_options_used(&o->wasm))
     extern_resolver = NULL;
   return driver_inputs_compile_and_jit(&o->inputs, compiler, host, &copts, &pp,
                                        o->entry, extern_resolver, NULL,
                                        out_jit);
 }
 
 typedef int (*MainFn)(int, char**);
 
 /* --- crash backtrace ------------------------------------------------------
  * When the JITed program faults, driver_run_with_crash_guard captures the
  * return-address chain (innermost first) inside its fault handler and hands it
  * here; we open the image's DWARF (best effort) and symbolize each frame to
  * stderr. */
 
 typedef struct RunCrashCtx {
   DriverEnv* env;
   KitJit* jit;
   int signo; /* filled in run_on_crash so the caller can derive the exit code */
 } RunCrashCtx;
 
 static void run_bt_emit(void* user, const char* line) {
   (void)user;
   driver_logf("%s", line); /* driver_logf appends the newline */
 }
 
 static void run_on_crash(void* user, int signo, const uint64_t* pcs, int npcs) {
   RunCrashCtx* c = (RunCrashCtx*)user;
   KitContext ctx = driver_env_to_context(c->env);
   KitDebugInfo* dwarf = NULL;
   DriverBtCtx btc;
 
   c->signo = signo;
   driver_logf("kit: program received signal %d; backtrace:", signo);
 
   /* DWARF is best effort: without it we still print addresses + JIT symbols. */
   if (c->jit) {
     const KitObjFile* view = kit_jit_view(c->jit);
     if (view) (void)kit_dwarf_open(&ctx, view, &dwarf);
   }
 
   memset(&btc, 0, sizeof btc);
   btc.jit = c->jit;
   btc.dwarf = dwarf;
   btc.emit = run_bt_emit;
   btc.emit_user = NULL;
   driver_backtrace_print_pcs(&btc, pcs, npcs);
 
   if (dwarf) kit_dwarf_free(dwarf);
 }
 
 /* Host-identity symbol resolver for the interpreter.
  *
  * The interpreter holds symbol names as they appear in the object/image symbol
  * table (already target-mangled, e.g. a leading `_` on Mach-O). kit_jit_lookup
  * only finds GLOBAL-bind symbols, but the toy/C frontends emit module-private
  * data and helper functions with LOCAL bind. So resolve by iterating the JIT
  * image's full symbol table (locals included) for an exact name match — this
  * also avoids the re-mangling kit_jit_lookup would apply. Extern/libc symbols
  * not defined in the image fall back to host dlsym (which wants the unmangled
  * name, so try with a leading `_` stripped too). */
 static void* interp_jit_resolve(void* ctx, KitSlice name) {
   KitJit* jit = (KitJit*)ctx;
   void* p = NULL;
   /* The interpreter holds object-table names (target-mangled, e.g. a leading
    * `_` on Mach-O); the JIT image exposes the canonical unmangled names. Match
    * tolerating a single leading-underscore on either side. */
   KitSlice alt = name;
   if (name.len > 1 && name.s[0] == '_') {
     alt.s = name.s + 1;
     alt.len = name.len - 1;
   }
   /* Two passes so an EXACT name match always wins over the underscore-stripped
    * fallback (avoids a local `_g` masking a global `g`, or vice-versa). */
   int pass;
   for (pass = 0; pass < 2 && !p; ++pass) {
     KitSlice want = (pass == 0) ? name : alt;
     KitJitSymIter* it = NULL;
     if (pass == 1 && alt.s == name.s) break; /* no distinct stripped form */
     if (!jit || kit_jit_sym_iter_new(jit, &it) != KIT_OK) break;
     {
       KitJitSym s;
       while (kit_jit_sym_iter_next(it, &s) == KIT_ITER_ITEM) {
         size_t k;
         if (s.name.len != want.len) continue;
         for (k = 0; k < want.len && s.name.s[k] == want.s[k]; ++k) {
         }
         if (k == want.len) {
           p = (void*)(uintptr_t)s.addr;
           break;
         }
       }
       kit_jit_sym_iter_free(it);
     }
   }
   if (!p) {
     p = driver_dlsym_resolver(NULL, name);
     if (!p && name.s[0] == '_') p = driver_dlsym_resolver(NULL, alt);
   }
   return p;
 }
 
 /* Thread-local resolver for the interpreter. A thread-local symbol resolves to
  * a Mach-O TLV descriptor (whose +16 slot holds the storage) or, on ELF/COFF,
  * directly to the in-image storage; kit_jit_tls_addr normalizes both to the
  * variable's single in-image instance and returns NULL for anything it can't
  * safely resolve (a foreign/extern thread-local resolved through the host). We
  * return NULL in those cases so the engine diagnoses cleanly rather than
  * treating a foreign pointer as the variable's storage. */
 static void* interp_jit_resolve_tls(void* ctx, KitSlice name, int64_t addend) {
   KitJit* jit = (KitJit*)ctx;
   void* sym = interp_jit_resolve(ctx, name);
   void* tls;
   if (!sym) return NULL;
   tls = kit_jit_tls_addr(jit, sym);
   return tls ? (uint8_t*)tls + addend : NULL;
 }
 
 int driver_run(int argc, char** argv) {
   DriverEnv env;
   RunOptions ro = {0};
   KitContext ctx;
   KitJitHost jhost;
   KitTarget* target = NULL;
   KitCompiler* compiler = NULL;
   KitJit* jit = NULL;
   KitInterpProgram* interp = NULL;
   RunMetrics metrics_storage;
   RunMetrics* metrics = NULL;
   void* sym;
   MainFn entry_fn;
   int rc;
   uint64_t bench_total_start = 0;
   uint64_t bench_compile_start = 0;
   uint64_t bench_compile_end = 0;
   uint64_t bench_exec_start = 0;
   uint64_t bench_exec_end = 0;
 
   if (argc < 2 || driver_argv_wants_help(argc, argv, 1)) {
     driver_help_run();
     return 0;
   }
 
   driver_env_init(&env);
   ro.env = &env;
 
   if (run_parse(argc, argv, &ro) != 0) {
     run_options_release(&ro);
     driver_env_fini(&env);
     return 2;
   }
 
   if (ro.metrics || ro.bench_time) {
     run_metrics_init(&metrics_storage, &env, ro.bench_time);
     metrics = &metrics_storage;
     env.metrics = &metrics->iface;
     if (ro.metrics && !ro.bench_time) driver_logf("kit metrics:");
     run_metrics_begin(metrics, "run.total");
   }
   if (ro.bench_time) bench_total_start = driver_now_ns();
 
   /* Compiler backs the JIT image — keep it alive across kit_jit_lookup
    * and the entry call, free after kit_jit_free. */
   ctx = driver_env_to_context(&env);
   jhost = driver_env_to_jit_host(&env);
   if (driver_target_new(&ctx, ro.target, &ro.target_features, RUN_TOOL,
                         &target) != KIT_OK ||
       driver_compiler_new(target, &ctx, &compiler) != KIT_OK) {
     driver_errf(RUN_TOOL, "failed to initialize compiler");
     kit_target_free(target);
     run_metrics_finish(metrics);
     run_options_release(&ro);
     driver_env_fini(&env);
     return 1;
   }
 
   /* For --no-jit, attach an InterpProgram so the optimizer captures each
    * function's IR as it compiles. The native object/JIT image is still built
    * (it lays out data globals and resolves externs/function pointers); only
    * the entry's *execution* is routed through the interpreter. */
   if (ro.no_jit) {
     interp = kit_interp_program_new(compiler);
     if (!interp) {
       driver_errf(RUN_TOOL, "failed to initialize interpreter");
       driver_compiler_free(compiler);
       kit_target_free(target);
       run_metrics_finish(metrics);
       run_options_release(&ro);
       driver_env_fini(&env);
       return 1;
     }
     kit_interp_program_attach(interp, compiler);
   }
 
   if (ro.bench_time) bench_compile_start = driver_now_ns();
   run_metrics_begin(metrics, "run.compile_and_jit");
   rc = run_compile_and_jit(&ro, compiler, &jhost, &jit);
   run_metrics_end(metrics, "run.compile_and_jit");
   if (ro.bench_time) bench_compile_end = driver_now_ns();
   if (rc != 0) {
     if (ro.bench_time)
       run_bench_time("compile_and_jit",
                      bench_compile_end - bench_compile_start);
     kit_interp_program_free(interp);
     driver_compiler_free(compiler);
     kit_target_free(target);
     run_metrics_finish(metrics);
     run_options_release(&ro);
     driver_env_fini(&env);
     return rc;
   }
 
   run_metrics_begin(metrics, "run.jit_lookup");
   sym = kit_jit_lookup(jit, kit_slice_cstr(ro.entry));
   run_metrics_end(metrics, "run.jit_lookup");
   if (!sym) {
     driver_errf(RUN_TOOL, "entry symbol not found: %.*s",
                 KIT_SLICE_ARG(kit_slice_cstr(ro.entry)));
     kit_interp_program_free(interp);
     kit_jit_free(jit);
     driver_compiler_free(compiler);
     kit_target_free(target);
     run_metrics_finish(metrics);
     run_options_release(&ro);
     driver_env_fini(&env);
     return 1;
   }
 
   {
     union {
       void* p;
       MainFn fn;
     } u;
     u.p = sym;
     entry_fn = u.fn;
   }
 
   /* --no-jit: execute the entry through the IR interpreter. There is NO JIT
    * fallback — if the entry was not captured as interpretable IR (e.g. it came
    * from a precompiled .o, or uses an unsupported construct), that is an error.
    * The native object/JIT image is still built, but only to lay out data
    * globals and resolve externs/function pointers for the interpreter; the
    * entry's code is never run as native. */
   if (ro.no_jit) {
     KitInterpHost host;
     KitInterpFunc* ifn;
     int64_t ret = 0;
     KitInterpStatus s;
     host.translate = NULL; /* host-identity: abstract addrs are host pointers */
     host.resolve_sym = interp_jit_resolve;
     host.resolve_tls = interp_jit_resolve_tls;
     host.ctx = jit;
     kit_interp_program_set_host(interp, &host);
     /* Wasm modules need their instance/linear-memory set up and a 2-call
      * (init, entry) sequence with the instance pointer as the argument. */
     if (driver_wasm_run_call_entry_interp(&ro.wasm, RUN_TOOL, compiler, jit,
                                           interp, ro.entry, &rc))
       goto after_entry;
     if (driver_wasm_run_options_used(&ro.wasm)) {
       driver_errf(RUN_TOOL, "wasm sandbox flags require a wasm input");
       rc = 1;
       goto after_entry;
     }
     ifn = kit_interp_lookup(interp, kit_slice_cstr(ro.entry));
     if (!ifn) {
       driver_errf(RUN_TOOL,
                   "interp: entry %.*s has no interpretable IR (--no-jit "
                   "requires an IR-compiled entry; .o/.a inputs are not "
                   "supported)",
                   KIT_SLICE_ARG(kit_slice_cstr(ro.entry)));
       rc = 1;
       goto after_entry;
     }
     run_metrics_begin(metrics, "run.entry_call");
     if (ro.bench_time) bench_exec_start = driver_now_ns();
     s = kit_interp_call(interp, ifn, (int)ro.prog_argc, ro.prog_argv, &ret);
     if (ro.bench_time) bench_exec_end = driver_now_ns();
     run_metrics_end(metrics, "run.entry_call");
     if (s == KIT_INTERP_DONE) {
       rc = (int)ret;
     } else {
       /* The engine already emitted an "interp: ... not supported" / trap
        * diagnostic; surface a nonzero status (no native fallback). */
       driver_errf(RUN_TOOL, "interp: could not execute %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(ro.entry)));
       rc = 1;
     }
     goto after_entry;
   }
 
   run_metrics_begin(metrics, "run.entry_call");
   if (ro.bench_time) bench_exec_start = driver_now_ns();
   if (!driver_wasm_run_call_entry(&ro.wasm, RUN_TOOL, compiler, jit, sym,
                                   &rc)) {
     if (driver_wasm_run_options_used(&ro.wasm)) {
       driver_errf(RUN_TOOL, "wasm sandbox flags require a wasm input");
       rc = 1;
     } else {
       RunCrashCtx cc;
       cc.env = &env;
       cc.jit = jit;
       cc.signo = 0;
       if (driver_run_with_crash_guard(&env, ro.target.arch, entry_fn,
                                       (int)ro.prog_argc, ro.prog_argv, &rc,
                                       run_on_crash, &cc))
         rc = 128 + cc.signo; /* program faulted; shell convention */
     }
   }
   if (ro.bench_time) bench_exec_end = driver_now_ns();
   run_metrics_end(metrics, "run.entry_call");
 after_entry:
   if (ro.bench_time) {
     run_bench_time("compile_and_jit", bench_compile_end - bench_compile_start);
     run_bench_time("execution", bench_exec_end - bench_exec_start);
     run_bench_time("total", bench_exec_end - bench_total_start);
   }
 
   kit_interp_program_free(interp);
   kit_jit_free(jit);
   driver_compiler_free(compiler);
   kit_target_free(target);
   run_metrics_finish(metrics);
   run_options_release(&ro);
   driver_env_fini(&env);
   return rc;
 }