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 fork 
   [`flutter/engine`](https://github.com/flutter/engine) into a GitHub account.

2. Fetch the Flutter Engine code into `$FUCHSIA_EMBEDDER_DIR/third_party/engine/src`:

   ```sh
   $FUCHSIA_EMBEDDER_DIR/scripts/setup_engine.sh --github-username <your_username>
   ```

### 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_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 $FUCHSIA_EMBEDDER_DIR/third_party/engine/src/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_to_revision.sh $(cat $FUCHSIA_EMBEDDER_DIR/third_party/dart-pkg/internal/flutter/flutter/bin/internal/engine.version)
   ```

   - By default this uses a prebuilt version of the Dart SDK instead of the Dart SDK source code
     at `$FUCHSIA_EMBEDDER_DIR/third_party/engine/src/third_party/dart`. To build the Dart SDK from
     source to test Dart SDK changes, pass `--no-prebuilt-dart-sdk`.

   - If you're a Googler, you can pass `--goma` to accelerate the build.

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
  `$FUCHSIA_EMBEDDER_DIR/third_party/engine/src/flutter`.
   For example if you stashed some changes earlier:

   ```sh
   git -C $FUCHSIA_EMBEDDER_DIR/third_party/engine/src/flutter stash apply
   ```

4. Run an example app with the `--with-engine` flag to build an example with your Flutter Engine
   changes included.

   ```sh
   $FUCHSIA_EMBEDDER_DIR/scripts/build_and_run_example.sh hello_flutter --with-engine
   ```

   - If you're a Googler, pass `--goma` to accelerate the build.

### 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_to_revision.sh`](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/scripts/sync_engine_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.