Skip to content

getting_started.md

Latest commit

 

History

History
222 lines (154 loc) · 7.56 KB

getting_started.md

File metadata and controls

222 lines (154 loc) · 7.56 KB

Fuchsia

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

Welcome to Fuchsia! This is a top-level entry point for the project. From here we try to link to everything you need to get started, use, and develop for Fuchsia.

Prerequisites

Prepare your build environment

The Fuchsia source includes Magenta, the core platform that underpins Fuchsia. Click the link below, follow the steps under Preparing the build environment, and then return to this document. (Do not continue to the Install Toolchains section.)

[Googlers only] Goma

  • Ensure goma is installed on your machine for faster builds.

Build Fuchsia

Get the source

Follow all steps in this document and then return to this document:

Setup Build Environment

Source the env.sh script, which provides helpful shell functions for Fuchsia development. The following command also changes the command prompt and sets up for a x86-64 build.

(If you don't want to change your command prompt, omit envprompt.)

source scripts/env.sh && envprompt && fset x86-64

Alternatively, you may use the underlying build scripts.

Run envhelp to see other useful shell functions, and envhelp <function> for specific usage information.

Optionally, you might find it useful to add a shell function fuchsia as a shortcut to setup the build environment. For that, add this to your shell startup script (e.g. ~/.bashrc):

export FUCHSIA_ROOT=/path/to/my/fuchsia/source
function fuchsia() {
  source $FUCHSIA_ROOT/scripts/env.sh && envprompt && fgo && fset x86-64 "$@"
}

[optional] Customize Build Environment

By default you will get a x86-64 debug build. You can skip this section unless you want something else.

ccache accelerates builds by caching artifacts from previous builds. ccache will be enabled automatically by default if the CCACHE_DIR environment variable is set and refers to a directory that exists. To disable ccache, specify --no-ccache.

[Googlers only: goma accelerates builds by distributing compilation across many machines. If you have goma installed in ~/goma, it will used by default in preference to ccache. To disable goma, specify --no-goma.]

Run fset-usage to see a list of build options. Some examples:

fset x86-64              # x86-64 debug build
fset arm64               # arm64 debug build
fset x86-64 --release    # x86-64 release build
fset x86-64 --ccache     # x86-64 debug build, force use of ccache even if goma is available
fset x86-64 --no-goma    # x86-64 debug build, disable use of goma
fset x86-64 --no-ccache  # x86-64 debug build, disable use of ccache

Start the build

Once you have setup your build environment, simply run:

fbuild

This builds Magenta, the sysroot, and the default Fuchsia build.

After Fuchsia is built, you will have a Magenta (magenta.bin) image and a user.bootfs file in out/debug-{arch}/.

Boot Fuchsia

Boot from hardware

There are three options for booting Fuchsia on hardware: network booting (see below), booting from USB (see below), or installing Fuchsia on internal storage. In all cases you'll need to put some code on the target hardware, using a USB drive is a good option for doing this.

If you want to netboot or create a bootable USB drive, but not install Fuchsia you can use the build-bootable-usb-gigaboot.sh script. If you plan to netboot, pass the -m and -f options to skip copying over the Magenta kernel and Fuchsia system images since the bootserver will supply these.

It may be useful to look at some of the hardware specific instructions. The Raspberry Pi 3 requires very different procedures and the other guides may help with hardware-specific firmware configuration.

Once your hardware is configured, you can run fboot to start the bootserver.

Boot from QEMU

If you don't have the supported hardware, you can run Fuchsia under emulation using QEMU. Fuchsia includes prebuilt binaries for QEMU under buildtools/qemu.

The frun command will launch Magenta within QEMU, using the locally built user.bootfs:

frun

There are various flags for frun to control QEMU's configuration:

  • -m sets QEMU's memory size in MB.
  • -g enables graphics (see below).
  • -N enables networking (see below).

Use frun -h to see all available options.

Enabling Graphics

To enable graphics under QEMU, add the -g flag to frun:

frun -g

Enabling Network

Note: Networking support within QEMU is only available under x86_64.

First, configure a virtual interface for QEMU's use.

Once this is done you can add the -N and -u flags to frun:

frun -N -u $FUCHSIA_SCRIPTS_DIR/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

When Fuchsia has booted and displays the "$" shell prompt, you can run programs!

For example, to receive deep wisdom, run:

fortune

Select a tab

Fuchsia shows multiple tabs after booting. 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 application log.
  • Tabs 1, 2 and 3 contain Fuchsia shells.
  • Tab 4 contains a Magenta shell.
  • Tabs 5 and higher contain applications you've launched.

Fuchsia has two shells. The Magenta shell talks directly to Magenta and has the prompt "magenta$". The Fuchsia shell supports additional features like the Application Manager. The prompt for the Fuchsia shell is just "$". You should use the Fuchsia shell for the examples below.

Launch a graphical application

(qemu users must enable graphics with -g.)

Most graphical applications in Fuchsia use the mozart engine. You can launch such applications, commonly found in /system/apps, like this:

launch spinning_square_view

Note: Fuchsia is currently doing software-based rendering and not using the GPU.

Source code for mozart example apps is here.

Contribute changes

Additional helpful documents