Docs Menu
Docs Home
/
Languages
/
C Driver
/
C Driver

Building the C Driver Libraries from Source

On this page

  • Choose a Version
  • Obtaining the Source
  • Downloading Using Git
  • Downloading a Release Archive
  • Obtaining Prerequisites
  • Configuring for libbson
  • Building the Project
  • Installing the Built Results
  • Configuring with libmongoc
  • Footnotes

This page details how to download, unpack, configure, and build the libbson and libmongoc libraries from their source code.

Tip

Extra information

Admonitions (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 to represent configuration information, such as $VERSION. You must choose values for these variables before you start the tutorial. When you see a variable referenced in a tutorial step, substitute your value in its place.

Tip

See also:

Before you build the libraries, check that you are running on a supported platform. For the list of supported platforms, refer to Platform Compatibility on the Compatibility page.

Choose a Version

Before you 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. This tutorial documents the current driver version, v1.29.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

Obtain the mongo-c-driver source code in one of the following ways:

  • Clone the repository by using git (recommended). For more information, see Downloading Using Git.

  • Download a source archive at a specific version. For more information, see Downloading a Release Archive.

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

You can clone the C driver repository from GitHub by using Git. Git tags for released versions are named after the version for which they correspond (e.g. "1.29.0"). To clone the repository from the command line, use the following command:

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

Tip

Despite its name, you can use the --branch option of the git-clone command to clone from repository tags.

Downloading a Release Archive

You can obtain an archived snapshot of the C driver repository from the repository's Releases page. Every release includes a mongo-c-driver-x.y.z.tar.gz archive, which contains contains the minimal set of files that you'll need for the build.

## 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"

The preceding commands create the mongo-c-driver-$VERSION directory within the directory in which you ran them, which is the root of the driver source tree. This documentation refers to this directory as $SOURCE. The $SOURCE directory contains the top-level CMakeLists.txt file.

## 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"

The preceding commands create the mongo-c-driver-$VERSION directory within the directory in which you ran them, which is the root of the driver source tree. This documentation refers to this directory as $SOURCE. The $SOURCE directory contains the top-level CMakeLists.txt file.

## 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 preceding commands create the mongo-c-driver-$VERSION directory within the directory in which you ran them. The mongo-c-driver-$VERSION directory contains a second mongo-c-driver-$VERSION directory, which is the root of the driver source tree. This documentation refers to this directory as $SOURCE. The $SOURCE directory contains the top-level CMakeLists.txt file.

Obtaining Prerequisites

You must install CMake to configure the libmongoc and libbson projects. We highly recommended that you download the latest stable version of CMake that is available for your platform.

Select the tab corresponding to your operating system and follow the instructions to download CMake:

  1. Visit the CMake downloads page.

  2. Download the CMake .msi or .dmg file and use it to install CMake.

  1. Visit the CMake downloads page

  2. Download the self-extracting shell script, which ends with .sh.

  3. Execute the script by using the sh utility and passing the appropriate arguments to perform the install. For example, with the CMake 3.27.0 on the x86_64 platform, run the following command:

    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.

This page assumes 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, as shown in the following code:

 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.

Tip

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.

Tip

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.

Tip

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.

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.

Back

Transform Your Data with Aggregation

Next

Configure Operations on Replica Sets