blob: 3db26f997a804a54e608c85ebd96738193957f61 [file] [log] [blame] [view]
# Fuchsia
Pink + Purple == Fuchsia (a new Operating System)
Welcome to Fuchsia! This document has everything you need to get started with
Fuchsia.
*** note
NOTE: The Fuchsia source includes
[Zircon](/zircon/README.md),
the core platform that underpins Fuchsia.
The Fuchsia build process will build Zircon as a side-effect;
to work on Zircon only, read and follow Zircon's
[Getting Started](/zircon/docs/getting_started.md)
doc.
***
[TOC]
## Prerequisites
### Prepare your build environment (once per build environment)
#### Debian
```
sudo apt-get install build-essential curl git python unzip
```
#### macOS
1. Install Command Line Tools:
```
xcode-select --install
```
1. In addition to Command Line Tools, you also need to
install a recent version of [Xcode](https://developer.apple.com/xcode/).
## Get the Source
Follow [the instructions to get the Fuchsia source](development/source_code/README.md)
and then return to this document.
## Build Fuchsia
Note: A quick overview of the basic build-and-pave workflow can be found [here](development/workflows/build_and_pave_quickstart.md).
### Build
If you added `.jiri_root/bin` to your path as part of getting the source code,
the `fx` command should already be in your path. If not, the command is also
available as `scripts/fx`.
```
fx set core.x64 --with //bundles:kitchen_sink
fx build
```
The first command selects the build configuration you wish to build and
generates the build system itself in an output directory (e.g., `out/x64`).
Fuchsia can ephemerally download [packages](development/build/packages.md) over the network;
here we use the `--available` flag to make the necessary packages covered in this guide
available for download.
The second command actually executes the build, transforming the source code in
build products. If you modify the source tree, you can do an incremental build
by re-running the `fx build` command alone. `fx -i build` starts a watcher
and automatically builds whenever a file is changed.
Alternatively, you can use the [underlying build system directly](development/build/README.md).
#### [optional] Customize Build Environment
By default you will get a x64 debug build. You can skip this section unless
you want something else.
Run `fx set` to see a list of build options. Some examples:
```
fx set workstation.x64 # x64 debug build
fx set core.arm64 # arm64 debug build
fx set core.x64 --release # x64 release build
```
#### [optional] Accelerate builds with `ccache` and `goma`
`ccache` accelerates builds by caching artifacts from previous builds. `ccache`
is enabled automatically if the `CCACHE_DIR` environment variable is set and
refers to a directory that exists.
[Googlers only: `goma` accelerates builds by distributing compilation across
many machines. If you have `goma` installed in `~/goma`, it is used by default.
It is also used by default in preference to `ccache`.]
To override the default behaviors, pass flags to `fx set`:
```
--ccache # force use of ccache even if goma is available
--no-ccache # disable use of ccache
--no-goma # disable use of goma
```
## Boot Fuchsia
### Installing and booting from hardware
To get Fuchsia running on hardware requires using the paver, which these
[instructions](development/workflows/paving.md) will help you get up and running
with.
Note: A quick overview of the basic build-and-pave workflow can be found
[here](development/workflows/build_and_pave_quickstart.md).
### Boot from QEMU
If you don't have the supported hardware, you can run Fuchsia under emulation
using [QEMU](/zircon/docs/qemu.md).
Fuchsia includes prebuilt binaries for QEMU under `buildtools/qemu`.
The `fx run` command will launch Zircon within QEMU, using the locally built
disk image:
```
fx run
```
There are various flags for `fx run` to control QEMU's configuration:
* `-m` sets QEMU's memory size in MB.
* `-g` enables graphics (see below).
* `-N` enables networking (see below).
* `-k` enables KVM acceleration on Linux.
Use `fx run -h` to see all available options.
#### QEMU tips
* `ctrl+a x` will exit QEMU in text mode.
* `ctrl+a ?` or `ctrl+a h` prints all supported commands.
#### Enabling Graphics
Note: Graphics under QEMU are extremely limited due to a lack of Vulkan
support. Only the Zircon UI renders.
To enable graphics under QEMU, add the `-g` flag to `fx run`:
```
fx run -g
```
#### Enabling Network
First, [configure](/zircon/docs/qemu.md#Enabling-Networking-under-QEMU) a
virtual interface for QEMU's use.
Once this is done you can add the `-N` and `-u` flags to `fx run`:
```
fx run -N -u scripts/start-dhcp-server.sh
```
The `-u` flag runs a script that sets up a local DHCP server and NAT to
configure the IPv4 interface and routing.
## Explore Fuchsia
In a separate shell, start the development update server, if it isn't already
running:
```
fx serve -v
```
Boot Fuchsia with networking. This can be done either in QEMU via the `-N` flag,
or on a paved hardware, both described above.
When Fuchsia has booted and displays the "$" shell prompt, you can run programs!
For example, to receive deep wisdom, run:
```
fortune
```
To shutdown or reboot Fuchsia, use the `dm` command:
```
dm help
dm shutdown
```
### Change some source
Almost everything that exists on a Fuchsia system is stored in a Fuchsia
package. A typical development
[workflow](development/workflows/package_update.md) involves re-building and
pushing Fuchsia packages to a development device or QEMU virtual device.
Make a change to the rolldice binary in `garnet/bin/rolldice/src/main.rs`.
Re-build and push the rolldice package to a running Fuchsia device with:
```
fx build-push rolldice
```
From a shell prompt on the Fuchsia device, run the updated rolldice component
with:
```
rolldice
```
### Select a tab
Fuchsia shows multiple tabs after booting [with graphics
enabled](#enabling-graphics). The currently selected tab is highlighted in
yellow at the top of the screen. You can switch to the next tab using Alt-Tab on
the keyboard.
- Tab zero is the console and displays the boot and component log.
- Tabs 1, 2 and 3 contain shells.
- Tabs 4 and higher contain components you've launched.
Note: to select tabs, you may need to enter "console mode". See the next section for details.
### Launch a graphical component
QEMU does not support Vulkan and therefore cannot run our graphics stack.
Most graphical components in Fuchsia use the [Scenic](/garnet/bin/ui/) system
compositor. You can launch such components, commonly found in `/system/apps`,
like this:
```
launch spinning_square_view
```
Source code for Scenic example apps is [here](/garnet/examples/ui).
When you launch something that uses Scenic, uses hardware-accelerated graphics, or if you build
the [default](https://fuchsia.googlesource.com/topaz/+/master/packages) package (which will
boot into the Fuchsia System UI), Fuchsia will enter "graphics mode", which will not display any
of the text shells. In order to use the text shell, you will need to enter "console mode" by
pressing Alt-Escape. In console mode, Alt-Tab will have the behavior described in the previous
section, and pressing Alt-Escape again will take you back to the graphical shell.
If you would like to use a text shell inside a terminal emulator from within the graphical shell
you can launch the [term](https://fuchsia.googlesource.com/topaz/+/master/app/term) by selecting the
"Ask Anything" box and typing `moterm`.
## Running tests
Compiled test binaries are installed in `/pkgfs/packages/`, and are referenced by a URI.
You can run a test by invoking it in the terminal. E.g.
```
run fuchsia-pkg://fuchsia.com/ledger_tests#meta/ledger_unittests.cmx
```
If you want to leave Fuchsia running and recompile and re-run a test, run
Fuchsia with networking enabled in one terminal, then in another terminal, run:
```
fx run-test <test name> [<test args>]
```
You may wish to peruse the [testing FAQ](development/workflows/testing_faq.md).
## Contribute changes
* See [CONTRIBUTING.md](/CONTRIBUTING.md).
## Additional helpful documents
* [Fuchsia documentation](README.md) hub
* Working with Zircon - [copying files, network booting, log viewing, and
more](/zircon/docs/getting_started.md#Copying-files-to-and-from-Zircon)
* [Documentation Standards](best-practices/documentation_standards.md) - best practices
for documentation
* [Information on the system bootstrap component](/garnet/bin/sysmgr/).
* [Workflow tips and FAQ](development/workflows/workflow_tips_and_faq.md) that help increase
productivity.