组件清单（组件 v1）

<<../_v1_banner.md>>

组件清单 (.cmx) 是文件扩展名为.cmx的 JSON 文件。 组件清单通常位于包的 meta/ 目录中,包含声明如何运行组件和 它收到资源的信息。 特别的是，组件清单描述了组件是如何被沙箱化的。

这是 ELF 二进制组件的 cmx 的简单示例：

{
    "include": [
        "src/lib/syslog/client.shard.cmx"
    ],
    "program": {
        "binary": "bin/example_app",
        "args": [ "--example", "args" ]
    },
    "sandbox": {
        "system": [ "data/sysmgr" ],
        "services": [
            "fuchsia.posix.socket.Provider",
            "fuchsia.sys.Launcher"
        ]
    }
}

还有一个用于 flutter/dart 组件的组件清单：

{
    "program": {
        "data": "data/simple_flutter"
    },
    "runner": "flutter_jit_runner"
}

include 属性

可选的 include 属性描述了零个或多个（或分片）组件清单要被合并到此组件清单中。

在上面给出的示例中，组件清单包含来自syslog 库提供的文件的内容， 从而确保组件在尝试写入 syslog 时在运行时正常运行。 按照惯例，此类文件以.shard.cmx结尾。

如果在 fuchsia.git 中工作，包含路径是相对于 Fuchsia 树的源根的。

您可以通过调用以下命令，查看将任何和所有包含合并到组件清单文件的结果：

fx cmc include {{ "<var>" }}cmx_file{{ "</var>" }} --includepath $FUCHSIA_DIR

include 是可以是递归的，这意味着分片可以有自己的include文件。

program 属性

program 属性描述了执行组件的资源。

如果 runner 不存在，则program属性是具有以下方案的 JSON 对象：

{
    "type": "object",
    "properties": {
        "binary": {
            "type": "string"
        },
        "args": {
            "type": "array",
            "items": {
                "type": "string"
            },
        },
        "env_vars": {
            "type": "array",
            "items": {
                "type": "string"
            },
        },
    }
}

binary 属性描述了在包命名空间中的哪个位置可以找到运行组件的二进制文件，可选的 args 属性包含要提供给进程的字符串参数。 可选的 env_vars 属性指定要提供给二进制文件的环境变量，其中数组中的每个元素都使用"VAR=VALUE"格式，例如"RUST_BACKTRACE=1"。

如果 runner存在，则 program 是一个自由格式的字符串 JSON 对象，被解释为传递给 runner 的 args。

例如，对于 flutter/dart 组件，其格式为：

{
    "type": "object",
    "properties": {
        "data": {
            "type": "string"
        }
    }
}

runner 属性

runner 是一个可选属性，用于命名将被执行委派的另一个组件（或包包含的一个组件) 。 目标组件必须暴露 Runner 服务。

如果存在 runner属性，则 program 是一个自由格式的字符串-字符串 JSON 对象，被解释为传递给runner的 参数。

如果 runner 不存在，则假定 program.binary 是一个 ELF 二进制文件或 shell脚本。

facets 属性

facets 是一个可选属性，包含关于组件的自由格式 JSON。 系统上的事物可以使用 Facet 来获取有关组件的其他元数据。

facets 的格式是：

{
    "type": "object"
}

作为 facet 的一个例子，fuchsia.test 字段用于传达额外的服务的具体内容： 注入测试环境.

sandbox 属性

sandbox 属性控制组件执行所处的环境。具体来说，该属性控制组件在执行期间可访问的目录。 sandbox 属性是一个具有以下架构的 JSON 对象：

