[samples] Update README to use ffx emu
This changes the emulator instructions to use `ffx emu`.
It also uses `--engine qemu --headless` for the arm64 emulator which
results in better performance than using AEMU.
Change-Id: I49026564f72583d0c88ed9a2db80e60016f7e679
Reviewed-on: https://fuchsia-review.googlesource.com/c/samples/+/674356
Reviewed-by: Dave Schuyler <dschuyler@google.com>
Reviewed-by: Wayne Piekarski <waynepie@google.com>
Reviewed-by: Daniel Dougherty <doughertyda@google.com>
Commit-Queue: Clayton Wilkinson <wilkinsonclay@google.com>
diff --git a/README.md b/README.md
index f0be182..173565d 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,5 @@
# Fuchsia Samples
+
A collection of samples demonstrating how to build, run, and test Fuchsia
components outside the Fuchsia source code tree.
@@ -7,14 +8,16 @@
> SLA or deprecation policy.
## Setup
+
1. Install required dependencies for building:
- ```
+ ```shell
sudo apt-get install curl unzip clang python3 build-essential
```
1. Clone this repo and submodules:
- ```
+
+ ```shell
git clone https://fuchsia.googlesource.com/samples --recursive --depth 1
```
@@ -26,10 +29,11 @@
1. Change directory to the root of the repo and setup and run the tests:
- ```
+ ```shell
cd samples
./scripts/setup-and-test.sh
```
+
This script downloads all required dependencies (this may take 5-30min),
builds the samples, and runs the tests. If the script completes without
errors all tests have passed.
@@ -37,13 +41,16 @@
## C++ Samples (GN)
### Supported host platforms and build systems
+
The C++ samples in this repo only support Linux hosts and the
[GN build system](https://gn.googlesource.com/gn/).
### Getting started
+
To get started see the [SDK documentation](https://fuchsia.dev/fuchsia-src/development/sdk).
### Samples
+
#### bouncing_ball
Example application using Scenic to render animated graphics.
@@ -75,79 +82,130 @@
To get started, see the [README](src/realm_builder/README.md).
### Repository structure
+
#### build
+
The `build` directory contains the build configuration for the sample including
the toolchain, targets and tests.
+
#### buildtools
+
The `buildtools` directory contains scripts to help with the build process like
downloading needed tools (e.g. gn, ninja).
+
#### src
+
The `src` directory contains the source code for the C++ samples.
+
#### third_party
+
GN samples has two third_party dependencies: the Fuchsia GN SDK and googletest
(googletest is only required for testing):
-* **Fuchsia SDK**: The Fuchsia SDK is a set of tools and libraries required to
+
+* **Fuchsia SDK**: The Fuchsia SDK is a set of tools and libraries required to
build Fuchsia components outside Fuchsia source code tree.
It contains libraries and tools for:
- * Installing/running Fuchsia and Fuchsia components/packages on a device
- * Fuchsia's interprocess communication (IPC) system (FIDL)
- * Other tasks needed to build, run, and test Fuchsia componenets
-* **googletest**: googletest is a C++ testing framework. googletest is used to
+* Installing/running Fuchsia and Fuchsia components/packages on a device
+* Fuchsia's interprocess communication (IPC) system (FIDL)
+* Other tasks needed to build, run, and test Fuchsia componenets
+* **googletest**: googletest is a C++ testing framework. googletest is used to
write tests for the rot13 and hello world samples.
googletest is only required for testing.
## Emulating x64 on x64 hosts
+
Fuchsia x64 system images can be started with the included emulator scripts and
run on x64 hosts. Native Vulkan support on the host is required for graphics support.
1. Install dependencies for Vulkan support:
- ```
+
+ ```shell
sudo apt-get install libvulkan1 mesa-vulkan-drivers
```
+
1. Download tool dependencies:
- ```
+
+ ```shell
./scripts/download-build-tools.sh
```
+
1. Generate Ninja files x64 targets:
- ```
+
+ ```shell
./buildtools/linux64/gn gen out/x64 --args='target_os="fuchsia" target_cpu="x64"'
```
-1. Start the emulator with networking support:
+
+1. List the available product bundles, and download the **terminal.qemu-x64** bundle:
+
+ ```shell
+ ./third_party/fuchsia-sdk/tools/x64/ffx product-bundle list
+ ```
+
+ ```shell
+ ./third_party/fuchsia-sdk/tools/x64/ffx product-bundle get terminal.qemu-x64
+ ```
+
+1. Start the emulator:
+
+ ```shell
+ ./third_party/fuchsia-sdk/tools/x64/ffx emu start terminal.qemu-x64
```
- ./third_party/fuchsia-sdk/bin/femu.sh -N
- ```
+
1. Start the package server:
- ```
+
+ ```shell
./third_party/fuchsia-sdk/tools/x64/fserve --image qemu-x64
```
+
1. SSH to the emulator:
- ```
+
+ ```shell
./third_party/fuchsia-sdk/tools/x64/fssh
```
## Emulating arm64 on x64 hosts
+
Fuchsia arm64 system images can be emulated on x64 hosts with the included
emulator scripts, although the performance is much slower since each instruction
needs to be emulated. Graphics output is also not supported at this time,
access is only via serial console or SSH.
1. Download tool dependencies:
- ```
+
+ ```shell
./scripts/download-build-tools.sh
```
+
1. Generate Ninja files for arm64 targets:
- ```
+
+ ```shell
./buildtools/linux64/gn gen out/arm64 --args='target_os="fuchsia" target_cpu="arm64"'
```
-1. Start the emulator with networking support and arm64 emulation:
+
+1. List the available product bundles, and download the **terminal.qemu-arm64** bundle:
+
+ ```shell
+ ./third_party/fuchsia-sdk/tools/x64/ffx product-bundle list
+ ```
+
+ ```shell
+ ./third_party/fuchsia-sdk/tools/x64/ffx product-bundle get terminal.qemu-arm64
+ ```
+
+1. Start the emulator headless. Use the QEMU engine for *much* better performance. Use a longer timeout since arm64 on x64 emulation is slower:
+
+ ```shell
+ ./third_party/fuchsia-sdk/tools/x64/ffx emu start --engine qemu --headless --startup-timeout 360 terminal.qemu-arm64
```
- ./third_party/fuchsia-sdk/bin/femu.sh -N --experiment-arm64 --image qemu-arm64 --headless --software-gpu
- ```
+
1. Start the package server:
- ```
+
+ ```shell
./third_party/fuchsia-sdk/tools/x64/fserve --image qemu-arm64
```
+
1. SSH to the emulator:
- ```
+
+ ```shell
./third_party/fuchsia-sdk/tools/x64/fssh
```
