V8 の公開 API

このドキュメントでは V8 の公開 API の安定性と、開発者がどのように変更を加えられるかについて説明します。

API の安定性 #

Chromium Canary の V8 がクラッシュしやすいことが判明した場合、前の Canary の V8 バージョンにロールバックされます。したがって、1 つの Canary バージョンから次の Canary バージョンに変更しても V8 の API 互換性を保つことが重要です。

現在、API の安定性の違反を通知する ボット を継続的に実行しています。Chromium の HEAD を V8 の 現在の Canary バージョン でコンパイルします。

このボットの障害は現在 FYI としてのみ使用されており、何らかのアクションが必要になることはありません。ロールバック時に依存する CL を簡単に特定するために、責任者リストを使用することができます。

このボットを停止した場合、次回 V8 の変更と依存する Chromium の変更の間の期間を長くすることを思い出してください。

V8 の公開 API を変更する方法 #

V8 は Chrome、Node.js、gjstest など、さまざまなエンベッダーによって使用されています。V8 の公開 API（基本的に include/ ディレクトリ以下のファイル）を変更する際は、エンベッダーが新しい V8 バージョンにスムーズに更新できることを確認する必要があります。特に、エンベッダーが新しい V8 バージョンにアップデートして、1 つの原子的な変更で新しい API にコードを調整することは想定できません。

エンベッダーは、以前のバージョンの V8 を使用したままコードを新しい API に調整できる必要があります。以下のすべての手順は、このルールに従います。

• 新しいタイプ、定数、関数の追加は、1 つの注意点に留意すれば安全です。既存のクラスに新しい純粋仮想関数を追加しないでください。新しい仮想関数には、デフォルトの実装が必要です。

• パラメーターにデフォルト値がある場合は、関数の新しいパラメーターを追加しても安全です。

• エンベッダーが非推奨メソッドを呼び出したときにコンパイル時に警告が発生する V8_DEPRECATED マクロと V8_DEPRECATE_SOON マクロを使用してください。たとえば、関数の foo を関数の bar に名前変更したいとします。次に、以下を実行する必要があります。

  • 新しい関数 bar を既存の関数 foo の近くに追加します。
  • CL が Chrome にロールインするまで待ちます。Chrome を調整して bar を使用します。
  • foo に V8_DEPRECATED("Use bar instead") void 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 ドキュメント もあります。