RFC-0268：SDK 类别更新

RFC-0268：SDK 类别更新
状态已接受
区域
  • 开发者
说明

更新了 SDK 类别集并阐明了其含义。
问题
Gerrit 更改
作者
审核人
提交日期（年-月-日）2025-02-20
审核日期（年-月-日）2025-04-02

修改此 RFC

修改 RFC 元数据

问题陈述

更新了 RFC-0165 中记录的一组 SDK 类别，以反映当前用法并阐明含义。

摘要

此 RFC 会更改一组 SDK 类别，并包含更新后的语言，用于描述所有 SDK 类别的含义和用法。这些类别取代了 RFC-0165 中记录的 SDK 类别。设计部分中的类别详细信息的编写方式便于用于更新 SDK 类别文档。

利益相关方

教练：neelsa@google.com

审核者：

  • 平台版本：hjfreyer@google.com
  • 开发者：wilkinsonclay@google.com
  • 测试：crjohns@google.com

社交：

此 RFC 中的更改已提交并与平台版本控制团队进行了讨论。问题 367760026 及相关问题中讨论了 CTF 测试的要求。

要求

更新类别的目标如下：

  • 减少用户对 SDK 类别和使用情形的困惑。这包括移除未使用的类别和已废弃的类别。
  • 具体而言，解决了有关 partner_internal 的混淆问题。partner_internal 经常被误解，这在一定程度上是因为其名称含糊不清，并且包含“内部”字样。
    • 此类别并非 RFC-0165 中记录的 SDK 类别之一；而是 API 委员会会话的结果。
    • 此类别适用于同时由 a) SDK 中分发的预编译库和 b) 宿主工具使用的 ABI。虽然是为了前者而添加的，但后者的用途是前者的两倍。此外，RealmFactory SDK 要求目前建议使用此类别。
    • 分发组件中使用的库和开发者使用的工具可能具有非常不同的兼容性期限要求，随着 Fuchsia 的成熟和弃用阶段 API 级别数量的增加，这种差异可能会显著扩大。
  • 定义了一种解决方案，可在不增加开销或承诺在 SDK 中发布 API 的情况下稳定 CTF 测试所用 API（问题 367760026）。
  • 使流程和兼容性期限能够根据用例以及暴露或风险而有所不同。
    • 具体而言，减少了稳定 CTF 测试所需的 API 和主机工具使用的 API 的开销。这些 API 过去使用的是不稳定的 API，因此存在兼容性破坏的风险。

本 RFC 不会尝试解决理论性或非常不常见的情况，例如问题 369892217 中所述的情况。

设计

与 RFC-0165 中所述的类别一样，新类别的排列顺序是按受众群体单调递增的顺序。被替换的现有类别用括号括起来。

  • compat_test（以前称为 cts）
  • host_tool（以前位于 partner_internal 中）
  • prebuilt（以前位于 partner_internal 中）
  • partner

每个类别名称都是一个单数名词，用于描述其受众群体，或该类别 API 的使用场景。如需为受众群体命名，请在类别名称中添加“开发者”。例如，“托管工具开发者”。

除了上述替换的类别外，我们还移除了 RFC-0165 中记录的以下 SDK 类别：

  • excluded：功能上等同于不指定 SDK 类别。此类别很少使用，并且尚不清楚这些用例是否表明这些原子绝不应包含在 SDK 中。您可以改用更灵活且不易产生歧义的注释。
  • experimental：在 RFC-0165 中被描述为没有多大意义。
  • internal：等同于不指定 SDK 类别。（已移除大多数用途。其余用途已将此类别用于其他用途 - 请参阅问题 372986936。在这些用例被弃用之前，我们仍会对此类别提供有限支持。）
  • public：从未实现。在扩大 SDK 的受众群体时，我们可以重新评估该机制。您日后可以轻松添加此类别。

