Google is committed to advancing racial equity for Black communities. See how.

Declaring components

Every component has a declaration that describes the component's attributes and capabilities. For components that are distributed in packages, the declaration is expressed using a component manifest file and loaded with the help of a component resolver.

component manifest formats

You declare components using component manifest language (CML) files. At build time, the Component Manifest Compiler (cmc) tool validates and compiles the manifest source into a binary format (.cm) and stores it in the component's package. At runtime, component resolvers load the manifest into a ComponentDecl FIDL structure for Component Manager .

Component manifests

CML files are JSON5 files that end with a .cml extension. Below is an example CML manifest file for a simple component running an ELF binary that prints a "Hello, World" message to the system log:

{
    // Information about the program to run.
    program: {
        // Use the built-in ELF runner.
        runner: "elf",
        // The binary to run for this component.
        binary: "bin/hello",
        // Program arguments
        args: [
            "Hello",
            "World!",
        ],
    },

    // Capabilities used by this component.
    use: [
        { protocol: "fuchsia.logger.LogSink" },
    ],
}

This file declares two main sections of information about the component:

  • program: Describes the executable information such as the binary file, program arguments, and the associated runtime. In this example, a binary written in C++ or Rust is compiled as an ELF executable and uses the built-in ELF runner.
  • use: Declares the capabilities this component requires to run. In this example, the fuchsia.logger.LogSink protocol enables the component to write messages to the system log (syslog).

Manifest shards

Some collections of capabilities represent use case requirements that are common to many components in the system, such as logging. To simplify including these capabilities in your components, the framework abstracts them into manifest shards that can be included in your CML source file.

Below is an equivalent CML to the previous example. In this case, the necessary logging capabilities are provided by including diagnostics/syslog/client.shard.cml instead of declaring fuchsia.logger.LogSink explicitly:

{
    include: [ "syslog/client.shard.cml" ],

    // Information about the program to run.
    program: {
        // Use the built-in ELF runner.
        runner: "elf",
        // The binary to run for this component.
        binary: "bin/hello-world",
        // Program arguments
        args: [
            "Hello",
            "World!",
        ],
    },
}

Building components

The Fuchsia build system provides templates as GN imports in //build/components.gni to build and package software into Fuchsia components. Below is an example of a BUILD.gn file for a simple C++ component:


import("//build/components.gni")

executable("bin") {
  sources = [ "main.cc" ]
}

resource("my_file") {
  sources = [ "my_file.txt" ]
  outputs = [ "data/{{source_file_part}}" ]
}

fuchsia_component("hello-world-component") {
  component_name = "hello-world"
  deps = [
    ":bin",
    ":my_file",
  ]
  manifest = "meta/hello-world.cml"
}

fuchsia_package("hello-world") {
  package-name = "hello-world"
  deps = [
    ":hello-world-component",
  ]
}

This file contains the following main elements:

  • executable(): Compiles the source code into a binary. This target varies depending on the programming language. For example, an executable target can be used for C++, rustc_binary for Rust, go_binary for Golang.
  • resource(): Optional named collection of data files to copy as resources into another GN target. These files are accessible to the binary inside the component's namespace.
  • fuchsia_component(): Collects the binary, component manifest, and additional resources together into a single target. This target compiles the manifest source into a component declaration using cmc.
  • fuchsia_package(): Unit of distribution for components. Allows one or more components to be hosted in a package repository and included in the target device's package sets. This target generates the package metadata and builds the Fuchsia Archive (.far) file.

Packages can contain multiple components, listed as deps in the fuchsia_package() template. You can simplify the build file for packages containing only one component using the fuchsia_package_with_single_component() template.

The following simplified BUILD.gn example is equivalent to to the previous example:


import("//build/components.gni")

executable("bin") {
  sources = [ "main.cc" ]
}

resource("my_file") {
  sources = [ "my_file.txt" ]
  outputs = [ "data/{{source_file_part}}" ]
}

fuchsia_package_with_single_component("hello-world") {
  manifest = "meta/hello-world.cml"
  deps = [
    ":bin",
    ":my_file",
  ]
}

Exercise: Create a new component

In this exercise, you'll build and run a basic component that reads the program arguments and echoes a greeting out the system log.

To begin, create a project scaffold for a new Rust component called echo-args under the //vendor/fuchsia-codelab directory:

fx create component --path vendor/fuchsia-codelab/echo-args --lang rust

This creates a project directory structure with a basic component template:

echo-args
  |- BUILD.gn
  |- meta
  |   |- echo_args.cml
  |
  |- src
      |- main.rs
  • BUILD.gn: GN build targets for the executable binaries, component, and package.
  • meta/echo_args.cml: Manifest declaring the component's executable and required capabilities.
  • src/main.rs: Source code for the Rust executable binary and unit tests.

Add program arguments

Open the echo_args.cml component manifest file in your editor and locate the program block. This defines the attributes of the component's executable. Add an args array to supply the list of names to greet:

echo-args/meta/echo_args.cml:

{
    include: [
        "inspect/client.shard.cml",
        "syslog/client.shard.cml",
    ],

    // Information about the program to run.
    program: {
        // Use the built-in ELF runner.
        runner: "elf",

        // The binary to run for this component.
        binary: "bin/echo_example",

        // Program arguments
        args: [
            "Alice",
            "Bob",
        ],

        // Program environment variables
        environ: [ "FAVORITE_ANIMAL=Spot" ],
    },

    // ...
}

Log the arguments

Open the main.rs source file and replace the import statements with the following code:

echo-args/src/main.rs:

use tracing::info;

Replace the main() function with the following code:

echo-args/src/main.rs:

#[fuchsia::component(logging = true)]
async fn main() -> Result<(), anyhow::Error> {
    // Read program arguments, and strip off binary name
    let mut args: Vec<String> = std::env::args().collect();
    args.remove(0);

    // Include environment variables
    let animal = std::env::var("FAVORITE_ANIMAL").unwrap();
    args.push(animal);

    // Print a greeting to syslog
    info!("Hello, {}!", greeting(&args));

    Ok(())
}

This code reads the program arguments and passes them to a function called greeting() to generate a response for the syslog entry.

Add the following code to implement the greeting() function:

echo-args/src/main.rs:

// Return a proper greeting for the list
fn greeting(names: &Vec<String>) -> String {
    // Join the list of names based on length
    match names.len() {
        0 => String::from("Nobody"),
        1 => names.join(""),
        2 => names.join(" and "),
        _ => names.join(", "),
    }
}

This function creates a simple string from the list of provided arguments based on the length of the list.

Add to the build configuration

Add your new component to the build configuration:

fx set workstation.qemu-x64 --with //vendor/fuchsia-codelab/echo-args

Run fx build and verify that the build completes successfully:

fx build

In the next section, you'll integrate this component into the build and test the output in the system log.