mirror of https://github.com/nlohmann/json.git synced 2026-07-12 13:35:13 +00:00

Files

T

Niels Lohmann 6a406ee141 Document that JSON_Diagnostics CMake option doesn't apply to pre-installed packages (#5270 )

Closes #3106. set(JSON_Diagnostics ON) before find_package() has no
effect on a package built and installed elsewhere (Homebrew, vcpkg, a
system package, etc.) -- the compile definition is baked into the
exported nlohmann_jsonTargets.cmake at install time and the generated
config script never re-reads that variable. Verified empirically
against the real Homebrew-installed 3.12.0 package: the exported
target carries a fixed $<$<BOOL:OFF>:JSON_DIAGNOSTICS=1>, and the
suggested set(JSON_Diagnostics ON) snippet produces no change in
exception output.

Documents the actual working fix (overriding the imported target's
INTERFACE_COMPILE_DEFINITIONS property after find_package()) and the
multi-target "JSON_DIAGNOSTICS redefined" pitfall reported earlier in
the issue thread.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

2026-07-11 23:58:18 +02:00

2.9 KiB

Raw Blame History

JSON_DIAGNOSTICS

#define JSON_DIAGNOSTICS /* value */

This macro enables extended diagnostics for exception messages. Possible values are 1 to enable or 0 to disable (default).

When enabled, exception messages contain a JSON Pointer to the JSON value that triggered the exception. Note that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead.

Default definition

The default value is 0 (extended diagnostics are switched off).

#define JSON_DIAGNOSTICS 0

When the macro is not defined, the library will define it to its default value.

Notes

!!! note "ABI compatibility"

As of version 3.11.0, this macro is no longer required to be defined consistently throughout a codebase to avoid
One Definition Rule (ODR) violations, as the value of this macro is encoded in the namespace, resulting in distinct
symbol names. 

This allows different parts of a codebase to use different versions or configurations of this library without
causing improper behavior.

Where possible, it is still recommended that all code define this the same way for maximum interoperability.

!!! hint "CMake option"

Diagnostic messages can also be controlled with the CMake option
[`JSON_Diagnostics`](../../integration/cmake.md#json_diagnostics) (`OFF` by default)
which defines `JSON_DIAGNOSTICS` accordingly. Note this only applies when building the
library from source — see the pre-installed-package caveat on that page.

Examples

??? example "Example 1: default behavior"

```cpp
--8<-- "examples/diagnostics_standard.cpp"
```

Output:

```
--8<-- "examples/diagnostics_standard.output"
```

This exception can be hard to debug if storing the value `#!c "12"` and accessing it is further apart.

??? example "Example 2: extended diagnostic messages"

```cpp
--8<-- "examples/diagnostics_extended.cpp"
```

Output:

```
--8<-- "examples/diagnostics_extended.output"
```

Now the exception message contains a JSON Pointer `/address/housenumber` that indicates which value has the wrong type.

??? example "Example 3: using only diagnostic positions in exceptions"

```cpp
--8<-- "examples/diagnostic_positions_exception.cpp"
```

Output:

```
--8<-- "examples/diagnostic_positions_exception.output"
```    
    The output shows the exception with start/end positions only.

Version history

Added in version 3.10.0.
As of version 3.11.0, the definition is allowed to vary between translation units.

2.9 KiB Raw Blame History