mongo-cxx-driver

Imported from mongodb/mongo-cxx-driver (AGENTS.md). Install upstream with npx skills add mongodb/mongo-cxx-driver. Copyright stays with the author.

AGENTS.md

This file provides guidance to AI coding agents working with code in this repository.

Build System

This project uses CMake.

The MongoDB C Driver (which provides the required bson and mongoc libraries) is fetched automatically via FetchContent unless an existing installation prefix is found via find_package() (set CMAKE_PREFIX_PATH accordingly).

Use build/ as the CMake binary directory unless otherwise specified by the user. When the user specifies a custom binary directory, always use that directory - do not fall back to build/.

The typical configure and build steps (for release and installation):

cmake -D CMAKE_BUILD_TYPE=RelWithDebInfo -D CMAKE_CXX_STANDARD=17 -B build
cmake --build build

The optional install step:

cmake --install build

[!IMPORTANT] For multi-configuration generators (e.g. "Visual Studio *", "Ninja Multi-Config", etc.), use --config <config> during the build, install, and test steps instead of CMAKE_BUILD_TYPE=<config>. The CMAKE_BUILD_TYPE option will be ignored by the configuration step. Only use CMAKE_BUILD_TYPE with single-configuration generators (e.g. Makefile Generators, Ninja, etc.).

Key CMake configuration options (given option=(default|alternatives...)):

• -G <generator-name>: specify a build system generator.
• -D CMAKE_PREFIX_PATH:PATH=<mongo-c-driver-prefix>: specify installation prefixes to search with find_*() CMake commands (e.g. to use an existing MongoDB C Driver installation)
• -D CMAKE_INSTALL_PREFIX:PATH=<install-prefix>: install directory used by install(). Defaults to:
  • The CMAKE_INSTALL_PREFIX environment variable when set (with CMake 3.29 or newer).
  • /usr/local on UNIX platforms.
  • C:/Program Files/${PROJECT_NAME} on Windows.
  • Use build/install/ as the custom install prefix when system modification is undesirable or disallowed by the user.
• -D CMAKE_BUILD_TYPE:STRING=<config>: specify the build type on single-configuration generators.
• -D CMAKE_CXX_STANDARD:STRING=(11|<cxx-standard>): set the C++ standard ("17" or newer is recommended).
• -D BUILD_SHARED_LIBS:BOOL=(ON|OFF): specify whether to build shared (ON) or static (OFF) libraries.
• -D BUILD_SHARED_AND_STATIC_LIBS:BOOL=(OFF|ON): enable building both shared and static libraries (requires BUILD_SHARED_LIBS=ON).
• -D ENABLE_TESTS:BOOL=(OFF|ON): required to enable and build test targets.
• -D BUILD_TESTING:BOOL=(OFF|ON): include test targets in the "all" target (when ENABLE_TESTS=ON).

Build performance: Ninja parallelizes builds across all available cores by default; to cap the job count, set CMAKE_BUILD_PARALLEL_LEVEL=<N> in the environment before running cmake --build.

[!NOTE] For local development and testing, use the Debug configure in the Running Tests section instead of the release configure above.

[!NOTE] .evergreen/scripts/compile.sh is the authoritative reference for CI configure-build-install routines. Consult it for details on Ninja generator selection, ccache integration, sanitizer flags (USE_SANITIZER_ASAN, USE_SANITIZER_UBSAN), polyfill selection (BSONCXX_POLYFILL), and other platform-specific options.

Running Tests

Tests use the Catch2 library and require C++14 or newer.

The typical configure and build steps (for testing and development):

cmake -D CMAKE_BUILD_TYPE=Debug -D CMAKE_CXX_STANDARD=17 -D ENABLE_TESTS=ON -D BUILD_TESTING=ON -B build
cmake --build build

