mongodb c++ 驱动

资源

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::optionalstd::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 命名空间提供了 optionalstring_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 的安装路径。请看下面的例子,假设 libmongoclibbson 都已经安装在 /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,等等)。如果你将 mongocxxlibmongoc安装到了一个非标准位置(不在环境变量中),你需要在运行 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\binD:\software4\mongo_c_driver\install\bin

借助 pkg-config 编译

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

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

使用静态库的高级用户必须使用 libmongocxx-static 参数替代上面 pkg-configlibmongocxx 参数(这需要 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_STATICBSONCXX_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 文件实现。为了确保你每一步都设置正确,下面PropertyGroupItemDefinitionGroup的设置示例展示了 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>
    原文作者:刘亚彬_244c
    原文地址: https://www.jianshu.com/p/c982a2960175
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。
点赞