deploy: 533cbfee51

home/debugging.md

@@ -11,7 +11,27 @@ file that gives `json`/`ordered_json` values a friendly, key/value debugger view
 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.
+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.
+2. List the ABI tags and the macros that enable them:
+
+    ```shell
+    make natvis NATVIS_ARGS="--list-tags"
+    ```
+
+3. Generate a Natvis file with the tags of your configuration, for example for `JSON_DIAGNOSTICS`,
+    `JSON_DIAGNOSTIC_POSITIONS`, and `JSON_VIEW_NO_SIMD`:
+
+    ```shell
+    make natvis NATVIS_ARGS="--abi-tags _diag,_dp,_vns --output my_nlohmann_json.natvis"
+    ```
+
+4. 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`](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