mirror of
https://github.com/nlohmann/json.git
synced 2026-11-02 10:55:35 +00:00
47 lines
4.1 KiB
Markdown
47 lines
4.1 KiB
Markdown
# 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`](https://github.com/nlohmann/json/blob/develop/nlohmann_json.natvis) at its root, a [Natvis](https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects) 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 file also has visualizers for `json_document` and `json_view` (and their `ordered_json`/editable variants). They show the value of the document or view, and its elements as an expandable list. Because a document is only a flat index into the source text, the strings of the direct elements are shown, but the elements of nested arrays and objects are shown as index nodes (their kind, size, and numbers; strings only by length). Arrays and objects that have been edited in a `json_editable_document` are not expanded. The visualizers read the internal layout of the MSVC STL (`std::array`, `std::unique_ptr`).
|
|
|
|
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:
|
|
|
|
1. Check out the release tag of the library version you use.
|
|
|
|
1. List the ABI tags and the macros that enable them:
|
|
|
|
```
|
|
make natvis NATVIS_ARGS="--list-tags"
|
|
```
|
|
|
|
1. Generate a Natvis file with the tags of your configuration, for example for `JSON_DIAGNOSTICS`, `JSON_DIAGNOSTIC_POSITIONS`, and `JSON_NO_SIMD`:
|
|
|
|
```
|
|
make natvis NATVIS_ARGS="--abi-tags _diag,_dp,_ns --output my_nlohmann_json.natvis"
|
|
```
|
|
|
|
1. 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 11 ABI tags, doubling with each further tag). See [`tools/generate_natvis`](https://github.com/nlohmann/json/tree/develop/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](https://github.com/nlohmann/json/tree/develop/tools/gdb_pretty_printer) under `tools/gdb_pretty_printer`, with its own usage instructions in that directory's `README.md`.
|
|
|
|
## Extended exception diagnostics
|
|
|
|
Defining [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) 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](https://json.nlohmann.me/features/parsing/parse_exceptions/index.md) for how parse errors report their own location instead.
|
|
|
|
## See also
|
|
|
|
- [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) - extended exception messages with the path of the failing value
|
|
- [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) - record byte positions of values for error messages
|
|
- [Exceptions](https://json.nlohmann.me/home/exceptions/index.md) - all exceptions and their error codes
|
|
- [`exception`](https://json.nlohmann.me/api/basic_json/exception/index.md) - base class of all exceptions thrown by the library
|