carbon-language/carbon-lang
1
0
Fork 0
mirror of https://github.com/carbon-language/carbon-lang.git synced 2026-10-06 09:44:55 +01:00
Code Issues Packages Projects Releases 10 Wiki Activity

Consolidate debugging documentation. (#6596)

Browse Source 
Co-authored-by: josh11b <15258583+josh11b@users.noreply.github.com>
Co-authored-by: Carbon Infra Bot <carbon-external-infra@google.com>
This commit is contained in:
Geoff Romer
2026-01-14 19:00:46 +00:00
committed by GitHub
co-authored by josh11b Carbon Infra Bot
parent 7f0f402f95
commit d8adcf93f5
3 changed files with 263 additions and 228 deletions
Download Patch File Download Diff File Expand all files Collapse all files
toolchain/docs/adding_features.md
+1 -57
View File
@@ -26,10 +26,6 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
- [SemIR dumps and ranges](#semir-dumps-and-ranges)
- [Example uses](#example-uses)
- [Debugging errors](#debugging-errors)
- [Verbose output](#verbose-output)
- [Stack traces](#stack-traces)
- [Dumping objects in interactive debuggers](#dumping-objects-in-interactive-debuggers)
- [Dumping prelude files](#dumping-prelude-files)
<!-- tocstop -->
@@ -602,56 +598,4 @@ output can help check that an error is correctly propagated in SemIR.
### Debugging errors
#### Verbose output
The `-v` flag can be passed to trace state, and should be specified before the
subcommand name: `carbon -v compile ...`. `CARBON_VLOG` is used to print output
in this mode. There is currently no control over the degree of verbosity.
To include VLOG output when debugging a file test, add an `ARGS: -v compile %s`
line to the file, such as:
```
// INCLUDE-FILE: toolchain/testing/testdata/min_prelude/convert.carbon
// ARGS: -v compile %s
// EXTRA-ARGS: --dump-sem-ir-ranges=if-present
```
This will also include the VLOG output when running the test in an interactive
debugger. Note that using `-v compile` with `autoupdate.py` will deeply mangle
your test file, so avoid doing that.
#### Stack traces
While the iterative processing pattern means function stack traces will have
minimal context for how the current function is reached, we use LLVM's
`PrettyStackTrace` to include details about the state stack. The state stack
will be above the function stack in crash output.
You can also use the `--sem-ir-crash-dump=path/to/file` flag to get a raw SemIR
dump in the event of a crash in the check phase. This can be particularly useful
for interpreting IDs you encounter during interactive debugging.
#### Dumping objects in interactive debuggers
We provide namespace-scoped `Dump` functions in several components, such as
[check/dump.cpp](/toolchain/check/dump.cpp). These `Dump` functions will print
contextual information about an object to stderr. The files contain details
regarding support.
Objects which inherit from `Printable` also have `Dump` member functions, but
these will lack contextual information.
IDs are dumped in hexadecimal, so it's often convenient to set your interactive
debugger to print integers in hexadecimal as well. In LLDB you can do this with
`type format add --format hex int`.
#### Dumping prelude files
By default, prelude files are excluded from dumps by
`--exclude-dump-file-prefix`. To enable dumps for specific files, add
`//@include-in-dumps`. This works for every phase after lex, but may be most
helpful to debug check and lower output. This can also be used to view
cross-file SemIR, such as imports from a prelude, by adding
`//@include-in-dumps` to the prelude file and looking at the SemIR of the
importing file.
See [Debugging tools and techniques](debugging.md).