[embedder] Add workflow for testing local Fuchsia.
This enables testing flutter-embedder.git with changes to
the Fuchsia SDK and platform, for example for validating a
new platform API by writing a Flutter component.
Using this workflow and https://fxrev.dev/753582, I was able
to see logs from a new Fuchsia API when running the example
component:
```sh
[381.267][scenic][scenic][E]: [src/ui/scenic/lib/scenic/util/error_reporter.cc:24] Flatland client(FlutterEmbedder): akbiggs: Hello from F
latland!!
```
Change-Id: I7055279dab7168984eb8a0b489aeaa7f18c64adc
Reviewed-on: https://fuchsia-review.googlesource.com/c/flutter-embedder/+/753467
Reviewed-by: Naud Ghebre <naudzghebre@google.com>
diff --git a/README.md b/README.md
index 6dc9121..7dd9246 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,8 @@
## Requirements
+This embedder can currently only be built on Linux, not Mac or Windows (native).
+
If you're using WSL2 (Windows Subsystem for Linux), see
[SETUP_WINDOWS.md](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/SETUP_WINDOWS.md)
first.
@@ -57,7 +59,7 @@
$FUCHSIA_EMBEDDER_DIR/tools/ffx target default set fuchsia-emulator
```
-3. Run an example component:
+3. Run [an example component](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/src/examples/README.md):
```sh
$FUCHSIA_EMBEDDER_DIR/scripts/build_and_run_example.sh hello_flutter
@@ -79,11 +81,9 @@
Caveats:
- - `--fidl` currently requires setting `$FUCHSIA_DIR` to a
- [Fuchsia source checkout](https://fuchsia.dev/fuchsia-src/get-started/get_fuchsia_source)
- with a build in `$FUCHSIA_DIR/out/default`. This directory is only
- used to read IR files for FIDL, you can still use the
- `workstation_eng.qemu-x64` product bundle with `--fidl`.
+ - `--fidl` currently requires using a local Fuchsia SDK instead of the prebuilt
+ Fuchsia SDK. See
+ [this guide for setup instructions](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/testing_fuchsia_sdk_changes.md).
- `--fidl` attaches after the component has been run, so it does not pick up
FIDL calls made when the component starts.
@@ -93,6 +93,10 @@
**TODO(akbiggs): Work with Bazel SDK team to get proper support for `--fidl`.**
+## Uploading changes for review.
+
+See [_`git_workflow.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/git_workflow.md).
+
## Making Flutter Engine changes
Running the Flutter app is handled by the Flutter Engine's
@@ -103,8 +107,18 @@
If you need to make changes to this Flutter Engine code (for example for
testing a new API in `embedder.h` with this embedder) see
[_`making_engine_changes.md`_ for instructions](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/making_engine_changes.md).
+
This isn't required for changes to only flutter-embedder.git's source code.
-## Uploading changes for review.
+## Testing Fuchsia SDK changes
-See [_`git_workflow.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/git_workflow.md).
\ No newline at end of file
+You may want to test changes to the Fuchsia platform
+([`fuchsia.git`](https://fuchsia.googlesource.com/fuchsia)) against the flutter-embedder
+repository locally (for example, to validate a WIP API using a Flutter component).
+To do so, see [_`testing_fuchsia_sdk_changes.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/testing_fuchsia_sdk_changes.md).
+
+This isn't required for changes to only flutter-embedder.git's source code (in which case
+you can follow [_"Run an example app"_](#run-an-example-app)) or changes
+to only fuchsia.git's non-SDK code (in which case you can run the example component on
+an emulator from fuchsia.git). It is only necessary if you have an unsubmitted API in
+the Fuchsia SDK that you want to test in flutter-embedder.
\ No newline at end of file
diff --git a/docs/testing_fuchsia_sdk_changes.md b/docs/testing_fuchsia_sdk_changes.md
new file mode 100644
index 0000000..f26bcdb
--- /dev/null
+++ b/docs/testing_fuchsia_sdk_changes.md
@@ -0,0 +1,67 @@
+# Testing Fuchsia SDK changes
+
+You may want to experiment with Fuchsia SDK changes in a Flutter
+component before submitting them to fuchsia.git, for example to
+validate a new UI API in the SDK with a Flutter component that uses
+that API.
+
+This is a workflow for making local changes to the Fuchsia
+SDK and testing those changes in flutter-embedder.git.
+
+## Requirements
+
+1. Get a Fuchsia source checkout [here](https://fuchsia.dev/fuchsia-src/get-started/get_fuchsia_source).
+
+2. Set up your Fuchsia build. For example for Workstation on emulator:
+
+ ```sh
+ cd $FUCHSIA_DIR
+ fx set workstation_eng.qemu-x64
+ ```
+
+3. Set `$LOCAL_FUCHSIA_PLATFORM_BUILD` to your out directory for your Fuchsia build.
+ For example:
+
+ ```
+ export LOCAL_FUCHSIA_PLATFORM_BUILD=$FUCHSIA_DIR/out/default
+ ```
+
+## Workflow
+
+1. Make your platform changes to the Fuchsia checkout that `$LOCAL_FUCHSIA_PLATFORM_BUILD` points to.
+
+2. Build Fuchsia and start the emulator.
+
+ ```sh
+ cd $LOCAL_FUCHSIA_PLATFORM_BUILD
+ fx build
+ fx ffx emu start
+ ```
+
+3. Run an example using `--with-fuchsia` to build the embedder against
+ `$LOCAL_FUCHSIA_PLATFORM_BUILD`'s Fuchsia SDK.
+
+ ```sh
+ $FUCHSIA_EMBEDDER_DIR/scripts/build_and_run_example.sh hello_flutter --with-fuchsia
+ ```
+
+ See
+ [this guide](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/README.md#run-an-example-app)
+ for the full list of options that can be passed to `build_and_run_example.sh`.
+
+4. To iterate on changes ...
+
+ - ... to only flutter-embedder.git, you can re-run step 3.
+ - ... to only internal fuchsia.git code, you can re-run step 2.
+ - ... to Fuchsia SDK code (`third_party/fuchsia/sdk`), you need to re-run steps 2
+ and 3.
+
+## Switching back to the prebuilt Fuchsia SDK
+
+If you want to switch back to working with flutter-embedder's prebuilt Fuchsia SDK
+and Fuchsia images instead of the local one, run:
+
+```sh
+unset $LOCAL_FUCHSIA_PLATFORM_BUILD
+$FUCHSIA_EMBEDDER_DIR/tools/bazel configure --sync
+```
\ No newline at end of file
diff --git a/scripts/build_and_run_example.sh b/scripts/build_and_run_example.sh
index b09aada..5858d2a 100755
--- a/scripts/build_and_run_example.sh
+++ b/scripts/build_and_run_example.sh
@@ -17,8 +17,11 @@
# --log: Follows logs containing the word "embedder" after running the example.
# --fidl: Follows FIDL calls made by the example process.
# We monitor after starting the example so FIDL calls on startup will not appear.
-# TODO(akbiggs): Improve on this behavior.
+# TODO(akbiggs): Show FIDL calls from startup.
# --with-engine: Also builds the Flutter Engine alongside the example.
+# See https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/making_engine_changes.md for setup.
+# --with-fuchsia: Also builds a local Fuchsia SDK alongside the example.
+# See https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/testing_fuchsia_sdk_changes.md for setup.
# --goma: Uses GOMA when building the Flutter Engine to accelerate the build.
# For Googlers only. Sorry. :(
#
@@ -37,6 +40,7 @@
log=0
fidl=0
with_engine=0
+with_fuchsia=0
goma_flags=""
app_name="hello_flutter"
while [[ $# -gt 0 ]]; do
@@ -51,21 +55,7 @@
shift # past argument
;;
--fidl)
- if ! [ -d "${FUCHSIA_DIR}"/out/default ]
- then
- echo-error '--fidl currently relies on:'
- echo-error ' 1. $FUCHSIA_DIR being set to your Fuchsia source checkout. https://fuchsia.dev/fuchsia-src/get-started/get_fuchsia_source'
- echo-error ' 2. "$FUCHSIA_DIR/out/default" having a Fuchsia build.'
- echo-error '... so that the FIDL IR can be read. You can still use a product bundle instead of a build from source.'
- echo-error
- echo-error 'If you already have a Fuchsia source checkout at $FUCHSIA_DIR, you can run:'
- echo 'cd $FUCHSIA_DIR'
- echo 'fx set workstation_eng.qemu-x64'
- echo 'fx build'
- echo-error "... and then try again."
- exit 1
- fi
-
+ ensure-local-fuchsia-platform-build
fidl=1
shift # past argument
;;
@@ -73,6 +63,11 @@
with_engine=1
shift # past argument
;;
+ --with-fuchsia)
+ ensure-local-fuchsia-platform-build
+ with_fuchsia=1
+ shift # past argument
+ ;;
--goma)
goma_flags="--goma"
shift # past argument
@@ -103,13 +98,30 @@
"${FUCHSIA_EMBEDDER_DIR}"/scripts/build_and_copy_engine_artifacts.sh ${goma_flags}
fi
+if [[ "${with_fuchsia}" != 0 ]]
+then
+ echo-info "Building Fuchsia SDK from $LOCAL_FUCHSIA_PLATFORM_BUILD..."
+ # All 'fx' commands must be run in the Fuchsia directory.
+ pushd "${LOCAL_FUCHSIA_PLATFORM_BUILD}"
+ "${LOCAL_FUCHSIA_PLATFORM_BUILD}"/../../.jiri_root/bin/fx build sdk
+ popd # "${LOCAL_FUCHSIA_PLATFORM_BUILD}"
+
+ echo-info "Syncing flutter-embedder's Bazel SDK to $LOCAL_FUCHSIA_PLATFORM_BUILD..."
+ # All bazel commands must be run from our workspace.
+ pushd "${FUCHSIA_EMBEDDER_DIR}"
+ "${FUCHSIA_EMBEDDER_DIR}"/tools/bazel sync --configure
+ popd # "${FUCHSIA_EMBEDDER_DIR}"
+fi
+
echo-info "Building Flutter sample app bundle."
pushd "${FUCHSIA_EMBEDDER_DIR}"/src/examples/"${app_name}"
"${FUCHSIA_EMBEDDER_DIR}"/tools/flutter build bundle
-popd # "${FUCHSIA_EMBEDDER_DIR}"/src/examples/"${app_name}"
+popd # "${FUCHSIA_EMBEDDER_DIR}"/src/examples/"${app_name}"
+
+# All bazel commands must be run from our workspace.
+pushd "${FUCHSIA_EMBEDDER_DIR}"
echo-info "Running Flutter sample app."
-pushd "${FUCHSIA_EMBEDDER_DIR}"
"${FUCHSIA_EMBEDDER_DIR}"/tools/ffx repository server start
"${FUCHSIA_EMBEDDER_DIR}"/tools/bazel run --config=fuchsia_x64 //src/examples/"${app_name}":"${app_name}"_pkg.component ${session_args}
@@ -122,15 +134,15 @@
popd # $FUCHSIA_EMBEDDER_DIR
-if [[ "${log}" -ne 0 ]]
+if [[ "${log}" != 0 ]]
then
echo-info "Showing ffx log --filter embedder --filter Embedder ... (ctrl+C to exit)"
"${FUCHSIA_EMBEDDER_DIR}"/tools/ffx log --filter embedder --filter Embedder
fi
-if [[ "${fidl}" -ne 0 ]]
+if [[ "${fidl}" != 0 ]]
then
echo-info 'Showing FIDL logs... (ctrl+C to exit)'
echo-info "(This does not currently catch FIDL calls from app startup)"
- "${FUCHSIA_EMBEDDER_DIR}"/tools/ffx debug fidl --remote-name embedder.cm --fidl-ir-path "${FUCHSIA_DIR}"/out/default
+ "${FUCHSIA_EMBEDDER_DIR}"/tools/ffx debug fidl --remote-name embedder.cm --fidl-ir-path "${LOCAL_FUCHSIA_PLATFORM_BUILD}"
fi
diff --git a/scripts/lib/helpers.sh b/scripts/lib/helpers.sh
index 432b82d..e43f3b6 100644
--- a/scripts/lib/helpers.sh
+++ b/scripts/lib/helpers.sh
@@ -11,7 +11,8 @@
# echo-info prints a line to stderr with a green INFO: prefix.
function echo-info {
- if is-stderr-tty; then
+ if is-stderr-tty
+ then
echo -e >&2 "\033[1;32mINFO:\033[0m $*"
else
echo -e >&2 "INFO: $*"
@@ -20,7 +21,8 @@
# echo-warning prints a line to stderr with a yellow WARNING: prefix.
function echo-warning {
- if is-stderr-tty; then
+ if is-stderr-tty
+ then
echo -e >&2 "\033[1;33mWARNING:\033[0m $*"
else
echo -e >&2 "WARNING: $*"
@@ -29,7 +31,8 @@
# echo-error prints a line to stderr with a red ERROR: prefix.
function echo-error {
- if is-stderr-tty; then
+ if is-stderr-tty
+ then
echo -e >&2 "\033[1;31mERROR:\033[0m $*"
else
echo -e >&2 "ERROR: $*"
@@ -37,8 +40,9 @@
}
function ensure-embedder-dir {
- if [[ -z "${FUCHSIA_EMBEDDER_DIR}" ]]; then
- echo-error '$FUCHSIA_EMBEDDER_DIR must be set to your flutter-embedder folder before running this script.'
+ if [[ -z "${FUCHSIA_EMBEDDER_DIR}" ]]
+ then
+ echo-error '$FUCHSIA_EMBEDDER_DIR must be set to your flutter-embedder folder before running this command.'
echo-error 'Add this line to your shell profile:'
echo-error "export FUCHSIA_EMBEDDER_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && cd ../.. && pwd)"
exit 1
@@ -49,10 +53,21 @@
embedder_engine_dir="${FUCHSIA_EMBEDDER_DIR}"/third_party/engine/src
function ensure-engine-dir {
- if [ ! -d "${embedder_engine_dir}" ]; then
- echo-error 'You must set up your Engine development environment before running this script.'
+ if [ ! -d "${embedder_engine_dir}" ]
+ then
+ echo-error 'You must set up your Engine development environment before running this command.'
echo-error 'To do this, run:'
- echo-error '$FUCHSIA_EMBEDDER_DIR/scripts/setup_engine --github-username my_username'
+ echo -e >&2 '$FUCHSIA_EMBEDDER_DIR/scripts/setup_engine.sh --github-username my_username'
+ exit 1
+ fi
+}
+
+function ensure-local-fuchsia-platform-build {
+ if [[ -z "${LOCAL_FUCHSIA_PLATFORM_BUILD}" ]]
+ then
+ echo-error '$LOCAL_FUCHSIA_PLATFORM_BUILD must be set to a Fuchsia out/ directory before running this command.'
+ echo-error 'For example:'
+ echo -e >&2 'export LOCAL_FUCHSIA_PLATFORM_BUILD=$FUCHSIA_DIR/out/default'
exit 1
fi
}
\ No newline at end of file
