@scriptc/compiler 0.0.27 → 0.0.29

package/dist/backend/cc.d.ts

@@ -208,11 +208,31 @@ export interface CcDriver {
     argv: string[];
     /** The SCRIPTC_TARGET triple, or null for a host-native build. */
     target: string | null;
+    /** The spelling handed to `zig cc -target` (and the relocatable-merge
+     * link). Identical to `target` except for the mobile triples, whose
+     * canonical LLVM spellings map to zig's own (`aarch64-apple-ios` →
+     * `aarch64-ios.15.0`), pinning the minimum OS version in the same
+     * breath. Null for a host-native build. */
+    zigTarget: string | null;
     /** Extra compile args the produced platform demands. */
     targetArgs: string[];
     /** Platform libraries appended after every object/archive input. */
     linkArgs: string[];
 }
+export declare const IPHONEOS_MIN_VERSION = "15.0";
+export declare const ANDROID_MIN_API = 26;
+export declare function isIosTarget(target: string | null): boolean;
+export declare function isAndroidTarget(target: string | null): boolean;
+export declare function isMobileTarget(target: string | null): boolean;
+/** The canonical mobile triple SCRIPTC_TARGET selects, or null when the
+ * environment names none. Pure string inspection — safe to consult before
+ * any toolchain discovery runs. */
+export declare function mobileLibraryTarget(env?: NodeJS.ProcessEnv): string | null;
+/** The admission verdict for a mobile-family triple: null when the spelling
+ * and host pairing are supported, otherwise the refusal text (the same text
+ * resolveCc throws and compileLibrary reports as SC3002). Pure string/host
+ * inspection — no discovery, no subprocess. */
+export declare function mobileTargetRefusal(target: string, hostPlatform?: NodeJS.Platform): string | null;
 export declare function resolveCc(env?: NodeJS.ProcessEnv, hostPlatform?: NodeJS.Platform): CcDriver;
 /** Musl intentionally has no predefined libc macro. The explicit Zig target
  * is therefore the source of truth for selecting its small runtime shim. */
