Migrate Linux Docker builds to .NET official cross-compilation images

.agents/skills/issue-fix/SKILL.md

@@ -282,10 +282,10 @@ When a bug affects one platform but not another, **build both platforms locally*
 
 ```bash
 # Build x64 native (in Docker)
-bash ./scripts/infra/native/linux/docker/debian/11/build-local.sh
+bash ./scripts/infra/native/linux/docker/glibc/build-local.sh x64
 
 # Build ARM64 cross-compile (in Docker)
-bash ./scripts/infra/native/linux/docker/debian/11/build-local.sh arm64 10
+bash ./scripts/infra/native/linux/docker/glibc/build-local.sh arm64
 
 # Compare DT_NEEDED entries (the linked libraries)
 docker run --rm -v $(pwd):/work debian:bookworm-slim bash -c \

.agents/skills/security-audit/references/cg-alerts.md

@@ -125,8 +125,9 @@ az devops invoke --area build --resource logs \
 
 | Category | Source | Fix Mechanism |
 |----------|--------|---------------|
-| Alpine sysroot packages | `apk add` in alpine Dockerfile | Bump `DISTRO_VERSION` in Dockerfile |
-| Debian base image packages | `apt-get` / base image | Update base image or wait for Debian patches |
+| Alpine sysroot packages | `apk.static add` in alpine Dockerfile (fontconfig) | Bump `ALPINE_VERSION` in `alpine/Dockerfile` |
+| Ubuntu/Debian .deb packages | SHA-pinned fontconfig .debs in glibc Dockerfiles | Bump `FC_VERSION` + new SHA-256 in `glibc/Dockerfile` or `glibc-x86/Dockerfile` |
+| .NET cross base image | `mcr.microsoft.com/dotnet-buildtools/prereqs:azurelinux-3.0-net10.0-cross-*` | Bump the .NET image tag (controlled by .NET infra team) |
 | npm build tooling | .NET SDK / Cake dependencies | Update .NET SDK or pin versions |
 | Rust crate deps | .NET SDK internals | Update .NET SDK |
 | NuGet build deps | Build-time references | Update package version |
@@ -135,10 +136,10 @@ az devops invoke --area build --resource logs \
 
 | File | Controls |
 |------|----------|
-| `scripts/infra/native/linux/docker/alpine/Dockerfile` (lines 43–47) | Alpine sysroot version (`DISTRO_VERSION`) |
-| `scripts/infra/native/linux/docker/debian/11/Dockerfile` | Debian 11 base image (EOL June 2026) |
-| `scripts/infra/native/linux/docker/debian/13/Dockerfile` | Debian 13 base image |
-| `scripts/infra/native/linux/docker/bionic/Dockerfile` | Bionic/Android cross-compile |
+| `scripts/infra/native/linux/docker/glibc/Dockerfile` | Glibc cross images (arm, arm64, x64, riscv64, loongarch64) — pinned fontconfig .debs + .NET SDK version |
+| `scripts/infra/native/linux/docker/glibc-x86/Dockerfile` | x86 self-contained build (libc++ stage + fontconfig) |
+| `scripts/infra/native/linux/docker/alpine/Dockerfile` | Musl/Alpine cross images — `ALPINE_VERSION` (look for `ARG ALPINE_VERSION`) controls fontconfig source |
+| `scripts/infra/native/linux/docker/bionic/Dockerfile` | Bionic/Android cross-compile (NDK detected dynamically) |
 | `scripts/infra/native/wasm/docker/Dockerfile` | WASM build container |
 
 ## Including CG Data in the Report

documentation/dev/building-linux.md

@@ -82,12 +82,12 @@ Building for different Linux distributions is easier with Docker. The repository
 
 ```bash
 # Build the Docker image
-cd scripts/infra/native/linux/docker/alpine/amd64
-docker build --tag skiasharp-alpine .
+cd scripts/infra/native/linux/docker/alpine
+docker build --tag skiasharp-alpine --build-arg BUILD_ARCH=x64 .
 
 # Run the build
 docker run --rm --name skiasharp-alpine --volume $(pwd):/work skiasharp-alpine \
-    /bin/bash ./bootstrapper.sh -t externals-linux --variant=alpine --buildarch=x64
+    /bin/bash -c "dotnet tool restore && dotnet cake --target=externals-linux-clang-cross --buildarch=x64 --variant=alpine"
 
 # Fix file ownership if needed
 chown -R $(id -u):$(id -g) .

documentation/dev/debugging-methodology.md

@@ -188,7 +188,7 @@ grep "libs = " externals/skia/out/linux/arm64/obj/SkiaSharp.ninja
 
 # Check if library exists in cross-compile sysroot
 docker run --rm skiasharp-linux-gnu-cross-arm64 bash -c \
