This guide provides step-by-step instructions on setting up the Fuchsia SDK development environment on your host machine using a terminal or Visual Studio Code (VS Code). Then the guide walks through the basic workflows of building, running, debugging, and testing Fuchsia components using the Fuchsia SDK.
Which development environment are you using for this guide?
Found an issue? Please let us know.
Prerequisites
This guide requires that your host machine meets the following criteria:
- An x64-based machine running Linux or macOS.
- Has at least 15 GB of storage space.
- Supports virtualization for running a QEMU-based emulator.
- IPv6 is enabled.
- Git is installed.
Clone the SDK samples repository
Start the emulator
Build and run the sample component
View symbolized logs
Debug the sample component
Inspect components
Run tests
Congratulations! You're now all set with the Fuchsia SDK!
Next steps
Learn more about the Fuchsia platform and tools in Fuchsia SDK Fundamentals.
Appendices
Update the environment to the latest SDK
To update your development environment to use the latest version of the Fuchsia SDK, do the following:
In a terminal, go to your
fuchsia-getting-started
directory:cd $HOME/fuchsia-getting-started
Update the project repository and its submodules to the latest version:
git pull --rebase --recurse-submodules
Update the Fuchsia SDK toolchain and dependencies:
tools/bazel build @fuchsia_sdk//:fuchsia_toolchain_sdk
Check the new version of the Fuchsia SDK:
tools/ffx sdk version
Verify that the SDK version is now the latest release version.
Clean up the environment
If you run into a problem while following this guide and decide to start over from the beginning, consider running the commands below to clean up your development environment (that is, to clean up directories, build artifacts, downloaded files, symlinks, configuration settings, and more).
Remove the package repositories created in this guide:
tools/ffx repository remove workstation-packages
tools/ffx repository server stop
Remove all existing configurations and data of ffx
:
Linux
tools/ffx daemon stop
rm -rf $HOME/.local/share/Fuchsia/ffx
macOS
tools/ffx daemon stop
rm -rf $HOME/Library/Caches/Fuchsia/ffx
rm -rf $HOME/Library/Fuchsia/ffx
rm -rf $HOME/Library/Preferences/Fuchsia/ffx
rm -rf $HOME/Library/Application\ Support/Fuchsia/ffx
When Bazel fails to build, try the commands below:
Linux
tools/bazel clean --expunge
tools/bazel shutdown && rm -rf $HOME/.cache/bazel
macOS
tools/bazel clean --expunge
tools/bazel shutdown && rm -rf /private/var/tmp/bazel$USER
Remove the fuchsia-getting-started
directory and its artifacts:
rm -rf $HOME/fuchsia-getting-started
Other clean up commands:
killall ffx
killall pm
Update the firewall rules
When you launch the sample component (for instance, using the command
tools/bazel run
), you might run into an issue where the command hangs for a
long time and eventually fails with the following error:
Lifecycle protocol could not start the component instance: InstanceCannotResolve
In that case, you may need to update the firewall rules on your host machine.
If you’re using the ufw
firewall, run the following commands:
sudo ufw allow proto tcp from fe80::/10 to any port 8083 comment 'Fuchsia Package Server'
sudo ufw allow proto tcp from fc00::/7 to any port 8083 comment 'Fuchsia Package Server'
However, for other non-ufw
-based firewalls, you will need to ensure that port
8083 is available for the Fuchsia package server.
Check if your Linux machine supports KVM virtualization
To check if your Linux machine supports KVM hardware virtualization, run the following command:
lscpu
This command prints output similar to the following:
$ lscpu
Architecture: x86_64
CPU op-mode(s): 32-bit, 64-bit
Address sizes: 46 bits physical, 48 bits virtual
Byte Order: Little Endian
...
Virtualization features:
Virtualization: VT-x
Hypervisor vendor: KVM
Virtualization type: full
...
If you see the following field in the output, your machine supports KVM hardware virtualization:
Virtualization: VT-x
On the other hand, for machines that support AMD virtualization, you may see the following field in the output:
Virtualization: AMD-V
However, if your output does not have the Virtualization
field at all,
while the Hypervisor vendor
and Virtualization type
fields may still
be shown (see the example output below), your machine
does not support hardware virtualization.
$ lscpu
...
Virtualization features:
Hypervisor vendor: KVM
Virtualization type: full
...
Set up KVM virtualization on a Linux machine
To verify that KVM is configured correctly on your Linux machine,
run the following bash
shell script:
if [[ -w /dev/kvm ]] && grep '^flags' /proc/cpuinfo | grep -qE 'vmx|svm'; then echo 'KVM is working'; else echo 'KVM not working'; fi
Verify that this shell script prints the following output:
KVM is working
If the output is KVM is working
, KVM hardware virtualization is
enabled on your Linux machine.
However, if the output is KVM not working
, do the following to
enable KVM hardware virtualization:
Add yourself to the
kvm
group on your Linux machine:sudo usermod -a -G kvm ${USER}
Reboot the machine.
Run the
bash
shell script above again.Verify that the output now prints
KVM is working
.