声明组件

每个组件都有一个描述组件属性和功能的声明。对于在软件包中分发的组件，该声明使用组件清单文件来表示，并借助组件解析器加载。

展示如何使用“组件清单”声明组件的示意图。该清单由开发者工具编译，并在运行时解析到设备上。

您可以使用组件清单语言 (CML) 文件来声明组件。在构建时，组件清单编译器 (cmc) 工具会验证清单源代码并将其编译为二进制格式 (.cm)，并将其存储在组件的软件包中。 ComponentDecl

组件清单

CML 文件是以 .cml 扩展名结尾的 JSON5 文件。下面是一个运行 ELF 二进制文件的简单组件的示例 CML 清单文件，该二进制文件会将“Hello, World”消息输出到系统日志：

{
    // 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" },
    ],
}

此文件声明了关于该组件的两个主要信息部分：

  • program：描述可执行文件信息，例如二进制文件、程序参数和关联的运行时。在此示例中，二进制文件被编译为 ELF 可执行文件，并使用内置的 ELF 运行程序。
  • use：声明运行此组件所需的功能。在此示例中，fuchsia.logger.LogSink 协议使组件能够将消息写入系统日志 (syslog)。

清单分片

一些功能集合代表系统中许多组件通用的用例要求，例如日志记录。为了简化将这些功能纳入组件的过程，框架会将其抽象为可添加到 CML 源文件中的清单分片。

以下是与上一个示例等效的 CML。在这种情况下，通过添加 diagnostics/syslog/client.shard.cml（而不是明确声明 fuchsia.logger.LogSink）来提供必要的日志记录功能：

{
    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!",
        ],
    },
}

建筑组件

Fuchsia 构建系统以 GN 导入的形式在 //build/components.gni 中提供模板，以构建软件并将其打包到 Fuchsia 组件中。下面是一个简单 C++ 组件的 BUILD.gn 文件示例：


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",
  ]
}

此文件包含以下主要元素：

  • executable()：将源代码编译为二进制文件。此目标因编程语言而异。例如，executable 目标可用于 C++，rustc_binary 可用于 Rust，go_binary 可用于 Golang。
  • resource()：要作为资源复制到另一个 GN 目标中的可选命名的数据文件集合。这些文件可由组件命名空间内的二进制文件访问。
  • fuchsia_component()：将二进制文件、组件清单和其他资源收集到一个目标中。此目标会使用 cmc 将清单来源编译为组件声明。
  • fuchsia_package()：组件的分布单位。允许将一个或多个组件托管在软件包代码库中，并添加到目标设备的软件包集中。此目标会生成软件包元数据并构建 Fuchsia Archive (.far) 文件。

软件包可以包含多个组件，在 fuchsia_package() 模板中列为 deps。您可以使用 fuchsia_package_with_single_component() 模板简化仅包含一个组件的软件包的 build 文件。

以下简化的 BUILD.gn 示例等同于前一个示例：


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",
  ]
}

练习：创建新组件

在本练习中，您将构建并运行一个基本组件，该组件可读取程序参数并在系统日志中回显问候语。

首先，在 //vendor/fuchsia-codelab 目录中为名为 echo-args 的新组件创建项目基架：

mkdir -p vendor/fuchsia-codelab/echo-args

在新项目目录中创建以下文件和目录结构：

Rust

//vendor/fuchsia-codelab/echo-args
                        |- BUILD.gn
                        |- meta
                        |   |- echo.cml
                        |
                        |- src
                            |- main.rs
  • BUILD.gn：可执行二进制文件、组件和软件包的 GN 构建目标。
  • meta/echo.cml：声明组件的可执行文件和所需功能的清单。
  • src/main.rs：Rust 可执行二进制文件和单元测试的源代码。

C++

//vendor/fuchsia-codelab/echo-args
                        |- BUILD.gn
                        |- meta
                        |   |- echo.cml
                        |
                        |- echo_component.cc
                        |- echo_component.h
                        |- main.cc
  • BUILD.gn：可执行二进制文件、组件和软件包的 GN 构建目标。
  • meta/echo.cml：声明组件的可执行文件和所需功能的清单。
  • echo_component.cc：C++ 组件功能的源代码。
  • main.cc：C++ 可执行二进制文件主入口点的源代码。

添加程序参数

组件清单文件定义了组件可执行文件的属性，包括程序参数和组件的功能。将以下内容添加到 meta/echo.cml：

Rust

echo-args/meta/echo.cml:

