Google is committed to advancing racial equity for Black communities. See how.

Run Fuchsia Emulator (FEMU)

This document describes how to run Fuchsia under emulation using the Fuchsia Emulator (FEMU), covering differnent developer environments and setups.

For more information on FEMU, see the Fuchsia emulator overview.

Prerequisites

Before you run FEMU, you must:

Run Fuchsia on FEMU

If you haven't already, set up and build Fuchsia, using fx set, specifying a qemu board and supported product. This example uses the core product:

fx set core.qemu-x64 --release [--with=...]
fx build

Next, run FEMU with ssh access (with the -N flag):

fx emu -N

Run FEMU without GUI support

If you don't need graphics or working under the remote workflow, you can run FEMU in headless mode by adding --headless argument to the fx emu command, for example:

fx emu -N --headless

Specify GPU used by FEMU

By default, FEMU tries using the host GPU automatically if it is available, and will fall back to software rendering using SwiftShader if host GPU is unavailable.

You can also add argument --host-gpu or --software-gpu to fx emu command to enforce FEMU to use a specific graphics device.

Develop remotely

There are multiple ways to develop Fuchsia remotely using FEMU, and all the workflow supports GPU acceleration without requiring GPU drivers and runtime on the local machine.

Remote Desktop

These instructions require remote access to the remote machine using remote desktop tools like Chrome Remote Desktop.

Follow general remote desktop instructions for logging in to your remote machine. Once logged in, follow standard Fuchsia development instructions for building Fuchsia, and use the following command to run Fuchsia in the emulator inside your remote desktop session:

fx emu

The emulator will use Swiftshader instead of real GPU hardware for GPU acceleration when running inside Chrome Remote Desktop. Performance will be worse than using real GPU hardware but the benefit is that it runs on any workstation.

fx emu-remote Command

These instructions work for local machines with macOS or Linux, and require SSH access to a Linux workstation capable of building Fuchsia.

On the terminal of your local machine, type the following to build, fetch the artifacts and start the emulator with networking:

fx emu-remote REMOTE-WORKSTATION-NAME  -- -N

Alternatively, start the emulator on remote workstation, and open an WebRTC connection to it using local browser.

On the terminal of your local machine, type the following to start the emulator with networking on REMOTE-WORKSTATION-NAME and have the output forwarded using WebRTC to a Chrome tab on local machine:

fx emu-remote --stream REMOTE-WORKSTATION-NAME -- -N

This by default uses software rendering and GPU acceleration is supported by using an existing X server on the remote machine with access to GPU hardware:

fx emu-remote --stream --display :0 REMOTE-WORKSTATION-NAME -- -N

Any arguments after “--” will be passed to the fx emu invocation on the remote machine.

Exit FEMU

To exit FEMU, run dm poweroff in the FEMU terminal.

Next steps

Once you are running Fuchsia on FEMU, you can: