blob: 75f024556362bbce61a1a7295e1718f8e185d792 [file] [log] [blame] [view]
# Fuchsia
Pink + Purple == Fuchsia (a new Operating System)
Welcome to Fuchsia! This guide has everything you need to get started with
Note: The Fuchsia source includes [Zircon](/zircon/, the core platform
that underpins Fuchsia. To work on Zircon, see
[Getting started with Zircon](/docs/development/kernel/
## Get the source code
To download the Fuchsia source code and set up your build environment, follow
the instructions in
[Get Fuchsia source code](/docs/development/source_code/
## Configure and build Fuchsia {#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](/docs/development/source_code/
### 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](/docs/concepts/build_system/
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
See [Configure a build](/docs/development/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](/docs/development/build/ for more
## 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](/docs/development/hardware/
### Set up the emulator
If you don't have supported hardware, you can run Fuchsia in an emulator using
#### Configure network
For Fuchsia's ephemeral software to work in the emulator, you need to configure
an IPv6 network.
##### Linux
To enable networking in QEMU, 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:
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
#### 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](/docs/development/build/ for more
## Explore Fuchsia {#explore-fuchsia}
When Fuchsia is booted and displays the `$` prompt in the shell, you can now run
[components](/docs/concepts/components/). In Fuchsia, components are the basic
unit of executable software.
To run components on your Fuchsia device, see
[Run an example component](/docs/development/run/
### Run shell commands
To shutdown or reboot Fuchsia, use the following `dm` commands in the shell:
dm shutdown
dm reboot
[Connect to a target shell](/docs/development/build/
for more information.
### Select a tab {#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](/docs/development/testing/
## Launch a graphical component
Warning: QEMU doesn't support Vulkan and therefore cannot run the graphics
stack. Commands in this section don't work on QEMU.
Most graphical components in Fuchsia use the
[Scenic](/docs/concepts/graphics/scenic/ system compositor. You can
launch such components (commonly found in `/system/apps`) using the
`present_view` command, for example:
present_view fuchsia-pkg://
See [Scenic example apps](/src/ui/examples).
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](#select-a-tab).
Press `Alt+Escape` again to return to the graphics mode.
## Contribute changes
To submit your contribution to Fuchsia, see
[Contribute changes](/docs/development/source_code/
## See also
* [fx workflows](/docs/development/build/
* [Workflow tips and questions](/docs/development/source_code/
* [Configure editors](/docs/development/editors/)
* [Source code layout](/docs/concepts/source_code/
* [Build system](/docs/concepts/build_system/