blob: 66fe1f86a85ea1293a8559039d914b8705f78643 [file] [log] [blame] [view]
# Fuchsia Emulator (FEMU)
Fuchsia can [run under emulation](/docs/
using Fuchsia Emulator (FEMU).
## Prebuilt FEMU
FEMU is downloaded by `jiri` as part of `jiri update` or `jiri run-hooks`.
FEMU is fetched into `//prebuilt/third_party/aemu`. You can run it using `fx emu`
(see section ["Run Fuchsia under FEMU"](#run_fuchsia_under_femu)).
## Network setup
In order to enable FEMU to connect to the local update server, you need to set
up a persistent TUN/TAP device used by FEMU to create emulator network interface
in advance.
### Linux network setup
On Linux, run the following commands to setup the device and interface:
sudo ip tuntap add dev qemu mode tap user $USER
sudo ifconfig qemu up
### macOS network setup
macOS does not support TUN/TAP devices out of the box; however, there is a widely
used set of kernel extensions called
[tuntaposx]({:.external} that allow
macOS to create virtual network interfaces.
For macOS 10.9 (Mavericks) and 10.10 (Yosemite), install TunTap using this
[installation package]({:.external}.
For macOS 10.13 (High Sierra) and later versions, do the following:
1. Install [Homebrew]({:.external}:
/bin/bash -c "$(curl -fsSL"
1. Install TunTap:
brew cask install tuntap
The installation of TunTap may fail at first. In that case, do the following:
1. Open `System Preferences`.
1. Open `Security & Privacy` and select the`General` tab.
1. Next to the `System software from developer "Mattias Nissler" was blocked
from loading.` message, click **Allow** (see Apple's
[User-Approved Kernel Extension Loading]({:.external}
for details).
1. Run the install command again:
brew cask install tuntap
After installing TunTap, run the following command:
sudo chown $USER /dev/tap0
## Run Fuchsia under FEMU
Ensure that you have set up and built the Fuchsia product (this example uses
`workstation` product). Currently only `x64` boards are supported.
fx set workstation.x64 --release [--with=...]
fx build
Then run Fuchsia Emulator with ssh access:
fx emu -N
To exit FEMU, run `dm poweroff` in the FEMU terminal.
### Run FEMU without GUI
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
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
#### `fx emu-remote` Command
These instructions work for local machines with macOS or Linux, and require SSH
access to a Linux workstation that is already able to run FEMU.
On the terminal of your local machine, type the following to start the emulator
with networking on remote workstation and have the output forwarded using WebRTC
to a Chrome tab on local machine:
fx emu-remote <remote-hostname> -- -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 --display :0 <remote-hostname> -- -N
Any arguments after “--” will be passed to the fx emu invocation on the remote