Pink + Purple == Fuchsia (a new Operating System)
Welcome to Fuchsia! This document has everything you need to get started with Fuchsia.
Note: The Fuchsia source includes Zircon, 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 doc.
sudo apt-get install build-essential curl git python unzip
Install Command Line Tools:
xcode-select --install
In addition to Command Line Tools, you also need to install a recent version of Xcode.
Follow the instructions to get the Fuchsia source and then return to this document.
Note: A quick overview of the basic build-and-pave workflow can be found here.
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 fx set command configures the contents of your build and generates build rules and metadata in the default output directories, out/default and out/default.zircon. The argument core.x64 refers to product and board definitions that describe, among other things, what packages are built and available to your Fuchsia device.
A Fuchsia device can ephemerally download and install packages over the network, and in a development environment, your development workstation is the source of these ephemeral packages. The board and product definitions contain a set of packages, but if you need to add other packages, use the --with flag. This example includes kitchen_sink, which is an idiom in english meaning “practically everything”. As you become more focused in your development, you will probably use more specific --with options to minimize build times.
The fx build command executes the build, transforming source code into packages and other build artifacts. If you modify source code, 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.
See the underlying build system for more details.
{% dynamic if user.is_googler %}
goma accelerates builds by distributing compilation across many machines. If you have goma installed in ~/goma, it is used by default.
If goma cannot be found, ccache is used if available.
It is also used by default in preference to ccache.
To disable using goma, pass --no-goma to fx set.
{% dynamic endif %}
ccache{: .external} 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.
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
To get Fuchsia running on hardware requires using the paver, which these instructions will help you get up and running with.
Note: A quick overview of the basic build-and-pave workflow can be found here.
If you don't have the supported hardware, you can run Fuchsia under emulation using QEMU. Fuchsia includes prebuilt binaries for QEMU under prebuilt/third_party/qemu.
The fx emu command will launch Fuchsia within QEMU, using the locally built disk image:
fx emu
There are various flags for fx emu to control the emulator configuration:
-N enables networking (see below).--headless disable graphics (see below).-c pass additional arguments to the kernel.Use fx emu -h to see all available options.
Note: Before you can run any commands, you will need to follow the instructions in the Explore Fuchsia section below.
In order for ephemeral software to work in the emulator, an IPv6 network must be configured.
On macOS: Install “http://tuntaposx.sourceforge.net/download.xhtml” On Linux: Run sudo ip tuntap add dev qemu mode tap user $USER && sudo ip link set qemu up
Now the emulator can be run with networking enabled:
fx emu -N
The above is sufficient for ephemeral software (that is served by fx serve, see below) to work, including many tools such as uname and fortune (if built).
Users who also wish to reach the internet from the emulator will need to configure some manner of IP forwarding and IPv4 support on the emulator TAP interface. Details of this process are beyond the scope of this document.
In a separate shell, start the development update server, if it isn't already running:
fx serve
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 shutdown
dm reboot
Almost everything that exists on a Fuchsia system is stored in a Fuchsia package. A typical development workflow involves re-building and pushing Fuchsia packages to a development device or QEMU virtual device.
Make a change to the rolldice binary in examples/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
Fuchsia shows multiple tabs after booting with graphics enabled. The currently selected tab is highlighted in yellow at the top of the screen.
The following keyboard shortcuts help you navigate the terminal:
Note: To select tabs, you may need to enter “console mode”. See the next section for details.
Warning: QEMU does not support Vulkan and therefore cannot run our graphics stack. Commands in this section will not work on QEMU.
Most graphical components in Fuchsia use the Scenic system compositor. You can launch such components, commonly found in /system/apps, like this:
present_view fuchsia-pkg://fuchsia.com/spinning_square_view#meta/spinning_square_view.cmx
Source code for Scenic example apps is here.
When you launch something that uses Scenic, uses hardware-accelerated graphics, or if you build the default 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.
Compiled test binaries are cached in pkgfs like other components, and are referenced by a URI. You can run a test by invoking it in the terminal. For example:
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.