From b548b02c328bfa62d9a53522113153dcf22db1a3 Mon Sep 17 00:00:00 2001
From: Chris Bracken <chris@bracken.jp>
Date: Wed, 28 Sep 2022 00:08:09 +0100
Subject: [PATCH] [macOS] Deduplicate gen_snapshot creation targets (#36455)

Cleans up the logic for building gen_snapshot for macOS hosts. Also adds
a bit more documentation to the snapshot-related build targets.

Previously:
* gen_snapshot targeting macOS (on both x64, and arm64) were generated
  via the `create_macos_gen_snapshots` target.
* gen_snapshot arm/arm64 builds (on a macOS host) were generated via the
  `create_arm_gen_snapshot` target. The reason why this covers only
  arm/arm64 is simply that those are the only platforms we generate
  iOS/Android AOT builds for. x64 iOS implies a simulator build, but we
  only support debug builds for the iOS simulator, which aren't AOT
  builds, and thus don't require gen_snapshot.

These two conditions overlap in the case of arm64 (but not x64) target
builds. This separates the two cases cleanly. A later patch will merge
the two cases to use a single tool.

Note that NEITHER of these two scenarios mentions builds for macOS hosts
targeting Fuchsia. That's because this target is never invoked during
Fuchsia target builds. See:
https://github.com/flutter/engine/blob/85fa818d85475693e9df9ebb62b51e8e57e93adb/BUILD.gn#L93-L95

Issue: https://github.com/flutter/flutter/issues/103386
Issue: https://github.com/flutter/flutter/issues/101138
---
 lib/snapshot/BUILD.gn | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/lib/snapshot/BUILD.gn b/lib/snapshot/BUILD.gn
index bf08b11d865b5..5eef5474badd2 100644
--- a/lib/snapshot/BUILD.gn
+++ b/lib/snapshot/BUILD.gn
@@ -9,28 +9,48 @@ import("//flutter/lib/ui/dart_ui.gni")
 import("//flutter/sky/tools/macos_snapshots.gni")
 import("//third_party/dart/utils/compile_platform.gni")
 
+# Generates the Dart/Flutter core platform files and tools.
+#
+# This target generates the platform-specific snapshots and snapshot-related
+# tooling for a given target CPU.
+#
+# Outputs:
+#   * Core platform compiled to kernel bytecode
+#   * Core platform compiled to target_cpu-specific binary snapshot
+#   * target_cpu-specific gen_snapshot
+#   * target_cpu-specific analyze_snapshot
 group("generate_snapshot_bins") {
   deps = [
     ":generate_snapshot_bin",
     ":kernel_platform_files",
   ]
-  if (host_os == "mac" && (target_cpu == "arm" || target_cpu == "arm64")) {
-    deps += [ ":create_arm_gen_snapshot" ]
-  }
+
+  # Build gen_snapshot for the currently specified target_cpu.
+  #
+  # For macOS target builds: needed for both target CPUs (arm64, x64).
+  # For iOS, Android target builds: all AOT target CPUs are arm/arm64.
   if (host_os == "mac" && target_os == "mac") {
     deps += [ ":create_macos_gen_snapshots" ]
+  } else if (host_os == "mac" &&
+             (target_cpu == "arm" || target_cpu == "arm64")) {
+    deps += [ ":create_arm_gen_snapshot" ]
   }
+
+  # Build analyze_snapshot for for 64-bit target CPUs.
   if (target_cpu == "x64" || target_cpu == "arm64") {
     deps +=
         [ "//third_party/dart/runtime/bin:analyze_snapshot($host_toolchain)" ]
   }
 }
 
-# Uses gen_snapshot to compile a Dart core platform snapshot.
+# Compiles a binary snapshot of the core Dart/Flutter platform.
 #
 # Inputs:
 #   * platform_strong.dill
 #
+# Tools:
+#   * gen_snapshot
+#
 # Outputs:
 #   * vm_snapshot_data.bin
 #   * vm_snapshot_instructions.bin