|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312 |
- <refentry>
- <refnamediv>
- <refname>ajdb</refname>
- <refpurpose>debugger for .class files produced by ajc (early-access)</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>ajdb</command>
- <arg>-classpath <replaceable>path</replaceable></arg>
- <arg>-D<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
- <arg>-help</arg>
- <arg>-gui</arg>
- <arg>-read <replaceable>file</replaceable></arg>
- <arg>-sourcepath <replaceable>dir</replaceable></arg>
- <arg>
- <group>
- <arg>-v</arg>
- <arg>-verbose</arg>
- <group>
- <arg>:class</arg>
- <arg>:gc</arg>
- <arg>:jni</arg>
- </group>
- </group>
- </arg>
- <arg>workingdir <replaceable>dir</replaceable></arg>
- <arg>-X<replaceable>option</replaceable></arg>
- <arg><replaceable>class</replaceable></arg>
- <arg><replaceable>arguments</replaceable>
- </arg>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
-
- <para>The command <command>ajdb</command> is used to debug AspectJ and
- Java programs. In addition to its command line interface,
- <command>adjb</command> also has a standalone, Swing-based GUI
- interface.
- </para>
- <para>
- Note: As of the 1.0.3 release, AspectJ supports JSR-45, which provides
- source-level debugging from many source files per class
- and non-Java source files.
- JSR-45 is implemented in the J2SE 1.4 debugger support, so
- you may be able to use your existing debugger to step through
- AspectJ source code if both the source and target VM's are
- running under Java 1.4 or later.
- However, existing debuggers will display synthetic methods
- in the stack frame.
- </para> <!-- todo find docs on JSR-45 -->
-
- <simplelist>
- <member>-classpath <emphasis>path</emphasis></member>
- <member>Specify where to find user class files.</member>
-
- <member>
- -D<replaceable>name</replaceable>=<replaceable>value</replaceable>
- </member>
- <member>Define the property <literal>name</literal> to have the value
- <literal>value</literal>.</member>
-
- <member>-help</member>
- <member>Print out <command>ajdb</command>'s usage summary.</member>
-
- <member>-read <emphasis>file</emphasis></member>
- <member>Read this file for initializatoin commands.</member>
-
- <member>-sourcepath <emphasis>path</emphasis></member>
- <member>Search this directory for source files.</member>
-
- <member>-gui</member>
- <member></member>
-
- <member>-v | -verbose [:class | :gc | :jni]</member>
- <member>Print out class loading, garbage collection or dynamic library
- loading information. Defaults to class loading.
- </member>
-
- <member>-workingdir <emphasis>directory</emphasis></member>
- <member>Set <command>ajdb</command>'s working directory.</member>
-
- <member>-X<emphasis>option</emphasis></member>
- <member>Pass a non-standard option to the VM</member>
- </simplelist>
-
- <refsect2>
- <title>Capabilities</title>
- <para>
- The AspectJ debugger implements all of <command>jdb</command>'s
- commands. In addition, the command <literal>workingdir</literal>
- allow you to set the AspectJ working directory, and the breakpoint
- command, <literal>stop on</literal>, has been extended to allow the
- setting of breakpoint on a source file line.
- </para>
- </refsect2>
-
- <refsect2>
- <title>Examples</title>
-
- <example id="ajdbcommandline">
- <title>Command line use</title>
-
- <para>Suppose you want to debug the file spacewar/Ship.java found in
- the examples directory. At the command line start up the debugger:
-
- <computeroutput>
- ajdb
- </computeroutput>
- </para>
-
-
- <para>
- The debugger will first look for initialization files in your
- home or current directory called either
- <filename>ajdb.ini</filename> or <filename>.ajdbrc</filename> and
- execute the commands contained in them. A useful command to have
- in this file is the <literal>source-path</literal> command which
- tells the debugger where to find source files.
- </para>
-
- <para>For this example, we need to set the source path by:
-
- <userinput>
- use C:\src
- </userinput>
- </para>
-
- <para>To view the file to debug, type <userinput>list
- spacewar/Ship.java</userinput> which generates the following
- output:
- <programlisting>
- 209 void fire() {
- 210 // firing a shot takes energy
- 211 if (!expendEnergy(BULLET_ENERGY))
- 212 return;
- 213
- 214 //create a bullet object so it doesn't hit the ship that's firing it
- 215 double xV = getXVel() + BULLET_SPEED * (Math.cos(orientation));
- 216 double yV = getYVel() + BULLET_SPEED * (Math.sin(orientation));
- 217
- 218 // create the actual bullet
- 219 new Bullet(
- 220 getGame(),
- 221 (getXPos() + ((getSize()/2 + 2) * (Math.cos(orientation))) + xV),
- 222 (getYPos() + ((getSize()/2 + 2) * (Math.sin(orientation))) + yV),
- 223 xV,
- 224 yV);
- 225 }
- </programlisting>
- </para>
- <para>This is different from <command>jdb</command> because it allows
- one to view files before the debugger has started. The
- <literal>list</literal> command has the following syntax: </para>
-
- <simplelist>
- <member><literal>list</literal></member>
- <member>list the source containing the location at which we are
- currently stopped (can only be used with a running VM)</member>
-
- <member><literal>list</literal>
- <emphasis><literal>source</literal></emphasis></member>
- <member>list the entire file source</member>
-
- <member><literal>list</literal> source line</member>
- <member>list source line line of file source</member>
-
- <member>
- list <emphasis><literal>source start-line
- end-line</literal></emphasis>
- </member>
- <member>
- list the lines from <emphasis>start-line</emphasis> to
- <emphasis>end-line</emphasis> of file
- <emphasis>source</emphasis>
- </member>
- </simplelist>
-
- <para>
- To set a breakpoint in the method <literal>Ship.fire</literal>, we
- would could type <userinput>stop in spacewar.Ship.fire</userinput>.
- </para>
-
- <para>The following message appears notifying the user that the
- breakpoint has been noted but will not be set until the class has
- been loaded by the VM: </para>
- <programlisting>
- Deferring breakpoint spacewar.Ship.fire()
- It will be set after the class is loaded.
- </programlisting>
-
- <para>
- To start Spacewar we type <userinput>run spacewar.Game</userinput>.
- </para>
-
- <para>
- When the breakpoint is set, the following message appears:
- <programlisting>
- Set deferred breakpoint spacewar.Ship.fire()
- </programlisting>
- </para>
-
- <para> We are notified that we've hit the breakpoint:
-
- <programlisting>
- Breakpoint hit: thread="Thread-2", spacewar.Ship.fire(), line=174, bci=0 209 void fire() {
- </programlisting></para>
-
- <para>
- The prompt changes to present the thread that has broken, and we
- can view the current stack with the <literal>where</literal>
- command, as follows:
- <programlisting>
- Thread-2[1] where
- [1] fire (spacewar\Ship.java:209)
- [2] run (spacewar\Robot.java:100)
- [3] run [class java.lang.Thread]
- </programlisting>
- </para>
-
- <para>
- Next, to stop on line 216 we
- type <userinput>stop on spacewar/Ship.java:216</userinput>
- </para>
-
- <para>
- The following message tells us the breakpoint was set:
- <programlisting>
- Set breakpoint Ship.java:216
- </programlisting>
- </para>
- <para>
- To continue execution, we type <userinput>cont</userinput> and the
- breakpoint at line 216 is hit
- <programlisting>
- Breakpoint hit: thread="Thread-2", spacewar.Ship.fire(), line=216, bci=28
- 216 double yV = getYVel() + BULLET_SPEED * (Math.sin(orientation));
- </programlisting></para>
-
- <para>
- To view the visible local variables, we type
- <userinput>locals</userinput> and ajdb responds with:
- <programlisting>
- Local variables
- xV = 12.242462584304468
- </programlisting></para>
-
- <para>
- To change the value of the local variable i to 15, we type
- <userinput>set xV = 16.1</userinput>
-
- <programlisting>
- Changed 'xV' from '12.242462584304468' to '16.1'
- </programlisting></para>
-
- <para>
- To see our changes we can print the value of <literal>i</literal>
- by the following:
- <programlisting>
- print xV
- Value for printing 'xV' = 12.242462584304468
- </programlisting></para>
-
- <para>We can now type exit or quit to leave the debugger, and we
- receive the following message:
-
- <programlisting>
- The application has exited.
- </programlisting></para>
- </example>
-
- </refsect2>
-
- <refsect2>
- <title>The AspectJ debugger API</title>
-
- <para>
- The AspectJ debugger is implemented completely in Java and can be
- called as a Java class. The only interface that should be
- considered public is the method
- <literal>org.aspectj.tools.debugger.Main.main(String[]
- args)</literal> where <literal>args</literal> are the standard
- <command>ajc</command> command line arguments. This means that an
- alternative way to run the compiler is </para>
-
- <cmdsynopsis>
- <command>
- <literal>java org.aspectj.tools.debugger.Main</literal>
- </command>
- <arg><replaceable>option</replaceable></arg>
- <arg><replaceable>class</replaceable></arg>
- <arg><replaceable>arguments</replaceable></arg>
- </cmdsynopsis>
-
- <!-- <note> -->
- <para>
- You must additionally include <filename>tools.jar</filename> from
- your Java developer's kit in your classpath.
- </para>
- <!-- </note> -->
-
- </refsect2>
- </refsect1>
- </refentry>
-
- <!-- Local variables: -->
- <!-- fill-column: 79 -->
- <!-- sgml-local-ecat-files: devguide.ced -->
- <!-- sgml-parent-document:("devguide.sgml" "book" "refentry") -->
- <!-- End: -->
|