CXX-2745 Add advanced CMake options to toggle root namespace redeclarations

[eramongodb]

An intermediate PR related to CXX-2745 following #1318.

Add advanced, for-development-only CMake options BSONCXX_API_OVERRIDE_DEFAULT_ABI and MONGOCXX_API_OVERRIDE_DEFAULT_ABI to permit toggling the ABI namespace that is used by root namespace redeclarations.

Important

These options are NOT intended for public use. This is strictly for development purposes. Enabling these options will emit CMake configuration warnings:

CMake Warning at src/bsoncxx/CMakeLists.txt:29 (message):
  BSONCXX_API_OVERRIDE_DEFAULT_ABI is an experimental feature
CMake Warning at src/mongocxx/CMakeLists.txt:29 (message):
  MONGOCXX_API_OVERRIDE_DEFAULT_ABI is an experimental feature

The options are also marked as "advanced" so they do not show up in CMake GUIs by default.

When enabled, relevant root namespace redeclarations will use v1 interfaces instead of v_noabi interfaces, e.g.:

#if defined(BSONCXX_API_OVERRIDE_DEFAULT_ABI)
using v1::document::view; // New v1 equivalent or successor API.
#else
using v_noabi::document::view; // Current v_noabi API.
#endif

This permits manually verifying compilation and runtime compatibility of v1 interfaces via root namespace redeclarations against existing code (e.g. bsoncxx::document::view (bsoncxx::v1::document::view)). This toggle will continue to be used throughout upcoming PRs to both document and control the set of v1 interfaces which are "ready for use". These options may be toggled individually for each library (although mongocxx should be only be enabled when bsoncxx is also enabled).

At the moment, this PR only applies this option to stdx::string_view and stdx::optional<T>. These are the only v1 interfaces which are currently "ready for use". This can be validated right now by building and running the C++ Driver with the BSONCXX_API_OVERRIDE_DEFAULT_ABI option enabled.

As more v1 interfaces are introduced and v_noabi interfaces updated to support forward-compatibility with v1 interfaces, the application of this configuration option will be incrementally extended to allow for reuse of existing (test) code for API and behavioral testing of v1 interfaces. This macro may also be used to denote v_noabi interfaces which do not have direct v1 counterparts (no corresponding v1 redeclarations), e.g.:

#if defined(BSONCXX_API_OVERRIDE_DEFAULT_ABI)
// No v1 API equivalent or successor.
#else
using v_noabi::builder::stream::document; // Current v_noabi API.
#endif

Conversely, new v1 interfaces, or those which substantially differ from their v_noabi equivalents, may introduce new redeclarations without v_noabi counterparts (reverse of the above).

Once v1 interfaces are sufficiently ready for use, this pattern will also permit users to opt-into using v1 interfaces early and migrate from v_noabi to v1. This may be done either with a different CMake option designed to target user configuration rather than internal development, or by converting this CMake option from advanced, for-development-only into a user-facing CMake option.

[kevinAlbs]

I very much support this idea as a means of local verification, and possibly exposing this in the future to help users test opting in to the v1. LGTM with a minor fix.

[kevinAlbs]

Suggested change

	mark_as_advanced(BSONCXX_API_OVERRIDE_DEFAULT_ABI)
	mark_as_advanced(MONGOCXX_API_OVERRIDE_DEFAULT_ABI)