Document and configure running lldb from the command line (#5324)

The docs explain that you must use `--local-lldbinit` in the command
line, and include an example of how to run a file_test under lldb from
the command line.

This PR includes `.lldbinit` file and `lldbinit.py` file which set up
our default options, copied from the VSCode launcher.

The instructions include settin the `max-string-summary-length`, and we
include this in the vscode launcher for lldb, as printing `Dump()`
output can easily get truncated otherwise when printing an InstBlockId.

.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

.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"
       ]
     }
   ]

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:

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}")