CXX-2745 Migrate library config headers into v1

Doxyfile

@@ -604,7 +604,7 @@ HIDE_COMPOUND_REFERENCE= NO
 # the files that are included by a file in the documentation of that file.
 # The default value is: YES.
 
-SHOW_INCLUDE_FILES     = YES
+SHOW_INCLUDE_FILES     = NO
 
 # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
 # grouped member an include statement to the documentation, telling the reader
@@ -2205,10 +2205,12 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = BSONCXX_API= \
+PREDEFINED             = BSONCXX_SATISFY_DOXYGEN_DEFINES \
+                         BSONCXX_API= \
                          BSONCXX_CALL= \
                          BSONCXX_DEPRECATED \
                          BSONCXX_INLINE= \
+                         MONGOCXX_SATISFY_DOXYGEN_DEFINES \
                          MONGOCXX_API= \
                          MONGOCXX_CALL= \
                          MONGOCXX_DEPRECATED \

src/bsoncxx/CMakeLists.txt

@@ -155,13 +155,13 @@ if(1)
             BASE_NAME BSONCXX
             EXPORT_MACRO_NAME BSONCXX_API
             NO_EXPORT_MACRO_NAME BSONCXX_PRIVATE
-            EXPORT_FILE_NAME ${PROJECT_BINARY_DIR}/lib/bsoncxx/v_noabi/bsoncxx/config/export.hpp
+            EXPORT_FILE_NAME ${PROJECT_BINARY_DIR}/lib/bsoncxx/v1/bsoncxx/config/export.hpp
             STATIC_DEFINE BSONCXX_STATIC
         )
 
         install(FILES
-            ${PROJECT_BINARY_DIR}/lib/bsoncxx/v_noabi/bsoncxx/config/export.hpp
-            DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/bsoncxx/v_noabi/bsoncxx/config
+            ${PROJECT_BINARY_DIR}/lib/bsoncxx/v1/bsoncxx/config/export.hpp
+            DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/bsoncxx/v1/bsoncxx/config
             COMPONENT dev
         )
     endfunction()

src/bsoncxx/include/CMakeLists.txt

