- legacy (v1)
- Installing the legacy driver
Installing the legacy driverThe Legacy C++ driver has reached End-Of-Life. Please upgrade to the mongocxx driver.
Table of Contents
- How to ask for Help
- Get the source code
- Choose a branch
- Compile the Driver
- Example C++ Driver Compilations
- Using the driver in your application
How to ask for Help
If you are having difficulty building the driver after reading the below instructions, please email the mongodb-user mailing list to ask for help. Please include in your email 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?
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.
- 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)
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
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
scons command. Use the SCons options described in this
To see the list of all SCons options, run:
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++.
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
--sslEnables 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-clientEnables 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.
--sharedclientBuilds a shared library version of the client driver alongside the static library. If applicable for your application, prefer using the shared client.
--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
--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-pathSpecifies 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
legacybranch at version legacy-0.10.0-pre or later. Prior to legacy-rc1, this option is available under the older
- NOTE: This option is only available on the
--ccThe compiler to use for C. Use the following syntax:
--cxxThe compiler to use for C++. Use the following syntax:
--dbg=[on|off]Enables runtime debugging checks. Defaults to off. Specifying
--opt=offunless explicitly overridden with
--opt=[on|off]Enables compile-time optimization. Defaults to on. Can be freely mixed with the values for the
--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.
--cacheEnables caching of object files.
-j NCompile with N cores.
--dynamic-windowsBy default, on Windows, compilation uses
/MT. Use this flag to compile with
/MD. Note that
/MDis required to build the shared client on Windows. Also note that your application compiler flags must match. If you build with
/MDdwill be used in place of
--dynamic-boost=[on|off|auto]Selects whether to link the driver to the boost libraries dynamically, statically, or as dynamic iff
--dynamic-windowsis enabled, respectively.
--win-version-minOverride the default build system choice of minimum windows version to target. Allowable options are currently
--msvc-host-archOverride the detected host architecture. The allowable choices are
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-environmentflag to the build so that the shell environment variables are passed down to the tool invocation.
--msvc-versionExplicitly 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.9when 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
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
scons --prefix=$HOME/mongo-client-install install
To enable SSL, add the
scons --prefix=$HOME/mongo-client-install --ssl install
To enable SASL support for use with Kerberos authentication on MongoDB Enterprise, add the
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
scons --prefix=$HOME/mongo-client-install --sharedclient install
To use a custom version of boost installed to /dev/boost, use the
scons --prefix=$HOME/mongo-client-install --extrapath=/dev/boost install
To target OS X 10.9 Mavericks (and default to using
libc++), use the
scons --prefix=$HOME/mongo-client-install --osx-version-min=10.9 install
To build a version of the library with debugging enabled, use
This turns off optimization, which is on by default. To enable both
debugging and optimization, pass
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
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) ```sh 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.org/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
$ARGS are the arguments you would normally pass (e.g.
--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.
There are only two headers intended for direct inclusion by consumers of the library:
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.
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
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.