[CP-stable][iOS] Bundle dSYM packages in Flutter.xcframework (#54513)

This pull request is created by [automatic cherry pick workflow](https://github.com/flutter/flutter/blob/main/docs/releases/Flutter-Cherrypick-Process.md#automatically-creates-a-cherry-pick-request)
Please fill in the form below, and a flutter domain expert will evaluate this cherry pick request.

### Issue Link:
What is the link to the issue this cherry-pick is addressing?

flutter/flutter#116493

Note this includes two PRs:
#54414
#54458

### Changelog Description:
Bundle iOS framework debugging symbols (`Flutter.framework.dSYM`) in `Flutter.xcframework` in iOS release builds. This eliminates the need for manual download/bundling of Flutter debug symbols for release build crash log symbolication. As of Xcode 16, these symbols are required to be bundled with App Store archives.

### Impact Description:
Without these bundled symbols, iOS App Store validation fails for Flutter apps under Xcode 16.

### Workaround:
Is there a workaround for this issue?

Users can follow the steps described in [docs/Crashes.md](https://github.com/flutter/engine/blob/main/docs/Crashes.md) to manually locate the engine SHA used in their Flutter app, download the Flutter.dSYM archive, and manually copy it into their app archive prior to App Store validation. This is very manual process with room for a lot of error. This process is not at all obvious or well-documented.

### Risk:
What is the risk level of this cherry-pick?

In the case where dSYM extraction fails, we'll know immediately since the build will fail. dSYMs can be verified using the steps below.

### Test Coverage:
Are you confident that your fix is well-tested by automated tests?

In this case the build itself will fail if dSYM extraction fails. Testing of bundling is covered in framework tool tests.

### Validation Steps:
What are the steps to validate that this fix works?

`artifacts.zip` can be checked at any commit on or after `c11fe483947c95553610ab59210af643f031f5f4`. For example https://storage.googleapis.com/flutter_infra_release/flutter/c11fe483947c95553610ab59210af643f031f5f4/ios-release/artifacts.zip

Verify that Flutter.xcframework in this archive contains `ios-arm64/dSYMs/Flutter.framework.dSYM`.

Author: flutteractionsbot

sky/tools/create_full_ios_framework.py

@@ -144,11 +144,20 @@ def create_framework(  # pylint: disable=too-many-arguments
     print('Cannot find iOS simulator dylib at %s' % simulator_x64_dylib)
     return 1
 
+  # Compute dsym output paths, if enabled.
+  framework_dsym = None
+  simulator_dsym = None
+  if args.dsym:
+    framework_dsym = framework + '.dSYM'
+    simulator_dsym = simulator_framework + '.dSYM'
+
+  # Emit the framework for physical devices.
   shutil.rmtree(framework, True)
   shutil.copytree(arm64_framework, framework)
   framework_binary = os.path.join(framework, 'Flutter')
-  process_framework(args, dst, framework, framework_binary)
+  process_framework(args, dst, framework_binary, framework_dsym)
 
+  # Emit the framework for simulators.
   if args.simulator_arm64_out_dir is not None:
     shutil.rmtree(simulator_framework, True)
     shutil.copytree(simulator_arm64_framework, simulator_framework)
@@ -160,22 +169,23 @@ def create_framework(  # pylint: disable=too-many-arguments
         'lipo', simulator_x64_dylib, simulator_arm64_dylib, '-create', '-output',
         simulator_framework_binary
     ])
-    process_framework(args, dst, simulator_framework, simulator_framework_binary)
+    process_framework(args, dst, simulator_framework_binary, simulator_dsym)
   else:
     simulator_framework = simulator_x64_framework
 
   # Create XCFramework from the arm-only fat framework and the arm64/x64
   # simulator frameworks, or just the x64 simulator framework if only that one
   # exists.
   xcframeworks = [simulator_framework, framework]
-  create_xcframework(location=dst, name='Flutter', frameworks=xcframeworks)
+  dsyms = [simulator_dsym, framework_dsym] if args.dsym else None
+  create_xcframework(location=dst, name='Flutter', frameworks=xcframeworks, dsyms=dsyms)
 
-  # Add the x64 simulator into the fat framework
+  # Add the x64 simulator into the fat framework.
   subprocess.check_call([
       'lipo', arm64_dylib, simulator_x64_dylib, '-create', '-output', framework_binary
   ])
 
-  process_framework(args, dst, framework, framework_binary)
+  process_framework(args, dst, framework_binary, framework_dsym)
   return 0
 
 
@@ -209,23 +219,36 @@ def zip_archive(dst):
       'extension_safe/Flutter.xcframework',
   ],
                         cwd=dst)
-  if os.path.exists(os.path.join(dst, 'Flutter.dSYM')):
+
+  # Generate Flutter.dSYM.zip for manual symbolification.
+  #
+  # Historically, the framework dSYM was named Flutter.dSYM, so in order to
+  # remain backward-compatible with existing instructions in docs/Crashes.md
+  # and existing tooling such as dart-lang/dart_ci, we rename back to that name
+  #
+  # TODO(cbracken): remove these archives and the upload steps once we bundle
+  # dSYMs in app archives. https://github.com/flutter/flutter/issues/116493
+  framework_dsym = os.path.join(dst, 'Flutter.framework.dSYM')
+  if os.path.exists(framework_dsym):
+    renamed_dsym = framework_dsym.replace('Flutter.framework.dSYM', 'Flutter.dSYM')
+    os.rename(framework_dsym, renamed_dsym)
     subprocess.check_call(['zip', '-r', 'Flutter.dSYM.zip', 'Flutter.dSYM'], cwd=dst)
 
-  if os.path.exists(os.path.join(dst, 'extension_safe', 'Flutter.dSYM')):
+  extension_safe_dsym = os.path.join(dst, 'extension_safe', 'Flutter.framework.dSYM')
+  if os.path.exists(extension_safe_dsym):
+    renamed_dsym = extension_safe_dsym.replace('Flutter.framework.dSYM', 'Flutter.dSYM')
+    os.rename(extension_safe_dsym, renamed_dsym)
     subprocess.check_call(['zip', '-r', 'extension_safe_Flutter.dSYM.zip', 'Flutter.dSYM'], cwd=dst)
 
 
-def process_framework(args, dst, framework, framework_binary):
-  if args.dsym:
-    dsym_out = os.path.splitext(framework)[0] + '.dSYM'
-    subprocess.check_call([DSYMUTIL, '-o', dsym_out, framework_binary])
+def process_framework(args, dst, framework_binary, dsym):
+  if dsym:
+    subprocess.check_call([DSYMUTIL, '-o', dsym, framework_binary])
 
   if args.strip:
     # copy unstripped
     unstripped_out = os.path.join(dst, 'Flutter.unstripped')
     shutil.copyfile(framework_binary, unstripped_out)
-
     subprocess.check_call(['strip', '-x', '-S', framework_binary])
 
 

sky/tools/create_xcframework.py

@@ -22,15 +22,22 @@ def main():
       help='The framework paths used to create the XCFramework.',
       required=True
   )