@@ -42,9 +42,12 @@ set_dist_list(src_bsoncxx_include_DIST
     bsoncxx/v_noabi/bsoncxx/builder/stream/key_context.hpp
     bsoncxx/v_noabi/bsoncxx/builder/stream/single_context.hpp
     bsoncxx/v_noabi/bsoncxx/builder/stream/value_context.hpp
+    bsoncxx/v_noabi/bsoncxx/config/config.hpp
     bsoncxx/v_noabi/bsoncxx/config/compiler.hpp
+    bsoncxx/v_noabi/bsoncxx/config/export.hpp
     bsoncxx/v_noabi/bsoncxx/config/postlude.hpp
     bsoncxx/v_noabi/bsoncxx/config/prelude.hpp
+    bsoncxx/v_noabi/bsoncxx/config/version.hpp
     bsoncxx/v_noabi/bsoncxx/decimal128.hpp
     bsoncxx/v_noabi/bsoncxx/document/element.hpp
     bsoncxx/v_noabi/bsoncxx/document/value.hpp
@@ -70,4 +73,7 @@ set_dist_list(src_bsoncxx_include_DIST
     bsoncxx/v_noabi/bsoncxx/util/functor.hpp
     bsoncxx/v_noabi/bsoncxx/validate.hpp
     bsoncxx/v_noabi/bsoncxx/view_or_value.hpp
+    bsoncxx/v1/bsoncxx/config/compiler.hpp
+    bsoncxx/v1/bsoncxx/config/postlude.hpp
+    bsoncxx/v1/bsoncxx/config/prelude.hpp
 )

src/bsoncxx/include/bsoncxx/v1/bsoncxx/config/compiler.hpp

@@ -0,0 +1,42 @@
+// Copyright 2023 MongoDB Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+///
+/// @file bsoncxx/v1/bsoncxx/config/compiler.hpp
+///
+/// Declares macros that control compiler-specific behavior.
+///
+/// @par Platform-Specific Behavior
+/// Including this header disables MSVC warnings C4251 and C4275 via `#pragma warning(push)`. This
+/// change is reverted by the postlude header via `#pragma warning(pop)`.
+///
+
+///
+/// The declared entity is a member of the public API but is excluded from ABI stability guarantees.
+///
+#define BSONCXX_INLINE inline BSONCXX_PRIVATE
+
+///
+/// @def BSONCXX_CALL
+/// Ensure the declared entity uses naming and calling conventions for C and C++.
+///
+#if defined(_MSC_VER)
+// Disable MSVC warnings that cause a lot of noise related to DLL visibility
+// for types that we don't control (like std::unique_ptr).
+#pragma warning(push)
+#pragma warning(disable : 4251 4275)
+#define BSONCXX_CALL __cdecl
+#else
+#define BSONCXX_CALL
+#endif

src/bsoncxx/include/bsoncxx/v1/bsoncxx/config/postlude.hpp

@@ -0,0 +1,78 @@
+// Copyright 2023 MongoDB Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+///
+/// @file bsoncxx/v1/bsoncxx/config/postlude.hpp
+///
+/// Macro guard postlude header for bsoncxx.
+///
+/// Ensures any config macro defined in config headers do not leak their definition after inclusion.
+///
+/// Restores prior definitions of conflicting macros that are guarded by the @ref
+/// bsoncxx/v1/bsoncxx/config/prelude.hpp "matching prelude header".
+///
+/// @warning Include of the postlude header must be preceeded by a matching include of the prelude
+/// header.
+///
+/// @note Include of the postlude header may be omitted if restoring prior definitions of
+/// conflicting macros is not necessary, e.g. in source (.cpp) files.
+///
+
+// compiler.hpp
+#undef BSONCXX_INLINE
+#pragma pop_macro("BSONCXX_INLINE")
+#if defined(_MSC_VER)
+#pragma warning(pop)
+#endif
+#undef BSONCXX_CALL
+#pragma pop_macro("BSONCXX_CALL")
+
+// config.hpp (generated by CMake)
+#undef BSONCXX_POLY_USE_MNMLSTC
+#pragma pop_macro("BSONCXX_POLY_USE_MNMLSTC")
+#undef BSONCXX_POLY_USE_STD_EXPERIMENTAL
+#pragma pop_macro("BSONCXX_POLY_USE_STD_EXPERIMENTAL")
+#undef BSONCXX_POLY_USE_SYSTEM_MNMLSTC
+#pragma pop_macro("BSONCXX_POLY_USE_SYSTEM_MNMLSTC")
+#undef BSONCXX_POLY_USE_BOOST
+#pragma pop_macro("BSONCXX_POLY_USE_BOOST")
+
+// export.hpp (generated by CMake)
+#undef BSONCXX_API_H
+#pragma pop_macro("BSONCXX_API_H")
+#undef BSONCXX_API
+#pragma pop_macro("BSONCXX_API")
+#undef BSONCXX_PRIVATE
+#pragma pop_macro("BSONCXX_PRIVATE")
+#undef BSONCXX_DEPRECATED
+#pragma pop_macro("BSONCXX_DEPRECATED")
+#undef BSONCXX_DEPRECATED_EXPORT
+#pragma pop_macro("BSONCXX_DEPRECATED_EXPORT")
+#undef BSONCXX_DEPRECATED_NO_EXPORT
+#pragma pop_macro("BSONCXX_DEPRECATED_NO_EXPORT")
+
+// version.hpp (generated by CMake)
+#undef BSONCXX_VERSION_EXTRA
+#pragma pop_macro("BSONCXX_VERSION_EXTRA")
+#undef BSONCXX_VERSION_MAJOR
+#pragma pop_macro("BSONCXX_VERSION_MAJOR")
+#undef BSONCXX_VERSION_MINOR
+#pragma pop_macro("BSONCXX_VERSION_MINOR")
+#undef BSONCXX_VERSION_PATCH
+#pragma pop_macro("BSONCXX_VERSION_PATCH")
+
+#if !defined(BSONCXX_V1_INSIDE_MACRO_GUARD_SCOPE)
+#error "postlude header included without matching prelude header"
+#endif
+#undef BSONCXX_V1_INSIDE_MACRO_GUARD_SCOPE

src/bsoncxx/include/bsoncxx/v1/bsoncxx/config/prelude.hpp

@@ -0,0 +1,167 @@
+// Copyright 2023 MongoDB Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+///
+/// @file bsoncxx/v1/bsoncxx/config/prelude.hpp
+///
+/// Macro guard prelude header for bsoncxx.
+///
+/// Ensures any config macro defined in config headers do not conflict with existing definitions
+/// prior to inclusion. To obtain config macros without macro guard behavior, include the
+/// corresponding config header directly.
+///
+/// Prior definitions of conflicting macros are restored by including the @ref
+/// bsoncxx/v1/bsoncxx/config/postlude.hpp "matching postlude header".
+///
+/// @warning Include of the prelude header twice in a row without a matching include of the postlude
+/// header for the first include is forbidden (e.g. prelude -> prelude -> postlude -> postlude).
+/// This is to enforce correct use of macro guard headers across transitive includes.
+///
+/// @warning Include of the postlude header must be preceeded by a matching include of the prelude
+/// header.
+///
+/// @note Include of the matching postlude header may be omitted if restoring prior definitions of
+/// conflicting macros is not necessary, e.g. in source (.cpp) files.
+///
+/// @par Includes
+/// @li bsoncxx/v1/bsoncxx/config/compiler.hpp
+/// @li @ref bsoncxx-v1-bsoncxx-config-config-hpp "bsoncxx/v1/bsoncxx/config/config.hpp"
+/// @li @ref bsoncxx-v1-bsoncxx-config-export-hpp "bsoncxx/v1/bsoncxx/config/export.hpp"
+/// @li @ref bsoncxx-v1-bsoncxx-config-version-hpp "bsoncxx/v1/bsoncxx/config/version.hpp"
+///
+
+#if defined(BSONCXX_V1_INSIDE_MACRO_GUARD_SCOPE)
+#error "prelude header included twice without matching postlude"
+#endif
+
+/// Used to validate correct use of macro guard headers.
+#define BSONCXX_V1_INSIDE_MACRO_GUARD_SCOPE
+
+// compiler.hpp
+#pragma push_macro("BSONCXX_INLINE")
+#undef BSONCXX_INLINE
+#pragma push_macro("BSONCXX_CALL")
+#undef BSONCXX_CALL
+
+// config.hpp (generated by CMake)
+#pragma push_macro("BSONCXX_POLY_USE_MNMLSTC")
+#undef BSONCXX_POLY_USE_MNMLSTC
+#pragma push_macro("BSONCXX_POLY_USE_STD_EXPERIMENTAL")
+#undef BSONCXX_POLY_USE_STD_EXPERIMENTAL
+#pragma push_macro("BSONCXX_POLY_USE_SYSTEM_MNMLSTC")
+#undef BSONCXX_POLY_USE_SYSTEM_MNMLSTC
+#pragma push_macro("BSONCXX_POLY_USE_BOOST")
+#undef BSONCXX_POLY_USE_BOOST
+
+// export.hpp (generated by CMake)
+#pragma push_macro("BSONCXX_API_H")
+#undef BSONCXX_API_H
+#pragma push_macro("BSONCXX_API")
+#undef BSONCXX_API
+#pragma push_macro("BSONCXX_PRIVATE")
+#undef BSONCXX_PRIVATE
+#pragma push_macro("BSONCXX_DEPRECATED")
+#undef BSONCXX_DEPRECATED
+#pragma push_macro("BSONCXX_DEPRECATED_EXPORT")
+#undef BSONCXX_DEPRECATED_EXPORT
+#pragma push_macro("BSONCXX_DEPRECATED_NO_EXPORT")
+#undef BSONCXX_DEPRECATED_NO_EXPORT
+
+// version.hpp (generated by CMake)
+#pragma push_macro("BSONCXX_VERSION_EXTRA")
+#undef BSONCXX_VERSION_EXTRA
+#pragma push_macro("BSONCXX_VERSION_MAJOR")
+#undef BSONCXX_VERSION_MAJOR
+#pragma push_macro("BSONCXX_VERSION_MINOR")
+#undef BSONCXX_VERSION_MINOR
+#pragma push_macro("BSONCXX_VERSION_PATCH")
+#undef BSONCXX_VERSION_PATCH
+
+#include <bsoncxx/v1/bsoncxx/config/compiler.hpp>
+#include <bsoncxx/v1/bsoncxx/config/config.hpp>
+#include <bsoncxx/v1/bsoncxx/config/export.hpp>
+#include <bsoncxx/v1/bsoncxx/config/version.hpp>
+
+// Doxygen does not account for generated header files.
+// Document globally applicable macros and namespaces here.
+
+// Doxygen complains if it cannot find at least one `#define` of a documented macro. Use dummy
+// `#define` for macros in generated config headers within this block to satisfy Doxygen.
+#if defined(BSONCXX_SATISFY_DOXYGEN_DEFINES)
+/// @defgroup bsoncxx-v1-bsoncxx-config-config-hpp bsoncxx/v1/bsoncxx/config/config.hpp
+/// A generated config header declaring macros dependent on bsoncxx library configuration.
+/// @sa bsoncxx/v1/bsoncxx/config/prelude.hpp
+/// @{
+
+/// Defined when the bsoncxx library is configured to use experimental standard library headers for
+/// C++17 polyfills.
+#define BSONCXX_POLY_USE_STD_EXPERIMENTAL
+/// Defined when the bsoncxx library is configured to use mnmlstc/core headers for C++17
+/// polyfills.
+#define BSONCXX_POLY_USE_MNMLSTC
+/// Defined when the bsoncxx library is configured to use external mnmlstc/core headers already
+/// installed on the system instead of bundling mnmlstc/core headers with the bsoncxx library.
+#define BSONCXX_POLY_USE_SYSTEM_MNMLSTC
+/// Defined when the bsoncxx library is configured to use  Boost library headers for C++17
+/// polyfills.
+#define BSONCXX_POLY_USE_BOOST
+/// Defined when the bsoncxx library is configured to use standard library headers for C++17
+/// polyfills.
+#define BSONCXX_POLY_USE_STD
+
+/// @}
+
+/// @defgroup bsoncxx-v1-bsoncxx-config-export-hpp bsoncxx/v1/bsoncxx/config/export.hpp
+/// A generated config header declaring macros that control symbol export behavior.
+/// @sa bsoncxx/v1/bsoncxx/config/prelude.hpp
+/// @{
+
+/// Header guard macro generated by CMake.
+#define BSONCXX_API_H
+/// The declared entity is a member of the public API.
+#define BSONCXX_API
+/// The declared entity is excluded from the public API.
+#define BSONCXX_PRIVATE
+/// The declared entity is deprecated.
+#define BSONCXX_DEPRECATED
+/// The declared entity is a deprecated member of the public API.
+#define BSONCXX_DEPRECATED_EXPORT
+/// The declared entity is deprecated and excluded from the public API.
+#define BSONCXX_DEPRECATED_NO_EXPORT
+
+/// @}
+
+/// @defgroup bsoncxx-v1-bsoncxx-config-version-hpp bsoncxx/v1/bsoncxx/config/version.hpp
+/// A generated config header declaring macros describing the bsoncxx library API version number.
+/// @sa bsoncxx/v1/bsoncxx/config/prelude.hpp
+/// @{
+
+/// The API major version number for this bsoncxx library.
+#define BSONCXX_VERSION_MAJOR
+/// The API minor version number for this bsoncxx library.
+#define BSONCXX_VERSION_MINOR
+/// The API patch version number for this bsoncxx library.
+#define BSONCXX_VERSION_PATCH
+/// Additional API version labels for this bsoncxx library.
+#define BSONCXX_VERSION_EXTRA
+
+/// @}
+
+#endif  // defined(BSONCXX_SATISFY_DOXYGEN_DEFINES)
+
+/// @namespace bsoncxx
+/// The top-level namespace for bsoncxx library entities.
+
+/// @namespace bsoncxx::v1
+/// Declares entities compatible with stable ABI version 1.

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/config/compiler.hpp

@@ -12,21 +12,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#if defined(_MSC_VER)
-
-// Disable MSVC warnings that cause a lot of noise related to DLL visibility
-// for types that we don't control (like std::unique_ptr).
-#pragma warning(push)
-#pragma warning(disable : 4251 4275)
-
-#define BSONCXX_INLINE inline BSONCXX_PRIVATE
-
-#define BSONCXX_CALL __cdecl
-
-#else
-
-#define BSONCXX_INLINE inline BSONCXX_PRIVATE
-
-#define BSONCXX_CALL
-
-#endif
+///
+/// @file bsoncxx/v_noabi/bsoncxx/config/compiler.hpp
+///
+/// Remains for backward compatibility.
+///
+/// @par Includes
+/// @li bsoncxx/v1/bsoncxx/config/compiler.hpp
+///
+
+#include <bsoncxx/v1/bsoncxx/config/compiler.hpp>