RFC-0024：强制源代码兼容性

RFC-0024：必需的源代码兼容性
状态	已接受
领域	FIDL
说明	为 FIDL 语言绑定制定源代码兼容性标准，以及完善该标准的流程。
作者	cramertj@google.com
提交日期（年-月-日）	2019-04-02
审核日期（年-月-日）	2019-04-11

摘要

为 FIDL 语言绑定制定源代码兼容性标准，例如 以及完善该标准的过程。

设计初衷

目前，对于由语言生成的代码， 绑定。 它们应符合特定的有线 ABI，除此之外 具有约束力的作者有很大的自由空间来决定 API。 对 FIDL 定义的任何更改都可能导致对 生成的绑定

在实践中，用户期望获得某种“常识”列出 应兼容源代码，例如定义新的顶级类型。 然而，并未明确规定必须做到这一点。 虽然这个案例听起来有点荒唐，但它充分说明了，缺乏 可能会损害用户的预期。 在实践中，添加字段就属于这种情况的真实示例 添加到表中、添加新的 xunion 变体，或向 结构体。 用户有理由预料到这些变化 虽然会破坏源代码，但目前还没有任何标准来指定这一点， 目前的更改会导致一个或多个语言绑定的源代码级中断 （例如，由于 C++ 或 Go 中的位置初始化器，或 Rust）。

此外，FIDL 还提供了许多非常实用的扩展， 曾经因为其 与源代码兼容性互动 例如，向copyclone 不包含标识名。 无法克隆包含任意句柄的类型，因此添加句柄 将阻止其提供 clone 函数（或阻止其提供 以任何频率提供正常运行的克隆函数）。 一项变更，引入了有条件地包含 clone 函数 因缺少句柄而生成的 Rust 绑定已被拒 多次，因为它会影响源代码兼容性。 因此，Fucsia 开发者不得不手动部署 clone 函数，并为 FIDL 生成的类型添加封装容器类型， clone。 本文档提出了一个一致的标准，我们可以据此评估 以便提供更符合人体工程学的功能， 为开发者提供人性化、无样板的体验。

设计

流程

此 FTP 会建立一组初始源代码兼容性限制。 此列表将通过 Fuchsia 源代码树的文档进行跟踪。 必须使用 FTP 添加其他源代码兼容性限制 过程。 为了便于轻松添加与新 API 相关的源代码兼容性规则， 即“向后兼容性”部分部分将 将进行修改以添加引入新的源代码兼容性的建议 限制条件（如果适用）。

定义：源代码兼容性和可转换性

以下更改必须与源代码兼容 （即非破坏源代码）或可转换。

与源代码兼容的更改不得导致任何有效的源代码中断 （编译）生成的 FIDL 绑定的公共 API 的使用。 对于 Responsible AI 的定义和可行性， 限制哪些功能属于“公共 API”，哪些不属于； 因此在本文中，我们将“公共 API”成为 对生成的绑定的任何使用，无需 非同凡响的语言体操（例如反思）或露骨的开发者 侵犯隐私权（例如 __private_dont_use_me_function_2()). 所有其他公开的 API（如位置初始化、模式匹配、 等），这样用户代码就不会被 对 FIDL 库进行源代码兼容的更改。

可转换更改是指可以写入的更改 可在更改前后进行编译的代码。 每条可转换的源代码兼容性规则都必须明确指定 “使用”API 的新版本。

初始源代码兼容性限制

以下是必须与源代码兼容的更改列表：

• 添加新的顶级项（协议、类型或常量）。
  • 动机：用户希望声明新的协议、类型和 常量，且无需破坏 FIDL 的现有用户的 库。
  • 豁免：与“*”的使用或从命名空间进行一揽子导入 因多个项目之间含糊不清而导致网站崩溃 来自多个同名的不同库。
• 将字段添加到非严格表。
  • 动机：表旨在实现易于扩展，并且应 支持更多字段而不会中断。 如需选择启用中断，可以使用 strict 修饰符。
• 将变体添加到非严格可扩展联合体。
  • 动机：可扩展联合的设计目标是易于扩展 并且应支持其他变体而不出现中断。 如需选择启用中断，可以使用 strict 修饰符。
• 将成员添加到非严格枚举 <ph type="x-smartling-placeholder">
  </ph>
  • 动机：非严格枚举隐式选择启用可扩展性 且能够在不中断源代码的情况下展开
