Building the C Driver Libraries from Source

This page details how to download, unpack, configure, and build libbson and libmongoc from their original source-code form.

Extra information

Dropdowns (like this one) contain extra information and explanatory details that are not required to complete the tutorial, but may be helpful for curious readers, and more advanced users that want an explanation of the meaning of certain tutorial steps.

The following page uses a few named “variables” that you must decide up-front. When you see such a value referrenced in a tutorial step, you should substitute the value into that step.

See also

Before building, you may want to check that you are running on a supported platform. For the list of supported platforms, refer to the mongo-c-driver Platform Support page.

Choose a Version

Before we begin, know what version of mongo-c-driver you will be downloading. A list of available versions can be found on the GitHub repository tags page. (The current version written for this documentation is 1.25.0.)

For the remainder of this page, $VERSION will refer to the version number of mongo-c-driver that you will be building for this tutorial.

Obtaining the Source

There are two primary recommended methods of obtaining the mongo-c-driver source code:

1. Clone the repository using git (recommended). (See below)

2. Download a source archive at a specific version. (See below)

Important

It is highly recommended that new users use a stable released version of the driver, rather than building from a development branch. When you git clone or download an archive of the repository, be sure to specify a release tag (e.g. with Git’s --branch argument).

Downloading Using Git

Using Git, the C driver repository can be cloned from the GitHub URL https://github.com/mongodb/mongo-c-driver.git. Git tags for released versions are named after the version for which they correspond (e.g. “1.25.0”). To clone the repository using the command line, the following command may be used:

$ git clone https://github.com/mongodb/mongo-c-driver.git --branch="$VERSION" "$SOURCE"

Tip

Despite the name, git-clone‘s --branch argument may also be used to clone from repository tags.

Downloading a Release Archive

An archived snapshot of the repository can be obtained from the GitHub Releases Page. The mongo-c-driver-x.y.z.tar.gz archive attached to any release contains the minimal set of files that you’ll need for the build.

Using wget + tar

## Download using wget:
$ wget "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.tar.gz" \
    --output-document="mongo-c-driver-$VERSION.tar.gz"
## Extract using tar:
$ tar xf "mongo-c-driver-$VERSION.tar.gz"

Using curl + tar

## Using curl:
$ curl "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.tar.gz" \
    --output="mongo-c-driver-$VERSION.tar.gz"
## Extract using tar:
$ tar xf "mongo-c-driver-$VERSION.tar.gz"

PowerShell

## Use Invoke-WebRequest:
PS> $url = "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.zip"
PS> $file = "mongo-c-driver-$VERSION.zip"
PS> Invoke-WebRequest -UseBasicParsing -Uri $url -OutFile $file
## Extract using Expand-Archive:
PS> Expand-Archive mongo-c-driver-$VERSION.zip

The above commands will create a new directory mongo-c-driver-$VERSION within the directory in which you ran the tar/Expand-Archive command (note: PowerShell will create an additional intermediate subdirectory of the same name). This directory is the root of the driver source tree (which we refer to as $SOURCE in these documents). The $SOURCE directory should contain the top-level CMakeLists.txt file.

Obtaining Prerequisites

In order to build the project, a few prerequisites need to be available.

Both libmongoc and libbson projects use CMake for build configuration.

Note

It is highly recommended – but not required – that you download the latest stable CMake available for your platform.

Getting the Latest CMake

A new stable release of CMake can be obtained from the CMake downloads page.

For Windows and macOS, simply download the CMake .msi/.dmg (not the .zip/.tar.gz) and use it to install CMake.

On Linux, download the self-extracting shell script (ending with .sh) and execute it using the sh utility, passing the appropriate arguments to perform the install. For example, with the CMake 3.27.0 on the x86_64 platform, the following command can be used on the cmake-3.27.0-linux-x86_64.sh script:

$ sh cmake-3.27.0-linux-x86_64.sh --prefix="$HOME/.local" --exclude-subdir --skip-license

Assuming that $HOME/.local/bin is on your $PATH list, the cmake command for 3.27.0 will then become available.

The --help option can be passed to the shell script for more information.

For the remainder of this page, it will be assumed that cmake is available as a command on your PATH environment variable and can be executed as “cmake” from a shell. You can test this by requesting the --version from CMake from the command line:

$ cmake --version
cmake version 3.21.4

CMake suite maintained and supported by Kitware (kitware.com/cmake).

Note

If you intend to build libbson only, then CMake is sufficient for the build. Additional C driver features may require additional external dependencies be installed, but we will not worry about them here.

Configuring for libbson

Important

