Making Flutter Engine changes

Running Flutter apps is handled by the Flutter Engine's embedder platform. 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.

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

You will need to get the Flutter Engine source code. Note that this is not just cloning https://github.com/flutter/engine.
Set $ENGINE_DIR to the src folder of your Flutter Engine checkout location. For example for zsh add this line to your .zprofile:
```
export ENGINE_DIR=$HOME/engine/src
```
You will need to install depot_tools and add it to your PATH. For example for zsh add this line to your .zprofile:
```
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.

To address these caveats, first:

git commit or git stash any local changes to your Flutter Engine source code.
```
git -C $ENGINE_DIR/flutter stash
```
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.
```
$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:

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:
```
git -C $ENGINE_DIR/flutter stash apply
```
Build and copy your Flutter Engine changes over to this repository.
```
$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.
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:

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.
Add your commit to the list of experimental unsubmitted patches in sync_engine_artifacts_to_revision.sh 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. It is good to be absolutely sure that the change is necessary and correct before submission.