chore(nix): unify Linux cross-compilation toolchains

.github/workflows/branch-checks.yml

@@ -120,7 +120,7 @@ jobs:
           - runner: macos-15-xlarge
             system: aarch64-darwin
     runs-on: ${{ matrix.runner }}
-    timeout-minutes: 30
+    timeout-minutes: 300
     defaults:
       run:
         shell: nix develop .#devShells.${{ matrix.system }}.default -c bash -euo pipefail {0}
@@ -138,7 +138,7 @@ jobs:
 
       - name: Realize Nix development shell
         shell: bash
-        run: nix build --no-link ".#devShells.${{ matrix.system }}.default"
+        run: nix build -L --no-link ".#devShells.${{ matrix.system }}.default"
 
       - name: Cache Rust target and registry
         uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
@@ -197,6 +197,54 @@ jobs:
             exit 1
           fi
 
+  macos-cross:
+    name: macOS cross (${{ matrix.target }})
+    needs: pr_metadata
+    if: needs.pr_metadata.outputs.should_run == 'true'
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - x86_64-unknown-linux-gnu
+          - aarch64-unknown-linux-gnu
+          - x86_64-unknown-linux-musl
+          - aarch64-unknown-linux-musl
+    runs-on: macos-15-xlarge
+    timeout-minutes: 300
+    defaults:
+      run:
+        shell: nix develop .#devShells.aarch64-darwin.default -c bash -euo pipefail {0}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: cachix/install-nix-action@13d8dd58da0234aa297dedd986986ccb8e7f3e24 # v31.11.1
+        with:
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: cachix/cachix-action@5f2d7c5294214f71b873db4b969586b980625e71 # v17
+        with:
+          name: openshell
+          authToken: ${{ secrets.CACHIX_AUTH_TOKEN }}
+
+      - name: Realize Nix development shell
+        shell: bash
+        run: nix build -L --no-link .#devShells.aarch64-darwin.default
+
+      - name: Cache Rust target and registry
+        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+        with:
+          shared-key: macos-cross-${{ matrix.target }}
+          cache-on-failure: "true"
+          cache-workspace-crates: "true"
+          cache-bin: "false"
+          cmd-format: nix develop .#devShells.aarch64-darwin.default -c {0}
+
+      - name: Build workspace
+        run: cargo build --locked --workspace --target ${{ matrix.target }}
+
+      - name: Compile Linux tests
+        run: cargo test --locked --no-run --workspace --features openshell-server/test-support --target ${{ matrix.target }}
+
   python:
     name: Python (${{ matrix.runner }})
     needs: pr_metadata

architecture/build.md

@@ -147,6 +147,20 @@ in platform-specific Nix development shells through reusable workflows and the
 shared `build-rust-binary` action. The image build downloads each binary artifact
 into the staging directory before running Buildx.
 
+The Nix flake exposes one development shell with target-specific toolchains.
+Each toolchain supplies its compiler driver, assembler, archiver, native
+libraries, and Cargo environment through derivation passthru. The shell omits
+an implicit host C compiler; Cargo builds select the appropriate tools with
+`--target`. GNU targets use a glibc 2.28 sysroot and static GCC runtimes, while
+musl targets produce static executables.
+
+On macOS, the shell also provides a native Darwin toolchain with static Z3
+and AWS-LC. Its Clang driver uses the pinned, unprocessed Apple SDK so system
+library stubs, including libiconv and libc++, retain their Apple install names.
+System libraries and frameworks remain dynamically linked. The deployment
+target matches the Nix host platform's minimum macOS version. The Rust toolchain
+does not propagate Nix's replacement system libraries into the link environment.
+
 Gateway and supervisor binaries staged into branch E2E, Release Dev, and Release
 Tag images are compiled through `cargo auditable` (pinned in `mise.toml`), which
 embeds a `.dep-v0` section describing the Rust dependencies actually compiled

flake.nix

@@ -69,9 +69,42 @@
           projectRootFile = "flake.nix";
           programs.nixfmt.enable = true;
         };
