Update Debugging with LLDB

Debugging-with-LLDB.md

@@ -6,8 +6,13 @@ Lemur can be used as a server for the gdb/lldb debuggers. If you're a homebrew d
 
 To debug Virtual Boy games, you need a version of gdb or lldb built to target the Virtual Boy. The llvm-v810 compiler comes with a working version of lldb. At this time, there is no compatible version of gdb, so just use lldb.
 
-1. Download the latest [llvm-v810 compiler](https://github.com/SupernaviX/v810-llvm/releases) for your OS (Windows, Darwin/Mac, or Linux).
+1. Download the latest [llvm-v810 compiler](https://github.com/SupernaviX/v810-llvm/releases) for your OS (Windows, Darwin/Mac, or Linux). The download link is under "Assets".
-2. On closer inspection, lldb isn't getting bundled in there. Gotta fix that. Sorry whoever's reading this, either compile llvm yourself or give me a few days to fix it.
+    * For Windows, download `llvm-v810-windows-main.7z` from the assets of a release with "Windows" in the name.
+    * For Mac, download `llvm-v810-darwin-main.tar.xz` from the assets of a release with "Darwin" in the name.
+    * For Linux, download `llvm-v810-linux-main.tar.xz` from the assets of a release with "Linux" in the name.
+2. Extract the files.
+    * For command-line debugging, you'll need the lldb executable from `llvm-v810/bin/lldb` (or `llvm-v810/bin/lldb.exe` on Windows).
+    * For IDE integration, you'll need the lldb-dap executable from `llvm-v810/bin/lldb-dap` (or `llvm-v810/bin/lldb-dap.exe` on Windows).
 
 ## Compiling with debug info
 
@@ -38,5 +43,62 @@ lldb -o "process connect connect://127.0.0.1:8080"
 At this point you can debug your game like any program. See [this lldb tutorial](https://lldb.llvm.org/use/tutorial.html) for some examples of what you can do.
 
 ## VSCode integration with lldb-dap
+If your IDE has a debugger, lldb-dap lets you use it to debug your Virtual Boy game. The below instructions are for VSCode, but this will work for almost any IDE (except VUEngine Studio).
+1. Download the [LLDB DAP](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap) extension.
+2. Configure the extension to use the lldb-dap you downloaded earlier. Add this to your `.vscode/settings.json`:
+```json
+{
+    "lldb-dap.executable-path": "/path/to/llvm-v810/bin/lldb-dap"
+}
+```
+3. Add a launch configuration to your project. Add this to `.vscode/launch.json`:
+```json
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug",
+            "type": "lldb-dap",
+            "request": "launch",
+            "program": "${workspaceFolder}/mygame.elf", // path to your .elf file
+            "launchCommands": ["gdb-remote 8080"], // replace 8080 with whichever port your server uses
+            "preLaunchTask": "Emulate" // see step 4
+        }
+    ]
+}
+```
+4. When you click the "Debug" button, you probably want to launch the emulator with your game. Set up a task to do this. Add this to `.vscode/tasks.json`:
+```json
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Emulate",
+            "type": "shell",
+            "command": "/path/to/lemur",
+            "args": [
+                "${workspaceFolder}/mygame.vb", // path to your rom
+                "--debug-port",
+                "8080"
+            ],
+            "isBackground": true,
+            "problemMatcher": {
+                "pattern": {
+                    "regexp": ""
+                },
+                "background": {
+                    "activeOnStart": true,
+                    "beginsPattern": "Connecting",
+                    "endsPattern": "Connecting"
+                }
+            }
+        }
+    ]
+}
+```
+If you're feeling spicy, you can add a "Compile" task which this "Emulate" task depends on, so that clicking "Debug" is all you need to do to start debugging.
 
-TODO: write this up tomorrow it's like 2am
+Happy debugging!