• 将成员添加到非严格“位” <ph type="x-smartling-placeholder">
  </ph>
  • 动机：非严格位正在隐式选择启用可扩展性 且可在不中断源代码的情况下展开
• 将 [Layout = "Simple"] 添加到现有协议 <ph type="x-smartling-placeholder">
  </ph>
  • 动机：[Layout = "Simple"] 存在以便于在以下位置使用： 简单的 C 绑定 符合要求的现有协议应该不需要中断 源代码更改，以指定可在简单的 C 绑定。
• 将 [MaxHandles] 添加到现有类型 <ph type="x-smartling-placeholder">
  </ph>
  • 动机：[MaxHandles] 的存在是为了提供以下相关信息： 一个类型，以便更宽松地使用。 无需更改破坏性源代码即可指定 某个类型已包含固定最大数量的句柄，并且 最多包含该数量的句柄。

下面列出了必须可以转换的更改：

• 将 [Transitional] 添加到方法中 <ph type="x-smartling-placeholder">
  </ph>
  • 使用：必须能够实现协议并提供 在 和 之前使用同一源代码的方法实现 将 [Transitional] 属性添加到该方法后。
  • 动机：必须能够逐步添加或移除方法 但前提是所有现有实现都可以 逐渐适应了。
• 添加新的 [Transitional] 方法 <ph type="x-smartling-placeholder">
  </ph>
  • 使用：必须能够使用 源代码在添加新的 [Transitional] 之前和之后 方法（不过，API 不需要允许实现该方法） ）。
  • 动机：必须能够逐步添加或移除方法 但前提是所有现有实现都可以 逐渐适应了。
• 移除 [Transitional] 方法 <ph type="x-smartling-placeholder">
  </ph>
  • 使用：必须能够使用 移除 [Transitional] 方法之前和之后的源代码 （不过，API 无需在 过渡期）。
  • 动机：必须能够逐步添加或移除方法 但前提是所有现有实现都可以逐步进行 进行了调整
• 移除非严格表的字段 <ph type="x-smartling-placeholder">
  </ph>
  • 使用：必须能够创建表并访问其字段 （移除的那个除外）之前使用的同一个来源 移除表格字段后生成的报告
  • 动机：表旨在实现易于改进，并且应 支持在不中断的情况下移除。 如需选择启用中断，可以在strict 表格。
• 移除非严格可扩展联合的变体 <ph type="x-smartling-placeholder">
  </ph>
  • 使用：必须能够创建 xunion 并访问其 使用相同来源的变体（移除的那个除外） 移除 xunion 变体前后的对比。
  • 动机：xunions 旨在便于进化，并且应该 支持在不中断的情况下移除。 如需选择启用中断，可以在strict 表格。
• 将类型标记为 strict <ph type="x-smartling-placeholder">
  </ph>
  • 使用：必须能够访问表的所有字段或“位” 以及使用同一来源的枚举或 xunion 的所有变体 添加 strict 之前和之后。
  • 动机：strict 旨在添加到类型声明中 一旦这种类型稳定下来，就可以更深入地推理和 开发工具 不过，这只是一项可转换的更改， 并非非重大更改，因为可扩展类型可能希望 允许访问无法识别的字段或变体。 这些功能不适用于 strict 类型，因为 则无法识别的字段或变体会被拒绝。
• 将 [Transitional] 添加到枚举或位字段的成员 或可扩展联合的变体。
  • 使用：必须能够访问所有非过渡 成员/位/字段/变体并构造 不包含 [Transitional] 值在 和之前使用相同的来源 在引入 [Transitional] 之后。
  • 动机：必须能够逐步移除成员， 字段或变体。
• 添加枚举或位、表字段或变体的新成员 标记为 [Transitional] 的可扩展联合体的一部分。
  • 使用：必须能够访问所有非过渡 成员/位/字段/变体并构造 不包含 [Transitional] 值在 和之前使用相同的来源 。[Transitional]
  • 动机：必须能够逐步添加成员、字段、 或变体。
• 移除枚举或位、表字段或 标记为 [Transitional]. 的可扩展并集 <ph type="x-smartling-placeholder">
  </ph>
  • 使用：必须能够访问所有非过渡 成员/位/字段/变体并构造 不包含 [Transitional] 值在 和之前使用相同的来源 移除 [Transitional] 字段之后。
  • 动机：必须能够逐步移除成员， 字段或变体。

