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
.
Before you can run an example component, you must:
This example component prints Hello, world!
to the system log. The example has three main elements:
.cml
) file to declare the component and its capabilities.BUILD.gn
file to define the component build target and include it in a Fuchsia package.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" %}
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.
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.
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:
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 that can be fetched and launched on demand.
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-rust-tests hello-world-cpp hello-world-rust
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
:
fx serve-updates
Open another terminal and run the example component:
{C++}
ffx component run fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world-cpp.cm
{Rust}
ffx component run fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world-rust.cm
Open another terminal and view the system log:
ffx log --filter hello-world
The component prints the following output to the log:
[ffx-laboratory:hello-world] INFO: 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, repeat these steps and rebuild your Fuchsia image to include the appropriate packages.