commit | 1eff89eaca9c49efe4bcff15188199d5f1707325 | [log] [tgz] |
---|---|---|
author | Alexander Biggs <akbiggs@google.com> | Wed Aug 17 07:20:25 2022 +0000 |
committer | Alexander Biggs <akbiggs@google.com> | Thu Aug 18 16:00:01 2022 +0000 |
tree | e8ac7518835eed1eb2c60d62b879b334045fa409 | |
parent | 0587d8d1ddcb1d0873f765858f11b63d607d673e [diff] |
[embedder] Document a workflow for code reviews. Change-Id: I7a21ed9d8ac5a941af3b383b31762deb5645f1a4
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.
Set $FUCHSIA_EMBEDDER_DIR
to your flutter-embedder.git checkout location, for example ~/flutter-embedder
.
Make sure this repository has the required submodules:
git submodule update --recursive --init
Run $FUCHSIA_EMBEDDER_DIR/scripts/bootstrap.sh
.
Ensure that there are Fuchsia SSH keys in your host machine. You will need them for running the Fuchsia emulator.
[[ -f "${HOME}/.ssh/fuchsia_ed25519" ]] || ssh-keygen -P "" -t ed25519 -f "${HOME}/.ssh/fuchsia_ed25519" -C "${USER}@$(hostname -f) Shared SSH Key for Fuchsia" [[ -f "${HOME}/.ssh/fuchsia_authorized_keys" ]] || ssh-keygen -y -f "${HOME}/.ssh/fuchsia_ed25519" > "${HOME}/.ssh/fuchsia_authorized_keys"
Now the repository is ready to build the sample.
Fetch an emulator image:
$FUCHSIA_EMBEDDER_DIR/tools/ffx product-bundle get workstation_eng.qemu-x64
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:
$FUCHSIA_EMBEDDER_DIR/tools/ffx log
Run an example app:
$FUCHSIA_EMBEDDER_DIR/scripts/build_and_run_example.sh hello_flutter
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 (embedder.h and libengine_flutter.so) that are used by the embedder to run Flutter apps. A script is provided for this workflow.
$ENGINE_DIR
to the src
folder of your Flutter Engine checkout location, for example ~/engine/src
.$FUCHSIA_EMBEDDER_DIR
should be set to your flutter-embedder.git checkout location, for example ~/flutter-embedder
.$DEPOT_TOOLS
should be set to your depot_tools
location, for example ~/depot_tools
.git stash
or git commit
any local changes to the Flutter Engine or the script will fail.You can run the script with a flutter/engine
Git commit to sync the Engine artifacts to that revision.
$FUCHSIA_EMBEDDER_DIR/scripts/sync_engine_artifacts_to_revision.sh <ENGINE_COMMIT_SHA>
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)
flutter-embedder reviews are handled using Gerrit at https://fuchsia-review.googlesource.com, which uses a single commit per code review. See this guide for an intro to Gerrit.
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.
Select ... > 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.