Move the user-defined string literals to <nlohmann/json_literals.hpp> and add JSON_NO_AUTOMATIC_UDLS

[nlohmann]

Moves operator""_json and operator""_json_pointer into a new header <nlohmann/json_literals.hpp>. <nlohmann/json.hpp> still includes it by default, but not when JSON_NO_AUTOMATIC_UDLS is defined. This follows the design proposed in #5294 (#5294 (comment)).

Why

The literals are non-template inline functions whose bodies call json::parse, so every translation unit that includes json.hpp instantiates the parser, lexer, and SAX DOM parsers — even if it never parses anything. With JSON_NO_AUTOMATIC_UDLS set for a whole project, only the translation units that include <nlohmann/json_literals.hpp> pay for that. Nothing changes for anyone who does not define the macro.

Changes

• New include/nlohmann/json_literals.hpp contains the literals and the global using-declarations (controlled by JSON_USE_GLOBAL_UDLS). It includes <nlohmann/json.hpp> itself, so it is self-contained. json.hpp includes it at its very end unless JSON_NO_AUTOMATIC_UDLS is defined; include guards make either include order work.
• Only public and standard macros are used in the new header. The library's internal macros are undefined at the end of json.hpp, and the amalgamation inlines macro_scope.hpp only once, so the header cannot reopen the macro scope. As a result:
  • The GCC 4.8 check is spelled out with __GNUC__/__GNUC_MINOR__ instead of JSON_HEDLEY_GCC_VERSION_CHECK.
  • JSON_HEDLEY_NON_NULL(1) on the two const char* overloads is gone. It had no practical effect on a literal operator.
  • The library no longer defines a default for JSON_USE_GLOBAL_UDLS or #undefs it at the end of json.hpp, since that would also erase a user's -DJSON_USE_GLOBAL_UDLS=0 before the new header reads it. The header checks !defined(JSON_USE_GLOBAL_UDLS) || JSON_USE_GLOBAL_UDLS, which keeps the same default.
• Single header: single_include/nlohmann/json_literals.hpp is a verbatim copy, because it only includes <nlohmann/json.hpp>. The amalgamated json.hpp still contains the literals behind the same include guard. The copy is wired into make amalgamate/check-amalgamation, ci_test_amalgamation, the amalgamation workflow (a cp, because that workflow runs the amalgamation tool from develop), include.zip/release files, and Meson install_headers. BUILD.bazel was regenerated. CMake and Swift install the whole directory already.
• Module: json.cppm includes <nlohmann/json_literals.hpp> explicitly, so import nlohmann.json; always exports the literals. I checked this with Homebrew LLVM, with and without the macro.
• Test: new tests/src/unit-no_automatic_udls.cpp. With the macro set, it checks via is_detected that neither the global nor the namespaced literals are declared (probing argument-dependent lookup with a type in the library namespace). It then includes <nlohmann/json_literals.hpp> and uses the literals, both globally and via using namespace. The probes are not vacuous: without the macro, all four fail as expected.
• Docs: new JSON_NO_AUTOMATIC_UDLS page, plus cross-references from the macro overview, JSON_USE_GLOBAL_UDLS, both literal pages, the modules page, and the integration page.

Also verified locally: the test passes with clang and GCC 16, C++11 and C++20, against both include/ and single_include/, with -Wall -Wextra -Wpedantic -Werror. unit-udl still passes in no-global mode (-DJSON_USE_GLOBAL_UDLS=0, also with -Wundef), and test-no-macro-leak, test-readme, test-json_pointer, and test-udt pass.

Compile times

Median of 11 runs against the amalgamated header. empty = only the include, model = a struct with NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE plus a to_json call, parse = one json::parse call.

compiler	std	TU	mode	default [ms]	JSON_NO_AUTOMATIC_UDLS [ms]	change
Apple clang	C++11	empty	-fsyntax-only	625	421	-33%
Apple clang	C++11	empty	-c -O0	640	415	-35%
Apple clang	C++11	model	-fsyntax-only	616	484	-21%
Apple clang	C++11	model	-c -O0	677	534	-21%
Apple clang	C++11	parse	-fsyntax-only	618	598	-3%
Apple clang	C++11	parse	-c -O0	804	806	+0%
Apple clang	C++20	empty	-fsyntax-only	882	668	-24%
Apple clang	C++20	empty	-c -O0	929	691	-26%
Apple clang	C++20	model	-fsyntax-only	891	783	-12%
Apple clang	C++20	model	-c -O0	986	833	-16%
Apple clang	C++20	parse	-fsyntax-only	944	938	-1%
Apple clang	C++20	parse	-c -O0	1098	1141	+4%
GCC 16	C++11	empty	-fsyntax-only	563	378	-33%
GCC 16	C++11	empty	-c -O0	625	416	-33%
GCC 16	C++11	model	-fsyntax-only	567	444	-22%
GCC 16	C++11	model	-c -O0	862	706	-18%
GCC 16	C++11	parse	-fsyntax-only	607	589	-3%
GCC 16	C++11	parse	-c -O0	1670	1584	-5%
GCC 16	C++20	empty	-fsyntax-only	993	769	-23%
GCC 16	C++20	empty	-c -O0	1017	757	-26%
GCC 16	C++20	model	-fsyntax-only	935	790	-16%
GCC 16	C++20	model	-c -O0	1222	1067	-13%
GCC 16	C++20	parse	-fsyntax-only	926	975	+5%
GCC 16	C++20	parse	-c -O0	2007	1971	-2%

Translation units that don't parse get 12–35 % faster. Translation units that parse anyway stay within noise (±5 %), because they instantiate the parser regardless.

Public API

No breaking changes for code that does not define the new macro: the literals, their namespaces, and JSON_USE_GLOBAL_UDLS behave as before. Minor observable differences:

• JSON_USE_GLOBAL_UDLS is no longer #undefined at the end of json.hpp, so a user's own definition now survives the include (before, it was erased).
• The nonnull attribute on the const char* literal overloads is gone.

New: header <nlohmann/json_literals.hpp> and macro JSON_NO_AUTOMATIC_UDLS. A matching CMake option (like JSON_GlobalUDLs) could follow if wanted.

---

This PR description was written by Claude Code.

🤖 Generated with Claude Code

[gregmarr]

See comments at #5294 (comment) for minor tweaks.

[nlohmann]

See comments at #5294 (comment) for minor tweaks.

Adding a new header introduces a lot of moving parts. What do you think?

[gregmarr]

I think if your goal is reducing compile times without breaking anyone, then this is the best way to do that. It allows an opt-in even in the case where someone wants to include this library in a precompiled header, so the base is available everywhere, and then allows the literals to be added where needed.

I think this could be one of those v4.0.0 macros that preserves the current behavior until that release, and then those that need the literals can just include the extra header. The question is whether people would still want it in the single header. I can see things on both sides of this.