Emulicious-debugger READMEThe "emulicious-debugger" extension enables debugging with Emulicious in VS Code. This extension requires Emulicious (https://emulicious.net/). In Emulicious you need to have "Remote Debugging" enabled. This option can be found in Emulicious's Tools menu. For breakpoints to work you need a language extension for the language you are using. For usage instructions see Usage. Known issues are listed in Known Issues. If you encounter any other issues please inform about them so they can be fixed. If anything is unclear please also inform about that so the explainations can be improved. RequirementsThe "emulicious-debugger" extension requires Visual Studio Code (VS Code) and Emulicious (https://emulicious.net/). In Emulicious you need to have "Remote Debugging" enabled. This option can be found in Emulicious's Tools menu. For breakpoints to work you need a language extension for the language you are using. If you are using C you can for example use the C language extension that is built into VS Code. For other languages you should be able to find a corresponding language extension in VS Code's Extension Marketplace. For example if you are developing for the Game Boy (Color) with RGBDS you can find Donald Hays's RGBDS Z80 extension. UsageMake sure that Emulicious is running and that "Remote Debugging" (in Emulicious's Tools menu) is enabled. After that is set up, you have multiple ways to start debugging with Emulicious:
When building your program, make sure that debug symbols get generated. For example, when building C code with SDCC you should pass the commandline flag FeaturesThe "emulicious-debugger" extension enables source level debugging for assembler code and C code (SDCC). Source-level SteppingStep through your own ASM source code. Source BreakpointsBreak on breakpoints in your ASM source code. CallstackKeep an eye on your callstack. Investigate RegistersInvestigate registers annotated with symbols. Investigate StackframesInvestigate stackframes. Investigate System StateInvestigate system state. Inspection on HoverInspect symbols on hover. Debug ConsoleEvaluate expressions in debug console DisassembleDisassemble with Emulicious and step through the disassembly in VS Code. C-level SteppingStep through your C source code line by line, into procedures or out of them. C-level BreakpointsBreak on breakpoints in your C source code. C CallstackKeep an eye on your C callstack. C Local VariablesKeep track of your local variables. C Inspection of Structured TypeInspect your C arrays and structs via Watch expressions, on hover or via the debug console. Known IssuesTrying to start a debug session without Emulicious running or without Remote Debugging enabled yields an error message saying that the connection was refused. If you see this error make sure that you are running Emulicious and that Remote Debugging is enabled. EmuliciousEmulicious is a free to use multi-system emulator for Windows, Linux, Raspberry Pi OS, Mac OS(X) and any other operating system supporting Java SE. It is focused on reverse-engineering, ROM hacking and development. For that it provides several tools such as a debugger with a smart disassembler (splitting code from data). Emulicious emulates the Game Boy and Game Boy Color, the MSX1 and the Master System and the Game Gear. Release Notes1.0.4Added description of Emulicious (https://emulicious.net/) and added gamegear keyword 1.0.3Added some missing keywords and improved some screenshots 1.0.2README improvements 1.0.0Initial release of "emulicious-debugger" |