[flutter_tool] Documentation on Base configurations in XCode with and without CocoaPods

[buzzware]

Steps to reproduce

1. flutter create flutter_20240424 --platforms ios
2. add the following to pubspec.yml (probably any packages requiring cocoapods will do)

  cloud_firestore: any
  firebase_auth: any
  firebase_messaging: any
  firebase_storage: any
  app_links: any
  firebase_analytics: any
  flutter_barcode_scanner: any

3. flutter pub get
4. cd ios
5. pod install

Actual results

you will see :

[!] CocoaPods did not set the base configuration of your project because your project already has a custom config set. In order for CocoaPods integration to work at all, please either set the base configurations of the target `Runner` to `Target Support Files/Pods-Runner/Pods-Runner.profile.xcconfig` or include the `Target Support Files/Pods-Runner/Pods-Runner.profile.xcconfig` in your build configuration (`Flutter/Release.xcconfig`).

The issue is that the Runner Profile configuration is set to the Release configuration. Setting it to Pods-Runner.profile makes the error go away, but I don't know what it should be.

This is my modified (and seemingly correct) configuration :

These base configurations cause a lot of trouble for flutter development, and I have not seen any official advice or documentation online. In my main project I've had #140845 / #138795 holding me up for days. Older articles advised selecting Pods-Runner.xxx directly, which means not including Generated which causes the #138795 "Null check operator" error (Debug & Release are only 2 lines - they include Pods-Runner.xxx and Generated, and Generated contains the environment variables required by xcode_backend.dart).

Adding packages that require CocoaPods makes the situation more confusing as there are many more configurations in the list.

I believe some official documentation including screenshots of what the base configurations in XCode should look like with and without CocoaPods would be very helpful. Even if the generated project is fixed, it would still help people with existing projects.

Logs

Logs

<!-- Paste your logs here -->

Flutter Doctor output

Doctor output

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel beta, 3.22.0-0.2.pre, on macOS 14.4.1 23E224 darwin-x64, locale en-AU)
[✓] Android toolchain - develop for Android devices (Android SDK version 33.0.2)
[✓] Xcode - develop for iOS and macOS (Xcode 15.3)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2023.2)
[✓] Android Studio (version 2022.2)
[✓] IntelliJ IDEA Ultimate Edition (version 2024.1)
[✓] VS Code (version 1.87.2)
[✓] Connected device (2 available)            
[✓] Network resources

• No issues found!

[darshankawar]

Thanks for the report @buzzware
Can you take a look at this issue and underlying comments to see if they help in your case or not ?

[buzzware]

Thanks for the report @buzzware Can you take a look at this issue and underlying comments to see if they help in your case or not ?

@darshankawar I don't have an issue in my project - I am reporting my learning and I think a bug when you generate a fresh project and then add packages that require CocoaPods. As part of the solution I'm suggesting some documentation explaining the XCode -> Flutter integration through xcode_backend and the recommended configs.
That reference is 3 years old and doesn't cover CocoaPods.

[darshankawar]

Thanks for the update. I do see the message but it is a warning / alert and not an error and it is coming from cocoapods and not Flutter.

I believe some official documentation including screenshots of what the base configurations in XCode should look like with and without CocoaPods would be very helpful.

I'll keep this issue open for documentation if the team thinks it would be beneficial.

[buzzware]

Yes its a warning but the warning says "In order for CocoaPods integration to work at all..."

Also when upgrading old projects or trying to fix build errors, it helps to know what the intention is of each of the configurations so you know what should be selected.