从源代码构建 C 驱动程序库

本页详细介绍如何从原始源代码形式下载、解包、配置和构建 libbson和libmongoc 。

提示

额外信息

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

以下页面使用了一些必须预先决定的命名“变量”。当您在教程步骤中看到这样的值时，应将该值替换到该步骤中。

提示

在构建之前，您可能需要检查是否在受支持的平台上运行。有关支持的平台列表，请参阅 mongo-c-driver 平台支持页面。

选择版本

在开始之前，请了解您将要下载哪个版本的mongo-c-driver 。您可以在 GitHub存储库标签页面找到可用版本的列表。（为本文档编写的当前版本是..1 276。）

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

获取源代码

推荐使用两种主节点 (primary node in the replica set)方法来获取mongo-c-driver源代码：

使用git克隆存储库（推荐）。（见下文）
下载特定版本的源存档。（见下文）

重要

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

使用 Git 下载

使用 Git，可以从 GitHub URL https://github.com/mongodb/mongo-c-driver.git 1276克隆C驾驶员存储库。已发布版本的 Git 标记以其对应的版本命名（例如“..”）。要使用命令行克隆存储库，可以使用以下命令：

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

提示

尽管名称如此，但git-clone的--branch参数也可用于从存储库标记进行克隆。

下载版本存档

可以从 GitHub 发布页面获取存储库的存档快照。任何发布附带的mongo-c-driver-x.y.z.tar.gz 存档都包含构建所需的最小文件设立。

## 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"

## 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

上述命令将在运行tar / Expand-Archive命令的目录中创建一个新目录mongo-c-driver-$VERSION （注意：PowerShell 将创建一个同名的额外中间子目录）。此目录是驱动程序源代码树的根目录（我们在这些文档中将其称为$SOURCE ）。 $SOURCE目录应包含顶级CMakeLists.txt文件。

获取先决条件

为了构建该项目，需要满足一些先决条件。

libmongoc和libbson 项目都使用 CMake 进行构建配置。

注意

强烈建议（但不要求）下载适用于您的平台的最新稳定版 CMake。

提示

获取最新的 CMake

可以从 CMake 下载页面获取新的稳定发布的 CMake。

对于 Windows 和 macOS，只需下载 CMake .msi / .dmg （而不是.zip / .tar.gz ）并使用它来安装 CMake 即可。

在Linux ，下载自解压shell脚本（以 .sh 结尾）并使用 sh 实用程序执行该脚本，传递适当的参数以执行安装。示例，对于x86_64平台上的 CMake 3.27.0 ，可以对cmake-3.27.0-linux-x86_64.sh脚本使用以下命令：

$ 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环境变量上的命令，并且可在 shell 中作为“ cmake ”执行。您可以通过从命令行请求 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 。我们将在下一节中构建它。

CMAKE_BUILD_TYPE设置告知 CMake 将生成哪种代码变体。对于RelWithDebInfo ，将生成优化的二进制文件，但仍包含调试信息。 CMAKE_BUILD_TYPE 对多配置生成器（即 Visual Studio）没有影响，后者在构建/安装时依赖于--config 选项。

构建项目

成功配置项目后，可以使用 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指定的值相同。

提示

上面的代码段只是将mongo-c-driver安装在源目录本身的子目录中，但这不是正常的工作流程。一旦您熟悉了配置和构建mongo-c-driver ，如何：从源安装 libbson/libmongoc页面将更深入地介绍从源安装选项。

使用 libmongoc 进行配置

如果您从配置 libbson开始执行上述步骤，则最终结果仅包含libbson ，而不包含完整的 C 数据库驱动程序库。使用ENABLE_MONGOC CMake 变量启用/禁用libmongoc的构建。再次重新运行 CMake，但将ENABLE_MONGOC设置为TRUE ：

$ cmake -D ENABLE_MONGOC=ON $BUILD

如果上述命令成功，则项目已重新配置为使用libmongoc进行构建。再次按照“构建项目并安装构建结果”中的流程来构建和安装libmongoc 。

脚注

[1]

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

$ xcode-select --install

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

[2] 如果希望使用Microsoft Visual C++配置和构建项目，则在运行任何 CMake 或构建命令时，可能需要设立Visual C++工具和环境变量。在许多情况下，CMake 会检测 Visual Studio 安装并自动加载环境本身。这种自动检测可以使用 CMake-G 的、-T 和-A 选项进行控制。-G 选项最为重要，因为它可以选择使用哪个 Visual Studio 版本。支持的 Visual Studio 版本取决于已安装的 CMake 版本。可以在此处找到受支持的 Visual Studio 版本的列表。为了获得更好的控制和更多的工具选项，建议从 Visual Studio 开发者 PowerShell（首选）或开发者命令提示符（旧版）中运行命令。有关详细信息，请参阅：Visual Studio 开发者命令提示符和开发者 PowerShell 以及使用通过Microsoft Visual Studio 文档页面上的命令行使用Microsoft C++工具集。

后退

C驱动程序库

来年

预构建库