Merge pull request #9436 from swiftlang/jdevlieghere/lldb-dap-cherrypicks

🍒 `lldb-dap` cherrypicks

Author: JDevlieghere

lldb/docs/resources/lldbdap.md

@@ -1,16 +1,95 @@
-# LLDB-DAP
-
-The `lldb-dap` tool (formerly `lldb-vscode`) is a command line tool that
-implements the [Debug Adapter
-Protocol](https://microsoft.github.io/debug-adapter-protocol/). It can be
-installed as an extension for Visual Studio Code and other IDEs supporting DAP.
-The protocol is easy to run remotely and also can allow other tools and IDEs to
-get a full featured debugger with a well defined protocol.
-
-## Local Installation for Visual Studio Code
+# Contributing to LLDB-DAP
+
+This guide describes how to extend and contribute to lldb-dap.
+For documentation on how to use lldb-dap, see [lldb-dap's README](https://github.com/llvm/llvm-project/blob/main/lldb/tools/lldb-dap/README.md).
+
+lldb-dap and LLDB are developed under the umbrella of the
+[LLVM project](https://llvm.org/). As such, the
+"[Getting Started with the LLVM System](https://llvm.org/docs/GettingStarted.html)",
+"[Contributing to LLVM](https://llvm.org/docs/Contributing.html)" and
+"[LLVM coding standard](https://llvm.org/docs/CodingStandards.html)"
+guides might also be relevant, if you are a first-time contributor to the LLVM
+project.
+
+lldb-dap's source code is [part of the LLVM
+repository](https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap)
+on Github. We use Github's [issue
+tracker](https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap)
+and patches can be submitted via [pull
+requests](https://github.com/llvm/llvm-project/pulls).
+
+## Building `lldb-dap` from soruce
+
+To build lldb-dap from source, first need to [setup a LLDB build](https://lldb.llvm.org/resources/build.html).
+After doing so, run `ninja lldb-dap`. To use your freshly built `lldb-dap`
+binary, install the VS Code extension and point it to lldb-dap by setting the
+`lldb-dap.executable-path` setting.
+
+## Responsibilities of LLDB, lldb-dap and the Visual Studio Code Extension
+
+Under the hood, the UI-based debugging experience is fueled by three separate
+components:
+
+* LLDB provides general, IDE-indepedent debugging features, such as:
+  loading binaries / core dumps, interpreting debug info, setting breakpoints,
+  pretty-printing variables, etc. The `lldb` binary exposes this functionality
+  via a command line interface.
+* `lldb-dap` exposes LLDB's functionality via the
+  "[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)",
+  i.e. a protocol through which various IDEs (VS Code, Emacs, vim, neovim, ...)
+  can interact with a wide range of debuggers (`lldb-dap` and many others).
+* The VS Code extension exposes the lldb-dap binary within VS Code. It acts
+  as a thin wrapper around the lldb-dap binary, and adds VS-Code-specific UI
+  integration on top of lldb-dap, such as autocompletion for `launch.json`
+  configuration files.
+
+Since lldb-dap builds on top of LLDB, all of LLDB's extensibility mechanisms
+such as [Variable Pretty-Printing](https://lldb.llvm.org/use/variable.html),
+[Frame recognizers](https://lldb.llvm.org/use/python-reference.html#writing-lldb-frame-recognizers-in-python)
+and [Python Scripting](https://lldb.llvm.org/use/python.html) are available
+also in lldb-dap.
+
+When adding new functionality, you generally want to add it on the lowest
+applicable level. I.e., quite frequently you actually want to add functionality
+to LLDB's core in order to improve your debugging experience in VS Code.
+
+### The Debug Adapter Protocol
+
+The most relevant resources for the Debug Adapter Protocol are:
+* [The overview](https://microsoft.github.io/debug-adapter-protocol/overview)
+  which provides a high-level introduction,
+* the [human-readable specification](https://microsoft.github.io/debug-adapter-protocol/specification), and
+* the [JSON-schema specification](https://github.com/microsoft/debug-adapter-protocol/blob/main/debugAdapterProtocol.json).
+
+lldb-dap adds some additional non-standard extensions to the protocol. To take
+advantage of those extensions, IDE-specific support code is needed, usually
+inside the VS Code extension. When adding a new extension, please first look
+through the [issue tracker of the Debug Adapter
+Protocol](https://github.com/microsoft/debug-adapter-protocol/issues) to check
+if there already is a proposal serving your use case. If so, try to take
+inspiration from it. If not, consider opening an upstream issue.
+
+To avoid naming collisions with potential future extensions of the Debug
+Adapter protocol, all non-standard extensions should use the prefix
+`$__lldb_extension` in their JSON property names.
+
+### Debugging the Debug Adapter Protocol
+
+To debug the Debug Adapter Protocol, point the `LLDBDAP_LOG` environment
+variable to a file on your disk. lldb-dap will log all communication received
+from / sent to the IDE to the provided path. In the VS Code extension, you
+can also set the log path through the `lldb-dap.log-path` VS Code setting.
+
+## Building the VS Code extension from source
 
 Installing the plug-in is very straightforward and involves just a few steps.
 
+In most cases, installing the VS Code extension from the [VS Code
+Marketplace](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap)
+and pointing it to a locally built lldb-dap binary is sufficient. Building
+the VS Code extension from source is only necessary if the TypeScript code is
+changed.
+
 ### Pre-requisites
 
 - Install a modern version of node (e.g. `v20.0.0`).
@@ -33,10 +112,6 @@ And then you are ready!
 
 ### Updating the extension
 
-*Note: It's not necessary to update the extension if there has been changes
-to  `lldb-dap`. The extension needs to be updated only if the TypesScript code
-has changed.*
-
 Updating the extension is pretty much the same process as installing it from
 scratch. However, VS Code expects the version number of the upgraded extension
 to be greater than the previous one, otherwise the installation step might have

lldb/packages/Python/lldbsuite/test/lldbplatformutil.py

@@ -180,6 +180,22 @@ def findMainThreadCheckerDylib():
     return ""
 
 
+def findBacktraceRecordingDylib():
+    if not platformIsDarwin():
+        return ""
+
+    if getPlatform() in lldbplatform.translate(lldbplatform.darwin_embedded):
+        return "/Developer/usr/lib/libBacktraceRecording.dylib"
+
+    with os.popen("xcode-select -p") as output:
+        xcode_developer_path = output.read().strip()
+        mtc_dylib_path = "%s/usr/lib/libBacktraceRecording.dylib" % xcode_developer_path
+        if os.path.isfile(mtc_dylib_path):
+            return mtc_dylib_path
+
+    return ""
+
+
 class _PlatformContext(object):
     """Value object class which contains platform-specific options."""
 

lldb/packages/Python/lldbsuite/test/tools/lldb-dap/dap_server.py

@@ -691,6 +691,19 @@ def request_disassemble(
         for inst in instructions:
             self.disassembled_instructions[inst["address"]] = inst
 
+    def request_readMemory(self, memoryReference, offset, count):
+        args_dict = {
+            "memoryReference": memoryReference,
+            "offset": offset,
+            "count": count,
+        }
+        command_dict = {
+            "command": "readMemory",
+            "type": "request",
+            "arguments": args_dict,
+        }
+        return self.send_recv(command_dict)
+
     def request_evaluate(self, expression, frameIndex=0, threadId=None, context=None):
         stackFrame = self.get_stackFrame(frameIndex=frameIndex, threadId=threadId)
         if stackFrame is None:
@@ -707,6 +720,17 @@ def request_evaluate(self, expression, frameIndex=0, threadId=None, context=None
         }
         return self.send_recv(command_dict)
 
+    def request_exceptionInfo(self, threadId=None):
+        if threadId is None:
+            threadId = self.get_thread_id()
+        args_dict = {"threadId": threadId}
+        command_dict = {
+            "command": "exceptionInfo",
+            "type": "request",
+            "arguments": args_dict,
+        }
+        return self.send_recv(command_dict)
+
     def request_initialize(self, sourceInitFile):
         command_dict = {
             "command": "initialize",
@@ -754,6 +778,7 @@ def request_launch(
         runInTerminal=False,
         postRunCommands=None,
         enableAutoVariableSummaries=False,
+        displayExtendedBacktrace=False,
         enableSyntheticChildDebugging=False,
         commandEscapePrefix=None,
         customFrameFormat=None,
@@ -806,6 +831,7 @@ def request_launch(
 
         args_dict["enableAutoVariableSummaries"] = enableAutoVariableSummaries
         args_dict["enableSyntheticChildDebugging"] = enableSyntheticChildDebugging
+        args_dict["displayExtendedBacktrace"] = displayExtendedBacktrace
         args_dict["commandEscapePrefix"] = commandEscapePrefix
         command_dict = {"command": "launch", "type": "request", "arguments": args_dict}
         response = self.send_recv(command_dict)
@@ -816,17 +842,21 @@ def request_launch(
             self.wait_for_event(filter=["process", "initialized"])
         return response
 
-    def request_next(self, threadId):
+    def request_next(self, threadId, granularity="statement"):
         if self.exit_status is not None:
             raise ValueError("request_continue called after process exited")
-        args_dict = {"threadId": threadId}
+        args_dict = {"threadId": threadId, "granularity": granularity}
         command_dict = {"command": "next", "type": "request", "arguments": args_dict}
         return self.send_recv(command_dict)
 
-    def request_stepIn(self, threadId, targetId):
+    def request_stepIn(self, threadId, targetId, granularity="statement"):
         if self.exit_status is not None:
             raise ValueError("request_stepIn called after process exited")
-        args_dict = {"threadId": threadId, "targetId": targetId}
+        args_dict = {
+            "threadId": threadId,
+            "targetId": targetId,
+            "granularity": granularity,
+        }
         command_dict = {"command": "stepIn", "type": "request", "arguments": args_dict}
         return self.send_recv(command_dict)
 
@@ -976,7 +1006,7 @@ def request_compileUnits(self, moduleId):
         return response
 
     def request_completions(self, text, frameId=None):
-        args_dict = {"text": text, "column": len(text)}
+        args_dict = {"text": text, "column": len(text) + 1}
         if frameId:
             args_dict["frameId"] = frameId
         command_dict = {
@@ -1079,6 +1109,17 @@ def request_setVariable(self, containingVarRef, name, value, id=None):
         }
         return self.send_recv(command_dict)
 
+    def request_locations(self, locationReference):
+        args_dict = {
+            "locationReference": locationReference,
+        }
+        command_dict = {
+            "command": "locations",
+            "type": "request",
+            "arguments": args_dict,
+        }
+        return self.send_recv(command_dict)
+
     def request_testGetTargetBreakpoints(self):
         """A request packet used in the LLDB test suite to get all currently
         set breakpoint infos for all breakpoints currently set in the
@@ -1095,6 +1136,20 @@ def terminate(self):
         self.send.close()
         # self.recv.close()
 
+    def request_setInstructionBreakpoints(self, memory_reference=[]):
+        breakpoints = []
+        for i in memory_reference:
+            args_dict = {
+                "instructionReference": i,
+            }
+            breakpoints.append(args_dict)
+        args_dict = {"breakpoints": breakpoints}
+        command_dict = {
+            "command": "setInstructionBreakpoints",
+            "type": "request",
+            "arguments": args_dict,
+        }
+        return self.send_recv(command_dict)
 
 class DebugAdaptorServer(DebugCommunication):
     def __init__(

lldb/packages/Python/lldbsuite/test/tools/lldb-dap/lldbdap_testcase.py

@@ -81,7 +81,10 @@ def verify_breakpoint_hit(self, breakpoint_ids):
                 body = stopped_event["body"]
                 if "reason" not in body:
                     continue
-                if body["reason"] != "breakpoint":
+                if (
+                    body["reason"] != "breakpoint"
+                    and body["reason"] != "instruction breakpoint"
+                ):
                     continue
                 if "description" not in body:
                     continue
@@ -100,13 +103,14 @@ def verify_breakpoint_hit(self, breakpoint_ids):
                         return
         self.assertTrue(False, "breakpoint not hit")
 
-    def verify_stop_exception_info(self, expected_description):
+    def verify_stop_exception_info(self, expected_description, timeout=timeoutval):
         """Wait for the process we are debugging to stop, and verify the stop
         reason is 'exception' and that the description matches
         'expected_description'
         """
-        stopped_events = self.dap_server.wait_for_stopped()
+        stopped_events = self.dap_server.wait_for_stopped(timeout=timeout)
         for stopped_event in stopped_events:
+            print("stopped_event", stopped_event)
             if "body" in stopped_event:
                 body = stopped_event["body"]
                 if "reason" not in body:
@@ -177,6 +181,10 @@ def get_stackFrames(self, threadId=None, startFrame=None, levels=None, dump=Fals
         )
         return stackFrames
 
+    def get_exceptionInfo(self, threadId=None):
+        response = self.dap_server.request_exceptionInfo(threadId=threadId)
+        return self.get_dict_value(response, ["body"])
+
     def get_source_and_line(self, threadId=None, frameIndex=0):
         stackFrames = self.get_stackFrames(
             threadId=threadId, startFrame=frameIndex, levels=1
@@ -202,6 +210,11 @@ def collect_console(self, timeout_secs, pattern=None):
             "console", timeout_secs=timeout_secs, pattern=pattern
         )
 
+    def collect_stdout(self, timeout_secs, pattern=None):
+        return self.dap_server.collect_output(
+            "stdout", timeout_secs=timeout_secs, pattern=pattern
+        )
+
     def get_local_as_int(self, name, threadId=None):
         value = self.dap_server.get_local_variable_value(name, threadId=threadId)
         # 'value' may have the variable value and summary.
@@ -222,14 +235,18 @@ def set_global(self, name, value, id=None):
         """Set a top level global variable only."""
         return self.dap_server.request_setVariable(2, name, str(value), id=id)
 
-    def stepIn(self, threadId=None, targetId=None, waitForStop=True):
-        self.dap_server.request_stepIn(threadId=threadId, targetId=targetId)
+    def stepIn(
+        self, threadId=None, targetId=None, waitForStop=True, granularity="statement"
+    ):
+        self.dap_server.request_stepIn(
+            threadId=threadId, targetId=targetId, granularity=granularity
+        )
         if waitForStop:
             return self.dap_server.wait_for_stopped()
         return None
 
-    def stepOver(self, threadId=None, waitForStop=True):
-        self.dap_server.request_next(threadId=threadId)
+    def stepOver(self, threadId=None, waitForStop=True, granularity="statement"):
+        self.dap_server.request_next(threadId=threadId, granularity=granularity)
         if waitForStop:
             return self.dap_server.wait_for_stopped()
         return None
@@ -369,6 +386,7 @@ def launch(
         expectFailure=False,
         postRunCommands=None,
         enableAutoVariableSummaries=False,
+        displayExtendedBacktrace=False,
         enableSyntheticChildDebugging=False,
         commandEscapePrefix=None,
         customFrameFormat=None,
@@ -410,6 +428,7 @@ def cleanup():
             runInTerminal=runInTerminal,
             postRunCommands=postRunCommands,
             enableAutoVariableSummaries=enableAutoVariableSummaries,
+            displayExtendedBacktrace=displayExtendedBacktrace,
             enableSyntheticChildDebugging=enableSyntheticChildDebugging,
             commandEscapePrefix=commandEscapePrefix,
             customFrameFormat=customFrameFormat,
@@ -449,6 +468,7 @@ def build_and_launch(
         postRunCommands=None,
         lldbDAPEnv=None,
         enableAutoVariableSummaries=False,
+        displayExtendedBacktrace=False,
         enableSyntheticChildDebugging=False,
         commandEscapePrefix=None,
         customFrameFormat=None,
@@ -485,6 +505,7 @@ def build_and_launch(
             postRunCommands=postRunCommands,
             enableAutoVariableSummaries=enableAutoVariableSummaries,
             enableSyntheticChildDebugging=enableSyntheticChildDebugging,
+            displayExtendedBacktrace=displayExtendedBacktrace,
             commandEscapePrefix=commandEscapePrefix,
             customFrameFormat=customFrameFormat,
             customThreadFormat=customThreadFormat,