Installing the legacy driver

Table of Contents

• How to ask for Help
• Get the source code
• Choose a branch
  • legacy branch
• Compile the Driver
  • SCons options when Compiling the C++ Driver
    • Targets
    • Client Options
    • Path Options
    • Build Options
    • SCons Options
    • Windows Options
    • Mac OS X Options
    • Deprecated Options
  • Windows Considerations
• Example C++ Driver Compilations
  • Debug Builds
  • Building on Windows
    • Building against the pre-built boost binaries
    • Building a DLL
    • Building multiple Windows library variants
• Using the driver in your application
  • Initialization and Configuration
  • Client Headers
  • Client Libraries
    • Windows autolinking
    • Linking with the static client library

How to ask for Help

If you are having difficulty building the driver after reading the below instructions, please post on the MongoDB Community Forums to ask for help. Please include in your post all of the following information:

• The version of the driver you are trying to build (branch or tag).
  • Examples: legacy-1.0.1 tag, legacy-1.0.2 tag
• Host OS, version, and architecture.
  • Examples: Windows 8 64-bit x86, Ubuntu 12.04 32-bit x86, OS X Mavericks
• C++ Compiler and version.
  • Examples: GCC 4.8.2, MSVC 2013 Express, clang 3.4, XCode 5
• Boost version.
  • Examples: boost 1.55, boost 1.49
• How boost was built or installed.
  • Examples: apt-get install libboost-all-dev, built from source, windows binary install
  • If you built boost from source, please include your boost build invocation as well.
• The complete SCons invocation.
  • Example: scons -j10 install
• The output of the configure phase of the build. If the configure phase failed (e.g. boost was not found), please attach the contents of the file build/scons/config.log.
• The error you encountered. This may be compiler, SCons, or other output.

Failure to include the relevant information will result in additional round-trip communications to ascertain the necessary details, delaying a useful response. Here is a made-up example of a help request that provides the relevant information:

PLEASE NOTE: The build invocation below is incomplete and intentionally erroneous. Read the section on building against the pre-built boost binaries under the “Building on Windows” section to understand what is wrong here, and the rest of the page to learn about other important options you will want or need to use when building the driver.

I’m trying to build the legacy-0.9 tag on Windows 8 64-bit, using MSVC 2013. I have the boost 1.55 pre-built Windows binaries for VC12 installed to D:\local\boost-1.55. When I invoked scons as scons --mute --64 --extrapath=D:\local\boost-1.55, the configure step will not find the boost headers. The build gives the following configure output:

Checking whether the C++ compiler works yes
Checking whether the C compiler works yes
Checking if C++ compiler "$CC" is MSVC... yes
Checking if C compiler "cl" is MSVC... yes
Checking if we are using libstdc++... no
WARNING: Cannot disable C++11 features when using MSVC
Checking if we are on a POSIX system... no
Checking for __declspec(thread)... yes
Checking for C++ header file boost/version.hpp... no
Could not find boost headers in include search path

Why can’t the build system find the boost headers?

Thanks

While collecting this information will take some additional time and effort, providing it will make it much more likely for your question to receive a prompt and immediately helpful reply.

Prerequisites

• Boost (>= 1.49) # May work with older versions back to 1.41
  • NOTE: On systems offering multiple C++ standard libraries, you must ensure that the standard library linked into boost matches that linked into the driver.
• Python (2.x)
• SCons
• Git

Get the Source Code

To get a repository that you can build, you can clone the sources, and then check out the branch or tag that you are interested in:

git clone -b releases/legacy https://github.com/mongodb/mongo-cxx-driver.git

Alternatively, see the releases page for downloadable tarball files containing the files associated with each released tag.

Choose a Branch

Legacy Branch:

Use the legacy branch if:

• You are using MongoDB’s C++ driver for the first time.
• You had been using 26compat (or the driver inside of the server source) and want to benefit from incremental improvements while having the same overall API.

git checkout legacy

Compile the Driver

From the directory where you cloned the code, compile the C++ driver by running the scons command. Use the SCons options described in this section.

