| # Run an example component | |
| This guide shows you how to build Fuchsia to include an example package from | |
| Fuchsia's source [`//examples`](/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`](/examples/hello_world). | |
| ## Prerequisites | |
| Before you can run an example component, you must: | |
| * [Set up the Fuchsia development environment](/docs/get-started/get_fuchsia_source.md) | |
| ## 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](#executable-program) written in a supported language. | |
| * A [component manifest](#component-manifest) (`.cml`) file to declare the | |
| component and its capabilities. | |
| * A [`BUILD.gn`](#build-gn) file 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](/docs/concepts/components/v2/elf_runner.md). | |
| * {C++} | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/hello_world/cpp/hello_world.cc" region_tag="main" adjust_indentation="auto" %} | |
| ``` | |
| * {Rust} | |
| ```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](/docs/glossary/README.md#component-manifest) describes | |
| how to run a Fuchsia program as a [component](/docs/glossary/README.md#component). | |
| This includes declaring program binary, runtime information, and any capabilities | |
| the component requires to execute, such as logging support. | |
| * {C++} | |
| ```json5 | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/hello_world/cpp/meta/hello_world_cpp.cml" adjust_indentation="auto" %} | |
| ``` | |
| * {Rust} | |
| ```json5 | |
| {% 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](/docs/concepts/components/v2/component_manifests.md). | |
| ### BUILD.gn {#build-gn} | |
| Fuchsia uses the Generate Ninja (GN) meta-build system to generate inputs for | |
| [Ninja](https://ninja-build.org/){:.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](/docs/development/build/gn_concepts/intro.md). | |
| * {C++} | |
| ```gn | |
| {% 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} | |
| ```gn | |
| {% 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](/docs/development/components/build.md). | |
| ## 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: | |
| <pre class="prettyprint"> | |
| <code class="devsite-terminal">fx set <var>product</var>.<var>board</var> --with //examples/hello_world</code> | |
| </pre> | |
| For a Fuchsia emulator with the minimum build configuration, the command is: | |
| ```posix-terminal | |
| 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: | |
| ```posix-terminal | |
| fx set core.x64 --with //examples/hello_world | |
| ``` | |
| See [Configure a build](/docs/development/build/fx.md#configure-a-build) for | |
| more options. | |
| Once you have set your build configuration, build Fuchsia with the following | |
| command: | |
| ```posix-terminal | |
| fx build | |
| ``` | |
| You now have a build that includes the example package that can be | |
| [fetched and launched on demand](/docs/development/build/software_assembly/build_configuration.md#universe). | |
| ### Explore your product configuration {#explore-your-product-configuration} | |
| You can explore the contents of your product configuration using the | |
| `list-packages` command. | |
| List all: | |
| ```posix-terminal | |
| fx list-packages | |
| ``` | |
| There may be many entries, so add the name to find the one you're looking for: | |
| ```posix-terminal | |
| fx list-packages hello-world | |
| hello-world | |
| hello-world-cpp-unittests | |
| hello-world-rust-tests | |
| ``` | |
| ## Run the example component {#run-the-example-component} | |
| To run a Fuchsia component, use its | |
| [Fuchsia package URL](/docs/glossary/README.md#fuchsia-pkg-url) as an argument | |
| to the `run` command: | |
| 1. Open a terminal and run `fx serve`: | |
| ```posix-terminal | |
| fx serve | |
| ``` | |
| 1. Open another terminal and run the example component: | |
| * {C++} | |
| ```posix-terminal | |
| ffx component run /core/ffx-laboratory:hello-world-cpp fuchsia-pkg://fuchsia.com/hello-world-cpp#meta/hello-world-cpp.cm | |
| ``` | |
| * {Rust} | |
| ```posix-terminal | |
| ffx component run /core/ffx-laboratory:hello-world-rust fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm | |
| ``` | |
| 1. Open another terminal and view the system log: | |
| ```posix-terminal | |
| ffx log --filter hello-world | |
| ``` | |
| 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` 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](#include-the-example) and rebuild your Fuchsia image to | |
| include the appropriate packages. |