V8 的公共 API

本文档讨论了 V8 公共 API 的稳定性，以及开发者如何对其进行更改。

API 稳定性 #

如果 Chromium canary 中的 V8 出现崩溃，则会回滚到之前 canary 版本的 V8 版本。因此，保持 V8 的 API 从一个 canary 版本到下一个 canary 版本的兼容性非常重要。

我们持续运行一个 机器人，它会发出 API 稳定性违规的信号。它使用 V8 的 当前 canary 版本 编译 Chromium 的 HEAD。

该机器人的故障目前仅供参考，不需要采取任何措施。在回滚的情况下，可以利用责任列表轻松识别依赖的 CL。

如果您破坏了这个机器人，请记住下次在 V8 更改和依赖的 Chromium 更改之间增加时间间隔。

如何更改 V8 的公共 API #

V8 被许多不同的嵌入器使用：Chrome、Node.js、gjstest 等。在更改 V8 的公共 API（基本上是 include/ 目录下的文件）时，我们需要确保嵌入器可以顺利更新到新的 V8 版本。特别是，我们不能假设嵌入器会更新到新的 V8 版本并在一个原子更改中调整其代码以适应新的 API。

嵌入器应该能够在仍然使用旧版本的 V8 的情况下调整其代码以适应新的 API。以下所有说明都遵循此规则。

• 添加新的类型、常量和函数是安全的，但有一个例外：不要向现有类添加新的纯虚函数。新的虚函数应该有默认实现。

• 如果参数具有默认值，则向函数添加新参数是安全的。

• 删除或重命名类型、常量、函数是不安全的。使用 V8_DEPRECATED 和 V8_DEPRECATE_SOON 宏，当嵌入器调用已弃用的方法时，这些宏会导致编译时警告。例如，假设我们想要将函数 foo 重命名为函数 bar。那么我们需要执行以下操作

  • 在现有函数 foo 附近添加新的函数 bar。
  • 等待 CL 在 Chrome 中滚动。调整 Chrome 以使用 bar。
  • 使用 V8_DEPRECATED("Use bar instead") void foo(); 对 foo 进行注释。
  • 在同一个 CL 中，调整使用 foo 的测试以使用 bar。
  • 在 CL 动机中写入更改和高级更新说明。
  • 等待下一个 V8 分支。
  • 删除函数 foo。

  V8_DEPRECATE_SOON 是 V8_DEPRECATED 的一个较柔和的版本。Chrome 不会因其而中断，因此不需要步骤 b。V8_DEPRECATE_SOON 不足以删除函数。

  您仍然需要使用 V8_DEPRECATED 进行注释，并在删除函数之前等待下一个分支。

  可以使用 v8_deprecation_warnings GN 标志测试 V8_DEPRECATED。
  可以使用 v8_imminent_deprecation_warnings 测试 V8_DEPRECATE_SOON。

• 更改函数签名是不安全的。如上所述，使用 V8_DEPRECATED 和 V8_DEPRECATE_SOON 宏。

我们维护一个 文档，其中提到了每个 V8 版本的重要 API 更改。

还有一个定期更新的 doxygen api 文档。