This commit was generated by cvs2svn to compensate for changes in r2,

which included commits to RCS files with non-trunk default branches.


git-svn-id: svn://svn.cc65.org/cc65/trunk@3 b7a2c559-68d2-44c3-8de9-860c34a00d81

doc/debugging.txt

@@ -0,0 +1,151 @@
+
+
+		      Debugging your code using VICE
+
+		     Ullrich von Bassewitz, March 1999
+
+
+Contents
+--------
+
+  1. Overview
+
+  2. What is VICE?
+
+  3. How to prepare your sources
+
+  4. How to use the label file
+
+  5. Problems and workarounds
+
+
+
+1. Overview
+-----------
+
+This document describes how to debug your programs using the cc65
+development tools and the VICE CBM emulator.
+
+
+
+2. What is VICE?
+----------------
+
+VICE is an emulator for many of the CBM machines. It runs on Unix, DOS and
+Windows 95. It emulates the Commodore 64, 128, VIC20, PET and the 600/700
+machines. For more information see the VICE home page:
+
+	http://www.cs.cmu.edu/~dsladic/vice/vice.html
+
+VICE has a builtin machine language monitor that may be used for debugging
+your programs. Using an emulator for debugging has some advantages:
+
+  - Since you're using a crossassembler/-compiler anyway, you don't need
+    to transfer the program to the real machine until it is done.
+
+  - An emulator allows many things that are almost impossible one of the
+    original machines. You may set watchpoints (detect read or write
+    access to arbitary addresses), debug interrupt handlers and even debug
+    routines that run inside the 1541 floppy.
+
+  - You may use the label file generated by the linker to make much more
+    use from the monitor.
+
+Please note that you need at least VICE version 0.16 for the label file
+feature to work. This version has still some problems (see section 5 for
+descriptions and some workarounds), but older versions had even more
+problems and do NOT work correctly.
+
+
+
+3. How to prepare your programs
+-------------------------------
+
+VICE support is mostly done via a label file that is generated by the
+linker and that may be read by the VICE monitor, so it knows about your
+program. Source level debugging is *not* available, you have to debug your
+programs in the assembler view.
+
+The first step is to generate object files that contain information about
+ALL labels in your sources, not just the exported ones. This can be done
+by several means:
+
+  - Use the -g switch on the assembler command line.
+
+  - Use the
+
+      .debuginfo +
+
+    command in your source.
+
+  - Use the -g switch when invoking the compiler. The compiler will then
+    put the .debuginfo command into the generated assembler source.
+
+So, if you have just C code, all you need is to invoke the compiler with
+-g. If you're using assembler code, you have to use -g for the assembler,
+or add ".debuginfo +" to your source files. Since the generated debug info
+is not appended to the generated executables, it is a good idea to always
+use -g. It makes the object files and libraries slightly larger (~30%),
+but this is usually not a problem.
+
+The second step is to tell the linker that it should generate a VICE label
+file. This is done by the -L switch followed by the name of the label file
+(I'm usually using a .lbl extension for these files). An example for a
+linker command line would be:
+
+    ld65 -t c64 -L hello.lbl -m hello.map -o hello crt0 hello.o c64.lib
+
+This will generate a file named hello.lbl that contains all symbols used
+in your program.
+
+Note: The runtime libraries and startup files were generated with debug
+info, so you don't have to care about this.
+
+
+
+4. How to use the label file
+----------------------------
+
+Load your program, then enter the monitor and use the "pb" command to load
+your label file like this:
+
+	pb "hello.lbl"
+
+You will get lots of warnings and even a few errors. You may ignore safely
+all these warnings and errors as long as they reference any problems VICE
+thinks it has with the labels.
+
+After loading the labels, they are used by VICE in the disassembler
+listing, and you may use them whereever you need to specify an address.
+Try
+
+	d ._main
+
+as an example (note that VICE needs a leading dot before all labels, and
+that the compiler prepends an underline under most named labels).
+
+
+
+5. Problems and workarounds
+---------------------------
+
+Unfortunately, the VICE monitor has several problems with labels. However,
+it is still tremendously useful, and I think that most problems are gone
+in the next version. So, here is a list of the problems known to me as of
+version 0.16.1:
+
+  * The "ll" command does not work. Worse, it seems that internal memory
+    gets corrupted when using this command, so VICE will crash after use.
+    Be sure to use the "pb" command to load the label file.
+
+  * VICE will crash if you use a label that is undefined. This is probably
+    the worst problem of all, since it needs just one typo to kill VICE.
+    So, watch your steps:-)
+
+  * Cheap labels, that is, labels starting with '@' or '?' are not
+    accepted.
+
+  * The disassembly output is somewhat suboptimal. However, most things are
+    just cosmetical, e.g. labels appended to the right side of the
+    disassembled code.
+