Start the Fuchsia emulator

This guide provides instructions on how to set up and launch the Fuchsia emulator (FEMU) on your machine.

The steps are:

Prerequisites.
Build Fuchisa 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 workstation for the product as an example.

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.

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 Fuchsia emulator on your machine.

Linux

The command below allows FEMU to access external networks:

fx vdl start -N -u FUCHSIA_ROOT/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 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:

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 opens a new 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.

Additionally, the command's output includes an instruction that asks you to run fx set-device. Make a note of this instruction for the next step.
Open a new terminal and run the fx set-device command to specify the launched Fuchsia emulator SSH port:
```
fx set-device 127.0.0.1:SSH_PORT
```
Replace the following:
- SSH_PORT: Use the value from the fx vdl start command's output in Step 1.

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-5254-0063-5e7a    <unknown>    workstation.qemu-x64    Product    [fe80::866a:a5ea:cd9e:69f6%qemu]    N

fuchsia-5254-0063-5e7a is the default node name of the Fuchsia emulator.

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 supported flags:

fx vdl start --help

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. 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:

GPU Emulation method	Explanation	Flag
Hardware (host GPU)	Uses the host machine’s GPU directly to perform GPU processing.	`fx vdl start --host-gpu`
Software (host CPU)	Uses the host machine’s CPU to simulate GPU processing.	`fx vdl start --software-gpu`

Reboot FEMU

To reboot FEMU, run the following ffx command:

ffx target reboot

Exit FEMU

To exit FEMU, run the following ffx command:

ffx target off

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.