Run the examples

While exploring the source code, you may have noticed the examples directory. This guide will show you how to build Fuchsia to include some examples and then run them on the device.

Explore the hello_world example

Go ahead and open the examples/hello_world/ file.

If you aren't familiar with GN, take a look at the introductory presentation or docs. In short, GN is a meta build system. Its output files serve as inputs to Ninja, the actual build system.

In this file, the hello_world target is a group containing other dependencies, notably cpp and rust. Using this target will build both of them.

group("hello_world") {
  testonly = true
  deps = [

Note: You can look at the build/package.gni file to learn more about how Fuchsia packages are defined by GN.

This sample outputs Hello, world! and is written in both C++ and Rust. Each language-dependent directory has its own file that defines a package for the specific example, as well as a meta subdirectory with .cmx files.

The .cmx file is known as a component manifest and describes how to run the application on Fuchsia as a component. This is the proper way to create a Fuchsia package.

You run a Fuchsia component by referencing its Fuchsia package URI. To run one of the examples:

  1. Make sure fx serve is running in a terminal window. If it's not running, start it:

    fx serve
  2. In another shell tab, run:

    fx shell run fuchsia-pkg://

This should fail with a message stating the package was not found.

Note: If it succeeds and prints “Hello World!”, then your current fx target includes these examples already. You may need to modify your target and repave the device, then return to this page to continue.

Set the build to include examples

You can include the examples in the build, but you need to determine where they will be included:

  • Base: Packages that are included in paving images produced by the build. They are included in over-the-air updates and are always updated as a single unit.

  • Cache: Packages that are included in paving images, but are not included in over-the-air system updates. These packages can be updated at any time that updates are available.

  • Universe: Packages that are additional optional packages that can be fetched and run on-demand, but are not pre-baked into any paving images.

(For more information, see fx workflows.)

To include this package in Universe so it can be fetched on-demand, use the --with flag when setting the product and board:

fx set ... --with //examples/hello_world
fx build

You now have a build that includes the examples.

Run the examples

  1. Make sure fx serve is running in a terminal window. If it's not running, start it:

    fx serve
  2. In another shell tab, run:

    fx shell run fuchsia-pkg://

You should see the following output:

Hello, World!

Important: If fx serve is not running, you should get an error from the device (for example, fuchsia-pkg:// not found).

The run command can expand a string to a URI if the string only matches one component in your product configuration:

fx shell run hello_world_cpp

If there are multiple matches, the command will list them for you to choose from:

fx shell run hello
Error: "hello" matched multiple components.

You can explore what components are in your product configuration using the locate command.

  • Find your favorite component.

    fx shell locate hello_world_cpp
  • Find all runnable components in your universe.

    fx shell locate --list cmx
  • Find multiple test components.

    fx shell locate --list test