Skip to content

Commit

Permalink
DOCSP-42115 - Cleanup (#53)
Browse files Browse the repository at this point in the history
* wip

* wip

* remove installation pages

* edits, remove buttons

* resolve TODOs

* toc

---------

Co-authored-by: norareidy <[email protected]>
  • Loading branch information
mongoKart and norareidy authored Aug 5, 2024
1 parent 89ef095 commit 5dbee65
Show file tree
Hide file tree
Showing 19 changed files with 454 additions and 720 deletions.
1 change: 0 additions & 1 deletion snooty.toml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ intersphinx = [
]

toc_landing_pages = [
"/installation",
"/api-abi-versioning",
"/get-started",
"/connect",
Expand Down
308 changes: 308 additions & 0 deletions source/advanced-installation.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,308 @@
.. _cpp-installation-advanced:

================================================
Advanced Configuration and Installation Options
================================================

.. contents:: On this page
:local:
:backlinks: none
:depth: 2
:class: singlecol

.. facet::
:name: genre
:values: reference

Additional Options for Integrators
----------------------------------

In the event that you are building the BSON C++ library and/or the C++ driver to
embed with other components and you wish to avoid the potential for collision with
components installed from a standard build or from a distribution package manager,
you can make use of the ``BSONCXX_OUTPUT_BASENAME`` and ``MONGOCXX_OUTPUT_BASENAME``
options to ``cmake``.

.. code-block:: bash

cmake .. \
-DBSONCXX_OUTPUT_BASENAME=custom_bsoncxx \
-DMONGOCXX_OUTPUT_BASENAME=custom_mongocxx

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).

Install with Package Managers
-----------------------------

You can use the following package managers to install the {+driver-short+}:

- :ref:`vcpkg <cpp-install-vcpkg>`
- :ref:`Conan <cpp-install-conan>`
- :ref:`Homebrew <cpp-install-homebrew>`

.. _cpp-install-vcpkg:

Vcpkg Install Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~

If you do not already have Vcpkg installed, install it with the following command:

.. code-block:: bash

$ git clone https://github.com/Microsoft/vcpkg.git
$ cd vcpkg
$ ./bootstrap-vcpkg.sh

Optionally, to install with Visual Studio integration:

.. code-block:: bash

vcpkg integrate install

Install the driver. You may need to ``git pull`` to get the latest version of
the driver.

.. code-block:: bash

$ ./vcpkg install mongo-cxx-driver

You can use the toolchain file, ``vcpkg.cmake``, to instruct CMake where to find
the development files, for example:

.. code-block:: bash

-DCMAKE_TOOLCHAIN_FILE=/<path to vcpkg repo>/vcpkg/scripts/buildsystems/vcpkg.cmake

You can find the header files in:

.. code-block:: none

vcpkg/installed/<CPU ARCHITECTURE>-<OPERATING SYSTEM>/include/

The library files are in:

.. code-block:: none

vcpkg/installed/<CPU ARCHITECTURE>-<OPERATING SYSTEM>/lib/

.. _cpp-install-conan:

Conan Install Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~

Package Specifier: ``mongo-cxx-driver/3.8.0``

If you do not already have Conan installed, then install it and run the Conan
initalization command below:

.. code-block:: bash

$ pip install conan
$ conan profile detect --force

Add the following to your ``conanfile.txt``:

.. code-block:: none

[requires]
mongo-cxx-driver/3.8.0
[generators]
CMakeDeps
CMakeToolchain

Install the driver via Conan, and build your project:

.. code-block:: bash

$ conan install conanfile.txt --output-folder=build --build=missing
$ cmake \
-B build \
-DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake \
-DCMAKE_BUILD_TYPE=Release
$ cmake --build build

.. _cpp-install-homebrew:

Homebrew Install Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MacOS users can use Homebrew to install the C++ driver by running
the following command:

.. code-block:: bash

brew install mongo-cxx-driver

For an Apple Silicon Mac
`````````````````````````

Headers can be found in:

.. code-block:: none

/opt/homebrew/include/mongocxx/v_noabi/
/opt/homebrew/include/bsoncxx/v_noabi/

Library files can be found in:

.. code-block:: none

/opt/homebrew/lib/

For an Intel Mac
`````````````````

Headers can be found in:

.. code-block:: none

/usr/local/include/mongocxx/v_noabi/
/usr/local/include/bsoncxx/v_noabi/

Library files can be found in:

.. code-block:: none

/usr/local/lib/

Install the MongoDB C Driver
----------------------------

The mongocxx driver builds on top of the `MongoDB C driver <https://www.mongodb.com/docs/drivers/c/>`__.

The build of mongocxx-3.9.0 automatically downloads and installs the C driver if the C driver is not detected.
To use an existing install of the C driver, set ``CMAKE_PREFIX_PATH`` to the directory containing the C driver install.

- For mongocxx-3.10.x, libmongoc 1.25.0 or later is required.
- For mongocxx-3.9.x, libmongoc 1.25.0 or later is required.
- For mongocxx-3.8.x, libmongoc 1.24.0 or later is required.
- For mongocxx-3.7.x, libmongoc 1.22.1 or later is required.
- For mongocxx-3.6.x, libmongoc 1.17.0 or later is required.
- For mongocxx-3.5.x, libmongoc 1.15.0 or later is required.
- For mongocxx-3.4.x, libmongoc 1.13.0 or later is required.
- For mongocxx-3.3.x, libmongoc 1.10.1 or later is required.
- For mongocxx-3.2.x, libmongoc 1.9.2 or later is required.
- For mongocxx-3.1.4+, libmongoc 1.7.0 or later is required.
- For mongocxx-3.1.[0-3], libmongoc 1.5.0 or later is required.
- For mongocxx-3.0.x, we recommend the last 1.4.x version of libmongoc

Unless you know that your package manager offers a sufficiently recent version, you
will need to download and build from the source code. Get a tarball from
the `C Driver release <https://github.com/mongodb/mongo-c-driver/releases>`__
page.

Follow the instructions for building from a tarball at
`Installing libmongoc <http://mongoc.org/libmongoc/current/installing.html>`__.

Industry best practices and some regulations require the use of TLS 1.1
or newer. The MongoDB C Driver supports TLS 1.1 on Linux if OpenSSL is
at least version 1.0.1. On macOS and Windows, the C Driver uses native
TLS implementations that support TLS 1.1.

Advanced Configuration (Static Configurations)
----------------------------------------------

The following sub-sections detail advanced options for configuring the C++ driver and/or its
dependencies as static libraries rather than the typical shared libraries. These options will
produce library artifacts that will behave differently. Ensure you have a complete understanding
of the implications of the various linking approaches before utilizing these options.

Configuring with ``mongocxx`` 3.2.x or Newer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Users have the option to build ``mongocxx`` as a static library. **This is not recommended for novice
users.** A user can enable this behavior with the ``-DBUILD_SHARED_LIBS`` option:

.. code-block:: bash

cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DBUILD_SHARED_LIBS=OFF

Configuring with ``mongocxx`` 3.5.0 or Newer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Users have the option to build ``mongocxx`` as both static and shared libraries. A user can enable
this behavior with the ``-DBUILD_SHARED_AND_STATIC_LIBS`` option:

.. code-block:: bash

cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DBUILD_SHARED_AND_STATIC_LIBS=ON

Users have the option to build ``mongocxx`` as a shared library that has statically linked
``libmongoc``. **This is not recommended for novice users.** A user can enable this behavior with the
``-DBUILD_SHARED_LIBS_WITH_STATIC_MONGOC`` option:

.. code-block:: bash

cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DBUILD_SHARED_LIBS_WITH_STATIC_MONGOC=ON

Disabling Tests
---------------

Pass ``-DENABLE_TESTS=OFF`` as a cmake option to disable configuration of test targets.

.. code-block:: bash

cmake .. -DENABLE_TESTS=OFF
cmake --build .. --target help
# No test targets are configured.

Installing to Non-Standard Directories
--------------------------------------

To install the C++ driver to a non-standard directory, specify ``CMAKE_INSTALL_PREFIX`` to the desired
install path:

.. code-block:: bash

cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver

Consider also specifying the ``-DCMAKE_INSTALL_RPATH=`` option to the ``lib`` directory of the install.
This may enable libmongocxx.so to locate libbsoncxx.so:

.. code-block:: bash

cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver \
-DCMAKE_INSTALL_RPATH=$HOME/mongo-cxx-driver/lib

If the C driver is installed to a non-standard directory, specify ``CMAKE_PREFIX_PATH`` to the install
path of the C driver:

.. code-block:: bash

cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_PREFIX_PATH=$HOME/mongo-c-driver \
-DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver

.. note::

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"``

Configuring with ``mongocxx`` 3.1.x or 3.0.x
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Instead of the ``-DCMAKE_PREFIX_PATH`` option, users must specify the ``libmongoc`` installation
directory by using the ``-DLIBMONGOC_DIR`` and ``-DLIBBSON_DIR`` options:

.. code-block:: bash

cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DLIBMONGOC_DIR=$HOME/mongo-c-driver \
-DLIBBSON_DIR=$HOME/mongo-c-driver \
-DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver

Troubleshooting
---------------

.. include:: /includes/troubleshooting/advanced-installation.rst
5 changes: 1 addition & 4 deletions source/get-started.txt
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,4 @@ MongoDB Atlas and query data in your cluster.

Follow this guide to connect a sample C++ application to a MongoDB Atlas
deployment. If you prefer to connect to MongoDB using a different driver or
programming language, see our :driver:`list of official drivers <>`.

.. button:: Next: Download and Install
:uri: /get-started/download-and-install/
programming language, see our :driver:`list of official drivers <>`.
3 changes: 0 additions & 3 deletions source/get-started/connect-to-mongodb.txt
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,3 @@ uses the driver to connect to your MongoDB deployment, runs a query on
the sample data, and prints out the result.

.. include:: /includes/get-started/troubleshoot.rst

.. button:: Next Steps
:uri: /get-started/next-steps/
8 changes: 3 additions & 5 deletions source/get-started/create-a-connection-string.txt
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ The connection string includes the hostname or IP address and
port of your deployment, the authentication mechanism, user credentials
when applicable, and connection options.

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

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

.. include:: /includes/get-started/troubleshoot.rst

.. button:: Next: Connect to MongoDB
:uri: /get-started/connect-to-mongodb/
.. include:: /includes/get-started/troubleshoot.rst
5 changes: 1 addition & 4 deletions source/get-started/create-a-deployment.txt
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,4 @@ After you complete these steps, you have a new free tier MongoDB
deployment on Atlas, database user credentials, and sample data loaded
into your database.

.. include:: /includes/get-started/troubleshoot.rst

.. button:: Next: Create a Connection String
:uri: /get-started/create-a-connection-string/
.. include:: /includes/get-started/troubleshoot.rst
Loading

0 comments on commit 5dbee65

Please sign in to comment.