| RFC-0169：SDK 工具兼容性 | |
|---|---|
| 状态 | 已接受 |
| 区域 |
|
| 说明 | 描述了 SDK 工具的兼容性要求 |
| 问题 | |
| Gerrit 更改 | |
| 作者 | |
| 审核人 | |
| 提交日期（年-月-日） | 2022-05-06 |
| 审核日期（年-月-日） | 2022-06-16 |
摘要
开发者需要使用各种基于 Fuchsia 的产品，每种产品可能支持不同的 Fuchsia ABI 修订版本。开发者使用主机端工具连接到 Fuchsia 系统并与这些系统互动。这些工具需要针对其连接到的 Fuchsia 系统制定明确的兼容性政策，以确保用户获得可预测且清晰的行为。
此 RFC 规定了一组政策，用于说明工具何时应与基于 Fuchsia 的产品版本兼容，以及我们打算采取的一些初始步骤来强制执行兼容性。
该政策的极简版本是，如果 SDK 随附受支持的开发者工具，则该开发者工具的兼容性保证与以该 SDK 支持的最新 ABI 修订版本为目标的组件相同。因此，该工具将保证可与支持相应 ABI 的任何后续 Fuchsia 产品软件包（如 RFC-0100 中所述）搭配使用。
设计初衷
Fuchsia 对组件与给定系统的兼容性有明确的定义。如 RFC-0002 中所述，每个版本的 Fuchsia SDK 都支持一组 API 级别和 ABI 修订版本。如果某个组件以给定的 ABI 修订版本为目标平台，并且 Fuchsia 产品软件包（运行 Fuchsia 产品所需的一组制品，不包括 SDK 及其工具）支持该修订版本，则该组件与给定的产品软件包兼容。
自推出以来，新的 Fuchsia 平台版本会在特定时间段内（即兼容性窗口）继续支持 ABI 修订版本。（即将发布的 RFC 将阐述一项新政策，说明我们如何确定兼容性窗口的长度。）因此，在兼容性窗口期间，该组件将与新的 Fuchsia build 兼容。
对于随 Fuchsia SDK 发布的工具，没有类似的兼容性概念，这些工具目前具有临时兼容性机制，主要反映了特定团队和开发者的意图。此 RFC 解决了这一缺点。
工具和组件之间的不匹配可能会让用户感到非常沮丧。许多 Fuchsia 用户会单独从工具下载产品软件包。这会导致开发者使用的工具支持的 ABI 与他们尝试监控和管理的产品支持的 ABI 不同。这会导致开发者难以诊断和解决的错误。
在此 RFC 中，我们针对工具何时应与给定的 Fuchsia 产品软件包搭配使用设置了初始政策，并描述了我们打算采取哪些步骤来强制执行和传达此政策。此政策并非旨在提供完整信息。我们在此处未提及 SDK 工具兼容性的其他方面，例如有关命令行选项生命周期的保证，或工具与旧版 C/C++/FIDL 标头的兼容性。
利益相关方
辅导员：
abarth
审核者：
abarth（版本控制，Fuchsia TL） amituttam（工具） dschuyler（SDK） sebmarchand（客户代表） sethladd（SDK，版本控制）
已咨询：
ffx 团队 CTF 团队 编辑团队 wilkinsonclay（开发者关系） yaar（客户代表）
共同化：
此 RFC 已与组件框架和开发者领域的代表进行了沟通，并在邮件列表中与 Fuchsia 版本控制方面的利益相关者进行了讨论。
设计
定义
SDK 工具是随 SDK 提供的可执行文件。请注意，就本政策而言，单个 ffx 插件算作单个工具。
Partner API 和 Partner Tools 是 API 和工具，支持供与 Fuchsia 团队密切合作进行功能开发的特定个人和团队使用。它们随附在 合作伙伴 SDK 中。
公共 API 和公共工具是指支持供任何人使用的 API 和工具。它们随附在 Public SDK 中。请注意，截至本文档撰写之时，还没有公开 SDK，只有合作伙伴 SDK。
在本文档中，我们使用“稳定”一词来指代以下两类工具/API：a) 以公共或合作伙伴 ABI 为目标的受支持的合作伙伴工具/API；b) 以公共 API 为目标的假设性未来公共工具/API。未来，公共平台和合作伙伴平台可能会有不同的兼容性窗口，但这种区别与本文档无关。
如果 SDK 工具没有任何指示（通过命令行标志、工具本身的命名方式 [例如 foo_internal] 或文档）表明其处于实验阶段，则表示该工具是受支持的。例如，ffx 工具具有多个实验性子命令，这些子命令不被视为受支持。即使系统声称与特定 ABI 修订版本兼容，也不保证不受支持的工具能够正常运行。
政策
此 RFC 引入了一项要求，即随 SDK 附带的受支持的开发者工具在与系统交互时，必须仅通过相应 SDK 支持的 ABI/API 与平台交互。
如果某个工具支持合作伙伴使用，则必须仅使用合作伙伴或公共 ABI / API 进行交互。如果某个工具支持公开使用，则必须仅使用公共 ABI / API 进行交互。受支持的 SDK 工具不得使用内部或实验性 ABI / API。
遵循此规范可确保受支持的 SDK 工具与在兼容性窗口期间开发的所有 Fuchsia 产品（无论是从主分支还是从为这些 ABI 和 ABI 创建的分支）兼容。
稳定的开发者工具可能会以之前稳定的 API / ABI 为目标，即已从平台中弃用或移除的稳定 API / ABI。例如，Fuchsia 项目可能会发现，如果能使用工具将新映像刷写到运行早于兼容性窗口的映像的设备上，会很有用。此类行为应在文档中明确说明。在这种情况下，除非工具本身已被弃用，否则它们必须继续与稳定的 API/ABI 搭配使用。
除了已弃用和已移除的 API / ABI 之外，当稳定工具以非稳定 API/ABI 为目标时，这会被视为 bug，并且必须制定计划将它们过渡到稳定 API/ABI 或将其移除。这包括 SDK 中使用非稳定 API 的当前受支持的工具。
为了便于实验，SDK 可能包含不稳定的开发者工具。这些内容必须标记为“广告”。非稳定版开发者工具可能会使用非稳定版 ABI / API。非稳定版工具的文档必须指明它们不受支持。对非稳定工具的调用应明确表明它们不受支持（例如，通过要求使用额外的命令行标志）。使用此类工具时，可能会产生警告。
各个 ffx 插件被视为单独的工具，这意味着，例如，ffx foo 可能被视为稳定版，但在同一版本中，ffx bar 可能不是稳定版。其他工具可能具有类似的政策，这些政策应有详细的文档说明。
Fuchsia 平台不保证其工具的前向兼容性。最新版本的工具可能无法与旧版产品搭配使用。开发者应尽一切努力确保工具在这些情况下提供清晰且可据以采取行动的错误消息。
实现
各个 SDK 工具的所有者可能会决定在开发期间通过测试和 build 支持等机制强制执行兼容性要求。这些强制执行机制将来可能会成为 SDK 工具的强制性要求。
ffx 工具团队计划采取以下措施来确保兼容性。此列表并非详尽无遗，仅列举了一些示例，说明团队可以采取哪些措施来强制执行这些政策。
旧版
ffx将作为 CTF 测试集（在 RFC-0015 中定义为CTS tests）的一部分运行，以确保新版平台 build 与经过测试的功能保持兼容。ffx的命令行和 JSON 接口将进行版本控制，并且将强制执行这些版本的兼容性。ffx工具及其底层 Overnet 传输将具有兼容的目标 ABI 修订版本，该版本很可能是在构建时fuchsia.git头的修订版本。该工具会将目标 ABI 修订版本报告给 Fuchsia 目标上的服务。服务将报告 ABI 是否在支持的集合中。如果不是，ffx将向用户显示错误，并引导用户前往兼容版本的ffx。随着兼容性强制执行的不断发展，我们可能需要重新审视此方法的具体细节；在短期内，只有静态 ABI 修订版（即在汇编时确定）可用，但在长期内，系统的不同部分将公开不同的 ABI，我们需要提供更动态的检查。内置于
fuchsia.git中的稳定版ffx插件将使用 build 限制来限制其使用的 FIDL 定义集，使其仅限于公共和合作伙伴 SDK 中提供的定义。Fuchsia 工具所有者的明确目标是将旨在获得长期支持的
ffx插件从不稳定的 API 和 ABI 迁移出来。ABI 修订版本将纳入产品软件包元数据，以帮助开发者在运行产品软件包之前确定哪些版本的
ffx可与该产品软件包搭配使用。我们的目标是将版本标识信息附加到任何需要该信息的ffx输入。
性能
这些政策不会影响效果。强制执行这些政策可能会影响性能；不过，这是单个工具的服务质量问题。
工效学设计
这些政策通过明确指定给定工具何时与给定 Fuchsia 目标兼容，从而改进工具的人体工程学设计。
向后兼容性
许多现有的 SDK 工具不支持检测或强制执行兼容性保证的机制，并且许多工具使用不稳定的 API 和 ABI。有些工具需要过渡到长期稳定的 ABI。与往常一样，您必须谨慎执行过渡，以尽量减少对用户的干扰。开发者应考虑以下选项：将工具使用的非稳定 API 和 ABI 视为稳定，在整个兼容性窗口期间继续支持它们，并软过渡到稳定的替代项。
安全注意事项
这些政策不会带来已知的安全问题。
有时，安全问题可能会导致我们不得不打破兼容性保证。例如，我们可能会发现用于从主机向设备通信的 Overnet 传输存在安全问题。
隐私注意事项
这些政策与用户数据的收集无关。
测试
虽然最佳做法是使用测试来确保面向 SDK 的开发者工具遵守这些政策，但此 RFC 并未要求开发者工具这样做。Fuchsia CTF（以前称为 CTS）提供了一种测试机制，一些工具开发者可能希望采用这种机制。
文档
应更新工具文档，以引用此政策。
缺点、替代方案和未知因素
一种替代方案是采用临时兼容性方法，即每种工具都提供自己的最低兼容性窗口。在实践中，我们发现这会给用户造成很大的困惑，因为用户通常不会单独使用某个工具。例如，如果 ffx log 有效，但 ffx component 无效，用户可能会感到意外。
在先技术和参考资料
许多系统的工具都面临向后兼容性挑战。例如，在 Java 中，字节码会标记有类文件版本号。JVM 具有一组它能理解的类文件版本号。过旧的 classfile 可能无法正常运行。