移除 public 后，partner 相当于“已发布到 SDK”。 由于现有名称的使用广泛，人们对其含义的认知度和理解度较高，并且未来可能适用于 public 或类似名称，因此我们保留了该名称。

以下部分详细介绍了每个类别的含义和兼容性要求，首先介绍了可在 sdk_atom() 模板等位置使用的简短说明。以下是关键要点的总结：

  • prebuilt 和 partner 类别中的库可能会在最终用户设备上的生产用例中使用，因此对平台实现具有相同的兼容性要求。
  • 只有 partner 类别中的 API 才能被外部开发者（SDK 使用方）直接使用。
  • 所有类别都可以用于 FIDL 库。其他 SDK 原子类型通常会直接向开发者公开，因此其他类别对他们来说不太有意义。
    • 因此，当前实现仅允许非 FIDL 原子类型属于 partner 类别。
  • partner 类别中允许不稳定的库（在 SDK 中公开，但仅在 HEAD 时可用，且不保证兼容性）。其他类别的目的是兼容性，因此不稳定的库不太适合它们。
    • 因此，当前实现仅允许 partner 类别中的库处于不稳定状态。
  • 所有类别的库在检测和防止稳定 API 级别发生更改的机制方面都受到相同的处理。
    • 目前，唯一的此类测试是与 FIDL 库的 API 摘要金标准文件进行比较。每个稳定的数字 API 级别都会在创建时创建快照。我们还会维护 NEXT 的快照，以便检测和审批 API 更改。如需了解详情，请参阅 SDK 历史记录。

下表总结了上述信息。反映当前实现的列会以此标记。

名称 上一个类别 可在最终用户设备上的正式版中使用 可供 OOT 开发者直接使用（“在 SDK 中”） 强制执行更改检测 是否可与 FIDL 库搭配使用？ 是否可与其他 SDK 原子类型搭配使用？（当前实现方式） 可能不稳定（当前实现）
compat_test cts（未实现） 否 否 是 是 否 否
host_tool partner_internal 内 否 否 是 是 否 否
prebuilt partner_internal 内 是 否 是 是 否 否
partner 不适用 是 是 是 是 是 是

compat_test

“可用于配置和运行兼容性测试，但不得公开用于 SDK 中的正式版或供主机工具使用。”

注意：为在当前机制和实践的背景下保持清晰，本部分使用“CTF”来代替“兼容性测试”。不过，本 RFC 并不禁止在未来可能出现的类似平台兼容性测试中使用。

此类别中的库很可能包含 CTF test realm factory 协议，或者通过 realm 工厂返回的 fuchsia.testing.harness/RealmProxy 或 fuchsia.component.sandbox/Dictionary 提供给测试。这些协议提供了稳定的测试 harness，用于比较不同版本 Fuchsia 中相同操作的行为，并且 harness 协议本身也必须具有兼容性保证，以确保可以在相关 Fuchsia 版本上运行兼容性测试。

虽然此类 API 可能会在平台内的生产代码中使用，但只能通过 CTF 测试环境或类似环境在平台外部公开。

注意：与所有 SDK 类别一样，此类别中的 FIDL 库必须在 "fuchsia" FIDL 平台中进行版本控制。因此，如果库名称以 test. 或 fuchsia. 以外的任何字符串开头，则必须在库的 @available 属性中指定 platform="fuchsia"。

  • 披露对象：CTF 测试以及负责这些测试的 Fuchsia 平台开发者。CTF 测试非常重要，因为它们有助于确保 ABI 兼容性，尤其是对旧版 API 级别的运行时支持。
  • ABI 兼容性窗口：只要我们需要运行相关 CTF 测试，就必须支持 API。
    • 一般来说，这意味着只要针对受支持或弃用阶段（“运行时支持”）的 API 级别的测试使用它们，就符合条件。
    • 我们可以选择停止运行测试、重新构建测试以使用其他 API，或引入代理以使用新 API。

host_tool

