Rename FlutterMacOS.framework to Flutter.framework

[jmagman]

Pros:

1. "MacOS" isn't as meaningful with Catalyst, universal apps, etc. Really, for Flutter it means "links on AppKit".
2. iOS Flutter.framework will soon be distributed as an XCFramework to support ARM iOS simulators. XCFrameworks can encode slices for any darwin platform (ios, macos, catalyst, etc). Future watchOS, tvOS, and Catalyst support could be added to the same XCFramework.
3. Flutter.framework and FlutterMacOS.framework currently share common .h and .m files. The different names mean that Fix all "Double-quoted include in framework header, expected angle-bracketed instead" warnings #60025 (comment) cannot be easily fixed.
4. This matches Apple's own conventions. For example, the CloudKit framework is named the same on every platform--there is no CloudKitWatch framework.

Cons:
The tool will no longer download macOS desktop engine artifacts separately. This will increase the artifact cache size for iOS developers who are not building macOS apps, and vice versa. This will not impact app size.

Work:

1. Engine files need to be updated to import and build a macOS Flutter.framework variant.
2. Adopt XCFramework
3. Move the linking and embedding logic out of the Xcode project and into the tool
4. Tool caching logic needs to be updated to download the common engine artifacts.

[stuartmorgan]

IIRC the only reason we called it FlutterMacOS was because of concerns about having two different frameworks with the same filename being potentially very confusing (@chinmaygarde does that match your memory of our discussion?), so if we combine everything into a single xcframework there wouldn't be any reason to keep the different naming. (The title says "Flutter.framework" not "Flutter.xcframework"; is that a typo? I don't think we should do this separately from adopting xcframework.)

Missing from the work list:

• Write a migrator for all existing macOS projects

And then more importantly, a combination of Con and Work:

• This will be a breaking change for all existing macOS plugins, creating a situation where every macOS plugin will have to publish a breaking-change new version; no apps will be able to update until all the plugins they rely on are updated, and conversely nobody whose project includes macOS will be able to update any of those plugins until they update all of them, and Flutter, potentially creating situations where, e.g., an app can't pick up an iOS bug fix in plugin A because they need plugin B to publish an updated version first to avoid breaking macOS build.

[jmagman]

The title says "Flutter.framework" not "Flutter.xcframework"; is that a typo? I don't think we should do this separately from adopting xcframework.

We have to keep all the Flutter.frameworks, then they get stitched together in a Flutter.xcframework. Agree, we can't do this without the xcframework work.

• Write a migrator for all existing macOS projects

You're right, the import FlutterMacOS need to be swapped out with import Flutter in the Swift files. The project file migration can be done with #56581, independent of the name change.

And then more importantly, a combination of Con and Work:

• This will be a breaking change for all existing macOS plugins, creating a situation where every macOS plugin will have to publish a breaking-change new version; no apps will be able to update until all the plugins they rely on are updated, and conversely nobody whose project includes macOS will be able to update any of those plugins until they update all of them, and Flutter, potentially creating situations where, e.g., an app can't pick up an iOS bug fix in plugin A because they need plugin B to publish an updated version first to avoid breaking macOS build.

Good point, I forgot about this.

flutter/packages/flutter_tools/templates/plugin/macos.tmpl/projectName.podspec.tmpl

Line 17 in 856a90e

s.dependency 'FlutterMacOS'

[jmagman]

• This will be a breaking change for all existing macOS plugins, creating a situation where every macOS plugin will have to publish a breaking-change new version; no apps will be able to update until all the plugins they rely on are updated, and conversely nobody whose project includes macOS will be able to update any of those plugins until they update all of them, and Flutter, potentially creating situations where, e.g., an app can't pick up an iOS bug fix in plugin A because they need plugin B to publish an updated version first to avoid breaking macOS build.

Good point, I forgot about this.

flutter/packages/flutter_tools/templates/plugin/macos.tmpl/projectName.podspec.tmpl

Line 17 in 856a90e

s.dependency 'FlutterMacOS'

Actually that part may not need to change--the pod can be named something different than the vendored_framework. The more important part is to migrate any import FlutterMacOS to import Flutter in existing plugins, same as existing projects, but with the version complications @stuartmorgan mentions.

[stuartmorgan]

If it's just the imports, then it sounds like we could avoid a lot of the transition headache by re-exporting. So we would

• Restructure the current framework into Flutter and FlutterMacOS
  • Flutter would have all the actual code
  • FlutterMacOS would be a container that just exported Flutter (like Cocoa)
• Once that's reached dev channel (macOS is still master and dev only), we update all the plugins we can find publicly to import Flutter instead.
• We announce a breaking change to remove FlutterMacOS, and after some period of time remove it.

The caveat is that I haven't verified that this works in practice, but if it does things get a lot easier :)

[jmagman]

If it's just the imports, then it sounds like we could avoid a lot of the transition headache by re-exporting.

That's exactly what I was thinking! We need to keep the two frameworks as you say because if the module name doesn't match the framework name on the file system, it won't be found (as I understand it). Meaning, we can't have Flutter just add a FlutterMacOS module.

[flutter-triage-bot]

This issue is assigned to @vashworth but has had no recent status updates. Please consider unassigning this issue if it is not going to be addressed in the near future. This allows people to have a clearer picture of what work is actually planned. Thanks!