If you are building with Xcode [1] or Visual Studio [2], you may need to execute CMake from within a special environment in which the respective toolchain is available.

Let the name $BUILD be the path $SOURCE/_build. This will be the directory where our built files will be written by CMake.

With the source directory for mongo-c-driver at $SOURCE and build directory $BUILD, the following command can be executed from a command-line to configure the project with both libbson and libmongoc:

$ cmake -S $SOURCE -B $BUILD \
  -D ENABLE_EXTRA_ALIGNMENT=OFF \
  -D ENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF \
  -D CMAKE_BUILD_TYPE=RelWithDebInfo \
  -D BUILD_VERSION="$VERSION" \
  -D ENABLE_MONGOC=OFF

If all dependencies are satisfied, the above command should succeed and end with:

$ cmake …
## … (Lines of output) …
-- Generating done
-- Build files have been written to: $BUILD

If configuration failed with an error, refer to the CMake output for error messages and information. Ensure that configuration succeeds before proceeding.

What do these CMake arguments mean?

The BUILD_VERSION sets the version number that will be included in the build results. This should be set to the same value as the version of the source driver that was downloaded in Obtaining the Source.

The ENABLE_EXTRA_ALIGNMENT and ENABLE_AUTOMATIC_INIT_AND_CLEANUP are part of mongo-c-driver, and correspond to deprecated features that are only enabled by default for ABI compatibility purposes. It is highly recommended to disable these features whenever possible.

The ENABLE_MONGOC=OFF argument disabled building libmongoc. We’ll build that in the next section.

The CMAKE_BUILD_TYPE setting tells CMake what variant of code will be generated. In the case of RelWithDebInfo, optimized binaries will be produced, but still include debug information. The CMAKE_BUILD_TYPE has no effect on Multi-Config generators (i.e. Visual Studio), which instead rely on the --config option when building/installing.

Building the Project

After successfully configuring the project, the build can be executed by using CMake:

$ cmake --build $BUILD --config RelWithDebInfo --parallel

If configured properly and all dependencies are satisfied, then the above command should proceed to compile and link the configured components. If the above command fails, then there is likely an error with your environment, or you are using an unsupported/untested platform. Refer to the build tool output for more information.

The --config option

The --config option is used to set the build configuration to use in the case of Multi-Config generators (i.e. Visual Studio). It has no effect on other generators, which instead use CMAKE_BUILD_TYPE.

Installing the Built Results

Let $PREFIX be the path $SOURCE/_install. We can use CMake to install the built results:

$ cmake --install "$BUILD" --prefix "$PREFIX" --config RelWithDebInfo

This command will install the mongo-c-driver build results into the $PREFIX directory.

The --config option

The --config option is only used for Multi-Config generators (i.e. Visual Studio) and is otherwise ignored. The value given for --config must be the same as was given for --config with cmake --build.

See also

The above snippet simply installs mongo-c-driver in a subdirectory of the source directory itself, but this is not a normal workflow. Once you feel compfortable about configuring and building mongo-c-driver, the page How to: Install libbson/libmongoc from Source will do a deeper dive on from-source installation options.

Configuring with libmongoc

If you followed the above steps starting from Configuring for libbson, your final result with only contain libbson and not the full C database driver library. Building of libmongoc is enabled/disabled using the ENABLE_MONGOC CMake variable. Re-run CMake again, but set ENABLE_MONGOC to TRUE:

$ cmake -D ENABLE_MONGOC=ON $BUILD

If the above command succeeds, then the project has been reconfigured to build with libmongoc. Follow the process at Building the Project and Installing the Built Results again to build and install libmongoc.

Footnotes

[1]

If you wish to configure and build the project with Xcode, the Xcode command-line tools need to be installed and made available in the environment. From within a command-line environment, run:

$ xcode-select --install

This will ensure that the compilers and linkers are available on your $PATH.

[2]

If you wish to configure and build the project using Microsoft Visual C++, then the Visual C++ tools and environment variables may need to be set when running any CMake or build command.

In many cases, CMake will detect a Visual Studio installation and automatically load the environment itself when it is executed. This automatic detection can be controlled with CMake’s -G, -T, and -A options. The -G option is the most significant, as it selects which Visual Studio version will be used. The versions of Visual Studio supported depends on the version of CMake that you have installed. A list of supported Visual Studio versions can be found here

For greater control and more tooling options, it is recommended to run commands from within a Visual Studio Developer PowerShell (preferred) or Developer Command Prompt (legacy).

For more information, refer to: Visual Studio Developer Command Prompt and Developer PowerShell and Use the Microsoft C++ toolset from the command line on the Microsoft Visual Studio documentation pages.