资源

github链接，官方主页，本教程来自官方的 安装教程页面。更新日期：2018年9月21日

安装准备

• 任何一个标准的 Unix 平台，或 Windows 7 SP1+
• 一个支持 C++11(gcc,clang,or Visual Studio)的编译器
• CMaker 3.2 或之后版本
• boost 头文件（可选）

安装

1 安装最新版本的 MongoDB C driver

mongocxx driver 是构建在 MongoDB C driver 之上的。对于 mongocxx-3.3.x,需要 libmongoc 1.10.1 或之后的版本。

除非你知道你的包管理工具提供了一个足够高的版本，否则你应该下载源码然后自己编译，可以从 C Driver release 获得源码。

根据 Installing libmongoc 的介绍可以从源码进行编译。

达到行业最佳实践和一些规则需要使用到 TLS 1.1 或更新的版本。如果在 Linux 上安装了至少为 1.0.1 版本的 OpenSSL，MongoDB C Driver 支持 TLS 1.1.在 macOS 和 Windows 上，C Driver 使用支持 TLS 1.1 的本地 TLS。

译者同样翻译了 mongoDB c 驱动，可以在 这里 查看。

2 选择 C++ 17 增加特性

mongocxx driver 使用到了 C++17 std::optional和std::string_view特性。为了使用 pre-C++17 编译 mongocxx driver，你必须在以下的实现中选择一个：

• MNMLSTC/core(非 Windows 平台默认) 。使用 -DBSONCXX_POLY_USE_MNMLSTC=1 选项。

NOTE:这个选项会使在安装 bsoncxx 库时同时提供一个 MNMLSTC/core 的仅头文件安装包。因此会在编译过程中自动从 GitHub 上下载 MLNMLSTC。如果你已经在你的系统上安装了一个可用的 MNMLSTC。你可以通过使用 -DBSONCXX_POLY_USE_SYSTEM_MNMLSTC 这个选项避免下载过程。

• Boost(Windows 平台默认)。使用 -DBSONCXX_POLY_USE_BOOST=1 选项。如果你使用的是 MSVC，目前这是唯一的选择。

• std::experimental。使用 -DBSONCXX_POLY_USE_STD_EXPERIMENTAL=1 选项。如果你的工具链标准库在 std::experimental 命名空间提供了 optional 和 string_view ，你可以使用这个选项。注意你标准库的 std::experimental的实现可能会随时间而改变，进而在不可预期的的情况下破坏二进制文件的兼容性。所以这种方式是不推荐也支持这么做的。

大多数用户使用默认参数就行了。然而，如果你已经有一个严重依赖上面提到对应库的应用，你可能更愿意使用相同的库来编译 mongocxx driver。

如果你想要构建一个稳定的二进制文件接口，不要改变你项目选择的特性实现方法。

3 下载最新的 mongocxx driver

从 git 上获得源码时，release/stable 分支上追踪了最新的稳定发行版。例如，下面代码获取了一个稳定的分支版本：

git clone https://github.com/mongodb/mongo-cxx-driver.git \
    --branch releases/stable --depth 1
cd mongo-cxx-driver/build

如果你更喜欢下载源码，可以从 mongocxx release 页面下载一个你喜欢的发布版本的源码。例如，下面代码下载了 3.3.1 版本源码：

curl -OL https://github.com/mongodb/mongo-cxx-driver/archive/r3.3.1.tar.gz
tar -xzf r3.3.1.tar.gz
cd mongo-cxx-driver-r3.3.1/build

请确保你进入源码下的 build 文件夹下，以便接下来的步骤可以执行。

4 配置驱动

在 Unix 系统中， libmongoc 默认安装到了 /usr/local 下，你也可以使用下面的 cmake 命令将 mongocxx 也安装到 /usr/local 目录下：

（注意：结尾的 .. 不能省略）

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local ..

/usr/local 可以被替换为我们实际 libmongoc 安装的位置。

如果你想将 mongocxx 安装到一个和 libmongoc 不同的文件夹下，你必须在 cmake 指令中指定如何找到 libmongoc安装的文件夹。根据 mongocxx 的版本不同这个步骤也不同：

• 编译 mongocxx 3.2.x及以后的版本，应该使用 CMAKE_PREFIX_PATH 参数指定 libmongoc 的安装文件夹。例如（请使用你实际安装 C driver 的路径替换 /your/cdriver/prefix,使用你想安装的路径替换 /your/cxxdriver/prefix）:

cmake -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/your/cxxdriver/prefix \
    -DCMAKE_PREFIX_PATH=/your/cdriver/prefix ..

注意：如果你需要给 CMAKE_PREFIX_PATH 指定多个路径，请使用英文状态下的分号隔开，例如：

-DCMAKE_PREFIX_PATH="/your/cdriver/prefix;/some/other/path"

