[embedder] General architecture documentation.
Fixed: 115343
Change-Id: I051f366dcb915267550d50f8a813dedd67d57d36
Reviewed-on: https://fuchsia-review.googlesource.com/c/flutter-embedder/+/762475
Reviewed-by: Ben Bergkamp <benbergkamp@google.com>
diff --git a/README.md b/README.md
index c7f371c..2f39f96 100644
--- a/README.md
+++ b/README.md
@@ -16,14 +16,20 @@
[SETUP_WINDOWS.md](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/SETUP_WINDOWS.md)
first.
-1. Set `$FUCHSIA_EMBEDDER_DIR` to your flutter-embedder.git checkout location,
+1. Clone this repository.
+
+ ```sh
+ git clone https://fuchsia.googlesource.com/flutter-embedder
+ ```
+
+2. Set `$FUCHSIA_EMBEDDER_DIR` to your flutter-embedder.git checkout location,
for example `~/flutter-embedder`.
```sh
export FUCHSIA_EMBEDDER_DIR=$HOME/flutter-embedder
```
-2. Bootstrap the repository's dependencies:
+3. Bootstrap the repository's dependencies:
```sh
$FUCHSIA_EMBEDDER_DIR/scripts/bootstrap.sh
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..02ae909
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,38 @@
+# Documentation
+
+This folder contains high-level documentation for Flutter on Fuchsia.
+
+To run an example component on Fuchsia, see the
+[top-level README](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/README.md).
+
+## Architecture docs
+
+- [_`architecture.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/architecture.md):
+ General overview of how the Flutter
+ Embedder for Fuchsia works.
+
+- [_`pointer_input.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/pointer_input.md):
+ How mouse and touch input works.
+
+- [_`software_rendering.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/software_rendering.md):
+ How software (CPU-based) rendering works.
+
+## Workflow docs
+
+- [_`debugging.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/debugging.md):
+ How to attach a debugger to a Flutter component.
+
+- [_`git_workflow.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/git_workflow.md):
+ A suggested workflow for uploading
+ changes to this repository.
+
+- [_`making_engine_changes.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/making_engine_changes.md):
+ How to test changes to
+ the [Flutter Engine](https://github.com/flutter/engine) code with a Flutter component.
+
+- [_`testing_fuchsia_sdk_changes.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/testing_fuchsia_sdk_changes.md):
+ How to test changes to
+ the [Fuchsia platform](https://fuchsia.googlesource.com/fuchsia) code with a Flutter component.
+
+- [_`updating_dependencies.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/updating_dependencies.md):
+ How to update this repository's third_party dependencies.
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..2ccbd75
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,81 @@
+# How a Flutter component works
+
+For a very detailed overview of Flutter architecture on all platforms,
+see [this doc](https://docs.flutter.dev/resources/architectural-overview).
+
+A Flutter component for Fuchsia is an [ELF binary](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format)
+that is built and run using Fuchsia's [Bazel SDK](https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0139_bazel_sdk).
+The component is launched by
+[Fuchsia's ELF runner](https://fuchsia.dev/fuchsia-src/concepts/components/v2/elf_runner)
+(there is no longer a separate Flutter runner or Dart runner).
+
+Building and running an example Flutter component is done by:
+
+1. Compiling the Flutter application to get a folder of compiled assets
+ ([snapshot](https://mrale.ph/dartvm/#how-does-dart-vm-run-your-code), fonts, images).
+
+ This is currently done with the Flutter CLI using `flutter build bundle`.
+ This only supports JIT compilation. To support AOT compilation, we should switch to
+ using the Dart SDK's tools instead (see
+ [this doc](https://github.com/flutter/flutter/wiki/Custom-Flutter-Engine-Embedding-in-AOT-Mode#the-hard-way)
+ for reference).
+
+2. [Packaging](https://fuchsia.dev/fuchsia-src/concepts/packages/package)
+ these assets together with the embedder executable and shared libraries.
+ See [_"Package layout"_](#package-layout) for details.
+
+3. Running the embedder executable with the ELF runner. This is handled
+ by the Bazel SDK.
+
+ We pass the path to the compiled assets as an argument
+ [here](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/src/embedder/meta/embedder.cml#18).
+
+Running the application using the assets is handled by `libflutter_engine.so`,
+a shared library from the [Flutter Engine repository](https://github.com/flutter/engine).
+We interact with `libflutter_engine.so` using
+[`embedder.h`](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/src/embedder/engine/embedder.h).
+
+
+
+## Package layout
+
+The compiled Flutter component's package has three main folders:
+
+- **`bin/embedder`**: The executable.
+
+- **`data/flutter_assets/`**: The compiled assets of the Flutter app that should
+ be run by the executable.
+
+- **`lib/`**: Shared libraries that are used by `bin/embedder`.
+
+ Notably, `lib/libflutter_engine.so` is the Flutter Engine code that
+ `bin/embedder` uses to run the Flutter app.
+
+When building and running a Flutter example, the full package contents are printed
+for debugging.
+
+## Threading model
+
+The easiest way to understand how threading works in Flutter
+is to
+[attach a debugger in VS Code](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/debugging.md#attaching-a-debugger-from-vscode)
+and break on a function that you're interested in. VS Code will tell
+you what thread the code is running on.
+
+
+
+Some notable threads:
+
+- Platform thread (`initial-thread`): The thread that `main()` runs on.
+
+ - We connect to all
+ [FIDL services](https://fuchsia.dev/fuchsia-src/concepts/fidl/overview)
+ on this thread and
+ [platform messages](https://docs.flutter.dev/development/platform-integration/platform-channels)
+ are sent on this thread.
+
+ - Async requests and responses to FIDL services are handled by an async loop that is started by `FlutterEngineRun`.
+
+- Raster thread (`io.flutter.raster`): Handles rendering logic for Flutter.
+
+ - Callbacks for rendering are called on this thread.
diff --git a/docs/debugging.md b/docs/debugging.md
index cad54ae..7cc08a9 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -2,10 +2,11 @@
There are two ways to attach a debugger to example components:
-- **From the command-line interface (CLI).** This is currently
- the most well-supported way.
+- [**From the command-line interface (CLI).**](#attaching-a-debugger-from-the-cli)
+ This is currently the most well-supported way.
-- **From VSCode.** This works for attaching breakpoints and stepping
+- [**From VSCode.**](#attaching-a-debugger-from-vscode)
+ This works for attaching breakpoints and stepping
through the code but more advanced commands may not work (see
[known issues](https://bugs.fuchsia.dev/p/fuchsia/issues/list?q=component%3ADeveloperExperience%3EFuchsiaExtensionForVSCode%20zxdb&can=2)).
diff --git a/docs/images/embedder_architecture.png b/docs/images/embedder_architecture.png
new file mode 100644
index 0000000..3153b44
--- /dev/null
+++ b/docs/images/embedder_architecture.png
Binary files differ
diff --git a/docs/images/vscode_thread_model.png b/docs/images/vscode_thread_model.png
new file mode 100644
index 0000000..8cc473c
--- /dev/null
+++ b/docs/images/vscode_thread_model.png
Binary files differ
