From bfafb64580ed584f453e8e36a9be533cc4017dd0 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 2 Aug 2024 12:32:34 -0500 Subject: [PATCH 1/6] wip --- source/get-started.txt | 5 +- source/get-started/download-and-install.txt | 6 +- .../{ => get-started}/polyfill-selection.txt | 9 +- source/index.txt | 128 +++++++++++++----- source/installation/windows.txt | 73 ---------- 5 files changed, 105 insertions(+), 116 deletions(-) rename source/{ => get-started}/polyfill-selection.txt (95%) diff --git a/source/get-started.txt b/source/get-started.txt index d3799cf3..a2ed3b5a 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -20,6 +20,7 @@ Get Started with the C++ Driver .. toctree:: + /get-started/polyfill-selection/ /get-started/download-and-install/ /get-started/create-a-deployment/ /get-started/create-a-connection-string/ @@ -44,5 +45,5 @@ 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/ \ No newline at end of file +.. button:: Next: Choose a C++17 Polyfill + :uri: /get-started/polyfill-selection/ \ No newline at end of file diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt index c3ff5914..9b02a13f 100644 --- a/source/get-started/download-and-install.txt +++ b/source/get-started/download-and-install.txt @@ -66,9 +66,9 @@ Download and Install This command instructs CMake to install ``mongocxx`` into the ``C:\mongo-cxx-driver`` directory. Replace the following placeholder values: - - ````: the path to your CMake executable - - ````: your Visual Studio version number - - ````: the year corresponding to your Visual Studio version + - ````: The path to your CMake executable + - ````: Your Visual Studio version number + - ````: The year corresponding to your Visual Studio version .. step:: Build and install the driver diff --git a/source/polyfill-selection.txt b/source/get-started/polyfill-selection.txt similarity index 95% rename from source/polyfill-selection.txt rename to source/get-started/polyfill-selection.txt index 8e9fa6b1..358e0969 100644 --- a/source/polyfill-selection.txt +++ b/source/get-started/polyfill-selection.txt @@ -1,8 +1,8 @@ .. _cpp-polyfill-selection: -========================= -Choosing a C++17 Polyfill -========================= +======================= +Choose a C++17 Polyfill +======================= .. contents:: On this page :local: @@ -65,3 +65,6 @@ selection behavior. .. warning:: The choice of polyfill library has a direct impact on the public API and ABI for the mongocxx library. Changing the polyfill can lead to both source-breaking changes (during compilation) and binary-breaking changes (during linking or execution). To limit reliance on polyfill-specific configuration or behavior, avoid using ``stdx::string_view`` and ``stdx::optional`` with non-mongocxx library interfaces. + +.. button:: Next: Download and Install + :uri: /get-started/download-and-install/ \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index 112ec3e4..d25116b0 100644 --- a/source/index.txt +++ b/source/index.txt @@ -18,7 +18,6 @@ MongoDB C++ Driver Get Started /connect - /polyfill-selection /installation /read /write @@ -42,12 +41,100 @@ MongoDB C++ Driver API Documentation Driver Source -Welcome to the MongoDB C++ driver. On this site, you'll find documentation -to help you get the most from MongoDB and C++. If you're just starting -out, take a look at these pages first: +Overview +-------- + +Welcome to the documentation site for the official {+driver-long+}. + +Get Started +----------- + +Learn how to install the driver, establish a connection to MongoDB, and begin +working with data in the :ref:`cpp-get-started` tutorial. + +Connect to MongoDB +------------------ + +Learn how to create and configure a connection to a MongoDB deployment +in the :ref:`cpp-connect` section. + +Databases and Collections +------------------------- + +Learn how to use the {+driver-short+} to work with MongoDB databases and collections +in the :ref:`cpp-databases-collections` section. + +Write Data to MongoDB +--------------------- + +Learn how you can write data to MongoDB in the :ref:`cpp-write` section. + +Read Data from MongoDB +---------------------- + +Learn how you can retrieve data from MongoDB in the :ref:`cpp-read` section. + +Optimize Queries with Indexes +----------------------------- + +Learn how to work with common types of indexes in the :ref:`cpp-indexes` +section. + +Transform Your Data with Aggregation +------------------------------------ + +Learn how to use the {+driver-short+} to perform aggregation operations in the +:ref:`cpp-aggregation` section. + +Secure Your Data +---------------- + +Learn about ways you can authenticate your application and encrypt your data in +the :ref:`cpp-security` section. + +Specialized Data Formats +------------------------ + +Learn how to work with specialized data formats and custom types in the +:ref:`cpp-data-formats` section. + +What's New +---------- + +For a list of new features and changes in each version, see the :ref:`cpp-whats-new` +section. + +Upgrade {+driver-short+} Versions +--------------------------- + +Learn what changes you might need to make to your application to upgrade driver versions +in the :ref:`cpp-upgrade` section. + +Previous Versions +----------------- + +For documentation on versions of the driver v3.9.x and earlier, see the +:ref:`cpp-previous-versions` section. + +Issues & Help +------------- + +Learn how to report bugs, contribute to the driver, and find help in the +:ref:`cpp-issues-help` section. + +Compatibility +------------- + +For compatibility tables that show the recommended {+driver-short+} +version to use for specific C++ and {+mdb-server+} versions, see the +:ref:`cpp-compatibility` section. + +API Documentation +----------------- + +For detailed information about types and methods in the {+driver-short+}, see +the `{+driver-short+} API documentation <{+api-root+}>`__. -- :ref:`Installing mongocxx ` -- :ref:`Quick-start tutorial ` Driver Status by Family and Version ----------------------------------- @@ -145,35 +232,6 @@ Releases of the mongocxx driver have version numbers like v3.x.y. There were no v2.x.y C++ drivers to avoid confusion with the deprecated legacy-0.0-26compat-2.x.y drivers. -Compatibility -------------- - -MongoDB Compatibility -~~~~~~~~~~~~~~~~~~~~~ - -The following compatibility table specifies the recommended version or versions -of the MongoDB C++ driver for use with a specific version of MongoDB. - -The first column lists the driver version. - -.. sharedinclude:: dbx/lifecycle-schedule-callout.rst - -.. include:: /includes/mongodb-compatibility-table-cxx.rst - -The driver does not support older versions of MongoDB. - -Language Compatibility -~~~~~~~~~~~~~~~~~~~~~~ - -The following compatibility table specifies the recommended version or versions -of the MongoDB C++ driver for use with a specific version of C++. - -The first column lists the driver version. - -.. include:: /includes/language-compatibility-table-cxx.rst - -For more information on how to read the compatibility tables, see our guide on `MongoDB Compatibility Tables `__. - .. include:: /includes/help-links-cxx.rst License diff --git a/source/installation/windows.txt b/source/installation/windows.txt index 07085f87..fc87a93b 100644 --- a/source/installation/windows.txt +++ b/source/installation/windows.txt @@ -1,69 +1,3 @@ -.. _cpp-installation-windows: - -======================= -Installation on Windows -======================= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -Step 1: Choose a C++17 polyfill -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First, :ref:`choose a C++17 polyfill library `. - -Step 2: Download the latest version of the mongocxx driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The most reliable starting point for building the mongocxx driver is the latest -release tarball. - -The `mongocxx releases `__ -page will have links to the release tarball for the version you wish you install. For -example, to download version {+full-version+}: - -.. code-block:: bash - - curl -OL https://github.com/mongodb/mongo-cxx-driver/releases/download/r{+full-version+}/mongo-cxx-driver-r{+full-version+}.tar.gz - tar -xzf mongo-cxx-driver-r{+full-version+}.tar.gz - cd mongo-cxx-driver-r{+full-version+}/build - -Make sure you change to the ``build`` directory of whatever source tree you -obtain. - -Step 3: Configure the driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -On Windows, the C++ driver is configured as follows (adjusting the path of the CMake executable as appropriate to your system): - -.. code-block:: bash - - 'C:\Program Files (x86)\CMake\bin\cmake.exe' .. \ - -G "Visual Studio 14 2015" -A "x64" \ - -DBOOST_ROOT=C:\local\boost_1_60_0 \ - -DCMAKE_INSTALL_PREFIX=C:\mongo-cxx-driver - -The example above assumes: - -- Boost is found in ``C:\local\boost_1_60_0``. -- ``mongocxx`` is to be installed into ``C:\mongo-cxx-driver``. - -To build with Visual Studio 2017 without a C++17 polyfill, configure as follows: - -.. code-block:: bash - - 'C:\Program Files (x86)\CMake\bin\cmake.exe' .. \ - -G "Visual Studio 15 2017" -A "x64" \ - -DCMAKE_CXX_STANDARD=17 \ - -DCMAKE_INSTALL_PREFIX=C:\mongo-cxx-driver \ - Configuring with ``mongocxx`` 3.7.0 and Older ````````````````````````````````````````````` @@ -82,7 +16,6 @@ configure with additional options: -DCMAKE_INSTALL_PREFIX=C:\mongo-cxx-driver \ Configuring with ``mongocxx`` 3.1.x or 3.0.x -````````````````````````````````````````````` .. code-block:: bash @@ -90,15 +23,9 @@ Configuring with ``mongocxx`` 3.1.x or 3.0.x -DLIBMONGOC_DIR=C:\mongo-c-driver \ -DCMAKE_INSTALL_PREFIX=C:\mongo-cxx-driver -Step 4: Build and install the driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Build and install the driver. Use ``--config`` to select a build configuration (e.g. ``Debug``, ``RelWithDebInfo``, ``Release``): -.. code-block:: bash - cmake --build . --config RelWithDebInfo - cmake --build . --target install --config RelWithDebInfo The driver can be uninstalled at a later time in one of two ways. First, the uninstall target can be called: From b87b056893fae8800713137f4333c5128790c5ce Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 2 Aug 2024 13:20:18 -0500 Subject: [PATCH 2/6] wip --- .../troubleshooting/advanced-installation.rst | 165 +++++++++++++++++ source/index.txt | 12 +- source/installation/advanced.txt | 167 +----------------- 3 files changed, 174 insertions(+), 170 deletions(-) create mode 100644 source/includes/troubleshooting/advanced-installation.rst diff --git a/source/includes/troubleshooting/advanced-installation.rst b/source/includes/troubleshooting/advanced-installation.rst new file mode 100644 index 00000000..b7fc6938 --- /dev/null +++ b/source/includes/troubleshooting/advanced-installation.rst @@ -0,0 +1,165 @@ +Fixing the ``Library not loaded`` Error on macOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Applications linking to a non-standard directory installation may encounter an error loading the C++ driver at runtime. Example: + +.. code-block:: bash + + # Tell pkg-config where to find C++ driver installation. + export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig + clang++ app.cpp -std=c++11 $(pkg-config --cflags --libs libmongocxx) -o ./app.out + ./app.out + # Prints the following error: + # dyld[3217]: Library not loaded: '@rpath/libmongocxx._noabi.dylib' + # Referenced from: '/Users/kevin.albertson/code/app.out' + # Reason: tried: '/usr/local/lib/libmongocxx._noabi.dylib' (no such file), '/usr/lib/libmongocxx._noabi.dylib' (no such file) + # zsh: abort ./app.out + +The default ``install name`` of the C++ driver on macOS includes ``@rpath``: + +.. code-block:: bash + + otool -D $HOME/mongo-cxx-driver/lib/libmongocxx.dylib + # Prints: + # /Users/kevin.albertson/mongo-cxx-driver/lib/libmongocxx.dylib: + # @rpath/libmongocxx._noabi.dylib + +Including ``@rpath`` in the install name allows linking applications to control the list of search paths for the library. + +``app.out`` includes the load command for ``@rpath/libmongocxx._noabi.dylib``. ``app.out`` does not have entries to substitute for ``@rpath``. + +There are several ways to consider solving this on macOS: + +Pass ``DYLD_FALLBACK_LIBRARY_PATH`` to the directory containing the C++ driver libraries: + +.. code-block:: bash + + DYLD_FALLBACK_LIBRARY_PATH=$HOME/mongo-cxx-driver/lib ./app.out + # Prints "successfully connected with C++ driver" + +Alternatively, the linker option ``-Wl,-rpath`` can be passed to add entries to substitute for ``@rpath``: + +.. code-block:: bash + + # Tell pkg-config where to find C++ driver installation. + export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig + # Pass the linker option -rpath to set an rpath in the final executable. + clang++ app.cpp -std=c++11 -Wl,-rpath,$HOME/mongo-cxx-driver/lib $(pkg-config --cflags --libs libmongocxx) -o ./app.out + ./app.out + # Prints "successfully connected with C++ driver" + +If building the application with cmake, the `Default RPATH settings `__ include the full RPATH to all used libraries in the build tree. However, when installing, cmake will clear the RPATH of these targets so they are installed with an empty RPATH. This may result in a ``Library not loaded`` error after install. + +Example: + +.. code-block:: bash + + # Build application ``app`` using the C++ driver from a non-standard install. + cmake \ + -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \ + -DCMAKE_INSTALL_PREFIX=$HOME/app \ + -DCMAKE_CXX_STANDARD=11 \ + -Bcmake-build -S. + cmake --build cmake-build --target app.out + # Running app.out from build tree includes rpath to C++ driver. + ./cmake-build ./cmake-build/app.out + # Prints: "successfully connected with C++ driver" + + cmake --build cmake-build --target install + # Running app.out from install tree does not include rpath to C++ driver. + $HOME/app/bin/app.out + # Prints "Library not loaded" error. + +Consider setting ``-DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE`` so the rpath for the executable is kept in the install target. + +.. code-block:: bash + + # Build application ``app`` using the C++ driver from a non-standard install. + # Use CMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE to keep rpath entry on installed app. + cmake \ + -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \ + -DCMAKE_INSTALL_PREFIX=$HOME/app \ + -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE \ + -DCMAKE_CXX_STANDARD=11 \ + -Bcmake-build -S. + + cmake --build cmake-build --target install + $HOME/app/bin/app.out + # Prints "successfully connected with C++ driver" + +See the cmake documentation for `RPATH handling `__ for more information. + +Fixing the "cannot open shared object file" Error on Linux +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Applications linking to a non-standard directory installation may encounter an error loading the C++ driver at runtime. Example: + +.. code-block:: bash + + # Tell pkg-config where to find C++ driver installation. + export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig + g++ -std=c++11 app.cpp $(pkg-config --cflags --libs libmongocxx) -o ./app.out + ./app.out + # Prints the following error: + # ./app.out: error while loading shared libraries: libmongocxx.so._noabi: cannot open shared object file: No such file or directory + +There are several ways to consider solving this on Linux: + +Pass ``LD_LIBRARY_PATH`` to the directory containing the C++ driver libraries: + +.. code-block:: bash + + LD_LIBRARY_PATH=$HOME/mongo-cxx-driver/lib ./app.out + # Prints "successfully connected with C++ driver" + +Alternatively, the linker option ``-Wl,-rpath`` can be passed to add ``rpath`` entries: + +.. code-block:: bash + + # Tell pkg-config where to find C++ driver installation. + export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig + # Pass the linker option -rpath to set an rpath in the final executable. + g++ app.cpp -std=c++11 -Wl,-rpath,$HOME/mongo-cxx-driver/lib $(pkg-config --cflags --libs libmongocxx) -o ./app.out + ./app.out + # Prints "successfully connected with C++ driver" + +If building the application with cmake, the `Default RPATH settings `__ include the full RPATH to all used libraries in the build tree. However, when installing, cmake will clear the RPATH of these targets so they are installed with an empty RPATH. This may result in a ``Library not loaded`` error after install. + +Example: + +.. code-block:: bash + + # Build application ``app`` using the C++ driver from a non-standard install. + cmake \ + -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \ + -DCMAKE_INSTALL_PREFIX=$HOME/app \ + -DCMAKE_CXX_STANDARD=11 \ + -Bcmake-build -S. + cmake --build cmake-build --target app.out + # Running app.out from build tree includes rpath to C++ driver. + ./cmake-build ./cmake-build/app.out + # Prints: "successfully connected with C++ driver" + + cmake --build cmake-build --target install + # Running app.out from install tree does not include rpath to C++ driver. + $HOME/app/bin/app.out + # Prints "cannot open shared object file" error. + +Consider setting ``-DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE`` so the rpath for the executable is kept in the install target. + +.. code-block:: bash + + # Build application ``app`` using the C++ driver from a non-standard install. + # Use CMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE to keep rpath entry on installed app. + cmake \ + -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \ + -DCMAKE_INSTALL_PREFIX=$HOME/app \ + -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE \ + -DCMAKE_CXX_STANDARD=11 \ + -Bcmake-build -S. + + cmake --build cmake-build --target install + $HOME/app/bin/app.out + # Prints "successfully connected with C++ driver" + +See the cmake documentation for `RPATH handling `__ for more information. diff --git a/source/index.txt b/source/index.txt index d25116b0..bb531225 100644 --- a/source/index.txt +++ b/source/index.txt @@ -21,8 +21,8 @@ MongoDB C++ Driver /installation /read /write - /aggregation /indexes + /aggregation /security /data-formats /configuration @@ -64,16 +64,16 @@ Databases and Collections Learn how to use the {+driver-short+} to work with MongoDB databases and collections in the :ref:`cpp-databases-collections` section. -Write Data to MongoDB ---------------------- - -Learn how you can write data to MongoDB in the :ref:`cpp-write` section. - Read Data from MongoDB ---------------------- Learn how you can retrieve data from MongoDB in the :ref:`cpp-read` section. +Write Data to MongoDB +--------------------- + +Learn how you can write data to MongoDB in the :ref:`cpp-write` section. + Optimize Queries with Indexes ----------------------------- diff --git a/source/installation/advanced.txt b/source/installation/advanced.txt index 446ffe23..c480d5a5 100644 --- a/source/installation/advanced.txt +++ b/source/installation/advanced.txt @@ -164,168 +164,7 @@ directory by using the ``-DLIBMONGOC_DIR`` and ``-DLIBBSON_DIR`` options: -DLIBBSON_DIR=$HOME/mongo-c-driver \ -DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver -Fixing the ``Library not loaded`` error on macOS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Applications linking to a non-standard directory installation may encounter an error loading the C++ driver at runtime. Example: - -.. code-block:: bash - - # Tell pkg-config where to find C++ driver installation. - export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig - clang++ app.cpp -std=c++11 $(pkg-config --cflags --libs libmongocxx) -o ./app.out - ./app.out - # Prints the following error: - # dyld[3217]: Library not loaded: '@rpath/libmongocxx._noabi.dylib' - # Referenced from: '/Users/kevin.albertson/code/app.out' - # Reason: tried: '/usr/local/lib/libmongocxx._noabi.dylib' (no such file), '/usr/lib/libmongocxx._noabi.dylib' (no such file) - # zsh: abort ./app.out - -The default ``install name`` of the C++ driver on macOS includes ``@rpath``: - -.. code-block:: bash - - otool -D $HOME/mongo-cxx-driver/lib/libmongocxx.dylib - # Prints: - # /Users/kevin.albertson/mongo-cxx-driver/lib/libmongocxx.dylib: - # @rpath/libmongocxx._noabi.dylib - -Including ``@rpath`` in the install name allows linking applications to control the list of search paths for the library. - -``app.out`` includes the load command for ``@rpath/libmongocxx._noabi.dylib``. ``app.out`` does not have entries to substitute for ``@rpath``. - -There are several ways to consider solving this on macOS: - -Pass ``DYLD_FALLBACK_LIBRARY_PATH`` to the directory containing the C++ driver libraries: - -.. code-block:: bash - - DYLD_FALLBACK_LIBRARY_PATH=$HOME/mongo-cxx-driver/lib ./app.out - # Prints "successfully connected with C++ driver" - -Alternatively, the linker option ``-Wl,-rpath`` can be passed to add entries to substitute for ``@rpath``: - -.. code-block:: bash - - # Tell pkg-config where to find C++ driver installation. - export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig - # Pass the linker option -rpath to set an rpath in the final executable. - clang++ app.cpp -std=c++11 -Wl,-rpath,$HOME/mongo-cxx-driver/lib $(pkg-config --cflags --libs libmongocxx) -o ./app.out - ./app.out - # Prints "successfully connected with C++ driver" - -If building the application with cmake, the `Default RPATH settings `__ include the full RPATH to all used libraries in the build tree. However, when installing, cmake will clear the RPATH of these targets so they are installed with an empty RPATH. This may result in a ``Library not loaded`` error after install. - -Example: - -.. code-block:: bash - - # Build application ``app`` using the C++ driver from a non-standard install. - cmake \ - -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \ - -DCMAKE_INSTALL_PREFIX=$HOME/app \ - -DCMAKE_CXX_STANDARD=11 \ - -Bcmake-build -S. - cmake --build cmake-build --target app.out - # Running app.out from build tree includes rpath to C++ driver. - ./cmake-build ./cmake-build/app.out - # Prints: "successfully connected with C++ driver" - - cmake --build cmake-build --target install - # Running app.out from install tree does not include rpath to C++ driver. - $HOME/app/bin/app.out - # Prints "Library not loaded" error. - -Consider setting ``-DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE`` so the rpath for the executable is kept in the install target. - -.. code-block:: bash - - # Build application ``app`` using the C++ driver from a non-standard install. - # Use CMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE to keep rpath entry on installed app. - cmake \ - -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \ - -DCMAKE_INSTALL_PREFIX=$HOME/app \ - -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE \ - -DCMAKE_CXX_STANDARD=11 \ - -Bcmake-build -S. - - cmake --build cmake-build --target install - $HOME/app/bin/app.out - # Prints "successfully connected with C++ driver" - -See the cmake documentation for `RPATH handling `__ for more information. - -Fixing the "cannot open shared object file" error on Linux -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Applications linking to a non-standard directory installation may encounter an error loading the C++ driver at runtime. Example: - -.. code-block:: bash - - # Tell pkg-config where to find C++ driver installation. - export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig - g++ -std=c++11 app.cpp $(pkg-config --cflags --libs libmongocxx) -o ./app.out - ./app.out - # Prints the following error: - # ./app.out: error while loading shared libraries: libmongocxx.so._noabi: cannot open shared object file: No such file or directory - -There are several ways to consider solving this on Linux: - -Pass ``LD_LIBRARY_PATH`` to the directory containing the C++ driver libraries: - -.. code-block:: bash - - LD_LIBRARY_PATH=$HOME/mongo-cxx-driver/lib ./app.out - # Prints "successfully connected with C++ driver" - -Alternatively, the linker option ``-Wl,-rpath`` can be passed to add ``rpath`` entries: - -.. code-block:: bash - - # Tell pkg-config where to find C++ driver installation. - export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig - # Pass the linker option -rpath to set an rpath in the final executable. - g++ app.cpp -std=c++11 -Wl,-rpath,$HOME/mongo-cxx-driver/lib $(pkg-config --cflags --libs libmongocxx) -o ./app.out - ./app.out - # Prints "successfully connected with C++ driver" - -If building the application with cmake, the `Default RPATH settings `__ include the full RPATH to all used libraries in the build tree. However, when installing, cmake will clear the RPATH of these targets so they are installed with an empty RPATH. This may result in a ``Library not loaded`` error after install. - -Example: - -.. code-block:: bash - - # Build application ``app`` using the C++ driver from a non-standard install. - cmake \ - -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \ - -DCMAKE_INSTALL_PREFIX=$HOME/app \ - -DCMAKE_CXX_STANDARD=11 \ - -Bcmake-build -S. - cmake --build cmake-build --target app.out - # Running app.out from build tree includes rpath to C++ driver. - ./cmake-build ./cmake-build/app.out - # Prints: "successfully connected with C++ driver" - - cmake --build cmake-build --target install - # Running app.out from install tree does not include rpath to C++ driver. - $HOME/app/bin/app.out - # Prints "cannot open shared object file" error. - -Consider setting ``-DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE`` so the rpath for the executable is kept in the install target. - -.. code-block:: bash - - # Build application ``app`` using the C++ driver from a non-standard install. - # Use CMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE to keep rpath entry on installed app. - cmake \ - -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \ - -DCMAKE_INSTALL_PREFIX=$HOME/app \ - -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE \ - -DCMAKE_CXX_STANDARD=11 \ - -Bcmake-build -S. - - cmake --build cmake-build --target install - $HOME/app/bin/app.out - # Prints "successfully connected with C++ driver" +Troubleshooting +--------------- -See the cmake documentation for `RPATH handling `__ for more information. +.. include:: /includes/troubleshooting/advanced-installation.rst \ No newline at end of file From edc550d5aff36df0536f2ec6b15c9773c49c0ac4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 2 Aug 2024 16:58:39 -0400 Subject: [PATCH 3/6] remove installation pages --- snooty.toml | 1 - ...advanced.txt => advanced-installation.txt} | 144 +++++++++++++++++- source/get-started/download-and-install.txt | 7 + source/installation/linux.txt | 86 ----------- source/installation/macos.txt | 86 ----------- source/installation/windows.txt | 41 ----- .../{get-started => }/polyfill-selection.txt | 0 7 files changed, 148 insertions(+), 217 deletions(-) rename source/{installation/advanced.txt => advanced-installation.txt} (68%) delete mode 100644 source/installation/linux.txt delete mode 100644 source/installation/macos.txt delete mode 100644 source/installation/windows.txt rename source/{get-started => }/polyfill-selection.txt (100%) diff --git a/snooty.toml b/snooty.toml index 24425718..74512ad1 100644 --- a/snooty.toml +++ b/snooty.toml @@ -8,7 +8,6 @@ intersphinx = [ ] toc_landing_pages = [ - "/installation", "/api-abi-versioning", "/get-started", "/connect", diff --git a/source/installation/advanced.txt b/source/advanced-installation.txt similarity index 68% rename from source/installation/advanced.txt rename to source/advanced-installation.txt index c480d5a5..630ca9c9 100644 --- a/source/installation/advanced.txt +++ b/source/advanced-installation.txt @@ -17,7 +17,11 @@ Advanced Configuration and Installation Options 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``. +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 @@ -27,8 +31,142 @@ In the event that you are building the BSON C++ library and/or the C++ driver to 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). -Installing the MongoDB C Driver --------------------------------- +Install with Package Managers +----------------------------- + +You can use the following package managers to install the {+driver-short+}: + +- :ref:`vcpkg ` +- :ref:`Conan ` +- :ref:`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=//vcpkg/scripts/buildsystems/vcpkg.cmake + +You can find the header files in: + +.. code-block:: none + + vcpkg/installed/-/include/ + +The library files are in: + +.. code-block:: none + + vcpkg/installed/-/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 `__. diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt index 9b02a13f..4b7a928f 100644 --- a/source/get-started/download-and-install.txt +++ b/source/get-started/download-and-install.txt @@ -24,6 +24,13 @@ Download and Install - `CMake `__ v3.15 or later - `pkg-config `__ + .. note:: C++17 Polyfills + + This tutorial configures the {+driver-short+} to use the C++17 standard + library. If you want to install the driver for pre-C++17 configurations, + you must choose a C++17 polyfill library. To learn more about C++17 + polyfills, see the :ref:`cpp-polyfill-selection` guide. + .. step:: Download the {+driver-short+} To download the latest version of the {+driver-short+} from the ``mongo-cxx-driver`` Github diff --git a/source/installation/linux.txt b/source/installation/linux.txt deleted file mode 100644 index fd62c605..00000000 --- a/source/installation/linux.txt +++ /dev/null @@ -1,86 +0,0 @@ -.. _cpp-installation-linux: - -===================== -Installation on Linux -===================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -Step 1: Choose a C++17 polyfill -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First, :ref:`choose a C++17 polyfill library `. - -Step 2: Download the latest version of the mongocxx driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The most reliable starting point for building the mongocxx driver is the latest -release tarball. - -The `mongocxx releases `__ -page will have links to the release tarball for the version you wish you install. For -example, to download version {+full-version+}: - -.. code-block:: bash - - curl -OL https://github.com/mongodb/mongo-cxx-driver/releases/download/r{+full-version+}/mongo-cxx-driver-r{+full-version+}.tar.gz - tar -xzf mongo-cxx-driver-r{+full-version+}.tar.gz - cd mongo-cxx-driver-r{+full-version+}/build - -Make sure you change to the ``build`` directory of whatever source tree you -obtain. - -Step 3: Configure the driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Without additional configuration, ``mongocxx`` installs into its local build -directory as a courtesy to those who build from source. To configure ``mongocxx`` -for installation into ``/usr/local`` as well, use the following -``cmake`` command: - -.. code-block:: bash - - cmake .. \ - -DCMAKE_BUILD_TYPE=Release \ - -DMONGOCXX_OVERRIDE_DEFAULT_INSTALL_PREFIX=OFF - -These options can be freely mixed with a C++17 polyfill option. For instance, this is how a user -would run the command above with the Boost polyfill option: - -.. code-block:: bash - - cmake .. \ - -DCMAKE_BUILD_TYPE=Release \ - -DBSONCXX_POLY_USE_BOOST=1 \ - -DMONGOCXX_OVERRIDE_DEFAULT_INSTALL_PREFIX=OFF - -Step 4: Build and install the driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Build and install the driver: - -.. code-block:: bash - - cmake --build . - sudo cmake --build . --target install - -The driver can be uninstalled at a later time in one of two ways. First, -the uninstall target can be called: - -.. code-block:: bash - - sudo cmake --build . --target uninstall - -Second, the uninstall script can be called: - -.. code-block:: bash - - sudo /share/mongo-cxx-driver/uninstall.sh diff --git a/source/installation/macos.txt b/source/installation/macos.txt deleted file mode 100644 index 2b51b6b9..00000000 --- a/source/installation/macos.txt +++ /dev/null @@ -1,86 +0,0 @@ -.. _cpp-installation-macos: - -===================== -Installation on macOS -===================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -Step 1: Choose a C++17 polyfill -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First, :ref:`choose a C++17 polyfill library `. - -Step 2: Download the latest version of the mongocxx driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The most reliable starting point for building the mongocxx driver is the latest -release tarball. - -The `mongocxx releases `__ -page will have links to the release tarball for the version you wish you install. For -example, to download version {+full-version+}: - -.. code-block:: bash - - curl -OL https://github.com/mongodb/mongo-cxx-driver/releases/download/r{+full-version+}/mongo-cxx-driver-r{+full-version+}.tar.gz - tar -xzf mongo-cxx-driver-r{+full-version+}.tar.gz - cd mongo-cxx-driver-r{+full-version+}/build - -Make sure you change to the ``build`` directory of whatever source tree you -obtain. - -Step 3: Configure the driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Without additional configuration, ``mongocxx`` installs into its local build -directory as a courtesy to those who build from source. To configure -``mongocxx`` for installation into ``/usr/local`` as well, use the following -``cmake`` command: - -.. code-block:: bash - - cmake .. \ - -DCMAKE_BUILD_TYPE=Release \ - -DMONGOCXX_OVERRIDE_DEFAULT_INSTALL_PREFIX=OFF - -These options can be freely mixed with a C++17 polyfill option. For instance, this is how a user -would run the command above with the Boost polyfill option: - -.. code-block:: bash - - cmake .. \ - -DCMAKE_BUILD_TYPE=Release \ - -DBSONCXX_POLY_USE_BOOST=1 \ - -DMONGOCXX_OVERRIDE_DEFAULT_INSTALL_PREFIX=OFF - -Step 4: Build and install the driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Build and install the driver: - -.. code-block:: bash - - cmake --build . - sudo cmake --build . --target install - -The driver can be uninstalled at a later time in one of two ways. First, -the uninstall target can be called: - -.. code-block:: bash - - sudo cmake --build . --target uninstall - -Second, the uninstall script can be called: - -.. code-block:: bash - - sudo /share/mongo-cxx-driver/uninstall.sh diff --git a/source/installation/windows.txt b/source/installation/windows.txt deleted file mode 100644 index fc87a93b..00000000 --- a/source/installation/windows.txt +++ /dev/null @@ -1,41 +0,0 @@ -Configuring with ``mongocxx`` 3.7.0 and Older -````````````````````````````````````````````` - -To build versions 3.7.0 and older without a C++17 polyfill, it is necessary to -configure with additional options: - -- ``/Zc:__cplusplus`` to opt into the correct definition of ``__cplusplus`` (`problem described here `__) -- ``/EHsc`` to enable recommended `exception handling behavior `__. - -.. code-block:: bash - - 'C:\Program Files (x86)\CMake\bin\cmake.exe' .. \ - -G "Visual Studio 15 2017" -A "x64" \ - -DCMAKE_CXX_STANDARD=17 \ - -DCMAKE_CXX_FLAGS="/Zc:__cplusplus /EHsc" \ - -DCMAKE_INSTALL_PREFIX=C:\mongo-cxx-driver \ - -Configuring with ``mongocxx`` 3.1.x or 3.0.x - -.. code-block:: bash - - cmake .. \ - -DLIBMONGOC_DIR=C:\mongo-c-driver \ - -DCMAKE_INSTALL_PREFIX=C:\mongo-cxx-driver - - - - - -The driver can be uninstalled at a later time in one of two ways. First, -the uninstall target can be called: - -.. code-block:: bash - - cmake --build . --target uninstall - -Second, the uninstall script can be called: - -.. code-block:: none - - C:\opt\mongo-cxx-driver\share\mongo-cxx-driver\uninstall.cmd diff --git a/source/get-started/polyfill-selection.txt b/source/polyfill-selection.txt similarity index 100% rename from source/get-started/polyfill-selection.txt rename to source/polyfill-selection.txt From 3c3aa9d6579532c68299a2c433cb2edab70d4049 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 2 Aug 2024 17:04:40 -0400 Subject: [PATCH 4/6] edits, remove buttons --- source/get-started.txt | 6 +- source/get-started/connect-to-mongodb.txt | 3 - .../create-a-connection-string.txt | 5 +- source/get-started/create-a-deployment.txt | 5 +- source/get-started/download-and-install.txt | 3 - source/get-started/next-steps.txt | 9 +- source/index.txt | 4 +- source/installation.txt | 186 ------------------ 8 files changed, 10 insertions(+), 211 deletions(-) delete mode 100644 source/installation.txt diff --git a/source/get-started.txt b/source/get-started.txt index a2ed3b5a..7338624c 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -20,7 +20,6 @@ Get Started with the C++ Driver .. toctree:: - /get-started/polyfill-selection/ /get-started/download-and-install/ /get-started/create-a-deployment/ /get-started/create-a-connection-string/ @@ -43,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: Choose a C++17 Polyfill - :uri: /get-started/polyfill-selection/ \ No newline at end of file +programming language, see our :driver:`list of official drivers <>`. \ No newline at end of file diff --git a/source/get-started/connect-to-mongodb.txt b/source/get-started/connect-to-mongodb.txt index 5f90ac02..dc0057e7 100644 --- a/source/get-started/connect-to-mongodb.txt +++ b/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/ diff --git a/source/get-started/create-a-connection-string.txt b/source/get-started/create-a-connection-string.txt index 9833ddc0..26aba9d8 100644 --- a/source/get-started/create-a-connection-string.txt +++ b/source/get-started/create-a-connection-string.txt @@ -58,7 +58,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/ \ No newline at end of file +.. include:: /includes/get-started/troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/create-a-deployment.txt b/source/get-started/create-a-deployment.txt index ab5d40d4..c24d276a 100644 --- a/source/get-started/create-a-deployment.txt +++ b/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/ \ No newline at end of file +.. include:: /includes/get-started/troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt index 4b7a928f..85a80b92 100644 --- a/source/get-started/download-and-install.txt +++ b/source/get-started/download-and-install.txt @@ -104,6 +104,3 @@ After you complete these steps, you have the {+driver-short+} installed on your machine. .. include:: /includes/get-started/troubleshoot.rst - -.. button:: Next: Create a MongoDB Deployment - :uri: /get-started/create-a-deployment/ diff --git a/source/get-started/next-steps.txt b/source/get-started/next-steps.txt index f0bb041d..525c4d38 100644 --- a/source/get-started/next-steps.txt +++ b/source/get-started/next-steps.txt @@ -17,7 +17,8 @@ In this tutorial, you created a C++ application that connects to a MongoDB deployment hosted on MongoDB Atlas and retrieves a document that matches a query. -.. TODO: add links once these pages exist - Learn more about {+driver-short+} from the following resources: - - Learn how to perform read operations in the :ref:`` section. - - Learn how to perform write operations in the :ref:`` section. \ No newline at end of file +Learn more about {+driver-short+} from the following resources: + +- Learn how to perform read operations in the :ref:`` section. + +- Learn how to perform write operations in the :ref:`` section. \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index bb531225..f806a8e0 100644 --- a/source/index.txt +++ b/source/index.txt @@ -17,8 +17,8 @@ MongoDB C++ Driver :maxdepth: 1 Get Started - /connect - /installation + /polyfill-selection + /connect /read /write /indexes diff --git a/source/installation.txt b/source/installation.txt deleted file mode 100644 index 8b5abd3e..00000000 --- a/source/installation.txt +++ /dev/null @@ -1,186 +0,0 @@ -.. _cpp-installation: - -============= -Installation -============= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: running - -.. toctree:: - :titlesonly: - :maxdepth: 1 - - /installation/windows - /installation/macos - /installation/linux - /installation/advanced - -Prerequisites -------------- - -- Any standard Unix platform, or Windows 7 SP1+ -- A compiler that supports C++11 (gcc, clang, or Visual Studio) -- `CMake `__ 3.15 or later -- `boost `__ headers (optional) - -If you encounter build failures or other problems with a platform configuration -that meets the above prerequisites, please file a bug report via -`JIRA `__. - -Installing ----------- - -To configure and install the driver, follow the instructions for your platform: - -- :ref:`Configuring and installing on Windows ` -- :ref:`Configuring and installing on macOS ` -- :ref:`Configuring and installing on Linux ` - -Advanced Options ----------------- - -- :ref:`Advanced Configuration and Installation Options ` - -Package Managers ----------------- - -The Mongo C++ driver is available in the following package managers. - -- `Vcpkg `__ (search for mongo-cxx-driver) -- `Conan `__ -- `Homebrew `__ - -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=//vcpkg/scripts/buildsystems/vcpkg.cmake - -You can find the header files in: - -.. code-block:: none - - vcpkg/installed/-/include/ - -The library files are in: - -.. code-block:: none - - vcpkg/installed/-/lib/ - -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 - -Homebrew -~~~~~~~~ - -For MacOS users, homebrew is a convenient way to install the C++ driver. - -.. 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/ - -Docker Image ------------- - -You can find a pre-built docker image for the C++ driver in -`Docker Hub `__. From 0b6d8c90d3e6ae37f01ca02159178cea7fb0acd2 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 2 Aug 2024 17:13:18 -0400 Subject: [PATCH 5/6] resolve TODOs --- source/get-started/create-a-connection-string.txt | 3 ++- source/polyfill-selection.txt | 5 +---- source/read/retrieve.txt | 15 ++++++++------- source/security/authentication.txt | 2 +- source/security/enterprise-authentication.txt | 2 +- source/write/insert.txt | 5 ++--- 6 files changed, 15 insertions(+), 17 deletions(-) diff --git a/source/get-started/create-a-connection-string.txt b/source/get-started/create-a-connection-string.txt index 26aba9d8..a5a84504 100644 --- a/source/get-started/create-a-connection-string.txt +++ b/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 diff --git a/source/polyfill-selection.txt b/source/polyfill-selection.txt index 358e0969..26e9974e 100644 --- a/source/polyfill-selection.txt +++ b/source/polyfill-selection.txt @@ -64,7 +64,4 @@ selection behavior. .. warning:: - The choice of polyfill library has a direct impact on the public API and ABI for the mongocxx library. Changing the polyfill can lead to both source-breaking changes (during compilation) and binary-breaking changes (during linking or execution). To limit reliance on polyfill-specific configuration or behavior, avoid using ``stdx::string_view`` and ``stdx::optional`` with non-mongocxx library interfaces. - -.. button:: Next: Download and Install - :uri: /get-started/download-and-install/ \ No newline at end of file + The choice of polyfill library has a direct impact on the public API and ABI for the mongocxx library. Changing the polyfill can lead to both source-breaking changes (during compilation) and binary-breaking changes (during linking or execution). To limit reliance on polyfill-specific configuration or behavior, avoid using ``stdx::string_view`` and ``stdx::optional`` with non-mongocxx library interfaces. \ No newline at end of file diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index e9707e70..3c85ca70 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -53,8 +53,9 @@ These methods take a **query filter** and return one or more matching documents. A query filter is an object that specifies the documents you want to retrieve in your query. -.. TODO: - To learn more about query filters, see :ref:`cpp-specify-query`. +.. tip:: + + To learn more about query filters, see :ref:`cpp-specify-query`. .. _cpp-retrieve-find-one: @@ -100,8 +101,8 @@ the ``name`` field has the value ``"LinkedIn"``: :manual:`natural order ` on disk if no sort criteria is specified. -.. TODO: - To learn more about sorting, see the :ref:`sort guide `. +To learn more about sorting, see the :ref:`cpp-return-documents-sort` +section of the Specify Documents to Return guide. .. _cpp-retrieve-find-multiple: @@ -220,9 +221,9 @@ For a full list of ``mongocxx::options::find`` object fields, see the Additional Information ---------------------- -.. TODO: - To learn more about query filters, see :ref:`cpp-specify-query`. - For runnable code examples of retrieving documents with {+driver-short+}, see :ref:`cpp-read`. +To learn more about query filters, see :ref:`cpp-specify-query`. + +For runnable code examples of retrieving documents with the {+driver-short+}, see :ref:`cpp-read`. For more examples that use the ``find()`` and ``find_one()`` methods, see the :ref:`cpp-tutorial-find` section of the Tutorial page. diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 83ff27f4..a52622fa 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -101,7 +101,7 @@ You can set these options in the connection string when creating a :start-after: // start-x509 :end-before: // end-x509 -.. TODO: To learn more about enabling TLS, see :ref:`cpp-tls`. +To learn more about enabling TLS, see :ref:`cpp-tls`. .. _cpp-mongo-aws: diff --git a/source/security/enterprise-authentication.txt b/source/security/enterprise-authentication.txt index fb660935..dd95017d 100644 --- a/source/security/enterprise-authentication.txt +++ b/source/security/enterprise-authentication.txt @@ -106,7 +106,7 @@ authentication mechanism often used with TLS or another encryption layer. PLAIN SASL is a clear-text authentication mechanism. We strongly recommend that you use TLS/SSL with certificate validation when using PLAIN SASL to authenticate to MongoDB. -.. TODO: To learn more about how to enable TLS for your connection, see :ref:``. +To learn more about how to enable TLS for your connection, see :ref:``. To authenticate with SASL, set the ``authMechanism`` connection option to ``PLAIN``. You can set this option through a parameter in your connection string, as shown diff --git a/source/write/insert.txt b/source/write/insert.txt index b258083f..3f6a19a6 100644 --- a/source/write/insert.txt +++ b/source/write/insert.txt @@ -157,9 +157,8 @@ insert operation bypasses document-level validation: Additional Information ---------------------- -.. TODO: - For runnable code examples of inserting documents with the {+driver-short+}, see - :ref:`cpp-write`. +For runnable code examples of inserting documents with the {+driver-short+}, see +:ref:`cpp-write`. For more examples that use the ``insert_one()`` and ``insert_many()`` methods, see the :ref:`cpp-tutorial-insert` section of the Tutorial page. From 0ce1f23761e7e34f365957ed89cbf0acf6a292f2 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 5 Aug 2024 10:25:09 -0400 Subject: [PATCH 6/6] toc --- source/index.txt | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/source/index.txt b/source/index.txt index f806a8e0..8effac5f 100644 --- a/source/index.txt +++ b/source/index.txt @@ -18,6 +18,7 @@ MongoDB C++ Driver Get Started /polyfill-selection + /advanced-installation /connect /read /write @@ -52,6 +53,18 @@ Get Started Learn how to install the driver, establish a connection to MongoDB, and begin working with data in the :ref:`cpp-get-started` tutorial. +Choose a C++17 Polyfill +----------------------- + +Learn how to a choose a polyfill library implementation for +pre-C++ 17 configurations in the :ref:`cpp-polyfill-selection` section. + +Advanced Installation Options +----------------------------- + +Learn about additional configuration and installation options +in the :ref:`cpp-installation-advanced` section. + Connect to MongoDB ------------------