To see the list of all SCons options, run: scons --help

SCons Options when Compiling the C++ Driver

Select options as appropriate for your environment. Please note that some flags may not be available on older versions.

Important note about C++11/C++14: The boost libraries do not offer a stable ABI across different versions of the C++ standard. As a result, you must ensure that your application, the C++ driver, and boost are all built with the same language standard. In particular, if you are building the C++ driver with C++11 enabled, you must also build your application with C++11 enabled, and link against a C++11 compiled boost. Note that on most systems, the system or package installed boost distribution is not built with C++11, and is therefore incompatible with a C++11 build of the legacy driver.

Important note about the C++ standard library: Much like the C++11 issues, it is again critical that all three components (your application, boost, and the C++ driver) be built against the same C++ runtime library. You cannot mix components that have linked against libc++ with those that have linked against libstdc++.

Targets

There are several targets you can build, but the most common target for users of the library is install, which will build the driver, and install the driver and headers to the location specified with the --prefix argument. If no prefix is specified, --prefix defaults to a directory named build/install under the current source directory.

Client Feature Options

• --ssl Enables SSL support. You will need a compatible version of the SSL libraries available.The default authorization mechanism since MongoDB version 3.0 is SCRAM-SHA-1. If you want to use standard MongoDB authentication, you should compile with –ssl option for SCRAM-SHA-1 mechanism support.
• --use-sasl-client Enables SASL, which MongoDB uses for the Kerberos authentication available on MongoDB Enterprise. You will need a compatible version of the SASL implementation libraries available. The Cyrus SASL libraries are what we test with, and are recommended.
• --sharedclient Builds a shared library version of the client driver alongside the static library. If applicable for your application, prefer using the shared client.

Path Options

• --prefix=<path> The directory prefix for the installation directory. Set to the directory where you want the build artifacts (headers and library files) installed. For example, you might set to /opt/local, /usr/local, or $HOME/mongo-client-install.
• --libpath=<path-to-libs> Specifies path to additional libraries.
• --cpppath=<path-to-headers> Specifies path to additional headers.
• --extrapath=<path-to-boost> Specifies the path to your Boost libraries if they are not in a standard search path for your toolchain.
• --runtime-library-search-path Specifies the runtime search path for dynamic libraries when running tests. Set this to the directory containing boost, ssl, or sasl DLLs as required.
  • NOTE: This option is only available on the legacy branch at version legacy-0.10.0-pre or later. Prior to legacy-rc1, this option is available under the older --dllpath name.

Build Options

• --cc The compiler to use for C. Use the following syntax: --cc=<path-to-c-compiler>
• --cxx The compiler to use for C++. Use the following syntax: --cxx=<path-to-c++-compiler>
• --dbg=[on|off] Enables runtime debugging checks. Defaults to off. Specifying --dbg=on implies --opt=off unless explicitly overridden with --opt=on.
• --opt=[on|off] Enables compile-time optimization. Defaults to on. Can be freely mixed with the values for the --dbg flag.
• --c++11=[on|off] Builds the driver in C++11 mode. Defaults to off. Please see the note above about requirements for using C++11.
• --libc++ Builds the driver against the libc++ C++ runtime library. Please see the note above about requirements for the C++ runtime library.

Scons Options

• --cache Enables caching of object files.
• -j N Compile with N cores.

Windows Options

