PVB/lemur
PVB
/
lemur
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 36 Wiki Activity

Update Debugging with LLDB

Simon Gellis 2025-01-19 22:56:15 +00:00
parent be84b89b20
commit a58654e79c
1 changed files with 65 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
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
Happy debugging!