diff --git a/Debugging-with-LLDB.md b/Debugging-with-LLDB.md index a07d039..196b307 100644 --- a/Debugging-with-LLDB.md +++ b/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). -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. +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". + * 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 \ No newline at end of file +Happy debugging!