This guide provides instructions on how to download the Fuchsia source code and set up the Fuchsia development environment on your machine.
The steps are:
Fuchsia provides a preflight check tool (ffx platform preflight) that examines your machine and informs you of any issues that may affect building Fuchsia from source on the machine.
Note: The preflight tool only works for the x64 architecture. Fuchsia is currently not guaranteed to build successfully on other host architectures, such as Windows and ARM64.
Run the following command:
{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
Fuchsia requires curl, file, unzip, and git to be up to date. The version of git needs to be 2.28 or higher.
{Linux}
Install (or update) the following packages:
sudo apt install curl file git unzip
{macOS}
Install the Xcode command line tools:
Note: Skip this step if ffx platform preflight shows that Xcode tools are already installed on your machine.
xcode-select --install
Fuchsia provides a bootstrap script that creates a directory named fuchsia and downloads the Fuchsia source code in that directory.
Downloading the Fuchsia source code requires about 2 GB of space on your machine. Depending on your build configuration, you need another 80 to 90 GB of space later when you build Fuchsia. Additionally, the download process uses a substantial amount of memory. It is advisible to close non-crucial processes during this time.
To download the Fuchsia source, do the following:
Select a directory for downloading the Fuchsia source code, for example:
Note: You can set up Fuchsia in any directory. This guide selects the $HOME directory as an example.
cd $HOME
Run the bootstrap script:
Note: Downloading the Fuchsia source code can take up to 60 minutes.
curl -s "https://fuchsia.googlesource.com/fuchsia/+/HEAD/scripts/bootstrap?format=TEXT" | base64 --decode | bash
This script creates the fuchsia directory and downloads the source code.
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 and fx tools that are essential to Fuchsia workflows. Fuchsia uses the jiri tool to manage repositories in the Fuchsia project, and the fx tool helps configure, build, run, and debug Fuchsia. The Fuchsia toolchain requires that jiri is available in your PATH.
Source the scripts/fx-env.sh file.
Though it's not required, sourcing the fx-env.sh script enables a number of useful shell functions in your terminal. For instance, it creates the FUCHSIA_DIR environment variable and provides the fd command for navigating directories with auto-completion. (For more information, see comments in fx-env.sh.)
Note: If you don't wish to update your shell profile, see Work on Fuchsia without updating your PATH in Appendices instead.
To update your shell profile to configure Fuchsia's environment variables, do the following:
Use a text editor to open your ~/.bash_profile file (in the example below, we use the Nano{:.external} text editor):
Note: This guide uses a bash terminal as an example. If you're 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
Note: This step is not required for building or running Fuchsia. But it is recommended to ensure that Fuchsia's emulator instances run smoothly on Linux.
(Linux only) If you're planning on running Fuchsia on Linux, it is advised to run the following command to allow Fuchsia-specific traffic on the host machine:
fx setup-ufw
This script requires sudo (which asks for your password) to set the appropriate firewall rules. (For more information on this script, see setup-ufw.)
To build your first Fuchsia system image, see Configure and build Fuchsia.
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 Set up environment variables 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.