SPM migrator should exit when unmigrated custom targets are found #165115

navaronbracke · 2025-03-13T09:46:01Z

This PR updates the Swift Package Manager project migrator to detect when custom targets are used and exits with a message pointing to the docs, if any of the custom targets are not migrated yet.

I also found some discrepancies in the wording around when a reference in the pbxproj is for the project or a native target.
That has been corrected in this PR as well.

Fixes #164099

If you had to change anything in the [flutter/tests] repo, include a link to the migration guide as per the [breaking change policy].

Pre-launch Checklist

I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
I read the [Tree Hygiene] wiki page, which explains my responsibilities.
I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement].
I signed the [CLA].
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is [test-exempt].
I followed the [breaking change policy] and added [Data Driven Fixes] where supported.
All existing and new tests are passing.

…ct in logger

navaronbracke · 2025-03-13T09:58:09Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

-      final int packageProductDependenciesIndex = lines.indexWhere(
-        (String line) => line.trim().contains('packageProductDependencies'),
-        runnerNativeTargetStartIndex,
+      lines.insertAll(nativeTargetStartIndex + 1, newContent);


I used an early return to avoid the else here, hence the odd diff.

navaronbracke · 2025-03-13T09:59:54Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

+
+    if (applicationNativeTargets.isEmpty) {
+      throw Exception(
+        'Unable to find parsed PBXNativeTargets for ${_xcodeProject.hostAppProjectName} project.',


The old code had target. at the end, but that is a bit misleading. It's the Runner project that has N Targets.
Because the migrator now handles multiple Targets, it gets more confusing so I updated it here to rectify that.

navaronbracke · 2025-03-13T10:02:48Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

+    if (packageProductDependenciesIndex == -1 ||
+        packageProductDependenciesIndex > endSectionIndex) {
+      throw Exception(
+        'Unable to find packageProductDependencies for ${_xcodeProject.hostAppProjectName} PBXNativeTarget.',


Should we use the name of the affected target? I also saw that there isn't an existing test for this throw statement. I guess this cannot really happen since the nativeTarget.packageProductDependencies are not null at this point?

…e in logger

navaronbracke · 2025-03-13T10:44:45Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

+    if (packageProductDependenciesIndex == -1 ||
+        packageProductDependenciesIndex > endSectionIndex) {
+      throw Exception(
+        'Unable to find packageProductDependencies for $pbxTargetName in ${_xcodeProject.hostAppProjectName} project.',


Added the name of the affected target + clarifying that hostAppProjectName is the project

…trict

navaronbracke · 2025-03-14T15:47:36Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

+  /// - The migrator is rerun through the flutter CLI upon executing `flutter run`
+  /// - The migrator should skip sections like 'PBXBuildFile' or 'XCSwiftPackageProductDependency',
+  ///   since they are already migrated
+  void _ensureNewIdentifiersNotUsed(List<String> lines) {


When adding the missing check for already migrated targets back, I encountered an issue:
The _ensureNewIdentifiersNotUsed is too conservative with its checks.

So I had to fix this by allowing the identifiers in the sections where these might occur after the migrator ran once. This enables the migrator to run again when additional application targets are added.
I'm not sure if there is a better solution to this issue?

Why is it too conservative? I think it's probably best to avoid duplicate ids whether they are in the same section or not.

Well, if we were to not modify the check, and we run the migrator on a pbxproj file which has more than one native target, then this check fails. This is due to encountering the identifiers in the custom targets that have already been migrated manually, as the old check only expects the identifiers once in the entire file.

For example:

Case 1: (the migration should be skipped)

migrated Runner target

manually migrated custom target

Case 2: (the migrator should throw for the newly added custom target)

migrated Runner target

manually migrated custom target

newly added, but not yet manually migrated custom target

When I run the tests after I revert that change, I see that the following tests start to fail:

skips PBXNativeTarget migration if all targets already migrated

skips Runner PBXNativeTarget migration if already migrated

fails if unmigrated custom target is detected

navaronbracke · 2025-03-14T15:49:03Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

+  /// Returns false if the [identifier] does not occur in the given [lines].
+  /// Returns false if the [identifier] only occurs within the sections denoted by the [sectionNames].
+  /// Returns true otherwise.
+  bool _isIdentifierOutsideAllowedSections(


This is used by the new duplicate identifier check

navaronbracke · 2025-03-14T15:52:44Z

...er_tools/test/general.shard/migrations/swift_package_manager_integration_migration_test.dart

@@ -671,6 +744,57 @@ void main() {
        expect(testLogger.traceText, contains('project.pbxproj already migrated. Skipping...'));
      });

+      testWithoutContext('skips PBXNativeTarget migration if all targets are migrated', () async {


There was no "skip" test for when the Runner target was already migrated. This is one of several new tests to cover that.

navaronbracke · 2025-03-17T14:57:09Z

...er_tools/test/general.shard/migrations/swift_package_manager_integration_migration_test.dart

@@ -2980,15 +3272,16 @@ String migratedNativeTargetSection(
  SupportedPlatform platform, {
  bool missingPackageProductDependencies = false,
  bool withOtherDependency = false,
+  String? otherNativeTarget,


I updated this method to allow for inserting an additional PBXNativeTarget. To keep the readability for the Runner target, I went with a StringBuffer, to allow for splitting it up, while preserving the sections.

navaronbracke · 2025-03-17T14:58:36Z

...er_tools/test/general.shard/migrations/swift_package_manager_integration_migration_test.dart

+/// A variant of [migratedNativeTargetSection]
+/// that includes an additional PBXNativeTarget, "OtherTarget", that is not migrated.
+String migratedRunnerWithUnmigratedOtherTargetSection(SupportedPlatform platform) {
+  final String otherTarget = <String>[


I only added this target for an iOS specific test. Not sure if we need a MacOS variant also? The only real difference is the identifiers being slightly different.

navaronbracke · 2025-03-29T13:30:07Z

Hi @navaronbracke! This is great work, but unfortunately I don't think this is something we want to adopt. When custom targets get involved it gets much more complicated and altering the pbxproj file is already a little precarious.

I think for a majority of Flutter users, the defaults are probably sufficient. I would be open to accepting a PR that detects a custom target is being used and is missing the migrations and throws a warning/error with a link to the documentation on how to add manually.

Done!

navaronbracke · 2025-03-29T19:40:51Z

Edit: It seems we only need some extra handling for the RunnerTests target. The Flutter Assemble target is not in the PBXNativeTargets section (it is a PBXAggregateTarget) and the Flutter Assemble scheme is an autogenerated XCode scheme, so it does not exist in the xcschemes directory where we look for schemes.

There is one failing set of tests, but that is because the Flutter tool itself also provides custom targets & schemes.

~~I'll either update the templates to be SPM compliant for those or ignore them for now in the migrator.~~

~~1. Flutter Assemble target & scheme~~
~~2. RunnerTests target~~

~~I'm not sure if there are more that the tool provides? cc @vashworth~~

navaronbracke · 2025-03-31T14:11:50Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

+    );
+  }
+
+  bool _isNotATestingNativeTarget(ParsedNativeTarget target) {


This check should help with the failures for the RunnerTests target.

IIRC the migrator previously didn't do anything for that type of target, so I think we can exclude testing targets from the migrator?

vashworth · 2025-04-11T15:52:49Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

@@ -294,7 +331,7 @@ class SwiftPackageManagerIntegrationMigration extends ProjectMigrator {
               <EnvironmentBuildable>
                  <BuildableReference
                     BuildableIdentifier = "primary"
-                     BlueprintIdentifier = "$_runnerNativeTargetIdentifier"
+                     BlueprintIdentifier = "$blueprintIdentifier"


Undo, we only will ever insert the $_runnerNativeTargetIdentifier.

vashworth · 2025-04-11T16:11:21Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

+        index = lineIndex;
+        break;
+      }
+    }


This may match on the wrong Blueprint Identifier.

For example, when I change the target of my scheme, $_runnerNativeTargetIdentifier is the first BlueprintIdentifier found in the scheme file, but now buildForRunning equals NO.

<?xml version="1.0" encoding="UTF-8"?> <Scheme LastUpgradeVersion = "1510" version = "1.7"> <BuildAction parallelizeBuildables = "YES" buildImplicitDependencies = "YES"> <BuildActionEntries> <BuildActionEntry buildForTesting = "YES" buildForRunning = "NO" buildForProfiling = "YES" buildForArchiving = "YES" buildForAnalyzing = "YES"> <BuildableReference BuildableIdentifier = "primary" BlueprintIdentifier = "97C146ED1CF9000F007C117D" BuildableName = "Runner.app" BlueprintName = "Runner" ReferencedContainer = "container:Runner.xcodeproj"> </BuildableReference> </BuildActionEntry> <BuildActionEntry buildForTesting = "YES" buildForRunning = "YES" buildForProfiling = "YES" buildForArchiving = "YES" buildForAnalyzing = "YES"> <BuildableReference BuildableIdentifier = "primary" BlueprintIdentifier = "788C022D2DA97110009DD71A" BuildableName = "NEW_TARGET.app" BlueprintName = "NEW_TARGET" ReferencedContainer = "container:Runner.xcodeproj"> </BuildableReference> </BuildActionEntry> </BuildActionEntries> </BuildAction> ...

Since the scheme file is XML, I think it would be better to use XmlDocument.parse to try and figure this out.

So steps would be

Parse the XML

Check if the LaunchAction > BuildableProductRunnable > BuildableReference matches _runnerNativeTargetIdentifier, if not throw an error. Otherwise, get the BuildableName, BlueprintName, ReferencedContainer

Shouldn't all changes below this point be removed since we're not migrating any custom targets?

You're right about that, we're only supposed to detect the custom targets in the pbxproj, not the active xcscheme file.

And good point about using the XML parser, no need to reinvent the wheel.

navaronbracke · 2025-04-26T12:22:31Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

-                     $buildableName
-                     $blueprintName
-                     $referencedContainer
+                     BuildableName = "$buildableName"


Since the BlueprintIdentifier attribute also keeps the XML attribute in the template, I opted for doing that for the others also.

vashworth · 2025-05-13T16:35:20Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

+  /// - The migrator is rerun through the flutter CLI upon executing `flutter run`
+  /// - The migrator should skip sections like 'PBXBuildFile' or 'XCSwiftPackageProductDependency',
+  ///   since they are already migrated
+  void _ensureNewIdentifiersNotUsed(List<String> lines) {


Why is it too conservative? I think it's probably best to avoid duplicate ids whether they are in the same section or not.

vashworth · 2025-05-13T16:59:10Z

packages/flutter_tools/lib/src/migrations/swift_package_manager_integration_migration.dart

+  }
+
+  List<String> _migrateNativeTargets(List<String> lines, ParsedProjectInfo projectInfo) {
+    if (projectInfo.nativeTargets.isNotEmpty && _areNativeTargetsMigrated(projectInfo)) {


I think we want to be more conservative since there can be more types of targets than just unit testing which Flutter may or may not support. For example, if they add a watch extension, which is not supported by Flutter currently and we wouldn't want them to migrate it, this will fail.

Here's roughly what I would do:

// get BlueprintIdentifier from scheme for the current flavor final ( :String blueprintIdentifier, :String buildableName, :String blueprintName, :String referencedContainer, ) = _parseSchemeFile(schemeFile.basename, schemeContent, throwOnCustomTarget = false); ... // Check if the selected flavor specifically is migrated final bool migrated = projectInfo.nativeTargets .where( (ParsedNativeTarget target) => target.identifier == blueprintIdentifier && target.packageProductDependencies != null && target.packageProductDependencies!.contains( _flutterPluginsSwiftPackageProductDependencyIdentifier, ), ) .toList() .isNotEmpty; // If not migrated, show error

Piinks · 2025-07-15T22:53:02Z

Hey @vashworth and @navaronbracke, greetings from stale PR triage. 👋
It looks like we left off here with @navaronbracke responding to the last feedback @vashworth provided. Is this still a change we want to make?

navaronbracke added 2 commits March 13, 2025 10:31

handle multiple application product native targets in SPM migrator

c143b1f

fix expectations for existing tests; fix discrepancy for Runner proje…

1e9e99e

…ct in logger

github-actions bot added the tool Affects the "flutter" command-line tool. See also t: labels. label Mar 13, 2025

navaronbracke commented Mar 13, 2025

View reviewed changes

fix "project" discrepancy in logger; add affected PBXNativeTarget nam…

5ee64bf

…e in logger

navaronbracke commented Mar 13, 2025

View reviewed changes

navaronbracke added 3 commits March 13, 2025 14:19

add test for scheme migration

20ac696

add test for pbxproj migration

338272c

use a test-only override property instead

478eb0b

navaronbracke marked this pull request as ready for review March 13, 2025 15:22

Merge branch 'master' into fix_spm_migrator_multiple_application_targets

561e627

loic-sharma requested review from loic-sharma and vashworth March 13, 2025 19:28

navaronbracke added 5 commits March 14, 2025 09:32

add helper for PBXNativeTarget name label

f1f0edd

add check for individual PBXNativeTargets

a43d378

make identifiers check more precise

84531e1

update flutterPluginSwiftPackageInProjectSettings getter to be more s…

a766fd8

…trict

add test for all PBXNativeTargets migrated

4d67e9a

github-actions bot added a: desktop Running on desktop team-ios Owned by iOS platform team labels Mar 14, 2025

navaronbracke commented Mar 14, 2025

View reviewed changes

navaronbracke added 2 commits March 17, 2025 15:49

fix broken checks

a873597

add missing test

f44d182

navaronbracke commented Mar 17, 2025

View reviewed changes

format

f54ffbc

Merge branch 'master' into fix_spm_migrator_multiple_application_targets

087d02a

navaronbracke changed the title ~~handle multiple application product native targets in SPM migrator~~ SPM migrator should exit when unmigrated custom targets are found Mar 29, 2025

navaronbracke marked this pull request as ready for review March 29, 2025 13:29

navaronbracke requested a review from vashworth March 29, 2025 13:30

navaronbracke mentioned this pull request Mar 29, 2025

[flutter_tools] Swift package manager tests contain two tests with almost identical names but different behaviors #166204

Open

fix broken test

6e265b6

navaronbracke marked this pull request as draft March 29, 2025 19:36

navaronbracke added 6 commits March 30, 2025 13:41

move test to correct section

19d24f5

reorganize test helper

94dd4f4

add other native target arg to test helper

9e36123

add runner tests target constants

42de01c

add tests for test targets

87e39b0

exclude testing targets from migration

f2f5675

navaronbracke commented Mar 31, 2025

View reviewed changes

navaronbracke marked this pull request as ready for review March 31, 2025 14:55

vashworth reviewed Apr 11, 2025

View reviewed changes

navaronbracke added 7 commits April 13, 2025 16:37

use xml parser to get scheme attributes

4ef01e3

revert doc change

2c34cbf

use named record fields; leave the XML attributes in the template

e4fd5dd

check if root element is a Scheme tag

6f913f1

update tests

93af510

fix check

37acc0c

format + fix closing tags

5b5f01f

navaronbracke requested a review from a team as a code owner April 26, 2025 12:19

navaronbracke commented Apr 26, 2025

View reviewed changes

navaronbracke requested a review from vashworth April 26, 2025 12:27

vashworth reviewed May 13, 2025

View reviewed changes

SPM migrator should exit when unmigrated custom targets are found #165115

Are you sure you want to change the base?

SPM migrator should exit when unmigrated custom targets are found #165115

Conversation

navaronbracke commented Mar 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

navaronbracke Mar 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

navaronbracke May 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

navaronbracke Mar 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

navaronbracke commented Mar 29, 2025

Uh oh!

navaronbracke commented Mar 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Piinks commented Jul 15, 2025

Uh oh!

Uh oh!

navaronbracke commented Mar 13, 2025 •

edited

Loading

navaronbracke Mar 13, 2025 •

edited

Loading

navaronbracke May 14, 2025 •

edited

Loading

navaronbracke Mar 14, 2025 •

edited

Loading

navaronbracke commented Mar 29, 2025 •

edited

Loading