自定义安装：从源代码构建C驱动程序库

本页详细介绍了如何从源代码下载、解压缩、配置和构建libbson 和 libmongoc 库。

提示

额外信息

警告（像这样的警告）包含完成本教程不需要的额外的信息和解释性细节，但可能对好奇的读者和需要解释某些教程步骤含义的高级用户有所帮助。

以下页面使用一些命名变量来表示配置信息，例如 $VERSION。在开始教程之前，您必须为这些变量选择值。当您看到教程步骤中引用的变量时，请用您的值替换该变量。

提示

在构建库之前，请检查您是否在支持的平台上运行。有关支持的平台列表，请参阅兼容性页面。

选择版本

开始之前，请了解要下载哪个版本的mongo-c-driver 。可以在 GitHub存储库标签页面上找到可用版本的列表。本教程记录了当前的驾驶员版本 v..1 3010。

在本页的其余部分中， $VERSION将指您将为本教程构建的mongo-c-driver的版本号。

获取源代码

通过以下方式之一获取 mongo-c-driver源代码：

使用 git 克隆存储库（推荐）。有关更多信息，请参阅使用 Git 下载。
下载特定版本的源存档。有关更多信息，请参阅下载版本存档。

重要

强烈建议新用户使用驱动程序的稳定发布版本，而不是从开发分支进行构建。当您 git clone 或下载存储库的存档时，请务必指定发布标签（例如使用 Git 的 --branch 参数）。

使用 Git 下载

您可以使用 Git 从 GitHub 克隆C驾驶员存储库。已发布版本的 Git1 3010标记以其对应的版本命名（例如“..”）。要命令行克隆存储库，请使用以下命令：

$ git clone https://github.com/mongodb/mongo-c-driver.git --branch="$VERSION" "$SOURCE"

提示

尽管有其名称，但您可以使用 git-clone 命令的 --branch 选项从存储库标签进行克隆。

下载版本存档

You can obtain an archived snapshot of the C driver repository from the repository's Releases page. Every release includes a mongo-c-driver-x.y.z.tar.gz archive, which contains the minimal set of files that you'll need for the build.

## Download using wget:
$ wget "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.tar.gz" \
     --output-document="mongo-c-driver-$VERSION.tar.gz"
## Extract using tar:
$ tar xf "mongo-c-driver-$VERSION.tar.gz"

前面的命令会在运行这些命令的目录中创建 mongo-c-driver-$VERSION目录，该目录是驱动程序源代码树的根目录。本文档将此目录称为 $SOURCE。$SOURCE目录包含顶级 CMakeLists.txt文件。

## Using curl:
$ curl "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.tar.gz" \
     --output="mongo-c-driver-$VERSION.tar.gz"
## Extract using tar:
$ tar xf "mongo-c-driver-$VERSION.tar.gz"

## Use Invoke-WebRequest:
PS> $url = "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.zip"
PS> $file = "mongo-c-driver-$VERSION.zip"
PS> Invoke-WebRequest -UseBasicParsing -Uri $url -OutFile $file
## Extract using Expand-Archive:
PS> Expand-Archive mongo-c-driver-$VERSION.zip

前面的命令会在运行这些命令的目录中创建 mongo-c-driver-$VERSION目录。mongo-c-driver-$VERSION目录包含第二个 mongo-c-driver-$VERSION目录，它是驱动程序源代码树的根目录。本文档将此目录称为 $SOURCE。$SOURCE目录包含顶级 CMakeLists.txt文件。

获取先决条件

You must install CMake to configure the libmongoc and libbson projects. We highly recommended that you download the latest stable version of CMake that is available for your platform.

选择与操作系统对应的标签页，然后按照说明下载CMake：

访问 CMake 下载页面。
下载 CMake .msi 或 .dmg文件并使用它来安装 CMake。

访问 CMake 下载页面
下载自解压Shell脚本，该脚本以 .sh 结尾。
使用 sh 实用程序执行脚本并传递相应参数以执行安装。示例，对于 x86_64 平台上的 CMake 3.27.0，运行以下命令：
sh cmake-3.27.0-linux-x86_64.sh --prefix="$HOME/.local" --exclude-subdir --skip-license
假设$HOME/.local/bin位于您的$PATH列表中，则3.27.0的cmake命令将变为可用。

可以将 --help 选项传递给shell脚本以获取更多信息。

本页假定 cmake 可用作 PATH 环境变量上的命令，并且可作为“cmake”从Shell中执行。您可以通过命令行向 CMake 请求 --version 来进行测试，如以下代码所示：

 cmake --version
 cmake version 3.21.4
CMake suite maintained and supported by Kitware (kitware.com/cmake).

注意

如果您打算仅构建libbson ，则 CMake 足以完成构建。其他 C 驱动程序功能可能需要安装额外的外部依赖项，但我们在这里不担心这些问题。

为 libbson 配置

重要