“可以由平台组织提供的主机工具（例如 ffx）使用，但不得由 SDK 中的正式版代码或预构建二进制文件使用。”

  • 披露：开发者使用平台提供的工具与支持工具支持的 API 级别的目标 Fuchsia 设备进行互动。
  • ABI 兼容性窗口：必须支持 API，直到平台不再支持在支持这些 API 的任何 API 级别与主机工具通信为止。
    • 这与使用不同版本的宿主工具与给定平台版本进行通信有关。
    • 注意：平台为此托管工具运行时支持的 API 级别集可能与以下任一级别或两者都不同：
      • 当前平台版本支持的一组组件目标 API 级别（组件运行时兼容性）。
      • 当前版本中托管工具支持用于与目标设备通信的一组 API 级别。
  • 由于此类别的 API 不会在 IDK/SDK 中使用，因此：
    • 任何非平台组件（即由外部开发者构建的组件）都无法（在未进行黑客攻击的情况下）使用这些 API。
    • 只要我们愿意处理对下游开发者的影响，就可以在不影响最终用户的情况下打破这些限制。我们还需要考虑 CTF 测试的任何用途。

实现说明：IDK/SDK 中的托管工具属于 "partner" 类别，但可以使用此类别中的 API。不过，"partner" 中的 API、代码、预编译库和预构建软件包不得使用此类别中的 API。

预构建

“可能属于 SDK 中包含的预构建二进制文件用于与平台交互的 ABI 的一部分。此类别中的 API 不适合供非树内开发者直接使用。”

SDK 中的预构建二进制文件（用于生产环境）目前包括预编译的静态库、预编译的共享库和软件包。从外部开发者的角度来看，这些是二进制文件的实现细节的一部分，不会在面向开发者的库或打包组件 API 中使用。预构建库和软件包内部使用的源代码集和库不需要属于任何 SDK 类别，但它们用于与平台交互的 API 需要属于某个类别。

  • 曝光对象：最终用户。
  • ABI 兼容性期限：只要支持某些 API 的任何 API 级别处于受支持或弃用阶段，就必须支持这些 API。即与 partner 相同的窗口。
  • 因为平台团队控制着使用此类 API 的所有软件：
    • 我们不一定需要太过担心开发者的工效学。
    • 我们无需担心第三方组件会使用该 API。
    • 我们可以针对新的 API 级别 (NEXT) 替换 SDK 预编译库和预构建软件包中的用法，从而比考虑下游用例时更快地取消运行时支持（而无需废弃）。

合作伙伴

“包含在 SDK 中，供外部开发者直接使用该 API。”

  • 公开范围：最终用户、外部开发者和产品所有者。
  • ABI 兼容性期限：只要支持某些 API 的任何 API 级别处于受支持或弃用阶段，就必须支持这些 API。
  • 此类别包括由外部开发者和/或产品组件路由到或从组件的功能。
    • 例如，产品所有者必须路由到平台的功能，以及必须路由到或从 SDK 中的预构建软件包的功能。

实现

实现将分为以下阶段完成：

  1. excluded 和 experimental 已被移除。
  2. 移除了对 public 的引用。
  3. 将 cts 替换为 compat_test 并实现它。
  4. 将 https://fxbug.dev/365602422 中跟踪的 FIDL 库添加到 compat_test 类别，并将其从许可名单中移除。
  5. 将 partner_internal 替换为 host_test 和 prebuilt。
    • 更新了 ffx 插件和工具使用的 SDK 标记机制，以允许同时使用这两者。
    • 添加了一些调整，以便将 FIDL 库的重新分配推迟到下一步。
  6. 根据需要将使用 partner_internal 的 FIDL 库分配给 host_test 或 prebuilt。
  7. 最终，在现有用途已提升到受支持的类别或已移除后，移除对 internal 的支持（问题 372986936）。

性能

