This guide shows you how to build Fuchsia to include an example package from
Fuchsia's source [`//examples`](https://cs.opensource.google/fuchsia/fuchsia/+/main:/examples/) directory and run a component on
your Fuchsia target.

> [!NOTE]
> **Note:** You can find the source code for the "Hello, World" example at [`//examples/hello_world`](https://cs.opensource.google/fuchsia/fuchsia/+/main:/examples/hello_world).

## Prerequisites

Before you can run an example component, you must:

- [Set up the Fuchsia development environment](https://fuchsia.dev/docs/get-started/get_fuchsia_source)

## Exploring the example

This example component prints `Hello, world!` to the system log. The example has
three main elements:

- An [executable binary](https://fuchsia.dev/fuchsia-src/development/run/run-examples#executable-program) written in a supported language.
- A [component manifest](https://fuchsia.dev/fuchsia-src/development/run/run-examples#component-manifest) (`.cml`) file to declare the component and its capabilities.
- A [`BUILD.gn`](https://fuchsia.dev/fuchsia-src/development/run/run-examples#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](https://fuchsia.dev/docs/concepts/components/v2/elf_runner).

### C++

    #include <iostream>

    int main() {
      std::cout << "Hello, World!\n";
      return 0;
    }

### Rust

    fn main() {
        println!("{}, world!", greeting());
        eprintln!("{}, world!", greeting());
    }

    fn greeting() -> String {
        return String::from("Hello");
    }

### Component manifest

A


[](https://fuchsia.dev/docs/glossary#component-manifest)


describes
how to run a Fuchsia program as a


[](https://fuchsia.dev/docs/glossary#component)


.
This includes declaring program binary, runtime information, and any capabilities
the component requires to execute, such as logging support.

### C++

    // Copyright 2022 The Fuchsia Authors. All rights reserved.
    // Use of this source code is governed by a BSD-style license that can be
    // found in the LICENSE file.
    {
        // Enable system logging capabilities
        include: [ "syslog/client.shard.cml" ],

        // Information about the program to run
        program: {
            // Use the built-in ELF runner for the executable
            runner: "elf",
            binary: "bin/hello_world_cpp",

            // Enable stdout logging
            forward_stderr_to: "log",
            forward_stdout_to: "log",
        },
    }

### Rust

    // Copyright 2022 The Fuchsia Authors. All rights reserved.
    // Use of this source code is governed by a BSD-style license that can be
    // found in the LICENSE file.
    {
        // Enable system logging capabilities
        include: [ "syslog/client.shard.cml" ],

        // Information about the program to run
        program: {
            // Use the built-in ELF runner for the executable
            runner: "elf",
            binary: "bin/hello_world_rust",

            // Enable stdout logging
            forward_stderr_to: "log",
            forward_stdout_to: "log",
        },
    }

For more details on component manifests and their declaration syntax,
see [component manifests](https://fuchsia.dev/docs/concepts/components/v2/component_manifests).

### BUILD.gn

Fuchsia uses the Generate Ninja (GN) meta-build system to generate inputs for
[Ninja](https://ninja-build.org/), which executes the actual build.
The `BUILD.gn` file declares the build targets for a `fuchsia_component()` and
`fuchsia_package()`.

> [!NOTE]
> **Note:** If you aren't familiar with GN, see [Introduction to GN](https://fuchsia.dev/docs/development/build/gn_concepts/intro).

### C++

    executable("bin") {
      output_name = "hello_world_cpp"
      sources = [ "hello_world.cc" ]
    }

    fuchsia_component("hello-world-cpp-component") {
      deps = [ ":bin" ]

      # Defines the name given to the manifest when included in a fuchsia package.
      # In this case: "hello-world-cpp.cm"
      component_name = "hello-world-cpp"
      manifest = "meta/hello_world_cpp.cml"
    }

    fuchsia_package("hello-world-cpp") {
      deps = [
        # component-url:
        # fuchsia-pkg://fuchsia.com/hello-world-cpp#meta/hello-world-cpp.cm
        ":hello-world-cpp-component",
      ]
    }

### Rust

    rustc_binary("bin") {
      name = "hello_world_rust"

      # Generates the "bin_test" build target
      with_unit_tests = true
      edition = "2024"

      deps = []
      test_deps = [ "//src/lib/fuchsia" ]

      sources = [ "src/main.rs" ]
    }

    fuchsia_component("hello-world-rust-component") {
      deps = [ ":bin" ]

      # Defines the name given to the manifest when included in a fuchsia package.
      # In this case: "hello-world-rust.cm"
      component_name = "hello-world-rust"
      manifest = "meta/hello_world_rust.cml"
    }

    fuchsia_package("hello-world-rust") {
      deps = [
        # component-url:
        # fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
        ":hello-world-rust-component",
      ]
    }

To learn more about how Fuchsia uses GN to define components and packages,
see: [Building components](https://fuchsia.dev/docs/development/components/build).

## Include the example package in your Fuchsia image

> [!NOTE]
> **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:

    fx set core.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](https://fuchsia.dev/docs/development/build/fx#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](https://fuchsia.dev/docs/development/build/software_assembly/build_configuration#universe).

### 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


[](https://fuchsia.dev/docs/glossary#fuchsia-pkg-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](https://fuchsia.dev/fuchsia-src/development/run/run-examples#include-the-example) and rebuild your Fuchsia image to
include the appropriate packages.
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/run/run-examples.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/run/run-examples.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/run/run-examples.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/run/run-examples.md "Edit the source code of this page")