DOCSP-45284 DOCSP-45287 using the C++ driver from CMake and pkg-config

source/include-link.txt

@@ -0,0 +1,228 @@
+.. _cpp-include-link:
+
+===========================================
+Include and Link the Driver in Your Program
+===========================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+Overview
+--------
+
+In this guide, you can learn how to use CMake and ``pkg-config`` to include the {+driver-short+} in your project.
+
+Sample Data
+~~~~~~~~~~~~
+
+The examples on this page use the :github:`view_and_value.cpp </mongo-cxx-driver/blob/master/examples/bsoncxx/view_and_value.cpp>` example program from the {+driver-short+} source code. Obtain the {+driver-short+} source code by following the :ref:`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 {+driver-short+} 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 {+driver-short+} library targets. Examples in the :ref:`CMake <cpp-include-cmake>` section use the ``mongo::bsoncxx_shared`` target, and examples in the :ref:`pkg-config <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.
+
+.. _cpp-include-cmake:
+CMake
+-----
+
+You can use CMake to include the {+driver-short+} in your project. CMake provides the ``find_package`` command, which your project can use to locate the {+driver-short+} once it is installed. Alternatively, your project can use the advanced ``add_subdirectory`` command without installing the {+driver-short+}.
+
+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:
+
+.. code-block:: none
+
+   cmake -Bbuild -DCMAKE_CXX_STANDARD=17 -DCMAKE_PREFIX_PATH=/opt/mongodb/cxx-driver
+
+With Driver Installation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+After installing the {+driver-short+}, you can use CMake's ``find_package`` command to integrate the driver with your project.
+
+.. tip::
+
+   To learn how to install the {+driver-short+}, visit 
+   the following guides:
+
+   - :ref:`cpp-quick-start-download-and-install` to 
+     install from source
+   - :ref:`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``:
+
+.. literalinclude:: /includes/cmake_with_driver_installation.txt
+  :caption: /home/user/project1/CMakeLists.txt
+  :start-after: -- sphinx-include-start --
+
+Then, run the following commands to build your project:
+
+.. code-block:: none
+
+   $ 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:
+
+.. code-block:: none
+
+   $ ./build/view_and_value
+
+The output resembles the following:
+
+.. code-block:: none
+
+   { "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 {+driver-short+}. 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 {+driver-short+} 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``:
+
+.. literalinclude:: /includes/cmake_without_driver_installation.txt
+  :caption: /home/user/project2/CMakeLists.txt
+  :start-after: -- sphinx-include-start --
+
+.. 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:
+
+.. code-block:: none
+
+   $ 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:
+
+.. code-block:: none
+
+   $ ./build/view_and_value
+
+The output resembles the following:
+
+.. code-block:: none
+
+   { "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
+
+.. _cpp-include-pkg-config:
+pkg-config
+----------
+
+If your project is not CMake-based, you can use ``pkg-config`` to integrate the {+driver-short+} 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 {+driver-short+} with pkg-config if you fully install the driver.
+
+The following code uses ``pkg-config`` to include and link the {+driver-short+}. Replace the ``<path-to-mongo-cxx-driver-sources>`` placeholder with the location of the {+driver-short+} source tree on your system:
+
+.. code-block:: none
+
+   $ 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.

source/includes/cmake_with_driver_installation.txt

@@ -0,0 +1,10 @@
+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)

source/includes/cmake_without_driver_installation.txt

@@ -0,0 +1,12 @@
+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)

source/index.txt

@@ -20,6 +20,7 @@ MongoDB C++ Driver
    Security </security>
    Specialized Data Formats </data-formats>
    Advanced Configuration & Installation </advanced-installation>
+   Include & Link the Driver </include-link>
    Thread & Fork Safety </thread-safety>
    API & ABI Versioning </api-abi-versioning>
    What's New </whats-new>
@@ -88,6 +89,12 @@ Advanced Installation Options
 Learn about advanced configuration and installation options
 in the :ref:`cpp-installation-advanced` section.
 
+Include and Link the Driver in Your Program
+-------------------------------------------
+
+Learn how to include and link the driver in your program
+in the :ref:`cpp-include-link` section.
+
 What's New
 ----------
 
@@ -254,4 +261,4 @@ Releases of the mongocxx driver have version numbers like v3.x.y.
 License
 -------
 
-MongoDB C++ drivers are available under the terms of the Apache License, version 2.0.
+MongoDB C++ drivers are available under the terms of the Apache License, version 2.0.