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 a component on
your Fuchsia target.
Note: You can find the source code for the "Hello, World" example at
//examples/hello_world.
Prerequisites
Before you can run an example component, you must:
Exploring the example {#exploring-the-example}
This example component prints Hello, world! to the system log. The example has
three main elements:
- An executable binary written in a supported language.
- A component manifest (
.cml) file to declare the component and its capabilities. - A
BUILD.gnfile to define the component build target and include it in a Fuchsia package.
Executable program {#executable-program}
Fuchsia components can execute programs written in any language with a supported runtime. The most common runtime used for C++ and Rust programs is the ELF runner.
- {C++}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/hello_world/cpp/hello_world.cc" region_tag="main" adjust_indentation="auto" %}
- {Rust}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/hello_world/rust/src/main.rs" region_tag="main" adjust_indentation="auto" %}
Component manifest {#component-manifest}
A component manifest describes how to run a Fuchsia program as a component. This includes declaring program binary, runtime information, and any capabilities the component requires to execute, such as logging support.
- {C++}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/hello_world/cpp/meta/hello_world_cpp.cml" adjust_indentation="auto" %}
- {Rust}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/hello_world/rust/meta/hello_world_rust.cml" adjust_indentation="auto" %}
For more details on component manifests and their declaration syntax, see component manifests.
BUILD.gn {#build-gn}
Fuchsia uses the Generate Ninja (GN) meta-build system to generate inputs for
Ninja{:.external}, which executes the actual build.
The BUILD.gn file declares the build targets for a fuchsia_component() and
fuchsia_package().
Note: If you aren't familiar with GN, see Introduction to GN.
- {C++}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/hello_world/cpp/BUILD.gn" region_tag="cpp_bin" adjust_indentation="auto" %}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/hello_world/cpp/BUILD.gn" region_tag="fuchsia_component" adjust_indentation="auto" %}
- {Rust}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/hello_world/rust/BUILD.gn" region_tag="rustc_tests" adjust_indentation="auto" %}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/hello_world/rust/BUILD.gn" region_tag="fuchsia_component" adjust_indentation="auto" %}
To learn more about how Fuchsia uses GN to define components and packages, see: Building components.
Include the example package in your Fuchsia image {#include-the-example}
Note: For new build configurations, these commands can take up to 90 minutes.
To include the example package in your build configuration, use the --with flag
when setting your product and board environment:
fx set product.board --with //examples/hello_world
For a Fuchsia emulator with the minimum build configuration, the command is:
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:
See Configure a build for more options.
Once you have set your build configuration, build Fuchsia with the following command:
You now have a build that includes the example package that can be fetched and launched on demand.
Explore your product configuration {#explore-your-product-configuration}
You can explore the contents of your product configuration using the
list-packages command.
List all:
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-rust-tests
hello-world-cpp
hello-world-rust
Run the example component {#run-the-example-component}
To run a Fuchsia component, use its
Fuchsia package URL as an argument
to the run command:
-
Open a terminal and run
fx serve-updates: -
Open another terminal and run the example component:
- {C++}
- {Rust}
-
Open another terminal and view the system log:
The component prints the following output to the log:
none {:.devsite-disable-click-to-copy} [ffx-laboratory:hello-world] INFO: Hello, World!
Troubleshooting {#troubleshooting}
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,
repeat these steps and rebuild your Fuchsia image to
include the appropriate packages.