API 和 ABI 版本控制

在此页面上

API版本控制

ABI 版本控制
头文件结构
库文件名
共享库
共享库（仅限 MSVC）
静态库
静态库（仅限 MSVC）

为简洁起见，此页面可能会将属性和功能描述为仅适用于 bsoncxx 库。除非另有说明，否则可以假定所述属性和功能同样适用于 mongocxx 库。

API版本控制

请参阅 API版本控制。

ABI 版本控制

请参阅ABI 版本控制。

头文件结构

bsoncxx 库的公共头文件按 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> 。

注意

不支持未记录的包含指令的稳定性。

包文件安装到${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/中的子目录。强烈建议用户使用这些包文件来获取 bsoncxx 库标头（以及用于链接和设置编译标志的标头）。不建议手动配置包含路径来获取 bsoncxx 头文件。下面将进一步描述包文件。

在所有情况下， CMake包配置文件都是导入C++驾驶员库的推荐方法。

库文件名

文件名和符号链接的存在与否取决于用于构建库的平台和工具链以及库类型（共享与静态）。

共享库

重要

由于特定于 Windows 的特殊注意事项，在Windows上使用 MSVC 工具链配置的Windows上的共享库会受到不同的对待。请参阅下面的共享库（仅限 MSVC）。

共享库的“真实名称”使用以下模式：

lib<basename>.so.<api-version-number>

其中：

<basename> 对应于BSONCXX_OUTPUT_BASENAME CMake 配置变量（ MONGOCXX_OUTPUT_BASENAME表示 mongocxx 库）。默认设置为bsoncxx和mongocxx 。静态库的基本名称以-static为后缀。
<api-version-number> 是给定构建配置的 MAJOR、MINOR 和 PATCH 版本，对应于BUILD_VERSION CMake 配置变量。（注意：在常规使用 C++ 驱动程序时，无需显式设置此配置变量。）
API版本号扩展名不包含在真实名称中（例如-alpha 中的1.2.3-alpha ）。

预期的图书馆实名示例包括：

libbsoncxx.so.1.0.0
libbsoncxx.so.2.3.4

CMake 的SOVERSION目标属性和“名称链接”行为还用于根据 Linux soname 约定将符号链接安装到库目录。这些符号链接包含 ABI 版本号，作为库 soname 的一部分。

示例，以下 lib目录包含API版本为1.2.3和 ABI 版本为10的 bsoncxx 库的预期库文件，其中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

bsoncxx 库的 CMake包的名称由 BSONCXX_OUTPUT_BASENAME 控制（对于 mongocxx 库，则为 MONGOCXX_OUTPUT_BASENAME）。应根据 CMake 的配置模式搜索过程导入它们。示例，假设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 驱动程序的 CMake 包配置文件，以满足这种依赖关系。

尽管C++驱动程序也提供了 pkg-config 文件，但强烈建议用户改用 CMake包配置文件。

bsoncxx 库的 pkg-config 文件的名称也由BSONCXX_OUTPUT_NAME控制，并遵循lib<basename>.pc模式。可能需要使用 PKG_CONFIG_PATH 环境变量来扩充 pkg-config 的Atlas Search路径，例如：

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

共享库（仅限 MSVC）

从3.10.0版本开始，在 Windows 上使用 MSVC 工具链构建共享库时（即使 CMake 生成器不是 Visual Studio），也会使用与其他平台不同的命名方案。要恢复之前的行为（与其他平台类似），请设置ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES=OFF 。

共享库的名称（也称为“输出名称”）使用以下模式（不包括文件扩展名）：

<basename>-v<abi-version-number>-<abi-tag>

其中：

<basename> 对应于BSONCXX_OUTPUT_BASENAME CMake 配置变量（ MONGOCXX_OUTPUT_BASENAME表示 mongocxx 库）。默认设置为bsoncxx和mongocxx 。静态库的基本名称以-static为后缀。
<abi-version-number> 对应于当前 ABI 版本号。
<abi-tag> 描述了影响共享库二进制兼容性的已知属性。

<abi-tag>是一个由三个字母组成的字母组合，表示：

构建类型
mongoc 链接类型
Polyfill 库

其后的后缀描述了用于构建该库的工具集和运行时库。后缀的确切内容取决于构建配置。

预期库文件名的示例（附带显着功能的简要描述）包括：

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 （bsoncxx 作为 polyfill 库）
bsoncxx-v_noabi-rhm-x64-v142-md.dll （mnmstc/core 作为 polyfill 库）
bsoncxx-v_noabi-rhb-x64-v142-md.dll （Boost 作为 polyfill 库）
bsoncxx-v1-rhs-x64-v142-md.dll （ABI 版本号1 ）
bsoncxx-v2-rhs-x64-v142-md.dll （ABI 版本号2 ）

注意

此示例也适用于伴随.lib文件。

这种命名方案允许使用不同的构建配置（例如调试与发布）和不同的运行时库要求（例如 MultiThreadedDLL 与 MultiThreadedDebugDLL）并行且无冲突。有关更多详细信息，请参阅 CMake 配置中对ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES和相关代码的引用。

例如，以下安装前缀目录包含 API 版本为1.2.3和 ABI 版本为10的 bsoncxx 库的预期调试和发布库文件（包含 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

CMake 包配置文件与上述常规（非 MSVC）共享库行为相同。

注意

CMake 会根据构建类型自动处理库的选择，但在仅安装一种构建类型时不会强制执行构建类型一致性。出于这个原因，强烈建议在 Windows 上同时安装调试和发布配置。（此注释仅适用于构建类型配置参数）。

C++ 驱动程序库的 pkg-config 文件的名称与上述常规（非 MSVC）共享库行为的名称相同。但是，当为ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON时，库输出名称将被视为 pkg-config 文件的基本名称。例如，要获取共享库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"

ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON在C++ 安装具有不同构建配置（例如调试与发布）是预期的。但是，建议改用 CMake 包配置文件。

静态库

静态库使用简单的文件名模式：

lib<basename>-static.a

静态库文件的名称中不包含 API 或 ABI 版本信息。 CMake 包配置文件的共享库与静态库选择是通过 CMake 目标处理的。 pkg-config 文件的共享库与静态库选择是通过在库基本名称中添加-static后缀来处理的，例如 lib<basename>-static.pc 。

例如，以下库目录包含 bsoncxx 库的预期共享库文件和静态库文件：

${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

静态库（仅限 MSVC）

静态库的名称使用与上述 MSVC 共享库行为相同的模式，但使用static作为<abi-version-number>和库输出名称，就好像它是基本名称一样。

例如，以下安装前缀目录包含 bsoncxx 库的预期共享和静态库文件（包含 bin 目录是为了考虑.dll文件）：

${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

后退

线程和分叉安全

来年

API版本控制