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

Add Debugging with LLDB

Simon Gellis 2025-01-19 06:52:36 +00:00
parent 7c4c3d9d48
commit be84b89b20
1 changed files with 42 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
Debugging-with-LLDB.md Normal file

@ -0,0 +1,42 @@
# Debugging with LLDB
Lemur can be used as a server for the gdb/lldb debuggers. If you're a homebrew developer, this gives you a rich source-level debugging experience for your C, C++, Rust, or assembly games. If you're reverse-engineering commercial games, it does a passable job at debugging ROMs without source code.
## Setting up LLDB
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.
## Compiling with debug info
To use source-level debugging, you must compile debug info into your game. To do this, simply add `-g` to your `CFLAGS`.
The `-g` flag is supported in
* [v810-gcc](https://github.com/jbrandwood/v810-gcc) v4.9.4
* [v810-llvm](https://github.com/SupernaviX/v810-llvm/releases)
Note that VUEngine Studio uses an older version of v810-gcc, so source-level debugging doesn't work for VUEngine games. This will be fixed Eventually™️.
This debug info will be added to your game's `.elf` file, but stripped from the final `.vb` file. This means compiling with `-g` won't make your ROM bigger or slower.
## Running the server
To run the server, you can go to "Tools > GDB Server" and click Start. It will run on port 8080 by default. You can also pass `--debug-port 8080` on the command line, to run the server as soon as the app starts. Your game will be paused until the debugger connects.
## Command-line debugging with lldb
You can use lldb as a command-line tool. To do this, pass your game's `.elf` file to lldb, and tell it to connect to Lemur on startup:
```sh
lldb /path/to/your/game.elf -o "process connect connect://127.0.0.1:8080"
```
You can also run lldb without an `.elf` file, but it'll be missing a lot of features (like variable inspection and call stack visualization) if you do.
```sh
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
TODO: write this up tomorrow it's like 2am