Niels Lohmann
6197341a21
* Clean up README, contribution guide, and repository metadata - REUSE.toml: fix the Hedley path and SPDX id (CC0-1.0), mark the docset icons as the public-domain JSON logo - CITATION.cff: v3.12.0 was released on 2025-04-11 - FILES.md: list all workflows, describe the Meson option defaults - README: ctest -LE, table of contents, typos, stale Android/MinGW advice, moved links, merge duplicate Thanks entries, list the analysis tools used in CI - CONTRIBUTING: iterative parser, json_literals.hpp is generated, links - .gitignore: backups and release outputs; .gitattributes: mark generated files - labeler: label other build systems and .github documentation - MODULE.bazel: add the module version Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Clean up CI, CMake, Makefile, and Bazel files - CMakeLists.txt: avoid VERSION_GREATER_EQUAL, which CMake < 3.7 lacks - ci.cmake: test JSON_DisableTupleReferenceConversion in ci_cmake_flags, remove unused variables and unreachable per-compiler targets, look up Clang tools consistently, forward CMAKE_CXX_FLAGS to ci_module_cpp20, format json_literals.hpp and remove backups in ci_test_amalgamation - BUILD.bazel: add json_literals.hpp to the single-header target - workflows: format json_literals.hpp before copying it, drop the obsolete natvis --version plumbing, name natvis and macro_builder in failure messages, drop the duplicate amalgamation job, install Valgrind only where needed, republish docs on version bumps, fix stale names - Makefile: complete .PHONY and help, check-amalgamation always restores the checked-in files, natvis uses its own venv, macro_builder_check installs astyle, clean removes the fuzzer binaries - remove tools/amalgamate/config_json_view.json (json_view.hpp is not on develop yet) Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix inaccuracies in the documentation - version history: json_base_class_t (3.11.3), JSON_HAS_CPP_11 (3.10.0), JSON_HAS_RANGES exclusions, define-type macros, ABI tags - releases: 3.12.0 raised the minimum CMake version - from_*: the (ptr, len) overloads are deleted, not removed, in 4.0.0 - contains/count/find: document the deleted integral overloads - add JSON_HAS_RANGE_VIEW_CONVERSION and list the JSON_HAS_* macros in the macro overview - mention BON8 and error_handler where binary formats are listed - broken links, outdated URLs, warning count, Hunter v0.26.12 - copy_markdown_source hook: expand snippets in the Markdown copies Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Pass /EHsc to the Windows C++20 module build ci_module_cpp20 now forwards CMAKE_CXX_FLAGS to the module build. The Windows workflow sets CMAKE_CXX_FLAGS, which replaces CMake's MSVC defaults including /EHsc, so <chrono> failed with C4530 under /WX. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
5.5 KiB
nlohmann Namespace
The 3.11.0 release introduced an inline namespace 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_abiand is followed by several optional ABI tags according to the value of these ABI-affecting macros, in order:JSON_DIAGNOSTICSdefined non-zero appends_diag.JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISONdefined non-zero appends_ldvcmp.JSON_DIAGNOSTIC_POSITIONSdefined non-zero appends_dp.JSON_BRACE_INIT_COPY_SEMANTICSdefined non-zero appends_bics.JSON_PRECISE_STREAM_POSITIONdefined non-zero appends_psp.JSON_STRICT_NUL_HANDLINGdefined non-zero appends_snul.JSON_STRICT_BINARY_UTF8defined non-zero appends_sbu8.JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPSdefined non-zero appends_ekmo.
- The inline namespace ends with the suffix
_vfollowed by the 3 components of the version number separated by underscores. To omit the version component, see Disabling the version component below.
For example, the namespace name for version 3.11.2 with JSON_DIAGNOSTICS defined to 1 is:
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. This is illustrated in the diagram below.
graph
json["<strong>nlohmann_json (v3.10.5)</strong><br>JSON_DIAGNOSTICS=0"]
json_diag["<strong>nlohmann_json (v3.10.5)</strong><br>JSON_DIAGNOSTICS=1"]
library["<strong>some library</strong>"]
app["<strong>application</strong>"]
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 inline 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 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 as
follows:
#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.
- Added ABI tag
_dp(JSON_DIAGNOSTIC_POSITIONS) in version 3.12.0. - Added ABI tags
_bics(JSON_BRACE_INIT_COPY_SEMANTICS),_psp(JSON_PRECISE_STREAM_POSITION),_snul(JSON_STRICT_NUL_HANDLING),_sbu8(JSON_STRICT_BINARY_UTF8), and_ekmo(JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS) in version 3.13.0.