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.
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:
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 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
You can install git through brew. Run
brew install git to install git.
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.
This will add both
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:
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
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.
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.
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.
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:1
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
- Fuchsia Official Website
- Fuchsia Getting Started
- Fuchsia Source Code
- More Fuchsia Docs
- Fuchsia Packages
- Kernel Concepts
- Install on a device #1
- Install on a device #2
We are assuming that you followed the rest of the article and that everything before this section has been followed and you have a functioning Fuchsia installation on your system.↩