README.md

flutter-embedder.git
=======================================

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](https://github.com/flutter/flutter/wiki/Custom-Flutter-Engine-Embedders).

This repository is a work in progress and should be considered
experimental.

## Requirements

1. Install a Bazel version no older than the one defined in the
   [WORKSPACE.bazel](WORKSPACE.bazel#23) file, by following the instructions at https://bazel.build/install.
   In some Linux distributions, `sudo apt-get install bazel` should be enough.

2. Make sure this repository has the required submodules:

   ```sh
   git submodule update --recursive --init
   ```

3. Ensure that there are Fuchsia SSH keys in your host machine. You will need
   them for running the Fuchsia emulator.

   ```sh
    [[ -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"
   ```

## Build and package the sample

Now the repository is ready to build the sample.

1. Fetch an emulator image and start an emulator:

   ```
   tools/ffx product-bundle get workstation.qemu-x64
   tools/ffx emu start --headless workstation.qemu-x64
   ```

2. (optional) Watch the device log in a separate window:

   ```
   tools/ffx log
   ```

3. Run the sample app component:

   ```
   scripts/build_and_run_sample_app.sh
   ```

TODO(akbiggs): Currently the component crashes on startup with an `ambient_mark_vmo_exec`
allowlist issue. We are talking to security to figure out how to handle this.

## Syncing engine artifacts

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.

### Prerequisites

1. You will [need to get the Flutter Engine source code](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment). **Note that this is not just cloning
https://github.com/flutter/engine.**
2. `$ENGINE_DIR` should be set to the `src` folder of your Flutter Engine checkout, for example
`~/engine/src`.
3. `$FUCHSIA_EMBEDDER_DIR` should be set to your flutter-embedder.git checkout, for example
`~/flutter-embedder`.
4. `$DEPOT_TOOLS` should be set to your [`depot_tools`](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up) location, for example `~/depot_tools`.
5. You will need to `git stash` or `git commit` any local changes to the Flutter Engine or the
script will fail.

### Running the script

You can run the script with a `flutter/engine` Git commit to sync the Engine artifacts to that
revision.

```sh
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. To do this:

```sh
scripts/sync_engine_artifacts_to_revision.sh $(cat $FUCHSIA_EMBEDDER_DIR/third_party/dart-pkg/internal/flutter/flutter/bin/internal/engine.version)
```