Add shared Darwin implementation for plugins (flutter#176495)

This PR introduces support for creating Flutter plugins with a single,
shared implementation for iOS and macOS. This is enabled by a new darwin
platform option in the flutter create command, which simplifies code
maintenance and reduces duplication for plugin authors.

*List which issues are fixed by this PR. You must list at least one
issue. An issue is not required if the PR fixes something trivial like a
typo.*
Fixes flutter#161019 

*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

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

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

Author: okorohelijah

dev/devicelab/bin/tasks/plugin_test_ios.dart

@@ -19,6 +19,8 @@ Future<void> main() async {
       PluginTest('ios', <String>['--platforms=ios,macos'], sharedDarwinSource: true).call,
       // Test that FFI plugins are supported.
       PluginTest('ios', <String>['--platforms=ios'], template: 'plugin_ffi').call,
+      // Test that plugins support the darwin platform.
+      PluginTest('ios', <String>['--platforms=darwin']).call,
     ]),
   );
 }

dev/devicelab/bin/tasks/plugin_test_macos.dart

@@ -15,6 +15,8 @@ Future<void> main() async {
       PluginTest('macos', <String>['--platforms=ios,macos'], sharedDarwinSource: true).call,
       // Test that FFI plugins are supported.
       PluginTest('macos', <String>['--platforms=macos'], template: 'plugin_ffi').call,
+      // Test that plugins support the darwin platform.
+      PluginTest('macos', <String>['--platforms=darwin']).call,
     ]),
   );
 }

dev/devicelab/lib/tasks/plugin_tests.dart

@@ -427,7 +427,7 @@ public class $pluginClass: NSObject, FlutterPlugin {
           '--template=$template',
           '--org',
           'io.flutter.devicelab',
-          ...options,
+          if (template == 'app' && isDarwin) '--platforms=$target' else ...options,
           name,
         ],
         environment: environment,
@@ -490,35 +490,44 @@ end
   // Make the platform version artificially low to test that the "deployment
   // version too low" warning is never emitted.
   void _reduceDarwinPluginMinimumVersion(String plugin, String target) {
-    final podspec = File(path.join(rootPath, target, '$plugin.podspec'));
+    var podspec = File(path.join(rootPath, target, '$plugin.podspec'));
+    if (!podspec.existsSync()) {
+      // Fallback to darwin directory for shared darwin plugins
+      podspec = File(path.join(rootPath, 'darwin', '$plugin.podspec'));
+    }
     if (!podspec.existsSync()) {
       throw TaskResult.failure('podspec file missing at ${podspec.path}');
     }
-    final versionString = target == 'ios'
-        ? "s.platform = :ios, '13.0'"
-        : "s.platform = :osx, '10.11'";
     String podspecContent = podspec.readAsStringSync();
+    final bool isMultiPlatform = podspecContent.contains('s.osx.deployment_target');
+    final String versionString;
+    if (isMultiPlatform) {
+      versionString = target == 'ios'
+          ? "s.ios.deployment_target = '13.0'"
+          : "s.osx.deployment_target = '10.15'";
+    } else {
+      versionString = target == 'ios' ? "s.platform = :ios, '13.0'" : "s.platform = :osx, '10.11'";
+    }
+
     if (!podspecContent.contains(versionString)) {
       throw TaskResult.failure(
         'Update this test to match plugin minimum $target deployment version',
       );
     }
     // Add transitive dependency on AppAuth 1.6 targeting iOS 8 and macOS 10.9, which no longer builds in Xcode
     // to test the version is forced higher and builds.
-    const iosContent = '''
-s.platform = :ios, '10.0'
-s.dependency 'AppAuth', '1.6.0'
-''';
-
-    const macosContent = '''
-s.platform = :osx, '10.8'
-s.dependency 'AppAuth', '1.6.0'
-''';
+    final String replacementContent;
+    if (isMultiPlatform) {
+      replacementContent = target == 'ios'
+          ? "s.ios.deployment_target = '10.0'\n  s.dependency 'AppAuth', '1.6.0'"
+          : "s.osx.deployment_target = '10.8'\n  s.dependency 'AppAuth', '1.6.0'";
+    } else {
+      replacementContent = target == 'ios'
+          ? "s.platform = :ios, '10.0'\ns.dependency 'AppAuth', '1.6.0'"
+          : "s.platform = :osx, '10.8'\ns.dependency 'AppAuth', '1.6.0'";
+    }
 
-    podspecContent = podspecContent.replaceFirst(
-      versionString,
-      target == 'ios' ? iosContent : macosContent,
-    );
+    podspecContent = podspecContent.replaceFirst(versionString, replacementContent);
     podspec.writeAsStringSync(podspecContent, flush: true);
   }
 

