此页面由 Cloud Translation API 翻译。

平台 Surface 区域清单

设计文档

设计初衷

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

术语库

（对已定义的术语表项的引用以 cursive 类型设置。）

平台 Surface 元素。

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

平台展示区域。

平台 Surface 元素的详尽集合。

平台 Surface fragment -

平台界面区域的子集。

平台 Surface 区域清单。

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

要求

在给定的平台 Surface 视图中唯一标识和枚举有用的平台 Surface 元素。
根据平台 Surface 视图，高效生成和遍历可能的许多 Surface 元素。
允许在不同的平台 Surface 种类中重复使用现有的平台 Surface fragment。
允许逐步包含定义和构建的平台 Surface fragment。
与我们的构建系统协作。

为何此时推荐？

为了使 CTF 测试覆盖率信息中心适合所有人使用，它应显示平台界面的被覆盖和未覆盖部分。

平台 surface 的涵盖部分有助于我们对底层平台做出一定正确的正确性和安全性保证。
未覆盖的平台 Surface 部分可引导 CTF 测试作者找到 CTF 测试未充分涵盖的 API Surface 部分。

平台界面区域清单是对 (1) 的补充，也是对 (2) 的补充。

利益相关方

CTF 维护人员
CTF 测试作者

设计

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

plasa 文件的逻辑结构

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

允许不同的子系统改进自己的自定义平台 Surface 区域格式。
允许同时生成平台 Surface 区域 fragment。这样可以避免因大型文件合并而导致平台级 build 瓶颈。
允许使用我们构建系统固有的轻量级元数据传播机制生成平台 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 文档，以包含平台 Surface 清单的存在。

向后兼容性

这是一项没有兼容性基准需要维护的新功能。

安全和隐私保护

此设计在安全和隐私方面是中立的，如下所示：

所有已知的平台 Surface Fragment 都可能不受安全和隐私限制的约束，因为它们的可公开可见程度。
任何专用平台 Surface Fragment 都可以在公开视图之外的清单中定义。如果需要，可以通过将私密和可公开访问的 fragment 都添加到单个清单中来形成整体的平台 surface 清单。

后续工作

后续工作将会看到平台 surface 区域清单涵盖的更多平台 surface 元素：

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