This guide provides instructions on how to set up the Fuchsia development environment on your machine for building Fuchsia from source.
The steps are:
Before you start, complete the following tasks:
We recommend you run ffx platform preflight
, which examines your machine and informs you of issues that may affect building Fuchsia from source or running the Fuchsia emulator.
{Linux}
curl -sO https://storage.googleapis.com/fuchsia-ffx/ffx-linux-x64 && chmod +x ffx-linux-x64 && ./ffx-linux-x64 platform preflight
{macOS}
curl -sO https://storage.googleapis.com/fuchsia-ffx/ffx-macos-x64 && chmod +x ffx-macos-x64 && ./ffx-macos-x64 platform preflight
The Fuchsia project requires curl
, unzip
, and git
to be up to date.
Note: Fuchsia requires the version of Git to be 2.28 or higher.
{Linux}
Install (or update) the following packages:
sudo apt-get install curl git unzip
{macOS}
Install the Xcode command line tools:
Note: Skip this step if ffx platform preflight
discovers that Xcode tools are installed on your machine.
xcode-select --install
Fuchsia's bootstrap script creates a fuchsia
directory and downloads the content of the Fuchsia source repository to this new directory.
Note: Downloading Fuchsia source requires ~2 GiB of space on your machine. In addition, you will need another 80-90 GiB of space when you build Fuchsia, depending on your build configuration.
To download the Fuchsia source, do the following:
Select a directory for downloading the Fuchsia source code, for example:
Note: While you can set up Fuchsia in any directory, this guide uses the home directory.
cd ~
Run the bootstrap script:
curl -s "https://fuchsia.googlesource.com/fuchsia/+/HEAD/scripts/bootstrap?format=TEXT" | base64 --decode | bash
This script creates a fuchsia
directory to download the source code. Downloading Fuchsia source can take up to 60 minutes.
If you see the Invalid authentication credentials
error during the bootstrapping process, see Authentication error for help.
Fuchsia recommends that you update your shell profile to include the following actions:
Add the .jiri_root/bin
directory to your PATH
.
The .jiri_root/bin
directory in the Fuchsia source contains the jiri{:.external} and fx tools are essential to Fuchsia workflows. Fuchsia uses the jiri
tool to manage repositories in the Fuchsia project. The fx
tool helps configure, build, run, and debug Fuchsia. The Fuchsia toolchain requires jiri
to be available in your PATH
.
Source the scripts/fx-env.sh
file.
Although it's not required, sourcing the fx-env.sh script enables useful shell functions in your terminal. For instance, it creates a FUCHSIA_DIR
environment variable and provides the fd
command for navigating directories with auto-completion (see comments in fx-env.sh
for more information).
To update your shell profile with the changes above, do the following:
Note: If you don't wish to update your environment variables, see Work on Fuchsia without updating your PATH.
Use a text editor to open your ~/.bash_profile
file, for example:
Note: This guide uses a bash
terminal as an example. If you are using zsh
, replace ~/.bash_profile
with ~/.zprofile
in the following steps:
nano ~/.bash_profile
Add the following lines to your ~/.bash_profile
file:
Note: If your Fuchsia source code is not located in the ~/fuchsia
directory, replace ~/fuchsia
with your Fuchsia directory.
export PATH=~/fuchsia/.jiri_root/bin:$PATH source ~/fuchsia/scripts/fx-env.sh
Save the file and exit the text editor.
To update your environment variables, run the following command:
source ~/.bash_profile
Verify that you can run the following commands inside your fuchsia
directory without error:
jiri help
fx help
See Configure and build Fuchsia in the Getting started guide for the next steps.
If you see the Invalid authentication credentials
error during the bootstrap process, your ~/.gitcookies
file may contain cookies from some repositories in googlesource.com
that the bootstrap script wants to check out anonymously.
To resolve this error, do one of the following:
.gitcookies
file.The following sections provide alternative approaches to the Update your shell script section:
If you don't wish to update your environment variables, but you want jiri
to work in any directory, copy the jiri
tool to your ~/bin
directory, for example:
Note: If your Fuchsia source code is not located in the ~/fuchsia
directory, replace ~/fuchsia
with your Fuchsia directory.
cp ~/fuchsia/.jiri_root/bin/jiri ~/bin
However, you must have write access to the ~/bin
directory without sudo
. If you don't, jiri
cannot keep itself up-to-date.
Similarly, if you want to use the fx
tool without updating your environment variables, provide the fx
tool's symlink in your ~/bin
directory, for example:
Note: If your Fuchsia source code is not located in the ~/fuchsia
directory, replace ~/fuchsia
with your Fuchsia directory.
ln -s ~/fuchsia/scripts/fx ~/bin
Alternatively, run the fx
tool directly using its path, for example:
./scripts/fx help
In either case, you need jiri
in your PATH
.