docs/updating_dependencies.md

# Updating flutter-embedder.git's dependencies

This doc describes how to bump the dependencies of flutter-embedder.git.

## Requirements

To update flutter-embedder.git's dependencies, you need the
Flutter Engine source code to build updated Flutter Engine
artifacts for flutter-embedder.git to use.

1. You will need to fork 
   [`flutter/engine`](https://github.com/flutter/engine) into a GitHub account.

2. Fetch the Flutter Engine code into `$FUCHSIA_EMBEDDER_DIR/third_party/engine/src`:

   ```sh
   $FUCHSIA_EMBEDDER_DIR/scripts/setup_engine.sh --github-username <your_username>
   ```

## Bumping dependencies

Running an example in flutter-embedder.git has two sensitive dependencies:

1. The **Fuchsia SDK**, which is used by flutter-embedder.git, Flutter Engine and
   the Dart SDK.

   - The Fuchsia SDK used by flutter-embedder.git must be around the
     same version as the Fuchsia SDK used by flutter-embedder.git's Flutter Engine
     artifacts, which come from [a separate repository](https://github.com/flutter/engine),
     or compile-time errors can occur from failing to link symbols.

2. The **Dart SDK**, which is used by Flutter Engine and the Flutter Framework.

   - A Flutter app must be built using the same Dart SDK as the Flutter Engine, or a crash will
     occur on startup.

As a result, we update the flutter-embedder.git's dependencies on the Fuchsia SDK, Flutter Framework
and Flutter Engine at the same time to keep:

1. flutter-embedder.git and Flutter Engine using roughly the same version of the Fuchsia SDK, and

2. Flutter Engine and Flutter Framework using the exact same version of the Dart SDK.

This can be done by running the following command:

```sh
$FUCHSIA_EMBEDDER_DIR/scripts/update_dependencies.sh
```

After updating the SDK, you should update your product bundle (`ffx product-bundle get workstation_eng.qemu-x64`)
and restart any running emulators and package servers as old images may be incompatible
with the updated SDK. To do this automatically, run:

```sh
$FUCHSIA_EMBEDDER_DIR/scripts/update_dependencies.sh --cleanup
```

## Future improvements

`update_dependencies.sh` should ensure that flutter-embedder.git and Flutter Engine
use the exact same version of the Fuchsia SDK instead of roughly the same version.