Below is just about everything you need to do to install Fuchsia on your Mac OS machine.

It has been tested on Mac OS Mojave, but it should run on any recent version of the OS.

Warning: Fuchsia is still in pre-alpha. Install and run it at your own risk.

Prerequisites

What follows is a list of the prerequisites necessary to install Fuchsia on your machine. If you have everything already installed and ready to go you can safely skip this section, otherwise, follow along our step by step instructions on how to get everything set up.

What you’re going to need:

• Brew
• Xcode
• Git
• Go

Brew

Homebrew is the first thing every developer should install on their Mac. As their creators state brew is the missing package manager for Mac OSX. To install homebrew on your machine open your Terminal.app and paste /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)".

Download Xcode

Download Xcode from Apple’s website and Install it.

Unzip the file and open it proceeding through all the steps of the configuration wizard. Once opened, make sure the developer tools for the command line are installed by opening a Terminal window and running:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Accept Apple’s license agreement by running xcodebuild -license.

Git

You can install git through brew. Run brew install git to install git.

Go

You can install go through brew as well. Run brew install go to install go.

Obtaining Fuchsia’s Source Code

Open a terminal window and navigate to the directory where you want to download Fuchsia into.

Run the following snippet to download the source code and decode it:

curl -s "https://fuchsia.googlesource.com/fuchsia/+/master/scripts/bootstrap?format=TEXT" | base64 --decode | bash

You can now make yourself some coffee, it will take a while. Make sure you have a lot of free space, especially if you plan to use the emulator. On my machine the Fuchsia folder has passed 100GB in size. I don’t think this is typical, but I’m not sure.

Configure the Environment Variables

Open your environment file. If you’re using bash, which is the default shell for Mac OSX up to Mojave, the file to edit is .bash_profile in your home directory. Add the following lines at the bottom of the file to add the entry for Fuchsia. Mind that I’ve placed the folder inside the projects folder on the Desktop, but your installation directory might be different. Update the path accordingly.

export PATH="/Users/$USER/Desktop/projects/fuchsia/fuchsia/.jiri_root/bin:$PATH"

This will add both jiri and fx to your environment. Restart your terminal to load the changes and type jiri. You should be greeted by this:

ERROR: jiri: no command specified

Command jiri is a multi-purpose tool for multi-repo development.

Usage:
   jiri [flags] <command>

The jiri commands are:
   branch              Show or delete branches
   bootstrap           Bootstrap essential packages
   diff                Prints diff between two snapshots
   edit                Edit manifest file
   fetch-packages      Fetch cipd packages using JIRI_HEAD version manifest
   generate-gitmodules Create a .gitmodule and a .gitattributes files for git submodule repository
   grep                Search across projects.
   import              Adds imports to .jiri_manifest file
   init                Create a new jiri root
   package             Display the jiri packages
   patch               Patch in the existing change
   project             Manage the jiri projects
   project-config      Prints/sets project's local config
   manifest            Reads <import>, <project> or <package> information from a manifest file
   override            Add overrides to .jiri_manifest file
   resolve             Generate jiri lockfile
   run-hooks           Run hooks using local manifest
   runp                Run a command in parallel across jiri projects
   selfupdate          Update jiri tool
   snapshot            Create a new project snapshot
   source-manifest     Create a new source-manifest from current checkout
   status              Prints status of all the projects
   update              Update all jiri projects
   upload              Upload a changelist for review
   version             Print the jiri version
   help                Display help for commands or topics
Run "jiri help [command]" for command usage.

The jiri additional help topics are:
   filesystem     Description of jiri file system layout
   manifest-files Description of manifest files
Run "jiri help [topic]" for topic details.

The global flags are:
 -color=auto
   Use color to format output. Values can be always, never and auto
 -j=24
   Number of jobs (commands) to run simultaneously
 -metadata=<just specify -metadata to activate>
   Displays metadata for the program and exits.
 -progress-window=5
   Number of progress messages to show simultaneously. Should be between 1 and 10
 -q=false
   Same as -quiet
 -quiet=false
   Only print user actionable messages.
 -root=
   Jiri root directory
 -show-progress=true
   Show progress.
 -show-root=<just specify -show-root to activate>
   Displays jiri root and exits.
 -time=false
   Dump timing information to stderr before exiting the program.
 -time-log-threshold=10s
   Log time taken by operations if more than the passed value (eg 5s). This only works with -v and -vv.
 -v=false
   Print debug level output.
 -vv=false
   Print trace level output.

Run "jiri help -style=full" to show all flags.

If it did not the environment was not configured correctly.

Build and Install Fuchsia

Before starting the build process load the fx env into your shell: source scripts/fx-env.sh.

Configure the installer by running: fx set core.x64 --with //bundles:kitchen_sink.

Force the System to use Python2

