Migrate Apple native builds from Xcode projects to GN

Replace the hand-maintained Xcode projects for libSkiaSharp and
libHarfBuzzSharp with the existing GN `skiasharp_build` targets, matching
how Linux, Windows, WASM and Android already build.

- Delete all 6 *.xcodeproj bundles (ios/tvos/macos × both libs) and
  scripts/infra/native/apple/xcode.cake.
- Rewrite native/{ios,tvos,macos}/build.cake to drive GN/ninja only.
- Add scripts/infra/native/apple/apple.cake (CombineFrameworks, StripSign,
  RunLipo, RunZip) for the post-GN lipo/strip/codesign/zip steps.
- macOS ships a plain fat .dylib (@rpath/lib<N>.dylib); iOS/tvOS/MacCatalyst
  frameworks are emitted directly by GN with link-time framework-relative
  install_name and provenance-complete Info.plist; Cake only lipos per-arch
  frameworks together and strips/codesigns last.
- Bump externals/skia to pull in the GN-emits-framework support.
- Document the new flow in update-skia known-gotchas (#23).

Verified against the released 3.119.0 baseline on all four Apple platforms
(symbol counts 887 sk_/gr_ + 560 hb_, fat archs, framework-relative
install_name, valid codesign, Info.plist key parity). iOS simulator and
Mac Catalyst test suites pass 5548/0.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mattleibow

.agents/skills/update-skia/references/known-gotchas.md

@@ -61,6 +61,47 @@ The C API shims (`src/c/gr_context.cpp` etc.) compile as part of `:core`, but ba
 
 Upstream may move previously-core modules into separate optional targets. If the C API exposes functions from that module, add it as an explicit dependency of the `SkiaSharp` target in `BUILD.gn` rather than merging sources into core.
 
+### 23. Apple Builds Are Pure GN — GN Emits the `.framework`
+
+Every platform — Windows, Linux, WASM, Android, macOS, iOS, tvOS, and MacCatalyst — builds
+`libSkiaSharp`/`libHarfBuzzSharp` from the `skiasharp_build("SkiaSharp")` /
+`skiasharp_build("HarfBuzzSharp")` GN targets in `externals/skia/BUILD.gn`. There are **no Xcode
+project files** — the Apple `native/{ios,tvos,macos}/build.cake` tasks drive `gn`/`ninja` directly,
+exactly like the other platforms.
+
+On iOS/tvOS/MacCatalyst the GN build itself emits a complete single-arch `lib<Name>.framework` in
+its out dir — bundle layout, framework-relative install_name (set via link-time ldflags), arm64e
+thinning, and the provenance Info.plist (CFBundle* + DT*/BuildMachineOSBuild keys App Store /
+notarization validation expects) all come from GN. The framework path is keyed entirely off the
+**OS** — there are no separate `skiasharp_apple_framework*` GN args: the `skiasharp_build` template
+in `gn/BUILDCONFIG.gn` emits a framework whenever `is_ios` is true (iOS/tvOS/MacCatalyst), uses the
+macOS-style versioned `Versions/A` layout when `is_maccatalyst`, and the install_name ldflags in
+`BUILD.gn` are gated the same way. The single GN `action` runs
+`gn/skiasharp/assemble_apple_framework.py` (self-contained Python — it shells out only to first-party
+Apple tools `lipo`/`xcrun`/`xcodebuild`/`sw_vers` and writes the plist with `plistlib`). The cake
+`CombineFrameworks` helper (`scripts/infra/native/apple/apple.cake`) then only lipos the per-arch
+frameworks together and code-signs last. macOS ships a plain fat `.dylib` (install_name
+`@rpath/libSkiaSharp.dylib`, set by GN's solink rule) and does not call `CombineFrameworks`.
+
+What to do when updating Skia:
+
+- **Adding/removing a C API source file** (`src/c/*.cpp`): update the list in `gn/core.gni` — these
+  shims compile into `:core` (see gotcha #21), which `skiasharp_build` reaches via `:skia`, so the
+  same list feeds desktop, mobile, and Apple builds. `src/xamarin/*.cpp` sources live directly on the
+  `skiasharp_build("SkiaSharp")` target in `BUILD.gn`.
+- **Adding/removing a HarfBuzz source file**: update the `skiasharp_build("HarfBuzzSharp")` target.
+  Keep its defines (`HAVE_OT`, `HAVE_CONFIG_OVERRIDE_H`, `HB_NO_FALLBACK_SHAPE`) and the `HB_EXTERN`
+  visibility export (which publishes the `hb_*` symbols) intact.
+- **Changing a feature define or warning flag** (e.g. `SK_*`): set it on the GN target/config and it
+  applies everywhere, Apple included.
+- After any native change, rebuild from source per platform (`dotnet cake --target=externals-<plat>`);
+  `externals-download` is forbidden for native work.
+
+A full Xcode install is still required on macOS build agents (not just the Command Line
+Tools): GN drives the Apple SDK + clang toolchain, and the framework-assembly action shells
+out to `xcodebuild -version` and `xcrun --show-sdk-version` for the provenance `Info.plist`,
+which need a full, license-accepted Xcode. The build itself is otherwise pure `gn`/`ninja`.
+
 ## Dependencies & Bindings
 
 ### 8. DEPS: Fork-Customized Dependencies

build.cake

@@ -184,7 +184,6 @@ Task ("clean-externals")
     .Does (() =>
 {
     CleanDirectories("externals/skia/out");
-    CleanDirectories("externals/skia/xcodebuild");
     CleanDirectories("externals/angle");
     CleanDirectories("output/native");
     CleanDirectories("native/*/*/bin");

externals/skia

@@ -2,7 +2,7 @@ DirectoryPath ROOT_PATH = MakeAbsolute(Directory("../.."));
 DirectoryPath OUTPUT_PATH = MakeAbsolute(ROOT_PATH.Combine("output/native"));
 
 #load "../../scripts/infra/native/shared/native-shared.cake"
-#load "../../scripts/infra/native/apple/xcode.cake"
+#load "../../scripts/infra/native/apple/apple.cake"
 
 string VARIANT = (BUILD_VARIANT ?? "ios").ToLower();
 
@@ -14,109 +14,115 @@ string GetDeploymentTarget(string arch)
     }
 }
 
+string SkiaGnArgs(string skiaArch, string arch, bool isSim) =>
+    $"target_cpu='{skiaArch}' " +
+    $"target_os='{VARIANT}' " +
+    $"min_{VARIANT}_version='{GetDeploymentTarget(arch)}' " +
+    $"ios_use_simulator={(isSim ? "true" : "false")} " +
+    $"skia_use_harfbuzz=false " +
+    $"skia_use_icu=false " +
+    $"skia_use_metal=true " +
+    $"skia_use_piex=true " +
+    $"skia_use_system_expat=false " +
+    $"skia_use_system_libjpeg_turbo=false " +
+    $"skia_use_system_libpng=false " +
+    $"skia_use_system_libwebp=false " +
+    $"skia_use_system_zlib=false " +
+    $"skia_enable_skottie=true " +
+    $"extra_cflags=[ '-DSKIA_C_DLL', '-DHAVE_ARC4RANDOM_BUF' ] " +
+    ADDITIONAL_GN_ARGS;
+
 Task("libSkiaSharp")
     .IsDependentOn("git-sync-deps")
     .WithCriteria(IsRunningOnMacOs())
     .Does(() =>
 {
     if (VARIANT == "ios") {
-        Build("iphonesimulator", "x86_64", "x64");
-        Build("iphonesimulator", "arm64", "arm64");
-        Build("iphoneos", "arm64", "arm64");
-        // Build("iphoneos", "arm64", "arm64", "arm64e");
-
-        SafeCopy(
-            $"libSkiaSharp/bin/{CONFIGURATION}/iphonesimulator/x86_64.xcarchive",
-            OUTPUT_PATH.Combine($"ios/libSkiaSharp/x86_64.xcarchive"));
-
-        CreateFatFramework(OUTPUT_PATH.Combine("ios/libSkiaSharp"));
-        CreateFatFramework(OUTPUT_PATH.Combine("iossimulator/libSkiaSharp"));
+        var simX64 = Build("iphonesimulator", "x86_64", "x64");
+        var simArm64 = Build("iphonesimulator", "arm64", "arm64");
+        var deviceArm64 = Build("iphoneos", "arm64", "arm64");
+
+        // device framework (runtimes/ios): device-arm64 + legacy simulator-x86_64,
+        // the exact arch layout the published iOS NuGet expects. The device (iphoneos)
+        // framework is the base, so the shipped bundle advertises the device SDK.
+        CombineFrameworks(
+            OUTPUT_PATH.Combine("ios/libSkiaSharp.framework"),
+            new[] { deviceArm64, simX64 });
+
+        // simulator framework (runtimes/iossimulator): simulator-x86_64 + simulator-arm64.
+        CombineFrameworks(
+            OUTPUT_PATH.Combine("iossimulator/libSkiaSharp.framework"),
+            new[] { simX64, simArm64 });
     } else if (VARIANT == "maccatalyst") {
-        Build("macosx", "x86_64", "x64");
-        Build("macosx", "arm64", "arm64");
+        var x64 = Build("macosx", "x86_64", "x64");
+        var arm64 = Build("macosx", "arm64", "arm64");
 
-        CreateFatVersionedFramework(OUTPUT_PATH.Combine("maccatalyst/libSkiaSharp"));
+        CombineFrameworks(
+            OUTPUT_PATH.Combine("maccatalyst/libSkiaSharp.framework"),
+            new[] { x64, arm64 },
+            versioned: true);
     }
 
-    void Build(string sdk, string arch, string skiaArch, string xcodeArch = null)
+    DirectoryPath Build(string sdk, string arch, string skiaArch, string xcodeArch = null)
     {
-        if (Skip(arch)) return;
+        if (Skip(arch)) return null;
 
         xcodeArch = xcodeArch ?? arch;
         var isSim = sdk.EndsWith("simulator");
         var platform = VARIANT;
         if (VARIANT == "ios" && isSim)
             platform += "simulator";
 
-        GnNinja($"{platform}/{xcodeArch}", "skia modules/skottie",
-            $"target_cpu='{skiaArch}' " +
-            $"target_os='{VARIANT}' " +
-            $"min_{VARIANT}_version='{GetDeploymentTarget(arch)}' " +
-            $"ios_use_simulator={(isSim ? "true" : "false")} " +
-            $"skia_use_harfbuzz=false " +
-            $"skia_use_icu=false " +
-            $"skia_use_metal=true " +
-            $"skia_use_piex=true " +
-            $"skia_use_system_expat=false " +
-            $"skia_use_system_libjpeg_turbo=false " +
-            $"skia_use_system_libpng=false " +
-            $"skia_use_system_libwebp=false " +
-            $"skia_use_system_zlib=false " +
-            $"skia_enable_skottie=true " +
-            $"extra_cflags=[ '-DSKIA_C_DLL', '-DHAVE_ARC4RANDOM_BUF' ] " +
-            ADDITIONAL_GN_ARGS);
-
-        RunXCodeBuild("libSkiaSharp/libSkiaSharp.xcodeproj", "libSkiaSharp", sdk, xcodeArch, properties: new Dictionary<string, string> {
-            { $"{VARIANT.ToUpper()}_DEPLOYMENT_TARGET_VERSION", GetDeploymentTarget(arch) },
-            { $"SKIA_PLATFORM", platform },
-        });
-
-        SafeCopy(
-            $"libSkiaSharp/bin/{CONFIGURATION}/{sdk}/{xcodeArch}.xcarchive",
-            OUTPUT_PATH.Combine($"{platform}/libSkiaSharp/{xcodeArch}.xcarchive"));
+        // GN produces the complete single-arch lib*.framework (bundle layout, install_name,
+        // arm64e-thinned binary and provenance Info.plist) in its out dir; we only fuse the
+        // per-arch frameworks together afterwards.
+        GnNinja($"{platform}/{xcodeArch}", "SkiaSharp", SkiaGnArgs(skiaArch, arch, isSim));
+
+        return SKIA_PATH.Combine($"out/{platform}/{xcodeArch}/libSkiaSharp.framework");
     }
 });
 
 Task("libHarfBuzzSharp")
+    .IsDependentOn("git-sync-deps")
     .WithCriteria(IsRunningOnMacOs())
     .Does(() =>
 {
     if (VARIANT == "ios") {
-        Build("iphonesimulator", "x86_64");
-        Build("iphonesimulator", "arm64");
-        Build("iphoneos", "arm64");
-        // Build("iphoneos", "arm64e");
+        var simX64 = Build("iphonesimulator", "x86_64", "x64");
+        var simArm64 = Build("iphonesimulator", "arm64", "arm64");
+        var deviceArm64 = Build("iphoneos", "arm64", "arm64");
 
-        SafeCopy(
-            $"libHarfBuzzSharp/bin/{CONFIGURATION}/iphonesimulator/x86_64.xcarchive",
-            OUTPUT_PATH.Combine($"ios/libHarfBuzzSharp/x86_64.xcarchive"));
+        CombineFrameworks(
+            OUTPUT_PATH.Combine("ios/libHarfBuzzSharp.framework"),
+            new[] { deviceArm64, simX64 });
 
-        CreateFatFramework(OUTPUT_PATH.Combine("ios/libHarfBuzzSharp"));
-        CreateFatFramework(OUTPUT_PATH.Combine("iossimulator/libHarfBuzzSharp"));
+        CombineFrameworks(
+            OUTPUT_PATH.Combine("iossimulator/libHarfBuzzSharp.framework"),
+            new[] { simX64, simArm64 });
     } else if (VARIANT == "maccatalyst") {
-        Build("macosx", "x86_64");
-        Build("macosx", "arm64");
+        var x64 = Build("macosx", "x86_64", "x64");
+        var arm64 = Build("macosx", "arm64", "arm64");
 
-        CreateFatVersionedFramework(OUTPUT_PATH.Combine("maccatalyst/libHarfBuzzSharp"));
+        CombineFrameworks(
+            OUTPUT_PATH.Combine("maccatalyst/libHarfBuzzSharp.framework"),
+            new[] { x64, arm64 },
+            versioned: true);
     }
 
-    void Build(string sdk, string arch, string xcodeArch = null)
+    DirectoryPath Build(string sdk, string arch, string skiaArch)
     {
-        if (Skip(arch)) return;
+        if (Skip(arch)) return null;
 
-        xcodeArch = xcodeArch ?? arch;
         var isSim = sdk.EndsWith("simulator");
         var platform = VARIANT;
         if (VARIANT == "ios" && isSim)
             platform += "simulator";
 
-        RunXCodeBuild("libHarfBuzzSharp/libHarfBuzzSharp.xcodeproj", "libHarfBuzzSharp", sdk, xcodeArch, properties: new Dictionary<string, string> {
-            { $"{VARIANT.ToUpper()}_DEPLOYMENT_TARGET_VERSION", GetDeploymentTarget(arch) },
-        });
+        // Reuse the same out dir + args as libSkiaSharp (identical args => no re-gen);
+        // only the ninja target differs. The HarfBuzzSharp GN target is self-contained.
+        GnNinja($"{platform}/{arch}", "HarfBuzzSharp", SkiaGnArgs(skiaArch, arch, isSim));
 
-        SafeCopy(
-            $"libHarfBuzzSharp/bin/{CONFIGURATION}/{sdk}/{xcodeArch}.xcarchive",
-            OUTPUT_PATH.Combine($"{platform}/libHarfBuzzSharp/{xcodeArch}.xcarchive"));
+        return SKIA_PATH.Combine($"out/{platform}/{arch}/libHarfBuzzSharp.framework");
     }
 });