Skip to content

Document options to reduce compile times - #5611

Merged
nlohmann merged 2 commits into
developfrom
claude/compile-time-docs
Oct 4, 2026
Merged

nlohmann merged 2 commits into
developfrom
claude/compile-time-docs

Conversation

@nlohmann

@nlohmann nlohmann commented Sep 28, 2026 •

Copy link
Copy Markdown
Owner

Stacked on #5610. Adds the documentation page Integration › Compile times, which collects the options discussed in #5294 to reduce compile times, each with measurements (C++17, Apple clang and GCC 16, -O0/-O2, median of 9 runs):

Option Where it helps Measured change
json_fwd.hpp in headers headers that only name json −53 % (clang), −69 % (GCC)
JSON_NO_AUTOMATIC_UDLS (#5610) + json_literals.hpp where needed TUs that don't parse −14 … −19 % (up to about −33 % for include-only TUs); parsing TUs unchanged
extern template class nlohmann::basic_json<>; + one explicit instantiation TU TUs using json −4 … −10 % (clang), −20 … −25 % (GCC); the instantiation TU takes 2–5 s (clang) / 5–11 s (GCC), once
C++20 modules everywhere refers to the existing Modules page (experimental)
Precompiled headers everywhere general CMake hint, not measured
JSON_NO_IO, JSON_USE_GLOBAL_UDLS=0 — no measurable effect (listed explicitly so people don't reach for them)

I compiled and linked the extern template example with clang (C++11/17) and GCC 16 (C++17). The page also notes that member templates (get<T>(), parse(...)) are not covered by the explicit instantiation, and that ordered_json needs its own lines.

Also links the page from the integration index and the JSON_NO_AUTOMATIC_UDLS page, and adds it to the navigation.

Public API

No changes. This is documentation only.


This PR description was written by Claude Code.

🤖 Generated with Claude Code

@nlohmann
nlohmann added this pull request to stack #5612 September 28, 2026 20:02
@nlohmann nlohmann added the review needed It would be great if someone could review the proposed changes. label Sep 28, 2026
@nlohmann
nlohmann force-pushed the claude/compile-time-docs branch from 5ab47ef to d324da8 Compare September 29, 2026 14:41
@github-actions github-actions Bot removed the tests label Sep 30, 2026
Base automatically changed from claude/json-no-udls-e999fc to develop September 30, 2026 18:08
Add an integration page that collects the ways to reduce compile times
with measurements: json_fwd.hpp in headers, JSON_NO_AUTOMATIC_UDLS,
explicit instantiation with extern template, modules, and precompiled
headers, and notes that JSON_NO_IO and JSON_USE_GLOBAL_UDLS have no
measurable effect.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
@nlohmann
nlohmann force-pushed the claude/compile-time-docs branch from d324da8 to 023ab67 Compare September 30, 2026 18:08

```cpp
#include <nlohmann/json.hpp>
#include <nlohmann/json_literals.hpp> // only where "..."_json is used

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

json_literals.hpp includes json.hpp so this is promoting extra cost. Either json_literals.hpp doesn't include json.hpp or this recommends just including json_literals.hpp. I would be fine with either version.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, done in 2ce78e1: the example (here and in the JSON_NO_AUTOMATIC_UDLS page) now includes only <nlohmann/json_literals.hpp> and mentions that it brings in <nlohmann/json.hpp>.

(Written by Claude Code.)

@gregmarr gregmarr left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One minor suggestion.

@nlohmann nlohmann added 🚀 ready to merge Ready to merge - just waiting for CI to complete. and removed review needed It would be great if someone could review the proposed changes. labels Oct 4, 2026
@nlohmann nlohmann added this to the Release 3.13.0 milestone Oct 4, 2026
json_literals.hpp includes json.hpp itself, so including both is redundant.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
@nlohmann
nlohmann merged commit 0c44626 into develop Oct 4, 2026
9 of 28 checks passed
@nlohmann
nlohmann deleted the claude/compile-time-docs branch October 4, 2026 10:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation L 🚀 ready to merge Ready to merge - just waiting for CI to complete.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants