Run an example component

This guide shows you how to build Fuchsia to include an example package from Fuchsia's source //examples directory and run that component on your Fuchsia device.

Exploring the example Fuchsia package

Open the examples/hello_world/BUILD.gn file.

This example, written in both C++ and Rust, prints Hello, world!. Each language-dependent directory has the following:

A BUILD.gn file that defines its Fuchsia package.
A meta subdirectory with component manifests (.cmx) files.

BUILD.gn

Generate Ninja (GN) is a meta build system. Output files from GN serve as inputs to Ninja, the actual build system. If you aren't familiar with GN, see Introduction to GN.

In the examples/hello_world/BUILD.gn file, the hello_world target is a group containing other dependencies, notably cpp and rust. Therefore, this target builds both of them:

group("hello_world") {
  testonly = true
  deps = [
    ":tests",
    "cpp",
    "rust",
  ]
}

To learn more about how GN defines Fuchsia packages, see the build/package.gni file.

Component manifest

A .cmx file, known as a component manifest, describes how to run an application on Fuchsia as a component. In other words, a component manifest creates a Fuchsia package.

Fuchsia package

To include a package in your Fuchsia image, you have the following options:

Base: Packages that are produced by build and included in paving images. These packages 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 when updates are available.
Universe: Packages that are not included in paving image. These optional packages are fetched and run on-demand.

Include the example package in your Fuchsia image

To include the example package in Universe so that it can be fetched on-demand, use the --with flag when setting your product and board environment and building Fuchsia:

fx set product.board --with //examples/hello_world

For a Fuchsia emulator with the minimum build configuration, the command is:

fx set core.qemu-x64 --with //examples/hello_world

In this example, core is a product with a minimal feature set, which includes common network capabilities, and x64 refers to the x64 architecture.

For a Fuchsia device with the minimum build configuration, the command is:

fx set core.x64 --with //examples/hello_world

See Configure a build for more options.

Once you have set your build configuration, build Fuchsia with the following command:

fx build

You now have a build that includes the example package in Universe.

Run the example component

To run a Fuchsia component, use its Fuchsia package URL as an argument to the fx shell run command:

Open a terminal and run fx serve-updates:
```
fx serve-updates
```

Open another terminal and run the example component:

fx shell run fuchsia-pkg://fuchsia.com/hello-world-cpp#meta/hello-world-cpp.cmx

This command prints the following output:

Hello, World!

If fx serve-updates is not running, the command prints an error message from the device or emulator.

If fx serve-updates is running, but the package is not found, then try going through these steps again, rebuilding your Fuchsia image to include this package and repaving it to the device.

Explore your product configuration

You can explore the contents of your product configuration using the list-packages command.

List all:

fx list-packages

There may be many entries, so add the name to find the one you're looking for:

fx list-packages hello-world
hello-world-cpp-unittests
hello-world-dart
hello-world-rust-tests
hello-world-cpp
hello-world-rust