xbintsc 0.5.52 → 0.6.8

package/src/driver/compiler.ts

@@ -18,18 +18,20 @@ import { DiagnosticBag, DiagnosticCode } from "../diagnostics/diagnostic.js";
 import { generate } from "../codegen/llvm.js";
 import { createDefaultRegistry } from "../extensions/registry.js";
 import { BuildCache } from "./cache.js";
-import { findRuntimeDir } from "./paths.js";
-import { resolveToolchain } from "./toolchain-provider.js";
+import { findRuntimeDir, platformSlug } from "./paths.js";
+import { resolveToolchain, type ResolvedToolchain } from "./toolchain-provider.js";
 import { readIcon, IconError, type IconInfo } from "./icon.js";
 import { bundlePathFor, packageMacApp } from "./mac-bundle.js";
 import type { AppConfig } from "./config.js";
 import { compileIr, link, mergeProfileData, realRunner, ToolchainError } from "./toolchain.js";
 import { parseEntry } from "./frontend.js";
-import { ensureRuntimeObjects } from "./runtime-objects.js";
+import { ensureRuntimeObjects, type RuntimeObjects } from "./runtime-objects.js";
 import { ensureAppArtifacts } from "./app-artifacts.js";
 import { buildCacheKey } from "./build-key.js";
 import { collectUsage } from "./usage.js";
 import { resolveLinkFeatures, type ResolvedLinkFeature } from "./link-features.js";
+import { isPrebuiltArchivePath, firstFailureLine, looksLikePrebuiltLinkFailure } from "./prebuilt.js";
+import { runtimeLibDirs as defaultRuntimeLibDirs } from "./runtime-lib.js";
 import type { BuildOptions, BuildResult, EmitKind, PhaseTiming } from "./options.js";
 
 export { COMPILER_VERSION } from "./version.js";
@@ -68,6 +70,36 @@ function executableName(entry: string, outDir: string, explicit: string | undefi
   return resolve(outDir, base + suffix);
 }
 
