Download the Fuchsia source code

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.

To install or update these packages, run the following command:

sudo apt install curl file git unzip

(Optional) If you want to run the Fuchsia emulator (FEMU), consider completing the following additional steps before proceeding to the next section:

Enable KVM acceleration
Configure emulator networking

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.

To perform a preflight check, 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

The Fuchsia bootstrap script creates a directory named fuchsia and downloads the Fuchsia source code.

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: Depending on your network speed, downloading the Fuchsia source code (about 2 GB) can take a while.
```
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

To configure the recommended Fuchsia environment variables in your shell profile, do the following:

Use a text editor to open your ~/.bash_profile file (in the example below, we use the Nano 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 checkout 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
```
- 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.
- 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.)
Save the file and exit the text editor.
Update environment variables:
```
source ~/.bash_profile
```

To verify your environment setup, do the following:

Go to your fuchsia directory, for example:
```
cd ~/fuchsia
```
Verify that you can run the following commands without errors:
```
jiri help
```
```
fx help
```

5. Configure firewall rules (Optional)

To allow Fuchsia-specific traffic on the host machine, run the following command:

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.

Appendix

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
Add a symlink to your binary directory

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.

Enable KVM acceleration

(Linux only) Most Linux machines support VM acceleration through KVM, which greatly improves the performance and usability of the emulator.

If KVM is available on your machine, add yourself to the kvm group:

sudo usermod -a -G kvm ${USER}

For this change to take effect, you may need to log out and log back in.

Configure emulator networking

(Linux only) To allow the Fuchsia emulator (FEMU) to access the network, you can configure an IPv6 network using TUN/TAP.

To enable networking using tap networking, do the following:

Set up tuntap:

sudo ip tuntap add dev qemu mode tap user $USER

Enable the network for qemu:
```
sudo ip link set qemu up
```