Add Swift Package Manager docs (#10827)

Flutter iOS/macOS is migrating to Swift Package Manager for native
dependencies. This is an experimental feature this isn't ready yet for
app developers. However, plugin authors should add Swift Package Manager
support to their packages.

The faster plugin authors add SwiftPM support, the sooner we can drop
CocoaPods (and make it easier to install Flutter iOS!). There's [~10K
Flutter iOS
plugins](https://gist.github.com/loic-sharma/891a358f8abab36133e8a9395f719296)
that'll need to migrate, so we really need the plugin migration docs to
be as easy to follow as possible. Any and all feedback is appreciated!
:)
 
This is based off @vashworth's
[guide](flutter/flutter#146256 (comment)).

Question for reviewers: What do you think of the doc structure? Should
we rearrange things to make it clearer that some sections are to be
followed when things go wrong? Or is the current structure clear enough?

Preview URLs:

1. [Swift Package Manager for app
developers](https://flutter-docs-prod--pr10827-spm-compatibility-ilxd3b00.web.app/packages-and-plugins/swift-package-manager/for-app-developers)
2. [Swift Package Manager for plugin authors

](https://flutter-docs-prod--pr10827-spm-compatibility-ilxd3b00.web.app/packages-and-plugins/swift-package-manager/for-plugin-authors)

Part of flutter/flutter#126005

## Presubmit checklist

- [ ] This PR is marked as draft with an explanation if not meant to
land until a future stable release.
- [x] This PR doesn’t contain automatically generated corrections
(Grammarly or similar).
- [x] This PR follows the [Google Developer Documentation Style
Guidelines](https://developers.google.com/style) — for example, it
doesn’t use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first person).
- [x] This PR uses [semantic line
breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks)
of 80 characters or fewer.

src/_data/sidenav.yml

@@ -506,6 +506,13 @@
       permalink: /packages-and-plugins/using-packages
     - title: Develop packages & plugins
       permalink: /packages-and-plugins/developing-packages
+    - title: Swift Package Manager
+      permalink: /packages-and-plugins/swift-package-manager
+      children:
+        - title: For app developers
+          permalink: /packages-and-plugins/swift-package-manager/for-app-developers
+        - title: For plugin authors
+          permalink: /packages-and-plugins/swift-package-manager/for-plugin-authors
     - divider
     - title: Flutter Favorites
       permalink: /packages-and-plugins/favorites

src/_includes/docs/swift-package-manager/how-to-enable-disable.md

@@ -0,0 +1,78 @@
+## How to turn on Swift Package Manager
+
+Flutter's Swift Package Manager support is turned off by default.
+To turn it on:
+
+1. Switch to Flutter's `main` channel:
+
+   ```sh
+   flutter channel main
+   ```
+
+2. Make sure you have the latest Flutter SDK:
+
+   ```sh
+   flutter upgrade
+   ```
+
+3. Turn on the Swift Package Manager feature:
+
+   ```sh
+   flutter config --enable-swift-package-manager
+   ```
+
+Using the Flutter CLI to run an app modifies the project to add Swift Package
+Manager integration.
+This makes your project download the Swift packages that
+your Flutter plugins depend on.
+
+Flutter falls back to CocoaPods for dependencies that do not support Swift
+Package Manager yet.
+
+## How to turn off Swift Package Manager
+
+:::secondary Plugin authors
+Plugin authors need to turn on and off Flutter's Swift Package Manager
+support for testing.
+App developers do not need to disable Swift Package Manager support,
+unless they are running into issues.
+
+If you find a bug in Flutter's Swift Package Manager support,
+[open an issue][].
+:::
+
+Disabling Swift Package Manager causes Flutter to use CocoaPods for all
+dependencies.
+However, Swift Package Manager remains integrated with your project.
+To remove Swift Package Manager integration completely from your project,
+follow the [How to remove Swift Package Manager integration][removeSPM]
+instructions.
+
+### Turn off for a single project
+
+In the project's `pubspec.yaml` file, under the `flutter` section,
+add `disable-swift-package-manager: true`.
+
+```yaml title="pubspec.yaml"
+# The following section is specific to Flutter packages.
+flutter:
+  disable-swift-package-manager: true
+```
+
+This turns off Swift Package Manager for all contributors to this project.
+
+### Turn off globally for all projects
+
+Run the following command:
+
+```sh
+flutter config --no-enable-swift-package-manager
+```
+
+This turns off Swift Package Manager for the current user.
+
+If a project is incompatible with Swift Package Manager, all contributors
+need to run this command. 
+
+[removeSPM]: /packages-and-plugins/swift-package-manager/for-app-developers#how-to-remove-swift-package-manager-integration
+[open an issue]: {{site.github}}/flutter/flutter/issues/new?template=2_bug.yml

src/_includes/docs/swift-package-manager/migrate-ios-project-manually.md

@@ -0,0 +1,85 @@
+Once you [turn on Swift Package Manager][], the Flutter CLI tries to migrate
+your project to use Swift Package Manager the next time you run your app
+using the CLI.
+
+However, the Flutter CLI tool might be unable to migrate your project
+automatically if there are unexpected modifications.
+
+If the automatic migration fails, use the steps below to add Swift Package
+Manager integration to a project manually.
+
+Before migrating manually, [file an issue][]; this helps the Flutter team
+improve the automatic migration process.
+Include the error message and, if possible, include a copy of
+the following files in your issue:
+
+* `ios/Runner.xcodeproj/project.pbxproj`
+* `ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme`
+   (or the xcsheme for the flavor used)
+
+### Step 1: Add FlutterGeneratedPluginSwiftPackage Package Dependency {:.no_toc}
+
+1. Open your app (`ios/Runner.xcworkspace`) in Xcode.
+2. Navigate to **Package Dependencies** for the project.
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/package-dependencies.png",
+   caption:"The project's package dependencies" %}
+
+3. Click <span class="material-symbols-outlined">add</span>.
+4. In the dialog that opens, click **Add Local...**.
+5. Navigate to `ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage`
+   and click **Add Package**.
+6. Ensure that it's added to the `Runner` target and click **Add Package**.
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/choose-package-products.png",
+   caption:"Ensure that the package is added to the `Runner` target" %}
+
+7. Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks,
+   Libraries, and Embedded Content**.
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/add-generated-framework.png",
+   caption:"Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks, Libraries, and Embedded Content**" %}
+
+### Step 2: Add Run Prepare Flutter Framework Script Pre-Action {:.no_toc}
+
+**The following steps must be completed for each flavor.**
+
+1. Go to **Product > Scheme > Edit Scheme**.
+2. Expand the **Build** section in the left side bar.
+3. Click **Pre-actions**.
+4. Click <span class="material-symbols-outlined">add</span> and
+   select **New Run Script Action** from the menu.
+5. Click the **Run Script** title and change it to:
+
+   ```plaintext
+   Run Prepare Flutter Framework Script
+   ```
+
+6. Change the **Provide build settings from** to the `Runner` app.
+7. Input the following in the text box:
+
+   ```sh
+   "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" prepare
+   ```
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/add-flutter-pre-action.png",
+   caption:"Add **Run Prepare Flutter Framework Script** build pre-action" %}
+
+### Step 3: Run app {:.no_toc}
+
+1. Run the app in Xcode.
+2. Ensure that  **Run Prepare Flutter Framework Script** runs as a pre-action
+   and that `FlutterGeneratedPluginSwiftPackage` is a target dependency.
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png",
+   caption:"Ensure **Run Prepare Flutter Framework Script** runs as a pre-action" %}
+
+3. Ensure that the app runs on the command line with `flutter run`.
+
+[turn on Swift Package Manager]: /packages-and-plugins/swift-package-manager/for-app-developers/#how-to-turn-on-swift-package-manager
+[file an issue]: {{site.github}}/flutter/flutter/issues/new?template=2_bug.yml

