資源

github鏈接，官方主頁，本教程來自官方的 安裝教程頁面。更新日期：2018年9月21日

安裝準(zhǔn)備

• 任何一個標(biāo)準(zhǔn)的 Unix 平臺，或 Windows 7 SP1+
• 一個支持 C++11(gcc,clang,or Visual Studio)的編譯器
• CMaker 3.2 或之后版本
• boost 頭文件（可選）

安裝

1 安裝最新版本的 MongoDB C driver

mongocxx driver 是構(gòu)建在 MongoDB C driver 之上的。對于 mongocxx-3.3.x,需要 libmongoc 1.10.1 或之后的版本。

除非你知道你的包管理工具提供了一個足夠高的版本，否則你應(yīng)該下載源碼然后自己編譯，可以從 C Driver release 獲得源碼。

根據(jù) Installing libmongoc 的介紹可以從源碼進(jìn)行編譯。

達(dá)到行業(yè)最佳實踐和一些規(guī)則需要使用到 TLS 1.1 或更新的版本。如果在 Linux 上安裝了至少為 1.0.1 版本的 OpenSSL，MongoDB C Driver 支持 TLS 1.1.在 macOS 和 Windows 上，C Driver 使用支持 TLS 1.1 的本地 TLS。

譯者同樣翻譯了 mongoDB c 驅(qū)動，可以在 這里 查看。

2 選擇 C++ 17 增加特性

mongocxx driver 使用到了 C++17 std::optional和std::string_view特性。為了使用 pre-C++17 編譯 mongocxx driver，你必須在以下的實現(xiàn)中選擇一個：

• MNMLSTC/core(非 Windows 平臺默認(rèn)) 。使用 -DBSONCXX_POLY_USE_MNMLSTC=1 選項。

NOTE:這個選項會使在安裝 bsoncxx 庫時同時提供一個 MNMLSTC/core 的僅頭文件安裝包。因此會在編譯過程中自動從 GitHub 上下載 MLNMLSTC。如果你已經(jīng)在你的系統(tǒng)上安裝了一個可用的 MNMLSTC。你可以通過使用 -DBSONCXX_POLY_USE_SYSTEM_MNMLSTC 這個選項避免下載過程。

• Boost(Windows 平臺默認(rèn))。使用 -DBSONCXX_POLY_USE_BOOST=1 選項。如果你使用的是 MSVC，目前這是唯一的選擇。

• std::experimental。使用 -DBSONCXX_POLY_USE_STD_EXPERIMENTAL=1 選項。如果你的工具鏈標(biāo)準(zhǔn)庫在 std::experimental 命名空間提供了 optional 和 string_view ，你可以使用這個選項。注意你標(biāo)準(zhǔn)庫的 std::experimental的實現(xiàn)可能會隨時間而改變，進(jìn)而在不可預(yù)期的的情況下破壞二進(jìn)制文件的兼容性。所以這種方式是不推薦也支持這么做的。

大多數(shù)用戶使用默認(rèn)參數(shù)就行了。然而，如果你已經(jīng)有一個嚴(yán)重依賴上面提到對應(yīng)庫的應(yīng)用，你可能更愿意使用相同的庫來編譯 mongocxx driver。

如果你想要構(gòu)建一個穩(wěn)定的二進(jìn)制文件接口，不要改變你項目選擇的特性實現(xiàn)方法。

3 下載最新的 mongocxx driver

從 git 上獲得源碼時，release/stable 分支上追蹤了最新的穩(wěn)定發(fā)行版。例如，下面代碼獲取了一個穩(wěn)定的分支版本：

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

如果你更喜歡下載源碼，可以從 mongocxx release 頁面下載一個你喜歡的發(fā)布版本的源碼。例如，下面代碼下載了 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

請確保你進(jìn)入源碼下的 build 文件夾下，以便接下來的步驟可以執(zhí)行。

4 配置驅(qū)動

在 Unix 系統(tǒng)中， libmongoc 默認(rèn)安裝到了 /usr/local 下，你也可以使用下面的 cmake 命令將 mongocxx 也安裝到 /usr/local 目錄下：

（注意：結(jié)尾的 .. 不能省略）

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

/usr/local 可以被替換為我們實際 libmongoc 安裝的位置。

如果你想將 mongocxx 安裝到一個和 libmongoc 不同的文件夾下，你必須在 cmake 指令中指定如何找到 libmongoc安裝的文件夾。根據(jù) mongocxx 的版本不同這個步驟也不同：

• 編譯 mongocxx 3.2.x及以后的版本，應(yīng)該使用 CMAKE_PREFIX_PATH 參數(shù)指定 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 指定多個路徑，請使用英文狀態(tài)下的分號隔開，例如：

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

• 編譯 mongocxx 3.1.x 和 3.0.x 的版本應(yīng)該在 cmake 中使用 -DLIBMONGOC_DIR 和 -DLIBBSON_DIR 參數(shù)指定 libmongoc 的安裝路徑。請看下面的例子，假設(shè) libmongoc 和 libbson 都已經(jīng)安裝在 /your/cdriver/prefix下：

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

