Niels Lohmann
533cbfee51
Since #5877, the checked-in nlohmann_json.natvis only covers namespaces with up to two ABI tags. The generator gets options to produce a file for other configurations: - --abi-tags TAGS adds the namespaces of one configuration (repeatable) - --all generates every combination of ABI tags - --list-tags prints the tags with the macros that enable them - --output FILE writes somewhere else than the repository root `make natvis NATVIS_ARGS="..."` passes the options through. The default output is unchanged. The options are documented in the generator's README, the debugging page, and FILES.md, and checked in CI. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
generate_natvis.py
Generate the Natvis debugger visualization file for namespace combinations with up to two ABI tags.
The checked-in nlohmann_json.natvis covers the default namespace (no ABI tags), every single ABI tag, and every pair
of ABI tags, with both versioned and unversioned namespace variants. Configurations that enable three or more ABI tags
are not covered by this reduced file; use --abi-tags or --all (see below) to generate a file for them.
The ABI tag list and the library version are parsed from
include/nlohmann/detail/abi_macros.hpp, so this script must be re-run (via
make natvis) whenever an NLOHMANN_JSON_ABI_TAG_* macro is added to that
file or the library version is bumped — otherwise the committed
nlohmann_json.natvis drifts from the header it visualizes, and
make check-amalgamation fails.
Usage
make natvis
make natvis sets up a virtual environment tools/generate_natvis/venv with the dependencies from
requirements.txt (Jinja2) and runs the script with it. Alternatively, install the requirements yourself and run:
./generate_natvis.py [--version X.Y.Z] [--abi-tags TAGS]... [--all] [--list-tags] [--output FILE] [repository_root/]
--version and the repository root both default to values
derived from this script's own location, so they only need to be given
explicitly when generating a Natvis file for a different checkout or a
version other than the one in abi_macros.hpp.
| Option | Description |
|---|---|
--list-tags |
Print every ABI tag (in namespace order) with the macro that enables it and the NLOHMANN_JSON_ABI_TAG_* identifier, then exit. |
--abi-tags TAGS |
Add the namespaces of one configuration, given as a comma-separated list of ABI tags (_diag,_dp,_vns; the leading underscore is optional, and the order does not matter). Can be repeated for several configurations. Unknown tags are an error. |
--all |
Generate the namespaces for every combination of ABI tags. The file size doubles with each tag (about 60 MB for 12 tags). Cannot be combined with --abi-tags. |
--output FILE |
Write the Natvis file to FILE instead of nlohmann_json.natvis in the repository root. |
Each configuration gets both the versioned (json_abi_diag_dp_vns_v3_12_0) and the unversioned (json_abi_diag_dp_vns,
used with NLOHMANN_JSON_NAMESPACE_NO_VERSION) namespace. The default namespaces (up to two ABI tags) are always
included, so a generated file can replace the checked-in one.
Generating a Natvis file for your configuration
-
Check out the release tag of the library version you use (the ABI tags and the version are read from the checkout).
-
Find the ABI tags of the macros you enable:
make natvis NATVIS_ARGS="--list-tags" -
Generate a Natvis file with them, for example for
JSON_DIAGNOSTICS,JSON_DIAGNOSTIC_POSITIONS, andJSON_VIEW_NO_SIMD:make natvis NATVIS_ARGS="--abi-tags _diag,_dp,_vns --output my_nlohmann_json.natvis" -
Use
my_nlohmann_json.natvisinstead of the shippednlohmann_json.natvis, for example by adding it to your Visual Studio project.
Passing --output keeps the checked-in nlohmann_json.natvis unchanged; without it, make check-amalgamation would
report the file as out of date.