src/_includes/docs/swift-package-manager/migrate-ios-project.md

@@ -0,0 +1,38 @@
+Once you [turn on Swift Package Manager][], the Flutter CLI tries to migrate
+your project the next time you run your app using the CLI.
+This migration updates your Xcode project to use Swift Package Manager to
+add Flutter plugin dependencies.
+
+To migrate your project:
+
+1. [Turn on Swift Package Manager][].
+
+2. Run the iOS app using the Flutter CLI.
+
+   If your iOS project doesn't have Swift Package Manager integration yet, the
+   Flutter CLI tries to migrate your project and outputs something like:
+
+   ```console
+   $ flutter run
+   Adding Swift Package Manager integration...
+   ```
+
+   The automatic iOS migration modifies the
+   `ios/Runner.xcodeproj/project.pbxproj` and
+   `ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme` files.
+
+3. If the Flutter CLI's automatic migration fails, follow the steps in
+   [add Swift Package Manager integration manually][manualIntegration].
+
+[Optional] To check if your project is migrated:
+
+1. Run the app in Xcode.
+2. Ensure that  **Run Prepare Flutter Framework Script** runs as a pre-action
+   and that `FlutterGeneratedPluginSwiftPackage` is a target dependency.
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png",
+   caption:"Ensure **Run Prepare Flutter Framework Script** runs as a pre-action" %}
+
+[Turn on Swift Package Manager]: /packages-and-plugins/swift-package-manager/for-app-developers/#how-to-turn-on-swift-package-manager
+[manualIntegration]: /packages-and-plugins/swift-package-manager/for-app-developers/#add-to-a-flutter-app-manually

src/_includes/docs/swift-package-manager/migrate-macos-project-manually.md

