Building the MongoDB C Driver

First checkout the version you want to build. Always build from a particular tag, since HEAD may be a work in progress. For example, to build version 0.8.1, run:

git checkout v0.8.1

Then follow the build steps below.

Compile options with custom defines

Before compiling, you should note the following compile options.

For big-endian support, define:

  • MONGO_BIG_ENDIAN

If your compiler has a plain bool type, define:

  • MONGO_HAVE_BOOL

Alternatively, if you must include stdbool.h to get bool, define:

  • MONGO_HAVE_STDBOOL

If you’re not using C99, then you must choose your 64-bit integer type by defining one of these:

  • MONGO_HAVE_STDINT - Define this if you have <stdint.h> for int64_t.
  • MONGO_HAVE_UNISTD - Define this if you have <unistd.h> for int64_t.
  • MONGO_USE__INT64 - Define this if __int64 is your compiler’s 64bit type (MSVC).
  • MONGO_USE_LONG_LONG_INT - Define this if long long int is your compiler’s 64-bit type.

Building with Make:

If you’re building the driver on posix-compliant platforms, including on OS X and Linux, then you can build with make.

To compile the driver, run:

make

This will build the following libraries:

  • libbson.a
  • libbson.so (libbson.dylib)
  • libmongoc.a
  • lobmongoc.so (libmongoc.dylib)

You can install the libraries with make as well:

make install

And you can run the tests:

make test

You can even build the docs:

make docs

By default, make will build the project in c99 mode. If you want to change the language standard, set the value of STD. For example, if you want to build using the ANSI C standard, set STD to c89:

make STD=c89

Once you’ve built and installed the libraries, you can compile the sample with gcc like so:

gcc --std=c99 -I/usr/local/include -L/usr/local/lib -o example docs/examples/example.c -lmongoc

If you want to statically link the program, add the -static option:

gcc --std=c99 -static -I/usr/local/include -L/usr/local/lib -o example docs/examples/example.c -lmongoc

Then run the program:

./example

To clean up objects:

make clean

To clobber products, includes clean:

make clobber

Building with SCons:

You may also build the driver using the Python build utility, SCons. This is required if you’re building on Windows. Make sure you’ve installed SCons, and then from the project root, enter:

scons

This will build static and dynamic libraries for both BSON and for the the driver as a complete package. It’s recommended that you build in C99 mode with optimizations enabled:

scons --c99

Once you’ve built the libraries, you can compile a program with gcc like so:

gcc --std=c99 -static -Isrc -o example docs/example/example.c libmongoc.a

On Posix systems, you may also install the libraries with scons:

scons install

To build the docs:

scons docs

To cleanup:

scons -c

Building on Windows

When building the driver on Windows, you must use the Python build utility, SCons. Install Python 2 (NOT Python 3) from www.python.org, making sure to install the 32-bit version and NOT the 64-bit version. Install SCons from www.scons.org. For your compiler, we recommend that you use Visual Studio. If you don’t have Visual Studio, a free version is available. Search for Visual Studio C++ Express to find it.

If you’re running on 32-bit Windows, you must compile the driver in 32-bit mode:

scons --m32

If getaddrinfo and friends aren’t available on your version of Windows, you may compile without these features like so:

scons --m32 --standard-env

Platform-specific features

The original goal of the MongoDB C driver was to provide a very basic library capable of being embedded anywhere. This goal is now evolving somewhat given the increased use of the driver. In particular, it now makes sense to provide platform-specific features, such as socket timeouts and DNS resolution, and to return platform-specific error codes.

To that end, we’ve organized all platform-specific code in the following file:

  • env.c: environment-specific implementation for Posix-compliant systems (Linux, OS X) and Windows.

This implements the interface defined in env.h.

If you want to compile with the generic, platform implementation, you have to do so explicity. In SCons:

scons --standard-env

Using make:

make ENV=standard

Dependencies

The driver itself has no dependencies, but one of the tests shows how to create a JSON-to-BSON converter. For that test to run, you’ll need JSON-C.

Test suite

Make sure that you’re running mongod on 127.0.0.1 on the default port (27017). The replica set test assumes a replica set with at least three nodes running at 127.0.0.1 and starting at port 30000. Note that the driver does not recognize ‘localhost’ as a valid host name.

With make:

make test

To compile and run the tests with SCons:

scons test

You may optionally specify a remote server:

scons test --test-server=123.4.5.67

You may also specify an alternate starting port for the replica set members:

scons test --test-server=123.4.5.67 --seed-start-port=40000