build-script: opt-in build.sysroot directive in package.yml

Adds a `build.sysroot:` block to the package.yml schema that, when
set, redirects the compiler at a specific glibc / kernel-headers
bottle (instead of using the build host's libc). This is the
hermetic-build / host-independent piece needed for the pantry to
target manylinux baselines, build on Alpine-musl hosts, and produce
bottles that don't carry the build runner's libc ABI assumptions.

YAML schema:

    build:
      sysroot:
        libc: gnu.org/glibc=~2.28               # required
        kernel-headers: kernel.org/linux-headers=^7   # optional
      dependencies:
        gnu.org/glibc: ~2.28      # MUST also be a build dep
        kernel.org/linux-headers: ^7  # MUST also be a build dep

When `build.sysroot.libc` is set, the generated build script exports:

    SYSROOT=<libc-install-prefix>
    CC="${CC:-gcc} -nostdinc -isystem <libc>/include [-isystem <khdr>/include] -B <libc>/lib -Wl,--enable-new-dtags,--dynamic-linker=<libc>/lib/ld-linux-*.so.*,--rpath=<libc>/lib"
    CXX="${CXX:-g++} <same> -nostdinc++"
    CPP="${CPP:-gcc} <same> -E"

The libc package must already be a `build.dependencies` entry (so
it's installed and resolved); this directive merely routes existing
deps, it doesn't add them. Same constraint for `kernel-headers`.

No behaviour change for recipes that don't declare `build.sysroot:` —
the helper returns an empty string and no env exports are emitted.

This is the brewkit half of the feature; the pantry yaml schema docs
need a companion update (will land in a pkgxdev/pantry PR).

Empirical motivation: pkgxdev/pantry#12968 (gnu.org/glibc) and the
HPC-cascade work in pkgm/notes/session-2026-05-{19,20}.md. We
demonstrated that this exact sysroot routing pattern (done manually
inside Docker containers) enables building glibc 2.17–2.43 host-
independent on both linux/x86-64 and linux/aarch64 from a clean
debian:bookworm-slim with no apt-installed compiler. Formalising it
in the recipe schema unblocks the rest of the pantry to follow the
same hermetic-build path.

Author: tannevaled

lib/porcelain/build-script.ts

@@ -17,6 +17,15 @@ export default async function(config: Config, PATH?: Path): Promise<string> {
   }
   const user_script = await usePantry().getScript(config.pkg, 'build', config.deps.gas, config)
 
+  // Sysroot routing — opt-in via `build.sysroot:` in package.yml.
+  // When set, redirects the compiler at a specific glibc / kernel-headers
+  // bottle (instead of the build host's libc). Lines emitted into the
+  // generated script export CC / CXX / CPP / SYSROOT before the user
+  // script runs, so recipes don't need to know the paths themselves.
+  // Empty string when the yaml has no `build.sysroot` block — no
+  // behaviour change for existing recipes.
+  const sysroot_env = await sysroot_block(config)
+
   const pkgx = find_in_PATH('pkgx')
   const bash = find_in_PATH('bash')
   const gum = find_in_PATH('gum')
@@ -71,6 +80,7 @@ export default async function(config: Config, PATH?: Path): Promise<string> {
       fi
       mkdir -p $HOME
       ${FLAGS.join('\n  ')}
+      ${sysroot_env}
 
       env -u GH_TOKEN -u GITHUB_TOKEN
 
@@ -82,6 +92,71 @@ export default async function(config: Config, PATH?: Path): Promise<string> {
     `
 }
 
+/// Emit `export CC=… CXX=… CPP=… SYSROOT=…` if the package.yml has a
+/// `build.sysroot` block. Resolves the libc bottle from the package's
+/// installed deps so the recipe doesn't need to know the absolute path.
+///
+/// YAML schema:
+///   build:
+///     sysroot:
+///       libc: gnu.org/glibc=~2.28           # required
+///       kernel-headers: kernel.org/linux-headers=^7   # optional
+///
+/// The libc package must already be a build dependency of the recipe
+/// (so it's installed and available in config.deps); this directive
+/// doesn't add a dep, just routes the compiler at it. Same for the
+/// kernel headers when set.
+async function sysroot_block(config: Config): Promise<string> {
+  const yml = await usePantry().project(config.pkg).yaml() as Record<string, unknown>
+  const build = yml.build as Record<string, unknown> | undefined
+  const sysroot = build?.sysroot as Record<string, unknown> | undefined
+  if (!sysroot) return ''
+
+  const want_libc = sysroot.libc as string | undefined
+  if (!want_libc) {
+    console.warn("build.sysroot present but no libc — skipping")
+    return ''
+  }
+  const libc_project = want_libc.split(/[=<>~^]/)[0]
+  const libc_install = config.deps.gas.find(i => i.pkg.project === libc_project)
+  if (!libc_install) {
+    throw new Error(`build.sysroot.libc='${want_libc}' but ${libc_project} is not in the resolved deps — declare it as a build.dependencies entry`)
+  }
+
+  const want_khdr = sysroot['kernel-headers'] as string | undefined
+  const khdr_path: string | undefined = want_khdr
+    ? (() => {
+        const proj = want_khdr.split(/[=<>~^]/)[0]
+        const inst = config.deps.gas.find(i => i.pkg.project === proj)
+        if (!inst) throw new Error(`build.sysroot.kernel-headers='${want_khdr}' not in resolved deps`)
+        return inst.path.string
+      })()
+    : undefined
+
+  const ldso = (() => {
+    switch (host().arch) {
+      case 'x86-64':  return 'ld-linux-x86-64.so.2'
+      case 'aarch64': return 'ld-linux-aarch64.so.1'
+      default: throw new Error(`sysroot directive unsupported on ${host().arch}`)
+    }
+  })()
+
+  const libc = libc_install.path.string
+  const isystems = [
+    `-isystem ${libc}/include`,
+    khdr_path ? `-isystem ${khdr_path}/include` : null,
+  ].filter(Boolean).join(' ')
+  const wrap = `-nostdinc ${isystems} -B ${libc}/lib -Wl,--enable-new-dtags,--dynamic-linker=${libc}/lib/${ldso},--rpath=${libc}/lib`
+
+  return undent`
+      # sysroot routing (build.sysroot in package.yml)
+      export SYSROOT=${libc}
+      export CC="\${CC:-gcc} ${wrap}"
+      export CXX="\${CXX:-g++} ${wrap} -nostdinc++"
+      export CPP="\${CPP:-gcc} ${wrap} -E"
+  `
+}
+
 function flags(): string[] {
   const {platform, arch} = host()
   const is_linux_x86_64 = platform == 'linux' && arch == 'x86-64'