[ios]: Proposal to provide Flutter specific error messages / suggestions for dependency related issues.

[alexeyinkin]

Use case

I find that the tools for building a Flutter app for iOS are too thin of a layer above the native tools for building for iOS. A few examples:

When packages get their dependencies wrong, this requires me to dig too deep.

I added a recent firebase_storage 12.2.0 to an otherwise building project, and it resulted in this error:

    [!] CocoaPods could not find compatible versions for pod "Firebase/Auth":
      In snapshot (Podfile.lock):
        Firebase/Auth (= 10.29.0)

      In Podfile:
        firebase_auth (from `.symlinks/plugins/firebase_auth/ios`) was resolved to 5.1.3, which depends on
          Firebase/Auth (= 11.0.0)
...
Error: CocoaPods's specs repository is too out-of-date to satisfy dependencies.
To update the CocoaPods specs, run:
  pod repo update

Error: Error running pod install

So the last tip of flutter run resulted to be to run pod repo update, which didn't work because the problem was in the dependencies. My firebase_auth was at 5.1.3, which is compatible to the recent firebase_storage according to pub, so Flutter allowed me to attempt the build. The package versions however are incompatible at their native plugin levels, and the solution was to run flutter clean and flutter pub upgrade.

This got me to compatible versions in pubspec.lock, but building still failed with the same error. Turned out it did not update Podfile.lock, and I had to delete it manually so it's recreated on the next build.

This got me to this error:

Running Xcode build...
Xcode build done.                                           294,5s
Failed to build iOS app
Could not build the precompiled application for the device.
Error (Xcode): Undefined symbols:

Error (Xcode): Linker command failed with exit code 1 (use -v to see invocation)

Error launching application on Alexey Inkin's iPhone.

I had to go through this to find the hidden undefined symbols: https://forums.developer.apple.com/forums/thread/739568

To find them, it required me to build the project from Xcode to see

ld: Undefined symbols:
  static StoreKit.Transaction.Offer.PaymentMode.freeTrial.getter : StoreKit.Transaction.Offer.PaymentMode, referenced from:
      static (extension in FirebaseAnalytics):__C.FIRAnalytics.logTransaction(StoreKit.Transaction) -> () in FirebaseAnalytics[17](Analytics+StoreKit.o)
...
clang: error: linker command failed with exit code 1 (use -v to see invocation)

To finally launch the app, I had to remove firebase_analytics in hope to use a future version when it works.

The point here is not the specific errors that are up to Firebase maintainers (that's why I'm not posting a min reproducible example). The point is if anything goes slightly wrong Flutter is not helpful enough. All those iOS techniques are indeed useful and good to know but not this early as to build a very basic app.

Also, such troublesome upgrades discourage upgrading dependencies, which impairs code quality and sometimes security.

Proposal

Some combination of the following:

1. Flutter should have better intel into Xcode error output. It should give Flutter-specific advices for common Xcode errors instead of just stopping after printing them as they are.
2. As Podfile dependencies and repository updates seem to be the most frequent detours from pure Flutter, it should translate pod resolution errors into Dart package resolution errors and suggest upgrades.
3. Manage Podfile so we don't need to delete it when we need it changed.
4. Attempt to auto-fix the errors described above. Out of the navigation through the errors above, only the removal of firebase_analytics could not be a subject of an auto-fix.

I'm not an iOS developer, so these are just directions and not a plan. I also understand that the output of Xcode and other tools subjects to change, so we should not rely on auto-fixes, but just trying to select a fix could cover many cases.

[stuartmorgan]

Since we're working on transitions from Cocoapods to SPM, and Cocoapods is in maintenance mode, it's unlikely that investing in more Cocoapods-specific error handling is worthwhile at this point.

[jmagman]

Error (Xcode): Undefined symbols:

Error (Xcode): Linker command failed with exit code 1 (use -v to see invocation)

The missing part after "Undefined symbols:" seems like a bug.

