Show the changes I'm making to the Flutter Wiki to add information about `--local-host-engine`

flutter-wiki-local-host-engine.diff

diff --git a/Comparing-AOT-Snapshot-Sizes.md b/Comparing-AOT-Snapshot-Sizes.md
index 2355d82..a5631cc 100644
--- a/Comparing-AOT-Snapshot-Sizes.md
+++ b/Comparing-AOT-Snapshot-Sizes.md
@@ -1,10 +1,10 @@
 These instructions can be used to prepare a tabulated summary of the differences in the sizes of two AOT snapshots. The instructions assume that the Flutter Engine has been [setup](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment) on the host (at `FLUTTER_ENGINE` in these instructions).
 
-Build the AOT snapshot (`flutter build aot`) for the application but pass in the `--verbose` flag. We need to find the `gen_snapshot` invocation and re-run it with an extra option (`--print-instructions-sizes-to`). If you are instrumenting with a local engine, the `flutter build` takes the `--local-engine` flag as well.
+Build the AOT snapshot (`flutter build aot`) for the application but pass in the `--verbose` flag. We need to find the `gen_snapshot` invocation and re-run it with an extra option (`--print-instructions-sizes-to`). If you are instrumenting with a local engine, the `flutter build` [takes a `--local-engine` and `--local-host-engine` flag](https://github.com/flutter/flutter/wiki/Debugging-the-engine#running-a-flutter-app-with-a-local-engine) as well.
 
 Here is an example of the updated invocation. Specify the path to a JSON file that acts as a summary (`SUMMARY_LOCATION` in these instructions) as follows.
 
-```
+```bash
 $FLUTTER_ENGINE/out/host_debug_unopt/gen_snapshot                    \
   --print-instructions-sizes-to=$SUMMARY_LOCATION                    \
   --causal_async_stacks                                              \
diff --git a/Custom-Flutter-Engine-Embedding-in-AOT-Mode.md b/Custom-Flutter-Engine-Embedding-in-AOT-Mode.md
index e9a310f..732927b 100644
--- a/Custom-Flutter-Engine-Embedding-in-AOT-Mode.md
+++ b/Custom-Flutter-Engine-Embedding-in-AOT-Mode.md
@@ -45,11 +45,12 @@ There are two separate steps involved in the generation of AOT instructions for
 
 Both iOS and Android AOT modes need to do this step when they build their artifacts. So, if the embedder targets are similar, the workflow supported by the Flutter tooling can be repurposed for custom AOT embedders. For example, in the case of `aarch64` AOT instructions for Android like targets, the following instructions will generated the four AOT blobs in the intermediates.
 
-```
-flutter --local-engine <local_engine_configuration> build aot --target-platform android-arm64 --release
+```bash
+flutter --local-engine <local_engine_configuration> --local-host-engine <local_host_engine_configuration> build aot --target-platform android-arm64 --release
 ```
 
-**Note:** The `--local-engine` flag is technically optional. However, not specifying the flag will make the tools pick the released version on of the Flutter engine. This version may contain subtle version mismatches with the engine you are using to prepare the `gen_snapshot` binary. So it is safer to just make sure the version are the same.
+**Note:** The `--local-engine` (and `--local-host-engine`) flag is technically optional. However, not specifying the flag will make the tools pick the released version on of the Flutter engine. This version may contain subtle version mismatches with the engine you are using to prepare the `gen_snapshot` binary. So it is safer to just make sure the version are the same.
+See [running with a local engine](https://github.com/flutter/flutter/wiki/Debugging-the-engine#running-a-flutter-app-with-a-local-engine) for more details.
 
 The result of the invocation will be the generation of the following binary blobs in the `build/aot directory`:
 
diff --git a/Debugging-the-engine.md b/Debugging-the-engine.md
index 5e93e8c..c93b674 100644
--- a/Debugging-the-engine.md
+++ b/Debugging-the-engine.md
@@ -9,13 +9,28 @@ First, make sure the appropriate version of the engine is built (see [[Compiling
 ### Using the Flutter tool
 
 Run your Flutter app with:
+
+```bash
+flutter run --local-engine=XXXX --local-host-engine=YYYY
 ```
-$ flutter run --local-engine=XXXX`
-```
-to run an app with the local engine where `XXXX` should be replaced with the version you wish to use. For example, use `--local-engine=android_debug_unopt` to run a debug android engine or `--local-engine=ios_debug_sim_unopt` to run a debug iOS simulator engine.
+
+to run an app with the local engine where `XXXX` should be replaced with the version you wish to use. For example, use `--local-engine=android_debug_unopt --local-host-engine=host_debug_unopt` to run a debug android engine or `--local-engine=ios_debug_sim_unopt --local-host-engine=host_debug_unopt` to run a debug iOS simulator engine.
+
+> 💡 **TIP**: When developing on a Mac with ARM (M CPU), use `--local-host-engine=host_debug_unopt_arm64`.
+>
+> You can continue to use `host_debug_unopt` (required for Intel Macs), but the engine will be run under Rosetta
+> which may be slower. See [Developing with Flutter on Apple Silicon](https://github.com/flutter/flutter/wiki/Developing-with-Flutter-on-Apple-Silicon)
+> for more information.
+
+<!-- TODO(matanl): https://github.com/flutter/flutter/issues/132245, update this. -->
 
 It is important to always have a `host_XXXX` version of the engine built when using a local engine since Flutter uses the host build's version of Dart.
 
+> ⚠️ **WARNING**: As of [#132245](https://github.com/flutter/flutter/issues/132245), `--local-host-engine` will be mandatory.
+>
+> If you're currently relying on the host engine being implicitly defined, you will need to update your workflow to explicitly specify the host engine.
+> For example, if you're currently running `flutter run --local-engine=android_debug_unopt`, you will need to run `flutter run --local-engine=android_debug_unopt --local-host-engine=host_debug_unopt` instead.
+
 ### Using Visual Studio Code
 
 You will need to add a new [launch configuration](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) in the `launch.json` file:
@@ -28,7 +43,7 @@ You will need to add a new [launch configuration](https://code.visualstudio.com/
             "name": "Launch (local engine)",
             "request": "launch",
             "type": "dart",
-            "args": ["--local-engine", "XXX"]
+            "args": ["--local-engine", "XXX", "--local-host-engine", "YYY"]
         },
 
         // Other profiles below..
@@ -38,7 +53,7 @@ You will need to add a new [launch configuration](https://code.visualstudio.com/
 
 ## Bisecting a roll failure
 
-If the engine roll is failing (see [[Autorollers]]), you can use `git bisect` on the engine repo to track down the offending commit, using the `--local-engine` command as described above to run the failing framework test with each version of the engine.
+If the engine roll is failing (see [[Autorollers]]), you can use `git bisect` on the engine repo to track down the offending commit, using the `--local-engine` and `--local-host-engine` arguments as described above to run the failing framework test with each version of the engine.
 
 ## Tracing OpenGL calls in Skia
 
@@ -53,8 +68,9 @@ Also, make sure to run your application with the `--trace-skia` flag.
 Building with `flutter --local-engine` will set a `LOCAL_ENGINE` Xcode build setting in your Flutter application `Generated.xcconfig` file. This will be set until you run `flutter run` again with either a different `--local-engine` option, or with none at all (which will unset it).
 
 You can speed up your workflow by adding the `--config-only` flag to set up the Xcode build settings and plugins, but not compile the app. For example:
-```
-$ flutter build ios --local-engine ios_debug_unopt --config-only
+
+```bash
+flutter build ios --local-engine ios_debug_unopt --local-host-engine host_debug_unopt --config-only
 ```
 
 To start debugging, open your Flutter app `ios/Runner.xcworkspace` file in Xcode. Ensure **Product > Scheme > Edit Scheme > Run > Build Configuration** matches your engine runtime mode (defaults to `Debug`).
@@ -85,7 +101,7 @@ Then hit the "Attach debugger" button in Android Studio, click "Show all process
 
 Compiling the engine creates a Visual Studio solution file. You can use it to debug the engine:
 
-1. Launch your Flutter app using a locally built engine `flutter run -d windows --local-engine host_debug_unopt`
+1. Launch your Flutter app using a locally built engine `flutter run -d windows --local-engine host_debug_unopt --local-host-engine host_debug_unopt`
 2. Using Visual Studio, open the engine's solution file `.\out\host_debug_unopt\all.sln`
 3. Open `Debug` > `Attach to Process...` (or press `CTRL+ALT+P`)
 4. Choose your Flutter app using either `Select Window`, or, the list of available processes.
@@ -94,7 +110,7 @@ Compiling the engine creates a Visual Studio solution file. You can use it to de
 Building a Flutter app also creates a Visual Studio solution file. You can use it to debug the
 engine, your app's runner, and your app's plugins:
 
-1. Build your Flutter app using a locally built engine using `flutter build windows --debug --local-engine host_debug_unopt`
+1. Build your Flutter app using a locally built engine using `flutter build windows --debug --local-engine host_debug_unopt --local-host-engine host_debug_unopt`
 2. Using Visual Studio, open the Flutter app's `.\build\windows\<project_name>.sln`
 3. In the `Solution Explorer` pane, right click the project whose name matches your app, and select `Set as Startup Project`
 
@@ -123,12 +139,13 @@ To debug a Flutter app using GDB, the stripped flutter engine GTK library in the
 First, in your Flutter project, build your Flutter app using the local engine:
 
 ```shell
-flutter build linux --debug --local-engine=host_debug_unopt lib/main.dart
+flutter build linux --debug --local-engine=host_debug_unopt --local-host-engine=host_debug_unopt lib/main.dart
 ```
 
 Then, replace the library in your Flutter application's build directory: `build/linux/x64/debug/bundle/lib/libflutter_linux_gtk.so` with a copy or symbolic link to the engine build's output file `out/host_debug_unopt/lib.unstripped/libflutter_linux_gtk.so`.
 
 Then you can open it in the debugger with:
+
 ```shell
 gdb build/linux/x64/debug/bundle/your_app_name
 ```
@@ -137,4 +154,4 @@ Note that this won't help you debug the Dart portion of the app: this is just fo
 
 ## Logging in the engine
 
-Flutter tool will by default parse out any non-error output from the engine. Error logs will be displayed. Logging is handled though the FML library's `logging.h`
\ No newline at end of file
+Flutter tool will by default parse out any non-error output from the engine. Error logs will be displayed. Logging is handled though the FML library's `logging.h`.
\ No newline at end of file
diff --git a/Impeller-Scene.md b/Impeller-Scene.md
index b58c295..f2bbd10 100644
--- a/Impeller-Scene.md
+++ b/Impeller-Scene.md
@@ -13,7 +13,7 @@ We are excited to have you tinker on [the Impeller Scene Demo presented at Flutt
     * If targeting the simulator: `ninja -C out/ios_debug_sim_arm64`
 * Clone the demo repository: `git clone https://github.com/bdero/flutter-scene-example.git` and move into the directory.
 * Plug in your device or open `Simulator.app`, then run `flutter devices` to note the device identifier.
-* Run the demo application: `flutter run -d [device_id] --local-engine ios_debug` (or `ios_debug_sim_arm64` if you are running on the Simulator).
+* Run the demo application: `flutter run -d [device_id] --local-engine ios_debug --local-host-engine host_debug` (or `ios_debug_sim_arm64` if you are running on the Simulator).
+    * On Silicon Macs, prefer `--local-host-engine host_debug_arm64` (adjusting your `ninja` command above accordingly)
 
- 
 We hope to continue evolving the API and have it available on the stable channel soon!
diff --git a/JIT-Release-Modes.md b/JIT-Release-Modes.md
index a0a6f58..e7ec2ee 100644
--- a/JIT-Release-Modes.md
+++ b/JIT-Release-Modes.md
@@ -3,13 +3,13 @@ Normally Flutter runs in JIT for faster compilation/debugging support in `debug`
 
 JIT release mode can be used with a local engine configuration. For example, to setup an Android x86 jit_release and host build you can use the GN command below. Both device and host artifacts need to be built, except in cases where they are the same such as the Desktop shells.
 
-```
+```shell
 ./flutter/tools/gn --runtime-mode=jit_release --android --android-cpu=x86
 ninja -C out/android_jit_release_x86
 ./flutter/tools/gn --runtime-mode=jit_release 
 ninja -C out/host_jit_release
 ```
 
-This can be used with the flutter tool via the `--local-engine` flag to produce a bundle containing the jit release artifacts using the `flutter assemble` command. By default, flutter.gradle does not know how to package this artifacts so it requires custom integration into a build pipeline. Nevertheless, the artifact structure should be identical to a debug build, but with asserts disabled and product mode enabled.
+This can be used with the flutter tool [via the `--local-engine`](https://github.com/flutter/flutter/wiki/Debugging-the-engine#running-a-flutter-app-with-a-local-engine) flag to produce a bundle containing the jit release artifacts using the `flutter assemble` command. By default, flutter.gradle does not know how to package this artifacts so it requires custom integration into a build pipeline. Nevertheless, the artifact structure should be identical to a debug build, but with asserts disabled and product mode enabled.
 
 jit_release is not supported on iOS devices. Applications built in JIT mode cannot be distributed on the Apple App Store.
\ No newline at end of file
diff --git a/Rolling-Dart.md b/Rolling-Dart.md
index 9318ace..4f7e43c 100644
--- a/Rolling-Dart.md
+++ b/Rolling-Dart.md
@@ -75,22 +75,24 @@ cd out
 find . -mindepth 1 -maxdepth 1 -type d | xargs -n 1 sh -c 'ninja -C $0 -j1000 || exit 255'
 ```
 
-7. Test the engine version you just built against the top of tree flutter/flutter version using the `--local-engine` option (see [[The flutter tool]]) against the Flutter Gallery app.
+7. Test the engine version you just built against the top of tree flutter/flutter version using the `--local-engine` and `--local-host-engine` options (see [[The flutter tool]]) against the Flutter Gallery app.
 
 ```bash
 cd $FLUTTER_HOME/examples/flutter_gallery
-flutter run --release --local-engine=android_release
-flutter run --local-engine=android_debug_unopt
-flutter test --local-engine=host_debug 
+flutter run --release --local-engine=android_release --local-host-engine=host_release
+flutter run --local-engine=android_debug_unopt --local-host-engine=host_debug_unopt
+flutter test --local-engine=host_debug --local-host-engine=host_debug
 ```
 
 In the debug version of flutter, run flutter_gallery and do a hot-reload and hot-restart of the app and ensure they both work.
 
 ```bash
 cd $FLUTTER_HOME/packages/flutter
-flutter test --local-engine=host_debug
+flutter test --local-engine=host_debug --local-host-engine=host_debug
 ```
 
+> ℹ️ **NOTE**: See [Running a Flutter app with a local engine](https://github.com/flutter/flutter/wiki/Debugging-the-engine#running-a-flutter-app-with-a-local-engine) for more information.
+
 8. Make sure your path contains `engine/src/third_party/dart/tools/sdks/dart-sdk/bin`, run the script `flutter/ci/licenses.sh` in the src directory, update `flutter/ci/licenses_golden/licenses_third_party` by copying `out/license_script_output/licenses_third_party` into it. Include this change in your pull request.
 **If any licenses changed, make sure to also update the actual `LICENSE` file.**
 
diff --git a/Running-Flutter-Driver-tests-with-Web.md b/Running-Flutter-Driver-tests-with-Web.md
index 0eb9077..f4b5094 100644
--- a/Running-Flutter-Driver-tests-with-Web.md
+++ b/Running-Flutter-Driver-tests-with-Web.md
@@ -58,7 +58,7 @@ flutter drive --target=test_driver/[driver_test].dart -d web-server --release --
 
 Let's go over the different arguments that can be used:
 * Use one of the six browsers for `--browser-name` parameter: chrome, safari, ios-safari, android-chrome, firefox, edge.
-* Use `--local-engine=host_debug_unopt` for running tests with a local engine. 
+* Use `--local-engine=host_debug_unopt --local-host-engine=host_debug_unopt` for running tests with a local engine.
 * Use `--release` or `--profile` mode for running the tests. Debug mode will be supported soon.
 * Change the `--webport` as needed, don't forget to change remote debugging settings for Android Chrome.
 * Use `--no-android-emulator` for using Android with real devices.
diff --git a/Running-and-writing-tests.md b/Running-and-writing-tests.md
index fdedf54..19302b6 100644
--- a/Running-and-writing-tests.md
+++ b/Running-and-writing-tests.md
@@ -49,7 +49,7 @@ runs them, run `dart dev/bots/test.dart` and `dart --enable-asserts dev/bots/ana
 If you've built your own flutter engine (see [[Setting up the Engine development environment]]), you
 can pass `--local-engine` to change what flutter shell `flutter test` uses. For example,
 if you built an engine in the `out/host_debug_unopt` directory, you can pass
-`--local-engine=host_debug_unopt` to run the tests in that engine.
+`--local-engine=host_debug_unopt --local-host-engine=host_debug_unopt` to run the tests in that engine.
 
 To learn how to see how well tested the codebase is, see [[Test coverage for package:flutter]].
 
@@ -82,10 +82,11 @@ When a device lab test fails, it is important to be able to run the test locally
 
 Sometimes a device lab test fails due to engine changes that you've made. In these cases, you'd like to run the impacted device lab tests locally with your local version of the engine. To do this, pass the appropriate flags to `run.dart`:
 
-```
+```shell
 ../../bin/dart bin/run.dart \
   --local-engine-src-path=[path_to_src] \
   --local-engine=[engine_build_for_your_device] \
+  --local-host-engine=[host_engine_build_for_your_device] \
   -t [task_name]
 ```
 
@@ -94,6 +95,7 @@ If your local Flutter engine is in the same directory as your `flutter/` directo
 ```
 ../../bin/dart bin/run.dart \
   --local-engine=[engine_build_for_your_device] \
+  --local-host-engine=[host_engine_build_for_your_device] \
   -t [task_name]
 ```
 
@@ -103,12 +105,13 @@ The following is an example of what running the local engine command might look
 ../../bin/dart bin/run.dart \
   --local-engine-src-path=/Users/myname/flutter/engine/src \
   --local-engine=android_debug_unopt_x86 \
+  --local-host-engine=host_debug_unopt_x86 \
   -t external_ui_integration_test
 ```
 
 The above command would use the local Flutter engine located at `/Users/myname/flutter/engine` to execute the `external_ui_integration_test` test on an Android emulator, which is why the `android_debug_unopt_x86` version of the engine is used.
 
-Note that some tests may require `profile` mode instead of `debug` mode when running with local engine. Make sure to pass in the correct local engine. See [Compiling the engine](https://github.com/flutter/flutter/wiki/Compiling-the-engine) for more details. 
+Note that some tests may require `profile` mode instead of `debug` mode when running with local engine. Make sure to pass in the correct local engine. See [Compiling the engine](https://github.com/flutter/flutter/wiki/Compiling-the-engine) for more details.
 
 
 For the engine
diff --git a/Testing-the-engine.md b/Testing-the-engine.md
index c278ec3..3066fb0 100644
--- a/Testing-the-engine.md
+++ b/Testing-the-engine.md
@@ -338,7 +338,7 @@ submitting PRs to the `flutter/engine` repository.
 Assuming your `flutter` and `engine` working directories are siblings, you can run the framework tests locally using the following command from the root of your `flutter` repository:
 
 ```bash
-(cd packages/flutter; ../../bin/flutter test --local-engine=host_debug_unopt)
+(cd packages/flutter; ../../bin/flutter test --local-engine=host_debug_unopt --local-host-engine=host_debug_unopt)
 ```
 
 ## Web engine
diff --git a/The-flutter-tool.md b/The-flutter-tool.md
index 8d0475b..9bbbf88 100644
--- a/The-flutter-tool.md
+++ b/The-flutter-tool.md
@@ -165,7 +165,7 @@ and  `local-engine`, which specifies which build of the engine to use.
 same upstream version of the engine that the Flutter SDK/flutter tool has pinned. You can find the engine version
 that the Flutter SDK has pinned at `flutter/bin/internal/engine.version`.
 
-A typical invocation would be: `--local-engine-src-path /path/to/engine/src --local-engine=android_debug_unopt`.
+A typical invocation would be: `--local-engine-src-path /path/to/engine/src --local-engine=android_debug_unopt --local-host-engine=host_debug_unopt`.
 
 If your engine is in a directory called `engine` that is a peer to the framework repository's `flutter` directory, then you can omit `--local-engine-src-path` and only specify `--local-engine`.
 
@@ -173,6 +173,13 @@ You can also set the environment variable `$FLUTTER_ENGINE` instead of specifyin
 
 The `--local-engine` should specify the build of the engine to use, e.g. a profile build for Android, a debug build for Android, or whatever. It must match the other arguments provided to the tool, e.g. don't use the `android_debug_unopt` build when you specify `--release`, since the Debug build expects to compile and run Dart code in a JIT environment, while `--release` implies a Release build which uses AOT compilation.
 
+<!-- TODO(matanl): https://github.com/flutter/flutter/issues/132245, update this. -->
+
+> ⚠️ **WARNING**: As of [#132245](https://github.com/flutter/flutter/issues/132245), `--local-host-engine` will be mandatory.
+>
+> If you're currently relying on the host engine being implicitly defined, you will need to update your workflow to explicitly specify the host engine.
+> For example, if you're currently running `flutter run --local-engine=android_debug_unopt`, you will need to run `flutter run --local-engine=android_debug_unopt --local-host-engine=host_debug_unopt` instead.
+
 If you've modified the public API of `dart:ui` in your local build of the engine
 and you need to be able to analyze the framework code with the new API,
 you will need to add a `dependency_overrides` section pointing to your