此页面由 Cloud Translation API 翻译。

平台 Surface 区域清单

设计文档

设计初衷

提供计算平台的平台 Surface 元素的详尽列表 CTF 工作的 Surface 测试覆盖率。

术语库

（对已定义的术语表项的引用采用 cursive 类型排版。）

平台 surface 元素。

Fuchsia 公共 API 或 ABI 中已命名的最小组件。

平台表面积。

平台 Surface 元素的详尽集合。

平台 surface fragment。

平台展示区域的一部分。

平台 surface 清单。

包含指向平台 Surface fragment 文件的指针的文件。

要求

可唯一标识和枚举给定中有用的平台 Surface 元素平台表面视图。
根据情况，高效生成和遍历可能的许多 Surface 元素平台 Surface 视图
允许在不同的平台间重复使用现有的平台 surface fragment 平台表面类型。
允许按原样增量包含平台 Surface fragment 定义和构建。
与我们的构建系统协作。

为何此时推荐？

为了让 CTF 测试覆盖率信息中心普遍有用，它应该显示平台表面被覆盖和未覆盖的部分。

我们可以通过平台表面的被遮盖部分正确性和安全性保证。
CTF 测试作者在平台 Surface 中未发现的部分 CTF 测试未充分覆盖的 API Surface 部分。

平台 surface 清单可补充 (1) 并满足 (2)。

利益相关方

CTF 维护者
CTF 测试作者

设计

平台表面区域以平台表面的集合的形式描述 fragment 文件，后者还有一个平台 Surface 清单文件，所有此类文件在 Fuchsia 的 build 输出目录中的位置（$FUCHSIA_DIR/out/default 或类似名称）。按照惯例，清单文件为名为 manifest.plasa.json，而 fragment 文件的名称与文件路径模式 *.fragment.plasa.json，如下图所示。

plasa 文件的逻辑结构

选择这种中心辐射式清单布局的原因有很多：

允许不同的子系统改进自己的自定义平台 surface 格式。
允许同时生成平台 surface 区域 fragment。这个避免因大型文件合并而出现平台级构建瓶颈。
允许使用轻量级元数据传播机制。
可根据需要轻松扩展平台 surface 区域元数据。

工具需要识别此文件布局，并确保所有文件得到正确处理对于需要单个文件的工具，应该编写能够合并文件的脚本。

清单文件格式

清单文件格式为一系列 JSON 格式的对象。每个对象包含对 fragment 文件的引用以及 fragment。清单是一个项目的序列我们的构建系统特别容易生成这种格式，同时能够充分详细地描述相关内容。

顺序...
- kind（枚举）：相关 fragment 的种类。每种不同的类型可以进行不同的解读。在撰写本文时，可能的值为：
- api_cc：表示相关 fragment 遵循 C++ API fragment 格式
- api_fidl：表示相关 fragment 遵循 FIDL API 摘要格式（根据 RFC-0076）
- file（字符串）：fragment 的完全限定标签。

示例

[
  {
    "file": "//out/workstation_eng.x64/gen/sdk/lib/fdio/fdio.fragment.plasa.json",
    "kind": "api_cc",
  },
  {
    "file": "//out/workstation_eng.x64/gen/sdk/lib/stdcompat/stdcompat.fragment.plasa.json",
    "kind": "api_cc",
  },
  {
    "file": "//out/workstation_eng.x64/gen/sdk/lib/fit/fit.fragment.plasa.json",
    "kind": "api_cc",
  }
]

C++ API fragment 文件格式

fragment 文件格式目前是一系列平台元素项。必要时，我们可能会扩充此格式。

以下各项的 JSON 对象
- items（顺序）...
- name（字符串）：平台 surface 元素的名称。
- file（可选 [String]）：指定元素所在文件的文件路径。
- line（可选 [Integer]）：file 行中，元素为。

示例

{
  "items": [
        {
            "name": "fit::deferred_action::deferred_action<T>",
            "file": "gen/sdk/lib/fit/../../../../../../sdk/lib/fit/include/lib/fit/defer.h",
            "line": 81
        },
        {
            "name": "fit::deferred_action::operator bool",
            "file": "gen/sdk/lib/fit/../../../../../../sdk/lib/fit/include/lib/fit/defer.h",
            "line": 43
        }
  ]
}

文档和示例

我们可能需要更新 CTF 文档，以添加平台接口清单

向后兼容性

这是一项新功能，它没有与维护。

安全和隐私

此设计不影响安全和隐私，如下所述：

可能并非公开的所有平台途径 Fragment 受到安全和隐私限制，由于其公众的性质，可见性。
任何专用平台 Surface 片段都可以在具有以下特征的清单中进行定义：公共视图以外的地方整个平台途径清单可以通过同时包含私有和可公开访问的 fragment 而形成的放入一个清单中

未来工作

未来的工作将涵盖平台 surface 中的更多元素，平台 surface 清单：

在清单中表示命令行实用程序和标志。
在清单中表示其他 Plasa 元素。