+  parser.add_argument(
+      '--dsyms', nargs='+', help='The dSYM paths to be bundled in the XCFramework.', required=False
+  )
   parser.add_argument('--name', help='Name of the XCFramework', type=str, required=True)
   parser.add_argument('--location', help='Output directory', type=str, required=True)
 
   args = parser.parse_args()
 
-  create_xcframework(args.location, args.name, args.frameworks)
+  create_xcframework(args.location, args.name, args.frameworks, args.dsyms)
+
 
+def create_xcframework(location, name, frameworks, dsyms=None):
+  if dsyms and len(frameworks) != len(dsyms):
+    print('Number of --dsyms must match number of --frameworks exactly.', file=sys.stderr)
+    sys.exit(1)
 
-def create_xcframework(location, name, frameworks):
   output_dir = os.path.abspath(location)
   output_xcframework = os.path.join(output_dir, '%s.xcframework' % name)
 
@@ -45,11 +52,13 @@ def create_xcframework(location, name, frameworks):
   #                  -framework bar/baz.framework -output output/
   command = ['xcrun', 'xcodebuild', '-quiet', '-create-xcframework']
 
-  for framework in frameworks:
-    command.extend(['-framework', os.path.abspath(framework)])
-
   command.extend(['-output', output_xcframework])
 
+  for i in range(len(frameworks)):  # pylint: disable=consider-using-enumerate
+    command.extend(['-framework', os.path.abspath(frameworks[i])])
+    if dsyms:
+      command.extend(['-debug-symbols', os.path.abspath(dsyms[i])])
+
   subprocess.check_call(command, stdout=open(os.devnull, 'w'))