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.
Open the examples/hello_world/BUILD.gn file.
If you aren't familiar with GN, take a look at the introductory presentation (slides 5-16 cover the core concepts, and slides 17-21 describe debugging commands) 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 = [ ":tests", "cpp", "rust", ] }
Note: You can look at the build/package.gni file to learn more about how Fuchsia packages are defined by GN.
This example outputs Hello, world! and is written in both C++ and Rust. Each language-dependent directory has its own BUILD.gn 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:
Make sure fx serve is running in a terminal window. If it's not running, start it:
fx serve
In another terminal, run:
fx shell run fuchsia-pkg://fuchsia.com/hello_world_cpp#meta/hello_world_cpp.cmx
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.
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.
Make sure fx serve is running in a terminal window. If it's not running, start it:
fx serve
In another terminal, run:
fx shell run fuchsia-pkg://fuchsia.com/hello_world_cpp#meta/hello_world_cpp.cmx
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://fuchsia.com/hello_world_cpp#meta/hello_world_cpp.cmx: 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
fuchsia-pkg://fuchsia.com/hello_world_cpp#meta/hello_world_cpp.cmx fuchsia-pkg://fuchsia.com/hello_world_rust#meta/hello_world_rust.cmx 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.
fx shell locate --list cmx
Find multiple test components.
fx shell locate --list test