• --dynamic-windows By default, on Windows, compilation uses /MT. Use this flag to compile with /MD. Note that /MD is required to build the shared client on Windows. Also note that your application compiler flags must match. If you build with --dbg=on, /MTd or /MDd will be used in place of /MT or /MD, respectively.
• --dynamic-boost=[on|off|auto] Selects whether to link the driver to the boost libraries dynamically, statically, or as dynamic iff --dynamic-windows is enabled, respectively.
• --win-version-min Override the default build system choice of minimum windows version to target. Allowable options are currently xpsp3, ws03sp2, vista, ws08r2, win7, and win8.
• --msvc-host-arch Override the detected host architecture. The allowable choices are x86, i386, amd64, emt64, x86_64, and ia64. You should only need to use this if the auto-detected host architecture selects a compiler variant that is not available on your system.
• --msvc-script=[<path>] Explicitly selects an MSVC configuration script to run. This may allow you to use MSVC toolchain versions for which your version of SCons does not offer support. You may also pass the empty string to inhibit SCons execution of any MSVC configuration scrip to run. This is useful if you have a “dressed” MSVC shell that you prefer to use. In this case, you will also need to pass the --propagate-shell-environment flag to the build so that the shell environment variables are passed down to the tool invocation.
• --msvc-version Explicitly select the MSVC version. This is useful if you have multiple toolchains installed. By default SCons will select the newest. If you need to run an older toolchain, you may override with this flag. Please be aware that the value passed here is the VC version (like 10.0, 11.0, 12.0, etc.), not the VS version (2010, 2012, etc.).

Mac OS X Options (Mac OS X Only)

• --osx-version-min=[10.7|10.8|10.9] Minimum version of Mac OS X to build for. Use --osx-version-min=10.9 when compiling on OS X 10.9 Mavericks to automatically select libc++ as the default runtime library, which is necessary if the prerequisite libraries (e.g. Boost) are built against libc++.

Windows Considerations

When building on Windows, use of the SCons --dynamic-windows option can result in an error unless all libraries and sources for the application use the same C runtime library. This option builds the driver to link against the dynamic link C RTL instead of the static C RTL. If the Boost library being linked against is expecting an /MT build (static C RTL), this can result in an error similar to the following:

error LNK2005: ___ already defined in msvcprt.lib(MSVCP100.dll) libboost_thread-vc100-mt-1_42.lib(thread.obj)

The same caveat applies to building with the –dbg=on flag, which will select the debug runtime library.

You may want to define _CRT_SECURE_NO_WARNINGS to avoid warnings on use of strncpy and such by the MongoDB client code.

Include the WinSock library in your application: Linker ‣ Input ‣ Additional Dependencies. Add ws2_32.lib.

Example C++ Driver Compilations

The following are examples of building the C++ driver.

The following example installs the driver to $HOME/mongo-client-install:

scons --prefix=$HOME/mongo-client-install install

To enable SSL, add the --ssl option:

scons --prefix=$HOME/mongo-client-install --ssl install

To enable SASL support for use with Kerberos authentication on MongoDB Enterprise, add the --use-sasl-client option:

scons --prefix=$HOME/mongo-client-install --use-sasl-client install

To build a shared library version of the driver, along with the normal static library, use the --sharedclient option:

scons --prefix=$HOME/mongo-client-install --sharedclient install

To use a custom version of boost installed to /dev/boost, use the --extrapath=<path-to-boost> option:

scons --prefix=$HOME/mongo-client-install --extrapath=/dev/boost install

To target OS X 10.9 Mavericks (and default to using libc++), use the --osx-version-min=<version> option:

scons --prefix=$HOME/mongo-client-install --osx-version-min=10.9 install

Debug Builds

To build a version of the library with debugging enabled, use --dbg=on. This turns off optimization, which is on by default. To enable both debugging and optimization, pass --dbg=on --opt=on:

scons --prefix=$HOME/mongo-client-install --dbg=on --opt=on install

To override the default compiler to a newer GCC installed in /opt/local/gcc-4.8, use the --cc and --cxx options:

scons --prefix=$HOME/mongo-client-install --cc=<path-to-gcc> --cxx=<path-to-g++> install

Building on Windows

Building against the pre-built boost binaries.

Building boost from source can be challenging on Windows. If appropriate for your situation, we recommend using the pre built boost Windows binaries. Please note that you must select a download that properly reflects your target architecture (i.e. 32-bit or 64-bit) and toolchain revision (MSVC 10, 11, etc. Note that this is the VC version not the Visual Studio version).

