This guide provides instructions on how to set up and launch the Fuchsia emulator (FEMU) on your machine.
The steps are:
- Prerequisites.
- Build Fuchsia for FEMU.
- Enable VM acceleration (Optional).
- Start FEMU.
- Discover FEMU.
1. Prerequisites
Running FEMU requires that you've completed the following guides:
2. Build Fuchsia for FEMU
To run FEMU, you first need to build a Fuchsia system image that supports
the emulator environment. This guide uses qemu-x64
for the board
and workbench_eng
for the product as an example.
To build a FEMU Fuchsia image, do the following:
Set the Fuchsia build configuration:
fx set workbench_eng.qemu-x64 --release
Build Fuchsia:
fx build
For more information on supported boards and products, see the Fuchsia emulator (FEMU) overview page.
3. Enable VM acceleration (Optional)
(Linux only) Most Linux machines support VM acceleration through KVM, which greatly improves the performance and usability of the emulator.
If KVM is available on your machine, update your group permission to enable KVM.
Linux
To enable KVM on your machine, do the following:
Add yourself to the
kvm
group on your machine:sudo usermod -a -G kvm ${USER}
Log out of all desktop sessions to your machine and then log in again.
To verify that KVM is configured correctly, run the following command:
if [[ -r /dev/kvm ]] && grep '^flags' /proc/cpuinfo | grep -qE 'vmx|svm'; then echo 'KVM is working'; else echo 'KVM not working'; fi
Verify that this command prints the following line:
KVM is working
If you see
KVM not working
, you may need to reboot your machine for the permission change to take effect.
macOS
No additional setup is required for macOS.
Instead of KVM, the Fuchsia emulator on macOS uses the Hypervisor framework.
4. Start FEMU
Start the package server
Prior to starting the emulator, start the package server.
To start the the package server, run the following command:
fx serve
Start the emulator
To start the emulator on your Linux machine, do the following:
Linux
Configure the upscript by running the following command:
ffx config set emu.upscript FUCHSIA_ROOT/scripts/start-unsecure-internet.sh
start-unsecure-internet.sh
is an example upscript.FUCHSIA_ROOT
is the path to your Fuchsia directory.
Start FEMU
To start the emulator with access to external networks, run the following command:
ffx emu start --net tap
--net
specifies the networking mode for the emulator.--net tap
attaches to a Tun/Tap interface.
To start the emulator without access to external networks, run the following command:
ffx emu start --net none
Starting the emulator opens a new window with the title Fuchsia Emulator. When the emulator is finished booting, you are returned to the command prompt, and the emulator runs in the background.
macOS
To start FEMU on macOS, do the following:
Start FEMU:
ffx emu start
If you launch FEMU for the first time on your macOS (including after a reboot), a window pops up asking if you want to allow the process
aemu
to run on your machine. Click Allow.This command opens a new window with the title Fuchsia Emulator. When the emulator is finished booting, you are returned to the command prompt, and the emulator runs in the background.
(Optional) If you need to specify the launched Fuchsia emulator, you can run the
fx set-device
command in the same terminal:fx set-device NAME
Replace the following:
NAME
: Use the desired value from theffx emu list
orffx target list
command's output.fuchsia-emulator
is the default value.
5. Discover FEMU
To discover the Fuchsia emulator as a running Fuchsia device, run the following command:
ffx target list
This command prints output similar to the following:
$ ffx target list
NAME SERIAL TYPE STATE ADDRS/IP RCS
fuchsia-emulator <unknown> workbench_eng.qemu-x64 Product [fe80::866a:a5ea:cd9e:69f6%qemu] N
fuchsia-emulator
is the default node name of the Fuchsia emulator.
The output of ffx target list
is influenced by the --net
option in the
following ways:
--net none
disables networking, which causes the device to not be discoverable when runningffx target list
.--net tap
and--net user
allow the device to be discoverable when runningffx target list
.
Next steps
To learn more about Fuchsia device commands and Fuchsia workflows, see Explore Fuchsia.
Appendices
This section provides additional FEMU options.
See all available flags
To see a full list of the emulator's supported flags, run the following command:
ffx emu start --help
Run FEMU without GUI support
If you don't need graphics or working under the remote workflow, you can run FEMU in headless mode:
ffx emu start --headless
Reboot FEMU
To reboot FEMU, run the following ffx
command:
ffx target reboot
Stop FEMU
To stop FEMU, run the following ffx
command:
ffx emu stop
Configure IPv6 network
This section provides instructions on how to configure an IPv6 network for FEMU on Linux machine using TUN/TAP.
Linux
To enable networking in FEMU using tap networking, do the following:
Set up
tuntap
:sudo ip tuntap add dev qemu mode tap user $USER
Enable the network for
qemu
:sudo ip link set qemu up
macOS
No additional IPv6 network setup is required for macOS.
User Networking (SLIRP) is the default network setup
for FEMU on macOS – while this setup does not support Fuchsia device
discovery, you can still use fx
tools (for example,fx ssh
) to
interact with your FEMU instance.
Specify GPU mode for FEMU (Experimental)
By default, the FEMU launcher uses SwiftShader
Vulkan ICD for host graphics rendering. With the --gpu
flag, you can set the
emulator to use the host GPU hardware for rendering. See the following options:
GPU emulation method | Description | Flag |
---|---|---|
SwiftShader | Use SwiftShader libraries to simulate GPU processing. This is the default mode. | ffx emu start --gpu swiftshader_indirect |
Hardware (host GPU) | Use the host machine's GPU directly to perform GPU processing. | ffx emu start --gpu host |
Auto | Resolve to host if there is a hardware GPU available or
swiftshader_indirect if there isn't a hardware GPU available. |
ffx emu start --gpu auto |