• 编译 mongocxx 3.1.x 和 3.0.x 的版本应该在 cmake 中使用 -DLIBMONGOC_DIR 和 -DLIBBSON_DIR 参数指定 libmongoc 的安装路径。请看下面的例子，假设 libmongoc 和 libbson 都已经安装在 /your/cdriver/prefix下：

cmake -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/your/cxxdriver/prefix
    -DLIBMONGOC_DIR=/your/cdriver/prefix
    -DLIBBSON_DIR=/your/cdriver/prefix ..

注意：此时根据需要在 cmake 指定对应的参数来设置 C++ 17 支持的方式。例如，选择 Boost 支持方式，使用下面的命令替代 cmake 那一行：

cmake -DCMAKE_BUILD_TYPE=Release -DBSONCXX_POLY_USE_BOOST=1 \
    -DCMAKE_INSTALL_PREFIX=/usr/local ..

对于 Windows 平台，下面例子演示了如何配置 MSVC 下的编译(假设 libmongoc 和 libbson 按照 mongoc Windows installation instructions 教程安装在 c:\mongo-c-driver且 boost 安装在 c:\local\boost_1_59_0)：

'C:\Program Files (x86)\CMake\bin\cmake.exe' -G "Visual Studio 14 Win64"
    -DCMAKE_INSTALL_PREFIX=C:\mongo-cxx-driver
    -DCMAKE_PREFIX_PATH=c:\mongo-c-driver
    -DBOOST_ROOT=c:\local\boost_1_59_0 ..

我根据我的另一篇 libmongoc 的译文将其安装到我指定的目录中了，所以我这里的命令对应为：

cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=D:\software4\mongo_c_driver\cppinstall_release -DCMAKE_PREFIX_PATH=D:\software4\mongo_c_driver\install -DBOOST_ROOT=D:\software3\boost_1_67_0 ..

mongocxx 默认以共享库的形式进行编译，同时这也是推荐初学者的编译形式。

注意：对于 mongocxx 3.2.x 和更新版本的用户，一些高级用户可能想编译静态库，如果需要的话，在 CMake 中指定 -DBUILD_SHARED_LIBS=OFF。该参数将会编译出 libmongoc 的静态库。在一个应用中同时链接共享 libmongoc 和 静态 mongocxx 是不支持的，同样同时链接静态 libmongoc 和共享 mongocxx也不行。

5 编译和安装驱动

如果你使用默认的 MNMLSTC 的C++17支持且安装在一个需要 root 权限的文件夹下。你应该在使用 make 之前首先通过 sudo 安装 MNMLSTC，否则你应该使用 sudo 运行所有的 make：

# Only for MNMLSTC polyfill
sudo make EP_mnmlstc_core

一旦你 MNMLSTC 安装完毕，或者你使用了其他的 C++17支持方式，你可以使用下面命令进行编译安装：

make && sudo make install

在 Windows 平台下，你可以使用以下的命令进行编译和安装：

msbuild.exe ALL_BUILD.vcxproj
msbuild.exe INSTALL.vcxproj

当然 CMake 执行完毕之后就会生成对应的 VS 项目文件，直接使用 VS 打开对应的 .sln 文件编译文件也可以。这一点和编译安装 libmongoc 相同。

6 测试你的安装文件

保存下面的源码到任意的目录下同时命名为 test.cpp：

#include <iostream>

#include <bsoncxx/builder/stream/document.hpp>
#include <bsoncxx/json.hpp>

#include <mongocxx/client.hpp>
#include <mongocxx/instance.hpp>

int main(int, char**) {
    mongocxx::instance inst{};
    mongocxx::client conn{mongocxx::uri{}};

    bsoncxx::builder::stream::document document{};

    auto collection = conn["testdb"]["testcollection"];
    document << "hello" << "world";

    collection.insert_one(document.view());
    auto cursor = collection.find({});

    for (auto&& doc : cursor) {
        std::cout << bsoncxx::to_json(doc) << std::endl;
    }
}

借助 CMake 进行编译

如果你使用 CMake 管理你的项目，你可以使用 find_package() 指令来使能 mongocxx 的编译链接。find_package()指令会设置当前环境中需要被传递到你的编译目标的相关变量（例如：LIBMONGOCXX_INCLUDE_DIRS, LIBMONGOCXX_LIBRARIES，等等）。如果你将 mongocxx 和 libmongoc安装到了一个非标准位置（不在环境变量中），你需要在运行 cmake时将 CMAKE_PREFIX_PATH 设置为库安装的位置（在上面编译时使用 CMAKE_INSTALL_PREFIX指定的参数）。

在 mongocxx 源仓库（3.2.x或更新版本）中，examples/projects/mongocxx/cmake 文件夹下有使用共享库方式链接 mongocxx 的 CMake 测试应用，以及使用静态库的链接的 CMake 测试应用。

译者这里参考了官方的 CMakeLists.txt 编写的 CMakeLists.txt 如下：

