Skip to content

Commit 94b84ba

Browse files
rcsanchez97norareidy
rcsanchez97
and
norareidy
authored
DOCSP-45284 DOCSP-45287 using the C++ driver from CMake and pkg-config (#88)
Co-authored-by: Nora Reidy <[email protected]>
1 parent 54a1187 commit 94b84ba

File tree

4 files changed

+258
-1
lines changed

4 files changed

+258
-1
lines changed

‎source/include-link.txt

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
.. _cpp-include-link:
2+
3+
===========================================
4+
Include and Link the Driver in Your Program
5+
===========================================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
Overview
18+
--------
19+
20+
In this guide, you can learn how to use CMake and ``pkg-config`` to include the {+driver-short+} in your project.
21+
22+
Sample Data
23+
~~~~~~~~~~~~
24+
25+
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.
26+
27+
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.
28+
29+
You do not need to run this program on a MongoDB server.
30+
31+
Library References
32+
~~~~~~~~~~~~~~~~~~
33+
34+
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:
35+
36+
- CMake:
37+
- ``mongo::bsoncxx_shared``
38+
- ``mongo::mongoccxx_shared``
39+
- ``mongo::bsoncxx_static``
40+
- ``mongo::mongoccxx_static``
41+
- pkg-config:
42+
- ``libbsoncxx``
43+
- ``libmongocxx``
44+
- ``libbsoncxx-static``
45+
- ``libmongocxx-static``
46+
47+
The availability of targets depends on the particular installation method.
48+
49+
.. _cpp-include-cmake:
50+
CMake
51+
-----
52+
53+
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+}.
54+
55+
Troubleshooting
56+
~~~~~~~~~~~~~~~~~~~~~~~~
57+
58+
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:
59+
60+
- If your compiler does not default to at least C++17, use the ``-DCMAKE_CXX_STANDARD=17`` CMake option.
61+
62+
- If you installed the driver to a non-standard location, specify the ``-DCMAKE_PREFIX_PATH=/<path-to-mongo-cxx-driver-installation>`` option. For example:
63+
64+
.. code-block:: none
65+
66+
cmake -Bbuild -DCMAKE_CXX_STANDARD=17 -DCMAKE_PREFIX_PATH=/opt/mongodb/cxx-driver
67+
68+
With Driver Installation
69+
~~~~~~~~~~~~~~~~~~~~~~~~
70+
71+
After installing the {+driver-short+}, you can use CMake's ``find_package`` command to integrate the driver with your project.
72+
73+
.. tip::
74+
75+
To learn how to install the {+driver-short+}, visit
76+
the following guides:
77+
78+
- :ref:`cpp-quick-start-download-and-install` to
79+
install from source
80+
- :ref:`cpp-installation-advanced` to install from
81+
packages
82+
83+
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``:
84+
85+
.. literalinclude:: /includes/cmake_with_driver_installation.txt
86+
:caption: /home/user/project1/CMakeLists.txt
87+
:start-after: -- sphinx-include-start --
88+
89+
Then, run the following commands to build your project:
90+
91+
.. code-block:: none
92+
93+
$ cd /home/user/project1
94+
$ cmake -Bbuild
95+
$ cmake --build build
96+
97+
These commands return information about the build process. After the build completes, run the executable produced in the preceding step:
98+
99+
.. code-block:: none
100+
101+
$ ./build/view_and_value
102+
103+
The output resembles the following:
104+
105+
.. code-block:: none
106+
107+
{ "team" : "platforms", "id" : { "$oid" : "66f4be6fef9eb8b9240619f0" }, "members" : [ "tyler", "jason", "drew", "sam", "ernie", "john", "mark", "crystal" ] }
108+
Got key, key = team
109+
Got String!
110+
Got key, key = id
111+
Got ObjectId!
112+
Got key, key = members
113+
Got Array!
114+
array element: tyler
115+
array element: jason
116+
array element: drew
117+
array element: sam
118+
array element: ernie
119+
array element: john
120+
array element: mark
121+
array element: crystal
122+
as expected, we have a team
123+
document has 3 keys.
124+
document keys are:
125+
team
126+
id
127+
members
128+
129+
Without Driver Installation
130+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
131+
132+
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.
133+
134+
.. note::
135+
136+
You may need to adjust build flags for your project to
137+
accommodate this approach. Your project's invocation of CMake must include any flags or
138+
options that are normally passed to the {+driver-short+} as part of its build.
139+
140+
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``:
141+
142+
.. literalinclude:: /includes/cmake_without_driver_installation.txt
143+
:caption: /home/user/project2/CMakeLists.txt
144+
:start-after: -- sphinx-include-start --
145+
146+
.. note::
147+
148+
The preceding example uses the ``bsoncxx_shared`` CMake target without the ``mongo::`` namespace. The namespace
149+
is added as part of the CMake module installation, which is not performed
150+
in this approach.
151+
152+
Then, run the following commands to build your project:
153+
154+
.. code-block:: none
155+
156+
$ cd /home/user/project1
157+
$ cmake -Bbuild
158+
$ cmake --build build
159+
160+
These commands return information about the build process. After the build completes, run the executable produced in the preceding step:
161+
162+
.. code-block:: none
163+
164+
$ ./build/view_and_value
165+
166+
The output resembles the following:
167+
168+
.. code-block:: none
169+
170+
{ "team" : "platforms", "id" : { "$oid" : "67207dcf532837a4470cc090" }, "members" : [ "tyler", "jason", "drew", "sam", "ernie", "john", "mark", "crystal" ] }
171+
Got key, key = team
172+
Got String!
173+
Got key, key = id
174+
Got ObjectId!
175+
Got key, key = members
176+
Got Array!
177+
array element: tyler
178+
array element: jason
179+
array element: drew
180+
array element: sam
181+
array element: ernie
182+
array element: john
183+
array element: mark
184+
array element: crystal
185+
as expected, we have a team
186+
document has 3 keys.
187+
document keys are:
188+
team
189+
id
190+
members
191+
192+
.. _cpp-include-pkg-config:
193+
pkg-config
194+
----------
195+
196+
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.
197+
198+
You can only use the {+driver-short+} with pkg-config if you fully install the driver.
199+
200+
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:
201+
202+
.. code-block:: none
203+
204+
$ 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
205+
$ ./view_and_value
206+
{ "team" : "platforms", "id" : { "$oid" : "67207262672b96dc3b0fc150" }, "members" : [ "tyler", "jason", "drew", "sam", "ernie", "john", "mark", "crystal" ] }
207+
Got key, key = team
208+
Got String!
209+
Got key, key = id
210+
Got ObjectId!
211+
Got key, key = members
212+
Got Array!
213+
array element: tyler
214+
array element: jason
215+
array element: drew
216+
array element: sam
217+
array element: ernie
218+
array element: john
219+
array element: mark
220+
array element: crystal
221+
as expected, we have a team
222+
document has 3 keys.
223+
document keys are:
224+
team
225+
id
226+
members
227+
228+
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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
cmake_minimum_required (VERSION 3.15)
2+
project (builder_basic LANGUAGES CXX)
3+
4+
find_package (bsoncxx 4.0 REQUIRED)
5+
6+
add_executable (view_and_value /<path-to-mongo-cxx-driver-sources>/examples/bsoncxx/view_and_value.cpp)
7+
8+
# we need target_include_directories because view_and_value.cpp refers to a common example header
9+
target_include_directories (view_and_value PRIVATE /<path-to-mongo-cxx-driver-sources>)
10+
target_link_libraries (view_and_value PRIVATE mongo::bsoncxx_shared)

