V8 的公開 API

本文探討 V8 公開 API 的穩定性，以及開發人員如何對其進行變更。

API 穩定性 #

如果 Chromium Canary 中的 V8 發生崩潰，它會回滾到前一個 Canary 的 V8 版本。因此，保持 V8 的 API 從一個 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_DEPRECATED 可以使用 v8_deprecation_warnings GN 旗標進行測試。
  V8_DEPRECATE_SOON 可以使用 v8_imminent_deprecation_warnings 進行測試。

• 變更函式簽章是不安全的。請如上所述使用 V8_DEPRECATED 和 V8_DEPRECATE_SOON 巨集。

我們維護一份 文件，其中提到每個 V8 版本的重要 API 變更。

還有一個定期更新的 doxygen api 文件。