| 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
Reviewers:
abarth（版本控制、Fuchsia TL） amituttam（工具） dschuyler（SDK） sebmarchand（客户代表） sethladd（SDK、版本控制）
咨询了：
ffx 团队 CTF 团队 编辑团队 wilkinsonclay（开发者关系） yaar（客户代表）
社交：
我们与组件框架和开发者领域的代表一起讨论了此 RFC，并在邮寄名单上与 Fuchsia 版本控制的利益相关方进行了讨论。
设计
定义
SDK 工具是随 SDK 一起提供的可执行文件。请注意，根据此政策的规定，各个 ffx 插件都属于各个工具。
合作伙伴 API 和合作伙伴工具是面向与 Fuchsia 团队密切合作开发功能的目标个人和团队提供的受支持 API 和工具。它们会在合作伙伴 SDK 中提供。
公共 API 和公共工具是指任何人都可以使用的 API 和工具。它们会在公开 SDK 中提供。请注意，在撰写本文档时，还没有公开 SDK，只有合作伙伴 SDK。
在本文档中，我们使用术语稳定来指代：(a) 以公共或合作伙伴 ABI 为目标平台的受支持合作伙伴工具 / API，以及 (b) 以公共 API 为目标平台的假设未来公共工具 / API。未来，公开平台和合作伙伴平台的接口可能具有不同的兼容性期限，但这项区分与本文档无关。
如果 SDK 工具没有任何迹象（通过命令行标志、工具本身的命名方式 [例如 foo_internal] 或文档）表明它处于实验阶段，则表示该工具受支持。例如，ffx 工具有几个实验性子命令，不受支持。即使系统声称与特定 ABI 修订版兼容，也不保证不受支持的工具一定能正常运行。
政策
此 RFC 引入了一项要求，即与系统交互时，随 SDK 一起提供的受支持开发者工具必须通过相应 SDK 支持的 ABI/API 与平台进行专有交互。
如果某个工具支持合作伙伴使用，则必须仅使用合作伙伴或公共 ABI / API 进行交互。如果某个工具支持公开使用，则必须仅使用公共 ABI / API 进行交互。受支持的 SDK 工具不得使用内部或实验性 ABI / API。
遵循此规则可确保支持的 SDK 工具与在这些 ABI 和 ABI 的兼容性期限内从主分支或分支开发的所有 Fuchsia 产品兼容。
稳定的开发者工具可以定位到以前的稳定 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构建时头部的修订版本。该工具将向 Fuchsia 目标上的服务报告目标 ABI 修订版。该服务将报告 ABI 是否在受支持的集合中。如果不是，ffx会向用户发出错误，并将用户定向到兼容的ffx版本。随着兼容性强制执行的演变，我们可能需要重新审视此方法的具体细节；短期内，只有静态 ABI 修订版（即在汇编时确定）可用，但从长远来看，系统的不同部分会公开不同的 ABI，我们需要提供更动态的检查。内置的稳定
ffx插件fuchsia.git将使用 build 限制来将其使用的一组 FIDL 定义限制为公共 SDK 和合作伙伴 SDK 中提供的定义。Fuchsia 工具所有者的明确目标是，将打算长期支持的
ffx插件从不稳定的 API 和 ABI 迁移出去。ABI 修订版将纳入到软件包元数据中，以帮助开发者在运行软件包之前确定哪些版本的
ffx与该软件包兼容。我们的目标是将版本标识信息附加到需要此信息的ffx的任何输入。
性能
这些政策不会影响效果。强制执行这些政策可能会影响效果；不过，这属于个别工具的服务质量问题。
工效学设计
这些政策通过明确给定工具何时与给定 Fuchsia 目标兼容，从而改善了工具的人体工学。
向后兼容性
许多现有 SDK 工具都不支持检测或强制执行兼容性保证的机制，并且许多工具都使用不稳定的 API 和 ABI。某些工具需要过渡到长期稳定的 ABI。一如既往，必须谨慎进行过渡，以尽可能减少对用户的干扰。开发者应考虑将其工具使用的不稳定 API 和 ABI 视为稳定 API 和 ABI 的选项，方法是在此类 API 和 ABI 的完整兼容性期限内继续支持它们，并向稳定替代项进行软过渡。
安全注意事项
这些政策没有引入任何已知的安全注意事项。
有时，安全问题可能会导致我们违背兼容性保证。例如，我们可能会发现用于从主机与设备通信的 Overnet 传输存在安全问题。
隐私注意事项
这些政策与收集用户数据无关。
测试
虽然最佳实践是使用测试来确保面向 SDK 的开发者工具遵守这些政策，但本 RFC 并不要求开发者工具这样做。Fuchsia CTF（以前称为 CTS）提供了一种测试机制，部分工具开发者可能希望采用该机制。
文档
应更新工具文档，以提及此政策。
缺点、替代方案和未知情况
一种替代方法是采用兼容性临时解决方法：即，每种工具都提供自己的最低兼容性期限。在实践中，我们发现这种做法会给用户造成很大的困惑，因为用户通常不会单独使用某一款工具。例如，如果 ffx log 有效而 ffx component 无效，用户可能会感到意外。
在先技术和参考文档
许多系统的工具都面临向后兼容性方面的挑战。例如，在 Java 中，字节码会带有类文件版本号标记。JVM 具有一组它可以理解的类文件版本号。过于陈旧的类文件可能无法正常运行。