Add Swift Package Manager docs

src/_data/sidenav.yml

@@ -502,6 +502,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