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:
- Install prerequisite packages.
- Perform a preflight check.
- Download the Fuchsia source code.
- Set up environment variables.
- Configure firewall rules (Optional).
1. Install prerequisite packages
Fuchsia requires curl
, file
, unzip
, and git
to be up to date. The version
of git
needs to be 2.31 or higher.
Install (or update) the following packages:
sudo apt install curl file git unzip
2. Perform a preflight check
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.
Run the following command:
curl -sO https://storage.googleapis.com/fuchsia-ffx/ffx-linux-x64 && chmod +x ffx-linux-x64 && ./ffx-linux-x64 platform preflight
3. Download the Fuchsia source code
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:
cd $HOME
Run the bootstrap script:
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.If you have a slower internet connection and run into timeouts, you may wish to download the bootstrap script directly and increase the values of
-fetch-packages-timeout
and-hook-timeout
. These timeouts are in minutes, and indicate a 2 hour timeout for package downloads. (The-hook-timeout
value is multiplied by 5 when downloading CIPD packages.)
4. Set up environment variables
Fuchsia recommends that you update your shell profile to include the following actions:
Add the
.jiri_root/bin
directory to yourPATH
.The
.jiri_root/bin
directory in the Fuchsia source contains thejiri
andfx
tools that are essential to Fuchsia workflows. Fuchsia uses thejiri
tool to manage repositories in the Fuchsia project, and thefx
tool helps configure, build, run, and debug Fuchsia. The Fuchsia toolchain requires thatjiri
is available in yourPATH
.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 theFUCHSIA_DIR
environment variable and provides thefd
command for navigating directories with auto-completion. (For more information, see comments infx-env.sh
.)
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 text editor):nano ~/.bash_profile
Add the following lines to your
~/.bash_profile
file: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
5. Configure firewall rules (Optional)
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
.)
Next steps
To build your first Fuchsia system image, see Configure and build Fuchsia.
Appendices
Authentication error
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:
- Follow the onscreen directions to get passwords for the specified repositories.
- Delete the offending cookies from the
.gitcookies
file.
Work on Fuchsia without updating your PATH
The following sections provide alternative approaches to the Set up environment variables section:
Copy the tool to your binary directory
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:
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.
Add a symlink to your binary directory
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:
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
.