Repository: flutter
Issue: [iOS] Process for renaming `Runner` incomplete for non-trivial projects
Labels: platform-ios,tool,t: xcode,c: proposal,P2,team-ios,triaged-ios

### Is there an existing issue for this?

- [X] I have searched the [existing issues](https://github.com/flutter/flutter/issues)
- [X] I have read the [guide to filing a bug](https://flutter.dev/docs/resources/bug-reports)

### Use case

In the article [What’s new in Flutter 3.13](https://medium.com/flutter/whats-new-in-flutter-3-13-479d9b11df4d) brief mention is given to the new ability to rename the Xcode project in iOS. No further information or link to additional details was given in the article.

A Google search found these [instructions](https://github.com/flutter/flutter/issues/9767#issuecomment-1533771721) by @LouiseHsu, as created 3 May 2023 and edited 28 August 2023.

The instructions were provided in the comments of #9767 (which is now closed and locked from further comment).

It is useful to me to have the ability to rename `Runner` because I deal with multiple Flutter projects and it can be confusing for them all to appear as `Runner` in various contexts (such as Xcode). So thank you for working on this capability.

However, when using the provided instructions, I encountered many errors when attempting to rename a mature, released iOS project. At least one issue did not appear until running `flutter build ipa`.

Here I'll detail the steps used that finally worked, some of the errors encountered along the way, and a lingering
appearance of `Runner` I was unable to resolve.

(Throughout, `XYZ` is used as the placeholder for the desired project name. Replace it with your own project name as needed.)


## Steps that worked

1. Make sure Xcode is closed / quit
2. Clean files
  - `rm -fr build`
  - `rm -fr ios/.symlinks`
  - `rm -fr ios/Pods`
  - `rm -fr .dart_tool`
  - `rm -f ios/Runner/GeneratedPluginRegistrant.*`
  - `rm -fr "$HOME/Library/Developer/Xcode/DerivedData"`
  - (These deletions may not be strictly necessary but I found it useful to start clean while working through the errors.)
3. Perform the described [instructions](https://github.com/flutter/flutter/issues/9767#issuecomment-1533771721)
4. In `ios/XYZ.xcodeproj/project.pbxproj`, search for `productName = Runner;` and replace `Runner`
5. In the `.metadata` file, `unmanaged_files` section, rename `'ios/Runner.xcodeproj/project.pbxproj'`
6. `flutter pub get`
7. `dart run build_runner build --delete-conflicting-outputs`
8. `flutter build ios`
9. `flutter build ipa`


## If you get the `building file list ... rsync: link_stat` error

You may see this error when trying to build an IPA, even if `flutter build ios` succeeds.

If so, you may need to update Cocoapods. Use `pod --version` to check the version, which should be >= 1.12.1 (see [this](https://stackoverflow.com/q/75977278) and [this](https://github.com/flutter/flutter/issues/123890)).

- `pod --version` to check version
- `sudo gem install -n /usr/local/bin cocoapods` to update, if needed
- `pod --version` to confirm version

Note that in my case, building an IPA succeeded with Cocoapods version 1.11.3 prior to renaming the project. However, after renaming the project, this error was encountered and it became necessary to update to Cocoapods 1.12.1.


## Caveat

The archive built by `flutter build ipa` is still named `Runner`.

<img width="889" alt="Screenshot 2023-09-20 at 9 46 41 PM" src="https://github.com/flutter/flutter/assets/8151661/2e155f90-4435-44d7-b9ac-baaf4cc2f8e0">

This may be due to the file `build/ios/archive/XYZ.xcarchive/Info.plist`:

```
$ cat build/ios/archive/XYZ.xcarchive/Info.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
...
	<key>ArchiveVersion</key>
	<integer>2</integer>
	<key>CreationDate</key>
	<date>2023-09-21T02:37:57Z</date>
	<key>Name</key>
	<string>Runner</string>
	<key>SchemeName</key>
	<string>Runner</string>
</dict>
</plist>
```

I was unable to find any source within my project for the `Runner` name here. It may be a lingering hard-coded string not addressed by #124533?


## Errors encountered

For the benefit of folks who may find this via search engine, here are some of the errors I dealt with when trying to get this to work:

```
missing module map file: '/Users/chuck/projects/XYZ/ios/Pods/Target Support Files/Pods-Runner/Pods-Runner.modulemap
/Users/chuck/projects/XYZ/ios/Pods/Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig:1:1 unable to open configuration settings file
Unable to load contents of file list: '/Target Support Files/Pods-XYZ/Pods-XYZ-frameworks-Debug-input-files.xcfilelist'
Unable to load contents of file list: '/Target Support Files/Pods-XYZ/Pods-XYZ-frameworks-Debug-output-files.xcfilelist'
```

```
Framework not found Pods_XYZ
Linker command failed with exit code 1 (use -v to see invocation)
```

```
Build input file cannot be found: '/Users/chuck/projects/XYZ/ios/Runner/Base.lproj/LaunchScreen.storyboard'. Did you forget to declare this file as an output of a script phase or custom build rule which produces it?
```

```
failed to emit precompiled header '/Users/chuck/Library/Developer/Xcode/DerivedData/XYZ-fpfmhkfomodrmueysbgwweumlsle/Build/Intermediates.noindex/PrecompiledHeaders/Runner-Bridging-Header-swift_31P3L1FFSO4MA-clang_25BF7UX6G48J0.pch' for bridging header '/Users/chuck/projects/XYZ/ios/Runner/Runner-Bridging-Header.h'
/Users/chuck/projects/XYZ/ios/Runner/Runner-Bridging-Header.h:1:9 'GeneratedPluginRegistrant.h' file not found
```

```
    rsync --delete -av --filter P .*.?????? --links --filter "- CVS/" --filter "- .svn/" --filter "- .git/" --filter "- .hg/" --filter "- Headers" --filter "- PrivateHeaders" --filter "- Modules" "../../../IntermediateBuildFilesPath/UninstalledProducts/iphoneos/in_app_purchase_storekit.framework" "/Users/chuck/Library/Developer/Xcode/DerivedData/XYZ-fpfmhkfomodrmueysbgwweumlsle/Build/Intermediates.noindex/ArchiveIntermediates/Runner/InstallationBuildProductsLocation/Applications/XYZ.app/Frameworks"
    building file list ... rsync: link_stat "/Users/chuck/projects/XYZ/ios/../../../IntermediateBuildFilesPath/UninstalledProducts/iphoneos/in_app_purchase_storekit.framework" failed: No such file or directory (2)
    done

    sent 29 bytes  received 20 bytes  98.00 bytes/sec
    total size is 0  speedup is 0.00
    rsync error: some files could not be transferred (code 23) at /AppleInternal/Library/BuildRoots/d9889869-120b-11ee-b796-7a03568b17ac/Library/Caches/com.apple.xbs/Sources/rsync/rsync/main.c(996) [sender=2.6.9]
    Command PhaseScriptExecution failed with a nonzero exit code
```

### Proposal

Please offer

- Comprehensive step-by-step instructions for renaming `Runner` in mature projects.
- A way to replace `Runner` that still appears in `.xcarchive` files generated by `flutter build ipa`.
- Or, a simpler, single location (i.e. "DRY") for the user to specify the Xcode project name.

Thank you.