Niels Lohmann
a47170346a
* docs: new design for the documentation site Apply the brand to the Material for MkDocs site: Inter and JetBrains Mono served by the site (upright and real italic), brand colours, blue header band with the syntax pattern, wordmark in the header, new home page (hero, cards, animated feature tour), 404 page, polish for tabs, search, footer, focus rings, tables and code blocks, and theme features (code copy, previous/next footer, TOC follow, search suggestions). Draw the number railroad diagram, the parser callback events and the iterator illustrations as inline SVGs that follow the light and dark scheme. The generator scripts are in docs/mkdocs/scripts/figures; the feature slideshow (json-light.svg, json-dark.svg, replacing json.gif on the home page) is built by docs/mkdocs/scripts/slideshow. Decision nodes in five flowcharts become hexagons, which need far less room. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: add figures, table captions and a macro chooser - Figures with numbered captions: SAX stepper, json_view layout and edit stepper, exception map, JSON pointer and patch walkers, QA pipeline, scaling and binary size charts, roadmap lanes, release timeline, integration decision tree and namespace builder - Table captions (nj-table-caption) on 9 pages - Compile times: modules and PCH charts, filesystem section, re-measured Figure 1, links between features/modules.md and compile_times.md - Interactive macro chooser for features/arbitrary_types.md - Link check: exclude URLs that answer the plugin with 400/401/419 or are dead (customers.md) Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: macro chooser generates adl_serializer for non-default-constructible types Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: cross-link concept pages and API pages in See also sections Add See also links in both directions between the concept pages (features, home, integration) and the API pages, write API links in code font, give every entry a comment after a dash, and show the callback event figure on the parser callbacks page. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: address review comments on the new design - Home: add a "Latest release" button - Sponsors: update the list and group it by tier - Features: list all feature pages on the index page - Releases: add highlights per release, link the 4.0 roadmap, add the first commit to the timeline - Exceptions: prefix all example messages with the exception name - API: no code font for format names in the See also links of the to_/from_ pages - Merge Patch: show the document before, the patch, and the result - Replace "--" with typographic dashes, mark external links with an icon, center Mermaid diagrams Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.4 KiB
Debugging
This page collects the library's built-in debugger integrations and other debugging-related features. They are not covered by any single page elsewhere in the docs, so they are collected here.
Visual Studio (natvis)
The repository ships nlohmann_json.natvis
at its root, a Natvis
file that gives json/ordered_json values a friendly, key/value debugger view instead of showing raw internal
fields, when debugging with the MSVC debug engine (cppvsdbg) in Visual Studio or VS Code.
The checked-in visualizers cover namespace variants with zero, one, or two ABI tags. Configurations with three or more ABI tags are not covered and may show raw internal fields instead. To generate a Natvis file for such a configuration:
-
Check out the release tag of the library version you use.
-
List the ABI tags and the macros that enable them:
make natvis NATVIS_ARGS="--list-tags" -
Generate a Natvis file with the tags of your configuration, for example for
JSON_DIAGNOSTICS,JSON_DIAGNOSTIC_POSITIONS, andJSON_NO_SIMD:make natvis NATVIS_ARGS="--abi-tags _diag,_dp,_ns --output my_nlohmann_json.natvis" -
Use the generated file instead of
nlohmann_json.natvis.
--abi-tags can be repeated for several configurations, and --all generates every combination (about 60 MB for 12
ABI tags, doubling with each further tag). See
tools/generate_natvis for all options.
Debug engines that wrap LLDB instead of the MSVC debug engine (for example, codelldb in VS Code) only have
partial/experimental Natvis support, and commonly fall back to showing raw internal fields even with the
.natvis file present. Switching to cppvsdbg where available, or checking your debug extension's own Natvis
support/version, are the next things to try if this happens. There is currently no bundled LLDB-native
pretty-printer script in this repository.
GDB
The repository ships a GDB Python pretty printer
under tools/gdb_pretty_printer, with its own usage instructions in that directory's README.md.
Extended exception diagnostics
Defining JSON_DIAGNOSTICS before including the library augments
type_error/out_of_range-style exceptions with a JSON Pointer to the offending value, which can help pinpoint
where in a large document a runtime error occurred. This only applies to exceptions thrown after a value
exists (e.g. during element access); parse errors, which happen before any value exists to point at, are not
covered by this mechanism — see Parsing and exceptions for how parse
errors report their own location instead.
See also
JSON_DIAGNOSTICS- extended exception messages with the path of the failing valueJSON_DIAGNOSTIC_POSITIONS- record byte positions of values for error messages- Exceptions - all exceptions and their error codes
exception- base class of all exceptions thrown by the library