- legacy (v1)
- Installing the legacy driver
Installing the legacy driver
The 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 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.
- NOTE: This option is only available on the
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 currentlyxpsp3
,ws03sp2
,vista
,ws08r2
,win7
, andwin8
.--msvc-host-arch
Override the detected host architecture. The allowable choices arex86
,i386
,amd64
,emt64
,x86_64
, andia64
. 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 selectlibc++
as the default runtime library, which is necessary if the prerequisite libraries (e.g. Boost) are built againstlibc++
.
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.