如果使用 Xcode [ 1 ]或 Visual Studio [ 2 ]进行构建，则可能需要在具有相应工具链的特殊环境中执行 CMake。

令名称$BUILD为路径$SOURCE/_build 。这将是 CMake 写入构建文件的目录。

利用位于$SOURCE的mongo-c-driver的源目录和构建目录$BUILD ，可以从命令行执行以下命令，以同时使用libbson和libmongoc配置项目：

$ cmake -S $SOURCE -B $BUILD \
   -D ENABLE_EXTRA_ALIGNMENT=OFF \
   -D ENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF \
   -D CMAKE_BUILD_TYPE=RelWithDebInfo \
   -D BUILD_VERSION="$VERSION" \
   -D ENABLE_MONGOC=OFF

如果满足所有依赖项，则上述命令应成功执行并以以下内容结束：

$ cmake …
## … (Lines of output) …
-- Generating done
-- Build files have been written to: $BUILD

如果配置因错误而失败，请参阅 CMake 输出以获取错误消息和信息。在继续之前确保配置成功。

提示

这些 CMake 参数是什么意思？

BUILD_VERSION设置将包含在构建结果中的版本号。它应设置为与获取源中下载的源驱动程序版本相同的值。

ENABLE_EXTRA_ALIGNMENT和ENABLE_AUTOMATIC_INIT_AND_CLEANUP是mongo-c-driver的一部分，对应于仅出于 ABI 兼容性目的而默认启用的已弃用功能。强烈建议尽可能禁用这些功能。

ENABLE_MONGOC=OFF参数已禁用构建libmongoc 。我们将在下一节中构建它。

The CMAKE_BUILD_TYPE setting tells CMake what variant of code will be generated. In the case of RelWithDebInfo, optimized binaries will be produced, but still include debug information. The CMAKE_BUILD_TYPE has no effect on Multi-Config generators (i.e. Visual Studio), which instead rely on the --config option when building/installing.

构建项目

成功配置项目后，可以使用 CMake 执行构建：

$ cmake --build $BUILD --config RelWithDebInfo --parallel

如果配置正确并且满足所有依赖关系，则上述命令应继续编译和链接已配置的组件。如果上述命令失败，则您的环境可能有错误，或者您使用的是不受支持/未经测试的平台。有关更多信息，请参阅构建工具输出。

提示

--config 选项

--config选项用于设置要在多配置生成器（即 Visual Studio）。它对其他生成器没有影响，而这些生成器会使用CMAKE_BUILD_TYPE 。

安装构建结果

令$PREFIX为路径$SOURCE/_install 。我们可以使用 CMake 来安装构建结果：

$ cmake --install "$BUILD" --prefix "$PREFIX" --config RelWithDebInfo

此命令会将mongo-c-driver构建结果安装到$PREFIX目录中。

提示

--config 选项

--config选项仅用于多配置生成器（即 Visual Studio），否则将被忽略。为--config指定的值必须与为--config和cmake --build指定的值相同。

提示

管理库版本

从源代码或使用包管理器安装MongoDB C驱动程序会安装使用版本化名称和路径的文件。为避免在升级驱动程序时需要更新构建配置，您可以使用构建系统的标准依赖项发现机制，例如 CMake 的 find_package() 命令。您还可以使用平台的共享库符号链接约定，而不是硬编码完整库文件名或安装路径。

使用 libmongoc 进行配置

If you followed the above steps starting from Configuring for libbson, your final result with only contain libbson and not the full C database driver library. Building of libmongoc is enabled/disabled using the ENABLE_MONGOC CMake variable. Re-run CMake again, but set ENABLE_MONGOC to TRUE:

$ cmake -D ENABLE_MONGOC=ON -B $BUILD -S $SOURCE

If the above command succeeds, then the project has been reconfigured to build with libmongoc. Follow the process at Building the Project and Installing the Built Results again to build and install libmongoc.

脚注

[1]

如果希望使用 Xcode 配置和构建项目，则需要安装 Xcode 命令行工具并使其在环境中可用。在命令行环境中，运行：

$ xcode-select --install

这将确保编译器和链接器在您的$PATH上可用。

[2]

如果您希望使用 Microsoft Visual C++ 配置和构建项目，则在运行任何 CMake 或构建命令时，可能需要设置 Visual C++ 工具和环境变量。

In many cases, CMake will detect a Visual Studio installation and automatically load the environment itself when it is executed. This automatic detection can be controlled with CMake's -G, -T, and -A options. The -G option is the most significant, as it selects which Visual Studio version will be used. The versions of Visual Studio supported depends on the version of CMake that you have installed. A list of supported Visual Studio versions can be found here.

为了获得更好的控制和更多的工具选项，建议从 Visual Studio 开发者 PowerShell（首选）或 开发者命令提示（旧版）中运行命令。

For more information, refer to: Visual Studio Developer Command Prompt and Developer PowerShell and Use the Microsoft C++ toolset from the command line on the Microsoft Visual Studio documentation pages.