-  "ls -la /usr/aarch64-linux-gnu/lib/libfontconfig*"
+  "source /etc/skia-env && ls -la \${SYSROOT_ROOT}/usr/lib/aarch64-linux-gnu/libfontconfig*"
 ```
 
 **Common issue:** The `-dev` package provides a broken symlink (`libfoo.so -> libfoo.so.1.2.3`)
@@ -199,7 +199,7 @@ but the actual `.so.1.2.3` file is in the runtime package (`libfoo1`), not the d
 | Root Cause | Fix Location |
 |------------|--------------|
 | Library missing from linker flags | `native/linux/build.cake` or `externals/skia/third_party/BUILD.gn` |
-| Library missing from cross-compile sysroot | `scripts/infra/native/linux/docker/debian/*/Dockerfile` |
+| Library missing from cross-compile sysroot | `scripts/infra/native/linux/docker/{glibc,glibc-x86,alpine,bionic}/Dockerfile` |
 | Indirect dependency (A→B→C missing) | Fix B's linkage or add C explicitly |
 
 ### Real Example: ARM64 fontconfig issue (#3369)

native/linux-clang-cross/build.cake

@@ -5,35 +5,64 @@ DirectoryPath ROOT_PATH = MakeAbsolute(Directory("../.."));
 string TOOLCHAIN_ARCH = Argument("toolchainArch", EnvironmentVariable("TOOLCHAIN_ARCH"));
 string TOOLCHAIN_ARCH_SHORT = Argument("toolchainArchShort", EnvironmentVariable("TOOLCHAIN_ARCH_SHORT"));
 string TOOLCHAIN_ARCH_TARGET = Argument("toolchainArchTarget", EnvironmentVariable("TOOLCHAIN_ARCH_TARGET"));
+string SYSROOT_PATH = Argument("sysrootPath", EnvironmentVariable("SYSROOT_PATH"));
+string SYSROOT_ROOT = Argument("sysrootRoot", EnvironmentVariable("SYSROOT_ROOT") ?? "");
+string GCC_LIB_DIR = Argument("gccLibDir", EnvironmentVariable("GCC_LIB_DIR") ?? "");
+
+if (string.IsNullOrEmpty(SYSROOT_PATH))
+    throw new Exception("FATAL: SYSROOT_PATH is not set. Expected from /etc/skia-env in the cross-compile Docker image.");
+if (string.IsNullOrEmpty(SYSROOT_ROOT))
+    throw new Exception("FATAL: SYSROOT_ROOT is not set. Expected from /etc/skia-env in the cross-compile Docker image.");
+if (string.IsNullOrEmpty(GCC_LIB_DIR))
+    throw new Exception("FATAL: GCC_LIB_DIR is not set. Expected from /etc/skia-env in the cross-compile Docker image.");
 
 Information("Toolchain:");
 Information($"    Arch:                          {TOOLCHAIN_ARCH} ({TOOLCHAIN_ARCH_SHORT})");
 Information($"    Target                         {TOOLCHAIN_ARCH_TARGET}");
+Information($"    Sysroot:                       {SYSROOT_PATH}");
+Information($"    Sysroot Root:                  {SYSROOT_ROOT}");
+Information($"    GCC Lib Dir:                   {GCC_LIB_DIR}");
 
 if (BUILD_ARCH.Length == 0)
     BUILD_ARCH = new [] { "arm" };
 
 string GetGnArgs(string arch)
 {
-    var (sysrootArg, linker) = BUILD_VARIANT switch
+    var sysrootArg = BUILD_VARIANT switch
     {
-        "alpine" or "alpinenodeps" => ("'--sysroot=/alpine', ", "'-fuse-ld=lld'"),
-        _ => ("", ""),
+        _ when !string.IsNullOrEmpty(SYSROOT_ROOT) => $"'--sysroot={SYSROOT_ROOT}', ",
+        _ => "",
     };
+    var linker = "'-fuse-ld=lld'";
 
-    var sysroot = $"/usr/{TOOLCHAIN_ARCH}";
+    var sysroot = SYSROOT_PATH;
     var init = $"{sysrootArg} '--target={TOOLCHAIN_ARCH_TARGET}'";
-    var bin = $"'-B{sysroot}/bin/' ";
-    var libs = $"'-L{sysroot}/lib/' ";
-    var includes =
-        $"'-I{sysroot}/include', " +
-        $"'-I{sysroot}/include/c++/current', " +
-        $"'-I{sysroot}/include/c++/current/{TOOLCHAIN_ARCH}' ";
+    var bin = $"'-B{sysroot}/bin/', '-B{sysroot}/lib/', '-B{sysroot}/lib64/' ";
+    var libs = $"'-L{sysroot}/lib/', '-L{sysroot}/lib64/', '-L{sysroot}/lib/{TOOLCHAIN_ARCH}/' ";
+    // Add GCC library directory for CRT files (crtbeginS.o) and libgcc
+    if (!string.IsNullOrEmpty(GCC_LIB_DIR))
+        libs += $", '-L{GCC_LIB_DIR}/', '-B{GCC_LIB_DIR}/' ";
+    // C++ headers MUST come before C headers for #include_next to work correctly.
+    // When <cmath> does #include_next <math.h>, the search continues from paths
+    // AFTER the directory where cmath was found. If C headers are listed first,
+    // they won't be searched by #include_next from C++ headers.
+    //
+    // All cross-images have libc++ headers installed at c++/v1/. Clang finds them
+    // automatically via -stdlib=libc++ — we only need the C system include paths.
+    var includes = $"'-I{sysroot}/include', " +
+                   $"'-I{sysroot}/include/{TOOLCHAIN_ARCH}' ";
+
+    // All cross-images provide libc++.a built with -DLIBCXX_CXX_ABI=libstdc++.
+    // This means libc++ delegates ABI symbols (operator delete, __cxa_throw, etc.)
+    // to GCC's libstdc++. We link libstdc++ with --whole-archive so its symbols are
+    // available before GN's object archives reference them (extra_ldflags appear first
+    // in the link command). -Wl bypasses clang's driver rewrite of -lstdc++ → -lc++.
+    var abiLib = "'-Wl,--whole-archive,-lstdc++,--no-whole-archive'";
 
     return
         $"extra_asmflags+=[ {init}, '-no-integrated-as', {bin}, {includes} ] " +
         $"extra_cflags+=[ {init}, {bin}, {includes} ] " +
-        $"extra_ldflags+=[ {init}, {bin}, {libs}, {linker} ] " +
+        $"extra_ldflags+=[ {init}, {bin}, {libs}, {abiLib}, {linker} ] " +
         ADDITIONAL_GN_ARGS;
 }
 

native/linux/build.cake

@@ -91,9 +91,14 @@ Task("libSkiaSharp")
         // Bionic (Android NDK) builds need SK_BUILD_FOR_UNIX to prevent the
         // NDK's __ANDROID__ define from suppressing SkDebugf (stdio port).
         // Fontconfig is not available on Bionic.
+        // The Android NDK ships libc++ as both static and shared — without
+        // -static-libstdc++ clang would pick libc++_shared.so as a runtime dep
+        // that we don't bundle. The .NET glibc/musl cross-images ship libc++
+        // static-only, so this flag is a no-op there but doesn't hurt.
         var isBionic = VARIANT.ToLower().StartsWith("bionic");
         var bionicDefine = isBionic ? ", '-DSK_BUILD_FOR_UNIX'" : "";
         var bionicArgs = isBionic ? "skia_use_fontconfig=false " : "";
+        var staticLibcxx = isBionic ? ", '-static-libstdc++'" : "";
 
         GnNinja($"{VARIANT}/{arch}", "SkiaSharp",
             $"target_os='linux' " +
@@ -112,8 +117,8 @@ Task("libSkiaSharp")
             $"skia_use_vulkan=true " +
             bionicArgs +
             $"extra_asmflags=[] " +
-            $"extra_cflags=[ '-DSKIA_C_DLL', '-DHAVE_SYSCALL_GETRANDOM', '-DXML_DEV_URANDOM'{spectreFlags}{wordSizeDefine}{bionicDefine} ] " +
-            $"extra_ldflags=[ '-static-libstdc++', '-static-libgcc', '-Wl,--version-script={map}' ] " +
+            $"extra_cflags=[ '-DSKIA_C_DLL', '-DHAVE_SYSCALL_GETRANDOM', '-DXML_DEV_URANDOM', '-stdlib=libc++'{spectreFlags}{wordSizeDefine}{bionicDefine} ] " +
+            $"extra_ldflags=[ '-stdlib=libc++', '-static-libgcc'{staticLibcxx}, '-Wl,--version-script={map}' ] " +
             COMPILERS +
             $"linux_soname_version='{soname}' " +
             ADDITIONAL_GN_ARGS);
@@ -137,6 +142,9 @@ Task("libHarfBuzzSharp")
         if (Skip(arch)) return;
 
         var skiaArch = GetSkiaArch(arch);
+        var isBionicHB = VARIANT.ToLower().StartsWith("bionic");
+        var bionicDefineHB = isBionicHB ? ", '-DSK_BUILD_FOR_UNIX'" : "";
+        var staticLibcxxHB = isBionicHB ? ", '-static-libstdc++'" : "";
 
         var soname = GetVersion("HarfBuzz", "soname");
         var map = MakeAbsolute((FilePath)"libHarfBuzzSharp/libHarfBuzzSharp.map");
@@ -146,8 +154,8 @@ Task("libHarfBuzzSharp")
             $"target_cpu='{skiaArch}' " +
             $"visibility_hidden=false " +
             $"extra_asmflags=[] " +
-            $"extra_cflags=[ {(VARIANT.ToLower().StartsWith("bionic") ? "'-DSK_BUILD_FOR_UNIX'" : "")} ] " +
-            $"extra_ldflags=[ '-static-libstdc++', '-static-libgcc', '-Wl,--version-script={map}' ] " +
+            $"extra_cflags=[ '-stdlib=libc++'{bionicDefineHB} ] " +
+            $"extra_ldflags=[ '-stdlib=libc++', '-static-libgcc'{staticLibcxxHB}, '-Wl,--version-script={map}' ] " +
             COMPILERS +
             $"linux_soname_version='{soname}' " +
             ADDITIONAL_GN_ARGS);

scripts/azure-templates-stages-native-linux.yml

@@ -27,27 +27,36 @@ stages:
               additionalArgs: --verifyExcluded=fontconfig
               gnArgs: skia_use_fontconfig=false
           matrix:
-            # Debian 13 / Trixie (gcc-14, glibc 2.38) - for archs that
-            # never had release-arch packages in Bullseye OR Bookworm:
-            #   - loongarch64 (LoongArch port; not in Bullseye/Bookworm main,
-            #                  first release arch in Trixie)
-            - ${{ each arch in split('loongarch64', ',') }}:
-              - arch: ${{ arch }}
-                docker: scripts/infra/native/linux/docker/debian/13
-                target: externals-linux-clang-cross
-                additionalArgs: --verifyGlibcMax=2.38
-            # Debian 11 / Bullseye (gcc-10, glibc 2.31). riscv64 is a
-            # carve-out: Bullseye has no riscv64 binary archive but ships
-            # gcc-10-cross packages that contain a riscv64 sysroot at
-            # glibc 2.31. The image installs those instead of LLVM
-            # multiarch packages and the build links libstdc++/libgcc
-            # statically - keeps glibc parity with the other archs.
-            - ${{ each arch in split('arm,arm64,x86,x64,riscv64', ',') }}:
-              - arch: ${{ arch }}
-                docker: scripts/infra/native/linux/docker/debian/11
-                target: externals-linux-clang-cross
-                additionalArgs: --verifyGlibcMax=2.31
-            - ${{ each arch in split('arm,arm64,x64,riscv64,loongarch64', ',') }}: # removed x86 as it is having issues building
+            # .NET official cross images (glibc)
+            # verifyGlibcMax ensures we detect if the base image bumps its sysroot
+            - arch: arm64
+              docker: scripts/infra/native/linux/docker/glibc
+              target: externals-linux-clang-cross
+              additionalArgs: --verifyGlibcMax=2.27
+            # x86 needs libc++ built first (the .NET team doesn't ship it for x86).
+            # Uses a separate directory with a self-contained Dockerfile (multi-stage).
+            - arch: x86
+              docker: scripts/infra/native/linux/docker/glibc-x86
+              target: externals-linux-clang-cross
+              additionalArgs: --verifyGlibcMax=2.27
+            - arch: arm
+              docker: scripts/infra/native/linux/docker/glibc
+              target: externals-linux-clang-cross
+              additionalArgs: --verifyGlibcMax=2.35
+            - arch: x64
+              docker: scripts/infra/native/linux/docker/glibc
+              target: externals-linux-clang-cross
+              additionalArgs: --verifyGlibcMax=2.27
+            - arch: riscv64
+              docker: scripts/infra/native/linux/docker/glibc
+              target: externals-linux-clang-cross
+              additionalArgs: --verifyGlibcMax=2.39
+            - arch: loongarch64
+              docker: scripts/infra/native/linux/docker/glibc
+              target: externals-linux-clang-cross
+              additionalArgs: --verifyGlibcMax=2.42
+            # .NET official cross images (musl/Alpine)
+            - ${{ each arch in split('arm,arm64,x64,riscv64,loongarch64', ',') }}:
               - arch: ${{ arch }}
                 variant: alpine
                 docker: scripts/infra/native/linux/docker/alpine

scripts/infra/native/linux/docker/alpine/.dockerignore

@@ -1 +1,4 @@
-build-local.sh
+# Only send Dockerfile and startup.sh to the Docker daemon.
+*
+!Dockerfile
+!startup.sh