diff --git a/.lldbinit b/.lldbinit new file mode 100644 index 000000000000..65d3f26fab99 --- /dev/null +++ b/.lldbinit @@ -0,0 +1,8 @@ +# Part of the Carbon Language project, under the Apache License v2.0 with LLVM +# Exceptions. See /LICENSE for license information. +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + +command script import external/+llvm_project+llvm-project/llvm/utils/lldbDataFormatters.py +command script import scripts/lldbinit.py +settings set escape-non-printables false +settings set target.max-string-summary-length 10000 diff --git a/.vscode/lldb_launch.json b/.vscode/lldb_launch.json index 821350165ba3..2ace4bacb0cc 100644 --- a/.vscode/lldb_launch.json +++ b/.vscode/lldb_launch.json @@ -13,6 +13,7 @@ "settings append target.source-map \".\" \"${workspaceFolder}\"", "settings append target.source-map \"/proc/self/cwd\" \"${workspaceFolder}\"", "settings set escape-non-printables false", + "settings set target.max-string-summary-length 10000", "env TEST_TARGET=//toolchain/testing:file_test", "env TEST_TMPDIR=/tmp" ] @@ -34,7 +35,8 @@ "command script import external/+llvm_project+llvm-project/llvm/utils/lldbDataFormatters.py", "settings append target.source-map \".\" \"${workspaceFolder}\"", "settings append target.source-map \"/proc/self/cwd\" \"${workspaceFolder}\"", - "settings set escape-non-printables false" + "settings set escape-non-printables false", + "settings set target.max-string-summary-length 10000" ] } ] diff --git a/docs/project/contribution_tools.md b/docs/project/contribution_tools.md index 1ee7e233c040..593980200f2f 100644 --- a/docs/project/contribution_tools.md +++ b/docs/project/contribution_tools.md @@ -30,6 +30,7 @@ contributions. - [Old LLVM versions](#old-llvm-versions) - [Asking for help](#asking-for-help) - [Troubleshooting debug issues](#troubleshooting-debug-issues) + - [Using LLDB from the command line](#using-lldb-from-the-command-line) - [Debugging with GDB instead of LLDB](#debugging-with-gdb-instead-of-lldb) - [Debugging other build modes](#debugging-other-build-modes) - [Debugging on MacOS](#debugging-on-macos) @@ -351,6 +352,24 @@ lldb bazel-bin/toolchain/carbon Any installed version of LLDB at least as recent as the installed Clang used for building should work. +### Using LLDB from the command line + +We include launch commands for running lldb in VSCode in +[`.vscode/lldb_launch.json`](/.vscode/lldb_launch.json). But it's also possible +to run lldb from the command line. + +When running the debugger, include the `--local-lldbinit` argument to use our +preset configuration options. This requires running from the repository root. + +To debug a single `file_test`, use the following command, pointing it to an +actual carbon test file. + +``` +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 +``` + ### Debugging with GDB instead of LLDB If you prefer using GDB, you may want to pass some extra flags to the build: diff --git a/scripts/lldbinit.py b/scripts/lldbinit.py new file mode 100644 index 000000000000..9880612d4a9b --- /dev/null +++ b/scripts/lldbinit.py @@ -0,0 +1,28 @@ +#!/usr/bin/env python3 + +"""Initialization for lldb.""" + +__copyright__ = """ +Part of the Carbon Language project, under the Apache License v2.0 with LLVM +Exceptions. See /LICENSE for license information. +SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +""" + +# This script is only meant to be used from LLDB. +import lldb # type: ignore +import os + +project_root = os.path.dirname(os.path.realpath(__file__)) + +ci = lldb.debugger.GetCommandInterpreter() +result = lldb.SBCommandReturnObject() + + +def RunCommand(cmd: str) -> None: + """Runs a command and prints it to the console to show that it ran.""" + print("(lldb) %s" % cmd) + ci.HandleCommand(cmd, result) + + +RunCommand(f"settings append target.source-map . {project_root}") +RunCommand(f"settings append target.source-map /proc/self/cwd {project_root}")