diff options
| author | wisberg <wisberg> | 2002-12-16 17:58:19 +0000 |
|---|---|---|
| committer | wisberg <wisberg> | 2002-12-16 17:58:19 +0000 |
| commit | d842c4f1139629c1f062b74ba818d233b2c31043 (patch) | |
| tree | 842d3871620bc0eb60edcd95e55804d67e0f61fa /docs/devGuideDB | |
| parent | 3ce247199704eae6b2c92c6e38c69584e3250c52 (diff) | |
| download | aspectj-d842c4f1139629c1f062b74ba818d233b2c31043.tar.gz aspectj-d842c4f1139629c1f062b74ba818d233b2c31043.zip | |
initial version
Diffstat (limited to 'docs/devGuideDB')
21 files changed, 2552 insertions, 0 deletions
diff --git a/docs/devGuideDB/ajbrowser-building.gif b/docs/devGuideDB/ajbrowser-building.gif Binary files differnew file mode 100644 index 000000000..29767c605 --- /dev/null +++ b/docs/devGuideDB/ajbrowser-building.gif diff --git a/docs/devGuideDB/ajbrowser-options.gif b/docs/devGuideDB/ajbrowser-options.gif Binary files differnew file mode 100644 index 000000000..41ba67654 --- /dev/null +++ b/docs/devGuideDB/ajbrowser-options.gif diff --git a/docs/devGuideDB/ajbrowser.xml b/docs/devGuideDB/ajbrowser.xml new file mode 100644 index 000000000..f4a44597c --- /dev/null +++ b/docs/devGuideDB/ajbrowser.xml @@ -0,0 +1,222 @@ +<refentry> + <refnamediv> + <refname>AspectJ Browser</refname> + + <refpurpose>GUI tool for compiling programs with ajc and navigating the + crosscutting structure (early-access)</refpurpose> + + </refnamediv> + + <refsect1 id="ajbrowser" xreflabel="AspectJ Browser"> + <title>Overview</title> + + + <para> + The AspectJ Browser is a development tool that will allow you to + compile using ajc, navigate your program's static structure, edit + source files, and graphically edit build configuration files. + </para> + + <imageobject> + <imagedata fileref="ajbrowser-building.gif"/> + </imageobject> + + <para> + To use the browser launch it by typing "ajbrowser" (assuming that + you've followed the instructions for setting up <xref + linkend="ajc">ajc</xref>). You can either pass in one or more + ".lst" build configuration files as command line parameters to the + browser in order to build them and navigate the corresponding + structure, or you can open one or more ".lst" files with "File -> + Open" or with the "Open Build Configuration" button + (<inlinemediaobject> + <imageobject> + <imagedata fileref="openConfig.gif"/> + </imageobject> + </inlinemediaobject>). + </para> + </refsect1> + + <refsect1> + <title>Compiling a Build Configuration</title> + + <para> + To compile click the "Build" button + (<inlinemediaobject> + <imageobject> + <imagedata fileref="build.gif"/> + </imageobject> + </inlinemediaobject>), or click <ctrl>F11. You may also select a + different build configuration here, as in label 1. + </para> + </refsect1> + + <refsect1> + <title>Navigating the Program Structure</title> + + <para> + Select nodes in the program structure by clicking them (as in label 2). + If one node is related to one or more other nodes by an association the + name of the association will appear below that node and will be + displayed in italics. Links to other structure nodes appear in blue + below the association. If there is no corresponding source for the + link it will appear light-blue. + </para> + + </refsect1> + + <refsect1> + <title>Manipulating Build Configuration</title> + + <para> + Build configurations can be manipulated adding, removing, and + editing build configuration files using the corresponding toolbar + buttons. The current configuration can be selected in the + configurations listbox. Build configurations are represented by + ".lst" files (which are described in the <xref + linkend="ajc">ajc</xref> documentation). + </para> + </refsect1> + + <refsect1> + <title>Example: Exploring the "Spacewar" sample code </title> + <para> + <itemizedlist> + + <listitem> <para>Launch <literal>ajbrowser</literal></para> + </listitem> + + <listitem> Choose "File -> Open" or click the "Open Build + Configuration" button + (<inlinemediaobject> + <imageobject> + <imagedata fileref="openConfig.gif"/> + </imageobject> + </inlinemediaobject>) and select the configuration file for debugging + the spacewar example, in + <literal>examples/spacewar/debug.lst</literal>. + </listitem> + + <listitem> <para>Click the "Build" button (<inlinemediaobject> + <imageobject> + <imagedata fileref="build.gif"/> + </imageobject> + </inlinemediaobject>) to + compile. The left pane should fill with a spacewar declaration + tree. If there is a compiler error, the clickable error message + shows up as in label 4. + </para> + + <para>Note: If you did not install in the default location, the + compile will fail with a message that you need to install + aspectjrt.jar on your compile classpath. To do that, select "Tools + -> Options" or click the "Options" button + (<inlinemediaobject> + <imageobject> + <imagedata fileref="browseroptions.gif"/> + </imageobject> + </inlinemediaobject>). Click the <literal>Build Options</literal> tab + to view the Build Paths pane. Edit the classpath entry to use your + install location, ok the dialog, and retry the compile. + + </para> + + <imageobject> + <imagedata fileref="ajbrowser-options.gif"/> + </imageobject> + + </listitem> + + <listitem> <para>Different structure views: The structure tree at the + left can display different orderings and granularity for structure: + + <itemizedlist> + <listitem> The package hierarchy view shows the traditional hierarchy + of package, class, and members. </listitem> + + <listitem> The inheritance view shows the hierarchy from topmost + parent classes through subclasses to members. </listitem> + + <listitem> The crosscutting view shows the aspect members + and the code they affect. </listitem> + + <listitem> Additional buttons in the pane can be used to change the + granularity and filter out items. + </listitem> + + </itemizedlist> + + </para> + + <para>Whenever you select an item in the tree view, the + source pane scrolls to that item. If you select a leaf item + representing another program element, then the tree + selection will go to the corresponding node. (See below for + how to use two panes to maintain your place.) + </para> + + </listitem> + <listitem> + + <para>When working with aspects, it helps to be able to navigate + between different program elements: + </para> + + <itemizedlist> + + <listitem><para>When looking at a method, find the advice that + affects it. </para></listitem> + + <listitem><para>When looking at a pointcut, find the advice that + uses it. </para></listitem> + + <listitem><para>When looking at advice, find what it advises - + e.g., method calls or executions, initializers, etc. + </para></listitem> + + <listitem><para>When looking at a type, find any aspects that + declare members or supertypes of the type, or + vice-versa. + </para></listitem> + + </itemizedlist> + + <para>You can view the advice on a particular method using the + default, hierarchical view. Navigate to the tree item for + <literal>spacewar.Registry.register(SpaceObject)</literal> + in the <literal>debug.lst</literal> config file. Now, in + the lower, file view, you can see and navigate to the advice + using the subtree whose parent is the <literal>method + affected by</literal> relation. + </para> + + <para>You can also use crosscutting view to see the + advice using a pointcut or the methods affected by advice. + For example, to see what advice uses a particular pointcut, + navigate to the tree item for the pointcut + <literal>spacewar.Debug.allConstructorsCut()</literal> in + the <literal>debug.lst</literal> config file. You can see + and navigate to the advice that uses the pointcut using the + <literal>pointcut used by</literal> relation. + </para> + + <para>As an example of seeing the methods affected by advice, + while still in the same view, select the first + <literal>before</literal> advice in + <literal>spacewar.Debug</literal>. It has relation + sub-trees for both <literal>uses pointcut</literal> and + <literal>affects constructions</literal>. The + <literal>affects</literal> relations will list different + kinds of join points - constructor or method calls, etc. + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> +</refentry> + +<!-- Local variables: --> +<!-- fill-column: 79 --> +<!-- sgml-local-ecat-files: devguide.ced --> +<!-- sgml-parent-document:("devguide.sgml" "book" "refentry") --> +<!-- End: --> diff --git a/docs/devGuideDB/ajc.xml b/docs/devGuideDB/ajc.xml new file mode 100644 index 000000000..28347b90b --- /dev/null +++ b/docs/devGuideDB/ajc.xml @@ -0,0 +1,484 @@ +<refentry> + <refnamediv> + <refname>ajc</refname> + <refpurpose>compiler for the AspectJ language </refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>ajc</command> + <arg><replaceable>Options</replaceable></arg> + <group> + <arg><replaceable>file...</replaceable></arg> + <arg>@<replaceable>file...</replaceable></arg> + <arg>-argfile <replaceable>file...</replaceable></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1 id="ajc" xreflabel="ajc"> + <title>Description</title> + + <para>The command <command>ajc</command> compiles AspectJ and Java + language source files into class files. Options and files may be + specified directly on the command line, or indirectly by naming a + file which contains them.</para> + + <para> The arguments after the options specify the file(s) to compile. + Files may be listed directly on the command line, or listed in a file. + The <parameter>@<replaceable>file</replaceable></parameter> and + <parameter>-argfile <replaceable>file</replaceable></parameter> forms + are equivalent, and are interpreted as meaning all the files listed in + the specified file. Each line in these files should contain one option + or filename. Comments, as in Java, start with <literal>//</literal> and + extend to the end of the line. + </para> + + <para> + <command>NB:</command> You must explicitly pass ajc all of the source files necessary + for the compilation. When you are compiling source files containing aspects + or pointcuts, be sure + to include the source files for any types affected by the aspects or + picked out by the pointcuts. + (If you wish to exclude types from the scope affected by the + aspect, change the corresponding pointcut or declaration.) + This is necessary because, unlike javac, ajc does not search the sourcepath for classes. + </para> + + <refsect2> + <title>Options</title> + + <variablelist> + + <varlistentry> + <term>-verbose</term> + <listitem><para> + Output messages about what ajc is doing + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-version</term> + <listitem><para> + Print the version of ajc + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-nocomments</term> + <listitem><para> + Don't generate any comments into the woven code. + Only relevant with -preprocess mode. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-emacssym</term> + <listitem><para> + Generate symbols used by AJDE for Emacs + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-usejavac</term> + <listitem><para> + Use javac to generate .class files + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-preprocess</term> + <listitem><para> + Don't try to generate any .class files. + Generate regular Java code into <replaceable>workingdir</replaceable> + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-workingdir <replaceable>Directory</replaceable></term> + <listitem><para> + Specify where to place intermediate .java files + <replaceable>Directory</replaceable> defaults to ./ajworkingdir. + Only relevant with -usejavac or -preprocess modes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term></term> + <listitem><para> + </para></listitem> + </varlistentry> + + <varlistentry> + <term></term> + <listitem><para> + + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-O</term> + <listitem><para> + Optimize; may hinder debugging or enlarge class files + </para></listitem> + </varlistentry> + + <!-- We don't actually warn about deprecated methods ever + <varlistentry> + <term>-deprecation</term> + <listitem><para> + Output source locations where deprecated APIs are used + </para></listitem> + </varlistentry> + --> + + <varlistentry> + <term>-d <replaceable>Directory</replaceable></term> + <listitem><para> + Specify where to place generated .class files + <replaceable>Directory</replaceable> defaults to the current working dir + </para></listitem> + </varlistentry> + + <varlistentry> + <term></term> + <listitem><para> + + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-classpath <replaceable>Path</replaceable></term> + <listitem><para> + Specify where to find user class files + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-bootclasspath <replaceable>Path</replaceable></term> + <listitem><para> + Override location of bootstrap class files + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-extdirs <replaceable>Path</replaceable></term> + <listitem><para> + Override location of installed extensions + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-argfile <replaceable>File</replaceable></term> + <listitem><para> + the file is a line-delimited list of arguments + these arguments are inserted into the argument list + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-encoding <replaceable>Encoding</replaceable></term> + <listitem><para> + Specify character encoding used by source files + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-source <replaceable>1.4</replaceable></term> + <listitem><para> + Specify support for assertions according to the 1.4 Java language. + This will treat <literal>assert</literal> as a keyword and will + implement assertions according to the 1.4 language spec. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-lenient</term> + <listitem><para> + Be extra-lenient in interpreting the java specification + This allows some statements that some compilers consider errors. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-strict</term> + <listitem><para> + Be extra-strict in interpreting the java specification + This signals errors for some statements that many compilers don't + catch, and generates code strictly according to the Java Language + Specification, even though such code may not run on 1.2 VMs. + </para></listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2> <title>File names</title> + + <para>ajc accepts source files with either the <filename>.java</filename> + extension or the <filename>.aj</filename> extension. We normally use + <filename>.java</filename> for all of our files in an AspectJ system -- files + that contain aspects as well as files that contain classes. However, if + you have a need to mechanically distinguish files that use AspectJ's + additional functionality from those that are pure Java we recommend using + the <filename>.aj</filename> extension for those files.</para> + + <para>We'd like to discourage other means of mechanical distinction such as + naming conventions or sub-packages in favor of the <filename>.aj</filename> + extension.</para> + + <itemizedlist> + + <listitem>Filename conventions are hard to enforce and lead to awkward names + for your aspects. Instead of <filename>TracingAspect.java</filename> we + recommend using <filename>Tracing.aj</filename> (or just + <filename>Tracing.java</filename>) instead.</listitem> + + <listitem>Sub-packages move aspects out of their natural place in a system + and can create an artificial need for privileged aspects. Instead of + adding a sub-package like <filename>aspects</filename> we recommend using the + <filename>.aj</filename> extension and including these files in your existing + packages instead.</listitem> + + </itemizedlist> + + </refsect2> + + <refsect2> + <title>Compatibility</title> + + <para> + AspectJ is a compatible extension to the Java programming language. The + AspectJ compiler adheres to the <ulink + url="http://java.sun.com/docs/books/jls/index.html"> <citetitle + pubwork="book">The Java Language Specfication, Second + Edition</citetitle></ulink> and to the <ulink + url="http://java.sun.com/docs/books/vmspec/index.html"><citetitle + pubwork="book">The Java Virtual Machine Specification, Second + Edition</citetitle></ulink> and runs on any Java 2 compatible + platform. The code it generates runs on any Java 1.1 or later + compatible platform.</para> + + </refsect2> + + <refsect2> + <title>Examples</title> + + <example id="simpleexample"> + <title>A simple example</title> + + <para>Compile two files:</para> + + <programlisting> + ajc HelloWorld.java Trace.java + </programlisting> + + </example> + + <example id="exampleusingargfile"> + <title>An example using -argfile/@</title> + + <para> + To avoid specifying file names on the command line, + list source files in a line-delimited text argfile. + Source file paths may be absolute or relative to the argfile, + and may include other argfiles by @-reference. + The following file <literal>sources.lst</literal> + contains absolute and relative files and @-references: + <para><programlisting> +Gui.java +/home/user/src/Library.java +data/Repository.java +data/Access.java +@../../common/common.lst +@/home/user/src/lib.lst +view/body/ArrayView.java</programlisting></para> + + Compile the files using either the -argfile or @ form: + + <para><programlisting> +ajc -argfile sources.lst +ajc @sources.lst</programlisting></para> + </para> + <para> + Argfiles are also supported by jikes, javac, and ajdoc, so you + can use the files in hybrid builds. However, the support varies: + </para> + + <simplelist> + <listitem>Only ajc accepts command-line options</listitem> + <listitem>Jikes and Javac do not accept internal @argfile references. + </listitem> + <listitem>Jikes and Javac only accept the @file form on the command line.</listitem> + </simplelist> + + </example> + + <!-- these examples suck + <example id="mixingoptionsandfiles"> + <title>Mixing directly and indirectly specified options and + files</title> + + <para>Invoke the AspectJ compiler with the options <literal>-threads + 2</literal>, <literal>-deprecation</literal>, + <literal>-verbose</literal> and the options listed in the file + <filename>standard_ajc_options</filename> on the files listed in + <filename>prog_src_files</filename>. </para> + + <programlisting> + ajc -threads 2 -deprecation @standard_ajc_options -argfile prog_src_files -verbose + </programlisting> + + </example> + + <example id="optionsnotinajc"> + + <title>Compiling with options not directly supported by + <command>ajc</command></title> + + <para>Run the AspectJ compiler on the file + <filename>figures/FigureElement.java</filename> but do not generate + <filename>.class</filename> (bytecode) files. Keep the generated + Java source files and place them in the directory + <filename>tmp</filename>.</para> + +<programlisting> + ajc -preprocess -workingdir tmp figures/FigureElement.java +</programlisting> + + <para>You may then compile those files with:</para> + + <programlisting> + cd tmp + javac -g figures/FigureElement.java + </programlisting> + + </example> + + <example id="usingjikes"> + <title>Using <command>jikes</command></title> + + <para>Invoke the AspectJ compiler on the file + <filename>figures/FigureElement.java</filename>, saving the + generated Java files in the directory + <filename>ajworkingdir</filename>. Then invoke the Jikes compiler + on the generated Java files.</para> + + <programlisting> + JIKESPATH=$JAVA_HOME/jre/lib/rt.jar:$CLASSPATH + ajc -preprocess figures/FigureElement.java + cd ajworkingdir + jikes figures/FigureElement.java + </programlisting> + + <para>Since <command>jikes</command> cannot infer the location of the + standard class files the way <command>javac</command> can, you must + tell it explicitly how to find the system and user class files it + needs. You may either use the <literal>-classpath</literal> option to + both <command>ajc</command> and to <command>jikes</command>, or you + may define the enviroment variables <envar>CLASSPATH</envar> and + <envar>JIKESPATH</envar> appropriately.</para> + + </example> + --> + + </refsect2> + + <refsect2> + <title>The AspectJ compiler API</title> + + <para>The AspectJ compiler 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.ajc.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.ajc.Main</literal></command> + <arg><replaceable>option...</replaceable></arg> + <arg><replaceable>file...</replaceable></arg> + </cmdsynopsis> + +<!-- <note> --> + <para> + To run in <literal>-usejavac</literal> mode, + you must include in your classpath the + <filename>tools.jar</filename> from your Java 2 developer's kit. + </para> +<!-- </note> --> + </refsect2> + + <refsect2> + <title>Stack Traces and the SourceFile attribute</title> + + <para>Unlike traditional java compilers, the AspectJ compiler may in + certain cases generate classfiles from multiple source files. + Unfortunately, the Java class file format does not support multiple + SourceFile attributes. So, in order to make sure all source file + information is available, the AspectJ compiler may in some cases + encode multiple filenames in the SourceFile attribute. + </para> + + <para>Probably the only time you may see this format is when you view + stack traces, where you may encounter traces of the format + </para> + +<programlisting> +java.lang.NullPointerException + at Main.new$constructor_call37(Main.java;SynchAspect.java[1k]:1030) +</programlisting> + + <para>where instead of the usual + </para> + +<programlisting> +File:LineNumber +</programlisting> + + <para>format, you see + </para> + +<programlisting> +File0;File1[Number1];File2[Number2] ... :LineNumber +</programlisting> + + <para>In this case, LineNumber is the usual offset in lines plus the + "start line" of the actual source file. That means you use LineNumber + both to identify the source file and to find the line at issue. + The number in [brackets] after each file tells you the + virtual "start line" for that file (the first file has a start of 0). + </para> + + <para> In our example from the null pointer exception trace, + the virtual start line is 1030. Since the file SynchAspect.java + "starts" at line 1000 [1k], the LineNumber points to line 30 of + SynchAspect.java. + </para> + + <para> So, when faced with such stack traces, the way to find the actual + source location is to look through the list of "start line" numbers to + find the one just under the shown line number. That is the file where + the source location can actually be found. Then, subtract that "start + line" from the shown line number to find the actual line number within + that file. + </para> + + <para>Of course, AspectJ tools will do this decoding for you, and in a + class file that comes from only a single source file, the AspectJ + compiler generates SourceFile attributes consistent with + traditional Java compilers. + </para> + + </refsect2> + + + </refsect1> +</refentry> + +<!-- Local variables: --> +<!-- fill-column: 79 --> +<!-- sgml-local-ecat-files: devguide.ced --> +<!-- sgml-parent-document:("devguide.sgml" "book" "refentry") --> +<!-- End: --> diff --git a/docs/devGuideDB/ajdb.xml b/docs/devGuideDB/ajdb.xml new file mode 100644 index 000000000..832002823 --- /dev/null +++ b/docs/devGuideDB/ajdb.xml @@ -0,0 +1,312 @@ +<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: --> diff --git a/docs/devGuideDB/ajdee.gif b/docs/devGuideDB/ajdee.gif Binary files differnew file mode 100644 index 000000000..e50832d0a --- /dev/null +++ b/docs/devGuideDB/ajdee.gif diff --git a/docs/devGuideDB/ajdee.xml b/docs/devGuideDB/ajdee.xml new file mode 100644 index 000000000..7c42a90fd --- /dev/null +++ b/docs/devGuideDB/ajdee.xml @@ -0,0 +1,452 @@ +<refentry id="ajdee"> + <refnamediv> + <refname>AJDEE</refname> + <refpurpose>JDEE support for XEmacs and GNU Emacs </refpurpose> + </refnamediv> + + <refsect1> + <title>AJDE for Emacs User's Guide</title> + <para> + This guide describes AspectJ-mode extensions of JDEE for GNU Emacs and + XEmacs, which + provides enhanced editing and management of AspectJ code via a minor + mode extension of JDE mode. AJDEE's AspectJ support builds on + <link linkend="aspectj-mode">aspectj-mode's</link> extension of + java-mode, also provided with the release. + Included in this document are guidance for AJDEE's <link + linkend="ajdee-featuresandusage">use</link>, including an <link + linkend="exploringspacewar">exploration of spacewar</link>, and <link + linkend="ajdee-installationetc">installation and compatibility</link>. See + the README file in AJDEE's distribution directory for + release-specific details. + </para> + + <para> + In addition to the java-mode extensions provided by + <link linkend="aspectj-mode">aspectj-mode</link>, AJDEE provides + (see graphic): + <itemizedlist> + <listitem> + <para> + Viewing and navigation of aspect structures via the + the speedbar and Classes menu. + </para> + </listitem> + + <listitem> + <para> + Basic support for completion. + </para> + </listitem> + + <listitem> + <para> + Integrated Javadoc support. + </para> + </listitem> + + </itemizedlist> + </para> + + <para> + <inlinemediaobject id="ajdeemacsscreenshot"> + <imageobject> + <imagedata fileref="ajdee.gif"/> + </imageobject> + </inlinemediaobject> + </para> + </refsect1> + + <refsect1 id="ajdee-featuresandusage"><!-- Features and Usage --> + <title>AJDEE Features and Usage</title> + <para> + The AJDEE extensions of JDE require no special effort to use. + The speedbar and Classes menus provide additional sublists showing + crosscutting structure. Selecting items in those lists navigates to + the referenced item. + </para> + + <refsect2> + <title>Aspect Structure and Navigation</title> + + <refsect3> + <title>Enhancements to Speedbar in JDE Mode</title> + <para> + As a minor mode of JDE mode, AJDEE enhances the speedbar to + show the location of aspect, advice, and inter-type declarations. + The affects/affected-by relationships are shown in the speedbar + rather than embedding tags in the text (available as an option), + and selecting the items in the speedbar will perform the expected + navigation. The speedbar symbols have been extended for AspectJ as + follows (see right side of <link + linkend="ajdeemacsscreenshot">figure)</link>: + </para> + + <table id="speedbarenhancements"> + <title>Enhancements to Speedbar in JDE Mode</title> + <tgroup cols="2" colsep="1" rowsep="1" align="left"> + <thead> + <row> + <entry>Indication</entry> + <entry>Meaning</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <literal>(+) </literal> + <emphasis><literal>name</literal></emphasis> + </entry> + <entry> + A class, interface, or aspect; double mouse-1 will + display its declarations + </entry> + </row> + + <row> + <entry><literal>+ </literal> + <emphasis><literal>methodSignature</literal></emphasis> + </entry> + <entry> + Method has an advice that applies to it; double mouse-1 + will display the relevant advice. + </entry> + </row> + + <row> + <entry><literal>+ </literal> + <emphasis><literal>adviceSignature</literal></emphasis> + </entry> + <entry> + Advice declared by the containing aspect; double mouse-1 + will display affected methods. + </entry> + </row> + + <row> + <entry><literal>+ </literal> + <emphasis><literal>introductionSig</literal></emphasis> + </entry> + <entry> + Inter-type declaration declared by the containing class; double + mouse-1 will display affected methods or classes. + </entry> + </row> + + <row> + <entry><literal>| | </literal> + <emphasis><literal>methodOrFieldSig</literal></emphasis> + </entry> + <entry> + Method or field has been declared by an aspect; + double mouse-1 on text will navigate to the declaration; a + + within the bars means that it has an advice that applies + to it. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + A minus (<literal>-</literal>) is displayed on the item when the + crosscutting items are displayed. AspectJ structure information is + derived from the last compile of your AspectJ program. + </para> + </refsect3> + </refsect2> + + <refsect2> + <title>Compilation and JavaDoc</title> + + <para> + The option <option>AspectJ Compile File Specification</option> + can be customized from the <guisubmenu>Customize options</guisubmenu> + under the <guimenu>AspectJ</guimenu> menu, changing the default + compile specification given to <command>ajc</command>. + See <link linkend="ajdee-installationetc">installation instructions</link> + for examples and other customizations. + </para> + + <para> + AspectJ JavaDoc support is + enabled by setting <option>Jde Javadoc Command Path</option> to + invoke <command>ajdoc</command>. These are the default settings + provided in the installation instructions. + </para> + </refsect2> + + </refsect1> + + <refsect1 id="exploringspacewar"><!-- Exploring the Spacewar Source Code --> + <title>Exploring the Spacewar Source Code</title> + <para> + To begin exploring Spacewar within emacs using JDE and AspectJ mode: + </para> + <itemizedlist> + <listitem> + <para>Compile spacewar.</para> + </listitem> + + <listitem> + <para>Change into the <filename>spacewar</filename> + directory.</para> + </listitem> + + <listitem> + <para>Type <userinput>emacs Ship.java</userinput>.</para> + </listitem> + + <listitem> + <para> + Pull down the <guimenu>JDE</guimenu> menu and select the + <guimenuitem>Speedbar</guimenuitem> entry to show the AspectJ + files in the directory. Note that <filename>Ship.java</filename> + is shown in red to denote that it is currently shown in the main + buffer. + </para> + </listitem> + + <listitem> + <para> + Double-click with the left mouse button on the + <literal>+</literal> in front of the + <filename>Ship.java</filename> entry. It should display an entry + for the class <classname>Ship</classname>. + </para> + </listitem> + + <listitem> + <para> + Double-clicking on Ship will navigate to its declaration in + the buffer. Note that declarations of advice are annotated to + note the types of objects that they advise, declarations of + methods that are advised are annotated with the aspects that + advise them, and so forth. + </para> + </listitem> + + <listitem> + <para> + Double-clicking on the <literal>+</literal> in front of either + will show the declared fields, methods, inter-type declarations, and + advice. A <literal>+</literal> in front of any field or method + means that it is introduced or advised; double-clicking will list + entries for the introducers/advisers; double-clicking on them + will navigate to their declarations. A <literal>+</literal> in + front of any inter-type declarations or advice will will display its + targets. + </para> + </listitem> + + </itemizedlist> + </refsect1> + + <refsect1 id="ajdee-installationetc"><!-- Installation and Compatibility --> + <title>Installation and Compatibility</title> + + <para> AJDEE requires the installation of + <ulink url="http://sunsite.auc.dk/jde">JDE 2.2.9beta4</ulink> or + higher and small edits to your <filename>.emacs</filename> file to + configure AJDEE and enable autoloading AJDEE when a + <filename>.java</filename> file is loaded. + </para> + + <refsect2> + <title>Installation for enhancement of JDE mode</title> + +<!-- <note> --> + <para> + The first and last steps, with enhancements, can be found in the + example Emacs initialization file + <filename>sample.emacs</filename> and the sample JDE project + file <filename>sample.prj</filename> in the distribution. The + latter also demonstrates a way to enable AspectJ mode on a + per-project basis. + </para> +<!-- </note> --> + + <orderedlist> + <listitem> + <para> + Make sure AJDEE, aspectj-mode, JDE, and supporting packages are on + your <literal>load-path</literal> and are ``required''. This is an + example for the 1.0 release: + <programlisting> + ;; I keep my emacs packages in C:/Emacs + (setq load-path + (append + '( + "C:/Emacs/aspectj-emacsMode-1.0" ; for AJDEE + "C:/Emacs/aspectj-emacsAJDEE-1.0" + "C:/Emacs/jde-2.2.9beta6/lisp" + "C:/Emacs/elib-1.0" ; for JDEE + "C:/Emacs/speedbar-0.14beta2" ; for JDEE + "C:/Emacs/semantic-1.4beta12" ; for JDEE/speedbar + "C:/Emacs/eieio-0.17beta3" ; for JDEE + ) + load-path)) + + (require 'jde) + (require 'ajdee) ; can also appear in prj.el</programlisting> + </para> + </listitem> + + <listitem> + <para> + <emphasis>[Optional]</emphasis> add <literal>-emacssym</literal> + switch to the <filename>ajc</filename> and <filename>ajc.bat</filename> + files in your AspectJ tools installations (in the + <filename>/bin</filename> directory). If you invoke the compiler + outside Emacs, this will + ensure that your compiles always generate information for annotations + and the jump menu in the form of <literal>.ajesym</literal> files. + </para> + </listitem> + + <listitem> + <para> + Customize AJDEE's compile options by + putting a version of the following in your + <filename>.emacs</filename> file or in a JDE project file + <filename>prj.el</filename> in your project's hierarchy (see the + <option>JDE Project File Name</option> option for the latter). + Here is a simple example: + + <programlisting> + ;; A default version for simple projects, maybe good for + ;;; .emacs file. + (custom-set-variables + '(jde-compiler '("ajc" "ajc")) + '(jde-javadoc-command-path "ajdoc") + + ;; ajc requires all files to be named for a compile + '(aspectj-compile-file-specification "*.java"))</programlisting> + + Here is an example for spacewar, in + <filename>examples/spacewar</filename>. + <programlisting> + ;;; These options are for the spacewar, in examples/spacewar. + (custom-set-variables + '(jde-compiler '("ajc" "ajc")) + '(jde-javadoc-command-path "ajdoc") + + ;; ajc provides an ``argfile'' mechanism for specifying all files. + '(aspectj-compile-file-specification "-argfile demo.lst") + + ;; *if* compiling packages, name root dir for package hierarchy + ;; to tell ajc where .class files should go. + '(jde-compile-option-directory "..") + '(jde-run-working-directory "..")) + '(jde-run-application-class "spacewar.Game")</programlisting> + </para> + </listitem> + <listitem> + <para> + <emphasis>[XEmacs only]</emphasis> If you're installing JDE + yourself, be sure to closely follow the JDE installation + directions for XEmacs, otherwise you may get out of date JDE + <filename>.jar</filename> files. + </para> + </listitem> + </orderedlist> + + </refsect2> + + <refsect2> + <title>Customizing Options</title> + <para> + Selecting <guimenuitem>Customize options</guimenuitem> from the + <guimenu>AspectJ</guimenu> menu displays a number of options that + customize AspectJ mode. These control whether annotations are shown + by default, and whether the bovinator set up by JDE runs. + <option>AspectJ Compile File Specification</option>, specifies a + compilation argument as + an alternative to the current buffer's file or the run class's file. + Example customizations are shown above and in the sample files + discussed above. + </para> + </refsect2> + + </refsect1> + + + <refsect1> + <title>Usage and Upgrade Problems</title> + + Please see the documentation for + <link linkend="aspectj-mode">aspectj-mode</link> for problems not + specific to AJDEE's features. + + <itemizedlist> + + <listitem> + <para><emphasis>Symptom</emphasis>: Get + standard speedbar menus in JDE; no annotations display. Message: + +<screen> +AspectJ Mode Warning: Can't find declarations file for... +</screen> + +</para> + + <para>AspectJ file has not been compiled with ajc and the <literal>-emacssym</literal> + flag, + or was compiled with an obsolete version of ajc. After compilation, + there should be a <file>.ajesym for every <file>.java in the + build. If .ajsym files are present but error persists, recompile. Note + that aspectj-mode for JDE has a fallback view for uncompiled files. + </para> + </listitem> + + <listitem> + <para><emphasis>Symptom</emphasis>: Navigations via the speedbar and + the jump menu are off, annotations are misplaced in the code. </para> + + <para>AspectJ mode operates by querying data + derived from the most recent compile that includes the + <literal>-emacssym</literal> flag. Recompile the entire program with + ajc including the switch. Consider permanently installing the switch + by editing the ajc and ajc.bat files in the /bin file in your + distribution.</para> + </listitem> + + <listitem> + <para><emphasis>Symptom</emphasis>: Java files that are part of a Java project not written + in AspectJ come up in aspectj-mode. </para> + + <para>Emacs uses the file suffix (.java) to + determine which mode to invoke. You can either globally toggle the + AspectJ features from the AspectJ menu, or you can prevent AJDEE + from coming up by moving the (require 'ajdee) expression from + your .emacs file to a prj.el file in each AspectJ project's directory + (see sample.prj in the distribution). + </para> + </listitem> + + <listitem> + <para><emphasis>Symptom</emphasis>: Reported bug fixes and new features + to AJDEE are not seen, or ajdee.el cannot be found or loaded, with + message: + +<screen> +Error in init file: File error: "Cannot open load file", "ajdee" +</screen> + +</para> + <para>Your load-path variable (set in your .emacs) + is referring to an old release. Change your load-path to + point at the directory for the current release. See the sample.emacs + files in the distribution, for example.</para> + </listitem> + </itemizedlist> + </refsect1> +</refentry> + +<!-- Local variables: --> +<!-- fill-column: 79 --> +<!-- compile-command: "ant -quiet dev-html" --> +<!-- sgml-local-ecat-files: devguide.ced --> +<!-- sgml-parent-document:("devguide.sgml" "book" "refentry") --> +<!-- End: --> diff --git a/docs/devGuideDB/ajdeforte.xml b/docs/devGuideDB/ajdeforte.xml new file mode 100644 index 000000000..910f62d81 --- /dev/null +++ b/docs/devGuideDB/ajdeforte.xml @@ -0,0 +1,215 @@ +<refentry> + <refnamediv> + <refname> + AspectJ Development Environment (AJDE) support for Forte + </refname> + <refpurpose> + Module extension to Sun's <ulink url="http://www.sun.com/forte/ffj">Forte + for Java</ulink> and + <ulink url="http://netbeans.org">NetBeans</ulink> IDEs. + </refpurpose> + </refnamediv> + + <refsect1> + <title>Overview</title> + <para> + For release-specific documentation refer to the <ulink + url="http://aspectj.org/doc/dist/changes.html"> changes file</ulink>. + </para> + + <para> + AJDE for Forte will allow you to: + <itemizedlist> + + <listitem><para>compile AspectJ and Java files within the + IDE</para></listitem> + + <listitem><para>browse the structure of your AspectJ + program</para></listitem> + + <listitem><para>set up a compile configuration that determine which + files will be passed to the compiler</para></listitem> + + </itemizedlist> + </para> + </refsect1> + + <refsect1> + <title>Installation</title> + <para> + + <itemizedlist> + <listitem><para>use the installer to place the "ajdeForForte.jar" and + "aspectjrt.jar" into the modules directory. This will also install + the two html files "LICENCE-AJDEFORTE.html" and + "README-AJDEFORTE.html".</para></listitem> + + <listitem><para>start up, and in the "Tools" menu select "Global + Options" </para></listitem> + + <listitem><para>right-click the "Modules" item and select "New Module + from File..." </para></listitem> + + <listitem><para>find the ajdeForForte.jar in the directory that you + installed into (e.g. c:/forte4j/modules) and select it + </para></listitem> + </itemizedlist> + + </para> + <para> + To uninstall follow Forte's documentation on un-installing modules, or + simply remove the file modules/aspectjForForte.jar from Forte's + install directory. + </para> + </refsect1> + + <refsect1> + <title>Running AJDE for Forte</title> + <para> + <emphasis role="strong">3.1 Setting up the AspectJ Examples (in + NetBeans 3.3.1)</emphasis> + + <imageobject> + <imagedata fileref="netbeans-building.gif"/> + </imageobject> + + <itemizedlist> + + <listitem><para>in the "Project" menu select "Project Manager" + </para></listitem> + + <listitem><para>Click "New..." and enter "AspectJ Examples" as the + projects' name and click "OK". </para></listitem> + + <listitem><para>In the "Filesystems" Explorer tab right click + "Filesystems", then select "Mount -> Local Directory". + </para></listitem> + + <listitem><para>browse into the AspectJ install directory (e.g. + "C:/apps/aspectj1.0") </para></listitem> + + <listitem><para>select "examples" and click "Finish" + </para></listitem> + + + <listitem><para>In the "Tools" menu select "AspectJ -> Start AJDE" + or just click on the "AJDE" + (<inlinemediaobject> + <imageobject> + <imagedata fileref="startAjde.gif"/> + </imageobject> + </inlinemediaobject>) + button (shown as label 1 of the screenshot). + </para></listitem> + + </itemizedlist> + </para> + <para> + <emphasis role="strong">3.2 Compiling the Spacewar Example</emphasis> + + <itemizedlist> + + <listitem><para>After AJDE is started, a new "AspectJ" tab is added + to the explorer window. Click it. The next thing to do is to choose + a particular build, since there are many in the examples + distribution. To the right of the "Build" button + (<inlinemediaobject> + <imageobject> + <imagedata fileref="build.gif"/> + </imageobject> + </inlinemediaobject>) + there is a downward arrow. Click it, and select "spacewar/demo.lst" + (as in label 2 of the screenshot). This will start a build of the + demo configuration of spacewar. Clicking the "Build" button will + rebuild. </para></listitem> + + <listitem><para>When the compile is finished and the "AspectJ + Explorer" structure is present navigate the structure by clicking + nodes (as shown in label 3 of the screenshot). Note that + associations between nodes appear with UML-style arrow icons and + italicized names and reperesent how a particular node in the + structure relates to others. In order to navigate these associations + expand the notes and click the corresponding links (in blue). These + links represent structure nodes elsewhere in the tree. + </para></listitem> + + <listitem><para>If there are compilation errors, clickable messages + will appear (as in label 4 of the screenshot). + </para></listitem> + + </itemizedlist> + + </para> + <para> + + <emphasis role="strong">3.3 Running the Spacewar Example</emphasis> + <itemizedlist> + <listitem><para> + In the "Filesystems" Explorer tab open the "spacewar" + directory, right click "spacewar/Game.java", and the select + "Execute". + </para></listitem> + + <listitem><para>When finished executing switch back to the "Editing" + mode.</para></listitem> + + <listitem><para>Select and build the "debug.lst" configuration as + described in 3.2 and execute again--you will notice that the debug + configuration adds a debug window used for tracing by including the + "Debug.java" aspect in the compile.</para></listitem> + </itemizedlist> + + </para> + + <emphasis role="strong">3.4 Debugging the Spacewar Example</emphasis> + + <itemizedlist> + <listitem><para> + You must first add the filesystem to the project so + that the debugger can see the main class. Do this in + the "Project AspectJ Examples" tab in the explorer by + right clicking the root node and selecting "Add + Existing...". + </para></listitem> + + <listitem><para>You may now need to add the AspectJ Runtime to the + project so that the debugger can see it. In the same way as described + in 3.1 select "Mount -> Archive (JAR, Zip)". </para></listitem> + + <listitem><para>Browse to the your lib/ext/aspectjrt.jar file within + your NetBeans install directory and click "Finish".</para></listitem> + + <listitem><para> + Select "Project -> Set Project Main Class..." in the + menu bar, browse to "spacewar/Game.java" in the + examples directory that you created and click "OK". + </para></listitem> + + <listitem><para> + In the "Filesystems" Explorer tab open the "spacewar" + directory, click "Game.java", and the select "Debug + -> Strat" from the menu bar. + </para></listitem> + </itemizedlist> + + <para> + AspectJ-related options can be modified in the AJDE settings window. + </para> + <imageobject> + <imagedata fileref="netbeans-buildOptions.gif"/> + </imageobject> + + + + + + + </refsect1> +</refentry> + +<!-- Local variables: --> +<!-- fill-column: 79 --> +<!-- compile-command: "ant -quiet dev-html" --> +<!-- sgml-local-ecat-files: devguide.ced --> +<!-- sgml-parent-document:("devguide.sgml" "book" "refentry") --> +<!-- End: --> diff --git a/docs/devGuideDB/ajdejbuilder.xml b/docs/devGuideDB/ajdejbuilder.xml new file mode 100644 index 000000000..a201dd48d --- /dev/null +++ b/docs/devGuideDB/ajdejbuilder.xml @@ -0,0 +1,266 @@ +r<refentry> + <refnamediv> + <refname> + AspectJ Development Environment (AJDE) support for JBuilder + </refname> + <refpurpose> + OpenTool extension Borland's <ulink url="http://www.borland.com/jbuilder">JBuilder IDE</ulink>. + </refpurpose> + </refnamediv> + <refsect1> + <title>Overview</title> + <para> + For release-specific documentation refer to the <ulink url="http://aspectj.org/doc/dist/changes.html"> changes file</ulink>. + </para> + <para> + AJDE for JBuilder will allow you to: + <itemizedlist> + <listitem> + <para>compile AspectJ and Java files within the + IDE</para> + </listitem> + <listitem> + <para>browse the structure of your AspectJ + program</para> + </listitem> + <listitem> + <para>set up a compile configuration that determine which + files will be passed to the compiler</para> + </listitem> + </itemizedlist> + </para> + </refsect1> + <refsect1> + <title>Installation and Project Setup</title> + <para> + <command>Install procedure:</command> use the installer to place the + "ajdeForJBuilder.jar" and "aspectjrt.jar" into JBuilder's lib/ext + directory. This will also install the two html files + "LICENCE-AJDEJBUILDER.html" and "README-AJDEJBUILDER.html". + </para> + <para> + <command>Uninstall procedure:</command> remove "ajdeForJBuilder.jar" + and "aspectjrt.jar" (and the two html files, if you like) from the + "lib/ext" directory. + </para> + <para> + <command>Project setup:</command> follow the normal procedure for + JBuilder project setup (for an example of this please refer to the + example below). However, note that all of the source files to be + passed to the compiler must be added to your project either as files or + within a package that is added to the project. This is necessary + because -- unlike a pure Java compiler -- ajc does not search the + SOURCEPATH for classes. + </para> + <imageobject> + <imagedata fileref="jbuilder-building.gif" /> + </imageobject> + <para> + <command>Starting and stopping AJDE:</command> select "Start AJDE" in + the "AspectJ" section of the "Tools" menu, or just click on the "AJDE" + (<inlinemediaobject id="ajdebutton"> + <imageobject> + <imagedata fileref="startAjde.gif" /> + </imageobject> + </inlinemediaobject>) button (label 1 in the first screenshot). This + will enable AJDE commands and will replace JBuilder's structure view + with the AspectJ Browser. To disable AJDE select "Stop AJDE" in the + same menu, or click the "AJDE" button again. + </para> + </refsect1> + <refsect1> + <title>Compiling and Running the Project</title> + <para> + To compile the project select "Build project with ajc" from the AspectJ + toolbar, or click <ctrl>F11 while the editor pane is active. All + of the files contained in your project and within any packages and + subpackages that have been added to your project will be compiled. You + may also select a different configuration (as with label 2 in the first + screenshot). Then, structure of the currently visited file is shown + (see label 3 in the first scrrenshot). If there is a compile error, + the clickable error message is available (as with label 4 in the first + screenshot). + </para> + <para> + To run the project select "Run Project" from the AspectJ toolbar, or + click <ctrl>F12 while the editor pane is active. Note that the + "AspectJ Runtime" library must be added to your project in order to + run. If the library is not added you will see a
"java.lang.NoClassDefFoundError: org/aspectj/lang/Signature" error.
The library is created automatically for you from the runtime + in "jbuilderdir/lib/ext". You can also create a new library + to use the runtime from a different location. If you have not added the + library to the "Required Libraries" of your project it will be added + automatically when you restart JBuilder. + </para> + <para> + JBuilder7 users please note: when you set up a run/debug configuration + you must select the "Build Target" (at the bottom of the + "Runtime Properties" dialog) to be "<None>". This will ensure + that the Java compiler is not invoked on your AspectJ sources + before running or debugging the project. + </para> + </refsect1> + <refsect1> + <title>Navigating the Program Structure</title> + <imageobject> + <imagedata fileref="jbuilder-structureNavigation.gif" /> + </imageobject> + <para> + Navigation of program structure is provided by the <xref linkend="ajbrowser">AspectJ Browser</xref>, so apart from a JBuilder + look and feel, the extra navigation AspectJ allows work as described + there. In particular, you can use views with labels 1, 2 and 4 of the + second screenshot to navigate structure using the blue links, and you + can set filtering and navigate history using the toolbar shown by label + 3 of the second screenshot. + </para> + </refsect1> + <refsect1> + <title>Manipulating Build Configurations</title> + <para> + Build configurations can be manipulated adding, removing, and + editing build configuration files. The <xref linkend="ajbrowser">AspectJ Browser</xref> is used to select the + current build configuration. Configurations are represented by + ".lst" files which are described in the <xref linkend="ajc">ajc</xref> documentation. + </para> + <imageobject> + <imagedata fileref="jbuilder-configs.gif" /> + </imageobject> + <refsect2> + <title>Adding and Removing Build Configurations</title> + <para> + By default all of the files contained in your project and + within any packages and subpackages that have been added to + your project will be compiled. In order to compile a different + configuration first add it to the project (by selecting + "Add Files / Packages..." in the "Project" + menu, and selecting the desired build configuration file (see + label 1 in the third screenshot). + </para> + </refsect2> + <refsect2> + <title>Editing Build Configurations</title> + <para> + Double click a build configuration file in JBuilder's + "Project Pane" in order to edit it. Configurations + can be edited as either text or in the graphical designer (see + labels 2 and 3 in the third screenshot) + </para> + </refsect2> + </refsect1> + <refsect1> + <title>Example: Setting up the "Spacewar" Sample Project</title> + <para> + To set up the Spacewar example first download it the <ulink url="http://aspectj.org/dl">examples distribution</ulink>. Then + + <orderedlist> + <listitem> + <para>launch JBuilder</para> + </listitem> + <listitem> + <para>in the "File" menu select "New + project"</para> + </listitem> + <listitem> + <para>Select the location of the "aspectj/examples" + directory for the project. This is because the Spacewar + example uses both the "spacewar" and "coordination" + packages, so we set up the project where it can get at both + packages. + </para> + </listitem> + <listitem> + <para> + Choose a "jpr" project, either by typing in "Spacewar.jpr" + as the project name, or by typing "Spacewar" as the project + name and "jpr" as the type. Make sure "aspectj/examples" + is still the directory for the project. </para> + </listitem> + <listitem> + <para>click "Finish"</para> + </listitem> + <listitem> + <para>in the "Project" menu select "Project + properties..."</para> + </listitem> + <listitem> + <para>set the "Output path" entry to be the directory + where you want your classes to go</para> + </listitem> + <listitem> + <para>set the "Output path" entry to be the directory + where you want your classes to go</para> + </listitem> + <listitem> + <para>add "aspectjrt.jar" as a required library for + the project. This library is located in + "<jbuilder-install-directory>/lib/ext". + </para> + </listitem> + <listitem> + <para> + in the "Source" tab select the entry and click + "Edit" (by default JBuilder will set this directory to be + "examples/src" which does not exist)</para> + </listitem> + <listitem> + <para> + Select the "examples" directory for the + Souce. </para> + </listitem> + <listitem> + <para>click "OK" to close the "Project + Properties"dialog</para> + </listitem> + <listitem> + <para>in the leftmost pane you will notice + "Spacewar.jpr", right click this and select "Add to + project" in the popup, then "Add class/package..." in + thenext popup. Or directly choose "Add + files/packages". </para> + </listitem> + <listitem> + <para><cntrl> select the "spacewar" and + "coordination" packages and then click "OK"; this will add + the two packages to your project</para> + </listitem> + <listitem> + <para>click the "Build Project" button + (<inlinemediaobject> + <imageobject> + <imagedata fileref="jbuilder-build.gif" /> + </imageobject> + </inlinemediaobject>) + to compile the project</para> + </listitem> + <listitem> + <para>open the Structure View to browse the structure + of the program</para> + </listitem> + <listitem> + <para>click the "Run Project" button to play + Spacewar (make sure that you have set up the runtime + library as described above)</para> + </listitem> + <listitem> + <para>if you have not selected a class to run, you + will be prompted to do so: select the class + "spacewar.Game". </para> + </listitem> + <listitem> + <para>AspectJ related build options can be + manipulated in the "AJDE settings" window + </para> + <imageobject> + <imagedata fileref="jbuilder-buildOptions.gif" /> + </imageobject> + </listitem> + </orderedlist> + </para> + </refsect1> +</refentry> + +<!-- Local variables: --> +<!-- fill-column: 79 --> +<!-- compile-command: "ant -quiet dev-html" --> +<!-- sgml-local-ecat-files: devguide.ced --> +<!-- sgml-parent-document:("devguide.sgml" "book" "refentry") --> +<!-- End: --> diff --git a/docs/devGuideDB/ajdoc.xml b/docs/devGuideDB/ajdoc.xml new file mode 100644 index 000000000..be13c897c --- /dev/null +++ b/docs/devGuideDB/ajdoc.xml @@ -0,0 +1,155 @@ +<refentry> + <refnamediv> + <refname>ajdoc</refname> + <refpurpose>generate HTML API documentation, including crosscutting structure (early-access) + </refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>ajdoc</command> + <arg choice="opt"> + -bootclasspath <replaceable>classpathlist</replaceable> + </arg> + <arg choice="opt"> + -classpath <replaceable>classpathlist</replaceable> + </arg> + <arg choice="opt">-d <replaceable>path</replaceable></arg> + <arg choice="opt">-help</arg> + <arg choice="opt">-package</arg> + <arg choice="opt">-protected</arg> + <arg choice="opt">-private</arg> + <arg choice="opt">-public</arg> + <arg choice="opt">-overview <replaceable>overviewFile</replaceable></arg> + <arg choice="opt"> + -sourcepath <replaceable>sourcepathlist</replaceable> + </arg> + <arg>-verbose</arg> + <arg>-version</arg> + <group> + <arg><replaceable>sourcefiles...</replaceable></arg> + <arg><replaceable>packages...</replaceable></arg> + <arg>@<replaceable>file...</replaceable></arg> + <arg>-argfile <replaceable>file...</replaceable></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + Similar to <command>javadoc</command>, + <command>ajdoc</command> renders HTML documentation for pointcuts, + advice, and inter-type declarations, as + well as the Java constructs that Javadoc renders. + <command>ajdoc</command> also links + advice from members affected by the advice and + the inter-type declaration for members declared from aspects. + The aspect will be fully documented, + as will your target classes, including links to any + advice or declarations that affect the class. + That means, for example, that + you can see everything affecting a method when reading + the documentation for the method. + </para> + + <para> + To run <command>ajdoc</command>, use one of the scripts in the + AspectJ <filename>bin</filename> directory. + The <command>ajdoc</command> implementation builds on Sun's <command>javadoc</command> + command line tool, and you use it in the same way with many of + the same options + (<command>javadoc</command> options are not documented here; + for more information on <command>javadoc</command> usage, see the + <ulink url="http://java.sun.com/j2se/javadoc/">Javadoc homepage</ulink>.) + </para> + + <para> + As with <command>ajc</command> (but unlike <command>javadoc</command>), + you pass <command>ajdoc</command> all your aspect source files + and any files containing types affected by the aspects; + it's often easiest to just pass all the <filename>.java</filename> files + in your system. + Unlike <command>ajc</command>, + <command>ajdoc</command> will try to find package sources using the + specified sourcepath if you list packages on the command line. + </para> + + + <para> + To provide an argfile listing the source files, you can use + use the same argfile (<filename>@filename</filename>) conventions + as with <command>ajc</command>. + For example, the following documents all the source files listed + in <filename>argfile.lst</filename>, sending the output to + the <literal>docDir</literal> output directory. + + <programlisting>ajdoc -d docDir @argfile.lst</programlisting> + + See the <link linkend="ajc">ajc documentation</link> + for details on the text file format. + </para> + + <para> + <command>ajdoc</command> currently requires the + <filename>tools.jar</filename> from J2SE 1.3 to be on the classpath. + Normally the scripts set this up, assuming that your <literal>JAVA_HOME</literal> + variable points to an appropriate installation of Java. + You may need to provide this jar when using a different + version of Java or a JRE. + </para> + + </refsect1> + <refsect1> + <title>Examples</title> + <example id="ajdocdocumentingspacewar"> <!-- docbook bug - rendering this as example 4? --> + <title>Documenting Spacewar</title> + <itemizedlist> + <listitem> + <para> + Change into the <filename>examples</filename> directory. + </para> + </listitem> + + <listitem> + <para> + Type <userinput>mkdir doc</userinput> to create the + destination directory for the documentation. + </para> + </listitem> + <listitem> + <para> + Type <userinput>ajdoc -private -d doc spacewar + coordination</userinput> to generate the documentation. + </para> + <itemizedlist> + <listitem> + <para> + (Use <literal>-private</literal> to get all members, since + may of the interesting ones in spacewar are not public.) + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + Type <userinput>ajdoc -private -d doc @spacewar/demo.lst</userinput> + to use the argfile associated with Spacewar. + </para> + </listitem> + <listitem> + <para> + To view the documentation, open the file <filename>index.html</filename> + in the <filename>doc</filename> directory using a web browser. + </para> + </listitem> + </itemizedlist> + </example> + </refsect1> +</refentry> + +<!-- Local variables: --> +<!-- fill-column: 79 --> +<!-- sgml-local-ecat-files: devguide.ced --> +<!-- sgml-parent-document:("devguide.sgml" "book" "refentry") --> +<!-- End: --> diff --git a/docs/devGuideDB/antsupport.xml b/docs/devGuideDB/antsupport.xml new file mode 100644 index 000000000..1b97968aa --- /dev/null +++ b/docs/devGuideDB/antsupport.xml @@ -0,0 +1,23 @@ +<refentry> + <refnamediv> + <refname>Ant Support</refname> + <refpurpose>Support of Ant</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>ant </command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para></para> + </refsect1> +</refentry> + +<!-- Local variables: --> +<!-- fill-column: 79 --> +<!-- sgml-local-ecat-files: devguide.ced --> +<!-- sgml-parent-document:("devguide.sgml" "book" "refentry") --> +<!-- End: --> diff --git a/docs/devGuideDB/aspectj-mode.gif b/docs/devGuideDB/aspectj-mode.gif Binary files differnew file mode 100644 index 000000000..9b07fdb33 --- /dev/null +++ b/docs/devGuideDB/aspectj-mode.gif diff --git a/docs/devGuideDB/aspectj-mode.xml b/docs/devGuideDB/aspectj-mode.xml new file mode 100644 index 000000000..b54837964 --- /dev/null +++ b/docs/devGuideDB/aspectj-mode.xml @@ -0,0 +1,354 @@ +<refentry id="aspectj-mode"> + <refnamediv> + <refname>AspectJ-mode</refname> + <refpurpose>support for XEmacs and GNU Emacs + </refpurpose> + </refnamediv> + + <refsect1> + <title>AspectJ-mode User's Guide</title> + <para> + This guide describes aspectj-mode for GNU Emacs and XEmacs, which + provides enhanced editing and management of AspectJ code via a minor + mode extension of java-mode. Included in this document + are guidance for aspectj-mode's <link + linkend="ajmode-featuresandusage">use</link>, and + <link linkend="ajmode-installationetc">installation and compatibility</link>. + See the README file in the aspectj-mode's distribution directory for + release-specific details. + </para> + + <para> + AspectJ minor mode provides (see graphic): + <itemizedlist> + <listitem> + <para> + Viewing and navigation of aspect structures, permitting + navigation between aspect code and the code that it affects, via + a `jump' menu (and in the speedbar and Classes menu for JDE + users). + </para> + </listitem> + + <listitem> + <para> + Source code annotation of inter-type and advice declarations, + as well as the code they affect. + </para> + </listitem> + + <listitem> + <para> + AspectJ-style compilation, using .lst files to generate a + compilation submenu. + </para> + </listitem> + + <listitem> + <para> + Highlighting of AspectJ keywords and declaration names. + </para> + </listitem> + + </itemizedlist> + </para> + + <para> + The first two are derived from ajc's last build of the AspectJ program. + An example usage is given below. + </para> + + <para> + <inlinemediaobject id="aspectjmodescreenshot"> + <imageobject> + <imagedata fileref="aspectj-mode.gif"/> + </imageobject> + </inlinemediaobject> + </para> + </refsect1> + + <refsect1 id="ajmode-featuresandusage"><!-- Features and Usage --> + <title>Features and Usage</title> + <para> + All commands governing AspectJ mode are available from the AspectJ menu + on the toolbar. Besides those described below, there is a menu item + <guimenuitem>Customize options</guimenuitem> for viewing and customizing + the options of the mode and <guimenuitem>AJ Mode user guide</guimenuitem> + to view this file. Keyword and declaration highlighting is enabled above + the minimal level of highlighting. + </para> + + <para> + By default, AspectJ mode is automatically turned on when a buffer + named with a <filename>.java</filename> suffix is entered. + The command + <command>M-x aspectj-mode-in-force-toggle</command> globally toggles + the features of the mode, easing quickly moving between + AspectJ and Java projects (also available as <guimenuitem>AspectJ mode + extensions</guimenuitem> in the AspectJ menu). + </para> + + <refsect2> + <title>Aspect Structure and Navigation</title> + + <para> + AspectJ minor mode highlights aspect relationships in the text with + textual annotations on the program source (optionally can be turned + off), such as the <literal>[Player, Robot, Ship]</literal> marking after the advice in EnsureShipIsAlive + at the bottom of the <link linkend="aspectjmodescreenshot">figure</link>, + which indicates that the advice refers to join points within Ship + objects. The following commands (also available from the menu) manage + annotations and navigation: + </para> + + <table id="minormodecommands"> + <title> + AspectJ Minor Mode Commands for Annotations and Navigation + </title> + <tgroup cols="2" colsep="1" rowsep="1" align="left"> + <thead> + <row> + <entry>Command (keyboard shortcut)</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry>M-x aspectj-jump-menu (C-x C-j)</entry> + <entry> + Display popup menu of advisers, advisees, and inter-type declarations. + Navigate to item by selecting with mouse + (see <link linkend="aspectjmodescreenshot2">figure</link> below). + </entry> + </row> + <row> + <entry>M-x aspectj-show-annotations</entry> + <entry> + Add crosscut annotations on the text on current buffer. + </entry> + </row> + + <row> + <entry>M-x aspectj-dont-show-annotations</entry> + <entry> + Remove crosscut annotations from text on current buffer. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + The default for whether annotations are shown or not can be + customized by selecting <guimenuitem>Customize options</guimenuitem> + from the <guimenu>AspectJ</guimenu> menu. + </para> + + <para> + <inlinemediaobject id="aspectjmodescreenshot2"> + <imageobject> + <imagedata fileref="aspectj-mode2.gif"/> + </imageobject> + </inlinemediaobject> + </para> + + </refsect2> + + <refsect2> + <title>Compilation</title> + + <para> + The <guisubmenu>Compile</guisubmenu> submenu + accessible from the <guimenu>AspectJ</guimenu> menu presents the + known<filename> .lst</filename> files for the project. Selecting + one compiles the project with that <filename>.lst</filename> file + and remembers that for future compiles. The + <guimenuitem>Compile...</guimenuitem> command accessible from the + Emacs <guimenu>Tools</guimenu> menu is customized through the + project customization option <option>Aspectj Tools Compile + Command</option>, customizable from the + <guimenu>AspectJ</guimenu> menu. + </para> + + </refsect2> + + </refsect1> + + <refsect1 id="ajmode-installationetc"><!-- Installation and Compatibility --> + <title>Installation and Compatibility</title> + + <para> AspectJ mode requires the installation of <ulink + url="http://www.gnu.org/software/emacs/">GNU Emacs 20.3.1</ulink> + or <ulink url="http://www.xemacs.org/">XEmacs 21.1.14 (Unix/Linux)</ulink>, + or <ulink url="http://www.xemacs.org/">XEmacs 21.4 (Windows)</ulink>, + or higher. In general, the most recent non-alpha/beta versions of these + are recommended. A web browser is required to view this documentation + via Emacs. Small modifications to the <filename>.emacs</filename> file + configures AspectJ mode and enables autoloading AspectJ mode when a + <filename>.java</filename> file is loaded. + </para> + + <refsect2> + <title> + Installation + </title> + +<!-- <note> --> + <para> + Step 1, with enhancements, can be found in the example Emacs + initialization file <filename>sample.emacs</filename> in the + distribution. + </para> +<!-- </note> --> + + <orderedlist> + <listitem> + <para> + The files in this package need to be in the load-path and + ``required''. For example, for the 1.0 release: + <programlisting> + ;; I keep my emacs packages in C:/Emacs + (setq load-path (cons "C:/Emacs/aspectj-emacsMode-1.0" load-path)) + (require 'aspectj-mode)</programlisting> + </para> + </listitem> + + <listitem> + <para> + <emphasis>[Optional]</emphasis> add <literal>-emacssym</literal> + switch to the <filename>ajc</filename> and <filename>ajc.bat</filename> + files in your AspectJ tools installations (in the + <filename>/bin</filename> directory). If you invoke the compiler + outside Emacs, this will + ensure that your compiles always generate information for annotations + and the jump menu in the form of <literal>.ajesym</literal> files. + </para> + </listitem> + + <listitem> + <para> + <!-- TBD: Change to something less bogus. --> + <emphasis>[XEmacs only]</emphasis> Go to the + <filename>xemacs-packages/lisp</filename> directory of your + XEmacs distribution and move the <filename>jde</filename> + directory to someplace harmless. Otherwise, Java files will come + up in JDE mode. + </para> + </listitem> + + </orderedlist> + </refsect2> + + <refsect2> + <title>Customizing Options</title> + <para> + Selecting <guimenuitem>Customize options</guimenuitem> from the + <guimenu>AspectJ</guimenu> menu displays a number of options that + customize AspectJ mode. These control whether annotations are shown + by default, as well as a + number of options controlling compilation and beanshell for + java-mode. + Example customizations are given in the file + <filename>sample.emacs</filename> in the distribution. + </para> + </refsect2> + + </refsect1> + + <refsect1> + <title>Usage and Upgrade Problems</title> + + <itemizedlist> + + <listitem> + <para><emphasis>Symptom</emphasis>: No annotations show. Message: + +<screen> +AspectJ Mode Warning: Can't find declarations file for... +</screen> + +</para> + + <para>AspectJ file has not been compiled with ajc and the <literal>-emacssym</literal> + flag, + or was compiled with an obsolete version of ajc. After compilation, + there should be a <file>.ajesym for every <file>.java in the + build. If .ajsym files are present but error persists, recompile. Note + that aspectj-mode for JDE has a fallback view for uncompiled files. + </para> + </listitem> + + <listitem> + <para><emphasis>Symptom</emphasis>: Annotations are misplaced in the + code. </para> + + <para>AspectJ mode operates by querying data + derived from the most recent compile that includes the + <literal>-emacssym</literal> flag. Recompile the entire program with + ajc including the switch. Consider permanently installing the switch + by editing the ajc and ajc.bat files in the /bin file in your + distribution.</para> + </listitem> + + <listitem> + <para><emphasis>Symptom</emphasis>: New customization option settings were saved + for future sessions, but do not show up when Emacs is restarted. + </para> + + <para>You may have two sets of saved settings in + your .emacs file, and Emacs updated the first one, which may be shadowed + by the second.</para> + </listitem> + + <listitem> + <para><emphasis>Symptom</emphasis>: Java files that are part of a Java project not written + in AspectJ come up in aspectj-mode. </para> + + <para>Emacs uses the file suffix (.java) to + determine which mode to invoke. You can either globally toggle the + AspectJ features from the AspectJ menu. + </para> + </listitem> + + <listitem> + <para><emphasis>Symptom</emphasis>: Reported bug fixes and new features + to aspectj-mode are not seen, or aspectj-mode.el cannot be found or + loaded, with message: + +<screen> +Error in init file: File error: "Cannot open load file", "aspectj-mode" +</screen> + +</para> + <para>Your load-path variable (set in your .emacs) + is referring to an old release. Change your load-path to + point at the directory for the current release. See the sample.emacs + files in the distribution, for example.</para> + </listitem> + + <listitem> + <para><emphasis>Symptom</emphasis>: When trying to get a jump menu, + I get the message "No crosscut elements at point" even though + there is a [list] on the same line. + </para> + + <para>The caret (point) is probably on or after the list. + To see the crosscut elements you need to hit the jump menu + on the same line that the annotated elements appear as a list + of items surrounded by '[' and ']' on the same line as the + affected declaration. If the caret is on the same line as the + elements and before the list (i.e. not at the end of the + list of elements) the jump menu should work. + </para> + </listitem> + </itemizedlist> + </refsect1> +</refentry> + +<!-- Local variables: --> +<!-- fill-column: 79 --> +<!-- compile-command: "ant -quiet dev-html" --> +<!-- sgml-local-ecat-files: devguide.ced --> +<!-- sgml-parent-document:("devguide.sgml" "book" "refentry") --> +<!-- End: --> diff --git a/docs/devGuideDB/aspectj-mode2.gif b/docs/devGuideDB/aspectj-mode2.gif Binary files differnew file mode 100644 index 000000000..f9e718385 --- /dev/null +++ b/docs/devGuideDB/aspectj-mode2.gif diff --git a/docs/devGuideDB/devguide.xml b/docs/devGuideDB/devguide.xml new file mode 100644 index 000000000..5b2b1ba30 --- /dev/null +++ b/docs/devGuideDB/devguide.xml @@ -0,0 +1,69 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> + +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN" + "../../lib/docbook/docbook-dtd/docbookx.dtd" +[ +<!ENTITY ajc SYSTEM "ajc.xml"> +<!ENTITY ajdb SYSTEM "ajdb.xml"> +<!ENTITY ajdoc SYSTEM "ajdoc.xml"> +<!ENTITY antsupport SYSTEM "antsupport.xml"> +<!ENTITY ajbrowser SYSTEM "ajbrowser.xml"> +<!ENTITY ajdejbuilder SYSTEM "ajdejbuilder.xml"> +<!ENTITY ajdeforte SYSTEM "ajdeforte.xml"> +<!ENTITY aspectj-mode SYSTEM "aspectj-mode.xml"> +<!ENTITY ajdee SYSTEM "ajdee.xml"> +]> + +<book> + <bookinfo> + <title>The AspectJ<superscript>tm</superscript> Development Environment Guide</title> + + <authorgroup> + <author> + <othername>the AspectJ Team</othername> + </author> + </authorgroup> + + <legalnotice> + <para>Copyright (c) 1998-2001 Xerox Corporation, + 2002 Palo Alto Research Center, Incorporated. + All rights reserved. + </para> + </legalnotice> + + <abstract> + <para> + This user's guide describes the tools which are part of the + AspectJ development environment. A companion guide describes the + AspectJ language. + </para> + </abstract> + </bookinfo> + + <reference> + <title>The Command Line Tools</title> + &ajc; + &ajdb; + &ajdoc; + </reference> + + <reference> + <title>The GUI Tools</title> + &ajbrowser; + &ajdejbuilder; + &ajdeforte; + &aspectj-mode; + &ajdee; + </reference> + +</book> + +<!-- +Local Variables: +compile-command:"ant -quiet dev-html" +fill-column: 79 +sgml-indent-step: 3 +sgml-local-ecat-files:devguide.ced +sgml-namecase-general: t +End: +--> diff --git a/docs/devGuideDB/jbuilder-buildOptions.gif b/docs/devGuideDB/jbuilder-buildOptions.gif Binary files differnew file mode 100644 index 000000000..5a34c9309 --- /dev/null +++ b/docs/devGuideDB/jbuilder-buildOptions.gif diff --git a/docs/devGuideDB/jbuilder-building.gif b/docs/devGuideDB/jbuilder-building.gif Binary files differnew file mode 100644 index 000000000..63fe151a2 --- /dev/null +++ b/docs/devGuideDB/jbuilder-building.gif diff --git a/docs/devGuideDB/jbuilder-configs.gif b/docs/devGuideDB/jbuilder-configs.gif Binary files differnew file mode 100644 index 000000000..1a262c1cf --- /dev/null +++ b/docs/devGuideDB/jbuilder-configs.gif diff --git a/docs/devGuideDB/jbuilder-structureNavigation.gif b/docs/devGuideDB/jbuilder-structureNavigation.gif Binary files differnew file mode 100644 index 000000000..bdd7ce815 --- /dev/null +++ b/docs/devGuideDB/jbuilder-structureNavigation.gif diff --git a/docs/devGuideDB/netbeans-buildOptions.gif b/docs/devGuideDB/netbeans-buildOptions.gif Binary files differnew file mode 100644 index 000000000..5cd5e75d2 --- /dev/null +++ b/docs/devGuideDB/netbeans-buildOptions.gif diff --git a/docs/devGuideDB/netbeans-building.gif b/docs/devGuideDB/netbeans-building.gif Binary files differnew file mode 100644 index 000000000..7ef8f4500 --- /dev/null +++ b/docs/devGuideDB/netbeans-building.gif |