This is only necessary if you have installed python3 and it’s your default settings for python on the system. If you don’t have python3 and only have python2 you don’t need to use virtual environment since the system will automatically use python2 and can safely skip this part.

Make sure you are using python2 and NOT python3. If you don’t the installation will fail with the following error AttributeError: 'dict' object has no attribute 'iteritems' since it requires python2 to install and run.

You can do it by using virtual environment (assuming you have python 2.7 installed):

virtualenv -p /usr/bin/python2.7 venv
source venv/bin/activate

Build Fuchsia

Make sure to run the following commands from inside the fuchsia working directory.

To start the build process run: fx build. This will take a while as well, possibly more than the download if you have a fast internet connection.

For the purpose of this tutorial, we are going to run Fuchsia on the Emulator. You can also install it/use it on a real device (the list is pretty limited by now, but it’s expected to grow in the future) by following the guides from Google in the source section below.

If the installation process fails don’t be afraid to try again. It worked for me the second time around.

Configure and Test your Fuchsia Installation

Run the emulator using: fx run -g. The -g flag enables graphics. Be wary that graphics on the emulator is really limited though:

QEMU does not support Vulkan and therefore cannot run our graphics stack.

Note: Graphics under QEMU are extremely limited due to a lack of Vulkan support. Only the Zircon UI renders.

This will create the disk image and start the emulator.

Click on the window to give focus to the emulator.

For now we are not able to run any program. If you try to run the fortune application by typing fortune and enter it will print an error. We are going to fix that in the next section.

Run dm shutdown to close the emulator.

Install tuntap Using Brew and Configure the Network Interface

Before running any application we need to enable networking on the emulator to allow the host OS to communicate to the emulator and load packages onto it.

Install tuntap: brew cask install tuntap

Since it’s a kernel extension you need to go to Preferences > Security and Privacy > General > Allow to enable it to run.

Make sure the output is successful: tuntap was successfully installed!, otherwise allow the installation again from Preferences and go through the install process one more time.

You might need to change the owner of the tap0 channel after it installs by running: sudo chown $USER /dev/tap0

Enable Networking on Fuchsia

Start the emulator with both networking and graphics:

fx run -N -G

Open a new terminal window and link the new tap0 to your network interface: sudo ifconfig tap0 inet6 fc00::/7 up

In that same new terminal start the update server:

fx serve -v

If it asks if you want to accept incoming network connections press Allow.

Press ⌥⇥ (alt-tab) to switch between different tabs. The first tab is used for logging, you can run commands in the other 3.

If you need to close and restart the emulator you can run it by using: fx run -Nu ./scripts/qemu-ifup-macos to make it load the tap0 interface automatically since it gets closed automatically when QEMU exits.

Once the interface has been setup you can run Fuchsia again by using fx run -N -u scripts/start-dhcp-server.sh to make sure that the server on your machine is able to launch packages. It will print [serve-updates] Ready to push packages! when ready. The process of starting the os might take longer than expected so don’t press enter before it is fully initialized or some parts might not work properly. [This is very important]

Remember that you can use dm shutdown to shut down fuchsia and close the emulator.

You can start it back up once you close it by again using fx run -N -u scripts/start-dhcp-server.sh.

Run a Fuchsia Application

We are now going to run a program that’s already included in the downloaded source that prints to the console a random message. The console application that we are going to run is called fortune. When you see the $ sign meaning the fuchsia has finished loading you can type fortune and press enter:

[00420.914] 04738:04948> pkgsvr: package activated fortune/0 (bfe4218c4ce7eab3cdc5453ede9c92093c0168bf874021f59ab553cdbb31072e)
Fortune favors the bold.

You’ve installed Fuchsia and run an application with it using an emulator!

As you’ve seen it is still early, but the foundations are there. Stay tuned for what’s next for Fuchsia.

Successive Runs

Once the setup is done and you’ve tested Fuchsia for a while you might shut down your computer and promptly forget how to turn it back on again. If you would like to run Fuchsia from a clean slate (let’s say you’ve rebooted your Mac) follow these steps:¹

• Open at least two Terminal windows inside the Fuchsia folder.

• Start a virtual environent with Python2 using:

  virtualenv -p /usr/bin/python2.7 venv && source venv/bin/activate

• Start your network interface (may not be needed):

  sudo ifconfig tap0 inet6 fc00::/7 up

• In the second terminal open the server:

  fx serve -v

• In the main terminal start Fuchsia:

  fx run -N -u scripts/start-dhcp-server.sh

Sources:

• Fuchsia Official Website
• Fuchsia Getting Started
• Fuchsia Source Code
• More Fuchsia Docs
• Fuchsia Packages
• Zircon
• Kernel Concepts
• Install on a device #1
• Install on a device #2
• Networking