Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCSP-45307: Drop external polyfill library support #74

Merged
merged 9 commits into from
Nov 19, 2024
Merged

DOCSP-45307: Drop external polyfill library support #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
749a114
DOCSP-45307: Drop external polyfill library support
norareidy Nov 13, 2024
9ebecae
JS feedback
norareidy Nov 14, 2024
a64cc6c
JS feedback 2
norareidy Nov 14, 2024
e048746
tech review
norareidy Nov 15, 2024
aaa0d35
polyfills
norareidy Nov 15, 2024
62d410d
fixes
norareidy Nov 19, 2024
e5c0a5f
EC feedback 2
norareidy Nov 19, 2024
d187939
wording
norareidy Nov 19, 2024
cadd67a
EC last feedback
norareidy Nov 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions source/api-abi-versioning.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
15 changes: 9 additions & 6 deletions source/get-started/download-and-install.txt
View file
Open in desktop
eramongodb marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -16,20 +16,22 @@ 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 <https://gcc.gnu.org/install/>`__, `Clang <https://clang.llvm.org/>`__,
or `Visual Studio <https://visualstudio.microsoft.com/>`__
- `CMake <https://cmake.org/>`__ v3.15 or later
- `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`__

.. note:: C++17 Polyfills
.. note:: Pre-C++17 Configurations
eramongodb marked this conversation as resolved.
Show resolved Hide resolved

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+}

Expand All @@ -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.
Expand Down
30 changes: 23 additions & 7 deletions source/index.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@ MongoDB C++ Driver
Run a Command </run-command>
Security </security>
Specialized Data Formats </data-formats>
C++17 Polyfill </polyfill-selection>
Advanced Configuration & Installation </advanced-installation>
Thread & Fork Safety </thread-safety>
API & ABI Versioning </api-abi-versioning>
Expand Down Expand Up @@ -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
-----------------------------

Expand Down Expand Up @@ -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<T>`` 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<T>`` with non-bsoncxx and non-mongocxx
library interfaces.

Driver Status by Family and Version
-----------------------------------
Expand Down
63 changes: 0 additions & 63 deletions source/polyfill-selection.txt
View file
Open in desktop

This file was deleted.

17 changes: 17 additions & 0 deletions source/upgrade.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
48 changes: 45 additions & 3 deletions source/whats-new.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ Overview

Learn what's new in:

* :ref:`Version 4.0 <version-4.0>`
* :ref:`Version 3.11 <version-3.11>`
* :ref:`Version 3.10 <version-3.10>`
* :ref:`Version 3.9 <version-3.9>`
Expand Down Expand Up @@ -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
eramongodb marked this conversation as resolved.
Show resolved Hide resolved
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``.

eramongodb marked this conversation as resolved.
Show resolved Hide resolved
.. 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<T>`` as aliases for Boost or MNMLSTC/core
library equivalents. For context, see the :ref:`Build System Breaking Changes
<version-4.0-build-system-breaking>` 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<T>`` as aliases for Boost or MNMLSTC/core
library equivalents. For context, see the :ref:`Build System Breaking Changes
<version-4.0-build-system-breaking>` 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:

Expand Down
Loading