cmake_minimum_required(VERSION 3.11)
PROJECT (MONGOTEST)
# SET (SRC_LIST test.cpp)
find_package(libmongocxx REQUIRED)
add_executable(test test.cpp)
find_package(Boost REQUIRED)
target_include_directories(test
  PRIVATE ${Boost_INCLUDE_DIRS}
)
target_include_directories(test
  PRIVATE ${LIBMONGOCXX_INCLUDE_DIRS}
)
target_link_libraries(test
  PRIVATE ${LIBMONGOCXX_LIBRARIES}
)
target_compile_definitions(test
  PRIVATE ${LIBMONGOCXX_DEFINITIONS}
)

参考官方的 build.sh 编写命令行参数如下：

cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_PREFIX_PATH=D:\software4\mongo_c_driver\cppinstall_release -DBOOST_ROOT=D:\software3\boost_1_67_0 ..

需要注意以下几点：

• 译者这里编译的是共享库
• 在运行程序之前需要将 c 和 cpp 驱动的 dll 文件路径添加到环境变量中。译者这里添加的是 D:\software4\mongo_c_driver\cppinstall_release\bin 和 D:\software4\mongo_c_driver\install\bin

借助 pkg-config 编译

使用下面的命令编译上面的测试代码：

c++ --std=c++11 test.cpp -o test $(pkg-config --cflags --libs libmongocxx)

使用静态库的高级用户必须使用 libmongocxx-static 参数替代上面 pkg-config 的 libmongocxx 参数（这需要 mongocxx 3.2.x 或更新的版本）。

如果你安装的位置不在 pkg-config 的搜索路径上，应该首先设置 PKG_CONFIG_PATH 环境变量。

export PKG_CONFIG_PATH="$MY_INSTALL_PREFIX/lib/pkgconfig"

不使用 pkg-config 和 CMake 编译

如果你即不使用 CMake 也没有可用的 pkg-config，你必须在命令行或 IDE 中手动的指定包含路径和库路径。

下面是上面一个命令行的一个扩展示例，假设 mongocxx 和 libmongoc 安装在 /usr/local：

c++ --std=c++11 test.cpp -o test \
    -I/usr/local/include/mongocxx/v_noabi \
    -I/usr/local/include/bsoncxx/v_noabi \
    -L/usr/local/lib -lmongocxx -lbsoncxx

对于高级用户：下面是使用静态库的扩展示例。注意预处理器定义的 MONGOCXX_STATIC 和 BSONCXX_STATIC 必须被定义在所有包括 mongocxx 头文件的源文件中。否则将会出现难以诊断的链接错误。

c++ --std=c++11 test.cpp -o test \
    -DMONGOCXX_STATIC -DBSONCXX_STATIC -DMONGOC_STATIC -DBSON_STATIC \
    -I/usr/local/include/libmongoc-1.0 \
    -I/usr/local/include/libbson-1.0 \
    -I/usr/local/include/mongocxx/v_noabi \
    -I/usr/local/include/bsoncxx/v_noabi \
    -L/usr/local/lib -lmongocxx-static -lbsoncxx-static
    -lmongoc-static-1.0 -lsasl2 -lssl -lcrypto -lbson-static-1.0 -lm -lpthread

使用 MSVC 编译

为了在 MSVC 上编译（VS），你必须在项目中设置需要的包含路径、库路径、预定义和链接库。这些操作可以在 VS 中借助 UI 实现也可以直接编辑 XML 格式的 .vcxproj 文件实现。为了确保你每一步都设置正确，下面PropertyGroup和ItemDefinitionGroup的设置示例展示了 Debug x64 编译的设置方法。

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
    <LinkIncremental>true</LinkIncremental>
    <IncludePath>c:\local\boost_1_59_0\;C:\mongo-cxx-driver\include\mongocxx\v_noabi;C:\mongo-cxx-driver\include\bsoncxx\v_noabi;C:\mongo-c-driver\include\libmongoc-1.0;C:\mongo-c-driver\include\libbson-1.0;$(IncludePath)</IncludePath>
    <LibraryPath>c:\mongo-c-driver\lib\;c:\mongo-cxx-driver\lib\;$(LibraryPath)</LibraryPath>
  </PropertyGroup>
  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
    <ClCompile>
      <PrecompiledHeader>Use</PrecompiledHeader>
      <WarningLevel>Level3</WarningLevel>
      <Optimization>Disabled</Optimization>
      <PreprocessorDefinitions>MONGOCXX_STATIC;BSONCXX_STATIC;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
      <SDLCheck>true</SDLCheck>
    </ClCompile>
    <Link>
      <SubSystem>Console</SubSystem>
      <GenerateDebugInformation>true</GenerateDebugInformation>
      <AdditionalDependencies>libmongocxx.lib;libbsoncxx.lib;mongoc-static-1.0.lib;bson-1.0.lib;%(AdditionalDependencies)</AdditionalDependencies>
    </Link>
  </ItemDefinitionGroup>