‎source/includes/cmake_without_driver_installation.txt

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
cmake_minimum_required (VERSION 3.15)
2+
project (builder_basic LANGUAGES CXX)
3+
4+
# specify a source_dir which is out-of-tree from this project, so also specify bin_dir
5+
add_subdirectory (/<path-to-mongo-cxx-driver-sources> ./build/mongo-cxx-driver)
6+
7+
add_executable (view_and_value /<path-to-mongo-cxx-driver-sources>/examples/bsoncxx/view_and_value.cpp)
8+
9+
# we need target_include_directories because view_and_value.cpp refers to a common example header
10+
target_include_directories (view_and_value PRIVATE /<path-to-mongo-cxx-driver-sources>)
11+
# no mongo:: namespace prefix, since the targets are use directly without installation
12+
target_link_libraries (view_and_value PRIVATE bsoncxx_shared)

‎source/index.txt

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ MongoDB C++ Driver
2121
Security </security>
2222
Specialized Data Formats </data-formats>
2323
Advanced Configuration & Installation </advanced-installation>
24+
Include & Link the Driver </include-link>
2425
Thread & Fork Safety </thread-safety>
2526
API & ABI Versioning </api-abi-versioning>
2627
What's New </whats-new>
@@ -95,6 +96,12 @@ Advanced Installation Options
9596
Learn about advanced configuration and installation options
9697
in the :ref:`cpp-installation-advanced` section.
9798

99+
Include and Link the Driver in Your Program
100+
-------------------------------------------
101+
102+
Learn how to include and link the driver in your program
103+
in the :ref:`cpp-include-link` section.
104+
98105
What's New
99106
----------
100107

@@ -261,4 +268,4 @@ Releases of the mongocxx driver have version numbers like v3.x.y.
261268
License
262269
-------
263270

264-
MongoDB C++ drivers are available under the terms of the Apache License, version 2.0.
271+
MongoDB C++ drivers are available under the terms of the Apache License, version 2.0.

0 commit comments

Comments
 (0)