From 6a406ee1412f10fd27c2e788f2860355406dd0c0 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sat, 11 Jul 2026 23:58:18 +0200 Subject: [PATCH] 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 $<$: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 Co-authored-by: Claude Sonnet 5 --- .../docs/api/macros/json_diagnostics.md | 3 ++- docs/mkdocs/docs/integration/cmake.md | 25 +++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/mkdocs/docs/api/macros/json_diagnostics.md b/docs/mkdocs/docs/api/macros/json_diagnostics.md index 91bdc1b39..d60df5e44 100644 --- a/docs/mkdocs/docs/api/macros/json_diagnostics.md +++ b/docs/mkdocs/docs/api/macros/json_diagnostics.md @@ -38,7 +38,8 @@ When the macro is not defined, the library will define it to its default value. 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. + 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 diff --git a/docs/mkdocs/docs/integration/cmake.md b/docs/mkdocs/docs/integration/cmake.md index 05d1d346f..a8a6d52b6 100644 --- a/docs/mkdocs/docs/integration/cmake.md +++ b/docs/mkdocs/docs/integration/cmake.md @@ -135,6 +135,31 @@ Enable CI build targets. The exact targets are used during the several CI steps Enable [extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) by defining macro [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md). This option is `OFF` by default. +!!! warning "Does not apply to a pre-installed package" + + This option only takes effect when building nlohmann/json from source as part of your own + CMake project (e.g. via [`FetchContent`](#fetchcontent) or [`add_subdirectory`](#external)). + It has **no effect** on a package that was already built and installed elsewhere (Homebrew, + vcpkg, a system package, etc.) — the resulting compile definition is baked into the exported + `nlohmann_jsonTargets.cmake` at install time, and `set(JSON_Diagnostics ON)` before + `find_package()` does not change it (verified against the Homebrew-installed package: the + exported target still carries a fixed `$<$:JSON_DIAGNOSTICS=1>`, regardless of any + variable set in the consuming project). + + To enable extended diagnostics for a pre-installed package, override the imported target's + property directly after `find_package()`: + + ```cmake + find_package(nlohmann_json REQUIRED) + set_target_properties(nlohmann_json::nlohmann_json PROPERTIES + INTERFACE_COMPILE_DEFINITIONS "JSON_DIAGNOSTICS=1") + ``` + + This only works cleanly when your project is the sole consumer of that imported target. If + nlohmann_json is pulled in from more than one place in your dependency graph with different + `JSON_DIAGNOSTICS` values, you may see a `"JSON_DIAGNOSTICS" redefined` compiler error, since + conflicting `-D` flags can end up on the same compile command line. + ### `JSON_Diagnostic_Positions` Enable position diagnostics by defining macro [`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md). This option is `OFF` by default.