Skip to content

Latest commit

 

History

History
199 lines (135 loc) · 6.31 KB

run-examples.md

File metadata and controls

199 lines (135 loc) · 6.31 KB
Raw

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:

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

fx set product.board --with //examples/hello_world

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

Run the example component {#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 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

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