Set up and start the Fuchsia emulator (FEMU)

This guide provides instructions on how to set up and run the Fuchsia emulator (FEMU), including networking and GPU support setup.

The steps are:

Prerequisites.
Build Fuchisa for FEMU.
Enable KVM (Optional).
Start FEMU.

Prerequisites

Running FEMU requires that you've completed the following tasks:

Build Fuchsia for FEMU

To run FEMU, you first need to build a Fuchsia system image that supports the emulator environment. The example below uses qemu-x64 for the board and workstation for the product.

To build a FEMU Fuchsia image, do the following:

Set the Fuchsia build configuration:
```
fx set workstation.qemu-x64 --release
```
Build Fuchsia:
```
fx build
```

For more information on supported boards and products, see the Fuchsia emulator (FEMU) overview page.

Enable KVM (Optional)

(Linux only) If KVM is supported on your machine, update permission to enable KVM.

{Linux}
To enable KVM on your machine, do the following:
Note: You only need to do this once per machine.
1. Add yourself to the kvm group on your machine:
```
sudo usermod -a -G kvm ${USER}
```
2. Log out of all desktop sessions to your machine and then log in again.
3. 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 in Step 2 to take effect.
{macOS}
No additional setup is required for macOS.
Instead of KVM, the Fuchsia emulator on macOS uses the Hypervisor framework{: .external}.

Start FEMU

Start the Fuchsia emulator on your machine.

{Linux}
The command below allows FEMU to access external networks:
```
fx vdl start -N -u {{ '<var>' }}FUCHSIA_ROOT{{ '</var>' }}/scripts/start-unsecure-internet.sh
```
Replace the following:
- FUCHSIA_ROOT: The path to the Fuchsia checkout on your machine (for example, ~/fuchsia).
This command opens a new terminal window with the title “Fuchsia Emulator”. After the Fuchsia emulator is launched successfully, the terminal starts a SSH console. You can run shell commands on this console, as you would on a Fuchsia device.
However, if you want to run FEMU without access to external network, run the following command instead:
```
fx vdl start -N
```
The -N option enables the fx tool to discover this FEMU instance as a device on your machine.
{macOS}
To start FEMU on macOS, do the following:
1. Start FEMU:
```
fx vdl 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 prints an instruction on running fx set-device. Make a note of this command for the next step.
2. Run the fx set-device command to specify the launched Fuchsia emulator SSH port:
```
fx set-device 127.0.0.1:{{ '<var>' }}SSH_PORT{{ '</var>' }}
```
  Replace the following:
  - SSH_PORT: Use the value from the fx vdl start command's output in Step 1.

Next steps

For the next steps, check out the following resources:

To learn more about how FEMU works, see the Fuchsia emulator (FEMU) overview page.
To learn more about Fuchsia device commands and Fuchsia workflows, see Explore Fuchsia.

Appendices

This section provides additional FEMU options.

Input options

By default FEMU uses multi-touch input. You can add the argument --pointing-device mouse for mouse cursor input instead.

fx vdl start --pointing-device mouse

Run FEMU without GUI support

If you don't need graphics or working under the remote workflow, you can run FEMU in headless mode:

fx vdl start --headless

Specify GPU used by FEMU

By default, FEMU launcher uses software rendering using SwiftShader{: .external}. To force FEMU to use a specific graphics emulation method, use the parameters --host-gpu or --software-gpu to the fx vdl start command.

These are the valid commands and options:

Supported hardware for graphics acceleration

FEMU currently supports a limited set of GPUs on macOS and Linux for hardware graphics acceleration. FEMU uses a software renderer fallback for unsupported GPUs.

Exit FEMU

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

Configure IPv6 network

This section provides instructions on how to configure an IPv6 network for FEMU on Linux machine using TUN/TAP{: .external}.

{Linux}
Note: The fx vdl command automatically performs the instructions below.
To enable networking in FEMU using tap networking{: .external}, do the following:
1. Set up tuntap:
```
sudo ip tuntap add dev qemu mode tap user $USER
```
2. Enable the network for qemu:
```
sudo ip link set qemu up
```
{macOS}
No additional IPv6 network setup is required for macOS.
User Networking (SLIRP){: .external} 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.