Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README

commit 52bdb93c7ad446ad640ec5d9d355247fc7d1f59a
parent 925c4b5a9572c62ea56684c05ef7467ab90e58a5
Author: aabacchus <ben@bvnf.space>
Date:   Mon,  6 Jun 2022 00:40:24 +0100

add README documenting usage

AREADME.md | 59+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 59 insertions(+), 0 deletions(-)

diff --git a/README.md b/README.md @@ -0,0 +1,59 @@ +# uxndebug + +This is a suite of tools for use in debugging uxn programs. + +### uxndebug +This is a modified version of uxnasm which operates exactly the same way, but +also generates a debug info file when run. The format of this file is documented +in the `uxndebug(5)` manpage. + +### uxnsolve +This program finds and highlights the faulty opcode by parsing a debug info file. + +## Usage + +First, to compile uxndebug, run +``` +make +``` + +Then compile your program: +``` +./uxndebug test.tal test.rom +``` +This will generate a file `test.tal.debug` in addition to the rom. + +Suppose you now run `test.rom` with your emulator of choice, and some error occurs. +Hopefully your emulator gives you an error message and a byte offset of the address +at which the error was encountered. For example, `uxnemu` might say: +``` +Loaded test.rom +<wst> empty +<rst> empty +Halted: Working-stack underflow#0002, at 0x01b3 +Boot: Failed to start rom. +Boot: Failed to boot. +``` +In this case, the faulty opcode had a value of `#0002` and was at address `0x01b3`. +So to find out which word in your source file this corresponds to, run +``` +./uxnsolve test.tal.debug 01b3 +``` +The first argument is the path to the debug file. Don't move it or rename it, it depends +on being the same as the name of the source file but with `.debug` appended. + +The second argument is the byte address. Don't subtract the 0x0100 padding of the zero-page, +uxnsolve does that for you. + +That command will print the line number, along with the line and the specific opcode in a bold +red font. +The output might look like this: +``` +line 289: DUP #04 SFT ,print-nibble-hex JSR +``` +(in this example the red font has been removed). + + +Remember to regenerate the debug info after changing your source code, otherwise it won't make +sense. uxnsolve will print a big WARNING if it notices that your source file is newer than the +debug info.