+/**
+ * Explain a retry that still fails while prebuilt `gui`/`media` archives are in
+ * the link. Unlike `core`/`ext_node`, those bundle SDL3/FFmpeg/glslang and
+ * their sources are not part of the npm package, so the source fallback cannot
+ * replace them; only a release/toolchain match can.
+ */
+function prebuiltFallbackError(
+  error: unknown,
+  runtimeObjects: RuntimeObjects,
+  dirs: readonly string[] | undefined,
+): unknown {
+  if (!(error instanceof ToolchainError) || !looksLikePrebuiltLinkFailure(error.stderr)) return error;
+  const runtimeDirs = dirs ?? defaultRuntimeLibDirs();
+  const fixed = [...runtimeObjects.featureObjects, ...runtimeObjects.nativeObjects].filter((object) =>
+    isPrebuiltArchivePath(object, runtimeDirs),
+  );
+  if (fixed.length === 0) return error;
+  const archives = [...new Set(fixed.map((object) => basename(object)))].join(", ");
+  return new ToolchainError(
+    error.command,
+    error.status,
+    `${error.stderr}\n` +
+      `The remaining prebuilt archives (${archives}) come from the @xbintsc/${platformSlug()} ` +
+      "package. Unlike the C runtime, they bundle SDL3/FFmpeg, whose sources are not shipped " +
+      "in the npm package, so they cannot be rebuilt here.\n" +
+      "Build with the Xcode Command Line Tools / Visual Studio C++ toolset the release was built " +
+      "with, or use a release archive built for this machine.",
+  );
+}
+
 export function build(entryPath: string, options: BuildOptions = {}): BuildResult {
   const runner = options.runner ?? realRunner;
   const registry = options.extensions ?? createDefaultRegistry();
@@ -220,8 +252,8 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
 
   // -- toolchain -----------------------------------------------------------
   const clangStarted = Date.now();
-  const toolchain = options.clang
-    ? { clang: options.clang, linkerArgs: [] as string[], env: {} as Record<string, string> }
+  const toolchain: Pick<ResolvedToolchain, "clang" | "linkerArgs" | "env" | "sdkRoot"> = options.clang
+    ? { clang: options.clang, linkerArgs: [], env: {} }
     : resolveToolchain(runner);
   const clang = toolchain.clang;
   if (pgo === "use") {
@@ -244,6 +276,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     objectPath,
     optimize,
     env: toolchain.env,
+    sdkRoot: toolchain.sdkRoot,
     debug: options.debug === true,
     lto,
     ...(pgo ? { pgo, pgoDir } : {}),
@@ -256,21 +289,32 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     return { outputPath, irPath, cached: false, diagnostics: [], ir, timings };
   }
 
-  const runtimeStarted = Date.now();
-  const { runtimeObjects, extensionObjects, featureObjects, nativeObjects } = ensureRuntimeObjects({
-    runner,
-    clang,
-    runtimeDir,
-    cacheDir,
-    registry,
-    preferPrebuilt: resolvePreferPrebuilt(options.preferPrebuilt) && !lto && pgo === undefined,
-    env: toolchain.env,
-    lto,
-    pgo,
-    pgoDir,
-    features: linkFeatures,
-  });
-  timings.push({ phase: "runtime", ms: Date.now() - runtimeStarted });
+  /* The runtime is assembled before the app artifacts so a failed prebuilt
+   * link can be retried with the same artifact inputs. */
+  const runtimeLibDirs = options.runtimeLibDirs;
+  const preferPrebuilt = resolvePreferPrebuilt(options.preferPrebuilt) && !lto && pgo === undefined;
+  const assembleRuntime = (usePrebuilt: boolean): RuntimeObjects => {
+    const started = Date.now();
+    const assembled = ensureRuntimeObjects({
+      runner,
+      clang,
+      runtimeDir,
+      cacheDir,
+      registry,
+      preferPrebuilt: usePrebuilt,
+      env: toolchain.env,
+      sdkRoot: toolchain.sdkRoot,
+      lto,
+      pgo,
+      pgoDir,
+      features: linkFeatures,
+      ...(runtimeLibDirs !== undefined ? { runtimeLibDirs } : {}),
+    });
+    timings.push({ phase: "runtime", ms: Date.now() - started });
+    return assembled;
+  };
+
+  let assembled = assembleRuntime(preferPrebuilt);
 
   const artifacts = ensureAppArtifacts({
     runner,
@@ -280,6 +324,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     app,
     icon,
     env: toolchain.env,
+    sdkRoot: toolchain.sdkRoot,
     verbose: options.verbose,
   });
   if (artifacts.iconError !== undefined) {
@@ -287,42 +332,108 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     return { outputPath, irPath, cached: false, diagnostics: diagnostics.diagnostics, ir };
   }
 
-  const linkStarted = Date.now();
-  link(runner, {
-    clang,
-    objectPaths: [
-      objectPath,
-      /* Feature archives come after their bridges (which reference the
-       * implementation) and before the extensions' own archives (`gui.a`
-       * provides symbols the bridges call back into). `Set` keeps that order
-       * and drops an archive two features or an extension share. */
-      ...new Set([
-        ...runtimeObjects,
-        ...extensionObjects,
-        ...featureObjects,
-        ...nativeObjects,
-        ...(artifacts.entryObject !== undefined ? [artifacts.entryObject] : []),
-        ...artifacts.iconObjects,
-      ]),
-    ],
-    outputPath,
-    linkerFlags: [
-      ...toolchain.linkerArgs,
-      ...(process.platform === "win32" ? ["-lws2_32"] : ["-lm", "-pthread"]),
-      ...registry.linkerFlags(),
-      ...linkFeatures.flatMap((feature) => feature.linkerFlags),
-      /* A GUI program is a Windows-subsystem executable: no console window is
-       * created when it is launched. Console output (stdout/stderr) is lost in
-       * that subsystem, so a program that wants to report things opts back in
-       * with `app.console: true`. */
-      ...artifacts.linkerFlags,
-    ],
-    optimize,
-    env: toolchain.env,
-    lto,
-    ...(pgo ? { pgo, pgoDir } : {}),
-  });
-  timings.push({ phase: "link", ms: Date.now() - linkStarted });
+  const linkAssembled = (runtimeObjects: RuntimeObjects): string => {
+    const started = Date.now();
+    const result = link(runner, {
+      clang,
+      objectPaths: [
+        objectPath,
+        /* Feature archives come after their bridges (which reference the
+         * implementation) and before the extensions' own archives (`gui.a`
+         * provides symbols the bridges call back into). `Set` keeps that order
+         * and drops an archive two features or an extension share. */
+        ...new Set([
+          ...runtimeObjects.runtimeObjects,
+          ...runtimeObjects.extensionObjects,
+          ...runtimeObjects.featureObjects,
+          ...runtimeObjects.nativeObjects,
+          ...(artifacts.entryObject !== undefined ? [artifacts.entryObject] : []),
+          ...artifacts.iconObjects,
+        ]),
+      ],
+      outputPath,
+      linkerFlags: [
+        ...toolchain.linkerArgs,
+        ...(process.platform === "win32" ? ["-lws2_32"] : ["-lm", "-pthread"]),
+        ...registry.linkerFlags(),
+        ...linkFeatures.flatMap((feature) => feature.linkerFlags),
+        /* A GUI program is a Windows-subsystem executable: no console window is
+         * created when it is launched. Console output (stdout/stderr) is lost in
+         * that subsystem, so a program that wants to report things opts back in
+         * with `app.console: true`. */
+        ...artifacts.linkerFlags,
+      ],
+      optimize,
+      env: toolchain.env,
+      sdkRoot: toolchain.sdkRoot,
+      lto,
+      ...(pgo ? { pgo, pgoDir } : {}),
+    });
+    timings.push({ phase: "link", ms: Date.now() - started });
+    return result.stderr;
+  };
+
+  /**
+   * Retry once with the C runtime compiled from the sources shipped in the
+   * package. The failed attempt is not cached: a later toolchain upgrade can
+   * use the archive again.
+   */
+  const retryFromSource = (stderr: string): void => {
+    const reason = firstFailureLine(stderr);
+    process.stderr.write(
+      "xbintsc: the prebuilt runtime archive does not match this toolchain" +
+        (reason ? ` (${reason})` : "") +
+        "; compiling the C runtime from source\n",
+    );
+    assembled = assembleRuntime(false);
+    try {
+      linkAssembled(assembled);
+    } catch (retryError) {
+      throw prebuiltFallbackError(retryError, assembled, runtimeLibDirs);
+    }
+  };
+  const prebuiltInUse = (): boolean =>
+    preferPrebuilt && assembled.prebuiltArchives.length > 0;
+  /** Whether the linker talked about an archive the source fallback can replace. */
+  const mentionsRebuildableArchive = (stderr: string): boolean =>
+    assembled.prebuiltArchives.some((archive) => stderr.includes(basename(archive)));
+
+  /* One attempt, captured instead of thrown so the retry below is not itself
+   * caught by this decision block. `failed` is explicit because a thrown
+   * `undefined` must not look like a successful link. */
+  let failed = false;
+  let firstError: unknown;
+  let firstStderr = "";
+  try {
+    firstStderr = linkAssembled(assembled);
+  } catch (error) {
+    failed = true;
+    firstError = error;
+  }
+
+  if (failed) {
+    const error = firstError;
+    /* The release runner's Xcode/SDK or Visual Studio toolset can be newer
+     * than this machine's, and then the prebuilt archive cannot be linked
+     * (`LNK2038`, `LNK2019`, `Undefined symbols`, ...). The C runtime sources
+     * ship with the package, so retry once with them instead of failing on a
+     * linker message the user cannot act on. */
+    if (!prebuiltInUse() || !(error instanceof ToolchainError) || !looksLikePrebuiltLinkFailure(error.stderr)) {
+      throw error;
+    }
+    retryFromSource(error.stderr);
+  } else if (
+    prebuiltInUse() &&
+    mentionsRebuildableArchive(firstStderr) &&
+    looksLikePrebuiltLinkFailure(firstStderr)
+  ) {
+    /* A successful link can still warn that the archive was built for a newer
+     * macOS than the one being targeted: the binary would then claim the local
+     * deployment target while calling newer SDK symbols at run time, so rebuild
+     * it from source just like an outright failure. Only `core`/`ext_node` can
+     * be replaced this way; a warning about `gui.a`/`media.a` is left alone. */
+    retryFromSource(firstStderr);
+  }
 
   const bundlePath =
     bundle !== undefined

package/src/driver/icon.ts

@@ -16,7 +16,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { hashParts } from "./cache.js";
-import { compileC, type Runner } from "./toolchain.js";
+import { compileC, sysrootFlags, type Runner } from "./toolchain.js";
 
 export type IconFormat = "png" | "ico" | "icns";
 
@@ -144,6 +144,7 @@ export function ensureIconObject(
   cacheDir: string,
   icon: IconInfo,
   env?: Record<string, string>,
+  sdkRoot?: string,
 ): string {
   const key = hashParts(["icon", process.platform, Buffer.from(icon.bytes).toString("base64")]);
   const sourcePath = join(cacheDir, `icon-${key}.c`);
@@ -151,7 +152,7 @@ export function ensureIconObject(
   if (!existsSync(objectPath)) {
     mkdirSync(cacheDir, { recursive: true });
     writeFileSync(sourcePath, iconSource(icon));
-    compileC(runner, clang, sourcePath, objectPath, cacheDir, env);
+    compileC(runner, clang, sourcePath, objectPath, cacheDir, env, sysrootFlags(sdkRoot));
   }
   return objectPath;
 }

package/src/driver/macos-sdk.ts

@@ -0,0 +1,52 @@
+/**
+ * macOS SDK discovery.
+ *
+ * macOS has no `/usr/include`: every C standard header (`stdio.h`,
+ * `setjmp.h`, …) ships inside the SDK, and the linker's `libm`/`libSystem`
+ * stubs live there too. clang only searches the SDK when it has a sysroot,
+ * which comes from the `/usr/bin/clang` shim, an explicit `-isysroot`, or the
+ * `SDKROOT` environment variable.
+ *
+ * xbintsc invokes clang by absolute path (CI pins it to the oldest installed
+ * Xcode so released archives stay linkable by newer ones), which bypasses the
+ * shim. Without a sysroot that driver sees neither the SDK nor `/usr/include`,
+ * and the first runtime include fails with `'setjmp.h' file not found` — the
+ * header is irrelevant, any system header would do. The same gap makes the
+ * link fail later with `ld: library 'm' not found`.
+ *
+ * The SDK is therefore resolved once, with `xcrun`, and handed to clang as
+ * `-isysroot` on the command line rather than as `SDKROOT` in the environment:
+ * a self-hosted xbintsc binary runs the same driver, and its compiled
+ * `spawnSync` ignores `options.env`, so the variable would be lost exactly
+ * where the compiler rebuilds itself. An explicit `SDKROOT` in the environment
+ * always wins, so a developer can select an older SDK deliberately.
+ */
+
+import { existsSync } from "node:fs";
+import type { CommandResult, Runner } from "./toolchain.js";
+
+/**
+ * The macOS SDK `xcrun` reports, or `undefined` when the host is not macOS,
+ * the environment already names one, or no usable SDK can be resolved.
+ *
+ * A missing SDK is not an error here: the build still runs, and clang reports
+ * the real problem (or the driver never needed the SDK in the first place).
+ */
+export function macosSdkRoot(
+  runner: Runner,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string | undefined {
+  if (platform !== "darwin") return undefined;
+  if (env.SDKROOT) return undefined;
+  let result: CommandResult;
+  try {
+    result = runner.run("xcrun", ["--show-sdk-path"]);
+  } catch {
+    /* A host without xcrun keeps the previous behaviour: let clang decide. */
+    return undefined;
+  }
+  if (result.status !== 0) return undefined;
+  const sdk = result.stdout.trim();
+  return sdk.length > 0 && existsSync(sdk) ? sdk : undefined;
+}

package/src/driver/options.ts

@@ -28,6 +28,12 @@ export interface BuildOptions {
   readonly clang?: string;
   /** Prefer a prebuilt `runtime/lib/<os>-<arch>/*.a` archive when present (default true). */
   readonly preferPrebuilt?: boolean;
+  /**
+   * Folders searched for the prebuilt `core`/`ext_<name>` archives, replacing
+   * the default (`runtime/lib/<os>-<arch>` plus the installed platform
+   * package). Mostly useful for tests and embedding tools.
+   */
+  readonly runtimeLibDirs?: readonly string[];
   readonly write?: boolean;
   /** Application icon embedded into the binary (shorthand for `app.icon`). */
   readonly icon?: string;

package/src/driver/platform-support.ts

@@ -0,0 +1,69 @@
+/**
+ * Oldest platform versions xbintsc supports, and the baseline every released
+ * artifact is built against.
+ *
+ * The prebuilt runtime archives (`core`, `ext_node`, `gui`, `media`) and the
+ * self-hosted compiler are built by CI with the **oldest toolchain each host
+ * still offers**, targeting the floors below. A newer Xcode/Visual Studio on a
+ * user's machine can link those older objects, but the reverse is what fails
+ * (`LNK2038`, `LNK2019`, `Undefined symbols`, `was built for newer macOS
+ * version`), which is why the direction matters.
+ *
+ * These values are the single source of truth for the archive build scripts,
+ * `xbintsc doctor` and `doc/requirements.md`.
+ */
+
+/** Deployment target for every macOS artifact (also the Apple Silicon floor). */
+export const MACOS_MINIMUM_VERSION = "11.0";
+
+/**
+ * Oldest Windows version the prebuilt objects and the compiler target.
+ *
+ * Windows 10 was the floor while the release jobs ran on `windows-2022`
+ * (VS 2022 / MSVC v143). Those images cannot assemble a release: their bundled
+ * `tar` has no built-in zstd, so `tar --zstd` hands compression to an external
+ * program the step waits on forever. The release jobs therefore run on
+ * `windows-2025`, whose toolset targets Windows 11, and the supported floor
+ * moved with them.
+ */
+export const WINDOWS_MINIMUM_VERSION = "11";
+
+/**
+ * glibc the release archives are built and tested against: the GitHub
+ * `ubuntu-24.04` image. Older distributions may link the npm package's
+ * archives, but only this floor is supported.
+ */
+export const LINUX_MINIMUM_GLIBC = "2.39";
+
+/** Human-readable support floor for the host running the compiler. */
+export function supportFloor(platform: NodeJS.Platform = process.platform): string {
+  switch (platform) {
+    case "darwin":
+      return `macOS ${MACOS_MINIMUM_VERSION}+`;
+    case "win32":
+      return `Windows ${WINDOWS_MINIMUM_VERSION}+`;
+    case "linux":
+      return `glibc ${LINUX_MINIMUM_GLIBC}+`;
+    default:
+      return `${platform} (unverified)`;
+  }
+}
+
+/**
+ * Make a macOS archive build target {@link MACOS_MINIMUM_VERSION}.
+ *
+ * Clang's Darwin driver reads `MACOSX_DEPLOYMENT_TARGET`, and CMake reads it as
+ * the default for `CMAKE_OSX_DEPLOYMENT_TARGET`; setting both keeps the direct
+ * engine compiles, the vendored CMake builds and FFmpeg's configure on the same
+ * floor. An explicit value in the environment still wins, so a developer can
+ * target an even older macOS deliberately. No-op on the other hosts.
+ */
+export function applyMacosDeploymentTarget(platform: NodeJS.Platform = process.platform): void {
+  if (platform !== "darwin") return;
+  if (!process.env.MACOSX_DEPLOYMENT_TARGET) {
+    process.env.MACOSX_DEPLOYMENT_TARGET = MACOS_MINIMUM_VERSION;
+  }
+  if (!process.env.CMAKE_OSX_DEPLOYMENT_TARGET) {
+    process.env.CMAKE_OSX_DEPLOYMENT_TARGET = MACOS_MINIMUM_VERSION;
+  }
+}

package/src/driver/prebuilt.ts

@@ -0,0 +1,61 @@
+/**
+ * Detecting a prebuilt runtime archive that this machine's toolchain cannot
+ * link.
+ *
+ * The optional `@xbintsc/<os>-<arch>` package carries archives compiled on the
+ * release runner (`core.a`, `ext_node.a`, `gui.a`, `media.a`). Its Xcode
+ * Command Line Tools or Visual Studio C++ toolset can be **newer** than the
+ * one on the machine that runs the build: a linker can then reject the archive
+ * with unresolved symbols (`LNK2038`/`LNK2019`, `Undefined symbols`,
+ * `undefined reference`) or `was built for newer macOS version`.
+ *
+ * The driver answers that with one automatic retry that compiles the runtime
+ * from the sources shipped in the npm package. Its decision is based on the
+ * linker's own output rather than a version comparison, because an archive does
+ * not record the toolset that produced it portably: Mach-O objects carry
+ * `LC_BUILD_VERSION`, COFF objects do not carry an MSVC toolset version.
+ *
+ * `gui.a`/`media.a` are exempt: they bundle SDL3/FFmpeg/glslang, whose sources
+ * are not part of the npm package, so they cannot be rebuilt from it.
+ */
+
+import { dirname, resolve } from "node:path";
+
+const ARCHIVE_SUFFIXES = [".a", ".lib"] as const;
+
+/** True when `candidate` is a static archive that sits in one of `dirs`. */
+export function isPrebuiltArchivePath(candidate: string, dirs: readonly string[]): boolean {
+  if (!ARCHIVE_SUFFIXES.some((suffix) => candidate.endsWith(suffix))) return false;
+  const parent = dirname(resolve(candidate));
+  return dirs.some((dir) => resolve(dir) === parent);
+}
+
+/**
+ * Linker messages that mean "these objects were produced by a different
+ * toolchain/SDK". Kept deliberately narrow: a missing file, a bad flag or a
+ * permission error must not trigger the (slow) source rebuild.
+ */
+const MISMATCH_PATTERNS = [
+  /LNK2038/i, // mismatch detected for 'RuntimeLibrary'/'_MSC_VER'
+  /LNK20(?:01|19)/i, // unresolved external symbol
+  /undefined symbols?/i, // ld64
+  /undefined reference/i, // GNU/LLD
+  /symbol\(s\) not found/i, // ld64 summary line
+  /was built for newer (?:macOS|iOS|tvOS|watchOS|visionOS)/i, // ld64 warning
+  /but linking in object file built for/i, // ld64 deployment-target error
+  /has an incompatible (?:architecture|platform)/i,
+] as const;
+
+/** Whether a failed link's stderr looks like a toolchain/archive mismatch. */
+export function looksLikePrebuiltLinkFailure(stderr: string): boolean {
+  return MISMATCH_PATTERNS.some((pattern) => pattern.test(stderr));
+}
+
+/** First non-empty line of a command's stderr, for a one-line build notice. */
+export function firstFailureLine(stderr: string): string {
+  for (const line of stderr.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.length > 0) return trimmed.length > 160 ? `${trimmed.slice(0, 157)}...` : trimmed;
+  }
+  return "";
+}

package/src/driver/runtime-objects.ts

@@ -12,7 +12,7 @@ import type { ExtensionRegistry } from "../extensions/registry.js";
 import type { ResolvedLinkFeature } from "./link-features.js";
 import { hashParts } from "./cache.js";
 import { findRuntimeLibrary } from "./runtime-lib.js";
-import { compileC, optimizationFlags, RUNTIME_CFLAGS, type PgoMode, type Runner } from "./toolchain.js";
+import { compileC, optimizationFlags, RUNTIME_CFLAGS, sysrootFlags, type PgoMode, type Runner } from "./toolchain.js";
 import { COMPILER_VERSION } from "./version.js";
 
 /** Core runtime translation units (each compiled and cached independently). */
@@ -51,6 +51,12 @@ export interface RuntimeObjects {
   readonly featureObjects: readonly string[];
   /** Pre-built C++/Rust objects and archives contributed by native extensions. */
   readonly nativeObjects: readonly string[];
+  /**
+   * The prebuilt `core`/`ext_<name>` archives this link used. Empty when the
+   * runtime was compiled from source. The driver retries a failed link without
+   * them, so it has to know whether the first attempt used any.
+   */
+  readonly prebuiltArchives: readonly string[];
 }
 
 export interface RuntimeObjectsOptions {
@@ -61,11 +67,16 @@ export interface RuntimeObjectsOptions {
   readonly registry: ExtensionRegistry;
   readonly preferPrebuilt: boolean;
   readonly env: Record<string, string>;
+  /** macOS SDK for `-isysroot`; part of the object cache key. */
+  readonly sdkRoot?: string;
   readonly lto: boolean;
   readonly pgo: PgoMode | undefined;
   readonly pgoDir: string;
   /** Optional link features selected for this program. */
   readonly features?: readonly ResolvedLinkFeature[];
+  /** Override the folders searched for prebuilt archives (defaults to the
+   * runtime's `lib/<os>-<arch>` plus the installed platform package). */
+  readonly runtimeLibDirs?: readonly string[];
 }
 
 /**
@@ -79,6 +90,9 @@ export interface RuntimeObjectsOptions {
 export function ensureRuntimeObjects(options: RuntimeObjectsOptions): RuntimeObjects {
   const { runner, clang, runtimeDir, cacheDir, registry, preferPrebuilt, env, lto, pgo, pgoDir } = options;
   const optimization = optimizationFlags(lto, pgo, pgoDir);
+  /* The sysroot joins the extra flags (and therefore the cache key): objects
+     compiled against a different SDK are a different artifact. */
+  const compileFlags = [...optimization, ...sysrootFlags(options.sdkRoot)];
   /* Runtime objects depend on the shared headers (rt.h/rt_internal.h/...) and
      the `#include`d implementation fragments (`.inc`), so any change to them
      must invalidate every cached object. Hash them all. */
@@ -99,7 +113,7 @@ export function ensureRuntimeObjects(options: RuntimeObjectsOptions): RuntimeObj
       "runtime",
       COMPILER_VERSION,
       RUNTIME_CFLAGS.join(" "),
-      optimization.join(" "),
+      compileFlags.join(" "),
       tag,
       headerStamp,
       body,
@@ -108,24 +122,30 @@ export function ensureRuntimeObjects(options: RuntimeObjectsOptions): RuntimeObj
     ]);
     const objectPath = join(cacheDir, `${tag}-${key}.o`);
     if (!existsSync(objectPath)) {
-      compileC(runner, clang, sourcePath, objectPath, runtimeDir, env, optimization);
+      compileC(runner, clang, sourcePath, objectPath, runtimeDir, env, compileFlags);
     }
     return objectPath;
   };
 
-  const coreArchive = preferPrebuilt ? findRuntimeLibrary("core") : undefined;
+  const coreArchive = preferPrebuilt ? findRuntimeLibrary("core", options.runtimeLibDirs) : undefined;
   const runtimeObjects = coreArchive
     ? [coreArchive]
     : RUNTIME_SOURCES.map((source) => compileOne(join(runtimeDir, source), basename(source, ".c")));
 
+  /** Prebuilt archives this link uses; the driver retries without them. */
+  const prebuiltArchives: string[] = coreArchive ? [coreArchive] : [];
+
   const extensionObjects: string[] = [];
   const seen = new Set<string>();
   for (const extension of registry.all()) {
     const sources = extension.runtimeSources ? extension.runtimeSources() : [];
     if (sources.length === 0) continue;
-    const archive = preferPrebuilt ? findRuntimeLibrary(`ext_${extension.name}`) : undefined;
+    const archive = preferPrebuilt
+      ? findRuntimeLibrary(`ext_${extension.name}`, options.runtimeLibDirs)
+      : undefined;
     if (archive) {
       extensionObjects.push(archive);
+      prebuiltArchives.push(archive);
       continue;
     }
     for (const sourcePath of sources) {
@@ -156,5 +176,6 @@ export function ensureRuntimeObjects(options: RuntimeObjectsOptions): RuntimeObj
     extensionObjects,
     featureObjects: [...new Set(featureObjects)],
     nativeObjects: [...new Set(registry.nativeObjects())],
+    prebuiltArchives,
   };
 }

package/src/driver/toolchain-provider.ts

@@ -22,11 +22,17 @@
  * skipped (or rejected, when named explicitly) instead of producing objects
  * the linker cannot mix.
  *
+ * On macOS the resolved driver also carries the SDK as `sdkRoot`, which the
+ * compile and link steps pass as `-isysroot` (see `macos-sdk.ts`): an Apple
+ * clang invoked by absolute path does not infer the SDK by itself, and without
+ * one not even `<stdio.h>` — nor the linker's `libm` stub — is found.
+ *
  * Extra linker arguments (for example `-fuse-ld=lld`) can be supplied through
  * `xbintsc_LINKER_ARGS`.
  */
 
 import { locateClang, realRunner, type ClangVersion, type Runner } from "./toolchain.js";
+import { macosSdkRoot } from "./macos-sdk.js";
 
 export type ToolchainSource = "env" | "system";
 
@@ -42,6 +48,9 @@ export interface ResolvedToolchain {
   /** Extra environment for the toolchain subprocesses, merged over the current
    * environment. */
   readonly env: Record<string, string>;
+  /** macOS SDK to pass as `-isysroot`; lost off macOS or when `SDKROOT` is
+   * already set. See `macos-sdk.ts`. */
+  readonly sdkRoot?: string;
 }
 
 function linkerArgs(fallback: readonly string[]): string[] {
@@ -53,11 +62,13 @@ function linkerArgs(fallback: readonly string[]): string[] {
 /** Resolve the toolchain that `build` should use. See the module docblock. */
 export function resolveToolchain(runner: Runner = realRunner): ResolvedToolchain {
   const location = locateClang(runner);
+  const sdkRoot = macosSdkRoot(runner);
   return {
     clang: location.command,
     source: location.source,
     ...(location.version ? { version: location.version } : {}),
     linkerArgs: linkerArgs([]),
     env: {},
+    ...(sdkRoot === undefined ? {} : { sdkRoot }),
   };
 }