{
    "type": "object",
    "properties": {
        "dev": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "services": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "system": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "pkgfs": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "features": {
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    }
}

dev 数组包含一个众所周知的设备目录列表，这些目录是提供给组件的。例如，如果字符串 class/input 出现在 dev 数组，然后 /dev/class/input 将出现在从包中加载的组件的命名空间中。要允许访问 misc 设备，请添加字符串 misc 到 dev 数组。不允许访问某些misc类型的设备。

system 数组包含系统包中提供给组件的已知路径的列表。例如，如果字符串bin 出现在 system 数组中，那么 /system/bin 将出现在从包加载的组件的命名空间中。

pkgfs 数组包含 pkgfs 树中提供给组件的已知路径的列表。例如，如果字符串 versions 出现在 pkgfs 数组中，然后 /pkgfs/versions 会出现在从包加载的组件的命名空间中， 从而可访问所有完全缓存在系统的包。

services 数组定义了组件可以访问的来自 /svc 的服务列表。一个典型的组件将需要来自 /svc的数字服务以便在系统中发挥一些有用的作用。 例如，如果 "services" = [ "fuchsia.posix.socket.Provider", "fuchsia.sys.Launcher" ],， 该组件将具有启动其他组件和访问网络服务的能力。 一个组件可以在其services 中声明任何服务列表， 但它只能访问其环境 中存在的服务。 这个属性应该由所有新组件定义，很快就会发生迁移以将所有组件转换为定义“服务”。

features 数组包含软件包希望使用的众所周知的特性列表。 在此列表中包含一个功能是执行环境对包内容的请求，以获得使用该功能所需的资源。

目前已知的一组特征如下： <!—

• config-data, which will provide any configuration data available to the package this component is in that was provided in the config-data package on the system.

• introspection, which requests access to introspect the system. The introspection namespace will be located at /info_experimental.

• isolated-cache-storage, which requests access to persistent storage for the device, located in /cache in the package’s namespace. This storage is isolated from the storage provided to other components. Unlike isolated-persistent-storage, items placed in the storage provided by this feature will be deleted by the system to reclaim space when disk usage is nearing capacity.

—>

• config-data，它将提供任何可用的配置数据。该组件所在的包在 config-data 中提供 系统上的包。

• introspection, 它请求访问以检查系统。命名空间将位于/info_experimental。

• isolated-cache-storage，它请求访问设备的持久存储，位于包命名空间的 /cache 中。 此存储与提供给其他组件的存储隔离。 不像 isolated-persistent-storage，当磁盘使用量接近容量时，系统将删除放置在此功能提供的存储中的项目以回收空间。 <!—

• isolated-temp, which requests that a temp directory be installed into the component’s namespace at /tmp. This is isolated from the system temp and the temp directories of other component instances. This directory is backed by an in-memory filesystem, and is thus cleared on device reboots.

• root-ssl-certificates, which requests access to the root SSL certificates for the device. These certificates are provided in the /config/ssl directory in the package’s namespace.

• hub, which shows information about the component instance’s realm and its children in a directory structure.

—>

• isolated-temp, 它要求将临时目录安装到组件的/tmp命名空间。 这与系统临时目录和其他组件实例的临时目录隔离。 该目录由内存文件系统支持，因此在设备重新启动时被清除。

• root-ssl-certificates, 它请求访问设备的根 SSL 证书。 这些证书在包命名空间的/config/ssl 目录中。

• hub, 它在 目录结构 中显示有关组件实例的领域及其子项的信息。

• deprecated-shell, 它请求访问适合于交互式命令行的资源 。 通常，shell 被授予访问所有 当前环境中可用的资源。 deprecated-shell 功能还暗示了root-ssl-certificates和hub功能。 顾名思义，此功能将被删除。 目前使用这个功能已明确列入许可名单，不鼓励新用途。

• shell-commands, 它请求访问当前可用的 shell 二进制文件（注意：不是“已安装”，而是“可用”）。二进制文件被映射到 请求者命名空间中的/bin。 运行这些命令可能还需要请求 fuchsia.process.Resolver 和 fuchsia.process.Launcher 服务。

• vulkan, 它请求访问使用 Vulkan 图形界面所需的资源。 这会在包命名空间的 /config/vulkan目录中添加图层配置数据。

• deprecated-ambient-replace-as-executable, 它为将无效句柄与 replace_as_executable 一起使用提供了遗留支持。 <!—

• factory-data, which requests access to the read-only factory partition for the device and places it at /factory in the component’s namespace.

• durable-data, which requests access to the read-write durable partition for the device and places it at /durable in the component’s namespace. This partition is for storing persistent data that will survive a factory reset, and is only to be used for specific, approved use cases.

See sandboxing for more information about sandboxing. —>

• factory-data, 它请求访问设备的只读工厂分区，并将其放置在组件命名空间中的/factory。

• durable-data, 它请求访问设备的读写持久分区，并将其放置在组件命名空间中的/durable。 此分区用于存储在恢复出厂设置后仍可保留的持久数据，并且仅用于特定的、经批准的用例。

参考 沙盒 了解有关沙盒的更多信息.