Building the C Driver Libraries from Source
On this page
This page details how to download, unpack, configure, and build libbson and
libmongoc from their original source-code form.
Tip
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 referenced in a tutorial step, you should substitute the value into that step.
Tip
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.28.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:
Clone the repository using
git(recommended). (See below)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.28.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.
## 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: $ 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"
## 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.
Tip
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
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.
Tip
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:$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. |