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:

   fx serve
   

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-cpp#meta/hello-world-cpp.cm
     

   • {Rust}

     ffx component run /core/ffx-laboratory:hello-world-rust fuchsia-pkg://fuchsia.com/hello-world-rust#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 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, repeat these steps and rebuild your Fuchsia image to include the appropriate packages.