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

4. You will need [the Flutter tool](https://github.com/flutter/flutter/wiki/Setting-up-the-Framework-development-environment) in
   your PATH. For example if your Flutter framework source checkout is at `~/flutter`, add the following to
   your `~/.zprofile` for `zsh` or `~/.bash_profile` for `bash`:

   ```sh
   export PATH=~/flutter/bin:$PATH
   ```

   TODO(akbiggs): Get rid of the dependency on the Flutter tool by using Bazel build rules to build the Flutter app instead.

## 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 your Flutter tool. If your Flutter tool
lives at `~/flutter/bin/flutter`, you can do `cat ~/flutter/bin/internal/engine.version` to get
your Flutter tool's Engine commit.