From be84b89b2006a85700161cfd6a2b2174e284a6e0 Mon Sep 17 00:00:00 2001 From: SonicSwordcane Date: Sun, 19 Jan 2025 06:52:36 +0000 Subject: [PATCH] Add Debugging with LLDB --- Debugging-with-LLDB.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 Debugging-with-LLDB.md diff --git a/Debugging-with-LLDB.md b/Debugging-with-LLDB.md new file mode 100644 index 0000000..a07d039 --- /dev/null +++ b/Debugging-with-LLDB.md @@ -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 \ No newline at end of file