Fuchsia

Pink + Purple == Fuchsia (a new Operating System)

Welcome to Fuchsia! This guide has everything you need to get started with Fuchsia.

Note: The Fuchsia source includes Zircon, the core platform that underpins Fuchsia. To work on Zircon, see Getting started with Zircon.

Get the source code

To download the Fuchsia source code and set up your build environment, follow the instructions in Get Fuchsia source code.

Configure and build Fuchsia

To build Fuchsia, you need to be able to run the fx command in your terminal.

Note: If you haven't set up your build environment, see Set up environment variables.

Set build configuration

To set your build configuration, run the following command:

fx set core.x64

The fx set command takes a PRODUCT.BOARD argument, which defines the product and board configuration of your build. This configuration informs the build system what packages to build for your Fuchsia device. core is a product with a minimal feature set, which includes common network capabilities. x64 refers to the x64 architecture.

See Configure a build for more options.

Accelerate the build with ccache

Note: This step is optional.

To accelerate Fuchsia builds, use ccache{:.external} to cache artifacts from previous builds.

To use ccache on Linux, install the following package:

sudo apt-get install ccache

For macOS, see Using CCache on Mac{:.external} for installation instructions.

ccache is enabled automatically if your CCACHE_DIR environment variable refers to an existing directory.

To override the default behavior, pass the following flags to fx set:

Force use of ccache even if other accelerators are available:
```
fx set core.x64 --ccache
```
Disable use of ccache:
```
fx set core.x64 --no-ccache
```

Build Fuchsia

To build Fuchsia, run the following command:

fx build

The fx build command executes the build to transform source code into packages and other build artifacts.

If you modify source code, re-run the fx build command to perform an incremental build, or run the fx -i build command to start a watcher, which automatically builds whenever you update source code.

See Execute a build for more information.

Set up a Fuchsia device

To run Fuchsia on a device, install Fuchsia on hardware or use an emulator.

Install Fuchsia on hardware

To get Fuchsia running on hardware, see Install Fuchsia on a device.

Set up the emulator

If you don't have supported hardware, you can run Fuchsia in an emulator using FEMU.

Configure network

For Fuchsia's ephemeral software to work in the emulator, you need to configure an IPv6 network.

Linux

To enable networking in FEMU, run the following commands:

sudo ip tuntap add dev qemu mode tap user $USER
sudo ip link set qemu up

macOS

You need to install TunTap{:.external}, kernal extensions 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:

Install Homebrew{:.external}:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Install TunTap:
```
brew cask install tuntap
```

The installation of TunTap may fail at first. In that case, do the following:

Open System Preferences.
Open Security & Privacy and select theGeneral tab.
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).
Run the install command again:
```
brew cask install tuntap
```

After installing TunTap, run the following command:

sudo chown $USER /dev/tap0

Start the emulator

To start the emulator with networking enabled, run the following command:

fx emu -N

Note: If you need to reach the internet from the emulator, configure IP forwarding and IPv4 support on the emulator TAP interface.

Pave the device with Fuchsia

In a new terminal, pave the device with your Fuchsia image:

fx serve

See Serve a build for more information.

Explore Fuchsia

When Fuchsia is booted and displays the $ prompt in the shell, you can now run components. In Fuchsia, components are the basic unit of executable software.

To run components on your Fuchsia device, see Run an example component.

Run shell commands

To shutdown or reboot Fuchsia, use the following dm commands in the shell:

dm shutdown
dm reboot

See Connect to a target shell for more information.

Select a tab

Fuchsia shows multiple tabs in the shell. At the top of the screen, the currently selected tab is highlighted in yellow.

The following keyboard shortcuts help you navigate the terminal:

Alt+Tab switches between tabs.
Alt+F{1,2,...} switches directly to a tab.
- Tab zero is the console, which displays the boot and component log.
- Tabs 1, 2 and 3 contain shells.
- Tabs 4 and higher contain components you've launched.
Alt+Up/Down scrolls up and down by lines.
Shift+PgUp/PgDown scrolls up and down by half page.
Ctrl+Alt+Delete reboots.

Run tests

To test Fuchsia on your device, see Running tests as components.

Launch a graphical component

Most graphical components in Fuchsia use the Scenic system compositor. You can launch such components (commonly found in /system/apps) using the present_view command, for example:

present_view fuchsia-pkg://fuchsia.com/spinning_square_view#meta/spinning_square_view.cmx

See Scenic example apps.

If you launch a component that uses Scenic or hardware-accelerated graphics, Fuchsia enters the graphics mode, which doesn't display the shell. To use the shell, press Alt+Escape to enter the console mode. In the console mode, Alt+Tab has the same behavior described in Select a tab. Press Alt+Escape again to return to the graphics mode.

Contribute changes

To submit your contribution to Fuchsia, see Contribute changes.