Quickstart Guide (New Driver)

The goal of this guide is to get you to the point where you can build a simple application with the driver in a few short minutes.

Prerequisites

1. Windows or any standard 'nix platform.
2. A modern compiler. We require Clang 3.5+, Apple Clang 5.1+, GCC 4.8.2+, or VC2015 Update 1+.
3. CMake 3.2+.
4. The MongoDB C driver version 1.3.5+.
5. On Windows, boost 1.56+.

Build and install the C driver

The C++ driver uses libbson and the MongoDB C driver internally. If you don't already have a new enough version of the C driver and libbson installed, then you need to build them.

Build the C driver according to the section "Building From a Release Tarball" in the install instructions. The C driver installs libbson if necessary.

Decide on a source of polyfills for bsoncxx::stdx::optional and bsoncxx::stdx::string_view

The bsoncxx library (and the mongocxx library built above it) makes heavy use of optional and string_view types, but does not define its own version. Instead, a provider for these types is selected when running CMake. There are three options:

• MNMLSTC/core: Selected with -DBSONCXX_POLY_USE_MNMLSTC. This is the default on non-Windows platforms, and vendors a header only installation of MNMLSTC/core into the bsoncxx library installation. NOTE: this downloads MNMLSTC from the Internet; if you are firewalled, use Boost or std::experimental instead.
• Boost: Selected with -DBSONCXX_POLY_USE_BOOST. This is the default on Windows platforms, and is currently the only option if you are using MSVC, since MSVC cannot (currently?) compile MNMLSTC/core and does not offer the experimental namespaced versions of these types.
• std::experimental: If your toolchain's standard library provides optional and string_view in the namespace std::experimental you can use those types by building with -DBSONCXX_POLY_USE_STD_EXPERIMENTAL. The implications of using experimental types in your library should be clear.

Most users should be fine sticking with the default choice on their platform. However, if you have an existing application which already makes heavy use of one of the above libraries, it may make sense to build the C++ driver against the same library, so that the application and the MongoDB C++ driver share a common definition of optional and string_view.

Note that changing the backing library for the bsoncxx polyfills will result in a library with different mangled names and type signatures, so they will not be binary compatible. In the future we will be adding the necessary logic to the build system so that the choice of polyfill is reflected in things like the ABI name, header install path, etc.

Build and install the C++ driver

• Clone the repository, and check out the latest stable release

  • git clone -b master https://github.com/mongodb/mongo-cxx-driver
  • cd mongo-cxx-driver
  • git checkout r3.0.1

• Build the driver. Note that if you installed the cdriver to a path that is automatically searched by pkgconfig, you can omit the PKG_CONFIG_PATH environment variable. If you don't have pkgconfig, you can explicitly set the path to the libbson and libmongoc install prefixes with the -DLIBBSON_DIR and -DLIBMONGOC_DIR CMake arguments. Note: The example below will install the driver to /usr/local – you can change the CMAKE_INSTALL_PREFIX argument if you want it installed somewhere else. Also note: the ".." at the end of the cmake line is required!

  • cd mongo-cxx-driver/build
  • [PKG_CONFIG_PATH=CDRIVER_INSTALL_PATH/lib/pkgconfig] cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local ..
  • make && sudo make install

• Fire up your editor and copy in this code to a file called hellomongo.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;
    }
}

• You can compile with:
  • [PKG_CONFIG_PATH=CDRIVER_INSTALL_PATH/lib/pkgconfig] c++ --std=c++11 hellomongo.cpp -o hellomongo $(pkg-config --cflags --libs libmongocxx)