Author: aabacchus <firstname.lastname@example.org>
Date: Mon, 6 Jun 2022 00:40:24 +0100
add README documenting usage
|A||README.md|| | ||59||+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++|
1 file changed, 59 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -0,0 +1,59 @@
+This is a suite of tools for use in debugging uxn programs.
+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.
+This program finds and highlights the faulty opcode by parsing a debug info file.
+First, to compile uxndebug, run
+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:
+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
+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