-        rustToolchain = pkgs.rust-bin.fromRustupToolchainFile ./rust-toolchain.toml;
-        z3-static = pkgs.callPackage ./nix/pkgs/z3-static.nix { };
-        aws-lc-static = pkgs.callPackage ./nix/pkgs/aws-lc-static.nix { };
+        rustToolchain =
+          ((pkgs.rust-bin.fromRustupToolchainFile ./rust-toolchain.toml).override {
+            targets = map (toolchain: toolchain.target) (builtins.attrValues toolchains);
+          }).overrideAttrs
+            {
+              propagatedBuildInputs = [ ];
+              depsHostHostPropagated = [ ];
+              depsTargetTargetPropagated = [ ];
+            };
+        buildInputs = { pkgs, stdenv }: [
+          (pkgs.callPackage ./nix/pkgs/z3.nix { inherit stdenv; })
+          (pkgs.callPackage ./nix/pkgs/aws-lc.nix { inherit stdenv; })
+        ];
+        toolchains = {
+          x86_64-gnu = pkgs.callPackage ./nix/toolchain {
+            pkgs = pkgs.pkgsCross.gnu64;
+            inherit buildInputs;
+          };
+          x86_64-musl = pkgs.callPackage ./nix/toolchain {
+            pkgs = pkgs.pkgsCross.musl64;
+            inherit buildInputs;
+          };
+          aarch64-gnu = pkgs.callPackage ./nix/toolchain {
+            pkgs = pkgs.pkgsCross.aarch64-multiplatform;
+            inherit buildInputs;
+          };
+          aarch64-musl = pkgs.callPackage ./nix/toolchain {
+            pkgs = pkgs.pkgsCross.aarch64-multiplatform-musl;
+            inherit buildInputs;
+          };
+        }
+        // pkgs.lib.optionalAttrs pkgs.stdenv.hostPlatform.isDarwin {
+          aarch64-darwin = pkgs.callPackage ./nix/toolchain/darwin.nix {
+            inherit buildInputs;
+          };
+        };
         vmRuntime = pkgs.callPackage ./nix/pkgs/vm-runtime.nix { };
         testGuest = import ./nix/test-guest {
           inherit pkgs;
@@ -85,31 +118,10 @@
 
         packages.vm-runtime = vmRuntime;
 
-        devShells = {
-          default =
-            (pkgs.mkShell.override {
-              stdenv =
-                if pkgs.stdenv.hostPlatform.isLinux then
-                  pkgs.stdenvAdapters.useMoldLinker pkgs.stdenv
-                else
-                  pkgs.stdenv;
-            })
-              {
-                packages = [
-                  rustToolchain
-                  z3-static
-                  aws-lc-static
-                ]
-                ++ commonDevShellPackages;
-              };
-        }
-        // pkgs.lib.optionalAttrs pkgs.stdenv.hostPlatform.isLinux {
-          glibc-2-28 = import ./nix/devShells/glibc-2-28.nix {
-            inherit pkgs rust-overlay commonDevShellPackages;
-          };
-          musl = import ./nix/devShells/musl.nix {
-            inherit pkgs rust-overlay commonDevShellPackages;
-          };
+        devShells.default = pkgs.mkShellNoCC {
+          packages = [ rustToolchain ] ++ commonDevShellPackages;
+
+          env = pkgs.lib.foldl' (env: toolchain: env // toolchain.env) { } (builtins.attrValues toolchains);
         };
 
         formatter = treefmtEval.config.build.wrapper;

nix/pkgs/aws-lc.nix

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+{
+  lib,
+  stdenv,
+  aws-lc,
+  buildEnv,
+  callPackage,
+}:
+
+let
+  strings = callPackage ../strings.nix { };
+  target = stdenv.hostPlatform.rust.cargoShortTarget;
+  package =
+    (aws-lc.override {
+      inherit stdenv;
+      useSharedLibraries = false;
+      withRustBindings = true;
+    }).overrideAttrs
+      (old: {
+        BINDGEN_EXTRA_CLANG_ARGS = "--target=${target}";
+        passthru = old.passthru // {
+          env.${strings.targetEnvVar target "AWS_LC_SYS_SYSTEM_DIR"} = "${libraries}";
+        };
+      });
+  libraries = buildEnv {
+    name = "${target}-aws-lc-libraries";
+    paths = [
+      (lib.getLib package)
+      (lib.getDev package)
+    ];
+    pathsToLink = [
+      "/include"
+      "/lib"
+      "/share/rust"
+    ];
+  };
+in
+package

nix/pkgs/z3-static.nix → nix/pkgs/z3.nix

@@ -1,12 +1,20 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-{ z3, stdenv }:
+{
+  lib,
+  stdenv,
+  z3,
+}:
 
 (z3.override {
   inherit stdenv;
   pythonBindings = false;
 }).overrideAttrs
   (old: {
-    cmakeFlags = old.cmakeFlags ++ [ "-DZ3_BUILD_LIBZ3_SHARED=OFF" ];
+    cmakeFlags = old.cmakeFlags ++ [
+      (lib.cmakeBool "Z3_BUILD_LIBZ3_SHARED" false)
+    ];
+    doCheck = false;
+    doInstallCheck = false;
   })

nix/strings.nix

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+{ lib }:
+
+let
+  targetSuffix = builtins.replaceStrings [ "-" ] [ "_" ];
+in
+{
+  targetEnvVar = target: name: "${name}_${targetSuffix target}";
+  cargoTargetEnvVar = target: name: "CARGO_TARGET_${lib.toUpper (targetSuffix target)}_${name}";
+}

nix/toolchain/darwin.nix

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+{
+  pkgs,
+  buildInputs,
+}:
+
+let
+  strings = pkgs.callPackage ../strings.nix { };
+  inherit (pkgs) stdenv;
+  target = stdenv.hostPlatform.rust.cargoShortTarget;
+  packages = buildInputs { inherit pkgs stdenv; };
+  # The processed Nix SDK removes system stubs such as libiconv and libc++.
+  sysroot = pkgs.apple-sdk.src;
+  toolchain = pkgs.callPackage ./driver.nix {
+    inherit sysroot;
+    compiler = "${stdenv.cc.cc}/bin/clang";
+    buildInputs = packages;
+  };
+in
+toolchain.overrideAttrs (old: {
+  passthru = (old.passthru or { }) // {
+    inherit target stdenv sysroot;
+    buildInputs = packages;
+    env = pkgs.lib.foldl' (env: package: env // (package.passthru.env or { })) { } packages // {
+      ${strings.cargoTargetEnvVar target "LINKER"} = "${toolchain}/bin/${target}-cc";
+      ${strings.targetEnvVar target "CC"} = "${toolchain}/bin/${target}-cc";
+      ${strings.targetEnvVar target "AS"} = "${stdenv.cc.bintools}/bin/as";
+      ${strings.targetEnvVar target "AR"} = "${stdenv.cc.bintools}/bin/ar";
+    };
+  };
+})