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 fork flutter/engine into a GitHub account.

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

$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.

To address these caveats, first:

git commit or git stash any local changes to your Flutter Engine source code.
```
git -C $FUCHSIA_EMBEDDER_DIR/third_party/engine/src/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_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:

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:
```
git -C $FUCHSIA_EMBEDDER_DIR/third_party/engine/src/flutter stash apply
```
Run an example app with the --with-engine flag to build an example with your Flutter Engine changes included.
```
$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:

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_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.