1. Flutter should have better intel into Xcode error output. It should give Flutter-specific advices for common Xcode errors instead of just stopping after printing them as they are.

We actually have an entire system to support this: https://github.com/flutter/flutter/blob/a3301cecae2867023288428f67945343173f70f9/packages/flutter_tools/lib/src/ios/mac.dart#L785-L823 Example: https://github.com/flutter/flutter/blob/a3301cecae2867023288428f67945343173f70f9/packages/flutter_tools/lib/src/ios/code_signing.dart#L44-L53

It's really hard to keep up with all the ways Xcode can fail and make actionable error messages, but we're happy to add new ones.

Since we're working on transitions from Cocoapods to SPM, and Cocoapods is in maintenance mode, it's unlikely that investing in more Cocoapods-specific error handling is worthwhile at this point.

+1. We're moving from CocoaPods to Swift Package Manager but I imagine very similar issues will be hit, since pub doesn't version-solve for the native dependencies, it's two dependency management systems layered on top of each other. We're definitely open to making these issues more actionable or auto-fix, but we would do so for the Swift Package Manager cases at this point, not CocoaPods.

[jmagman]

that's why I'm not posting a min reproducible example

The missing part after "Undefined symbols:" seems like a bug.

@alexeyinkin I want to file a separate bug for that particular problem, so if you have a min reproducible example for just that it would be very helpful so I don't need to spend time following all the paths you took to get your app building.

[alexeyinkin]

@jmagman, I reproduced it:

1. Create a project with flutter create temp2.
2. Add firebase_analytics: 11.3.0 to pubspec.yaml (note no ^ to pin this specific broken version).
3. Replace in files IPHONEOS_DEPLOYMENT_TARGET = 12.0 with IPHONEOS_DEPLOYMENT_TARGET = 13.0.
4. Open Runner.xcworkspace in Xcode and set a unique bundle identifier.
5. Run flutter devices to learn the ID of your iPhone.
6. Run flutter run -d your_device_id

This gave me an error I haven't seen before:

Launching lib/main.dart on Alexey Inkin's iPhone in debug mode...
Automatically signing iOS for device deployment using specified development team
in Xcode project: DNLKN6QZ24
Running pod install...                                              3,3s
Running Xcode build...                                                  
Xcode build done.                                           37,1s
Failed to build iOS app
Could not build the precompiled application for the device.
Error (Xcode): Provisioning profile "iOS Team Provisioning Profile:
com.alexeyinkintemp2" doesn't include the currently selected device "Alexey’s
MacBook Pro" (identifier XXXXXXXX-XXXXXXXXXXXXXXXX).
/Users/ai/temp/temp2/ios/Runner.xcodeproj

It appears that there was a problem signing your application prior to
installation on the device.

Verify that the Bundle Identifier in your project is your signing id in Xcode
  open ios/Runner.xcworkspace

Also try selecting 'Product > Build' to fix the problem.

Error launching application on Alexey Inkin's iPhone.

I followed the advice to build with Xcode first. It gave me this error (the symbols are visible if clicking the hamburger icon):

After that failure, I was able to reproduce the missing symbols message with re-running flutter run ...:

Launching lib/main.dart on Alexey Inkin's iPhone in debug mode...
Automatically signing iOS for device deployment using specified development team
in Xcode project: DNLKN6QZ24
Running Xcode build...                                                  
 └─Compiling, linking and signing...                      1.325ms
Xcode build done.                                           10,0s
Failed to build iOS app
Could not build the precompiled application for the device.
Error (Xcode): Undefined symbols:

Error (Xcode): Linker command failed with exit code 1 (use -v to see invocation)

Error launching application on Alexey Inkin's iPhone.

flutter doctor -v

