API と ABI のバージョン管理
簡潔にするために、このページでは bsoncx ライブラリにのみ適用される場合は、プロパティと機能を説明する場合があります。 特に指定がない限り、説明されているプロパティと機能は mongocx ライブラリにも同様に適用されると想定される場合があります。
API のバージョン管理
ABI のバージョン管理
ヘッダー ファイルの構造
bsoncx ライブラリの公開ヘッダー ファイルは、ABI 名前空間によって整理されています。
${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}/ └── bsoncxx/ ├── v_noabi/bsoncxx/ │ └── ... ├── v1/bsoncxx/ │ └── ... ├── v2/bsoncxx/ │ └── ... └── vN/bsoncxx/ └── ...
上位互換性のために、ABI名前空間ディレクトリ vA内の公開ヘッダーファイルには、新しいABI名前空間ディレクトリvBにヘッダーファイルを含めることができます。ここでは、 A < Bが となります。 このような上位互換性が含まれるディレクティブは、サポートされている場合は明示的にドキュメント化されます。 ABI の安定性が必要な場合は、最新の安定した ABI名前空間ディレクトリのヘッダーを含めることをお勧めします。 ABI 安定性が必要ない場合は、代わりに適切な不安定ABI ヘッダーを含めることをお勧めします。
重要
bsoncxx/v_noabi/不安定 ABI名前空間ディレクトリは、インクルージョン パスのbsoncxx/ルートディレクトリよりも優先され、 #include <bsoncxx/example.hpp>は#include <bsoncxx/v_noabi/bsoncxx/example.hpp>と同等になります。
注意
ドキュメントされていない include ディレクティブの安定性はサポートされていません。
パッケージ ファイルは${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/のサブディレクトリにインストールされます。 bsoncx ライブラリ ヘッダー（およびコンパイル フラグのリンクと設定）を取得するために、これらのパッケージ ファイルを使用することを強くお勧めします。 bsoncx ヘッダー ファイルを取得するためのインクルージョン パスの手動設定は推奨されません。 パッケージ ファイルについて詳しくは、以下をご覧ください。
いずれの場合も、 C++ ドライバー ライブラリをインポートするには、CMax パッケージ構成ファイルが推奨されます。
ライブラリ ファイル名
シンボリック リンクのファイル名と存在は、ライブラリのビルドに使用されるプラットフォームとツールチェーン、およびライブラリのタイプ（共有と静的）によって異なります。
共有ライブラリ
重要
Windows 上の MSV ツールチェーンで構成されている Windows 上の共有ライブラリは、Windows 固有の特別な考慮事項により、異なる方法で処理されます。 以下の共有ライブラリ（MSV のみ）を参照してください。
共有ライブラリの「実際の名前」は、次のパターンを使用します。
lib<basename>.so.<api-version-number>
以下の条件に一致するもの。
<basename>は、BSONCXX_OUTPUT_BASENAMECSpec 構成変数（mongocx ライブラリの場合はMONGOCXX_OUTPUT_BASENAME）に対応します。 デフォルトでは、これはbsoncxxとmongocxxに設定されています。 静的ライブラリのベース名には-staticが付きます。<api-version-number>は、BUILD_VERSIONCMax 構成変数に対応する、特定のビルド構成の MAJOR、MINOR、PATCH バージョンです。 （注: この構成変数を明示的に設定する必要は、C++ ドライバーの通常の使用では必要ありません。）API バージョン番号の拡張子は実際の名前には含まれ
-alpha1.2.3-alphaません （例: の ）。
予想されるライブラリの実際名の例は次のとおりです。
libbsoncxx.so.1.0.0 libbsoncxx.so.2.3.4
CSpec のSOVERSIONターゲット プロパティと「namelink」動作は、Linux のソー名規則に準拠したライブラリ ディレクトリへのシンボリック リンクもインストールします。 これらのシンボリック リンクには、ライブラリのソー名の一部として ABI バージョン番号が含まれます。
たとえば、次の lib ディレクトリには、API バージョン1.2.3と ABI バージョン10の bsoncx ライブラリに必要なライブラリ ファイルが含まれています。ここで、 a -> bはaがbへのシンボリック リンクであることを示します。
${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/ ├── libbsoncxx.so.1.2.3 ├── libbsoncxx.so.10 -> libbsoncxx.so.1.2.3 ├── libbsoncxx.so -> libbsoncxx.so.10 ├── cmake/bsoncxx-1.2.3/ │ ├── bsoncxx-config.cmake │ └── ... └── pkgconfig/ └── libbsoncxx.pc
bsoncx ライブラリの CSpecパッケージの名前は BSONCXX_OUTPUT_BASENAME によって制御されます（ mongocx ライブラリの場合は MONGOCXX_OUTPUT_BASENAME）。CSpec のコンフィギュレーションモード検索手順 に従ってインポートする必要があります。例、 C++ドライバーがプレフィックス $INSTALLDIR にインストールされていると仮定します。
# The CMake package may be imported via CMAKE_PREFIX_PATH (recommended)... cmake -S example -B example-build -D CMAKE_PREFIX_PATH="$INSTALLDIR" # Or via <PackageName>_ROOT (assuming BSONCXX_OUTPUT_NAME=bsoncxx)... cmake -S example -B example-build -D bsoncxx_ROOT="$INSTALLDIR" # Or via ``PATHS`` in the ``find_package()`` command... or etc. # find_package(bsoncxx CONFIG REQUIRED PATHS "$INSTALLDIR")
注意
C ドライバーは、C++ ドライバーの必須依存関係です。 この依存関係を満たすには、C ドライバーの CSpec パッケージ構成ファイルも同じ（または同様）アプローチでインポートする必要がある場合があります。
C++ ドライバーは pkg-config ファイルも提供しますが、代わりに CSpec パッケージ 構成ファイルを使用することを強くお勧めします。
bsoncx ライブラリの pkg 構成ファイルの名前もBSONCXX_OUTPUT_NAMEによって制御され、パターンlib<basename>.pcに従います。 pkg-config の検索パスを増やすには、 PKG_CONFIG_PATH環境変数を使用する必要がある場合があります。例:
bsoncxx_cflags="$(PKG_CONFIG_PATH="$INSTALLDIR" pkg-config --cflags "libbsoncxx >= 1.2.3")" bsoncxx_ldflags="$(PKG_CONFIG_PATH="$INSTALLDIR" pkg-config --libs "libbsoncxx >= 1.2.3")" g++ $bsoncxx_cflags -c example-a.cpp g++ $bsoncxx_cflags -c example-b.cpp g++ $bsoncxx_ldflags -o example example-a.o example-b.o
共有ライブラリ（MSV のみ）
バージョン3.10.0以降、Windows の MSV ツールチェーンを使用してビルドされた共有ライブラリは（CSpec ジェネレーターが Visual Studio でない場合でも）、他のプラットフォームとは異なる命名スキームを使用します。 他のプラットフォームと同様の以前の動作を復元するには、 ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES=OFFを設定します。
共有ライブラリの名前（「出力名」とも）には、次のパターン（ファイル拡張子は除外）が使用されます。
<basename>-v<abi-version-number>-<abi-tag>
以下の条件に一致するもの。
<basename>は、BSONCXX_OUTPUT_BASENAMECSpec 構成変数（mongocx ライブラリの場合はMONGOCXX_OUTPUT_BASENAME）に対応します。 デフォルトでは、これはbsoncxxとmongocxxに設定されています。 静的ライブラリのベース名には-staticが付きます。<abi-version-number>は、現在の ABI バージョン番号に対応します。<abi-tag>は、共有ライブラリのバイナリ互換性に影響を与える既知のプロパティについて説明します。
<abi-tag>は、次の要素を含む 3 文字のコレクションです。
ビルド タイプ
mongoc リンク タイプ
ポリゴン ライブラリ
これには、ライブラリの構築に使用されるツールセットとランタイム ライブラリを説明するサフィックスが続きます。 サフィックスの正確な内容は、ビルド構成によって異なります。
予想されるライブラリ ファイル名の例（注目すべき機能を簡単に説明します）の例は次のとおりです。
bsoncxx-v_noabi-rhs-x64-v142-md.dll（ビルド構成のリリース）bsoncxx-v_noabi-dhs-x64-v142-mdd.dll（デバッグ ビルド構成）bsoncxx-v_noabi-rts-x64-v142-md.dll（mongoc 静的ライブラリとのリンク）bsoncxx-v_noabi-rhi-x64-v142-md.dll（polyfill ライブラリとしての bsoncx）bsoncxx-v_noabi-rhm-x64-v142-md.dll（polyfill ライブラリとしての mnstc/core）bsoncxx-v_noabi-rhb-x64-v142-md.dll（ポリゴン ライブラリとしてブースト）bsoncxx-v1-rhs-x64-v142-md.dll（ABI バージョン番号1 ）bsoncxx-v2-rhs-x64-v142-md.dll（ABI バージョン番号2 ）
注意
この例は、コンフィギュレーション ファイルである.libファイルにも適用されます。
この命名スキームにより、bsoncx ライブラリをさまざまなビルド構成でビルドおよびインストールできます（例: デバッグとリリース）および異なるランタイム ライブラリの要件（例: MultiThreadedDll と MultiThreadedDebugDll) は競合することなく並列に実行されます。 詳しくは、 CSpec 構成内のENABLE_ABI_TAG_IN_LIBRARY_FILENAMESおよび関連コードへの参照を参照してください。
たとえば、次のインストール プレフィックス ディレクトリには、API バージョン1.2.3と ABI バージョン10の bsoncx ライブラリの予想されるデバッグとリリース ライブラリ ファイルが含まれています（bin ディレクトリは.dllファイルを考慮するために含まれています）。
${CMAKE_INSTALL_PREFIX}/ ├── ${CMAKE_INSTALL_BINDIR}/ │ ├── bsoncxx-v10-dhs-x64-v142-mdd.dll │ └── bsoncxx-v10-rhs-x64-v142-md.dll └── ${CMAKE_INSTALL_LIBDIR}/ ├── bsoncxx-v10-dhs-x64-v142-mdd.lib ├── bsoncxx-v10-rhs-x64-v142-md.lib ├── cmake/bsoncxx-1.2.3/ │ ├── bsoncxx-config.cmake │ └── ... └── pkgconfig/ ├── libbsoncxx-v10-dhs-x64-v142-mdd.pc └── libbsoncxx-v10-rhs-x64-v142-md.pc
CSpec パッケージの構成ファイルは、上記で説明した通常の（MSBC 以外）共有ライブラリの動作と同じです。
注意
CSpec はビルド タイプに応じてライブラリの選択を自動的に処理しますが、ビルド タイプが 1 つだけインストールされている場合は、ビルド タイプの整合性を強制しません。 このため、Windows にデバッグ構成とリリース構成の両方をインストールすることを強くお勧めします。 （このメモは ビルドタイプ構成パラメーターにのみ適用されます）。
C++ ドライバー ライブラリの pkg 構成ファイルの名前は、上記で説明した通常の（MSBC 以外）共有ライブラリの動作と同じです。 ただし、 ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ONの場合、ライブラリ出力名は pkg 構成ファイルのベース名であるかのように使用されます。 たとえば、共有ライブラリbsoncxx-v_noabi-rhs-x64-v142-md.dllのフラグを取得するには、 ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=OFF （デフォルト）の場合に pkg-config コマンドは次のようになります。
pkg-config --cflags "libbsoncxx"
または、 ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ONの場合は次のようになります。
pkg-config --cflags "libbsoncxx-v_noabi-rhs-x64-v142-md"
異なるビルド構成を持つ C++ ドライバー ライブラリを並行してインストールする場合は、 ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ONを設定することをお勧めします（例: デバッグとリリース）が予想されます。 ただし、代わりに Cake パッケージの構成ファイルを使用することをお勧めします。
静的ライブラリ
静的ライブラリは単純なファイル名パターンを使用します。
lib<basename>-static.a
静的ライブラリ ファイルの名前には、API または ABI のバージョン情報は含まれません。 CSpec パッケージ構成ファイルの共有ライブラリ選択と静的ライブラリの選択は、CSpec ターゲットを介して処理されます。 pkg 構成ファイルの共有ライブラリ選択と静的ライブラリ選択は、ライブラリのベース名に-staticサフィックスを追加することで処理されます。例: lib<basename>-static.pc 。
たとえば、次のライブラリ ディレクトリには、bsoncx ライブラリに予想される共有ライブラリ ファイルと静的ライブラリ ファイルが含まれています。
${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/ ├── libbsoncxx.so.1.2.3 ├── libbsoncxx.so.10 -> libbsoncxx.so.1.2.3 ├── libbsoncxx.so -> libbsoncxx.so.10 ├── libbsoncxx-static.a ├── cmake/bsoncxx-1.2.3/ │ ├── bsoncxx-config.cmake │ └── ... └── pkgconfig/ ├── libbsoncxx.pc └── libbsoncxx-static.pc
静的ライブラリ（MSV のみ）
静的ライブラリの名前は、上記で説明した MSVstatic 共有ライブラリの動作と同じパターンを使用しますが、<abi-version-number> としては を使用し、ライブラリの出力名はベース名のように使用します。
たとえば、次のインストール プレフィックス ディレクトリには、bsoncx ライブラリに予想される共有ライブラリ ファイルと静的ライブラリ ファイルが含まれています（ .dllファイルを考慮するためにbin ディレクトリが含まれています）。
${CMAKE_INSTALL_PREFIX}/ ├── ${CMAKE_INSTALL_BINDIR}/ │ └── bsoncxx-v10-rhs-x64-v142-md.dll └── ${CMAKE_INSTALL_LIBDIR}/ ├── bsoncxx-v10-rhs-x64-v142-md.lib ├── bsoncxx-static-dhs-x64-v142-mdd.lib ├── cmake/bsoncxx-1.2.3/ │ ├── bsoncxx-config.cmake │ └── ... └── pkgconfig/ ├── libbsoncxx-v10-rhs-x64-v142-md.pc └── libbsoncxx-static-rhs-x64-v142-md.pc