{
    include: [
        // Enable logging on stdout
        "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-args",

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

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

C++

echo-args/meta/echo.cml:

{
    include: [
        // Enable logging.
        "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-args",

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

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

记录参数

打开主可执行文件的源文件，并添加以下 import 语句：

Rust

echo-args/src/main.rs:

use tracing::info;

C++

echo-args/main.cc:

#include <lib/syslog/cpp/log_settings.h>
#include <lib/syslog/cpp/macros.h>

#include <cstdlib>
#include <iostream>

#include "vendor/fuchsia-codelab/echo-args/echo_component.h"

添加以下代码以实现 main() 函数：

Rust

echo-args/src/main.rs:

#[fuchsia::main(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(())
}

C++

echo-args/main.cc:

int main(int argc, const char* argv[], char* envp[]) {
  fuchsia_logging::SetTags({"echo"});
  // Read program arguments, and exclude the binary name in argv[0]
  std::vector<std::string> arguments;
  for (int i = 1; i < argc; i++) {
    arguments.push_back(argv[i]);
  }

  // Include environment variables
  const char* favorite_animal = std::getenv("FAVORITE_ANIMAL");
  arguments.push_back(favorite_animal);

  // Print a greeting to syslog
  FX_SLOG(INFO, "Hello", FX_KV("greeting", echo::greeting(arguments).c_str()));

  return 0;
}

此代码读取程序参数并将其传递给名为 greeting() 的函数，以生成 syslog 条目的响应。

添加以下代码以实现 greeting() 函数：

Rust

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(", "),
    }
}

C++

echo-args/echo_component.h:

#include <string>
#include <vector>

namespace echo {

std::string greeting(std::vector<std::string>& names);

}  // namespace echo

echo-args/echo_component.cc:

#include "vendor/fuchsia-codelab/echo-args/echo_component.h"

#include <numeric>

namespace echo {

static std::string join(std::vector<std::string>& input_list, const std::string& separator) {
  return std::accumulate(std::begin(input_list), std::end(input_list), std::string(""),
                         [&separator](std::string current, std::string& next) {
                           return current.empty() ? next : (std::move(current) + separator + next);
                         });
}

// Return a proper greeting for the list
std::string greeting(std::vector<std::string>& names) {
  // Join the list of names based on length
  auto number_of_names = names.size();
  switch (number_of_names) {
    case 0:
      return "Nobody!";
    case 1:
      return join(names, "");
    case 2:
      return join(names, " and ");
    default:
      return join(names, ", ");
  }
}

}  // namespace echo

此函数会根据列表的长度，从提供的参数列表中创建一个简单的字符串。

添加到 build 配置

在 BUILD.gn 文件中更新程序的依赖项：

Rust

echo-args/BUILD.gn:

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


group("echo-args") {
  testonly = true
  deps = [
    ":package",
  ]
}

rustc_binary("bin") {
  output_name = "echo-args"
  edition = "2021"

  # Generates a GN target for unit-tests with the label `bin_test`,
  # and a binary named `echo_bin_test`.
  with_unit_tests = true

  deps = [
    "//src/lib/fuchsia",
    "//third_party/rust_crates:anyhow",
    "//third_party/rust_crates:tracing",
  ]

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

fuchsia_component("component") {
  component_name = "echo-args"
  manifest = "meta/echo.cml"
  deps = [ ":bin" ]
}

fuchsia_package("package") {
  package_name = "echo-args"
  deps = [ ":component" ]
}

C++

echo-args/BUILD.gn:

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


group("echo-args") {
  testonly = true
  deps = [
    ":package",
  ]
}

executable("bin") {
  output_name = "echo-args"

  sources = [ "main.cc" ]

  deps = [
    ":cpp-lib",
    "//sdk/lib/syslog/cpp",
    "//zircon/system/ulib/async-default",
    "//zircon/system/ulib/async-loop:async-loop-cpp",
    "//zircon/system/ulib/async-loop:async-loop-default",
  ]
}

source_set("cpp-lib") {
  sources = [
    "echo_component.cc",
    "echo_component.h",
  ]
}

fuchsia_component("component") {
  component_name = "echo-args"
  manifest = "meta/echo.cml"
  deps = [ ":bin" ]
}

fuchsia_package("package") {
  package_name = "echo-args"
  deps = [ ":component" ]
}

将新组件添加到 build 配置：

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

运行 fx build 并验证构建是否成功完成：

fx build

在下一部分中，您会将此组件集成到 build 中，并在系统日志中测试输出。

上一页
概览
下一页
整理组件