Due to the layout of the boost installation in the pre-built binaries, you cannot use the --extrapath SCons flag to inform the build of the installation path for the boost binaries. Instead, you should use the --cpppath flag to point to the root of the chosen boost installation path, and --libpath to point into the appropriately named library subdirectory of the boost installation. For example, if you have installed the 64-bit boost 1.55 libraries for MSVC11 into D:\local\boost_1_55_0_msvc11, then you would add

--cpppath=d:\local\boost_1_55_0_msvc --libpath=d:\local\boost_1_55_0_msvc11\lib64-msvc-11.0

to your SCons invocation.

Building a DLL (New in version 2.5.5)

scons
    <--64 or --32>
    --sharedclient
    --dynamic-windows
    --prefix=<install-path>
    --cpppath=<path-to-boost-headers>
    --libpath=<path-to-boost-libs>
    install

The following example will build and install the C++ driver, in a PowerShell:

scons
    --64
    --sharedclient
    --dynamic-windows
    --prefix="%HOME%\mongo-client-install"
    --cpppath="C:\local\boost_1_55_0\include"
    --libpath="C:\local\boost_1_55_0\lib64-msvc-12.0"
    install

Building multiple Windows library variants:

As of legacy-0.8, the Windows libraries are now tagged with boost-like ABI tags (see http://www.boost.org/doc/libs/1_55_0/more/getting_started/windows.html#library-naming), so it is possible to build several different variants (debug vs retail, static vs dynamic runtime) and install them to the same location. We have added support for autolib, so the selection of the appropriate library is handled automatically (see https://jira.mongodb.com/browse/CXX-200). To build all of the different driver variants, repeatedly invoke scons as follows:

scons $ARGS install
scons $ARGS install --dbg=on
scons $ARGS install --dynamic-windows --sharedclient
scons $ARGS install --dynamic-windows --sharedclient --dbg=on

Where $ARGS are the arguments you would normally pass (e.g. --cpppath, --libpath, --64, --prefix, etc.). You should ensure that you use the same arguments for all four invocations. If this works properly, your $PREFIX/lib directory should contain the following files:

libmongoclient.lib
libmongoclient-gd.lib
libmongoclient-s.lib
libmongoclient-sgd.lib
mongoclient.dll
mongoclient.exp
mongoclient.lib
mongoclient.pdb
mongoclient-gd.dll
mongoclient-gd.exp
mongoclient-gd.lib
mongoclient-gd.pdb

Using the driver in your application

Initialization and Configuration

NOTE: You must initialize the legacy driver before use. See Configuration for more details.

Client Headers

There are only two headers intended for direct inclusion by consumers of the library:

• $PREFIX/include/mongo/bson/bson.h
• $PREFIX/include/mongo/client/dbclient.h

These ‘facade’ headers should include all of the headers necessary to use the driver or BSON library. Directly including other headers from $PREFIX/include/mongo/ is unlikely to work as intended and may lead to subtle or hard to diagnose problems.

To consume the headers, you must configure your build system so that $PREFIX/include is incorporated into the header search path. For GCC-esque compilers, this is typically done with the -I flag. For IDEs, consult the relevant documentation on how to configure the header search path for your project.

Client Libraries

Depending on how you built the driver, you may end up with a static library, a dynamic library, or both. On Windows, you may end up with many libraries with different names.

To link with the library, you must configure your build system so that $PREFIX/lib is incorporated into the link-time library search path. For GCC-esque compilers, this is typically done with the -L flag. For IDEs, consult the relevant documentation on how to configure the library search path for your project.

Once you have added the search path, you may need to specify the name of the library you want to link against on your application link line. For GCC style compilers, this is typically done with the -l flag. For IDE’s, consult the relevant documentation on how to add libraries to the link line.

Windows autolinking

For legacy-0.9.0+ on Windows, the driver off autolib support. In this case, you do not need to add the client library as a dependent library. Inclusion of the client headers will register the dependency on the library and it will automatically be linked. You do still need to specify the library search path however.

Linking with the static client library.

If you intend to link against the static client library, you must also define the preprocessor symbol STATIC_LIBMONGOCLIENT in all translation units that include the driver or BSON headers. Failure to do so will result in hard to diagnose warnings or errors.