Get started with the Fuchsia SDK

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.