API 和 ABI 版本
为了简洁，本页可能将特性和属性描述为仅适用于 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 头文件。
重要
在包含路径中，优先考虑不稳定ABI命名空间目录bsoncxx/v_noabi/，而不是根目录bsoncxx/。这意味着#include <bsoncxx/example.hpp>与#include <bsoncxx/v_noabi/bsoncxx/example.hpp>是等效的。
注意
不支持未记录的包含指令的稳定性。
包文件安装到${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/的子目录中。强烈建议用户使用这些包文件来获取bsoncxx库头文件（以及链接和编译标志的设置）。不推荐手动配置包含路径以获取bsoncxx头文件。以下将详细描述包文件。
在所有情况下，推荐使用CMake包配置文件作为导入C++驱动库的方法。
库文件名
库文件名和符号链接的存在取决于构建库的平台和工具链，以及库类型（共享与静态）。
共享库
重要
在Windows上使用MSVC工具链配置的共享库由于Windows特有的特殊考虑而有所不同。请参阅以下内容。共享库（仅限MSVC）。
共享库的“真实名称”使用以下模式
lib<basename>.so.<api-version-number>
其中
<basename>对应于CMake配置变量BSONCXX_OUTPUT_BASENAME（对于mongocxx库为MONGOCXX_OUTPUT_BASENAME）。默认情况下，这设置为bsoncxx和mongocxx。静态库的基本名后缀为-static。<api-version-number>是给定构建配置的主版本、次版本和补丁版本，对应于CMake配置变量BUILD_VERSION。（注意：在常规使用C++驱动时，不应显式设置此配置变量。）API版本号扩展不包括在真实名称中（例如，在
1.2.3-alpha中的-alpha）。
预期库真实名称的示例包括
libbsoncxx.so.1.0.0 libbsoncxx.so.2.3.4
CMake的SOVERSION目标属性和“namelink”行为用于在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的搜索路径，例如。
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>对应于CMake配置变量BSONCXX_OUTPUT_BASENAME（对于mongocxx库为MONGOCXX_OUTPUT_BASENAME）。默认情况下，这设置为bsoncxx和mongocxx。静态库的基本名后缀为-static。<abi-version-number>对应于当前的 ABI 版本号。<abi-tag>描述了影响共享库二进制兼容性的已知属性。
<abi-tag> 是一个由三个字母组成的组合，表示
构建类型
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（bsoncxx 作为填充库）bsoncxx-v1-rhs-x64-v142-md.dll（ABI 版本号 1）bsoncxx-v2-rhs-x64-v142-md.dll（ABI 版本号 2）
注意
此示例也适用于相应的 .lib 文件。
此命名方案允许 bsoncxx 库以不同的构建配置（例如 Debug 与 Release）和不同的运行库需求（例如 MultiThreadedDLL 与 MultiThreadedDebugDLL）并行构建和安装，而不会发生冲突。有关 ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES 以及 CMake 配置中相关代码的详细信息，请参阅参考。
例如，以下安装前缀目录包含具有 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 文件的基名使用。例如，当 ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=OFF（默认值）时，获取共享库 bsoncxx-v_noabi-rhs-x64-v142-md.dll 的标志的 pkg-config 命令可能如下所示
pkg-config --cflags "libbsoncxx"
或者如下所示，当 ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON
pkg-config --cflags "libbsoncxx-v_noabi-rhs-x64-v142-md"
当预期并行安装具有不同构建配置（例如 Debug 与 Release）的 C++ 驱动库时，建议设置 ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON。然而，最推荐使用 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