[!IMPORTANT] The "Debug" config type is recommended for local testing and development. If the project was already built with a different build type and the user has not requested a change, preserve the existing CMAKE_BUILD_TYPE rather than switching to Debug, and advise the user that switching to Debug is recommended for local testing and development. This configure step replaces the release/installation configure above - running both is unnecessary when developing.

Test executables test_* are generated under build/src/bsoncxx/test and build/src/mongocxx/test:

./build/src/bsoncxx/test/test_bson
./build/src/mongocxx/test/test_driver
./build/src/mongocxx/test/test_unified_format_specs
./build/src/mongocxx/test/test_* # other test executables

[!IMPORTANT] For multi-configuration generators (e.g. "Visual Studio *", "Ninja Multi-Config"), executables appear under a <config>/ subdirectory (e.g. build/src/bsoncxx/test/Debug/test_bson).

Run a test executable with --help to explore available options (e.g. listing test cases and tags, filtering by name/pattern/tags, etc.).

bsoncxx test cases do not require a live MongoDB server. Most mongocxx test cases require a live MongoDB server. test_instance is an exception - it tests instance lifecycle via subprocess and does not connect to a server.

Test executables include:

• test_bson (bsoncxx): bsoncxx tests
• test_driver (mongocxx): mongocxx tests (includes legacy spec tests and prose tests)
• test_unified_format_specs (mongocxx): unified spec test runner
• test_instance (mongocxx): mongocxx::instance lifecycle tests (initialization, singleton behavior)
• test_crud_specs (mongocxx): CRUD spec test runner
• test_gridfs_specs (mongocxx): GridFS spec test runner
• test_command_monitoring_specs (mongocxx): command monitoring spec test runner
• test_client_side_encryption_specs (mongocxx): client-side encryption spec test runner
• test_transactions_specs (mongocxx): transactions spec test runner
• test_retryable_reads_specs (mongocxx): retryable reads spec test runner
• test_read_write_concern_specs (mongocxx): read/write concern spec test runner

Key environment variables controlling test behavior include:

• *_TESTS_PATH: path to data/ subdirectory containing spec test files (e.g. CRUD_LEGACY_TESTS_PATH, COMMAND_MONITORING_TESTS_PATH).
  • Explore calls to run_tests_in_suite() in test code for details.
• MONGOCXX_TEST_*: additional test environment variables (TLS, AWS, Azure, GCP credentials, etc.).
  • Integration tests that connect to a live server default to mongodb://localhost:27017 (hardcoded); no URI env var is required for a standard local setup.
  • MONGODB_URI is read by a small number of tests (e.g. search-index tests in test_driver) that skip themselves when it is unset.
  • Explore calls to getenv_or_fail() and std::getenv() in test code for the full list of variables.

Architecture

The repository provides two libraries, each under src/<library>/:

bsoncxx

A standalone BSON document library with no MongoDB dependency. It wraps the bson library.

mongocxx

The MongoDB C++ Driver. It wraps the mongoc library and depends on the bsoncxx library.

ABI Namespaces

Each library exposes headers under both v_noabi/ (unstable ABI) and v1/ (stable ABI) subdirectories. See etc/coding_guidelines.md for when to use each.

C++ Standard

Minimum is C++11. Polyfills for optional<T> and string_view in bsoncxx::v1::stdx are required up to C++17.

Features in newer standards must be guarded by private macros (e.g. BSONCXX_PRIVATE_INLINE_CXX17).

Before Committing

Always format before committing:

uv run --frozen etc/format.py           # C++ source files.
uv run --frozen etc/ruff-format-all.sh  # Python scripts.
uv run --frozen etc/shfmt-format-all.sh # Shell scripts.

Also run linting when modifying C++ source files:

bash etc/run-clang-tidy.sh

Code Style

See etc/coding_guidelines.md for detailed rules on:

• Directory structure and component design
• ABI versioning and namespace qualification
• Export macros and inline definitions
• Include ordering (IWYU)
• Exception specification (noexcept policy)
• Parameter passing and declaration order