# Debugging tools and techniques ## Table of contents - [Interactive debugger setup](#interactive-debugger-setup) - [Debugging with LLDB](#debugging-with-lldb) - [MacOS](#macos) - [VS Code integration](#vs-code-integration) - [Debugging with GDB](#debugging-with-gdb) - [VS Code integration](#vs-code-integration-1) - [Toolchain-specific debugging techniques](#toolchain-specific-debugging-techniques) - [Dumping objects in interactive debuggers](#dumping-objects-in-interactive-debuggers) - [The LLDB `dump` command](#the-lldb-dump-command) - [Verbose output](#verbose-output) - [Stack traces](#stack-traces) - [Dumping prelude files](#dumping-prelude-files) ## Interactive debugger setup The toolchain codebase should work with either GDB or LLDB, but using GDB requires a little more setup and may not have quite as many conveniences. Pass `-c dbg` to `bazel build` in order to compile with debugging enabled. For example: ```shell bazel build -c dbg //toolchain ``` This produces a compiled binary with debug symbols at `bazel-bin/toolchain/carbon`. For the best debugging experience you may want to pass additional flags when building and/or running the debugger, but the specifics depend on your environment; see the following sections for details. If you have an issue that only reproduces with another build mode, you can still enable debug information in that mode by passing `--feature=debug_info_flags` to Bazel. ### Debugging with LLDB The output of a `-c dbg` build should be usable with any version of LLDB as recent as the installed Clang used for building: ```shell lldb bazel-bin/toolchain/carbon ``` However, we recommend running LLDB with the `--local-lldbinit` flag, to enable our preset configuration (which enables the [`dump` command](#the-lldb-dump-command) among other features). This requires running from the repository root: ```shell lldb --local-lldbinit bazel-bin/toolchain/carbon ``` To debug a single `file_test`, use the following command, pointing it to an actual carbon test file. ```shell bazel build -c dbg //toolchain/testing:file_test && \ lldb --local-lldbinit bazel-bin/toolchain/testing/file_test -- \ --dump_output --file_tests /path/to/some/test.carbon ``` #### MacOS Bazel sandboxes builds, which on MacOS makes it hard for the debugger to locate symbols on linked binaries when debugging. See this [Bazel issue](https://github.com/bazelbuild/bazel/issues/2537#issuecomment-449089673) for more information. To workaround, provide the `--spawn_strategy=local` option to Bazel for the debug build, like: ```shell bazel build --spawn_strategy=local -c dbg //toolchain ``` You should then be able to debug with `lldb`. If this build command doesn't seem to produce a debuggable binary you might need to both clear the build disk cache and clean the build. Running `scripts/clean_disk_cache.sh` may not be enough, you might try deleting all the files within the disk cache, typically located at `~/.cache/carbon-lang-build-cache`. Deleting the disk cache, followed by a `bazel clean` should allow your next rebuild, with the recommended options, to supply the symbols for debugging. #### VS Code integration VS Code's integrated debugger support can be configured to use LLDB, with custom support for debugging the toolchain tests. To set that up: 1. In the `.vscode` subdirectory, symlink `lldb_launch.json` to `launch.json`. For example: `ln -s lldb_launch.json .vscode/launch.json` 2. Install the [`llvm-vs-code-extensions.lldb-dap` extension](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap). 3. In VS Code settings, it may be necessary to set `lldb-dap.executable-path` to the path of `lldb-dap`. A typical debug session looks like: 1. `bazel build -c dbg //toolchain/testing:file_test` 2. Open a `.carbon` testdata file to debug. This must be the active file in VS Code. 3. Go to the "Run and debug" panel in VS Code. 4. Select and run the `file_test (lldb)` configuration. For debugging on MacOS using VSCode, some people have had success using the CodeLLDB extension. In order for LLDB to connect the project source files with the symbols you will need to add a `"sourceMap": { ".": "${workspaceRoot}" }` line to the CodeLLDB `launch.json` configuration, for example: ```json { "version": "0.2.0", "configurations": [ { "name": "explorer", "type": "lldb", "request": "launch", "program": "${workspaceRoot}/bazel-bin/explorer/explorer", "args": [], "cwd": "${workspaceRoot}", "sourceMap": { ".": "${workspaceRoot}" } } ] } ``` ### Debugging with GDB If you prefer using GDB, you may want to pass some extra flags to the build: ```shell bazel build -c dbg --features=-lldb_flags --features=gdb_flags //toolchain ``` Or you can add them to your `user.bazelrc`, they are designed to be safe to pass at all times and only have effect when building with `-c dbg`: ```shell echo "build --features=-lldb_flags --features=gdb_flags" >> user.bazelrc ``` Note that on Linux we use Split DWARF and DWARF v5 debug symbols, which means that GDB version 10.1 or newer is required. If you see an error like this: ```shell Dwarf Error: DW_FORM_strx1 found in non-DWO CU ``` It means that the version of GDB used is too old, and does not support the DWARF v5 format. #### VS Code integration VS Code's integrated debugger support can be configured to use GDB, with custom support for debugging the toolchain tests. To set that up: 1. In the `.vscode` subdirectory, symlink `gdb_launch.json` to `launch.json`. For example: `ln -s gdb_launch.json .vscode/launch.json` 2. Install the [`coolchyni.beyond-debug` extension](https://marketplace.visualstudio.com/items?itemName=coolchyni.beyond-debug). A typical debug session looks like: 1. `bazel build -c dbg --features=-lldb_flags --features=gdb_flags //toolchain/testing:file_test` 2. Open a `.carbon` testdata file to debug. This must be the active file in VS Code. 3. Go to the "Run and debug" panel in VS Code. 4. Select and run the `file_test (gdb)` configuration. ## Toolchain-specific debugging techniques ### 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`. #### The LLDB `dump` command Our LLDB configuration includes a `dump` command (see [above](#debugging-with-lldb) for how to enable that configuration), which allows you to dump the contents of a value associated with an id. Since most data in the toolchain is referenced by id, this ends up being a very frequent task. The debugger command `dump ` gets roughly translated into a C++ call to `Dump(, )`. Run the `dump` command without any arguments to see the builtin help on how to use it. ### 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 prelude files By default, prelude files are excluded from SemIR 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.