[kaffe] CVS kaffe (guilhem): Debug faq update.

Mon Apr 18 10:01:40 PDT 2005

PatchSet 5690 
Date: 2005/04/18 16:57:11
Author: guilhem
Branch: HEAD
Tag: (none) 
Log:
Debug faq update.

2005-04-18  Michael Franz  <mvfranz at gmail.com>

        * FAQ/FAQ.debugging: Added new informations on how to debug kaffe
        easily.

Members: 
	ChangeLog:1.3856->1.3857 
	FAQ/FAQ.debugging:INITIAL->1.6 

Index: kaffe/ChangeLog
diff -u kaffe/ChangeLog:1.3856 kaffe/ChangeLog:1.3857

--- kaffe/ChangeLog:1.3856	Mon Apr 18 16:47:09 2005
+++ kaffe/ChangeLog	Mon Apr 18 16:57:11 2005
@@ -1,3 +1,8 @@
+2005-04-18  Michael Franz  <mvfranz at gmail.com>
+	
+	* FAQ/FAQ.debugging: Added new informations on how to debug kaffe
+	easily.
+
 2005-04-18  Dalibor Topic  <robilad at kaffe.org>
 
 	Resynced with GNU Classpath.
===================================================================
Checking out kaffe/FAQ/FAQ.debugging
RCS:  /home/cvs/kaffe/kaffe/FAQ/FAQ.debugging,v
VERS: 1.6
***************
--- /dev/null	Sun Aug  4 19:57:58 2002
+++ kaffe/FAQ/FAQ.debugging	Mon Apr 18 17:01:40 2005
@@ -0,0 +1,176 @@
+Debugging Kaffe
+---------------
+
+This document provides some pointers for debugging the Kaffe VM. (Not
+necessarily for debugging Java apps running on Kaffe, though you can
+abuse these techniques to that end.)
+
+building Kaffe for debugging
+============================
+
+There are a few things to consider when building Kaffe to make your 
+debugging experience enjoyable.  There are debugging macros within 
+Kaffe that will print out predefined messages, you control which 
+messages you are interested in by using -vmdebug (see below).  If
+you are planning on using GDB (either alone or with some GUI) you
+will want to disable GCC optimizations.  The optimizations that 
+GCC perform may change the execution order of some instructions 
+and make your debugging session very frustrating!  You will not 
+know which like will execute next and your executing line will 
+jump around.  The easiest way disable GCC optimizations when 
+building Kaffe is to edit the config.frag for your system 
+(config/<CPU>/<OS>/config.frag).  Add the -O0 flag to CFLAGS, 
+this tells GCC to use zero (0) optimizations. 
+        CFLAGS="$CFLAGS -O0"
+
+The other thing that you will want to do is to use
+static linking when building Kaffe.  There are issue with some 
+dynamic loaders and GDB may not be able to find your source files
+when you step into a function that is defined in another directory
+or library.  When configuring Kaffe you can pass the static flags
+     ./configure --with-staticlib --with-staticbin --with-staticvm
+
+       
+-vmdebug
+========
+
+Configure Kaffe with the '--enable-debug' option. This turns on a
+bunch of debugging infrastructure in Kaffe. Most of the
+infrastructure is for tracing, but there are some sanity checks that
+can be turned on (e.g., 'GCDIAG'), and other flags and settings (e.g.,
+'NOGC').
+
+Run kaffe with '-vmdebug list' to get a list of supported VM debugging
+options. Pass the options you're interested in as a comma-separated
+list of names. For example, you can use it like so:
+        kaffe -vmdebug INIT,VMTHREAD,GCSYSALLOC foo
+
+This will print some stats about initialization, VM-level threading
+events, and system-level memory allocations. Note that some of the
+options are very, very verbose (e.g., 'GCALLOC' or 'ALL'.)
+
+If you want to add more run-time tracing code, look at
+kaffe/kaffevm/debug.h. Grep for the DBG() macros to see how they're
+used.
+
+gdb
+===
+
+Kaffe is started by a script that determines the BOOTCLASSPATH, 
+CLASSPATH and LD_LIBRARY_PATH that is needed for Kaffe to run.
+Since the Kaffe executable is not started directly by you, trying
+'dbg kaffe' will not work.  You will need to tell the startup script
+which debugger you want to use.  This is as easy as setting the 
+environment variable KAFFE_DEBUG to your debugger of choice.
+Currently Kaffe can be debugged use: gdb, ddd, emacs and cgdb.
+        KAFFE_DEBUG=gdb
+Once you are done debugging or nolonger want Kaffe to start up 
+within a debugger you can simply unset KAFFE_DEBUG.        
+
+There are some gdb macros in developers/gdbinit that are useful for
+looking at Kaffe's GC, thread, and object structures (in particular,
+look for 'pobject', 'livethreadsbt'). Some of the macros are out of
+sync wrt to the actual structures, so you may have to update
+them. Comments in the file should explain how to use them.
+
+Also, look at FAQ.xdebugging for a mechanism for including Java
+symbols in backtraces in GDB. If you're going to debug Kaffe on a
+regular basis, you should always include the xdebugging support.
+
+
+Internal Tests
+==============
+
+Internal tests are kept in the test/internal directory and are used to
+do very basic checking of the VM.  If you are doing a port, you will
+want to start here since the tests are less demanding than the full
+regression tests.  In general, the tests are written in C, link
+directly to the VM libraries, check results internally, and exit when
+they first encounter a problem.
+
+Currently, there is only one test, jitBasic, which does basic testing
+of the jitter.  For example, the tests range from simple checking of
+functions returning constants to creating objects and accessing their
+fields.  These tests are ideal for those doing a port of the jitter,
+and were in fact used to assist the development of the PowerPC port.
+Note that the test relies on Java classes, Jikes is required to do the
+compilation, we do not currently distribute precompiled versions.
+
+jitBasic environment variables:
+
+	TEST_CLASSES - The classes to test against.
+
+To run it manually, you need to do something like the following 
+in sh/bash:
+
+  . ../../BUILD_ENVIRONMENT
+  export BOOTCLASSPATH=${BOOTCLASSPATH}:.
+  export TEST_CLASSES="ConstMethods.class"
+  ./jitBasic
+
+It "should" complain if it has any problems and it should print out 
+a bunch of debugging info as it jits the methods.  If its completely 
+silent, something is probably wrong.
+
+Regression Tests
+================
+
+Regression tests are kept in test/regression/.  Regression tests are
+just simple stand-alone .java programs. They have special comments at
+the end that influence how the tester treats their output.  Generally,
+the "correct" output is included in the comment, and the test script
+simply compares the output generated.  
+
+To add a new test, just add it to the list of tests in Makefile.am,
+regenerate the Makefile.in, re-configure, and run 'make check'.  (Ugh,
+the need to re-generate Makefile.in is awkward and lame.)
+
+To run a single test (or a subset of tests) set the TEST variable,
+like so:
+	cd test/regression
+	make check TESTS="ThreadInterrupt.java IndexTest.java"
+
+Note, you can test new tests without doing the whole Makefile.am thing
+by just including the test in the test/regression directory and then
+setting the TESTS environment variable to that test.  For example:
+
+	$ vi test/regression/OneOffHackTest.java
+	$ make check TESTS="OneOffHackTest.java"
+
+
+Special Comments in Regression Tests
+====================================
+
+Regression tests have special comments that tell the test driver
+script what to do with them. The special comments and their
+effects are:
+
+// Sources: SOURCES
+compile also these sources with current test case.
+
+// javac flags: FLAGS
+add some javac flags.  For exemple -nowarn remove warning lines
+and therefore don't let's think that javac fail.
+
+// Skip Run
+Compile only
+
+// java args: CLASSNAME [OPTIONS]
+Replace current classname by this classname and options.
+
+All lines enclose inside line
+/* Expected Output:
+and
+*/
+are compared to test-case's output.
+
+// Sort Output
+Sort output before compare it to Expected Output.
+
+Other Stuff
+===========
+
+Debugging Performance: Look at FAQ.timing and FAQ.xprofiling for
+details on getting performance information out of the VM.
+
+


