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:

• Set up the Fuchsia development environment

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.gn file to define the component build target and include it in a Fuchsia package.

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

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

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

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.

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
hello-world-cpp-unittests
hello-world-rust-tests

Run the example component

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

1. Open a terminal and run fx serve-updates:

   fx serve-updates
   

2. Open another terminal and run the example component:

   • {C++}

     ffx component run /core/ffx-laboratory:hello-world-cpp fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world-cpp.cm
     

   • {Rust}

     ffx component run /core/ffx-laboratory:hello-world-rust fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world-rust.cm
     

3. 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!
   

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.