From 9287c825ebdce4d91e4509a8269736697c07669f Mon Sep 17 00:00:00 2001 From: Joshua Peterson Date: Sat, 23 Jul 2022 11:53:03 -0400 Subject: [PATCH] Add debugging troubleshooting for GDB (#1613) Older versions of GDB (before version 10.1) don't work with the DWARF v5 debugging format the LLVM uses. The error message which GDB shows when this happens is a bit misleading though. Provide documentation about how to deal with that error message. --- docs/project/contribution_tools.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/project/contribution_tools.md b/docs/project/contribution_tools.md index fa62c71e6d99..6cf577e22ad3 100644 --- a/docs/project/contribution_tools.md +++ b/docs/project/contribution_tools.md @@ -23,6 +23,7 @@ contributions. - [Clang and LLVM](#clang-and-llvm) - [Manual installations (not recommended)](#manual-installations-not-recommended) - [Troubleshooting build issues](#troubleshooting-build-issues) + - [Troubleshooting debug issues](#troubleshooting-debug-issues) - [pre-commit](#pre-commit) - [Optional tools](#optional-tools) - [Carbon-maintained](#carbon-maintained) @@ -198,6 +199,31 @@ These commands will help diagnose potential build issues because they'll expose what's occurring with [clang detection](/bazel/cc_toolchains/clang_configuration.bzl). +#### Troubleshooting debug issues + +Use the `--compilation_mode=dbg` argument to `bazel build` in order to compile +with debugging enabled. For example: + +```shell +bazel build --compilation_mode=dbg //explorer +``` + +Then debugging works with GDB: + +```shell +gdb bazel-bin/explorer/explorer +``` + +Note that LLVM uses 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. + ### pre-commit We use [pre-commit](https://pre-commit.com) to run