注意：此時根據(jù)需要在 cmake 指定對應(yīng)的參數(shù)來設(shè)置 C++ 17 支持的方式。例如，選擇 Boost 支持方式，使用下面的命令替代 cmake 那一行：

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

對于 Windows 平臺，下面例子演示了如何配置 MSVC 下的編譯(假設(shè) 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 ..

我根據(jù)我的另一篇 libmongoc 的譯文將其安裝到我指定的目錄中了，所以我這里的命令對應(yīng)為：

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 默認(rèn)以共享庫的形式進(jìn)行編譯，同時這也是推薦初學(xué)者的編譯形式。

注意：對于 mongocxx 3.2.x 和更新版本的用戶，一些高級用戶可能想編譯靜態(tài)庫，如果需要的話，在 CMake 中指定 -DBUILD_SHARED_LIBS=OFF。該參數(shù)將會編譯出 libmongoc 的靜態(tài)庫。在一個應(yīng)用中同時鏈接共享 libmongoc 和 靜態(tài) mongocxx 是不支持的，同樣同時鏈接靜態(tài) libmongoc 和共享 mongocxx也不行。

5 編譯和安裝驅(qū)動

如果你使用默認(rèn)的 MNMLSTC 的C++17支持且安裝在一個需要 root 權(quán)限的文件夾下。你應(yīng)該在使用 make 之前首先通過 sudo 安裝 MNMLSTC，否則你應(yīng)該使用 sudo 運行所有的 make：

# Only for MNMLSTC polyfill
sudo make EP_mnmlstc_core

一旦你 MNMLSTC 安裝完畢，或者你使用了其他的 C++17支持方式，你可以使用下面命令進(jìn)行編譯安裝：

make && sudo make install

在 Windows 平臺下，你可以使用以下的命令進(jìn)行編譯和安裝：

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

當(dāng)然 CMake 執(zhí)行完畢之后就會生成對應(yīng)的 VS 項目文件，直接使用 VS 打開對應(yīng)的 .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 進(jìn)行編譯

如果你使用 CMake 管理你的項目，你可以使用 find_package() 指令來使能 mongocxx 的編譯鏈接。find_package()指令會設(shè)置當(dāng)前環(huán)境中需要被傳遞到你的編譯目標(biāo)的相關(guān)變量（例如：LIBMONGOCXX_INCLUDE_DIRS, LIBMONGOCXX_LIBRARIES，等等）。如果你將 mongocxx 和 libmongoc安裝到了一個非標(biāo)準(zhǔn)位置（不在環(huán)境變量中），你需要在運行 cmake時將 CMAKE_PREFIX_PATH 設(shè)置為庫安裝的位置（在上面編譯時使用 CMAKE_INSTALL_PREFIX指定的參數(shù)）。

在 mongocxx 源倉庫（3.2.x或更新版本）中，examples/projects/mongocxx/cmake 文件夾下有使用共享庫方式鏈接 mongocxx 的 CMake 測試應(yīng)用，以及使用靜態(tài)庫的鏈接的 CMake 測試應(yīng)用。

譯者這里參考了官方的 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 編寫命令行參數(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 驅(qū)動的 dll 文件路徑添加到環(huán)境變量中。譯者這里添加的是 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)

使用靜態(tài)庫的高級用戶必須使用 libmongocxx-static 參數(shù)替代上面 pkg-config 的 libmongocxx 參數(shù)（這需要 mongocxx 3.2.x 或更新的版本）。

如果你安裝的位置不在 pkg-config 的搜索路徑上，應(yīng)該首先設(shè)置 PKG_CONFIG_PATH 環(huán)境變量。

export PKG_CONFIG_PATH="$MY_INSTALL_PREFIX/lib/pkgconfig"

不使用 pkg-config 和 CMake 編譯

如果你即不使用 CMake 也沒有可用的 pkg-config，你必須在命令行或 IDE 中手動的指定包含路徑和庫路徑。

下面是上面一個命令行的一個擴展示例，假設(shè) 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

對于高級用戶：下面是使用靜態(tài)庫的擴展示例。注意預(yù)處理器定義的 MONGOCXX_STATIC 和 BSONCXX_STATIC 必須被定義在所有包括 mongocxx 頭文件的源文件中。否則將會出現(xiàn)難以診斷的鏈接錯誤。

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），你必須在項目中設(shè)置需要的包含路徑、庫路徑、預(yù)定義和鏈接庫。這些操作可以在 VS 中借助 UI 實現(xiàn)也可以直接編輯 XML 格式的 .vcxproj 文件實現(xiàn)。為了確保你每一步都設(shè)置正確，下面PropertyGroup和ItemDefinitionGroup的設(shè)置示例展示了 Debug x64 編譯的設(shè)置方法。

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