docs/making_engine_changes.md

# Making Flutter Engine changes

Running Flutter apps is handled by the Flutter Engine's
[embedder platform](https://github.com/flutter/engine/tree/main/shell/platform/embedder).
This code is compiled into a shared library called `libflutter_engine.so`,
which we interact with using the `embedder.h` header.

## Updating Flutter Engine

If you simply want to pull a newer version of Flutter Engine into this repo with no
local changes, see [_`updating_dependencies.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/updating_dependencies.md).

## Testing local Flutter Engine changes

This section describes a workflow for making local changes to the Flutter Engine
embedder platform and testing those changes in flutter-embedder.git.

### Requirements

1. You will
   [need to get the Flutter Engine source code](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment).
   **Note that this is not just cloning https://github.com/flutter/engine.**

2. Set `$ENGINE_DIR` to the `src` folder of your Flutter Engine checkout location. For example
   for `zsh` add this line to your `.zprofile`:

   ```sh
   export ENGINE_DIR=$HOME/engine/src
   ```

3. You will need to install
   [`depot_tools`](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up)
   and add it to your `PATH`. For example for `zsh` add this line to your `.zprofile`:

   ```sh
   export PATH=$HOME/depot_tools:$PATH
   ```

### Workflow

There are two caveats to building Flutter Engine artifacts for this repository:

- The Dart SDK used by the Flutter Engine artifacts needs to match the Dart SDK
  used by the Flutter Framework to run examples.

- The Flutter Engine artifacts are currently built with
  [several experimental patches that have not been submitted yet](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/scripts/sync_engine_artifacts_to_revision.sh#72).

To address these caveats, first:

1. `git commit` or `git stash` any local changes to your Flutter Engine source code.

   ```sh
   git -C $ENGINE_DIR/flutter stash
   ```

2. Sync your Flutter Engine source code to Flutter Framework's version of Flutter Engine.
   This:

   - Ensures that the Dart SDK in your Flutter Engine artifacts is the same Dart SDK
   that is used to run examples in this repository.

   - Applies the experimental patches to your Flutter Engine source code.

   ```sh
   $FUCHSIA_EMBEDDER_DIR/scripts/sync_engine_artifacts_to_revision.sh $(cat $FUCHSIA_EMBEDDER_DIR/third_party/dart-pkg/internal/flutter/flutter/bin/internal/engine.version)
   ```

You can then build Flutter Engine artifacts for this repository with your local changes:

3. Make any local changes you'd like to test to the Flutter Engine code in `$ENGINE_DIR`.
   For example if you stashed some changes earlier:

   ```sh
   git -C $ENGINE_DIR/flutter stash apply
   ```

4. Build and copy your Flutter Engine changes over to this repository.

   ```sh
   $FUCHSIA_EMBEDDER_DIR/scripts/build_and_copy_engine_artifacts.sh
   ```

   You can re-run this script multiple times to iterate on your Flutter Engine
   changes.

5. [Run an example app](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/README.md#run-an-example-app)
   to test your changes.

### Landing your local Flutter Engine changes

Once you've verified that your local Flutter Engine change works, you have two options to land your
Flutter Engine change in flutter-embedder.git:

1. Submit a pull request to the Flutter Engine and then update the version of Flutter Engine used by
   this repository by following
   [_`updating_dependencies.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/updating_dependencies.md).

2. Add your commit to the list of experimental unsubmitted patches in
   [`sync_engine_artifacts_to_revision.sh`](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/scripts/sync_engine_artifacts_to_revision.sh#72)
   and commit your changes to `//src/embedder/engine` (i.e. commit the updated Flutter Engine artifacts).
   This is a useful tool to unblock while we continue to verify the change in flutter-embedder.git
   but you will be expected to submit the change in Flutter Engine later as this blocks production.
   
   - This is useful when making changes to Flutter Engine's `embedder.h` header as these changes cannot be reverted
     post-submission due to [embedder.h's ABI compatibility requirements](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/src/embedder/engine/embedder.h#18).
     It is good to be absolutely sure that the change is necessary and correct before submission.