[SwiftPM] When Swift Package Manager migration fails, link to documentation instructions to set it up manually

[bc-lee]

The Xcode project format has a notoriously bad reputation among iOS/macOS software engineers. It is fragile, hard to read, and difficult to maintain. This is why iOS engineers often reinvent alternatives or generators for Xcode project files, such as XcodeGen and Tuist. Personally, I no longer use plain Xcode project files, except for Flutter-related projects. Flutter performs a lot of "magic" during the build process and relies on Xcode project files for iOS/macOS targets.

Additionally, with the decline of CocoaPods, most dependencies are now available through Swift Package Manager (SPM). Flutter has embraced this shift by introducing an option to use SPM for iOS/macOS projects in Flutter 3.27, which I find very exciting.

However, I encountered an issue when migrating to Swift Package Manager. The migration script failed with the following error:

Adding Swift Package Manager integration...                         22ms
An error occurred when adding Swift Package Manager integration:
  Exception: Unable to find PBXFrameworksBuildPhase for Runner target.

Swift Package Manager is currently an experimental feature. Please file a bug at:
  https://github.com/flutter/flutter/issues/new?template=1_activation.yml
Consider including a copy of the following files in your bug report:
  ios/Runner.xcodeproj/project.pbxproj
  ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme (or the scheme for the flavor used)

To avoid this failure, disable Flutter Swift Package Manager integration for the project
by adding the following to the project's `pubspec.yaml` under the "flutter" section:
  `disable-swift-package-manager: true`
Alternatively, disable Flutter Swift Package Manager integration globally with:
  `flutter config --no-enable-swift-package-manager`

Upon investigation, I reviewed the migration script code in swift_package_manager_integration_migration.dart and discovered that it relies on hard-coded identifiers for various Xcode project sections. For example:

static const String _iosRunnerNativeTargetIdentifier = '97C146ED1CF9000F007C117D';

This is problematic because tools like xUnique, which normalize Xcode project files, can change these identifiers. Here's an example of how identifiers change after normalization:

Before Normalization

/* Begin PBXNativeTarget section */
97C146ED1CF9000F007C117D /* Runner */ = {
    isa = PBXNativeTarget;
    buildConfigurationList = 97C147051CF9000F007C117D /* Build configuration list for PBXNativeTarget "Runner" */;
    buildPhases = (
        EF5FC0595FAA045E778ABA64 /* [CP] Check Pods Manifest.lock */,
        9740EEB61CF901F6004384FC /* Run Script */,
        97C146EA1CF9000F007C117D /* Sources */,
        97C146EB1CF9000F007C117D /* Frameworks */,
        97C146EC1CF9000F007C117D /* Resources */,
        9705A1C41CF9048500538489 /* Embed Frameworks */,
        3B06AD1E1E4923F5004D2608 /* Thin Binary */,
    );
    productName = Runner;
    ...
};
/* End PBXNativeTarget section */

After Normalization

/* Begin PBXNativeTarget section */
E30F7D64842177B99FDDF63DCA10BCDE /* Runner */ = {
    isa = PBXNativeTarget;
    buildConfigurationList = 92578F7B9E3F6AC8F17192C290223DCF /* Build configuration list for PBXNativeTarget "Runner" */;
    buildPhases = (
        AC0061BF939EE938EA540EE9D04BF3B3 /* [CP] Check Pods Manifest.lock */,
        7E9D2C9174A80CAA4BFDFDCB4F72C7A8 /* Run Script */,
        FBC56BB6E87C12DAFB6BB5C3C53DF533 /* Sources */,
        00C27919A6B50DC1DE2CD3F64D33BCCA /* Frameworks */,
        8CF819BBBFB9AE05A1821B127DF85DF8 /* Resources */,
        E55F38183CFB6C120953C92EF0C091F4 /* Embed Frameworks */,
        3CBF9DA705FA99067B6DD4D7F9246CC9 /* Thin Binary */,
    );
    productName = Runner;
    ...
};
/* End PBXNativeTarget section */

The hard-coded identifier for the Runner target (97C146ED1CF9000F007C117D) was replaced with a new identifier (E30F7D64842177B99FDDF63DCA10BCDE). As a result, the migration script failed.

Suggested Solution

To avoid these issues, the migration script should not rely on hard-coded identifiers. Instead, it should dynamically locate the required objects in the Xcode project file, possibly by matching the name property of targets or using other stable metadata. While implementing such a solution might be more complex, it would make the migration process more robust and compatible with various Xcode project configurations.

[loic-sharma]

I wasn't aware of normalized projects. Thank you for opening this issue and the excellent explanation!

[stuartmorgan-g]

Generally our approach is to consider auto-migration to be best-effort, and then provide a link to manual instructions for people who have made alterations to their project that prevent auto-migration, so we should explore that option here.

[jmagman]

There's a difficult problem here which is that Flutter wants to "own" parts of your Xcode project (like the part that injects Flutter into it, or links against it, or adds your plugin dependencies), but in actuality Flutter devs can open their Xcode projects and change it (same for your Android projects). You can open it up and add extensions, or change your build version to match something other than what's in pubpec, or a million other totally legit reasons Flutter should allow. Our auto-migrations, like the Swift Package Manager migration, are extremely conservative and only make changes to your Xcode project if it's sure it's safe and won't corrupt your Xcode project (which as you point out, is very easy to do). The hard-coded IDs in the tool come from previous flutter create templates, and are something we use to assume that that particular part of the project is probably safe to edit and likely looks almost the same as when it was created.

We have to serve a few types of users here: advanced iOS users who need to be able to crack open their Xcode project and do whatever they want, and iOS n00bs who never want to open Xcode.

I can tell you in the Bad Old Days before the migrations (disclaimer: I wrote the feature) we didn't change the Xcode project at all, and every release your Xcode project would get further and further away from what Flutter needed (minimum supported iOS version bump), or Apple wanted (you'll start getting compilation errors if you have X build setting), and all we could do it print a message "go to this doc to figure out how to open Xcode and manually do X", or worse nothing at all. Which is painful for everyone but especially the developers who never want to open Xcode. Every example you see on Stackoverflow of "just regenerate your Xcode project" is an example of this, and that advice fell off sharply after we introduced the migrations.

A better form of these Xcode project migrations would be to have an Xcode project DSL to alter the things we need. But we haven't because

1. Apple doesn't provide one afaik
2. If we use something that already exists, we're back in CocoaPods world where it breaks every release PBXGroup attempted to initialize an object with unknown ISA PBXFileSystemSynchronizedRootGroup CocoaPods/CocoaPods#12456 (also potential licensing issues)
3. We don't want to be in the business of writing something like that ourselves.

So our string mashing and ID comparisons are the best solutions we have (though I'd love to hear better ideas).

As @stuartmorgan says, the Swift Package Manager migration should bail when it doesn't think it can do it safely, but link to manual documentation. For example: https://web.archive.org/web/20220614103526/https://docs.flutter.dev/development/ios-project-migration

Let's take this issue as a request to add that manual documentation for Swift Package Manager specifically.