| 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 修订版本推出后的指定时间长度（或兼容性窗口）内支持 ABI 修订版本。（即将发布的 RFC 将阐述一项新政策，说明我们如何确定兼容性期的长度。）因此，在兼容期内，该组件将与新的 Fuchsia build 兼容。
对于与 Fuchsia SDK 一起发布的工具，没有类似的兼容性概念，这些工具目前具有临时兼容性机制，这些机制主要反映了特定团队和开发者的意图。该 RFC 解决了这一缺点。
工具和组件之间的不匹配可能会让用户感到非常沮丧。许多 Fuchsia 用户是将产品软件包与工具分开下载。这会导致开发者使用的工具支持的 ABI 与他们尝试监控和管理的产品支持的 ABI 不同。这会导致开发者发现难以诊断和解决的错误。
在此 RFC 中，我们设定了一项初始政策，规定工具何时与指定的 Fuchsia 软件包搭配使用，并说明了我们计划采取哪些措施来强制执行和传达此政策。因此，此政策并非详尽无遗。还有一些 SDK 工具兼容性问题在这里未予以说明，例如对命令行选项生命周期的保证，或工具与旧版 C/C++/FIDL 头文件的兼容性。
利益相关方
教员：
阿巴斯
审核者：
abarth（版本控制，Fucsia 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 和工具。它们在公共 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 产品或者通过在兼容性期内开发的分支开发的所有 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 工具所有者可能会决定在开发过程中通过测试和构建支持等机制来强制执行兼容性要求。这些强制执行机制将来可能会成为 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 和合作伙伴 SDK 中提供的那些定义。Fuchsia 工具所有者的明确目标就是将旨在长期支持的
ffx插件从不稳定的 API 和 ABI 中迁出。ABI 修订版本将包含在商品软件包元数据中，以帮助开发者在运行该软件包之前确定哪些版本的
ffx支持该软件包。我们的目标是将版本标识信息附加到需要具有版本标识信息的ffx输入中。
性能
这些政策不会影响性能。强制执行这些政策可能会影响性能；但是，对于单个工具来说，存在服务质量问题。
工效学设计
这些政策可以明确指定工具何时与指定的 Fuchsia 目标兼容，从而提高工具工效学设计。
向后兼容性
许多现有的 SDK 工具都不支持用于检测或强制执行兼容性保证的机制，并且许多工具使用非稳定的 API 和 ABI。某些工具需要过渡到长期稳定的 ABI。与往常一样，您必须谨慎完成转换，以最大限度减少对用户的干扰。开发者应考虑是否将其工具使用的不稳定 API 和 ABI 视为稳定版，方法是在完整兼容性期限内继续支持该 API 和 ABI，并执行软过渡到稳定版替代项。
安全注意事项
这些政策未引入任何已知的安全考虑因素。
有时，安全问题可能需要我们破坏兼容性保证。例如，我们用于从主机到设备通信的 Overnet 传输层可能存在安全问题。
隐私注意事项
这些政策与用户数据的收集无关。
测试
尽管最佳实践是使用测试来确保面向 SDK 的开发者工具遵守这些政策，但此 RFC 并不要求使用开发者工具这样做。Fuchsia CTF（以前称为 CTS）提供了一种测试机制，某些开发者可能希望采用这些工具。
文档
应更新工具文档以引用此政策。
缺点、替代方案和未知情况
一种替代方案是临时兼容性方法：也就是说，每个工具都提供自己的最小兼容性窗口。在实践中，我们发现这样做会让用户非常困惑，因为用户通常不会孤立地使用单一工具。例如，如果 ffx log 有效而 ffx component 无效，用户可能会感到惊讶。
早期技术和参考资料
许多系统的工具都面临向后兼容性挑战。例如，在 Java 中，字节码使用类文件版本号进行标记。JVM 具有一组它理解的类文件版本号。足够旧的课程文件可能无法正常使用。