ABI のバージョン管理
C++ ドライバーは、安定性を定義するための Ulridge Docker のガイド 、Linux 共有ライブラリの "sonname" 規則、および ABI バージョン管理用の CMax SOVERSIONターゲット プロパティを使用します。
Per Ulrich Drepper:
したがって、安定性の定義では、文書化されたインターフェースを基に使用する必要があります。 インターフェースの正規使用は、 実装の変更の影響を受けないようにしてください。インターフェースを未定義の方法で使用する場合、保証が無効になります。 完全にドキュメント化されていない内部記号 を使用する場合も同様です。 これらは絶対に使用しないでください。
すべての共有ライブラリには、「`sonname」と呼ばれる特別な名前が付けられています。 ソー名には、プレフィックス「`lib」、ライブラリの名前、「」というフレーズがあり、 その後にピリオドと、インターフェースが変更されるたびに増加するバージョン番号（特別な例外として、最低レベルの C ライブラリは ``lib` では起動しません）。 完全修飾ソー名には、それが含まれているディレクトリのプレフィックスとして が含まれます。ワーキングシステムでは、完全修飾のソー名は、共有ライブラリの「実際の名前」へのシンボリック リンクに相当します。
共有ライブラリの場合、
VERSIONとSOVERSIONを使用してそれぞれビルドバージョンと ABI バージョンを指定できます。 ビルドまたはインストール時に、プラットフォームがシンボリック リンクをサポートし、リンクがソー名をサポートしている場合は、適切なシンボリック リンクが作成されます。 両方のうち 1 つだけが指定されている場合、欠落している は同じバージョン番号を持つと見なされます。*
ABI のバージョン管理では、安定した ABIと不安定な ABIを区別します。
以下で定義されているように、安定版 ABI の下位互換性のない変更が行われるたびに、ABI のバージョン番号がダンプされます。
重要
安定版 ABI の安定性のみが ABI バージョン番号によって伝達されます。 不安定な ABI に対する下位互換性のない変更は、ABI バージョン番号では伝達されません。
注意
ABI バージョン管理ポリシーは、共有ライブラリにのみ適用されます。 静的ライブラリには適用されません。
バイナリ互換性
ABI 名前空間はライブラリのルート名前空間内で宣言され（ ソースの互換性を参照）、文字vを先頭に、整数または_noabiのいずれかが続きます。
ABI 名前空間の例には（グローバル名前空間スコープに対して相対的）次のものが含まれます。
bsoncxx::v_noabibsoncxx::v1bsoncxx::v2bsoncxx::v99
不安定な ABI 名前空間は、 v_noabiという名前の名前空間です。 その他の ABI 名前空間は、安定した ABI 名前空間です。 ルート名前空間は ABI 名前空間ではありません。
Stable ABIは、パブリック API によって使用され、安定した ABI 名前空間で宣言されたエクスポートされたシンボルのセットです。ただし、次の例外があります。
シンボルまたは対応するパブリック API エンティティは、実験的なものであるか、ABI 安定性のためにまだ準備ができていないことが明示的に文書化されています。
エンティティは、ABI 名前空間内で宣言されていません。
これらの例外を含め、他のすべてのエクスポートされたシンボルは、不安定な ABIの一部と見なされます。
対応する API エンティティがエクスポート マイクロで明示的に宣言されているシンボルのみがエクスポートされます。これは CXX_VISIBILity_PRESet によって制御されます。 ターゲット プロパティ。さらに、明示的に（例: inline inlineと）または暗黙的に（例: クラス定義内のノード関数の定義、変数や関数のテンプレートのインスタンス化など）はエクスポートされ ません 。これは、 VISIBILity_INLineS_HIDDN によって制御されるためです。 ターゲット プロパティ。
エクスポートする必要があるシンボル、または安定版 ABI の一部であるが現在はエクスポートできないシンボルがある場合は、バグレポートを送信してください。
重要
パブリック API をバイパスするエクスポートされたシンボルの直接使用はサポートされていません。 エクスポートされたすべてのシンボル（安定または不安定）は、パブリック API 経由で使用する必要があります。 エクスポートする必要があるシンボル、または安定版 ABI の一部であるが現在はエクスポートできないシンボルがある場合は、バグレポートを送信してください。
重要
安定版 ABI の一部と見なされるには、シンボルがパブリック API（間接的に）で使用されるだけで済みます。 以前のリリースでパブリック API エンティティによって使用されたことがないエクスポートされたシンボルは、安定版 ABI の一部とは見なされません（上記の注を参照）。
重要
安定性のある ABI シンボルの動作も、安定性のある ABI の一部です。 これは、同じ ABI バージョン番号を持つ共有ライブラリ間で、一貫性と互換性のあるランタイム動作を確保するためのものです。 The behavior must be consistent with the documentation of one or more public API entities that uses the symbol (even indirectly) such that there is no observable change in public API behavior (within the scope of what is explicitly documented) across releases with the same ABI version number.
注意
パブリック API の一部である一部のエンティティは、安定版 ABI の一部ではない場合があります（例: インライン関数、インライン変数、関数と変数のテンプレートインスタンス化）。 逆に、安定版 ABI の一部であるエンティティは、パブリック API の一部ではない場合もあります（例: エクスポートされたプライベート メンバー関数）。 「 API バージョン管理 」を参照してください。
ビルド システムの互換性
ビルドシステムのプロパティに関する安定した ABI ポリシーは、パブリック API のそれとほとんど同じ（ API ビルド システムの互換性を参照）ですが、次の違いがあります。
パブリック API に直接影響するプロパティの代わりに、安定性のある ABI に直接影響するプロパティは、安定性のある ABI の一部と見なされます。
ソー名は、安定版 ABI の一部と見なされます。 つまり、パブリック API とは対照的に、
BSONCXX_OUTPUT_NAMEは結果として得られる bsoncx 共有ライブラリのソー名に直接影響するため、安定版 ABI の一部と見なされます。"sonname" は Windows では適用されません。 「共有ライブラリ（MSV のみ） 」を参照してください。
注意
ビルド構成 ごとの Stable API の安定性をサポートします。 異なるビルド構成間での Stable API の互換性はサポートされていません。 たとえば、 BSONCXX_OUTPUT_NAME=bsoncxxで生成された共有ライブラリは、 BSONCXX_OUTPUT_NAME=bsoncxx-custom-basenameのビルド構成を使用して生成された安定版 ABI に対してコンパイルされたプログラムと互換性がありません。 （Visual Studio などの複数構成のジェネレーターを使用する場合、特に重要です）
ルート名前空間の再宣言
ルート名前空間は、ABI 名前空間で宣言されたエンティティの「再宣言」を提供します。 ABI 名前空間は、再定義されるエンティティによって異なる場合があります。
たとえば、次のすべての再アクセスが同時に存在する可能性があります。
bsoncxx::example::foo-->bsoncxx::v_noabi::example::foobsoncxx::example::bar-->bsoncxx::v1::example::barbsoncxx::example::baz-->bsoncxx::v2::example::baz
ルート名前空間の再宣言は、 vAシンボルのバイナリ互換性を損なうことなく、 vBにバイナリ互換性のないシンボルを追加できるように設計されています。 安定した ABI シンボルの非推奨を容易にしながら、バイナリ互換性を損なうことなくvAからvBにクリーンに移行する機会を提供します。 これにより、ユーザー コードはvAからvBに移行するときにソースコードに必要な変更を減らす「再宣言アップグレード」を選択できるようになります。
これらの冗長化アップグレードは、リリース間で非推奨で削除される ABI シンボルからのクリーンな移行をサポートすることを目的としています。 したがって、これらのアップグレードを選択するために、ユーザーはデフォルトでルート名前空間宣言を使用することをお勧めします。 ただし、ユーザーは、独自の安定性ポリシーに応じて、安定型 ABI で C++ ドライバー エンティティを参照するときに明示的な ABI 名前空間修飾子を使用する必要がある場合があります。
次の互換性テーブルでは、互換性のない変更のために API メジャー バージョン番号または ABI バージョン番号をアップグレードする必要がある場合について説明しています。
タイプの変更 | ソース互換 | バイナリ互換 |
Add a new vB symbol | はい | はい |
リテラル化を vAからvBにアップグレードします | あるいは[ 1 ] | はい |
vA記号を削除します（公開 API から） | No | あるいは[ 2 ] |
vA記号（安定版 ABI から）を削除する | あるいは[ 2 ] | No |
| [1] | vBエンティティは、互換性のない新しい安定版 ABI シンボルを使用する必要があるにもかかわらず、 vA API と互換性のある100 % ソースになる可能性があります。 |
| [2] | （ 1 、 2 ）安定した ABI シンボルをパブリック API から削除することができました（例: ドキュメントの作成やパブリック ヘッダーの削除など）、下位互換性のためにエクスポートされたシンボル定義を引き続き提供します。 This is probably unlikely to happen, but if it does, it would be a rare case where the source and binary incompatible changes can be split into separate releases. |
重要
ABI 名前空間で使用される整数は、ABI バージョン番号に直接対応することはありません。 ABI のバージョン番号は、安定した ABI から1 つのシンボルを削除する場合でも、バイナリと互換性のない変更が発生するたびにアップグレードされます。 ABI バージョン番号がAからBに引き上げられても、ABI 名前空間vAで宣言されたシンボルの非推奨または削除は意味されません（存在する場合）。
非推奨と削除
安定版 ABI の非推奨とシンボル削除のポリシーは、公開 API のポリシーと同じです。 詳細については、「 API の廃止と削除 」を参照してください。
バイナリ互換性のない変更を含むリリースでは、API メジャー バージョン番号ではなく、ABI バージョン番号が使用されます。 ただし、ABI のバージョン番号がアップグレードされると、API メジャーのバージョン番号もアップグレードされる可能性が高く、バイナリ互換性のない変更はソースも互換性のない変更になる可能性があるためです。