Fuchsia Samples

A collection of samples demonstrating how to build, run, and test Fuchsia components outside the Fuchsia source code tree.

Caution: These samples might be changed in backward-incompatible ways and are not recommended for production use. This repository is not subject to any SLA or deprecation policy.

Setup

  1. Install required dependencies for building:

    sudo apt-get install curl unzip clang python3 build-essential
    
  2. Clone this repo and submodules:

    git clone https://fuchsia.googlesource.com/samples --recursive --depth 1
    

    If you have already cloned this repo without the --recursive flag you can run git submodule init && git submodule update --recursive to download the submodules. The git history is quite large, and you can download only the newest commit with --depth 1. Remove this flag if you want the entire history.

  3. Change directory to the root of the repo and setup and run the tests:

    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.

C++ Samples (GN)

Supported host platforms and build systems

The C++ samples in this repo only support Linux hosts and the GN build system.

Getting started

To get started see the SDK documentation.

Samples

bouncing_ball

Example application using Scenic to render animated graphics.

To get started, see the README.

calculator

FIDL protocol server and client implementing a calculator interface.

To get started, see the README.

hello_world

Basic component that prints a Hello World greeting.

To get started, see the README.

rot13

FIDL protocol server and client implementing a simple ROT13 encoding interface.

To get started, see the README.

realm_builder

Integration test component using the Realm Builder library.

To get started, see the README.

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 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 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:
    sudo apt-get install libvulkan1 mesa-vulkan-drivers
    
  2. Download tool dependencies:
    ./scripts/download-build-tools.sh
    
  3. Generate Ninja files x64 targets:
    ./buildtools/linux64/gn gen out/x64 --args='target_os="fuchsia" target_cpu="x64"'
    
  4. Start the emulator with networking support:
    ./third_party/fuchsia-sdk/bin/femu.sh -N
    
  5. Start the package server:
    ./third_party/fuchsia-sdk/tools/x64/fserve --image qemu-x64
    
  6. SSH to the emulator:
    ./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:
    ./scripts/download-build-tools.sh
    
  2. Generate Ninja files for arm64 targets:
    ./buildtools/linux64/gn gen out/arm64 --args='target_os="fuchsia" target_cpu="arm64"'
    
  3. Start the emulator with networking support and arm64 emulation:
    ./third_party/fuchsia-sdk/bin/femu.sh -N --experiment-arm64 --image qemu-arm64 --headless --software-gpu
    
  4. Start the package server:
    ./third_party/fuchsia-sdk/tools/x64/fserve --image qemu-arm64
    
  5. SSH to the emulator:
    ./third_party/fuchsia-sdk/tools/x64/fssh