packages/flutter_tools/lib/src/commands/create.dart

@@ -104,7 +104,13 @@ class CreateCommand extends FlutterCommand with CreateBase {
           'internally and should generally not be used manually.',
       hide: !verboseHelp,
     );
-    addPlatformsOptions(customHelp: kPlatformHelp);
+
+    final Map<String, String> platformsAllowedHelp = {
+      for (final String p in kAllCreatePlatforms) p: '',
+    };
+    platformsAllowedHelp['darwin'] =
+        'A shared platform for iOS and macOS. (only supported for plugins)';
+    addPlatformsOptions(customHelp: kPlatformHelp, allowedHelp: platformsAllowedHelp);
 
     final List<ParsedFlutterTemplateType> enabledTemplates =
         ParsedFlutterTemplateType.enabledValues(featureFlags);
@@ -356,6 +362,7 @@ class CreateCommand extends FlutterCommand with CreateBase {
 
     final String dartSdk = globals.cache.dartSdkBuild;
     final bool includeIos;
+    final bool includeDarwin;
     final bool includeAndroid;
     final bool includeWeb;
     final bool includeLinux;
@@ -369,6 +376,7 @@ class CreateCommand extends FlutterCommand with CreateBase {
       includeLinux = false;
       includeMacos = false;
       includeWindows = false;
+      includeDarwin = false;
     } else if (template == FlutterTemplateType.package) {
       // The package template does not supports any platform.
       includeIos = false;
@@ -377,12 +385,32 @@ class CreateCommand extends FlutterCommand with CreateBase {
       includeLinux = false;
       includeMacos = false;
       includeWindows = false;
+      includeDarwin = false;
     } else {
-      includeIos = featureFlags.isIOSEnabled && platforms.contains('ios');
+      final bool darwinRequested = platforms.contains('darwin');
+      final bool darwinSupported =
+          (template == FlutterTemplateType.plugin) &&
+          featureFlags.isIOSEnabled &&
+          featureFlags.isMacOSEnabled;
+
+      if (darwinRequested && darwinSupported) {
+        includeDarwin = true;
+        includeIos = true;
+        includeMacos = true;
+      } else {
+        includeDarwin = false;
+        includeIos = featureFlags.isIOSEnabled && platforms.contains('ios');
+        includeMacos = featureFlags.isMacOSEnabled && platforms.contains('macos');
+        if (darwinRequested && !darwinSupported) {
+          globals.printWarning(
+            'Warning: To use the "darwin" platform, you must have both iOS and macOS enabled.\n'
+            'Run "flutter config --enable-ios --enable-macos-desktop" and try again.',
+          );
+        }
+      }
       includeAndroid = featureFlags.isAndroidEnabled && platforms.contains('android');
       includeWeb = featureFlags.isWebEnabled && platforms.contains('web');
       includeLinux = featureFlags.isLinuxEnabled && platforms.contains('linux');
-      includeMacos = featureFlags.isMacOSEnabled && platforms.contains('macos');
       includeWindows = featureFlags.isWindowsEnabled && platforms.contains('windows');
     }
 
@@ -418,6 +446,7 @@ class CreateCommand extends FlutterCommand with CreateBase {
       iosDevelopmentTeam: developmentTeam,
       ios: includeIos,
       android: includeAndroid,
+      darwin: includeDarwin,
       web: includeWeb,
       linux: includeLinux,
       macos: includeMacos,
@@ -529,9 +558,9 @@ class CreateCommand extends FlutterCommand with CreateBase {
         await project.ensureReadyForPlatformSpecificTooling(
           releaseMode: ignoreReleaseModeSinceItsNotABuildAndHopeItWorks,
           androidPlatform: includeAndroid,
-          iosPlatform: includeIos,
+          iosPlatform: includeIos || includeDarwin,
           linuxPlatform: includeLinux,
-          macOSPlatform: includeMacos,
+          macOSPlatform: includeMacos || includeDarwin,
           windowsPlatform: includeWindows,
           webPlatform: includeWeb,
         );
@@ -697,10 +726,28 @@ Your $application code is in $relativeAppMain.
     templateContext['description'] = description;
 
     final projectName = templateContext['projectName'] as String?;
+    final bool includeDarwin = templateContext['darwin'] as bool? ?? false;
+    final bool originalIos = templateContext['ios'] as bool? ?? false;
+    final bool originalMacos = templateContext['macos'] as bool? ?? false;
+    if (includeDarwin) {
+      // Temporarily disable ios/macos for the plugin generation
+      // so we don't get ios/ and macos/ directories in the plugin root.
+      templateContext['ios'] = false;
+      templateContext['macos'] = false;
+    }
+
     final templates = <String>['plugin', 'plugin_shared'];
-    if ((templateContext['ios'] == true || templateContext['macos'] == true) &&
-        featureFlags.isSwiftPackageManagerEnabled) {
-      templates.add('plugin_swift_package_manager');
+
+    final bool useSwiftPackageManager =
+        (templateContext['ios'] == true || templateContext['macos'] == true || includeDarwin) &&
+        featureFlags.isSwiftPackageManagerEnabled;
+
+    if (useSwiftPackageManager) {
+      if (includeDarwin) {
+        templates.add('plugin_darwin_spm');
+      } else {
+        templates.add('plugin_swift_package_manager');
+      }
       templateContext['swiftLibraryName'] = projectName?.replaceAll('_', '-');
       templateContext['swiftToolsVersion'] = minimumSwiftToolchainVersion;
       templateContext['iosSupportedPlatform'] = FlutterDarwinPlatform.ios.supportedPackagePlatform
@@ -710,16 +757,24 @@ Your $application code is in $relativeAppMain.
           .supportedPackagePlatform
           .format();
     } else {
-      templates.add('plugin_cocoapods');
+      if (includeDarwin) {
+        templates.add('plugin_darwin_cocoapods');
+      } else {
+        templates.add('plugin_cocoapods');
+      }
     }
-
     generatedCount += await renderMerged(
       templates,
       directory,
       templateContext,
       overwrite: overwrite,
       printStatusWhenWriting: printStatusWhenWriting,
     );
+    // Restore the original ios and macos values.
+    // This is necessary in case the user requested the darwin platform,
+    // and we need to restore them for the example app generation.
+    templateContext['ios'] = originalIos;
+    templateContext['macos'] = originalMacos;
 
     final FlutterProject project = FlutterProject.fromDirectory(directory);
     final generateAndroid = templateContext['android'] == true;
@@ -984,6 +1039,10 @@ List<String> _getPlatformWarningList(List<String> requestedPlatforms) {
     if (requestedPlatforms.contains('macos') && !featureFlags.isMacOSEnabled) 'macos',
     if (requestedPlatforms.contains('windows') && !featureFlags.isWindowsEnabled) 'windows',
     if (requestedPlatforms.contains('linux') && !featureFlags.isLinuxEnabled) 'linux',
+    if (requestedPlatforms.contains('darwin') &&
+        !featureFlags.isMacOSEnabled &&
+        !featureFlags.isIOSEnabled)
+      'darwin',
   ];
 
   return platformsToWarn;
@@ -992,13 +1051,16 @@ List<String> _getPlatformWarningList(List<String> requestedPlatforms) {
 void _printWarningDisabledPlatform(List<String> platforms) {
   final desktop = <String>[];
   final web = <String>[];
+  final darwin = <String>[];
 
   for (final platform in platforms) {
     switch (platform) {
       case 'web':
         web.add(platform);
       case 'macos' || 'windows' || 'linux':
         desktop.add(platform);
+      case 'darwin':
+        darwin.add(platform);
     }
   }
 
@@ -1015,6 +1077,12 @@ For more details, see: https://flutter.dev/to/add-desktop-support
     globals.printStatus('''
 The web is currently not supported on your local environment.
 For more details, see: https://flutter.dev/to/add-web-support
+''');
+  }
+  if (darwin.isNotEmpty) {
+    globals.printStatus('''
+The darwin platform is currently not supported on your local environment.
+You must have a macOS host with Xcode installed to develop for iOS or macOS.
 ''');
   }
 }

packages/flutter_tools/lib/src/commands/create_base.dart

@@ -22,7 +22,15 @@ const _kAvailablePlatforms = <String>['ios', 'android', 'windows', 'linux', 'mac
 
 /// A list of all possible create platforms, even those that may not be enabled
 /// with the current config.
-const kAllCreatePlatforms = <String>['ios', 'android', 'windows', 'linux', 'macos', 'web'];
+const kAllCreatePlatforms = <String>[
+  'ios',
+  'android',
+  'windows',
+  'linux',
+  'macos',
+  'web',
+  'darwin',
+];
 
 const _kDefaultPlatformArgumentHelp =
     '(required) The platforms supported by this project. '
@@ -94,13 +102,14 @@ mixin CreateBase on FlutterCommand {
   ///
   /// The help message of the argument is replaced with `customHelp` if `customHelp` is not null.
   @protected
-  void addPlatformsOptions({String? customHelp}) {
+  void addPlatformsOptions({String? customHelp, required Map<String, String> allowedHelp}) {
     argParser.addMultiOption(
       'platforms',
       help: customHelp ?? _kDefaultPlatformArgumentHelp,
       aliases: <String>['platform'],
       defaultsTo: <String>[..._kAvailablePlatforms],
-      allowed: <String>[..._kAvailablePlatforms],
+      allowed: <String>[...kAllCreatePlatforms],
+      allowedHelp: allowedHelp,
     );
   }
 
@@ -312,6 +321,7 @@ mixin CreateBase on FlutterCommand {
     bool linux = false,
     bool macos = false,
     bool windows = false,
+    bool darwin = false,
     bool implementationTests = false,
   }) {
     final String pluginDartClass = _createPluginClassName(projectName);
@@ -336,6 +346,7 @@ mixin CreateBase on FlutterCommand {
       'androidIdentifier': androidIdentifier,
       'iosIdentifier': appleIdentifier,
       'macosIdentifier': appleIdentifier,
+      'darwinIdentifier': appleIdentifier,
       'linuxIdentifier': linuxIdentifier,
       'windowsIdentifier': windowsIdentifier,
       'description': projectDescription,
@@ -365,6 +376,8 @@ mixin CreateBase on FlutterCommand {
       'web': web,
       'linux': linux,
       'macos': macos,
+      'darwin': darwin,
+      'sharedDarwinSource': darwin,
       'windows': windows,
       'year': DateTime.now().year,
       'dartSdkVersionBounds': dartSdkVersionBounds,
@@ -469,6 +482,7 @@ mixin CreateBase on FlutterCommand {
     final bool macOSPlatform = templateContext['macos'] as bool? ?? false;
     final bool windowsPlatform = templateContext['windows'] as bool? ?? false;
     final bool webPlatform = templateContext['web'] as bool? ?? false;
+    final bool darwinPlatform = templateContext['darwin'] as bool? ?? false;
 
     final platformsForMigrateConfig = <SupportedPlatform>[SupportedPlatform.root];
     if (androidPlatform) {
@@ -484,6 +498,14 @@ mixin CreateBase on FlutterCommand {
     if (macOSPlatform) {
       platformsForMigrateConfig.add(SupportedPlatform.macos);
     }
+    if (darwinPlatform) {
+      if (!platformsForMigrateConfig.contains(SupportedPlatform.ios)) {
+        platformsForMigrateConfig.add(SupportedPlatform.ios);
+      }
+      if (!platformsForMigrateConfig.contains(SupportedPlatform.macos)) {
+        platformsForMigrateConfig.add(SupportedPlatform.macos);
+      }
+    }
     if (webPlatform) {
       platformsForMigrateConfig.add(SupportedPlatform.web);
     }