Skip to content

Commit 5dbee65

Browse files
mongoKartnorareidy
mongoKart
and
norareidy
authored
DOCSP-42115 - Cleanup (#53)
* wip * wip * remove installation pages * edits, remove buttons * resolve TODOs * toc --------- Co-authored-by: norareidy <[email protected]>
1 parent 89ef095 commit 5dbee65

19 files changed

+454
-720
lines changed

‎snooty.toml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@ intersphinx = [
88
]
99

1010
toc_landing_pages = [
11-
"/installation",
1211
"/api-abi-versioning",
1312
"/get-started",
1413
"/connect",

‎source/advanced-installation.txt

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
.. _cpp-installation-advanced:
2+
3+
================================================
4+
Advanced Configuration and Installation Options
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+
Additional Options for Integrators
18+
----------------------------------
19+
20+
In the event that you are building the BSON C++ library and/or the C++ driver to
21+
embed with other components and you wish to avoid the potential for collision with
22+
components installed from a standard build or from a distribution package manager,
23+
you can make use of the ``BSONCXX_OUTPUT_BASENAME`` and ``MONGOCXX_OUTPUT_BASENAME``
24+
options to ``cmake``.
25+
26+
.. code-block:: bash
27+
28+
cmake .. \
29+
-DBSONCXX_OUTPUT_BASENAME=custom_bsoncxx \
30+
-DMONGOCXX_OUTPUT_BASENAME=custom_mongocxx
31+
32+
The above command would produce libraries named ``libcustom_bsoncxx.so`` and ``libcustom_mongocxx.so`` (or with the extension appropriate for the build platform). Those libraries could be placed in a standard system directory or in an alternate location and could be linked to by specifying something like ``-lcustom_mongocxx -lcustom_bsoncxx`` on the linker command line (possibly adjusting the specific flags to those required by your linker).
33+
34+
Install with Package Managers
35+
-----------------------------
36+
37+
You can use the following package managers to install the {+driver-short+}:
38+
39+
- :ref:`vcpkg <cpp-install-vcpkg>`
40+
- :ref:`Conan <cpp-install-conan>`
41+
- :ref:`Homebrew <cpp-install-homebrew>`
42+
43+
.. _cpp-install-vcpkg:
44+
45+
Vcpkg Install Instructions
46+
~~~~~~~~~~~~~~~~~~~~~~~~~~
47+
48+
If you do not already have Vcpkg installed, install it with the following command:
49+
50+
.. code-block:: bash
51+
52+
$ git clone https://github.com/Microsoft/vcpkg.git
53+
$ cd vcpkg
54+
$ ./bootstrap-vcpkg.sh
55+
56+
Optionally, to install with Visual Studio integration:
57+
58+
.. code-block:: bash
59+
60+
vcpkg integrate install
61+
62+
Install the driver. You may need to ``git pull`` to get the latest version of
63+
the driver.
64+
65+
.. code-block:: bash
66+
67+
$ ./vcpkg install mongo-cxx-driver
68+
69+
You can use the toolchain file, ``vcpkg.cmake``, to instruct CMake where to find
70+
the development files, for example:
71+
72+
.. code-block:: bash
73+
74+
-DCMAKE_TOOLCHAIN_FILE=/<path to vcpkg repo>/vcpkg/scripts/buildsystems/vcpkg.cmake
75+
76+
You can find the header files in:
77+
78+
.. code-block:: none
79+
80+
vcpkg/installed/<CPU ARCHITECTURE>-<OPERATING SYSTEM>/include/
81+
82+
The library files are in:
83+
84+
.. code-block:: none
85+
86+
vcpkg/installed/<CPU ARCHITECTURE>-<OPERATING SYSTEM>/lib/
87+
88+
.. _cpp-install-conan:
89+
90+
Conan Install Instructions
91+
~~~~~~~~~~~~~~~~~~~~~~~~~~
92+
93+
Package Specifier: ``mongo-cxx-driver/3.8.0``
94+
95+
If you do not already have Conan installed, then install it and run the Conan
96+
initalization command below:
97+
98+
.. code-block:: bash
99+
100+
$ pip install conan
101+
$ conan profile detect --force
102+
103+
Add the following to your ``conanfile.txt``:
104+
105+
.. code-block:: none
106+
107+
[requires]
108+
mongo-cxx-driver/3.8.0
109+
[generators]
110+
CMakeDeps
111+
CMakeToolchain
112+
113+
Install the driver via Conan, and build your project:
114+
115+
.. code-block:: bash
116+
117+
$ conan install conanfile.txt --output-folder=build --build=missing
118+
$ cmake \
119+
-B build \
120+
-DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake \
121+
-DCMAKE_BUILD_TYPE=Release
122+
$ cmake --build build
123+
124+
.. _cpp-install-homebrew:
125+
126+
Homebrew Install Instructions
127+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128+
129+
MacOS users can use Homebrew to install the C++ driver by running
130+
the following command:
131+
132+
.. code-block:: bash
133+
134+
brew install mongo-cxx-driver
135+
136+
For an Apple Silicon Mac
137+
`````````````````````````
138+
139+
Headers can be found in:
140+
141+
.. code-block:: none
142+
143+
/opt/homebrew/include/mongocxx/v_noabi/
144+
/opt/homebrew/include/bsoncxx/v_noabi/
145+
146+
Library files can be found in:
147+
148+
.. code-block:: none
149+
150+
/opt/homebrew/lib/
151+
152+
For an Intel Mac
153+
`````````````````
154+
155+
Headers can be found in:
156+
157+
.. code-block:: none
158+
159+
/usr/local/include/mongocxx/v_noabi/
160+
/usr/local/include/bsoncxx/v_noabi/
161+
162+
Library files can be found in:
163+
164+
.. code-block:: none
165+
166+
/usr/local/lib/
167+
168+
Install the MongoDB C Driver
169+
----------------------------
170+
171+
The mongocxx driver builds on top of the `MongoDB C driver <https://www.mongodb.com/docs/drivers/c/>`__.
172+
173+
The build of mongocxx-3.9.0 automatically downloads and installs the C driver if the C driver is not detected.
174+
To use an existing install of the C driver, set ``CMAKE_PREFIX_PATH`` to the directory containing the C driver install.
175+
176+
- For mongocxx-3.10.x, libmongoc 1.25.0 or later is required.
177+
- For mongocxx-3.9.x, libmongoc 1.25.0 or later is required.
178+
- For mongocxx-3.8.x, libmongoc 1.24.0 or later is required.
179+
- For mongocxx-3.7.x, libmongoc 1.22.1 or later is required.
180+
- For mongocxx-3.6.x, libmongoc 1.17.0 or later is required.
181+
- For mongocxx-3.5.x, libmongoc 1.15.0 or later is required.
182+
- For mongocxx-3.4.x, libmongoc 1.13.0 or later is required.
183+
- For mongocxx-3.3.x, libmongoc 1.10.1 or later is required.
184+
- For mongocxx-3.2.x, libmongoc 1.9.2 or later is required.
185+
- For mongocxx-3.1.4+, libmongoc 1.7.0 or later is required.
186+
- For mongocxx-3.1.[0-3], libmongoc 1.5.0 or later is required.
187+
- For mongocxx-3.0.x, we recommend the last 1.4.x version of libmongoc
188+
189+
Unless you know that your package manager offers a sufficiently recent version, you
190+
will need to download and build from the source code. Get a tarball from
191+
the `C Driver release <https://github.com/mongodb/mongo-c-driver/releases>`__
192+
page.
193+
194+
Follow the instructions for building from a tarball at
195+
`Installing libmongoc <http://mongoc.org/libmongoc/current/installing.html>`__.
196+
197+
Industry best practices and some regulations require the use of TLS 1.1
198+
or newer. The MongoDB C Driver supports TLS 1.1 on Linux if OpenSSL is
199+
at least version 1.0.1. On macOS and Windows, the C Driver uses native
200+
TLS implementations that support TLS 1.1.
201+
202+
Advanced Configuration (Static Configurations)
203+
----------------------------------------------
204+
205+
The following sub-sections detail advanced options for configuring the C++ driver and/or its
206+
dependencies as static libraries rather than the typical shared libraries. These options will
207+
produce library artifacts that will behave differently. Ensure you have a complete understanding
208+
of the implications of the various linking approaches before utilizing these options.
209+
210+
Configuring with ``mongocxx`` 3.2.x or Newer
211+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
212+
213+
Users have the option to build ``mongocxx`` as a static library. **This is not recommended for novice
214+
users.** A user can enable this behavior with the ``-DBUILD_SHARED_LIBS`` option:
215+
216+
.. code-block:: bash
217+
218+
cmake .. \
219+
-DCMAKE_BUILD_TYPE=Release \
220+
-DBUILD_SHARED_LIBS=OFF
221+
222+
Configuring with ``mongocxx`` 3.5.0 or Newer
223+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
224+
225+
Users have the option to build ``mongocxx`` as both static and shared libraries. A user can enable
226+
this behavior with the ``-DBUILD_SHARED_AND_STATIC_LIBS`` option:
227+
228+
.. code-block:: bash
229+
230+
cmake .. \
231+
-DCMAKE_BUILD_TYPE=Release \
232+
-DBUILD_SHARED_AND_STATIC_LIBS=ON
233+
234+
Users have the option to build ``mongocxx`` as a shared library that has statically linked
235+
``libmongoc``. **This is not recommended for novice users.** A user can enable this behavior with the
236+
``-DBUILD_SHARED_LIBS_WITH_STATIC_MONGOC`` option:
237+
238+
.. code-block:: bash
239+
240+
cmake .. \
241+
-DCMAKE_BUILD_TYPE=Release \
242+
-DBUILD_SHARED_LIBS_WITH_STATIC_MONGOC=ON
243+
244+
Disabling Tests
245+
---------------
246+
247+
Pass ``-DENABLE_TESTS=OFF`` as a cmake option to disable configuration of test targets.
248+
249+
.. code-block:: bash
250+
251+
cmake .. -DENABLE_TESTS=OFF
252+
cmake --build .. --target help
253+
# No test targets are configured.
254+
255+
Installing to Non-Standard Directories
256+
--------------------------------------
257+
258+
To install the C++ driver to a non-standard directory, specify ``CMAKE_INSTALL_PREFIX`` to the desired
259+
install path:
260+
261+
.. code-block:: bash
262+
263+
cmake .. \
264+
-DCMAKE_BUILD_TYPE=Release \
265+
-DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver
266+
267+
Consider also specifying the ``-DCMAKE_INSTALL_RPATH=`` option to the ``lib`` directory of the install.
268+
This may enable libmongocxx.so to locate libbsoncxx.so:
269+
270+
.. code-block:: bash
271+
272+
cmake .. \
273+
-DCMAKE_BUILD_TYPE=Release \
274+
-DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver \
275+
-DCMAKE_INSTALL_RPATH=$HOME/mongo-cxx-driver/lib
276+
277+
If the C driver is installed to a non-standard directory, specify ``CMAKE_PREFIX_PATH`` to the install
278+
path of the C driver:
279+
280+
.. code-block:: bash
281+
282+
cmake .. \
283+
-DCMAKE_BUILD_TYPE=Release \
284+
-DCMAKE_PREFIX_PATH=$HOME/mongo-c-driver \
285+
-DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver
286+
287+
.. note::
288+
289+
If you need multiple paths in a CMake PATH variable, separate them with a semicolon like this: ``-DCMAKE_PREFIX_PATH="/your/cdriver/prefix;/some/other/path"``
290+
291+
Configuring with ``mongocxx`` 3.1.x or 3.0.x
292+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
293+
294+
Instead of the ``-DCMAKE_PREFIX_PATH`` option, users must specify the ``libmongoc`` installation
295+
directory by using the ``-DLIBMONGOC_DIR`` and ``-DLIBBSON_DIR`` options:
296+
297+
.. code-block:: bash
298+
299+
cmake .. \
300+
-DCMAKE_BUILD_TYPE=Release \
301+
-DLIBMONGOC_DIR=$HOME/mongo-c-driver \
302+
-DLIBBSON_DIR=$HOME/mongo-c-driver \
303+
-DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver
304+
305+
Troubleshooting
306+
---------------
307+
308+
.. include:: /includes/troubleshooting/advanced-installation.rst

‎source/get-started.txt

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,4 @@ MongoDB Atlas and query data in your cluster.
4242

4343
Follow this guide to connect a sample C++ application to a MongoDB Atlas
4444
deployment. If you prefer to connect to MongoDB using a different driver or
45-
programming language, see our :driver:`list of official drivers <>`.
46-
47-
.. button:: Next: Download and Install
48-
:uri: /get-started/download-and-install/
45+
programming language, see our :driver:`list of official drivers <>`.

‎source/get-started/connect-to-mongodb.txt

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,3 @@ uses the driver to connect to your MongoDB deployment, runs a query on
9292
the sample data, and prints out the result.
9393

9494
.. include:: /includes/get-started/troubleshoot.rst
95-
96-
.. button:: Next Steps
97-
:uri: /get-started/next-steps/

‎source/get-started/create-a-connection-string.txt

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ The connection string includes the hostname or IP address and
1313
port of your deployment, the authentication mechanism, user credentials
1414
when applicable, and connection options.
1515

16-
.. TODO: link to instructions on connecting to local deployment in Connection guide
16+
To connect to an instance or deployment not hosted on Atlas, see the
17+
:ref:`cpp-connection-targets` guide.
1718

1819
.. procedure::
1920
:style: connected
@@ -58,7 +59,4 @@ when applicable, and connection options.
5859
After completing these steps, you have a connection string that
5960
corresponds to your Atlas cluster.
6061

61-
.. include:: /includes/get-started/troubleshoot.rst
62-
63-
.. button:: Next: Connect to MongoDB
64-
:uri: /get-started/connect-to-mongodb/
62+
.. include:: /includes/get-started/troubleshoot.rst

‎source/get-started/create-a-deployment.txt

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,4 @@ After you complete these steps, you have a new free tier MongoDB
2626
deployment on Atlas, database user credentials, and sample data loaded
2727
into your database.
2828

29-
.. include:: /includes/get-started/troubleshoot.rst
30-
31-
.. button:: Next: Create a Connection String
32-
:uri: /get-started/create-a-connection-string/
29+
.. include:: /includes/get-started/troubleshoot.rst

0 commit comments

Comments
 (0)