性能不会受到影响，因为类别只会影响 build，并且只会更改现有机制中使用的字符串。

工效学设计

平台开发者使用的机制保持不变。类别数量越少、名称越精确，就越容易理解它们的含义，以及哪个类别适合特定用例。

向后兼容性

此 RFC 仅会影响平台 build 规则。在实施过程中，已移除类别的所有用法都将更新。

安全注意事项

此 RFC 不会更改 build 中存在或向开发者公开的 ABI 接口。

隐私注意事项

此 RFC 不会更改 build 中存在或向开发者公开的 ABI 接口。

测试

//build/sdk/sdk_common/sdk_common_unittest.py 中的类别测试将更新，以反映每个类别的更改。

此外，任何类别的 FIDL 库都应在 //sdk/history 中包含 <library_name>.api_summary.json 文件。您可以验证添加到 compat_test 的库是否符合此要求。此外，我们可以在本地删除所有此类文件，并确保它们已生成（Git 中没有缺失的文件）。

文档

主要的 SDK 类别文档将更新。我们还将更新对 partner_internal 的 RealmFactory SDK 要求引用。

缺点、替代方案和未知情况

大多数替代方案涉及的选项较少，以减少平台开发者需要了解和做出的决策数量。例如，将 partner 和 prebuilt 组合在一起，因为它们具有相同的兼容性要求，甚至具有单个位 - 某项内容是“在 SDK 中”/是否需要兼容性。有人提出了非正式提案，建议完全用两个布尔值来替换现有类别

虽然此类选项在适当情况下可以实现确保兼容性的目标，但无法满足某些非技术要求。例如，平台开发者表示希望在不进行完整 API 校准的情况下获得兼容性保证。（未来，这个问题可能不会那么严重。）此外，如果我们知道平台团队拥有 API 的所有使用权，则会稍微灵活一些。这对于平台充当客户端的 FIDL 协议可能尤为重要（请参阅 RFC-0241）。建议使用命名惯例来保留其中的一些属性。不过，这可能会更容易造成混淆，并且更难以强制执行（例如在构建规则中）。

此 RFC 中的变更更为渐进，继续使用类别字符串的概念和现有的强制执行机制，这意味着这些变更可以快速实现。虽然我们做出了这些变更，但这并不排除我们日后在积累更多经验并更好地了解兼容性需求后，再做出此类变更的可能性。具体而言，我们可能需要一些机制来为 SDK 中的 API 定义不同的兼容性时间范围。

另一种方法是保留单个类别 partner_internal（可能使用新名称），以便用于主机工具和预编译库用例。不过，通过描述用例来解释某些内容似乎比找到一个涵盖这两者的明确名称更容易。如果我们日后需要考虑破坏兼容性，单独分类还可以提供使用记录。此外，如果平台和宿主工具支持的 API 级别范围不同，则每个工具的支持期限也会有所不同。

在先技术和参考文档

  • RFC-0165 定义了当前的一组类别，这些类别在现有 SDK 类别文档中有所记录。
  • 此 API 委员会会话促成了 partner_internal 类别的定义，其中讨论了一系列相关问题，包括：
    • 需要使用 SDK 中不存在的稳定 API。
    • 不希望将某些 API 公开供应用直接使用，以及控制使用 API 的所有代码的好处。
    • 发现 CTF 测试作者会有类似的用例。
    • 将新类别描述为“对内部人员可见，合作伙伴稳定”，为最终名称 partner_internal 提供了背景信息。
    • 建议将 "prebuilts" 用作新类别的名称。
      • 由于这个名称有其他含义，因此有人对其提出了一些反对意见，但据传，在指代 SDK 中的静态库和共享库时，这个术语似乎越来越常见。
  • 问题 328322682 包含对现有 SDK 类别的早期评估。
  • 问题 367760026 提供了 compat_test 的动机。
  • RealmFactory SDK 要求介绍了 RealmFactory FIDL 协议的要求。