kit

ld.c (64367B)

---

 #include <kit/core.h>
 #include <kit/link.h>
 #include <kit/object.h>
 #include <stdint.h>
 #include <string.h>
 
 #include "driver.h"
 #include "hosted.h"
 #include "lib_resolve.h"
 #include "runtime.h"
 
 /* `kit ld` — link object/archive inputs into an executable, shared
  * library, or relocatable object. The driver loads each input via
  * env.file_io, optionally parses a `-T` linker script into the structured
  * form, and calls the public link APIs directly so the full link surface
  * (per-archive flags, group cycling, build-id, soname/rpath/exports) is
  * reachable without thickening the convenience KitOptions struct.
  *
  * Supported flags:
  *   -o out                            output path (required, exactly one)
  *   -e symbol                         entry symbol
  *   -T script.ld                      linker script (parsed, not raw)
  *   --support-dir DIR                 kit support root for compiler rt
  *   --sysroot DIR                     hosted C runtime/sysroot root
  *   -L dir                            library search path (-l targets)
  *   -l c                              enable hosted CRT/libc expansion
  *   -l name                           resolves via -L (.so preferred unless
  *                                     -Bstatic/-static)
  *   -static / -pie / -no-pie          target.pic
  *   -shared                           emit a shared library / dylib
  *   -r / --relocatable                emit a relocatable partial-link object
  *   -soname NAME                      DT_SONAME / LC_ID_DYLIB
  *   -rpath DIR                        DT_RPATH/DT_RUNPATH entry (repeatable)
  *   -rpath-link DIR                   shared-lib search at link time
  * (repeatable; accepted, currently advisory)
  *   --enable-new-dtags                rpath entries emit as DT_RUNPATH
  * (default)
  *   --disable-new-dtags               rpath entries emit as DT_RPATH
  *   -E / --export-dynamic             promote all defined globals to the
  * dynamic symbol table
  *   --whole-archive / --no-whole-archive
  *                                     positional state for following .a
  *   --gc-sections / --no-gc-sections  drop unreferenced sections
  *   -Bstatic / -Bdynamic              positional link-mode for following .a
  *   --as-needed / --no-as-needed      positional link-mode for following .a
  *   --start-group / --end-group       cyclic-resolution group of archives
  *   --build-id={none|sha256|uuid|0xHEX}
  */
 
 #define LD_TOOL "ld"
 
 /* Per-archive metadata mirroring the relevant subset of
  * KitLinkArchiveInput plus driver-side ownership info. */
 typedef struct LdArchive {
   const char* path;      /* path used for both open and KitSliceInput.name */
   int owned;             /* 1 if `path` was alloc'd by lib_resolve         */
   size_t owned_size;     /* allocation size (for driver_free)              */
   uint8_t whole_archive; /* nonzero == --whole-archive                     */
   uint8_t link_mode;     /* KitLinkMode (-Bstatic/-Bdynamic/--as-needed) */
   uint8_t group_id;      /* cyclic resolution group id; 0 = single-pass    */
 } LdArchive;
 
 /* Per-DSO ownership info. The DSO bytes are loaded straight off disk
  * via env->file_io into the KitSlice passed to libkit; only
  * the path itself may need to be free'd if it came from -l<name>
  * resolution. */
 typedef struct LdDso {
   const char* path;  /* path used for both open and KitSliceInput.name */
   int owned;         /* 1 if `path` was alloc'd by lib_resolve            */
   size_t owned_size; /* allocation size (for driver_free)                 */
 } LdDso;
 
 typedef struct LdOptions {
   DriverEnv* env;
   const char* driver_path;
   size_t argv_bound;
 
   KitTargetSpec target;
 
   const char* output_path; /* -o */
   int output_seen;
   const char* entry;       /* -e */
   const char* script_path; /* -T */
   int text_base_set;       /* -Ttext seen */
   uint64_t text_base;      /* -Ttext ADDR: static ET_EXEC image base */
   int no_default_libs;     /* -nostdlib / --no-default-libs */
   int pic_explicit;        /* -static / -pie / -no-pie / -shared seen */
   const char* support_dir; /* --support-dir */
   const char* sysroot;     /* --sysroot / KIT_SYSROOT */
   uint16_t pe_subsystem;   /* KitPeSubsystem */
   /* PT_INTERP path. NULL means "let libkit pick the target default
    * (e.g. /lib/ld-musl-aarch64.so.1)". Set by -dynamic-linker /
    * --dynamic-linker. */
   const char* interp_path;
   int pie; /* -pie was requested */
 
   const char** object_files;
   uint32_t nobject_files;
 
   LdArchive* archives;
   uint32_t narchives;
 
   /* Shared-object inputs (positional .so / .so.N or `-l<name>` under
    * -Bdynamic). The runtime loader resolves these by SONAME at link
    * time → DT_NEEDED entries. */
   LdDso* dsos;
   uint32_t ndsos;
   KitLinkInputOrder* order;
   uint32_t norder;
 
   const char** lib_dirs; /* -L */
   uint32_t nlib_dirs;
   char** owned_paths; /* sysroot-expanded argv/search paths */
   size_t* owned_path_sizes;
   uint32_t nowned_paths;
 
   /* Shared-library output state. */
   int shared;          /* -shared */
   int relocatable;     /* -r / --relocatable */
   const char* soname;  /* -soname NAME */
   const char** rpaths; /* -rpath DIR (repeatable) */
   uint32_t nrpaths;
   const char** rpath_links; /* -rpath-link DIR (advisory) */
   uint32_t nrpath_links;
   int new_dtags;       /* 1=DT_RUNPATH (default), 0=DT_RPATH */
   int export_dynamic;  /* -E / --export-dynamic */
   int gc_sections;     /* --gc-sections / --no-gc-sections */
   int strip_debug;     /* -S / --strip-debug */
   int allow_undefined; /* shared output undefined-symbol policy */
   int static_link;     /* -static: hosted libc should pick static profile */
   int wants_hosted_libc; /* -lc: expand crt + libc through hosted resolver */
   DriverHostedPlan hosted;
 
   /* --build-id state */
   uint8_t build_id_mode;   /* KitBuildIdMode */
   uint8_t* build_id_bytes; /* USER mode: parsed hex, owned */
   uint32_t build_id_len;
   size_t build_id_alloc; /* allocation size for free */
 
   /* Mutable parse state for positional archive flags / groups. */
   uint8_t cur_whole_archive; /* pending --whole-archive flag  */
   uint8_t cur_link_mode;     /* KitLinkMode for following inputs */
   uint8_t cur_group_id;      /* 0 outside any --start-group   */
   uint8_t next_group_id;     /* increments on --start-group   */
 
   /* Opt-in: treat `/...` arguments as MSVC link.exe flags. Off by
    * default so legacy paths like `/usr/lib/foo.o` remain inputs. */
   int ms_link_driver;
 } LdOptions;
 
 static void ld_usage(void) {
   driver_errf(LD_TOOL, "%.*s",
               KIT_SLICE_ARG(KIT_SLICE_LIT(
                   "usage: kit ld -o out [options...] inputs.o|inputs.a...\n"
                   "       kit ld --help    for full option reference")));
 }
 
 void driver_help_ld(void) {
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "kit ld — link objects/archives into an executable or shared "
           "library\n"
           "\n"
           "USAGE\n"
           "  kit ld -o OUT [options] inputs.o ... inputs.a ...\n"
           "  kit ld -shared -o libfoo.so [options] inputs.o ...\n"
           "  kit ld -r -o partial.o inputs.o ...\n"
           "\n"
           "DESCRIPTION\n"
           "  Loads each input via host file I/O, optionally parses a -T "
           "linker\n"
           "  script, and emits an executable (default) or shared library\n"
           "  (-shared). The full link surface is exposed: per-archive flags,\n"
           "  cyclic-resolution groups, build-id, soname/rpath/exports.\n"
           "\n"
           "OUTPUT\n"
           "  -o PATH                   Output path (required, exactly one)\n"
           "  -shared                   Emit a position-independent shared "
           "library "
           "/\n"
           "                            dylib instead of an executable\n"
           "  -r, --relocatable         Emit a relocatable partial-link object\n"
           "\n"
           "ENTRY / SCRIPT\n"
           "  -e SYMBOL                 Entry symbol\n"
           "  --subsystem NAME          PE subsystem: console or windows\n"
           "  -T SCRIPT.ld              Use a linker script (parsed, not raw)\n"
           "\n"
           "TARGET\n"
           "  -static                   Non-PIC, non-PIE\n"
           "  -pie                      Position-independent executable\n"
           "  -no-pie                   Disable PIE\n"
           "  --support-dir DIR         kit support root for compiler "
           "runtime\n"
           "  --sysroot DIR             hosted C runtime/sysroot root\n"
           "  (target is otherwise auto-detected from the first object input)\n"
           "\n"
           "LIBRARY RESOLUTION\n"
           "  -L DIR                    Add library search path\n"
           "  -l c                      Add hosted CRT objects and libc\n"
           "  -l NAME                   Resolve via -L (.so preferred unless "
           "static)\n"
           "\n"
           "POSITIONAL ARCHIVE STATE (apply to following .a inputs)\n"
           "  --whole-archive           Pull every member of following "
           "archives\n"
           "  --no-whole-archive        Reset (default behaviour)\n"
           "  -Bstatic                  Force static link mode\n"
           "  -Bdynamic                 Force dynamic link mode\n"
           "  --as-needed               Link only if a real reference exists\n"
           "  --no-as-needed            Reset to dynamic\n"
           "  --start-group ...\n"
           "    --end-group             Cyclic-resolution archive group\n"
           "\n"
           "SHARED-LIBRARY OPTIONS (require -shared)\n"
           "  -soname NAME              DT_SONAME / LC_ID_DYLIB\n"
           "  -soname=NAME              equivalent attached form\n"
           "  -rpath DIR                DT_RPATH/DT_RUNPATH entry (repeatable)\n"
           "  -rpath=DIR                attached form\n"
           "  -rpath-link DIR           Link-time-only search path (advisory)\n"
           "  --enable-new-dtags        rpaths land in DT_RUNPATH (default)\n"
           "  --disable-new-dtags       rpaths land in DT_RPATH\n"
           "\n"
           "SECTION GC\n"
           "  --gc-sections             Drop sections unreferenced from the "
           "entry\n"
           "                            symbol, init/fini arrays, "
           "SHF_GNU_RETAIN,\n"
           "                            and __start_/__stop_ section "
           "references\n"
           "  --no-gc-sections          Disable section GC (default)\n"
           "  -E, --export-dynamic      Promote defined globals into dynsym\n"
           "                            (no-op for -shared; recorded for exe)\n"
           "  -S, --strip-debug         Omit debug info from linked output\n"
           "  --no-undefined            Reject unresolved symbols in -shared "
           "output\n"
           "  -z defs                   Same as --no-undefined\n"
           "\n"
           "BUILD ID\n"
           "  --build-id                Same as --build-id=sha256\n"
           "  --build-id=MODE           none | sha256 | uuid | 0xHEX\n"
           "\n"
           "GETTING HELP\n"
           "  -h, --help                Show this help and exit\n"
           "\n"
           "EXIT CODES\n"
           "  0   success           1   link error           2   bad usage\n")));
 }
 
 /* ---------- argv-sized scratch arrays ---------- */
 
 static int ld_alloc_arrays(LdOptions* o, int argc) {
   size_t bound = (size_t)argc + 32u;
   o->argv_bound = bound;
   o->object_files =
       driver_alloc_zeroed(o->env, bound * sizeof(*o->object_files));
   o->archives = driver_alloc_zeroed(o->env, bound * sizeof(*o->archives));
   o->dsos = driver_alloc_zeroed(o->env, bound * sizeof(*o->dsos));
   o->order = driver_alloc_zeroed(o->env, bound * sizeof(*o->order));
   o->lib_dirs = driver_alloc_zeroed(o->env, bound * sizeof(*o->lib_dirs));
   o->owned_paths = driver_alloc_zeroed(o->env, bound * sizeof(*o->owned_paths));
   o->owned_path_sizes =
       driver_alloc_zeroed(o->env, bound * sizeof(*o->owned_path_sizes));
   o->rpaths = driver_alloc_zeroed(o->env, bound * sizeof(*o->rpaths));
   o->rpath_links = driver_alloc_zeroed(o->env, bound * sizeof(*o->rpath_links));
   if (!o->object_files || !o->archives || !o->dsos || !o->order ||
       !o->lib_dirs || !o->owned_paths || !o->owned_path_sizes || !o->rpaths ||
       !o->rpath_links) {
     driver_errf(LD_TOOL, "out of memory");
     return 1;
   }
   o->new_dtags = 1;
   o->allow_undefined = 1;
   return 0;
 }
 
 /* ---------- positional archive bookkeeping ---------- */
 
 static void ld_push_order(LdOptions* o, uint8_t kind, uint32_t index) {
   KitLinkInputOrder* slot = &o->order[o->norder++];
   slot->kind = kind;
   slot->index = index;
 }
 
 static void ld_insert_order(LdOptions* o, uint32_t pos, uint8_t kind,
                             uint32_t index) {
   uint32_t i;
   if (pos > o->norder) pos = o->norder;
   for (i = o->norder; i > pos; --i) o->order[i] = o->order[i - 1u];
   o->order[pos].kind = kind;
   o->order[pos].index = index;
   o->norder++;
 }
 
 static void ld_push_object(LdOptions* o, const char* path) {
   o->object_files[o->nobject_files++] = path;
   ld_push_order(o, KIT_LINK_INPUT_OBJ_BYTES, o->nobject_files - 1u);
 }
 
 static void ld_insert_object(LdOptions* o, const char* path, uint32_t pos) {
   o->object_files[o->nobject_files++] = path;
   ld_insert_order(o, pos, KIT_LINK_INPUT_OBJ_BYTES, o->nobject_files - 1u);
 }
 
 static void ld_push_archive(LdOptions* o, const char* path, int owned,
                             size_t owned_size) {
   LdArchive* a = &o->archives[o->narchives++];
   a->path = path;
   a->owned = owned;
   a->owned_size = owned_size;
   a->whole_archive = o->cur_whole_archive;
   a->link_mode = o->cur_link_mode;
   a->group_id = o->cur_group_id;
   ld_push_order(o, KIT_LINK_INPUT_ARCHIVE, o->narchives - 1u);
 }
 
 static void ld_push_runtime_archive(LdOptions* o, DriverRuntimeArchive* rt) {
   LdArchive* a = &o->archives[o->narchives++];
   a->path = rt->path;
   a->owned = 1;
   a->owned_size = rt->path_size;
   a->whole_archive = rt->whole_archive;
   a->link_mode = rt->link_mode;
   a->group_id = rt->group_id;
   rt->path = NULL;
   rt->path_size = 0;
   ld_push_order(o, KIT_LINK_INPUT_ARCHIVE, o->narchives - 1u);
 }
 
 static void ld_push_dso(LdOptions* o, const char* path, int owned,
                         size_t owned_size) {
   LdDso* d = &o->dsos[o->ndsos++];
   d->path = path;
   d->owned = owned;
   d->owned_size = owned_size;
   ld_push_order(o, KIT_LINK_INPUT_DSO, o->ndsos - 1u);
 }
 
 /* Filename ends in `.so` (with no further extension) or in `.so.N`
  * for some run of digits and dots. */
 static int driver_is_so_filename(const char* path) {
   size_t n = driver_strlen(path);
   size_t i;
   /* Walk from the end: trim trailing ".N" / ".N.N" sequences if any,
    * then check that we land on ".so". */
   i = n;
   while (i > 0) {
     /* Strip a trailing ".<digits>" cluster (e.g. ".1", ".26"). */
     size_t end = i;
     size_t j = i;
     while (j > 0) {
       char c = path[j - 1];
       if (c >= '0' && c <= '9') {
         --j;
         continue;
       }
       break;
     }
     if (j < end && j > 0 && path[j - 1] == '.') {
       i = j - 1;
       continue;
     }
     break;
   }
   if (i >= 3 && path[i - 3] == '.' && path[i - 2] == 's' && path[i - 1] == 'o')
     return 1;
   return 0;
 }
 
 static char* ld_join2(DriverEnv* env, const char* a, const char* b,
                       size_t* out_size) {
   size_t alen = driver_strlen(a);
   size_t blen = driver_strlen(b);
   size_t slash = (alen > 0 && a[alen - 1] != '/') ? 1u : 0u;
   size_t bytes = alen + slash + blen + 1u;
   char* out = driver_alloc(env, bytes);
   size_t off = 0;
   if (!out) return NULL;
   if (alen) {
     driver_memcpy(out + off, a, alen);
     off += alen;
   }
   if (slash) out[off++] = '/';
   if (blen) {
     driver_memcpy(out + off, b, blen);
     off += blen;
   }
   out[off] = '\0';
   if (out_size) *out_size = bytes;
   return out;
 }
 
 static int ld_own_path(LdOptions* o, char* path, size_t size,
                        const char** out) {
   if (!path) {
     driver_errf(LD_TOOL, "out of memory");
     return 1;
   }
   if (o->nowned_paths >= o->argv_bound) {
     driver_free(o->env, path, size);
     driver_errf(LD_TOOL, "too many sysroot-expanded paths");
     return 1;
   }
   o->owned_paths[o->nowned_paths] = path;
   o->owned_path_sizes[o->nowned_paths] = size;
   o->nowned_paths++;
   if (out) *out = path;
   return 0;
 }
 
 static int ld_add_sysroot_libdir(LdOptions* o) {
   char* path;
   size_t size;
   const char* owned;
   if (!o->sysroot || !o->sysroot[0]) return 0;
   path = ld_join2(o->env, o->sysroot, "lib", &size);
   if (ld_own_path(o, path, size, &owned) != 0) return 1;
   o->lib_dirs[o->nlib_dirs++] = owned;
   return 0;
 }
 
 static int ld_sysroot_rewrite_path(LdOptions* o, const char* path,
                                    const char** out) {
   const char* tail;
   char* joined;
   size_t size;
   if (!path || path[0] != '=' || !o->sysroot || !o->sysroot[0]) {
     *out = path;
     return 0;
   }
   tail = path + 1;
   if (tail[0] == '/') tail++;
   joined = ld_join2(o->env, o->sysroot, tail, &size);
   return ld_own_path(o, joined, size, out);
 }
 
 static int ld_note_library_request(LdOptions* o, const char* name) {
   if (driver_streq(name, "c") && !o->no_default_libs) {
     o->wants_hosted_libc = 1;
     return 1;
   }
   return 0;
 }
 
 /* ---------- --build-id parsing ---------- */
 
 static int hex_nibble(char c) {
   if (c >= '0' && c <= '9') return c - '0';
   if (c >= 'a' && c <= 'f') return 10 + (c - 'a');
   if (c >= 'A' && c <= 'F') return 10 + (c - 'A');
   return -1;
 }
 
 /* Parse a -Ttext address: 0x<hex> or decimal. Returns 0 on success. */
 static int ld_parse_addr(const char* s, uint64_t* out) {
   uint64_t v = 0;
   const char* p;
   if (!s || !s[0]) return 1;
   if (s[0] == '0' && (s[1] == 'x' || s[1] == 'X')) {
     p = s + 2;
     if (!*p) return 1;
     for (; *p; ++p) {
       int n = hex_nibble(*p);
       if (n < 0) return 1;
       v = (v << 4) | (uint64_t)n;
     }
   } else {
     for (p = s; *p; ++p) {
       if (*p < '0' || *p > '9') return 1;
       v = v * 10u + (uint64_t)(*p - '0');
     }
   }
   *out = v;
   return 0;
 }
 
 /* Parse `--build-id=...` argument into options. Accepts "none", "sha256",
  * "uuid", or "0x<even-hex>". Returns 0 on success, 1 on bad value. */
 static int ld_parse_build_id(LdOptions* o, const char* val) {
   if (driver_streq(val, "none")) {
     o->build_id_mode = KIT_BUILDID_NONE;
     return 0;
   }
   if (driver_streq(val, "sha256")) {
     o->build_id_mode = KIT_BUILDID_SHA256;
     return 0;
   }
   if (driver_streq(val, "uuid")) {
     o->build_id_mode = KIT_BUILDID_UUID;
     return 0;
   }
 
   /* "0x<hex>" — must be even number of hex digits, at least one byte. */
   if (val[0] == '0' && (val[1] == 'x' || val[1] == 'X')) {
     const char* hex = val + 2;
     size_t hex_len = driver_strlen(hex);
     size_t nbytes;
     size_t i;
     uint8_t* buf;
     if (hex_len == 0 || (hex_len & 1u)) {
       driver_errf(LD_TOOL,
                   "--build-id=0xHEX requires an even number of hex digits");
       return 1;
     }
     nbytes = hex_len / 2;
     buf = driver_alloc(o->env, nbytes);
     if (!buf) {
       driver_errf(LD_TOOL, "out of memory");
       return 1;
     }
     for (i = 0; i < nbytes; ++i) {
       int hi = hex_nibble(hex[2 * i]);
       int lo = hex_nibble(hex[2 * i + 1]);
       if (hi < 0 || lo < 0) {
         driver_errf(LD_TOOL, "--build-id: invalid hex digit");
         driver_free(o->env, buf, nbytes);
         return 1;
       }
       buf[i] = (uint8_t)((hi << 4) | lo);
     }
     o->build_id_mode = KIT_BUILDID_USER;
     o->build_id_bytes = buf;
     o->build_id_len = (uint32_t)nbytes;
     o->build_id_alloc = nbytes;
     return 0;
   }
 
   driver_errf(LD_TOOL, "--build-id: unknown value: %.*s",
               KIT_SLICE_ARG(kit_slice_cstr(val)));
   return 1;
 }
 
 /* ---------- argv parser ---------- */
 
 /* If `arg` starts with `prefix` followed by '=', returns the tail past the
  * '='; otherwise returns NULL. */
 static const char* arg_eq_value(const char* arg, const char* prefix) {
   size_t n = driver_strlen(prefix);
   if (!driver_strneq(arg, prefix, n)) return NULL;
   if (arg[n] != '=') return NULL;
   return arg + n + 1;
 }
 
 /* Compare an MSVC-style flag against `arg`, case-insensitive on the
  * key. MSVC accepts both `/` and `-` as the lead char and is
  * case-insensitive in the key part — we accept `/KEY:val`, `/key:val`,
  * `-KEY:val`. Returns the tail past the colon, or NULL on mismatch. */
 static const char* ms_flag_value(const char* arg, const char* key) {
   size_t klen = driver_strlen(key);
   size_t i;
   if (arg[0] != '/' && arg[0] != '-') return NULL;
   for (i = 0; i < klen; ++i) {
     char a = arg[1 + i];
     char k = key[i];
     if (a >= 'a' && a <= 'z') a = (char)(a - 'a' + 'A');
     if (k >= 'a' && k <= 'z') k = (char)(k - 'a' + 'A');
     if (a != k) return NULL;
   }
   if (arg[1 + klen] != ':') return NULL;
   return arg + 1 + klen + 1;
 }
 
 /* Same shape as ms_flag_value but for bare flags (no `:value`). */
 static int ms_flag_match(const char* arg, const char* key) {
   size_t klen = driver_strlen(key);
   size_t i;
   if (arg[0] != '/' && arg[0] != '-') return 0;
   for (i = 0; i < klen; ++i) {
     char a = arg[1 + i];
     char k = key[i];
     if (a >= 'a' && a <= 'z') a = (char)(a - 'a' + 'A');
     if (k >= 'a' && k <= 'z') k = (char)(k - 'a' + 'A');
     if (a != k) return 0;
   }
   return arg[1 + klen] == '\0';
 }
 
 static int ld_subsystem_value_eq(const char* val, const char* want) {
   size_t i;
   for (i = 0; want[i]; ++i) {
     char a = val[i];
     char b = want[i];
     if (a >= 'a' && a <= 'z') a = (char)(a - 'a' + 'A');
     if (b >= 'a' && b <= 'z') b = (char)(b - 'a' + 'A');
     if (a != b) return 0;
   }
   return val[i] == '\0' || val[i] == ',';
 }
 
 static int ld_parse_pe_subsystem(LdOptions* o, const char* val) {
   if (ld_subsystem_value_eq(val, "CONSOLE") ||
       ld_subsystem_value_eq(val, "CUI")) {
     o->pe_subsystem = KIT_PE_SUBSYSTEM_WINDOWS_CUI;
     return 0;
   }
   if (ld_subsystem_value_eq(val, "WINDOWS") ||
       ld_subsystem_value_eq(val, "GUI")) {
     o->pe_subsystem = KIT_PE_SUBSYSTEM_WINDOWS_GUI;
     return 0;
   }
   driver_errf(LD_TOOL, "unsupported subsystem: %.*s",
               KIT_SLICE_ARG(kit_slice_cstr(val)));
   return 1;
 }
 
 /* Parse one MSVC-style argument. Recognized subset (others warn and
  * skip — match-but-no-op so legacy build scripts pass cleanly):
  *   /OUT:path                  → o->output_path
  *   /ENTRY:sym                 → o->entry
  *   /SUBSYSTEM:CONSOLE|WINDOWS → PE optional-header subsystem; WINDOWS
  *                                also defaults entry to WinMainCRTStartup.
  *   /DEFAULTLIB:name           → equivalent to -l<name>; resolved
  *                                lazily in the same path as -l.
  *   /LIBPATH:dir               → equivalent to -L dir
  *
  * Returns 1 if consumed, 0 if not a recognized MS flag (caller falls
  * through to its existing behaviour), -1 on hard error. */
 static int ld_try_ms_flag(LdOptions* o, const char* a) {
   const char* val;
   if (!o->ms_link_driver) return 0;
   if (a[0] != '/' && a[0] != '-') return 0;
 
   if ((val = ms_flag_value(a, "OUT")) != NULL) {
     if (o->output_seen) {
       driver_errf(LD_TOOL, "/OUT specified after -o");
       return -1;
     }
     o->output_path = val;
     o->output_seen = 1;
     return 1;
   }
   if ((val = ms_flag_value(a, "ENTRY")) != NULL) {
     o->entry = val;
     return 1;
   }
   if ((val = ms_flag_value(a, "LIBPATH")) != NULL) {
     o->lib_dirs[o->nlib_dirs++] = val;
     return 1;
   }
   if ((val = ms_flag_value(a, "DEFAULTLIB")) != NULL) {
     /* Resolve eagerly like -l does, using whatever current link-mode
      * state is in effect. Windows mode triggers the .lib/.dll.a/.a
      * suffix list. */
     char* resolved;
     size_t resolved_size;
     LibResolveKind kind;
     LibResolveMode mode = (o->cur_link_mode == KIT_LM_STATIC)
                               ? LIB_RESOLVE_STATIC_ONLY
                               : LIB_RESOLVE_DYNAMIC_PREFER;
     if (driver_lib_resolve_for_os(o->env, val, mode, LIB_RESOLVE_OS_WINDOWS,
                                   o->lib_dirs, o->nlib_dirs, &resolved,
                                   &resolved_size, &kind) != 0) {
       driver_errf(LD_TOOL, "/DEFAULTLIB: cannot find %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(val)));
       return -1;
     }
     if (kind == LIB_RESOLVE_KIND_SHARED || kind == LIB_RESOLVE_KIND_TBD) {
       ld_push_dso(o, resolved, 1, resolved_size);
     } else {
       ld_push_archive(o, resolved, 1, resolved_size);
     }
     return 1;
   }
   if ((val = ms_flag_value(a, "SUBSYSTEM")) != NULL) {
     if (ld_parse_pe_subsystem(o, val) != 0) return -1;
     return 1;
   }
   if (ms_flag_match(a, "NOLOGO") || ms_flag_match(a, "VERBOSE") ||
       ms_flag_match(a, "INCREMENTAL") || ms_flag_match(a, "DEBUG") ||
       ms_flag_match(a, "DYNAMICBASE") || ms_flag_match(a, "NXCOMPAT")) {
     /* Common flags every Windows build script sets; silently accept. */
     return 1;
   }
 
   /* Any other `/key[:val]` shape under --ms-link-driver: warn + skip.
    * We treat the entire arg as consumed so it doesn't fall through to
    * the positional path and try to open a file. */
   driver_errf(LD_TOOL, "ignoring unsupported MS-style flag: %.*s",
               KIT_SLICE_ARG(kit_slice_cstr(a)));
   return 1;
 }
 
 static int ld_parse(int argc, char** argv, LdOptions* o) {
   int i;
   if (ld_alloc_arrays(o, argc) != 0) return 1;
 
   o->target = driver_host_target();
 
   /* First pass: detect --ms-link-driver up front so the option can
    * appear anywhere on the command line and still affect earlier
    * `/...` tokens. Also capture --sysroot before resolving any -l
    * entries; GNU ld treats the sysroot as a global search-prefix
    * setting, not positional state. Also detect -lc so the hosted lib
    * dirs can be pre-populated before -lm / -lpthread etc. are resolved. */
   {
     int has_lc = 0;
     for (i = 1; i < argc; ++i) {
       if (driver_streq(argv[i], "--ms-link-driver")) {
         o->ms_link_driver = 1;
         continue;
       }
       if (driver_streq(argv[i], "--sysroot")) {
         if (i + 1 < argc) {
           o->sysroot = argv[i + 1];
           i++;
         }
         continue;
       }
       if (driver_strneq(argv[i], "--sysroot=", 10)) {
         o->sysroot = argv[i] + 10;
         continue;
       }
       /* Detect -lc / -l c so hosted lib dirs are available for later -l
        * flags regardless of where -lc appears on the command line. */
       if (driver_streq(argv[i], "-lc")) {
         has_lc = 1;
         continue;
       }
       if ((driver_streq(argv[i], "-l") || driver_streq(argv[i], "--library")) &&
           i + 1 < argc && driver_streq(argv[i + 1], "c")) {
         has_lc = 1;
         i++;
         continue;
       }
     }
     if (!o->sysroot || !o->sysroot[0]) {
       const char* env_sysroot = driver_getenv("KIT_SYSROOT");
       if (env_sysroot && env_sysroot[0]) o->sysroot = env_sysroot;
     }
     if (ld_add_sysroot_libdir(o) != 0) return 1;
     /* Pre-populate the hosted lib dirs so user -l flags are resolved
      * against the correct sysroot even when they appear before -lc. */
     if (has_lc) {
       DriverHostedRequest req;
       DriverHostedDirs dirs;
       uint32_t j;
       memset(&req, 0, sizeof req);
       req.env = o->env;
       req.tool = LD_TOOL;
       req.target = o->target;
       req.sysroot = o->sysroot;
       if (driver_hosted_dirs_resolve(&req, &dirs) == 0) {
         for (j = 0; j < dirs.nlibdirs; ++j) {
           /* Transfer ownership of each dir string to o->owned_paths so
            * it is freed in ld_options_release; then point lib_dirs at it. */
           const char* p;
           if (ld_own_path(o, dirs.libdirs[j], dirs.libdir_sizes[j], &p) == 0) {
             dirs.libdirs[j] = NULL;
             dirs.libdir_sizes[j] = 0;
             o->lib_dirs[o->nlib_dirs++] = p;
           }
         }
         driver_hosted_dirs_fini(&dirs);
       }
     }
   }
 
   for (i = 1; i < argc; ++i) {
     const char* a = argv[i];
     const char* val;
     int ms_rc;
 
     if (driver_streq(a, "--ms-link-driver")) {
       o->ms_link_driver = 1;
       continue;
     }
     ms_rc = ld_try_ms_flag(o, a);
     if (ms_rc < 0) return 1;
     if (ms_rc > 0) continue;
 
     if (driver_streq(a, "-o")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "-o requires an argument");
         return 1;
       }
       if (o->output_seen) {
         driver_errf(LD_TOOL, "-o specified more than once");
         return 1;
       }
       o->output_path = argv[i];
       o->output_seen = 1;
       continue;
     }
     if ((val = arg_eq_value(a, "--output")) != NULL) {
       if (o->output_seen) {
         driver_errf(LD_TOOL, "-o specified more than once");
         return 1;
       }
       o->output_path = val;
       o->output_seen = 1;
       continue;
     }
     if (driver_streq(a, "--output")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "--output requires an argument");
         return 1;
       }
       if (o->output_seen) {
         driver_errf(LD_TOOL, "-o specified more than once");
         return 1;
       }
       o->output_path = argv[i];
       o->output_seen = 1;
       continue;
     }
     if (driver_streq(a, "-e")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "-e requires an argument");
         return 1;
       }
       o->entry = argv[i];
       continue;
     }
     if ((val = arg_eq_value(a, "--entry")) != NULL) {
       o->entry = val;
       continue;
     }
     if (driver_streq(a, "--entry")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "--entry requires an argument");
         return 1;
       }
       o->entry = argv[i];
       continue;
     }
     if ((val = arg_eq_value(a, "--subsystem")) != NULL) {
       if (ld_parse_pe_subsystem(o, val) != 0) return 1;
       continue;
     }
     if (driver_streq(a, "--subsystem")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "--subsystem requires an argument");
         return 1;
       }
       if (ld_parse_pe_subsystem(o, argv[i]) != 0) return 1;
       continue;
     }
     if (driver_streq(a, "-T")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "-T requires an argument");
         return 1;
       }
       o->script_path = argv[i];
       continue;
     }
     if ((val = arg_eq_value(a, "--script")) != NULL) {
       o->script_path = val;
       continue;
     }
     if (driver_streq(a, "--script")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "--script requires an argument");
         return 1;
       }
       o->script_path = argv[i];
       continue;
     }
     /* -Ttext ADDR / -Ttext=ADDR: set the static ET_EXEC image (text) base, for
      * freestanding images that must load at a fixed address (e.g. the qemu
      * `virt` RAM base 0x80000000). Matched here; the bare "-T" above is an exact
      * match, so it never swallows -Ttext. No effect on PIE/scripted layouts. */
     {
       const char* tval = NULL;
       if (driver_streq(a, "-Ttext")) {
         if (++i >= argc) {
           driver_errf(LD_TOOL, "-Ttext requires an argument");
           return 1;
         }
         tval = argv[i];
       } else if ((tval = arg_eq_value(a, "-Ttext")) != NULL) {
         /* -Ttext=ADDR */
       }
       if (tval) {
         uint64_t v;
         if (ld_parse_addr(tval, &v) != 0) {
           driver_errf(LD_TOOL, "-Ttext: invalid address: %s", tval);
           return 1;
         }
         o->text_base = v;
         o->text_base_set = 1;
         continue;
       }
     }
     /* -nostdlib / --no-default-libs: do not auto-resolve and link kit's
      * compiler runtime. A freestanding image (e.g. riscv32-none-elf) supplies
      * its own libkit_rt.a on the command line, and a pure-linker invocation
      * should not require a per-target runtime archive to exist. */
     if (driver_streq(a, "-nostdlib") || driver_streq(a, "--no-default-libs") ||
         driver_streq(a, "-nodefaultlibs")) {
       o->no_default_libs = 1;
       continue;
     }
     if (driver_streq(a, "--support-dir")) {
       if (++i >= argc) {
         driver_errf(LD_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, "--sysroot")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "--sysroot requires an argument");
         return 1;
       }
       o->sysroot = argv[i];
       continue;
     }
     if (driver_strneq(a, "--sysroot=", 10)) {
       o->sysroot = a + 10;
       continue;
     }
 
     if (driver_strneq(a, "-L", 2)) {
       const char* dir = a[2] ? a + 2 : (++i < argc ? argv[i] : NULL);
       const char* rewritten;
       if (!dir) {
         driver_errf(LD_TOOL, "-L requires an argument");
         return 1;
       }
       if (ld_sysroot_rewrite_path(o, dir, &rewritten) != 0) return 1;
       o->lib_dirs[o->nlib_dirs++] = rewritten;
       continue;
     }
     if ((val = arg_eq_value(a, "--library-path")) != NULL) {
       const char* rewritten;
       if (ld_sysroot_rewrite_path(o, val, &rewritten) != 0) return 1;
       o->lib_dirs[o->nlib_dirs++] = rewritten;
       continue;
     }
     if (driver_streq(a, "--library-path")) {
       const char* rewritten;
       if (++i >= argc) {
         driver_errf(LD_TOOL, "--library-path requires an argument");
         return 1;
       }
       if (ld_sysroot_rewrite_path(o, argv[i], &rewritten) != 0) return 1;
       o->lib_dirs[o->nlib_dirs++] = rewritten;
       continue;
     }
 
     if (driver_strneq(a, "-l", 2)) {
       const char* name = a[2] ? a + 2 : (++i < argc ? argv[i] : NULL);
       char* resolved;
       size_t resolved_size;
       LibResolveKind kind;
       LibResolveMode mode;
       LibResolveOS resolve_os;
       if (!name) {
         driver_errf(LD_TOOL, "-l requires an argument");
         return 1;
       }
       if (ld_note_library_request(o, name)) continue;
       /* -Bstatic forces .a only; everything else (default,
        * -Bdynamic, --as-needed) prefers .so but falls back to .a. */
       mode = (o->cur_link_mode == KIT_LM_STATIC) ? LIB_RESOLVE_STATIC_ONLY
                                                  : LIB_RESOLVE_DYNAMIC_PREFER;
       resolve_os = (o->target.os == KIT_OS_WINDOWS) ? LIB_RESOLVE_OS_WINDOWS
                                                     : LIB_RESOLVE_OS_POSIX;
       if (driver_lib_resolve_for_os(o->env, name, mode, resolve_os, o->lib_dirs,
                                     o->nlib_dirs, &resolved, &resolved_size,
                                     &kind) != 0) {
         driver_errf(LD_TOOL, "cannot find -l%.*s",
                     KIT_SLICE_ARG(kit_slice_cstr(name)));
         return 1;
       }
       if (kind == LIB_RESOLVE_KIND_SHARED || kind == LIB_RESOLVE_KIND_TBD) {
         ld_push_dso(o, resolved, 1, resolved_size);
       } else {
         ld_push_archive(o, resolved, 1, resolved_size);
       }
       continue;
     }
     if ((val = arg_eq_value(a, "--library")) != NULL) {
       char* resolved;
       size_t resolved_size;
       LibResolveKind kind;
       LibResolveMode mode = (o->cur_link_mode == KIT_LM_STATIC)
                                 ? LIB_RESOLVE_STATIC_ONLY
                                 : LIB_RESOLVE_DYNAMIC_PREFER;
       LibResolveOS resolve_os = (o->target.os == KIT_OS_WINDOWS)
                                     ? LIB_RESOLVE_OS_WINDOWS
                                     : LIB_RESOLVE_OS_POSIX;
       if (ld_note_library_request(o, val)) continue;
       if (driver_lib_resolve_for_os(o->env, val, mode, resolve_os, o->lib_dirs,
                                     o->nlib_dirs, &resolved, &resolved_size,
                                     &kind) != 0) {
         driver_errf(LD_TOOL, "cannot find -l%.*s",
                     KIT_SLICE_ARG(kit_slice_cstr(val)));
         return 1;
       }
       if (kind == LIB_RESOLVE_KIND_SHARED || kind == LIB_RESOLVE_KIND_TBD) {
         ld_push_dso(o, resolved, 1, resolved_size);
       } else {
         ld_push_archive(o, resolved, 1, resolved_size);
       }
       continue;
     }
     if (driver_streq(a, "--library")) {
       char* resolved;
       size_t resolved_size;
       LibResolveKind kind;
       LibResolveMode mode;
       LibResolveOS resolve_os;
       if (++i >= argc) {
         driver_errf(LD_TOOL, "--library requires an argument");
         return 1;
       }
       if (ld_note_library_request(o, argv[i])) continue;
       mode = (o->cur_link_mode == KIT_LM_STATIC) ? LIB_RESOLVE_STATIC_ONLY
                                                  : LIB_RESOLVE_DYNAMIC_PREFER;
       resolve_os = (o->target.os == KIT_OS_WINDOWS) ? LIB_RESOLVE_OS_WINDOWS
                                                     : LIB_RESOLVE_OS_POSIX;
       if (driver_lib_resolve_for_os(o->env, argv[i], mode, resolve_os,
                                     o->lib_dirs, o->nlib_dirs, &resolved,
                                     &resolved_size, &kind) != 0) {
         driver_errf(LD_TOOL, "cannot find -l%.*s",
                     KIT_SLICE_ARG(kit_slice_cstr(argv[i])));
         return 1;
       }
       if (kind == LIB_RESOLVE_KIND_SHARED || kind == LIB_RESOLVE_KIND_TBD) {
         ld_push_dso(o, resolved, 1, resolved_size);
       } else {
         ld_push_archive(o, resolved, 1, resolved_size);
       }
       continue;
     }
 
     if (driver_streq(a, "-static")) {
       o->target.pic = KIT_PIC_NONE;
       o->static_link = 1;
       o->cur_link_mode = KIT_LM_STATIC;
       o->pic_explicit = 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, "-dynamic-linker") ||
         driver_streq(a, "--dynamic-linker")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "-dynamic-linker requires an argument");
         return 1;
       }
       o->interp_path = argv[i];
       continue;
     }
     if ((val = arg_eq_value(a, "--dynamic-linker")) != NULL) {
       o->interp_path = val;
       continue;
     }
     if (driver_streq(a, "-no-pie")) {
       o->target.pic = KIT_PIC_NONE;
       o->pie = 0;
       o->pic_explicit = 1;
       continue;
     }
 
     if (driver_streq(a, "-shared")) {
       o->shared = 1;
       /* Shared objects must be position-independent. Force PIC unless
        * the caller has explicitly chosen PIE (which is also fine). */
       if (o->target.pic == KIT_PIC_NONE) o->target.pic = KIT_PIC_PIC;
       o->pic_explicit = 1;
       continue;
     }
     if (driver_streq(a, "-r") || driver_streq(a, "--relocatable")) {
       o->relocatable = 1;
       continue;
     }
     if (driver_streq(a, "-soname")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "-soname requires an argument");
         return 1;
       }
       o->soname = argv[i];
       continue;
     }
     if ((val = arg_eq_value(a, "-soname")) != NULL) {
       o->soname = val;
       continue;
     }
     if (driver_streq(a, "-rpath")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "-rpath requires an argument");
         return 1;
       }
       o->rpaths[o->nrpaths++] = argv[i];
       continue;
     }
     if ((val = arg_eq_value(a, "-rpath")) != NULL) {
       o->rpaths[o->nrpaths++] = val;
       continue;
     }
     if (driver_streq(a, "-rpath-link")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "-rpath-link requires an argument");
         return 1;
       }
       o->rpath_links[o->nrpath_links++] = argv[i];
       continue;
     }
     if ((val = arg_eq_value(a, "-rpath-link")) != NULL) {
       o->rpath_links[o->nrpath_links++] = val;
       continue;
     }
     if (driver_streq(a, "--enable-new-dtags")) {
       o->new_dtags = 1;
       continue;
     }
     if (driver_streq(a, "--disable-new-dtags")) {
       o->new_dtags = 0;
       continue;
     }
     if (driver_streq(a, "--gc-sections")) {
       o->gc_sections = 1;
       continue;
     }
     if (driver_streq(a, "--no-gc-sections")) {
       o->gc_sections = 0;
       continue;
     }
     if (driver_streq(a, "-S") || driver_streq(a, "--strip-debug")) {
       o->strip_debug = 1;
       continue;
     }
     if (driver_streq(a, "-E") || driver_streq(a, "--export-dynamic")) {
       o->export_dynamic = 1;
       continue;
     }
     if (driver_streq(a, "--no-undefined")) {
       o->allow_undefined = 0;
       continue;
     }
     if (driver_streq(a, "--allow-shlib-undefined")) {
       o->allow_undefined = 1;
       continue;
     }
     if (driver_streq(a, "-z")) {
       if (++i >= argc) {
         driver_errf(LD_TOOL, "-z requires an argument");
         return 1;
       }
       if (driver_streq(argv[i], "defs")) {
         o->allow_undefined = 0;
         continue;
       }
       driver_errf(LD_TOOL, "unsupported -z option: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(argv[i])));
       return 1;
     }
 
     if (driver_streq(a, "--whole-archive")) {
       o->cur_whole_archive = 1;
       continue;
     }
     if (driver_streq(a, "--no-whole-archive")) {
       o->cur_whole_archive = 0;
       continue;
     }
     if (driver_streq(a, "-Bstatic")) {
       o->cur_link_mode = KIT_LM_STATIC;
       continue;
     }
     if (driver_streq(a, "-Bdynamic")) {
       o->cur_link_mode = KIT_LM_DYNAMIC;
       continue;
     }
     if (driver_streq(a, "--as-needed")) {
       o->cur_link_mode = KIT_LM_AS_NEEDED;
       continue;
     }
     if (driver_streq(a, "--no-as-needed")) {
       o->cur_link_mode = KIT_LM_DYNAMIC;
       continue;
     }
     if (driver_streq(a, "--start-group")) {
       if (o->cur_group_id != 0) {
         driver_errf(LD_TOOL, "nested --start-group is not supported");
         return 1;
       }
       if (o->next_group_id == UINT8_MAX) {
         driver_errf(LD_TOOL, "too many --start-group occurrences");
         return 1;
       }
       o->next_group_id++;
       o->cur_group_id = o->next_group_id;
       continue;
     }
     if (driver_streq(a, "--end-group")) {
       if (o->cur_group_id == 0) {
         driver_errf(LD_TOOL, "--end-group without --start-group");
         return 1;
       }
       o->cur_group_id = 0;
       continue;
     }
 
     if ((val = arg_eq_value(a, "--build-id")) != NULL) {
       if (ld_parse_build_id(o, val) != 0) return 1;
       continue;
     }
     if (driver_streq(a, "--build-id")) {
       /* Bareword form defaults to sha256, matching GNU ld. */
       o->build_id_mode = KIT_BUILDID_SHA256;
       continue;
     }
 
     if (a[0] == '-' && a[1] != '\0') {
       driver_errf(LD_TOOL, "unknown flag: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(a)));
       return 1;
     }
 
     {
       const char* path;
       if (ld_sysroot_rewrite_path(o, a, &path) != 0) return 1;
       if (driver_has_suffix(path, ".a")) {
         ld_push_archive(o, path, 0, 0);
       } else if (driver_is_so_filename(path)) {
         ld_push_dso(o, path, 0, 0);
       } else {
         ld_push_object(o, path);
       }
     }
   }
 
   if (!o->output_path) {
     driver_errf(LD_TOOL, "-o is required");
     return 1;
   }
   if (o->cur_group_id != 0) {
     driver_errf(LD_TOOL, "missing --end-group");
     return 1;
   }
   if (o->nobject_files == 0 && o->narchives == 0 && o->ndsos == 0) {
     driver_errf(LD_TOOL, "no input files");
     ld_usage();
     return 1;
   }
   if (o->wants_hosted_libc && o->no_default_libs) {
     driver_errf(LD_TOOL,
                 "-lc hosted expansion is disabled by -nostdlib/"
                 "--no-default-libs");
     return 1;
   }
   if (o->shared) {
     driver_errf(LD_TOOL,
                 "creating dynamic/shared libraries is not yet supported");
     return 1;
   }
   if (o->relocatable) {
     if (o->shared) {
       driver_errf(LD_TOOL, "-r and -shared are incompatible");
       return 1;
     }
     if (o->wants_hosted_libc) {
       driver_errf(LD_TOOL, "-lc hosted expansion requires executable output");
       return 1;
     }
     /* Only an explicit -pie conflicts; a default PIE target.pic is simply
      * overridden by -r (driver_link_pie suppresses pie when relocatable). */
     if (o->pie) {
       driver_errf(LD_TOOL, "-r and -pie are incompatible");
       return 1;
     }
     if (o->interp_path) {
       driver_errf(LD_TOOL, "-dynamic-linker requires executable output");
       return 1;
     }
     if (o->soname || o->nrpaths || o->nrpath_links) {
       driver_errf(LD_TOOL, "-soname/-rpath/-rpath-link require -shared");
       return 1;
     }
     if (o->ndsos) {
       driver_errf(LD_TOOL, "-r does not support shared-object inputs");
       return 1;
     }
     if (o->script_path) {
       driver_errf(LD_TOOL, "-r does not support linker scripts yet");
       return 1;
     }
   }
   return 0;
 }
 
 /* ---------- options teardown ---------- */
 
 static void ld_options_release(LdOptions* o) {
   size_t bound = o->argv_bound;
   uint32_t i;
   for (i = 0; i < o->narchives; ++i) {
     LdArchive* a = &o->archives[i];
     if (a->owned && a->path) {
       driver_free(o->env, (void*)a->path, a->owned_size);
     }
   }
   for (i = 0; i < o->ndsos; ++i) {
     LdDso* d = &o->dsos[i];
     if (d->owned && d->path) {
       driver_free(o->env, (void*)d->path, d->owned_size);
     }
   }
   for (i = 0; i < o->nowned_paths; ++i) {
     if (o->owned_paths[i])
       driver_free(o->env, o->owned_paths[i], o->owned_path_sizes[i]);
   }
   if (o->build_id_bytes) {
     driver_free(o->env, o->build_id_bytes, o->build_id_alloc);
   }
   driver_hosted_plan_fini(o->env, &o->hosted);
   driver_free(o->env, o->object_files, bound * sizeof(*o->object_files));
   driver_free(o->env, o->archives, bound * sizeof(*o->archives));
   driver_free(o->env, o->dsos, bound * sizeof(*o->dsos));
   driver_free(o->env, o->order, bound * sizeof(*o->order));
   driver_free(o->env, o->lib_dirs, bound * sizeof(*o->lib_dirs));
   driver_free(o->env, o->owned_paths, bound * sizeof(*o->owned_paths));
   driver_free(o->env, o->owned_path_sizes,
               bound * sizeof(*o->owned_path_sizes));
   driver_free(o->env, o->rpaths, bound * sizeof(*o->rpaths));
   driver_free(o->env, o->rpath_links, bound * sizeof(*o->rpath_links));
 }
 
 /* ---------- input loading ---------- */
 
 typedef struct LoadedFile {
   const KitFileIO* io;
   KitFileData data;
   int loaded;
 } LoadedFile;
 
 static int load_file(const KitFileIO* io, const char* path, LoadedFile* out) {
   out->io = io;
   out->loaded = 0;
   out->data.data = NULL;
   out->data.size = 0;
   out->data.token = NULL;
   if (io->read_all(io->user, path, &out->data) != KIT_OK) return 1;
   out->loaded = 1;
   return 0;
 }
 
 static void release_file(LoadedFile* lf) {
   if (lf->loaded && lf->io && lf->io->release) {
     lf->io->release(lf->io->user, &lf->data);
   }
   lf->loaded = 0;
 }
 
 static void release_all(LoadedFile* arr, uint32_t n) {
   uint32_t i;
   if (!arr) return;
   for (i = 0; i < n; ++i) release_file(&arr[i]);
 }
 
 static int ld_append_hosted_input(LdOptions* o, const DriverHostedInput* in,
                                   uint32_t insert_pos, int insert) {
   switch ((DriverHostedInputKind)in->kind) {
     case DRIVER_HOSTED_INPUT_OBJECT:
       if (insert)
         ld_insert_object(o, in->path, insert_pos);
       else
         ld_push_object(o, in->path);
       return 0;
     case DRIVER_HOSTED_INPUT_ARCHIVE: {
       LdArchive* a = &o->archives[o->narchives++];
       a->path = in->path;
       a->owned = 0;
       a->owned_size = 0;
       a->whole_archive = 0;
       a->link_mode = KIT_LM_DEFAULT;
       a->group_id = 0;
       if (insert)
         ld_insert_order(o, insert_pos, KIT_LINK_INPUT_ARCHIVE,
                         o->narchives - 1u);
       else
         ld_push_order(o, KIT_LINK_INPUT_ARCHIVE, o->narchives - 1u);
       return 0;
     }
     case DRIVER_HOSTED_INPUT_DSO: {
       LdDso* d = &o->dsos[o->ndsos++];
       d->path = in->path;
       d->owned = 0;
       d->owned_size = 0;
       if (insert)
         ld_insert_order(o, insert_pos, KIT_LINK_INPUT_DSO, o->ndsos - 1u);
       else
         ld_push_order(o, KIT_LINK_INPUT_DSO, o->ndsos - 1u);
       return 0;
     }
     default:
       driver_errf(LD_TOOL, "internal error: unknown hosted input kind");
       return 1;
   }
 }
 
 static int ld_apply_hosted_before_after(LdOptions* o) {
   DriverHostedRequest req;
   uint32_t i;
   uint32_t insert_pos = 0;
   if (!o->wants_hosted_libc || o->shared) return 0;
   memset(&req, 0, sizeof req);
   req.env = o->env;
   req.tool = LD_TOOL;
   req.target = o->target;
   req.sysroot = o->sysroot;
   req.static_link = o->static_link;
   req.link_inputs = 1;
   if (driver_hosted_resolve(&req, &o->hosted) != 0) return 1;
   /* Add hosted lib search dirs so user -l flags resolve against the sysroot. */
   for (i = 0; i < o->hosted.nlib_search_dirs; ++i)
     o->lib_dirs[o->nlib_dirs++] = o->hosted.lib_search_dirs[i];
   for (i = 0; i < o->hosted.nbefore; ++i) {
     if (ld_append_hosted_input(o, &o->hosted.before[i], insert_pos, 1) != 0)
       return 1;
     insert_pos++;
   }
   for (i = 0; i < o->hosted.nafter; ++i) {
     if (ld_append_hosted_input(o, &o->hosted.after[i], 0, 0) != 0) return 1;
   }
   if (!o->interp_path && o->hosted.interp_path)
     o->interp_path = o->hosted.interp_path;
   return 0;
 }
 
 static int ld_apply_hosted_final(LdOptions* o) {
   uint32_t i;
   if (!o->hosted.profile_name) return 0;
   for (i = 0; i < o->hosted.nfinal; ++i) {
     if (ld_append_hosted_input(o, &o->hosted.final[i], 0, 0) != 0) return 1;
   }
   return 0;
 }
 
 /* ---------- link execution ---------- */
 
 /* Run the link. Returns 0 on success, nonzero on error. The caller owns
  * `o` and any allocations within; this function only owns transient
  * loaded-file buffers and the writer/compiler it constructs. */
 static int ld_run_link(LdOptions* o) {
   KitContext ctx = driver_env_to_context(o->env);
   const KitFileIO* io = ctx.file_io;
   KitTarget* target = NULL;
   KitCompiler* compiler = NULL;
   KitWriter* writer = NULL;
   LoadedFile* obj_lf = NULL;
   LoadedFile* arch_lf = NULL;
   LoadedFile* dso_lf = NULL;
   LoadedFile script_lf = {0};
   KitSlice* obj_in = NULL;
   KitLinkArchiveInput* arch_in = NULL;
   KitSlice* dso_in = NULL;
   KitLinkScript* script = NULL;
   KitLinkSession* link = NULL;
   DriverRuntimeSupport runtime = {0};
   DriverRuntimeArchive rt_archive = {0};
   uint32_t i;
   uint32_t initial_nobject_files;
   int runtime_resolved = 0;
   int rc = 1;
 
   if (!io || !io->read_all || !io->open_writer) {
     driver_errf(LD_TOOL, "host file I/O unavailable");
     return 1;
   }
 
   /* Load the caller's object files first so the final target is known before
    * deciding which hosted CRT/libc profile and compiler-runtime archive to
    * add. The arrays are sized to the argv bound because hosted expansion may
    * append start files after target detection. */
   initial_nobject_files = o->nobject_files;
   if (o->argv_bound) {
     obj_lf = driver_alloc_zeroed(o->env, o->argv_bound * sizeof(*obj_lf));
     obj_in = driver_alloc_zeroed(o->env, o->argv_bound * sizeof(*obj_in));
     if (!obj_lf || !obj_in) {
       driver_errf(LD_TOOL, "out of memory");
       goto out;
     }
   }
   for (i = 0; i < initial_nobject_files; ++i) {
     const char* path = o->object_files[i];
     if (load_file(io, path, &obj_lf[i]) != 0) {
       driver_errf(LD_TOOL, "failed to read: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(path)));
       goto out;
     }
     obj_in[i].data = obj_lf[i].data.data;
     obj_in[i].len = obj_lf[i].data.size;
   }
 
   /* Auto-detect target from the object inputs, falling back to the host target.
    * The PIC default is a property of the *target*, not the host: hosted targets
    * default to PIE, freestanding ones to no-PIE (driver_default_pic). The host's
    * default PIC must never leak onto a detected cross target; only an EXPLICIT
    * -static/-pie/-no-pie/-shared wins.
    *
    * Detection takes the arch from the first object, but the OS from any object:
    * a freestanding (`*-none-elf`, EI_OSABI=STANDALONE) object means a freestanding
    * link even if a foreign object (e.g. a clang-assembled startup stub, which
    * stamps EI_OSABI=SysV and so decodes as Linux) appears first. */
   if (initial_nobject_files > 0) {
     KitTargetSpec detected;
     if (kit_detect_target(obj_lf[0].data.data, obj_lf[0].data.size,
                           &detected) == KIT_OK) {
       uint8_t pic = o->target.pic;
       uint32_t oi;
       for (oi = 1; oi < initial_nobject_files; ++oi) {
         KitTargetSpec t;
         if (kit_detect_target(obj_lf[oi].data.data, obj_lf[oi].data.size, &t) ==
             KIT_OK) {
           if (t.os == KIT_OS_FREESTANDING) detected.os = KIT_OS_FREESTANDING;
           /* Reconcile the float ABI across inputs. A foreign startup stub (e.g.
            * a clang-assembled .S) may not carry the float-ABI e_flags that the
            * kit-compiled objects do, so prefer any object's hardware ABI
            * (single/double) over a soft/unset reading. This picks the runtime
            * variant (rv32 ilp32 vs ilp32f) the real code was compiled for even
            * when obj[0] is the stub. */
           if (detected.float_abi != KIT_FLOAT_ABI_SINGLE &&
               detected.float_abi != KIT_FLOAT_ABI_DOUBLE &&
               (t.float_abi == KIT_FLOAT_ABI_SINGLE ||
                t.float_abi == KIT_FLOAT_ABI_DOUBLE))
             detected.float_abi = t.float_abi;
         }
       }
       o->target = detected;
       if (o->pic_explicit)
         o->target.pic = pic;
       else
         o->target.pic = driver_default_pic(o->target.obj, o->target.os);
     }
   }
 
   if (ld_apply_hosted_before_after(o) != 0) goto out;
 
   /* Hosted dynamic link: default to PIE, matching what `kit cc` does.
    * Without PIE the link_dyn path (PLT/GOT/.rela.plt) is not entered and
    * any CALL26/PLT32 reloc against an imported symbol faults at apply time.
    * Only override when the user has not made an explicit PIC choice.
    * Non-PIE (ET_EXEC) dynamic linking is not yet supported; reject early. */
   if (o->wants_hosted_libc && !o->static_link && !o->shared &&
       !o->relocatable) {
     if (o->pic_explicit && !o->pie) {
       driver_errf(LD_TOOL,
                   "-lc with -no-pie is not supported; use -pie (default) "
                   "or -static for a static link");
       goto out;
     }
     if (!o->pic_explicit)
       o->pie = 1;
   }
 
   /* Auto-link kit's compiler runtime for any target that has a variant —
    * including the freestanding riscv32-none-elf / riscv64-none-elf targets,
    * whose runtime (and, for rv32, the float-ABI it was detected with) is
    * resolved like every other target's. A target with no variant is implicitly
    * -nostdlib and supplies its own libkit_rt.a on the command line, so skip
    * resolution rather than erroring. -nostdlib forces the skip for any target. */
   if (!o->relocatable && !o->no_default_libs &&
       driver_runtime_has_variant(o->target)) {
     if (driver_runtime_resolve(o->env, o->support_dir, o->driver_path,
                                &runtime) != 0) {
       driver_errf(LD_TOOL, "support dir not found");
       goto out;
     }
     runtime_resolved = 1;
     if (driver_runtime_prepare_archive(o->env, LD_TOOL, &runtime, o->target, 0,
                                        &rt_archive) != 0)
       goto out;
     ld_push_runtime_archive(o, &rt_archive);
   }
 
   if (ld_apply_hosted_final(o) != 0) goto out;
 
   for (i = initial_nobject_files; i < o->nobject_files; ++i) {
     const char* path = o->object_files[i];
     if (load_file(io, path, &obj_lf[i]) != 0) {
       driver_errf(LD_TOOL, "failed to read: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(path)));
       goto out;
     }
     obj_in[i].data = obj_lf[i].data.data;
     obj_in[i].len = obj_lf[i].data.size;
   }
 
   if (o->narchives) {
     arch_lf = driver_alloc_zeroed(o->env, o->narchives * sizeof(*arch_lf));
     arch_in = driver_alloc_zeroed(o->env, o->narchives * sizeof(*arch_in));
     if (!arch_lf || !arch_in) {
       driver_errf(LD_TOOL, "out of memory");
       goto out;
     }
   }
   if (o->ndsos) {
     dso_lf = driver_alloc_zeroed(o->env, o->ndsos * sizeof(*dso_lf));
     dso_in = driver_alloc_zeroed(o->env, o->ndsos * sizeof(*dso_in));
     if (!dso_lf || !dso_in) {
       driver_errf(LD_TOOL, "out of memory");
       goto out;
     }
   }
 
   /* Load archives. */
   for (i = 0; i < o->narchives; ++i) {
     const LdArchive* a = &o->archives[i];
     if (load_file(io, a->path, &arch_lf[i]) != 0) {
       driver_errf(LD_TOOL, "failed to read: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(a->path)));
       goto out;
     }
     arch_in[i].name = kit_slice_cstr(a->path);
     arch_in[i].bytes.data = arch_lf[i].data.data;
     arch_in[i].bytes.len = arch_lf[i].data.size;
     arch_in[i].whole_archive = a->whole_archive;
     arch_in[i].link_mode = a->link_mode;
     arch_in[i].group_id = a->group_id;
   }
   /* Load shared objects. */
   for (i = 0; i < o->ndsos; ++i) {
     const LdDso* d = &o->dsos[i];
     if (load_file(io, d->path, &dso_lf[i]) != 0) {
       driver_errf(LD_TOOL, "failed to read: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(d->path)));
       goto out;
     }
     dso_in[i].data = dso_lf[i].data.data;
     dso_in[i].len = dso_lf[i].data.size;
   }
 
   /* Load and parse the linker script (if any). The structured script is
    * arena-owned by the compiler; we free it explicitly before the
    * compiler is destroyed. */
   if (o->script_path) {
     if (load_file(io, o->script_path, &script_lf) != 0) {
       driver_errf(LD_TOOL, "failed to read: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(o->script_path)));
       goto out;
     }
   }
 
   {
     KitTargetOptions topts;
     memset(&topts, 0, sizeof topts);
     topts.spec = o->target;
     if (kit_target_new(&ctx, &topts, &target) != KIT_OK ||
         driver_compiler_new(target, &ctx, &compiler) != KIT_OK) {
       driver_errf(LD_TOOL, "failed to initialize compiler");
       goto out;
     }
   }
 
   if (script_lf.loaded) {
     KitSlice script_text = {.s = (const char*)script_lf.data.data,
                             .len = script_lf.data.size};
     if (kit_link_script_parse(&ctx, script_text, &script) != KIT_OK) {
       /* The parser reports a diagnostic via env.diag. */
       goto out;
     }
   }
 
   if (io->open_writer(io->user, o->output_path, &writer) != KIT_OK) {
     driver_errf(LD_TOOL, "failed to open output: %.*s",
                 KIT_SLICE_ARG(kit_slice_cstr(o->output_path)));
     goto out;
   }
 
   if (o->soname || o->nrpaths || o->nrpath_links) {
     if (!o->shared) {
       driver_errf(LD_TOOL, "-soname/-rpath/-rpath-link require -shared");
       goto out;
     }
   }
 
   {
     KitLinkSessionOptions lopts;
     KitStatus st;
     KitSlice* rpath_slices = NULL;
     /* Lift the argv-derived -rpath dirs into slices for the linker. */
     if (o->nrpaths) {
       rpath_slices =
           driver_alloc_zeroed(o->env, o->nrpaths * sizeof(*rpath_slices));
       if (!rpath_slices) {
         driver_errf(LD_TOOL, "out of memory");
         goto out;
       }
       for (i = 0; i < o->nrpaths; ++i)
         rpath_slices[i] = kit_slice_cstr(o->rpaths[i]);
     }
     memset(&lopts, 0, sizeof(lopts));
     lopts.output_kind = o->relocatable ? KIT_LINK_OUTPUT_RELOCATABLE
                         : o->shared    ? KIT_LINK_OUTPUT_SHARED
                                        : KIT_LINK_OUTPUT_EXE;
     lopts.entry = kit_slice_cstr(o->entry);
     lopts.text_base_set = o->text_base_set;
     lopts.text_base = o->text_base;
     lopts.linker_script = script;
     lopts.build_id_mode = o->build_id_mode;
     lopts.build_id_bytes = o->build_id_bytes;
     lopts.build_id_len = o->build_id_len;
     lopts.gc_sections = o->gc_sections;
     lopts.strip_debug = o->strip_debug;
     /* GNU ld and lld default to a non-PIE ET_EXEC; PIE is opt-in via -pie.
      * The linker imposes no hosted-PIE default the way a compiler driver
      * does (kit cc still defaults hosted executables to PIE through the link
      * API) — a freestanding or static link has no dynamic loader to apply a
      * PIE image's relocations or choose its base, so a PIE default produces a
      * binary that faults under a direct/qemu loader (its writable segments
      * sit below mmap_min_addr at the vaddr-0 PIE base). -shared/-r never PIE.
      * Callers that want a hosted PIE executable pass -pie explicitly (as the
      * musl dynamic lane and real compiler drivers do). */
     lopts.pie = o->pie && !o->shared && !o->relocatable;
     lopts.pe_subsystem = o->pe_subsystem;
     lopts.interp_path = kit_slice_cstr(o->interp_path);
     lopts.soname = kit_slice_cstr(o->soname);
     /* Per --enable-new-dtags / --disable-new-dtags: when new_dtags is
      * set (the default), -rpath entries land in DT_RUNPATH; otherwise
      * in DT_RPATH. -rpath-link is link-time-only and is forwarded as
      * runpaths so the library has a record of the search paths used
      * (advisory; ELF runtime ignores DT_RUNPATH entries it didn't
      * write itself, so this matches GNU-ld behaviour where rpath-link
      * does not appear in DT_*PATH). */
     if (o->new_dtags) {
       lopts.runpaths = rpath_slices;
       lopts.nrunpaths = o->nrpaths;
     } else {
       lopts.rpaths = rpath_slices;
       lopts.nrpaths = o->nrpaths;
     }
     /* By default shared output may resolve symbols against its loader at
      * runtime; --no-undefined / -z defs tightens that policy. */
     lopts.allow_undefined = o->allow_undefined ? 1 : 0;
     (void)o->export_dynamic;
 
     st = kit_link_session_new(compiler, &lopts, &link);
     if (o->order && o->norder) {
       for (i = 0; i < o->norder && st == KIT_OK; ++i) {
         const KitLinkInputOrder* ord = &o->order[i];
         switch ((KitLinkInputOrderKind)ord->kind) {
           case KIT_LINK_INPUT_OBJ:
           case KIT_LINK_INPUT_OBJ_BYTES:
             st = kit_link_session_add_obj_bytes(
                 link, kit_slice_cstr(o->object_files[ord->index]),
                 &obj_in[ord->index]);
             break;
           case KIT_LINK_INPUT_ARCHIVE:
             st = kit_link_session_add_archive_bytes(link, &arch_in[ord->index]);
             break;
           case KIT_LINK_INPUT_DSO:
             st = kit_link_session_add_dso_bytes(
                 link, kit_slice_cstr(o->dsos[ord->index].path),
                 &dso_in[ord->index]);
             break;
         }
       }
     } else {
       for (i = 0; i < o->nobject_files && st == KIT_OK; ++i)
         st = kit_link_session_add_obj_bytes(
             link, kit_slice_cstr(o->object_files[i]), &obj_in[i]);
       for (i = 0; i < o->narchives && st == KIT_OK; ++i)
         st = kit_link_session_add_archive_bytes(link, &arch_in[i]);
       for (i = 0; i < o->ndsos && st == KIT_OK; ++i)
         st = kit_link_session_add_dso_bytes(
             link, kit_slice_cstr(o->dsos[i].path), &dso_in[i]);
     }
     if (st == KIT_OK) st = kit_link_session_emit(link, writer);
     rc = st == KIT_OK ? 0 : 1;
   }
 
 out:
   if (writer) kit_writer_close(writer);
   kit_link_session_free(link);
   /* Match compiler/linker drivers: successful link outputs get executable
    * file modes while still respecting the process umask. Done after closing
    * the writer so the bits are stable on disk. */
   if (rc == 0 && o->output_path && !o->relocatable) {
     if (driver_mark_executable_output(o->output_path) != 0) {
       driver_errf(LD_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);
   if (compiler) driver_compiler_free(compiler);
   kit_target_free(target);
   driver_runtime_archive_fini(o->env, &rt_archive);
   if (runtime_resolved) driver_runtime_support_fini(o->env, &runtime);
   release_file(&script_lf);
   release_all(arch_lf, o->narchives);
   release_all(obj_lf, o->nobject_files);
   release_all(dso_lf, o->ndsos);
   if (arch_in) driver_free(o->env, arch_in, o->narchives * sizeof(*arch_in));
   if (arch_lf) driver_free(o->env, arch_lf, o->narchives * sizeof(*arch_lf));
   if (obj_in) driver_free(o->env, obj_in, o->argv_bound * sizeof(*obj_in));
   if (obj_lf) driver_free(o->env, obj_lf, o->argv_bound * sizeof(*obj_lf));
   if (dso_in) driver_free(o->env, dso_in, o->ndsos * sizeof(*dso_in));
   if (dso_lf) driver_free(o->env, dso_lf, o->ndsos * sizeof(*dso_lf));
   return rc;
 }
 
 int driver_ld(int argc, char** argv) {
   DriverEnv env;
   LdOptions lo = {0};
   int rc;
 
   if (argc < 2 || driver_argv_wants_help(argc, argv, 1)) {
     driver_help_ld();
     return 0;
   }
 
   driver_env_init(&env);
   lo.env = &env;
   lo.driver_path = argv[0];
 
   if (ld_parse(argc, argv, &lo) != 0) {
     ld_options_release(&lo);
     driver_env_fini(&env);
     return 2;
   }
 
   rc = ld_run_link(&lo);
 
   ld_options_release(&lo);
   driver_env_fini(&env);
   return rc;
 }