メインコンテンツまでスキップ

V8のパブリックAPI

このドキュメントでは、V8のパブリックAPIの安定性と、開発者がそれに変更を加える方法について説明します。

APIの安定性​

Chromiumのカナリア版でV8がクラッシュする場合、以前のカナリア版のV8バージョンにロールバックされます。そのため、V8のAPIをカナリア版間で互換性がある状態に保つことが重要です。

私たちは常にボットを実行しており、APIの安定性違反を検出します。このボットはChromiumのHEADをV8の現在のカナリア版バージョンでコンパイルします。

このボットの失敗は現時点で単なるFYIであり、特に対応は必要ありません。ロールバックの場合に依存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を追加します。
    • ChromeにCLがロールインするまで待ちます。Chromeを調整してbarを使用するようにします。
    • fooをV8_DEPRECATED("代わりにbarを使用してください") 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ドキュメントもあります。