@@ -0,0 +1,85 @@
+Once you [turn on Swift Package Manager][], the Flutter CLI tries to migrate
+your project to use Swift Package Manager the next time you run your app
+using the CLI.
+
+However, the Flutter CLI tool might be unable to migrate your project
+automatically if there are unexpected modifications.
+
+If the automatic migration fails, use the steps below to add Swift Package
+Manager integration to a project manually.
+
+Before migrating manually, [file an issue][]; this helps the Flutter team
+improve the automatic migration process.
+Include the error message and, if possible, include a copy of
+the following files in your issue:
+
+* `macos/Runner.xcodeproj/project.pbxproj`
+* `macos/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme`
+  (or the xcscheme for the flavor used)
+
+### Step 1: Add FlutterGeneratedPluginSwiftPackage Package Dependency {:.no_toc}
+
+1. Open your app (`macos/Runner.xcworkspace`) in Xcode.
+2. Navigate to **Package Dependencies** for the project.
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/package-dependencies.png",
+   caption:"The project's package dependencies" %}
+
+3. Click <span class="material-symbols-outlined">add</span>.
+4. In the dialog that opens, click the **Add Local...**.
+5. Navigate to `macos/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage`
+   and click the **Add Package**.
+6. Ensure that it's added to the Runner Target and click **Add Package**.
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/choose-package-products.png",
+   caption:"Ensure that the package is added to the `Runner` target" %}
+
+7. Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks,
+   Libraries, and Embedded Content**.
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/add-generated-framework.png",
+   caption:"Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks, Libraries, and Embedded Content**" %}
+
+### Step 2: Add Run Prepare Flutter Framework Script Pre-Action {:.no_toc}
+
+**The following steps must be completed for each flavor.**
+
+1. Go to **Product > Scheme > Edit Scheme**.
+2. Expand the **Build** section in the left side bar.
+3. Click **Pre-actions**.
+4. Click the <span class="material-symbols-outlined">add</span> button
+   and select **New Run Script Action** from the menu.
+5. Click the **Run Script** title and change it to:
+
+   ```plaintext
+   Run Prepare Flutter Framework Script
+   ```
+
+6. Change the **Provide build settings from** to the `Runner` target.
+7. Input the following in the text box:
+
+   ```sh
+   "$FLUTTER_ROOT"/packages/flutter_tools/bin/macos_assemble.sh prepare
+   ```
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/add-flutter-pre-action.png",
+   caption:"Add **Run Prepare Flutter Framework Script** build pre-action" %}
+
+### Step 3: Run app {:.no_toc}
+
+1. Run the app in Xcode.
+2. Ensure that  **Run Prepare Flutter Framework Script** runs as a pre-action
+   and that `FlutterGeneratedPluginSwiftPackage` is a target dependency.
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png",
+   caption:"Ensure `Run Prepare Flutter Framework Script` runs as a pre-action" %}
+
+3. Ensure that the app runs on the command line with `flutter run`.
+
+[turn on Swift Package Manager]: /packages-and-plugins/swift-package-manager/for-app-developers/#how-to-turn-on-swift-package-manager
+[file an issue]: {{site.github}}/flutter/flutter/issues/new?template=2_bug.yml

src/_includes/docs/swift-package-manager/migrate-macos-project.md

@@ -0,0 +1,38 @@
+Once you [turn on Swift Package Manager][], the Flutter CLI tries to migrate
+your project the next time you run your app using the CLI.
+This migration updates your Xcode project to use Swift Package Manager to
+add Flutter plugin dependencies.
+
+To migrate your project:
+
+1. [Turn on Swift Package Manager][].
+
+2. Run the macOS app using the Flutter CLI.
+
+   If your macOS project doesn't have Swift Package Manager integration yet, the
+   Flutter CLI tries to migrate your project and outputs something like:
+
+   ```console
+   $ flutter run -d macos
+   Adding Swift Package Manager integration...
+   ```
+
+   The automatic iOS migration modifies the
+   `macos/Runner.xcodeproj/project.pbxproj` and
+   `macos/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme` files.
+
+3. If the Flutter CLI's automatic migration fails, follow the steps in
+   [add Swift Package Manager integration manually][manualIntegration].
+
+[Optional] To check if your project is migrated:
+
+1. Run the app in Xcode.
+2. Ensure that  **Run Prepare Flutter Framework Script** runs as a pre-action
+   and that `FlutterGeneratedPluginSwiftPackage` is a target dependency.
+
+   {% render docs/captioned-image.liquid,
+   image:"development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png",
+   caption:"Ensure **Run Prepare Flutter Framework Script** runs as a pre-action" %}
+
+[Turn on Swift Package Manager]: /packages-and-plugins/swift-package-manager/for-app-developers/#how-to-turn-on-swift-package-manager
+[manualIntegration]: /packages-and-plugins/swift-package-manager/for-app-developers/#add-to-a-flutter-app-manually