Restructure inline namespace and allow version component to be disabl…

…ed (#3683)
nlohmann · Aug 10, 2022 · 0e61ee8 · 0e61ee8
1 parent 93112fb
commit 0e61ee8
Show file tree

Hide file tree

Showing 21 changed files with 501 additions and 100 deletions.
diff --git a/docs/docset/docSet.sql b/docs/docset/docSet.sql
@@ -183,6 +183,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('Iterators', 'Guide', 'feature
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON Merge Patch', 'Guide', 'features/merge_patch/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON Patch and Diff', 'Guide', 'features/json_patch/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON Pointer', 'Guide', 'features/json_pointer/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('nlohmann Namespace', 'Guide', 'features/namespace/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('Types', 'Guide', 'features/types/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('Types: Number Handling', 'Guide', 'features/types/number_handling/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('Object Order', 'Guide', 'features/object_order/index.html');
@@ -225,6 +226,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('NLOHMANN_DEFINE_TYPE_NON_INTR
 INSERT INTO searchIndex(name, type, path) VALUES ('NLOHMANN_JSON_NAMESPACE', 'Macro', 'api/macros/nlohmann_json_namespace/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('NLOHMANN_JSON_NAMESPACE_BEGIN', 'Macro', 'api/macros/nlohmann_json_namespace_begin/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('NLOHMANN_JSON_NAMESPACE_END', 'Macro', 'api/macros/nlohmann_json_namespace_begin/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('NLOHMANN_JSON_NAMESPACE_NO_VERSION', 'Macro', 'api/macros/nlohmann_json_namespace_no_version/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('NLOHMANN_JSON_SERIALIZE_ENUM', 'Macro', 'api/macros/nlohmann_json_serialize_enum/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('NLOHMANN_JSON_VERSION_MAJOR', 'Macro', 'api/macros/nlohmann_json_version_major/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('NLOHMANN_JSON_VERSION_MINOR', 'Macro', 'api/macros/nlohmann_json_version_major/index.html');

diff --git a/docs/examples/nlohmann_json_namespace.output b/docs/examples/nlohmann_json_namespace.output
@@ -1 +1 @@
-nlohmann::json_v3_11_1
+nlohmann::json_abi_v3_11_1
diff --git a/docs/examples/nlohmann_json_namespace_no_version.cpp b/docs/examples/nlohmann_json_namespace_no_version.cpp
@@ -0,0 +1,13 @@
+#include <iostream>
+
+#define NLOHMANN_JSON_NAMESPACE_NO_VERSION 1
+#include <nlohmann/json.hpp>
+
+// macro needed to output the NLOHMANN_JSON_NAMESPACE as string literal
+#define Q(x) #x
+#define QUOTE(x) Q(x)
+
+int main()
+{
+    std::cout << QUOTE(NLOHMANN_JSON_NAMESPACE) << std::endl;
+}
diff --git a/docs/examples/nlohmann_json_namespace_no_version.output b/docs/examples/nlohmann_json_namespace_no_version.output
@@ -0,0 +1 @@
+nlohmann::json_abi
diff --git a/docs/mkdocs/docs/api/macros/index.md b/docs/mkdocs/docs/api/macros/index.md
@@ -32,7 +32,10 @@ header. See also the [macro overview page](../../features/macros.md).
 ## Library namespace
 
 - [**NLOHMANN_JSON_NAMESPACE**](nlohmann_json_namespace.md) - full name of the `nlohmann` namespace
-- [**NLOHMANN_JSON_NAMESPACE_BEGIN**<br>**NLOHMANN_JSON_NAMESPACE_END**](nlohmann_json_namespace_begin.md) - open and close the library namespace
+- [**NLOHMANN_JSON_NAMESPACE_BEGIN**<br>**NLOHMANN_JSON_NAMESPACE_END**](nlohmann_json_namespace_begin.md) - open and
+  close the library namespace
+- [**NLOHMANN_JSON_NAMESPACE_NO_VERSION**](nlohmann_json_namespace_no_version.md) - disable the version component of
+  the inline namespace
 
 ## Type conversions
 

diff --git a/docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md b/docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md
@@ -1,19 +1,18 @@
 # NLOHMANN_JSON_NAMESPACE
 
 ```cpp
-#define NLOHMANN_JSON_NAMESPACE
+#define NLOHMANN_JSON_NAMESPACE /* value */
 ```
 
-This macro evaluates to the full name of the `nlohmann` namespace, including  the name of a versioned and ABI-tagged
-inline namespace. Use this macro to unambiguously refer to the `nlohmann` namespace.
+This macro evaluates to the full name of the `nlohmann` namespace.
 
 ## Default definition
 
-The default value consists of a prefix, a version string, and optional ABI tags depending on whether ABI-affecting
-macros are defined (e.g., [`JSON_DIAGNOSTICS`](json_diagnostics.md), and
-[`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](json_use_legacy_discarded_value_comparison.md)).
+The default value consists of the root namespace (`nlohmann`) and an inline ABI namespace. See
+[`nlohmann` Namespace](../../features/namespace.md#structure) for details.
 
-When the macro is not defined, the library will define it to its default value.
+When the macro is not defined, the library will define it to its default value. Overriding this value has no effect on
+the library.
 
 ## Examples
 
@@ -35,7 +34,8 @@ When the macro is not defined, the library will define it to its default value.
 ## See also
 
 - [`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](nlohmann_json_namespace_begin.md)
+- [`NLOHMANN_JSON_NAMESPACE_NO_VERSION`](nlohmann_json_namespace_no_version.md)
 
 ## Version history
 
-- Added in version 3.11.0.
+- Added in version 3.11.0. Changed inline namespace name in version 3.11.2.
diff --git a/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md b/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md
@@ -1,38 +1,43 @@
 # NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END
 
 ```cpp
-#define NLOHMANN_JSON_NAMESPACE_BEGIN  // (1)
-#define NLOHMANN_JSON_NAMESPACE_END    // (2)
+#define NLOHMANN_JSON_NAMESPACE_BEGIN /* value */  // (1)
+#define NLOHMANN_JSON_NAMESPACE_END   /* value */  // (2)
 ```
 
-These macros can be used to open and close the `nlohmann` namespace. They include an inline namespace used to
-differentiate symbols when linking multiple versions (including different ABI-affecting macros) of this library.
+These macros can be used to open and close the `nlohmann` namespace. See
+[`nlohmann` Namespace](../../features/namespace.md#structure) for details.
 
 1. Opens the namespace.
+2. Closes the namespace.
+
+## Default definition
+
+The default definitions open and close the `nlohmann` namespace. The precise definition of
+[`NLOHMANN_JSON_NAMESPACE_BEGIN`] varies as described [here](../../features/namespace.md#structure).
+
+1. Default definition of `NLOHMANN_JSON_NAMESPACE_BEGIN`:
+
     ```cpp
     namespace nlohmann
     {
-    inline namespace json_v3_11_0
+    inline namespace json_abi_v3_11_2
     {
     ```
 
-2. Closes the namespace.
+2. Default definition of `NLOHMANN_JSON_NAMESPACE_END`:
     ```cpp
+    }  // namespace json_abi_v3_11_2
     }  // namespace nlohmann
-    }  // json_v3_11_0
     ```
 
-## Default definition
-
-The default definitions open and close the `nlohmann` as well as an inline  namespace.
-
 When these macros are not defined, the library will define them to their default definitions.
 
 ## Examples
 
 ??? example
 
-    The example shows an example how to use `NLOHMANN_JSON_NAMESPACE_BEGIN`/`NLOHMANN_JSON_NAMESPACE_END` from the
+    The example shows how to use `NLOHMANN_JSON_NAMESPACE_BEGIN`/`NLOHMANN_JSON_NAMESPACE_END` from the
     [How do I convert third-party types?](../../features/arbitrary_types.md#how-do-i-convert-third-party-types) page.
 
     ```cpp
@@ -47,8 +52,10 @@ When these macros are not defined, the library will define them to their default
 
 ## See also
 
+- [`nlohmann` Namespace](../../features/namespace.md)
 - [NLOHMANN_JSON_NAMESPACE](nlohmann_json_namespace.md)
+- [`NLOHMANN_JSON_NAMESPACE_NO_VERSION`](nlohmann_json_namespace_no_version.md)
 
 ## Version history
 
-- Added in version 3.11.0.
+- Added in version 3.11.0. Changed inline namespace name in version 3.11.2.
diff --git a/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_no_version.md b/docs/mkdocs/docs/api/macros/nlohmann_json_namespace_no_version.md
@@ -0,0 +1,45 @@
+# NLOHMANN_JSON_NAMESPACE_NO_VERSION
+
+```cpp
+#define NLOHMANN_JSON_NAMESPACE_NO_VERSION /* value */
+```
+
+If defined to `1`, the version component is omitted from the inline namespace. See
+[`nlohmann` Namespace](../../features/namespace.md#structure) for details.
+
+## Default definition
+
+The default value is `0`.
+
+```cpp
+#define NLOHMANN_JSON_NAMESPACE_NO_VERSION 0
+```
+
+When the macro is not defined, the library will define it to its default value.
+
+## Examples
+
+??? example
+
+    The example shows how to use `NLOHMANN_JSON_NAMESPACE_NO_VERSION` to disable the version component of the inline
+    namespace.
+
+    ```cpp
+    --8<-- "examples/nlohmann_json_namespace_no_version.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/nlohmann_json_namespace_no_version.output"
+    ```
+
+## See also
+
+- [`nlohmann` Namespace](../../features/namespace.md)
+- [`NLOHMANN_JSON_NAMESPACE`](nlohmann_json_namespace.md)
+- [`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](nlohmann_json_namespace_begin.md)
+
+## Version history
+
+- Added in version 3.11.2.
diff --git a/docs/mkdocs/docs/features/namespace.md b/docs/mkdocs/docs/features/namespace.md
@@ -0,0 +1,93 @@
+# `nlohmann` Namespace
+
+The 3.11.0 release introduced an
+[inline namespace](https://en.cppreference.com/w/cpp/language/namespace#Inline_namespaces) to allow different parts of
+a codebase to safely use different versions of the JSON library as long as they never exchange instances of library
+types.
+
+## Structure
+
+The complete default namespace name is derived as follows:
+
+- The root namespace is always `nlohmann`.
+- The inline namespace starts with `json_abi` and is followed by serveral optional ABI tags according to the value of
+  these ABI-affecting macros, in order:
+    - [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) defined non-zero appends `_diag`.
+    - [`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](../api/macros/json_use_legacy_discarded_value_comparison.md)
+      defined non-zero appends `_ldvcmp`.
+- The inline namespace ends with the suffix `_v` followed by the 3 components of the version number separated by
+  underscores. To omit the version component, see [Disabling the version component](#disabling-the-version-component)
+  below.
+
+For example, the namespace name for version 3.11.2 with `JSON_DIAGNOSTICS` defined to `1` is:
+
+```cpp
+nlohmann::json_abi_diag_v3_11_2
+```
+
+## Purpose
+
+Several incompatibilities have been observed. Amongst the most common ones is linking code compiled with different
+definitions of [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md). This is illustrated in the diagram below.
+
+```plantuml
+[**nlohmann_json (v3.10.5)**\nJSON_DIAGNOSTICS=0] as [json]
+[**nlohmann_json (v3.10.5)**\nJSON_DIAGNOSTICS=1] as [json_diag]
+[**some_library**] as [library]
+[**application**] as [app]
+
+[library] ..|> [json]
+[app] ..|> [json_diag]
+[app] ..|>[library]
+```
+
+In releases prior to 3.11.0, mixing any version of the JSON library with different `JSON_DIAGNOSTICS` settings would
+result in a crashing application. If `some_library` never passes instances of JSON library types to the application,
+this scenario became safe in version 3.11.0 and above due to the inline namespace yielding distinct symbol names.
+
+## Limitations
+
+Neither the compiler nor the linker will issue as much as a warning when translation units – intended to be linked
+together and that include different versions and/or configurations of the JSON library – exchange and use library
+types.
+
+There is an exception when forward declarations are used (i.e., when including `json_fwd.hpp`) in which case the linker
+may complain about undefined references.
+
+## Disabling the version component
+
+Different versions are not necessarily ABI-incompatible, but the project does not actively track changes in the ABI and
+recommends that all parts of a codebase exchanging library types be built with the same version. Users can, **at their
+own risk**, disable the version component of the linline namespace, allowing different versions – but not
+configurations – to be used in cases where the linker would otherwise output undefined reference errors.
+
+To do so, define [`NLOHMANN_JSON_NAMESPACE_NO_VERSION`](../api/macros/nlohmann_json_namespace_no_version.md) to `1`.
+
+This applies to version 3.11.2 and above only, versions 3.11.0 and 3.11.1 can apply the technique described in the next
+section to emulate the effect of the `NLOHMANN_JSON_NAMESPACE_NO_VERSION` macro.
+
+!!! danger "Use at your own risk"
+
+    Disabling the namespace version component and mixing ABI-incompatible versions will result in crashes or incorrect
+    behavior. You have been warned!
+## Disabling the inline namespace completely
+
+When interoperability with code using a pre-3.11.0 version of the library is required, users can, **at their own risk**
+restore the old namespace layout by redefining
+[`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](../api/macros/nlohmann_json_namespace_begin.md) as
+follows:
+
+```cpp
+#define NLOHMANN_JSON_NAMESPACE_BEGIN  namespace nlohmann {
+#define NLOHMANN_JSON_NAMESPACE_END    }
+```
+
+!!! danger "Use at your own risk"
+
+    Overriding the namespace and mixing ABI-incompatible versions will result in crashes or incorrect behavior. You
+    have been warned!
+
+## Version history
+
+- Introduced inline namespace (`json_v3_11_0[_abi-tag]*`) in version 3.11.0.
+- Changed structure of inline namespace in version 3.11.2.
diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml
@@ -58,6 +58,7 @@ nav:
     - features/json_pointer.md
     - features/json_patch.md
     - features/merge_patch.md
+    - 'nlohmann Namespace': features/namespace.md
     - features/object_order.md
     - Parsing:
         - features/parsing/index.md
@@ -270,6 +271,7 @@ nav:
         - 'NLOHMANN_JSON_NAMESPACE': api/macros/nlohmann_json_namespace.md
         - 'NLOHMANN_JSON_NAMESPACE_BEGIN': api/macros/nlohmann_json_namespace_begin.md
         - 'NLOHMANN_JSON_NAMESPACE_END': api/macros/nlohmann_json_namespace_begin.md
+        - 'NLOHMANN_JSON_NAMESPACE_NO_VERSION': api/macros/nlohmann_json_namespace_no_version.md
         - 'NLOHMANN_JSON_SERIALIZE_ENUM': api/macros/nlohmann_json_serialize_enum.md
         - 'NLOHMANN_JSON_VERSION_MAJOR': api/macros/nlohmann_json_version_major.md
         - 'NLOHMANN_JSON_VERSION_MINOR': api/macros/nlohmann_json_version_major.md

diff --git a/include/nlohmann/detail/abi_macros.hpp b/include/nlohmann/detail/abi_macros.hpp
@@ -42,38 +42,59 @@
     #define NLOHMANN_JSON_ABI_TAG_LEGACY_DISCARDED_VALUE_COMPARISON
 #endif
 
-#define NLOHMANN_JSON_ABI_PREFIX_EX(major, minor, patch) \
-    json_v ## major ## _ ## minor ## _ ## patch
-#define NLOHMANN_JSON_ABI_PREFIX(major, minor, patch) \
-    NLOHMANN_JSON_ABI_PREFIX_EX(major, minor, patch)
-
-#define NLOHMANN_JSON_ABI_CONCAT_EX(a, b, c) a ## b ## c
-#define NLOHMANN_JSON_ABI_CONCAT(a, b, c) \
-    NLOHMANN_JSON_ABI_CONCAT_EX(a, b, c)
-
-#define NLOHMANN_JSON_ABI_STRING                                    \
-    NLOHMANN_JSON_ABI_CONCAT(                                       \
-            NLOHMANN_JSON_ABI_PREFIX(                               \
-                    NLOHMANN_JSON_VERSION_MAJOR,                    \
-                    NLOHMANN_JSON_VERSION_MINOR,                    \
-                    NLOHMANN_JSON_VERSION_PATCH),                   \
-            NLOHMANN_JSON_ABI_TAG_DIAGNOSTICS,                      \
+#ifndef NLOHMANN_JSON_NAMESPACE_NO_VERSION
+    #define NLOHMANN_JSON_NAMESPACE_NO_VERSION 0
+#endif
+
+// Construct the namespace ABI tags component
+#define NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b) json_abi ## a ## b
+#define NLOHMANN_JSON_ABI_TAGS_CONCAT(a, b) \
+    NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b)
+
+#define NLOHMANN_JSON_ABI_TAGS                                       \
+    NLOHMANN_JSON_ABI_TAGS_CONCAT(                                   \
+            NLOHMANN_JSON_ABI_TAG_DIAGNOSTICS,                       \
             NLOHMANN_JSON_ABI_TAG_LEGACY_DISCARDED_VALUE_COMPARISON)
 
+// Construct the namespace version component
+#define NLOHMANN_JSON_NAMESPACE_VERSION_CONCAT_EX(major, minor, patch) \
+    _v ## major ## _ ## minor ## _ ## patch
+#define NLOHMANN_JSON_NAMESPACE_VERSION_CONCAT(major, minor, patch) \
+    NLOHMANN_JSON_NAMESPACE_VERSION_CONCAT_EX(major, minor, patch)
+
+#if NLOHMANN_JSON_NAMESPACE_NO_VERSION
+#define NLOHMANN_JSON_NAMESPACE_VERSION
+#else
+#define NLOHMANN_JSON_NAMESPACE_VERSION                                 \
+    NLOHMANN_JSON_NAMESPACE_VERSION_CONCAT(NLOHMANN_JSON_VERSION_MAJOR, \
+                                           NLOHMANN_JSON_VERSION_MINOR, \
+                                           NLOHMANN_JSON_VERSION_PATCH)
+#endif
+
+// Combine namespace components
+#define NLOHMANN_JSON_NAMESPACE_CONCAT_EX(a, b) a ## b
+#define NLOHMANN_JSON_NAMESPACE_CONCAT(a, b) \
+    NLOHMANN_JSON_NAMESPACE_CONCAT_EX(a, b)
+
 #ifndef NLOHMANN_JSON_NAMESPACE
-    #define NLOHMANN_JSON_NAMESPACE nlohmann::NLOHMANN_JSON_ABI_STRING
+#define NLOHMANN_JSON_NAMESPACE               \
+    nlohmann::NLOHMANN_JSON_NAMESPACE_CONCAT( \
+            NLOHMANN_JSON_ABI_TAGS,           \
+            NLOHMANN_JSON_NAMESPACE_VERSION)
 #endif
 
 #ifndef NLOHMANN_JSON_NAMESPACE_BEGIN
-#define NLOHMANN_JSON_NAMESPACE_BEGIN         \
-    namespace nlohmann                        \
-    {                                         \
-    inline namespace NLOHMANN_JSON_ABI_STRING \
+#define NLOHMANN_JSON_NAMESPACE_BEGIN                \
+    namespace nlohmann                               \
+    {                                                \
+    inline namespace NLOHMANN_JSON_NAMESPACE_CONCAT( \
+                NLOHMANN_JSON_ABI_TAGS,              \
+                NLOHMANN_JSON_NAMESPACE_VERSION)     \
     {
 #endif
 
 #ifndef NLOHMANN_JSON_NAMESPACE_END
-#define NLOHMANN_JSON_NAMESPACE_END \
-    }  /* namespace (abi_string) */ \
-    }  /* namespace nlohmann */
+#define NLOHMANN_JSON_NAMESPACE_END                                     \
+    }  /* namespace (inline namespace) NOLINT(readability/namespace) */ \
+    }  // namespace nlohmann
 #endif