diff --git a/source/api-abi-versioning.txt b/source/api-abi-versioning.txt index f82f4ddd..191946f1 100644 --- a/source/api-abi-versioning.txt +++ b/source/api-abi-versioning.txt @@ -193,8 +193,6 @@ Examples of expected library filenames (with a brief description of notable feat - ``bsoncxx-v_noabi-dhs-x64-v142-mdd.dll`` (debug build configuration) - ``bsoncxx-v_noabi-rts-x64-v142-md.dll`` (link with mongoc static libraries) - ``bsoncxx-v_noabi-rhi-x64-v142-md.dll`` (bsoncxx as polyfill library) -- ``bsoncxx-v_noabi-rhm-x64-v142-md.dll`` (mnmlstc/core as polyfill library) -- ``bsoncxx-v_noabi-rhb-x64-v142-md.dll`` (Boost as polyfill library) - ``bsoncxx-v1-rhs-x64-v142-md.dll`` (ABI version number 1) - ``bsoncxx-v2-rhs-x64-v142-md.dll`` (ABI version number 2) diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt index 85a80b92..3fcf96ff 100644 --- a/source/get-started/download-and-install.txt +++ b/source/get-started/download-and-install.txt @@ -16,7 +16,7 @@ Download and Install .. step:: Install dependencies - Before you being developing, ensure you have the following dependencies + Before you being this tutorial, ensure you have the following dependencies installed in your development environment: - Compiler that supports C++17, such as `GCC `__, `Clang `__, @@ -24,12 +24,14 @@ Download and Install - `CMake `__ v3.15 or later - `pkg-config `__ - .. note:: C++17 Polyfills + .. note:: Pre-C++17 Configurations - 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. + Although C++11 is the minimum supported language version, this tutorial + configures the {+driver-short+} to use the C++17 standard library + as recommended by the :ref:`cpp-polyfill-config` section. If you want to install + the driver for pre-C++17 configurations, set the ``CMAKE_CXX_STANDARD`` + configuration option to your C++ version. Then, the driver will automatically use + bsoncxx library polyfill implementations for required C++17 features. .. step:: Download the {+driver-short+} @@ -56,6 +58,7 @@ Download and Install cmake .. \ -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_CXX_STANDARD=17 \ -DMONGOCXX_OVERRIDE_DEFAULT_INSTALL_PREFIX=OFF This command instructs CMake to install ``mongocxx`` into the ``/usr/local`` directory. diff --git a/source/index.txt b/source/index.txt index 1e66380d..b661483f 100644 --- a/source/index.txt +++ b/source/index.txt @@ -19,7 +19,6 @@ MongoDB C++ Driver Run a Command Security Specialized Data Formats - C++17 Polyfill Advanced Configuration & Installation Thread & Fork Safety API & ABI Versioning @@ -83,12 +82,6 @@ Specialized Data Formats Learn how to work with specialized data formats and custom types in the :ref:`cpp-data-formats` section. -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 ----------------------------- @@ -126,6 +119,29 @@ API Documentation For detailed information about types and methods in the {+driver-short+}, see the `{+driver-short+} API documentation <{+api+}>`__. +.. _cpp-polyfill-config: + +C++17 Polyfill Configuration +---------------------------- + +.. important:: + + We recommend using the C++ standard library whenever possible by setting the + ``CMAKE_CXX_STANDARD`` configuration option to ``17`` or newer. + +The {+driver-long+} uses C++17 features ``std::optional`` and ``std::string_view``. +If you configure the driver with a pre-C++17 standard, the bsoncxx library provides +polyfill implementations for these C++17 features. The driver uses the bsoncxx polyfill +implementations when the ``CMAKE_CXX_STANDARD`` configuration option is set to a number +less than ``17``. By default, this option is set to ``11``. + +.. 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 + behavior, avoid using ``stdx::string_view`` and ``stdx::optional`` with non-bsoncxx and non-mongocxx + library interfaces. Driver Status by Family and Version ----------------------------------- diff --git a/source/polyfill-selection.txt b/source/polyfill-selection.txt deleted file mode 100644 index ba62546a..00000000 --- a/source/polyfill-selection.txt +++ /dev/null @@ -1,63 +0,0 @@ -.. _cpp-polyfill-selection: - -======================= -Choose a C++17 Polyfill -======================= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -The mongocxx driver uses C++17 features ``std::optional`` and ``std::string_view``. -To use the C++17 standard library implementations for these features, set -the CMake configuration variable ``CMAKE_CXX_STANDARD`` to 17 or higher. -Otherwise, to compile the mongocxx driver for pre-C++17 configurations, a -polyfill library implementation must be selected from the following options: - -- bsoncxx (*default only when -DENABLE_BSONCXX_POLY_USE_IMPLS=ON*) - - Select with ``-DBSONCXX_POLY_USE_IMPLS=ON``. This option is most recommended, as - it does not require additional external library dependencies. To enable - selecting this option by default for pre-C++17 configurations when no other - options are specified, set ``ENABLE_BSONCXX_POLY_USE_IMPLS=ON`` (this option - will be set to ON by default in an upcoming major release). - -- MNMLSTC/core (*default for non-Windows platforms*) - - **This option is deprecated and will be removed in an upcoming major release.** - Select with ``-DBSONCXX_POLY_USE_MNMLSTC=1``. - - .. note:: - - This option vendors a header-only installation of MNMLSTC/core into the bsoncxx library installation and will therefore download MLNMLSTC from GitHub during the configuration process. If you already have an available version of MNMLSTC on your system, you can avoid the download step by using ``-DBSONCXX_POLY_USE_SYSTEM_MNMLSTC``. - -- Boost (*default for Windows platforms*) - - **This option is deprecated and will be removed in an upcoming major release.** - Select with ``-DBSONCXX_POLY_USE_BOOST=1``. This is currently the only - non-bsoncxx option if you are using a version of MSVC that does not support - C++17. - -.. note:: - - "default" refers to **pre-C++17** configurations when no polyfill library is explicitly selected. - -Most users should use default behavior with ``-DENABLE_BSONCXX_POLY_USE_IMPLS=ON``. -However, if you have a preference for one of the external polyfill libraries -(e.g. already a dependency being used by your application), you may prefer to -explicitly select that external polyfill library rather than rely on default -selection behavior. - -.. note:: - - C++ standard conformance and supported behavior of polyfill features may vary depending on the selected polyfill library. The purpose of these polyfills is to support pre-C++17 configurations by providing stand-ins for their C++17 equivalents. Therefore we recommend using the C++17 standard library whenever possible by setting ``-DCMAKE_CXX_STANDARD=17`` or newer. - -.. 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. \ No newline at end of file diff --git a/source/upgrade.txt b/source/upgrade.txt index a521a630..102b6ad1 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -66,11 +66,28 @@ and upgrade versions. If you're upgrading the {+driver-short+} from version 3.0 to version 3.10, address all breaking changes listed for versions 3.1 to 3.10, if any. +.. _version-4.0-breaking-changes: + +Version 4.0 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This driver version introduces the following breaking changes: + +- Drops support for the Boost and MNMLSTC/core external polyfill libraries. You can no + longer set the following configuration options: + + - ``ENABLE_BSONCXX_POLY_USE_IMPLS``. This option is implicitly set to ``ON``. + - ``BSONCXX_POLY_USE_MNMLSTC``. + - ``BSONCXX_POLY_USE_SYSTEM_MNMLSTC``. + - ``BSONCXX_POLY_USE_BOOST``. + .. _version-3.11-breaking-changes: Version 3.11 Breaking Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This driver version introduces the following breaking changes: + - Drops support for {+mdb-server+} v3.6. - Requires MongoDB C Driver v1.28.0 or later. - Removes export of the following private member functions in the bsoncxx diff --git a/source/whats-new.txt b/source/whats-new.txt index 62f926fb..28cb52df 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -22,6 +22,7 @@ Overview Learn what's new in: +* :ref:`Version 4.0 ` * :ref:`Version 3.11 ` * :ref:`Version 3.10 ` * :ref:`Version 3.9 ` @@ -73,18 +74,59 @@ New versions of the {+driver-short+} can introduce the following types of breaki - Drops support for platform A, compiler B, or architecture C. .. _upcoming-breaking-changes: +.. _version-4.0: + +What's New in 4.0 +----------------- + +.. _version-4.0-build-system-breaking: + +.. warning:: Build System Breaking Changes + + The v4.0 driver introduces the following breaking changes to the build system: + + - Drops support for the Boost and MNMLSTC/core external polyfill libraries. You can no + longer set the following configuration options: + + - ``ENABLE_BSONCXX_POLY_USE_IMPLS``. This option is implicitly set to ``ON``. + - ``BSONCXX_POLY_USE_MNMLSTC``. + - ``BSONCXX_POLY_USE_SYSTEM_MNMLSTC``. + - ``BSONCXX_POLY_USE_BOOST``. + +.. warning:: API Breaking Changes + + The v4.0 driver introduces the following breaking changes to the API: + + - Drops support for configuring ``bsoncxx::stdx::string_view`` and + ``bsoncxx::stdx::optional`` as aliases for Boost or MNMLSTC/core + library equivalents. For context, see the :ref:`Build System Breaking Changes + ` admonition. + +.. warning:: ABI Breaking Changes + + The v4.0 driver introduces the following breaking changes to the ABI: + + - Drops support for configuring ``bsoncxx::stdx::string_view`` and + ``bsoncxx::stdx::optional`` as aliases for Boost or MNMLSTC/core + library equivalents. For context, see the :ref:`Build System Breaking Changes + ` admonition. .. _version-3.11: What's New in 3.11 ------------------ -.. warning:: Breaking Changes +.. warning:: Build System Breaking Changes + + The v3.11 driver introduces the following breaking changes to the build system: - The v3.11 driver introduces the following breaking changes: - - Drops support for {+mdb-server+} v3.6. - Requires MongoDB C Driver v1.28.0 or later. + +.. warning:: ABI Breaking Changes + + The v3.11 driver introduces the following breaking changes to the ABI: + - Removes export of the following private member functions in the bsoncxx ABI: