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
:fx serve
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
is not running, the command prints an error message from
the device or emulator.
If fx serve
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.
Run the example component using a simple string
The fx shell run
command can match a string to a package URL
if the string is only mapped to one component
in your product configuration. For example:
$ fx shell run hello_world_cpp.cmx
If multiple matches exist, the command prints the list of matches:
$ fx shell run hello_world
fuchsia-pkg://fuchsia.com/hello_world_cpp_tests#meta/hello_world_cpp_unittests.cmx
fuchsia-pkg://fuchsia.com/hello_world_cpp#meta/hello_world_cpp.cmx
Error: "hello_world" matched multiple components.
Explore the components in your product configuration
You can explore what components are in your product configuration using the
locate
command.
Find your favorite component:
fx shell locate hello_world_cpp.cmx
Find all runnable components:
fx shell locate --list cmx
Find multiple test components:
fx shell locate --list test