以下是此部分中省略的潜在限制条件 列表中，并附上被略去的理由：

• 在结构体中添加或移除字段（无论是否为默认字段） <ph type="x-smartling-placeholder">
  </ph>
  • 这是一项破坏 ABI 合规性的更改，并需要其他重要的更改 以确保兼容的过渡。 实施此项非破坏性更改需要消除 对某个类型进行“适用于所有字段”式推理， 包括自动推导的方法（例如“此类型是否包含 任何浮点数”）、位置初始化程序和详尽的字段匹配 和施工。
• 添加或移除严格设置字段/变体（无论是否为默认） 表和 xunions <ph type="x-smartling-placeholder">
  </ph>
  • strict旨在启用其他开发者工具， 依赖于“针对所有字段”式对类型进行推理，包括 自动推导方法（例如“此类型是否包含任何浮点数”）， 位置初始化程序，以及详尽的字段匹配和构造。 如果强制进行非破坏性更改，会导致 目的。
• 向未带有如下标记的类型添加包含句柄的字段或变体 [MaxHandles] <ph type="x-smartling-placeholder">
  </ph>
  • 向严格类型或结构体添加字段已经 由于其他原因，会破坏源代码，因此添加一个具有 同样也是一项重大更改，可能会影响 。

实施策略

此 FTP 制定了最初拟定的语言兼容性标准。 系统会提交错误，并将其分配给每个语言绑定的一位作者 确保其语言绑定合规

工效学设计

此变更为源代码设定了明确的标准，使 FIDL 更易于使用 兼容性，允许自动检查以及更方便的手动检查 检查 FIDL 更改”源代码兼容性以及提供 绑定开发者就源代码兼容性提供更清晰的指南，让他们能够 自由地绑定符合语言习惯的绑定， 项目标准要求。

文档和示例

接受此 FTP 后，FTP 之间建立的流程 并且源代码兼容性规则本身也会 以及其他 FIDL 参考文档。

向后兼容性

应用所提议的指导原则可能需要更改绑定和 则由相应的绑定作者决定 应该能够轻松应对此类更改

本部分（“向后兼容性”部分）将进行修正， 包含以下文本：

“如果要引入新的数据类型或语言功能，请考虑 您希望用户在不更改 FIDL 定义的情况下 来破坏用户生成的代码 如果您的功能放置了任何新的源代码兼容性， 请在此处列出针对生成的语言绑定的限制。

请注意，您应添加源代码兼容性文本作为实际 此 FTP 的链接，即：

[source compatibility](/docs/contribute/governance/rfcs/0024_mandatory_source_compatibility.md)

性能

尽管 源代码 API 可能会导致语言绑定作者多或少地设计 高性能 API 使用支持的语言创建高性能绑定的可行性 在存在新的源代码兼容性限制时，应考虑 。

由于推送内容，此功能可能会影响编译时性能 面向需要大量内联和编译器优化的模式 为了提高性能（例如，优化了复杂的构建器 API 简单的结构体初始化）。 绑定设计作者应尽量做出 会显著限制编译时间， 特定语言 API 不一定会妨碍引入 新的源代码兼容性限制。

安全

此功能不会影响安全性。

测试

许多源代码兼容性规则都采用如下形式：“ “ 很遗憾，这些限制很难或无法测试 因为这样需要枚举 API 的所有可能用法 更改之前

不过，我们可以（并且应该）向 FIDL 变更测试添加项目 以表明确实存在某种 API。 这是满足来源的必要但非充分条件 兼容性要求。

缺点、替代方案和未知问题

• 不要引入这样的规范。 允许绑定作者选择 希望更改的内容 这与目前的法律规定大致相似 约束的作者拥有更大的灵活性， 当前系统，其中一些源代码兼容性和恶意更改 收到回复。
• 创建允许更改的规范 而不是不允许 来破坏源代码 这一要求更难执行，并且需要约束作者 预测其绑定必须保持不变的变化 与源代码兼容。
• 您可以稍作修改，例如同时指定是和 不是，并且未指定任何更改，默认采用一种方式， 本质上与此 FTP 或上述替代方案相同 取决于默认值，虽然它设定了更正式的期望值， 以及记录不同 FIDL 变更的影响。

先验技术和参考资料

之前尝试引入进化性限制 通过 [MaxHandles] 属性指定。 该设计及其预期修改已在 该提案的早期部分中