|author||Alexander Biggs <firstname.lastname@example.org>||Wed Aug 24 18:38:36 2022 +0000|
|committer||Alexander Biggs <email@example.com>||Wed Aug 24 19:27:56 2022 +0000|
[embedder] Improve docs for syncing engine stuff. Change-Id: I0679fcd77fe0b6d0ce88bc45cff259c4715c58af
The Flutter Embedder for Fuchsia is a new in-progress runtime for Flutter apps on Fuchsia. This runtime is built on top of Flutter's embedder platform.
This repository is a work in progress and should be considered experimental.
$FUCHSIA_EMBEDDER_DIR to your flutter-embedder.git checkout location, for example
Bootstrap the repository's dependencies:
This script initializes tools (including
ffx), installs some Git hooks and downloads the
workstation_eng.qemu-x64 product bundle, which you can use to run the examples below.
Start the emulator.
If running in a graphical environment:
$FUCHSIA_EMBEDDER_DIR/tools/ffx emu start workstation_eng.qemu-x64
If running in a terminal environment:
$FUCHSIA_EMBEDDER_DIR/tools/ffx emu start --headless workstation_eng.qemu-x64
(optional) Watch the device log in a separate window:
Run an example app:
TODO(akbiggs): The app occasionally gets stuck on a loading screen instead of rendering. Re-running the app usually fixes it. We need to fix this.
Occasionally you will need to update the Flutter Engine artifacts (
libengine_flutter.so) that are used by the embedder to run Flutter apps. A script is provided for this workflow.
srcfolder of your Flutter Engine checkout location, for example
$DEPOT_TOOLSshould be set to your
depot_toolslocation, for example
sync_engine_artifacts_to_revision.sh, you will need to
git commitany local changes to the Flutter Engine. This is not necesssary for
You can run the script with a
flutter/engine Git commit to sync the Engine artifacts to that revision.
A common workflow is to sync your Engine commit to the Flutter tool in this repository, for example when updating the Flutter tool to a new version. To do this:
$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)
If you want to test local changes to the Engine, you can run
build_and_copy_engine_artifacts.sh instead, which simply builds and copies your Engine into
An alternative Gerrit workflow is a branchless workflow where you do all your work from
origin/main without creating new branches. We describe such a workflow below, but it‘s not mandatory, it’s just provided as an example.
An example branchless workflow for creating a new change is:
# Start work from an up-to-date main branch. git fetch origin git checkout origin/main # Modify some files... ... # Stage and commit your changes. git add file1.cc file2.h git commit -m "[embedder] My cool new feature." # Upload for review. git push origin HEAD:refs/for/main
An example branchless workflow to apply feedback during a code review is:
Visit https://fuchsia-review.googlesource.com and find your change.
... > Download patch > Checkout and copy the command.
Run the following commands:
# Start from main with your change on top. <paste the command you copied above> # Make some changes to some files to apply the feedback... ... # Stage and amend your changes to your commit. git add file1.cc file2.h git commit --amend # Upload your updated change for review. git push origin HEAD:refs/for/main
An example branchless workflow to create a chain of changes is:
# Start work from an up-to-date main branch. git fetch origin git checkout origin/main # Modify some files... ... # Stage and commit your changes. git add file1.cc file2.h git commit -m "[embedder] My cool new feature 1." # Upload for review. git push origin HEAD:refs/for/main # Do some more work on top of your cool new feature. git add file3.cc file4.h git commit -m "[embedder] My cool new feature 2." # Create a second code review for your second feature. # The second code review will only show changes for # your second feature and it will indicate that it is based on # top of the first feature. git push origin HEAD:refs/for/main
A branchless workflow comes with some benefits:
git checkout origin/main).
However a branchless workflow also prevents you from storing multiple chains of commits locally. Uploading your changes to https://fuchsia-review.googlesource.com frequently can help address that problem, as https://fuchsia-review.googlesource.com then acts as the storage for each of your ongoing changes. This also keeps your changes in a state where they're easy to share and hand off to other people.