Include and Link the Driver in Your Program

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Overview

In this guide, you can learn how to use CMake and pkg-config to include the C++ driver in your project.

Sample Data

The examples on this page use the view_and_value.cpp example program from the C++ driver source code. Obtain the C++ driver source code by following the [Download and Install](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/get-started.md#std-label-cpp-quick-start-download-and-install guide.

In the sections that follow, replace <path-to-mongo-cxx-driver-sources> with the actual path where the C++ driver source tree is located on your system.

You do not need to run this program on a MongoDB server.

Library References

The examples on this page reference C++ driver library targets. Examples in the [CMake](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/connect/include-link.md#std-label-cpp-include-cmake section use the mongo::bsoncxx_shared target, and examples in the [pkg-config](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/connect/include-link.md#std-label-cpp-include-pkg-config section use the libbsoncxx package. You may use the following alternative library targets, depending on the needs of your project:

  • CMake: - mongo::bsoncxx_shared - mongo::mongoccxx_shared - mongo::bsoncxx_static - mongo::mongoccxx_static

  • pkg-config: - libbsoncxx - libmongocxx - libbsoncxx-static - libmongocxx-static

The availability of targets depends on the particular installation method.

CMake

You can use CMake to include the C++ driver in your project. CMake provides the find_package command, which your project can use to locate the C++ driver once it is installed. Alternatively, your project can use the advanced add_subdirectory command without installing the C++ driver.

Troubleshooting

In the following sections, if you encounter errors, you may need to specify additional options to the initial CMake command. The specific options depend on your particular environment. However, the following options address most common issues:

  • If your compiler does not default to at least C++17, use the -DCMAKE_CXX_STANDARD=17 CMake option.

  • If you installed the driver to a non-standard location, specify the -DCMAKE_PREFIX_PATH=/<path-to-mongo-cxx-driver-installation> option. For example:

cmake -Bbuild -DCMAKE_CXX_STANDARD=17 -DCMAKE_PREFIX_PATH=/opt/mongodb/cxx-driver

With Driver Installation

After installing the C++ driver, you can use CMake's find_package command to integrate the driver with your project.

Tip:

To learn how to install the C++ driver, visit the following guides:

  • [Download and Install](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/get-started.md#std-label-cpp-quick-start-download-and-install to install from source

  • [Advanced Configuration and Installation Options](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/connect/advanced-installation.md#std-label-cpp-installation-advanced to install from packages

To use the find_package command, create a CMakeLists.txt file in your project directory. The following example creates a CMakeLists.txt file in the /home/user/project1 project directory that uses find_package:

cmake_minimum_required (VERSION 3.15)
project (builder_basic LANGUAGES CXX)

find_package (bsoncxx 4.0 REQUIRED)

add_executable (view_and_value /<path-to-mongo-cxx-driver-sources>/examples/bsoncxx/view_and_value.cpp)

## we need target_include_directories because view_and_value.cpp refers to a common example header
target_include_directories (view_and_value PRIVATE /<path-to-mongo-cxx-driver-sources>)
target_link_libraries (view_and_value PRIVATE mongo::bsoncxx_shared)

Then, run the following commands to build your project:

$ cd /home/user/project1
$ cmake -Bbuild
$ cmake --build build

These commands return information about the build process. After the build completes, run the executable produced in the preceding step:

$ ./build/view_and_value

The output resembles the following:

{ "team" : "platforms", "id" : { "$oid" : "66f4be6fef9eb8b9240619f0" }, "members" : [ "tyler", "jason", "drew", "sam", "ernie", "john", "mark", "crystal" ] }
Got key, key = team
Got String!
Got key, key = id
Got ObjectId!
Got key, key = members
Got Array!
array element: tyler
array element: jason
array element: drew
array element: sam
array element: ernie
array element: john
array element: mark
array element: crystal
as expected, we have a team
document has 3 keys.
document keys are:
team
id
members

Without Driver Installation

Alternatively, you can use CMake's add_subdirectory command without installing the C++ driver. This is an advanced technique that, unlike the find_package command, does not support specifying version constraints.

Note:

You may need to adjust build flags for your project to accommodate this approach. Your project's invocation of CMake must include any flags or options that are normally passed to the C++ driver as part of its build.

To use the add_subdirectory command, create a CMakeLists.txt file in your project directory. The following example creates a CMakeLists.txt file in the /home/user/project2 project directory that uses add_subdirectory:

cmake_minimum_required (VERSION 3.15)
project (builder_basic LANGUAGES CXX)

## specify a source_dir which is out-of-tree from this project, so also specify bin_dir
add_subdirectory (/<path-to-mongo-cxx-driver-sources> ./build/mongo-cxx-driver)

add_executable (view_and_value /<path-to-mongo-cxx-driver-sources>/examples/bsoncxx/view_and_value.cpp)

## we need target_include_directories because view_and_value.cpp refers to a common example header
target_include_directories (view_and_value PRIVATE /<path-to-mongo-cxx-driver-sources>)
## no mongo:: namespace prefix, since the targets are use directly without installation
target_link_libraries (view_and_value PRIVATE bsoncxx_shared)

Note:

The preceding example uses the bsoncxx_shared CMake target without the mongo:: namespace. The namespace is added as part of the CMake module installation, which is not performed in this approach.

Then, run the following commands to build your project:

$ cd /home/user/project1
$ cmake -Bbuild
$ cmake --build build

These commands return information about the build process. After the build completes, run the executable produced in the preceding step:

$ ./build/view_and_value

The output resembles the following:

{ "team" : "platforms", "id" : { "$oid" : "67207dcf532837a4470cc090" }, "members" : [ "tyler", "jason", "drew", "sam", "ernie", "john", "mark", "crystal" ] }
Got key, key = team
Got String!
Got key, key = id
Got ObjectId!
Got key, key = members
Got Array!
array element: tyler
array element: jason
array element: drew
array element: sam
array element: ernie
array element: john
array element: mark
array element: crystal
as expected, we have a team
document has 3 keys.
document keys are:
team
id
members

pkg-config

If your project is not CMake-based, you can use pkg-config to integrate the C++ driver with your project. Because pkg-config provides less flexibility than CMake, we recommend using the CMake-based approach when possible.

You can only use the C++ driver with pkg-config if you fully install the driver.

The following code uses pkg-config to include and link the C++ driver. Replace the <path-to-mongo-cxx-driver-sources> placeholder with the location of the C++ driver source tree on your system:

$ c++ /<path-to-mongo-cxx-driver-sources>/examples/bsoncxx/view_and_value.cpp $(pkg-config --cflags libbsoncxx) -I/<path-to-mongo-cxx-driver-sources> $(pkg-config --libs libbsoncxx) -o view_and_value
$ ./view_and_value
{ "team" : "platforms", "id" : { "$oid" : "67207262672b96dc3b0fc150" }, "members" : [ "tyler", "jason", "drew", "sam", "ernie", "john", "mark", "crystal" ] }
Got key, key = team
Got String!
Got key, key = id
Got ObjectId!
Got key, key = members
Got Array!
array element: tyler
array element: jason
array element: drew
array element: sam
array element: ernie
array element: john
array element: mark
array element: crystal
as expected, we have a team
document has 3 keys.
document keys are:
team
id
members

You can adapt the preceding command line for more complex projects or specific build systems depending on how they consume pkg-config packages.