Include and Link the Driver in Your Program

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 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 section use the mongo::bsoncxx_shared target, and examples in the 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.

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.

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.

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)

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