-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* wip * wip * remove installation pages * edits, remove buttons * resolve TODOs * toc --------- Co-authored-by: norareidy <[email protected]>
- Loading branch information
Showing
19 changed files
with
454 additions
and
720 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.