DOCSP-42115 - Cleanup

snooty.toml

@@ -8,7 +8,6 @@ intersphinx = [
 ]
 
 toc_landing_pages = [
-    "/installation",
     "/api-abi-versioning",
     "/get-started",
     "/connect",

source/advanced-installation.txt

@@ -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

source/get-started.txt

@@ -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 <>`.

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

@@ -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/

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

@@ -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
@@ -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

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

@@ -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