``` [✓] Flutter (Channel stable, 3.24.2, on macOS 13.6 22G120 darwin-arm64, locale es-GE) • Flutter version 3.24.2 on channel stable at /Users/ai/bin/flutter • Upstream repository https://github.com/flutter/flutter.git • Framework revision 4cf269e36d (3 days ago), 2024-09-03 14:30:00 -0700 • Engine revision a6bd3f1de1 • Dart version 3.5.2 • DevTools version 2.37.2 [!] Android toolchain - develop for Android devices (Android SDK version 34.0.0) • Android SDK at /Users/ai/Library/Android/sdk ✗ cmdline-tools component is missing Run `path/to/sdkmanager --install "cmdline-tools;latest"` See https://developer.android.com/studio/command-line for more details. ✗ Android license status unknown. Run `flutter doctor --android-licenses` to accept the SDK licenses. See https://flutter.dev/to/macos-android-setup for more details. [✓] Xcode - develop for iOS and macOS (Xcode 15.0) • Xcode at /Applications/Xcode.app/Contents/Developer • Build 15A240d • CocoaPods version 1.15.2 [✓] Chrome - develop for the web • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome [✓] Android Studio (version 2024.1) • Android Studio at /Applications/Android Studio.app/Contents • Flutter plugin can be installed from: 🔨 https://plugins.jetbrains.com/plugin/9212-flutter • Dart plugin can be installed from: 🔨 https://plugins.jetbrains.com/plugin/6351-dart • Java version OpenJDK Runtime Environment (build 17.0.10+0-17.0.10b1087.21-11609105) [✓] IntelliJ IDEA Ultimate Edition (version 2023.3.3) • IntelliJ at /Applications/IntelliJ IDEA.app • Flutter plugin can be installed from: 🔨 https://plugins.jetbrains.com/plugin/9212-flutter • Dart plugin can be installed from: 🔨 https://plugins.jetbrains.com/plugin/6351-dart [✓] VS Code (version 1.90.0) • VS Code at /Users/ai/bin/Visual Studio Code.app/Contents • Flutter extension version 3.90.0 [✓] Connected device (4 available) • Alexey Inkin's iPhone (mobile) • 0dec698e7e1f6bfbe7bdd7e1b311ca5b2fd3199c • ios • iOS 15.8.3 19H386 • macOS (desktop) • macos • darwin-arm64 • macOS 13.6 22G120 darwin-arm64 • Mac Designed for iPad (desktop) • mac-designed-for-ipad • darwin • macOS 13.6 22G120 darwin-arm64 • Chrome (web) • chrome • web-javascript • Google Chrome 128.0.6613.120 [✓] Network resources • All expected network resources are available. ! Doctor found issues in 1 category. ```

Xcode Version 15.0 (15A240d)

[jmagman]

Thanks @alexeyinkin, I filed https://github.com/flutter/flutter/issues/154733

[andrewkolos]

@jmagman, There's been a lot of back and forth here, could you summarize what this issue tracks?

[jmagman]

From the proposal: some of the confusion seems to be about the missing error output, which is now tracked in https://github.com/flutter/flutter/issues/154733.

The rest are suggestions for the CocoaPods flow, which we are no longer investing in since it is in maintenance mode, and Flutter is imminently migrating from CocoaPods to Swift Package Manager.

Likely SwiftPM will have similar issues since it's still a dependency manager (pub) on top of another dependency manager (SwiftPM). However, we don't yet know how these issues will manifest, and the best way to help the user resolve.

@alexeyinkin am I missing anything else actionable?

[alexeyinkin]

@jmagman I think that covers all.

[bkonyi]

@jmagman is this safe to close if we're tracking the missing error output in #154733?

[jmagman]

@bkonyi yes I think so, I'll close. Thank you! @alexeyinkin if you have suggestions for errors we could handle better than don't involve CocoaPods, please file any suggestions. It's relatively easy to add new ones. https://github.com/flutter/flutter/blob/a3301cecae2867023288428f67945343173f70f9/packages/flutter_tools/lib/src/ios/mac.dart#L785-L823