@@ -255,9 +275,13 @@ export interface LibArchiveOptions {
      * symbol. Toolchain sanitizer ABI remains external as required,
      * so N archives built under pairwise-distinct prefixes link into one
      * process with no symbol collisions and no shared mutable runtime state.
-     * Undefined references (libc/libm, plus sanitizer ABI in instrumented
-     * builds) keep their global binding. Omitted = the classic archive,
-     * byte-for-byte. Host-native builds only. */
+     * Undefined references (the target C/math runtime and system APIs, plus
+     * sanitizer ABI in instrumented builds) keep their global binding. Windows
+     * embedders additionally link advapi32, iphlpapi, and ws2_32. Omitted = the
+     * classic archive, byte-for-byte. Admitted for darwin/linux/win32 native
+     * hosts, linux/android/windows cross triples from any host, and macos/ios
+     * cross triples from a darwin host (compileLibrary owns the refusal
+     * fence). */
     localizeSymbols?: readonly string[];
     /** Thread-instanced state (the profile's abi.instance_per_thread): every
      * TU of the archive compiles with -DSCR_THREAD_INSTANCES, moving the

package/dist/backend/cc.js

@@ -1,11 +1,12 @@
-import { execFile } from "node:child_process";
+import { execFile, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { constants as fsConstants } from "node:fs";
+import { constants as fsConstants, existsSync, readdirSync } from "node:fs";
 import { createRequire } from "node:module";
 import { access, chmod, copyFile, link, mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, stat, unlink, utimes, writeFile } from "node:fs/promises";
 import { availableParallelism, homedir, tmpdir } from "node:os";
 import { basename, delimiter, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { promisify } from "node:util";
+import { localizeElfObject, mergeAndLocalizeCoffObjects } from "./object-localize.js";
 const execFileAsync = promisify(execFile);
 /** Test lanes run against one immutable checkout and one immutable toolchain
  * for the lifetime of each Vitest worker. Production deliberately rediscovers
@@ -175,6 +176,181 @@ export function runtimeSrcDir() {
     const require = createRequire(import.meta.url);
     return join(dirname(require.resolve("@scriptc/runtime/package.json")), "src");
 }
+/* ── mobile targets (library mode) ─────────────────────────────────────────
+ * Three mobile triples are admitted, and only for LIBRARY-MODE archive
+ * builds — the consuming pattern is an embedding app linking the archive,
+ * never a standalone executable (compile()/compileC refuse the executable
+ * lane with the pointer to --lib):
+ *
+ *   aarch64-apple-ios            device archives; zig `aarch64-ios.15.0`
+ *   aarch64-apple-ios-simulator  simulator archives; zig
+ *                                `aarch64-ios.15.0-simulator`
+ *   aarch64-linux-android        zig `aarch64-linux-android.26`
+ *
+ * The minimum-version floors are part of the target contract: iOS archives
+ * build for iOS 15.0 (IPHONEOS_MIN_VERSION), Android archives for API level
+ * 26 (ANDROID_MIN_API) — LC_BUILD_VERSION minos and the bionic stub level
+ * both come from the pinned zig spelling above, so an embedder's deployment
+ * target at or above the floor links cleanly.
+ *
+ * Zig bundles no Apple or bionic libc, so both families compile against an
+ * explicit sysroot discovered here and spelled into targetArgs (where every
+ * cache tier already keys it):
+ *
+ *   iOS      darwin hosts only — `xcrun --show-sdk-path` selects the
+ *            iPhoneOS/iPhoneSimulator SDK; compiles add `-isysroot <sdk>`
+ *            plus `-isystem <sdk>/usr/include` (zig's driver manages libc
+ *            header search itself and would otherwise find no headers).
+ *   Android  any host with an NDK — ANDROID_NDK_ROOT/ANDROID_NDK_HOME, or
+ *            the newest ndk/<version> under ANDROID_HOME/ANDROID_SDK_ROOT
+ *            or the platform-default SDK location; compiles add the NDK
+ *            sysroot's generic and per-triple include directories.
+ *
+ * Library archives never link, so the sysroot's LIBRARIES are the
+ * embedder's side of the contract: Xcode links iOS archives against the
+ * selected SDK, and Gradle/NDK builds link Android archives against the
+ * API-26+ bionic stubs. */
+export const IPHONEOS_MIN_VERSION = "15.0";
+export const ANDROID_MIN_API = 26;
+const MOBILE_LIBRARY_TARGETS = [
+    "aarch64-apple-ios",
+    "aarch64-apple-ios-simulator",
+    "aarch64-linux-android",
+];
+export function isIosTarget(target) {
+    return target === "aarch64-apple-ios" || target === "aarch64-apple-ios-simulator";
+}
+export function isAndroidTarget(target) {
+    return target === "aarch64-linux-android";
+}
+export function isMobileTarget(target) {
+    return isIosTarget(target) || isAndroidTarget(target);
+}
+/** The canonical mobile triple SCRIPTC_TARGET selects, or null when the
+ * environment names none. Pure string inspection — safe to consult before
+ * any toolchain discovery runs. */
+export function mobileLibraryTarget(env = process.env) {
+    const target = env["SCRIPTC_TARGET"] ?? "";
+    return isMobileTarget(target) ? target : null;
+}
+/** The admission verdict for a mobile-family triple: null when the spelling
+ * and host pairing are supported, otherwise the refusal text (the same text
+ * resolveCc throws and compileLibrary reports as SC3002). Pure string/host
+ * inspection — no discovery, no subprocess. */
+export function mobileTargetRefusal(target, hostPlatform = process.platform) {
+    if (isIosTarget(target)) {
+        return hostPlatform === "darwin"
+            ? null
+            : `${target} library archives build on macOS hosts only (the Apple iOS SDK sysroot and Mach-O symbol localization live there); this host is ${hostPlatform}`;
+    }
+    if (isAndroidTarget(target))
+        return null;
+    // A near-miss mobile spelling must refuse with the supported set named,
+    // never reach zig with no sysroot wired (the compile would fail on the
+    // first libc header) or produce an artifact for an unverified device
+    // class.
+    if (/(?:^|-)(?:ios|tvos|watchos|visionos|android)/.test(target)) {
+        return `unsupported mobile target '${target}' (supported: ${MOBILE_LIBRARY_TARGETS.join(", ")})`;
+    }
+    return null;
+}
+/** The Apple SDK root for one mobile platform, discovered through xcrun the
+ * way Xcode's own build system selects it. Memoized per SDK name and
+ * selection environment: production rediscovers per process, and the two
+ * selection variables (DEVELOPER_DIR/SDKROOT) are already mutable-input
+ * keys that disable persistent caching. */
+const appleSdkMemos = new Map();
+function appleSdkRoot(sdk, env) {
+    const key = [sdk, env["PATH"] ?? "", env["DEVELOPER_DIR"] ?? "", env["SDKROOT"] ?? ""].join("\0");
+    const memo = appleSdkMemos.get(key);
+    if (memo !== undefined)
+        return memo;
+    const probe = spawnSync("xcrun", ["--sdk", sdk, "--show-sdk-path"], {
+        encoding: "utf8",
+        env,
+    });
+    const path = probe.status === 0 ? (probe.stdout ?? "").trim() : "";
+    if (path === "" || !existsSync(join(path, "usr", "include"))) {
+        throw new Error(`the ${sdk} SDK was not found (xcrun --sdk ${sdk} --show-sdk-path failed) — ` +
+            `iOS targets need Xcode with the ${sdk === "iphoneos" ? "iPhoneOS" : "iPhoneSimulator"} SDK installed`);
+    }
+    appleSdkMemos.set(key, path);
+    return path;
+}
+/** Compare dotted-numeric NDK version directory names, newest first. */
+function compareNdkVersionsDesc(a, b) {
+    const as = a.split(".").map((s) => Number.parseInt(s, 10));
+    const bs = b.split(".").map((s) => Number.parseInt(s, 10));
+    for (let i = 0; i < Math.max(as.length, bs.length); i++) {
+        const d = (bs[i] ?? 0) - (as[i] ?? 0);
+        if (d !== 0 && Number.isFinite(d))
+            return d;
+    }
+    return a < b ? 1 : a > b ? -1 : 0;
+}
+/** The Android NDK sysroot for the selected environment: an explicit
+ * ANDROID_NDK_ROOT/ANDROID_NDK_HOME wins; otherwise the newest ndk/<version>
+ * under ANDROID_HOME, ANDROID_SDK_ROOT, or the platform-default SDK
+ * location. The prebuilt host directory is discovered rather than guessed —
+ * the NDK ships exactly one per host OS. Memoized per selection
+ * environment. */
+const ndkSysrootMemos = new Map();
+function androidNdkSysroot(env) {
+    const key = ["ANDROID_NDK_ROOT", "ANDROID_NDK_HOME", "ANDROID_HOME", "ANDROID_SDK_ROOT"]
+        .map((name) => env[name] ?? "")
+        .join("\0");
+    const memo = ndkSysrootMemos.get(key);
+    if (memo !== undefined)
+        return memo;
+    const ndkRoots = [];
+    const explicit = [env["ANDROID_NDK_ROOT"], env["ANDROID_NDK_HOME"]]
+        .find((root) => root !== undefined && root !== "");
+    if (explicit !== undefined) {
+        ndkRoots.push(explicit);
+    }
+    else {
+        const sdkRoots = [
+            env["ANDROID_HOME"],
+            env["ANDROID_SDK_ROOT"],
+            process.platform === "darwin"
+                ? join(homedir(), "Library", "Android", "sdk")
+                : process.platform === "win32"
+                    ? join(env["LOCALAPPDATA"] ?? join(homedir(), "AppData", "Local"), "Android", "Sdk")
+                    : join(homedir(), "Android", "Sdk"),
+        ].filter((root) => root !== undefined && root !== "");
+        for (const root of sdkRoots) {
+            let versions = [];
+            try {
+                versions = readdirSync(join(root, "ndk")).filter((name) => /^\d/.test(name));
+            }
+            catch {
+                continue;
+            }
+            versions.sort(compareNdkVersionsDesc);
+            ndkRoots.push(...versions.map((version) => join(root, "ndk", version)));
+        }
+    }
+    for (const ndk of ndkRoots) {
+        const prebuilt = join(ndk, "toolchains", "llvm", "prebuilt");
+        let hosts = [];
+        try {
+            hosts = readdirSync(prebuilt).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const host of hosts) {
+            const sysroot = join(prebuilt, host, "sysroot");
+            if (existsSync(join(sysroot, "usr", "include", "aarch64-linux-android"))) {
+                ndkSysrootMemos.set(key, sysroot);
+                return sysroot;
+            }
+        }
+    }
+    throw new Error("no Android NDK sysroot was found — install an NDK (sdkmanager 'ndk;<version>') and/or set " +
+        "ANDROID_NDK_ROOT to it (ANDROID_HOME with an ndk/ directory also works). " +
+        "aarch64-linux-android compiles against the NDK's bionic headers.");
+}
 /** Resolve native platform flags independently of the machine running tests,
  * so the host-Linux contract remains pinned on every development host. */
 function nativePlatformArgs(platform) {
@@ -190,22 +366,70 @@ export function resolveCc(env = process.env, hostPlatform = process.platform) {
         if (target !== "") {
             throw new Error(`SCRIPTC_TARGET=${target} requires SCRIPTC_CC=zigcc — the default clang path has no cross-target sysroots.`);
         }
-        return { argv: ["clang"], target: null, ...hostArgs };
+        return { argv: ["clang"], target: null, zigTarget: null, ...hostArgs };
     }
     if (cc !== "zigcc") {
         throw new Error(`unknown SCRIPTC_CC '${cc}' (supported: clang, zigcc)`);
     }
     if (target === "")
-        return { argv: ["zig", "cc"], target: null, ...hostArgs };
+        return { argv: ["zig", "cc"], target: null, zigTarget: null, ...hostArgs };
     if (target.includes("wasi") && target !== "wasm32-wasi") {
         throw new Error(`unsupported WASI target '${target}' (supported: wasm32-wasi)`);
     }
+    const mobileRefusal = mobileTargetRefusal(target, hostPlatform);
+    if (mobileRefusal !== null)
+        throw new Error(mobileRefusal);
+    if (isIosTarget(target)) {
+        // Library-mode-only target (compile()/compileC own the executable-lane
+        // refusal). Zig bundles no Apple libc: the compile rides the selected
+        // SDK sysroot, with the libc header directory spelled explicitly
+        // because zig's driver manages libc search itself and consults no
+        // -isysroot for it. The zig spelling pins the iOS 15.0 floor into
+        // every object's LC_BUILD_VERSION minos.
+        const simulator = target === "aarch64-apple-ios-simulator";
+        const sdk = appleSdkRoot(simulator ? "iphonesimulator" : "iphoneos", env);
+        const zigTarget = `aarch64-ios.${IPHONEOS_MIN_VERSION}${simulator ? "-simulator" : ""}`;
+        return {
+            argv: ["zig", "cc"],
+            target,
+            zigTarget,
+            targetArgs: ["-target", zigTarget, "-isysroot", sdk, "-isystem", join(sdk, "usr", "include")],
+            linkArgs: [],
+        };
+    }
+    if (isAndroidTarget(target)) {
+        // Library-mode-only target. Zig bundles no bionic: compiles ride the
+        // NDK sysroot's generic and per-triple include directories. Bionic
+        // supports _GNU_SOURCE like glibc (and hides some POSIX declarations
+        // without it); the zig spelling pins the API 26 floor, which the NDK's
+        // versioned stub libraries enforce at the embedder's link. API 26
+        // bionic carries everything the library-lane units call (arc4random_buf
+        // included), so no shim TU joins the archive.
+        const sysroot = androidNdkSysroot(env);
+        const zigTarget = `aarch64-linux-android.${ANDROID_MIN_API}`;
+        return {
+            argv: ["zig", "cc"],
+            target,
+            zigTarget,
+            targetArgs: [
+                "-target",
+                zigTarget,
+                "-D_GNU_SOURCE",
+                "-isystem",
+                join(sysroot, "usr", "include"),
+                "-isystem",
+                join(sysroot, "usr", "include", "aarch64-linux-android"),
+            ],
+            linkArgs: ["-lm"],
+        };
+    }
     const linux = target.includes("linux");
     const wasi = target.includes("wasi");
     const musl = target.includes("linux-musl");
     return {
         argv: ["zig", "cc"],
         target,
+        zigTarget: target,
         targetArgs: [
             "-target",
             target,
@@ -236,6 +460,11 @@ export function targetPlatform(driver) {
         return process.platform;
     if (driver.target.includes("wasi"))
         return "wasi";
+    // iOS is a darwin-family target: Mach-O objects, ld64 localization,
+    // POSIX path/EOL semantics. Android falls to the linux arm below —
+    // bionic is a linux libc and its archives are ordinary ELF.
+    if (isIosTarget(driver.target))
+        return "darwin";
     if (driver.target.includes("linux"))
         return "linux";
     if (driver.target.includes("windows"))
@@ -712,9 +941,12 @@ async function ensureTlsArchive(sanitize, driver, buildIdentity, cacheRoot = ven
  * units a library may reach are the pure-data ones (regex + the vendored matcher, assert,
  * inspect, symbol, searchParams, emitter+dyn_handle, zlib); every
  * loop-hooked or ambient unit was refused at SC4005 before emission.
- * External-symbol contract: undefined references only to libc/libm — which
- * is why zlib rides the VENDORED per-flavor objects here even on hosts
- * (the executable lane's system `-lz` cannot ride inside an archive). */
+ * External-symbol contract: undefined references only to the target's C/math
+ * runtime and system APIs. Windows embedders additionally link advapi32,
+ * iphlpapi, and ws2_32; the platform driver supplies its ordinary CRT and
+ * kernel imports. Zlib rides the VENDORED per-flavor objects here even on
+ * hosts because the executable lane's system `-lz` cannot ride inside an
+ * archive. */
 /** The library base: the executable lane's unconditional sources minus the
  * fiber/loop and child-process units, plus the library-mode TU. */
 const LIB_RUNTIME_SOURCES = [
@@ -817,9 +1049,10 @@ export async function compileLibArchive(opts) {
     }
     const vendorBuildIdentity = await currentVendorCacheBuildIdentity(driver, `${toolchainEnv}\0${implicitToolchain ?? "<uncached>"}`);
     // Runtime-localized archives skip the completed-archive tier: their bytes
-    // additionally depend on the host's ld/objcopy identities, which the
-    // archive key does not fingerprint. The runtime-object tier still serves
-    // them (localization consumes the same per-flavor objects).
+    // additionally depend on the localization toolchain's identity (host ld/
+    // objcopy or the cross driver's lld), which the archive key does not
+    // fingerprint. The runtime-object tier still serves them (localization
+    // consumes the same per-flavor objects).
     const cacheCompleteArchive = opts.localizeSymbols === undefined &&
         root !== null && await archiverSupportsPersistentCache(arArgv, driver);
     let cachedArchive = null;
@@ -1054,9 +1287,11 @@ export async function compileLibArchive(opts) {
  * renamed apart — they stop being visible to the embedder's linker at all,
  * so a second archive built under a different prefix brings its own private
  * copy of the whole runtime (allocator, collector, arena, panic sink) into
- * the same process. Undefined references (libc/libm, plus sanitizer ABI in
- * instrumented builds) keep their global binding: the C library and
- * sanitizer are the embedder's, shared by design.
+ * the same process. Undefined references (the target C/math runtime and
+ * system APIs, plus sanitizer ABI in instrumented builds) keep their global
+ * binding: those platform services and the sanitizer are the embedder's,
+ * shared by design. Windows embedders additionally link advapi32, iphlpapi,
+ * and ws2_32.
  *
  * Member selection matters: a classic archive's unused members (and their
  * undefined references to units library mode excludes, like the
@@ -1064,26 +1299,40 @@ export async function compileLibArchive(opts) {
  * blind merge of every object would carry those references into the one
  * combined member. Staging the support objects into an intermediate
  * archive keeps the linker's own member semantics: `ld -r` pulls only the
- * members the program object transitively needs.
+ * members the program object transitively needs (the COFF arm implements
+ * the same member semantics in process).
  *
- *   darwin — one ld64 invocation: -r merges program + needed members,
+ *   Mach-O — one host-ld64 invocation: -r merges program + needed members,
  *            -exported_symbols_list demotes every unlisted global to
  *            private extern, and -r without -keep_private_externs writes
  *            private externs out as non-external symbols. Apple ASan's
  *            image-registration COMMON remains shared so the final Mach-O
- *            image registers its globals once.
- *   linux  — ld -r merges with --force-group-allocation (ASan's
- *            instrumented globals ride ELF section groups whose signatures
- *            repeat across archives sharing runtime objects; resolving the
- *            groups into the combined member keeps a later multi-archive
- *            link from discarding one archive's copies), then binutils
- *            objcopy --keep-global-symbols localizes every other DEFINED
- *            global (objcopy leaves undefined symbols global by its own
- *            rule).
- *
- * Host-native only: compileLibrary refuses localization for cross targets
- * before emission (this step runs the host's ld/objcopy over host-format
- * objects). */
+ *            image registers its globals once. ld64 reads every Apple
+ *            platform's objects — macOS architectures and the iOS/
+ *            iOS-simulator triples alike (LC_BUILD_VERSION platform and
+ *            minos survive the merge) — so darwin-host macos AND ios
+ *            targets ride the same arm; compileLibrary refuses those
+ *            targets elsewhere.
+ *   ELF, native linux host — ld -r merges with --force-group-allocation
+ *            (ASan's instrumented globals ride ELF section groups whose
+ *            signatures repeat across archives sharing runtime objects;
+ *            resolving the groups into the combined member keeps a later
+ *            multi-archive link from discarding one archive's copies),
+ *            then binutils objcopy --keep-global-symbols localizes every
+ *            other DEFINED global (objcopy leaves undefined symbols
+ *            global by its own rule). The exact historical recipe.
+ *   ELF, cross triples from any host — `zig cc -target <triple> -r`
+ *            merges (zig is already the cross driver's hard requirement),
+ *            then localizeElfObject demotes in process and resolves
+ *            section groups the way --force-group-allocation does, with
+ *            no host binutils/llvm-objcopy dependency.
+ *   COFF, native win32 hosts and windows cross triples from any host —
+ *            mergeAndLocalizeCoffObjects performs member selection, the
+ *            merge, cross-object symbol resolution, and demotion in
+ *            process: no linker offers a COFF relocatable mode (lld-link
+ *            mirrors MSVC link.exe; zig's COFF driver refuses multi-object
+ *            merges) and llvm-objcopy rejects symbol-scope flags for
+ *            COFF, so no tool pairing exists to shell out to. */
 async function localizeLibraryObjects(driver, arArgv, buildDir, programObject, supportObjects, keepSymbols, stem) {
     const platform = targetPlatform(driver);
     const combined = join(buildDir, `${stem}.localized.o`);
@@ -1096,21 +1345,58 @@ async function localizeLibraryObjects(driver, arArgv, buildDir, programObject, s
         catch (err) {
             const stderr = err.stderr ?? String(err);
             throw new Error(`${argv[0]} failed while localizing the library archive's runtime symbols (abi.localize_runtime).\n` +
-                `Runtime symbol localization needs the host toolchain's ${platform === "darwin" ? "ld" : "ld and objcopy"} beside the C compiler.\n\n${stderr}`);
+                `Runtime symbol localization needs the ${platform === "darwin" ? "host toolchain's ld" : driver.target === null ? "host toolchain's ld and objcopy" : "cross driver's relocatable link"} beside the C compiler.\n\n${stderr}`);
         }
     };
+    if (platform === "win32") {
+        // COFF has no relocatable-link tool to stage through; the member
+        // selection and combine+demote happen in process over the object bytes.
+        const [program, ...support] = await Promise.all([programObject, ...supportObjects].map((path) => readFile(path)));
+        try {
+            await writeFile(combined, mergeAndLocalizeCoffObjects(program, support, new Set(keepSymbols), {
+                program: basename(programObject),
+                support: supportObjects.map((path) => basename(path)),
+            }));
+        }
+        catch (err) {
+            throw new Error(`COFF symbol localization failed while localizing the library archive's runtime symbols (abi.localize_runtime).\n\n${err.message}`);
+        }
+        return combined;
+    }
     await run([arArgv[0] ?? "ar", ...arArgv.slice(1), "rcs", staging, ...supportObjects]);
     if (platform === "darwin") {
         await writeFile(keepFile, keepSymbols.map((s) => `_${s}\n`).join(""));
         await run(["ld", "-r", programObject, staging, "-o", combined, "-exported_symbols_list", keepFile]);
     }
-    else if (platform === "linux") {
+    else if (platform === "linux" && driver.target === null) {
         await writeFile(keepFile, keepSymbols.map((s) => `${s}\n`).join(""));
         await run(["ld", "-r", "--force-group-allocation", programObject, staging, "-o", combined]);
         await run(["objcopy", `--keep-global-symbols=${keepFile}`, combined]);
     }
+    else if (platform === "linux") {
+        // Cross ELF: the cross driver's own lld performs the relocatable merge
+        // (with the staging archive's member semantics); demotion and section-
+        // group resolution happen in process. -nostdlib keeps zig from feeding
+        // libc/compiler-rt inputs into the merge. Android rides this arm
+        // unchanged: bionic archives are ordinary aarch64 ELF64, and the merge
+        // uses the driver's zig spelling (which pins the API floor).
+        await run([
+            driver.argv[0] ?? "zig",
+            ...driver.argv.slice(1),
+            "-target", driver.zigTarget ?? driver.target,
+            "-nostdlib",
+            "-r", programObject, staging,
+            "-o", combined,
+        ]);
+        try {
+            await writeFile(combined, localizeElfObject(await readFile(combined), new Set(keepSymbols)));
+        }
+        catch (err) {
+            throw new Error(`ELF symbol localization failed while localizing the library archive's runtime symbols (abi.localize_runtime).\n\n${err.message}`);
+        }
+    }
     else {
-        throw new Error(`runtime symbol localization (abi.localize_runtime) supports darwin and linux host builds; this build targets ${platform}`);
+        throw new Error(`runtime symbol localization (abi.localize_runtime) has no ${platform} arm; compileLibrary admits darwin, linux, and win32 builds only`);
     }
     return combined;
 }
@@ -2277,6 +2563,14 @@ export async function compileC(opts) {
     const http = (opts.http ?? false) || nativeFetch || netIsland;
     const tls = (opts.tls ?? false) || nativeFetch || netIsland;
     const driver = resolveCc();
+    // Mobile triples produce library archives, never standalone executables:
+    // the executable-lane runtime (event loop, sockets, child processes) is
+    // not verified on those device classes. compile() reports the SC3002
+    // diagnostic first; this is the backstop for direct compileC callers.
+    if (isMobileTarget(driver.target)) {
+        throw new Error(`SCRIPTC_TARGET=${driver.target} builds library-mode static archives only — ` +
+            `compile with a library profile (SCRIPTC_CC=zigcc scriptc build --lib --profile <profile.json>) and link the archive from the app project.`);
+    }
     const runtimeSources = targetPlatform(driver) === "wasi"
         ? RUNTIME_SOURCES.filter((source) => source !== "scr_child.c")
         : RUNTIME_SOURCES;