| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>The AspectJtm Development Environment Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.44"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" id="d0e1"><div class="titlepage"><div><h1 class="title"><a name="d0e1"></a>The AspectJ<sup>tm</sup> Development Environment Guide</h1></div><div><h3 class="author">the AspectJ Team</h3></div><div><div class="legalnotice"><p>Copyright (c) 1998-2001 Xerox Corporation, |
| 2002 Palo Alto Research Center, Incorporated, |
| 2003 Contributors. |
| All rights reserved. |
| </p></div></div><div><div class="abstract"><p><a name="d0e15"></a><b>Abstract</b></p><p> |
| This guide describes the tools in the AspectJ 1.2 development |
| environment. See also |
| <a href="../progguide/index.html" target="_top">The |
| AspectJ Programming Guide</a>, |
| the documentation available with the AspectJ support available for |
| various integrated development environments (e.g., Eclipse, Emacs, |
| JBuilder, and NetBeans), |
| and the most-recent documentation available from |
| the AspectJ project page, at |
| <a href="http://eclipse.org/aspectj" target="_top"> |
| http://eclipse.org/aspectj</a>. |
| |
| </p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>I. <a href="#d0e26"></a></dt><dd><dl><dt><a href="#ajc-ref">ajc</a> - compiler and bytecode weaver for the AspectJ and Java languages </dt><dt><a href="#d0e645">ajdoc</a> - generate HTML API documentation, including crosscutting structure (early-access) |
| </dt></dl></dd><dt>1. <a href="#ajbrowser">AspectJ Browser</a></dt><dd><dl><dt><a href="#ajbrowser-intro"></a></dt><dt><a href="#d0e886">Building Programs</a></dt><dd><dl><dt><a href="#d0e889">Build Configurations</a></dt><dt><a href="#d0e920">Compiling a Program Build Configuration</a></dt></dl></dd><dt><a href="#d0e944">Navigating Program Structure</a></dt><dd><dl><dt><a href="#d0e951">Example: Exploring the "Spacewar" sample code </a></dt></dl></dd><dt><a href="#d0e1077">Running Programs</a></dt><dt><a href="#ajbrowser-problems">Isolating problems running the AspectJ browser</a></dt><dd><dl><dt><a href="#ajbrowser-knownProblems">Known issues with the AspectJ browser</a></dt><dt><a href="#ajbrowser-limitations">Limitations</a></dt><dt><a href="#ajbrowser-feedback">AspectJ Browser questions and bugs</a></dt></dl></dd></dl></dd><dt>2. <a href="#antTasks">AspectJ Ant Tasks</a></dt><dd><dl><dt><a href="#antTasks-intro">Introduction</a></dt><dt><a href="#antTasks-install">Installing Ant Tasks</a></dt><dt><a href="#antTasks-iajc">AjcTask (iajc)</a></dt><dd><dl><dt><a href="#antTasks-iajc-options">AjcTask (iajc) Options</a></dt><dt><a href="#antTasks-nested-includes">AjcTask matching parameters specified as nested elements</a></dt><dt><a href="#antTasks-iajc-paths">AjcTask Path-like Structures</a></dt><dt><a href="#antTasks-iajc-sample">Sample of iajc task</a></dt><dt><a href="#antTasks-iajc-uptodate">Avoiding clean compiles</a></dt><dt><a href="#d0e1878">Programmatically handling compiler messages</a></dt></dl></dd><dt><a href="#antTasks-adapter">Ajc11CompilerAdapter (javac)</a></dt><dd><dl><dt><a href="#antTasks-adapter-sample">Sample of compiler adapter</a></dt><dt><a href="#antTasks-adapter-options">Compiler adapter compilerarg options</a></dt></dl></dd><dt><a href="#antTasks-ajc">Ajc10 (ajc)</a></dt><dd><dl><dt><a href="#antTasks-ajc-options">Ajc10 (ajc) Options</a></dt><dt><a href="#antTasks-ajc-nested">Ajc10 parameters specified as nested elements</a></dt><dt><a href="#antTasks-ajc-sample">Sample of ajc task</a></dt></dl></dd><dt><a href="#antTasks-problems">Isolating problems running the Ant tasks</a></dt><dd><dl><dt><a href="#antTasks-knownProblems">Known issues with the Ant tasks</a></dt><dt><a href="#antTasks-feedback">Ant task questions and bugs</a></dt></dl></dd></dl></dd></dl></div><div class="reference"><div class="titlepage"><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#ajc-ref">ajc</a> - compiler and bytecode weaver for the AspectJ and Java languages </dt><dt><a href="#d0e645">ajdoc</a> - generate HTML API documentation, including crosscutting structure (early-access) |
| </dt></dl></div><div class="refentry"><h1 class="title"><a name="ajc-ref"></a>ajc</h1><div class="refnamediv"><a name="d0e28"></a><h2>Name</h2>ajc — compiler and bytecode weaver for the AspectJ and Java languages </div><div class="refsynopsisdiv"><a name="d0e33"></a><h2>Synopsis</h2><div class="cmdsynopsis" id="d0e34"><a name="d0e34"></a><tt>ajc</tt> [<i><tt>Options</tt></i>] [<i><tt>file...</tt></i> | @<i><tt>file...</tt></i> | -argfile <i><tt>file...</tt></i>]</div></div><div class="refsect1"><a name="ajc"></a><h2>Description</h2><p>The <b>ajc</b> command compiles AspectJ and Java |
| language files, weaving aspects as necessary to produce .class files |
| compliant with any Java VM (1.1 or later). |
| To do bytecode weaving, it also accepts input classes or aspects |
| in binary form. |
| </p><p> The arguments after the options specify the source file(s) to compile. |
| (Specify source classes using the <i><tt>-injars</tt></i> or |
| <i><tt>-inpath</tt></i> options, below.) |
| Files may be listed directly on the command line, or listed in a file. |
| The <i><tt>-argfile <i><tt>file</tt></i></tt></i> |
| and <i><tt>@<i><tt>file</tt></i></tt></i> 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 <tt>//</tt> and |
| extend to the end of the line. |
| </p><p> |
| <b>NB:</b> |
| You must explicitly pass <b>ajc</b> all sources necessary |
| for the compilation. When 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. |
| (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. |
| You may use the <i><tt>-sourceroots</tt></i> option to specify |
| as source all the .aj and .java files in a set of directory trees. |
| </p><div class="refsect2"><a name="d0e92"></a><h3>Options</h3><div class="variablelist"><dl><dt><a name="d0e96"></a><span class="term">-injars <i><tt>JarList</tt></i></span></dt><dd><p><a name="d0e101"></a> |
| deprecated: since 1.2, use -inpath, which also takes |
| directories. |
| </p></dd><dt><a name="d0e104"></a><span class="term">-inpath <i><tt>Path</tt></i></span></dt><dd><p><a name="d0e109"></a> |
| Accept as source bytecode any .class files in the |
| .jar files or directories on Path. |
| The output will include these |
| classes, possibly as woven with any applicable aspects. |
| Path is a single argument containing |
| a list of paths to zip files or directories, |
| delimited by the platform-specific path delimiter. |
| </p></dd><dt><a name="d0e112"></a><span class="term">-aspectpath <i><tt>JarList</tt></i></span></dt><dd><p><a name="d0e117"></a> |
| Weave binary aspects from JarList zip files into all sources. |
| The aspects should have been output by the same version |
| of the compiler. |
| To run the output classes requires putting all the |
| aspectpath entries on the run classpath. |
| JarList, like classpath, is a single argument containing |
| a list of paths to jar files, delimited by the platform- |
| specific classpath delimiter. |
| </p></dd><dt><a name="d0e120"></a><span class="term">-argfile <i><tt>File</tt></i></span></dt><dd><p><a name="d0e125"></a> |
| The file is a line-delimited list of arguments. |
| These arguments are inserted into the argument list. |
| </p></dd><dt><a name="d0e128"></a><span class="term">-outjar <i><tt>output.jar</tt></i></span></dt><dd><p><a name="d0e133"></a>Put output classes in zip file output.jar. |
| </p></dd><dt><a name="d0e136"></a><span class="term">-incremental</span></dt><dd><p><a name="d0e139"></a>Run the compiler continuously. |
| After the initial compilation, the compiler will |
| wait to recompile until it reads a newline from the standard |
| input, and will quit when it reads a 'q'. |
| It will only recompile necessary components, so a recompile |
| should be much faster than doing a second compile. |
| This requires -sourceroots. |
| </p></dd><dt><a name="d0e142"></a><span class="term">-sourceroots <i><tt>DirPaths</tt></i></span></dt><dd><p><a name="d0e147"></a>Find and build all .java or .aj source files under |
| any directory listed in DirPaths. |
| DirPaths, like classpath, is a single argument containing |
| a list of paths to directories, delimited by the platform- |
| specific classpath delimiter. |
| Required by -incremental. |
| </p></dd><dt><a name="d0e150"></a><span class="term">-emacssym</span></dt><dd><p><a name="d0e153"></a> |
| Generate .ajesym symbol files for emacs support |
| </p></dd><dt><a name="d0e156"></a><span class="term">-Xlint</span></dt><dd><p><a name="d0e159"></a>Same as -Xlint:warning (enabled by default) |
| </p></dd><dt><a name="d0e162"></a><span class="term">-Xlint:{level}</span></dt><dd><p><a name="d0e165"></a>Set default level for messages about potential |
| programming mistakes in crosscutting code. |
| {level} may be ignore, warning, or error. |
| This overrides entries in |
| org/aspectj/weaver/XlintDefault.properties |
| from aspectjtools.jar, but does not override levels set |
| using the -Xlintfile option. |
| </p></dd><dt><a name="d0e168"></a><span class="term">-Xlintfile <i><tt>PropertyFile</tt></i></span></dt><dd><p><a name="d0e173"></a>Specify properties file to set levels for |
| specific crosscutting messages. |
| PropertyFile is a path to a Java .properties file that |
| takes the same property names and values as |
| org/aspectj/weaver/XlintDefault.properties |
| from aspectjtools.jar, which it also overrides. |
| </p></dd><dt><a name="d0e176"></a><span class="term">-help</span></dt><dd><p><a name="d0e179"></a> |
| Emit information on compiler options and usage |
| </p></dd><dt><a name="d0e182"></a><span class="term">-version</span></dt><dd><p><a name="d0e185"></a> |
| Emit the version of the AspectJ compiler |
| </p></dd><dt><a name="d0e188"></a><span class="term">-classpath <i><tt>Path</tt></i></span></dt><dd><p><a name="d0e193"></a> |
| Specify where to find user class files. |
| Path is a single argument containing |
| a list of paths to zip files or directories, |
| delimited by the platform-specific path delimiter. |
| </p></dd><dt><a name="d0e196"></a><span class="term">-bootclasspath <i><tt>Path</tt></i></span></dt><dd><p><a name="d0e201"></a> |
| Override location of VM's bootclasspath |
| for purposes of evaluating types when compiling. |
| Path is a single argument containing |
| a list of paths to zip files or directories, |
| delimited by the platform-specific path delimiter. |
| </p></dd><dt><a name="d0e204"></a><span class="term">-extdirs <i><tt>Path</tt></i></span></dt><dd><p><a name="d0e209"></a> |
| Override location of VM's extension directories |
| for purposes of evaluating types when compiling. |
| Path is a single argument containing |
| a list of paths to directories, |
| delimited by the platform-specific path delimiter. |
| </p></dd><dt><a name="d0e212"></a><span class="term">-d <i><tt>Directory</tt></i></span></dt><dd><p><a name="d0e217"></a> |
| Specify where to place generated .class files. |
| If not specified, <i><tt>Directory</tt></i> |
| defaults to the current working dir. |
| </p></dd><dt><a name="d0e223"></a><span class="term">-target <i><tt>[1.1 to 1.4]</tt></i></span></dt><dd><p><a name="d0e228"></a>Specify classfile target setting (1.1 to 1.4, default is 1.2) |
| </p></dd><dt><a name="d0e231"></a><span class="term">-1.3</span></dt><dd><p><a name="d0e234"></a>Set compliance level to 1.3 |
| </p></dd><dt><a name="d0e237"></a><span class="term">-1.4</span></dt><dd><p><a name="d0e240"></a>Set compliance level to 1.4 (default) |
| </p></dd><dt><a name="d0e243"></a><span class="term">-source <i><tt>[1.3|1.4]</tt></i></span></dt><dd><p><a name="d0e248"></a>Toggle assertions (1.3 or 1.4, default is 1.3). |
| When using -source 1.3, an assert() statement valid under |
| Java 1.4 will result in a compiler error. |
| When using -source 1.4, |
| treat <tt>assert</tt> as a keyword and |
| implement assertions according to the 1.4 language spec. |
| </p></dd><dt><a name="d0e254"></a><span class="term">-nowarn</span></dt><dd><p><a name="d0e257"></a>Emit no warnings (equivalent to '-warn:none') |
| This does not suppress messages |
| generated by <tt>declare warning</tt> or |
| <tt>Xlint</tt>. |
| </p></dd><dt><a name="d0e266"></a><span class="term">-warn: <i><tt>items</tt></i></span></dt><dd><p><a name="d0e271"></a>Emit warnings for any instances of |
| the comma-delimited list of questionable code |
| (eg '-warn:unusedLocals,deprecation'): |
| <pre class="programlisting"> |
| constructorName method with constructor name |
| packageDefaultMethod attempt to override package-default method |
| deprecation usage of deprecated type or member |
| maskedCatchBlocks hidden catch block |
| unusedLocals local variable never read |
| unusedArguments method argument never read |
| unusedImports import statement not used by code in file |
| none suppress all compiler warnings |
| </pre> |
| <tt>-warn:none</tt> does not suppress messages |
| generated by <tt>declare warning</tt> or |
| <tt>Xlint</tt>. |
| |
| </p></dd><dt><a name="d0e287"></a><span class="term">-deprecation</span></dt><dd><p><a name="d0e290"></a>Same as -warn:deprecation |
| </p></dd><dt><a name="d0e293"></a><span class="term">-noImportError</span></dt><dd><p><a name="d0e296"></a>Emit no errors for unresolved imports |
| </p></dd><dt><a name="d0e299"></a><span class="term">-proceedOnError</span></dt><dd><p><a name="d0e302"></a>Keep compiling after error, |
| dumping class files with problem methods |
| </p></dd><dt><a name="d0e305"></a><span class="term">-g<i><tt>:[lines,vars,source]</tt></i></span></dt><dd><p><a name="d0e310"></a>debug attributes level, that may take three forms: |
| <pre class="programlisting"> |
| -g all debug info ('-g:lines,vars,source') |
| -g:none no debug info |
| -g:{items} debug info for any/all of [lines, vars, source], e.g., |
| -g:lines,source |
| </pre> |
| |
| </p></dd><dt><a name="d0e316"></a><span class="term">-preserveAllLocals</span></dt><dd><p><a name="d0e319"></a>Preserve all local variables during code generation |
| (to facilitate debugging). |
| </p></dd><dt><a name="d0e322"></a><span class="term">-referenceInfo</span></dt><dd><p><a name="d0e325"></a>Compute reference information. |
| </p></dd><dt><a name="d0e328"></a><span class="term">-encoding <i><tt>format</tt></i></span></dt><dd><p><a name="d0e333"></a>Specify default source encoding format. |
| Specify custom encoding on a per file basis by suffixing |
| each input source file/folder name with '[encoding]'. |
| </p></dd><dt><a name="d0e336"></a><span class="term">-verbose</span></dt><dd><p><a name="d0e339"></a>Emit messages about accessed/processed compilation units |
| </p></dd><dt><a name="d0e342"></a><span class="term">-showWeaveInfo</span></dt><dd><p><a name="d0e345"></a>Emit messages about weaving |
| </p></dd><dt><a name="d0e348"></a><span class="term">-log <i><tt>file</tt></i></span></dt><dd><p><a name="d0e353"></a>Specify a log file for compiler messages. |
| </p></dd><dt><a name="d0e356"></a><span class="term">-progress</span></dt><dd><p><a name="d0e359"></a>Show progress (requires -log mode). |
| </p></dd><dt><a name="d0e362"></a><span class="term">-time</span></dt><dd><p><a name="d0e365"></a>Display speed information. |
| </p></dd><dt><a name="d0e368"></a><span class="term">-noExit</span></dt><dd><p><a name="d0e371"></a>Do not call System.exit(n) at end of compilation |
| (n=0 if no error) |
| </p></dd><dt><a name="d0e374"></a><span class="term">-repeat <i><tt>N</tt></i></span></dt><dd><p><a name="d0e379"></a>Repeat compilation process N times |
| (typically to do performance analysis). |
| </p></dd><dt><a name="d0e382"></a><span class="term">-Xnoweave</span></dt><dd><p><a name="d0e385"></a>(Experimental) produce unwoven class files |
| for input using -injars. |
| </p></dd><dt><a name="d0e388"></a><span class="term">-Xreweavable[:compress]</span></dt><dd><p><a name="d0e391"></a>(Experimental) runs weaver in reweavable mode which causes |
| it to create woven classes that can be rewoven, subject to the restriction that |
| on attempting a reweave all the types that advised the woven type must be accessible. |
| </p></dd><dt><a name="d0e394"></a><span class="term">-XnoInline</span></dt><dd><p><a name="d0e397"></a>(Experimental) do not inline around advice |
| </p></dd><dt><a name="d0e400"></a><span class="term">-XincrementalFile <i><tt>file</tt></i></span></dt><dd><p><a name="d0e405"></a>(Experimental) This works like incremental mode, |
| but using a file rather than standard input to control the compiler. |
| It will recompile each time file is changed and |
| and halt when file is deleted. |
| </p></dd><dt><a name="d0e408"></a><span class="term">-XserializableAspects</span></dt><dd><p><a name="d0e411"></a>(Experimental) Normally it is an error to declare |
| aspects Serializable. This option removes that restriction. |
| </p></dd></dl></div></div><div class="refsect2"><a name="d0e414"></a><h3>File names</h3><p>ajc accepts source files with either the <tt>.java</tt> |
| extension or the <tt>.aj</tt> extension. We normally use |
| <tt>.java</tt> 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 <tt>.aj</tt> extension for those files.</p><p>We'd like to discourage other means of mechanical distinction such as |
| naming conventions or sub-packages in favor of the <tt>.aj</tt> |
| extension.</p><p> |
| |
| <div class="itemizedlist"><ul><li><a name="d0e439"></a>Filename conventions are hard to enforce and lead to awkward names |
| for your aspects. Instead of <tt>TracingAspect.java</tt> we |
| recommend using <tt>Tracing.aj</tt> (or just |
| <tt>Tracing.java</tt>) instead.</li><li><a name="d0e450"></a>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 <tt>aspects</tt> we recommend using the |
| <tt>.aj</tt> extension and including these files in your existing |
| packages instead.</li></ul></div> |
| </p></div><div class="refsect2"><a name="d0e459"></a><h3>Compatibility</h3><p> |
| AspectJ is a compatible extension to the Java programming language. The |
| AspectJ compiler adheres to the <a href="http://java.sun.com/docs/books/jls/index.html" target="_top"> <i>The Java Language Specfication, Second |
| Edition</i></a> and to the <a href="http://java.sun.com/docs/books/vmspec/index.html" target="_top"><i>The Java Virtual Machine Specification, Second |
| Edition</i></a> and runs on any Java 2 compatible |
| platform. The code it generates runs on any Java 1.1 or later |
| compatible platform.</p></div><div class="refsect2"><a name="d0e473"></a><h3>Examples</h3><div class="example"><p><a name="simpleexample"></a><b>Example 1. A simple example</b></p><p>Compile two files:</p><pre class="programlisting"> |
| ajc HelloWorld.java Trace.java |
| </pre></div><div class="example"><p><a name="exampleusingargfile"></a><b>Example 2. An example using -argfile/@</b></p><p> |
| 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 <tt>sources.lst</tt> |
| contains absolute and relative files and @-references: |
| <p><pre class="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</pre></p> |
| |
| Compile the files using either the -argfile or @ form: |
| |
| <p><pre class="programlisting"> |
| ajc -argfile sources.lst |
| ajc @sources.lst</pre></p> |
| </p><p> |
| Argfiles are also supported by jikes and javac, so you |
| can use the files in hybrid builds. However, the support varies: |
| </p><p> |
| <div class="itemizedlist"><ul><li><a name="d0e504"></a>Only ajc accepts command-line options</li><li><a name="d0e506"></a>Jikes and Javac do not accept internal @argfile references. |
| </li><li><a name="d0e508"></a>Jikes and Javac only accept the @file form on the command line.</li></ul></div> |
| </p></div><div class="example"><p><a name="examplebytecode"></a><b>Example 3. An example using -injars and -aspectpath</b></p><p>Bytecode weaving using -injars: |
| AspectJ 1.1 supports weaving from input zip or jar files containing |
| class files. Using input jars is like compiling the corresponding |
| source files, and all binaries are emitted to output. Although |
| Java-compliant compilers may differ in their output, ajc should |
| take as input any class files produced by javac, jikes, eclipse, |
| and, of course, ajc. Aspects included in -injars will be woven into |
| like other .class files, but they will specify any crosscutting |
| code (i.e., they will not be woven into other types). To use |
| aspects in their binary form to specify crosscutting, |
| see -aspectpath below. |
| </p><p>Aspect libraries using -aspectpath: |
| AspectJ 1.1 supports weaving from read-only libraries containing |
| aspects. Like input jars, they affect all input; unlike input |
| jars, they themselves are not affected or emitted as output. |
| Sources compiled with aspect libraries must be run with the same |
| aspect libraries on their classpath. |
| </p><p>The following example builds the tracing example in a |
| command-line environment; it creates a read-only aspect library, |
| compiles some classes for use as input bytecode, and |
| compiles the classes and other sources with the aspect library. |
| </p><p>The tracing example is in the AspectJ distribution |
| ({aspectj}/doc/examples/tracing). This uses the following files: |
| </p><p><pre class="programlisting"> |
| aspectj1.1/ |
| bin/ |
| ajc |
| lib/ |
| aspectjrt.jar |
| examples/ |
| tracing/ |
| Circle.java |
| ExampleMain.java |
| lib/ |
| AbstractTrace.java |
| TraceMyClasses.java |
| notrace.lst |
| Square.java |
| tracelib.lst |
| tracev3.lst |
| TwoDShape.java |
| version3/ |
| Trace.java |
| TraceMyClasses.java |
| </pre></p><p>Below, the path separator is taken as ";", but file separators |
| are "/". All commands are on one line. Adjust paths and |
| commands to your environment as needed. |
| |
| </p><p>Setup the path, classpath, and current directory: |
| |
| <p><pre class="programlisting"> |
| cd examples |
| export ajrt=../lib/aspectjrt.jar |
| export CLASSPATH="$ajrt" |
| export PATH="../bin:$PATH" |
| </pre></p> |
| |
| </p><p>Build a read-only tracing library: |
| <p><pre class="programlisting"> |
| ajc -argfile tracing/tracelib.lst -outjar tracelib.jar |
| </pre></p> |
| |
| </p><p>Build the application with tracing in one step: |
| |
| <p><pre class="programlisting"> |
| ajc -aspectpath tracelib.jar -argfile tracing/notrace.lst -outjar tracedapp.jar |
| </pre></p> |
| |
| </p><p>Run the application with tracing: |
| |
| <p><pre class="programlisting"> |
| java -classpath "$ajrt;tracedapp.jar;tracelib.jar" tracing.ExampleMain |
| </pre></p> |
| |
| </p><p>Build the application with tracing from binaries in two steps: |
| <li><p><a name="d0e553"></a> |
| (a) Build the application classes (using javac for demonstration's sake): |
| <p><pre class="programlisting"> |
| mkdir classes |
| javac -d classes tracing/*.java |
| jar cfM app.jar -C classes . |
| </pre></p> |
| |
| </p></li> |
| <li><p><a name="d0e561"></a> |
| (b) Build the application with tracing: |
| <p><pre class="programlisting"> |
| ajc -injars app.jar -aspectpath tracelib.jar -outjar tracedapp.jar |
| </pre></p> |
| </p></li> |
| |
| </p><p>Run the application with tracing (same as above): |
| |
| <p><pre class="programlisting"> |
| java -classpath "$ajrt;tracedapp.jar;tracelib.jar" tracing.ExampleMain |
| </pre></p> |
| |
| </p><p>Run the application without tracing: |
| |
| <p><pre class="programlisting"> |
| java -classpath "app.jar" tracing.ExampleMain |
| </pre></p> |
| </p></div></div><div class="refsect2"><a name="d0e581"></a><h3>The AspectJ compiler API</h3><p>The AspectJ compiler is implemented completely in Java and can be |
| called as a Java class. The only interface that should be considered |
| public are the public methods in <tt>org.aspectj.tools.ajc.Main</tt>. |
| E.g., <tt>main(String[] args)</tt> takes the |
| the standard <b>ajc</b> command line arguments. |
| This means that an alternative way to run the |
| compiler is </p><div class="cmdsynopsis" id="d0e595"><a name="d0e595"></a><tt><tt>java org.aspectj.tools.ajc.Main</tt></tt> [<i><tt>option...</tt></i>] [<i><tt>file...</tt></i>]</div><p>To access compiler messages programmatically, use the methods |
| <tt>setHolder(IMessageHolder holder)</tt> and/or |
| <tt>run(String[] args, IMessageHolder holder)</tt>. |
| </p></div><div class="refsect2"><a name="d0e613"></a><h3>Stack Traces and the SourceFile attribute</h3><p>Unlike traditional java compilers, the AspectJ compiler may in |
| certain cases generate classfiles from multiple source files. |
| Unfortunately, the original Java class file format does not support |
| multiple |
| SourceFile attributes. 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. |
| When the Java VM generates stack traces, it uses this attribute |
| to specify the source file. |
| </p><p>(The AspectJ 1.0 compiler also supports the .class file extensions of JSR-45. |
| These permit compliant debuggers (such as jdb in Java 1.4.1) to identify |
| the right file and line even given many source files for a single class. |
| JSR-45 support is planned for ajc in AspectJ 1.1, but is not in the initial |
| release. To get fully debuggable .class files, use the -XnoInline option.) |
| </p><p>Probably the only time you may see this format is when you view |
| stack traces, where you may encounter traces of the format |
| </p><pre class="programlisting"> |
| java.lang.NullPointerException |
| at Main.new$constructor_call37(Main.java;SynchAspect.java[1k]:1030) |
| </pre><p>where instead of the usual |
| </p><pre class="programlisting"> |
| File:LineNumber |
| </pre><p>format, you see |
| </p><pre class="programlisting"> |
| File0;File1[Number1];File2[Number2] ... :LineNumber |
| </pre><p>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). |
| </p><p> 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. |
| </p><p> 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. |
| </p><p>In a class file that comes from only a single source file, the AspectJ |
| compiler generates SourceFile attributes consistent with |
| traditional Java compilers. |
| </p></div></div></div><div class="refentry"><h1 class="title"><a name="d0e645"></a>ajdoc</h1><div class="refnamediv"><a name="d0e646"></a><h2>Name</h2>ajdoc — generate HTML API documentation, including crosscutting structure (early-access) |
| </div><div class="refsynopsisdiv"><a name="d0e651"></a><h2>Synopsis</h2><div class="cmdsynopsis" id="d0e652"><a name="d0e652"></a><tt>ajdoc</tt> [ |
| -bootclasspath <i><tt>classpathlist</tt></i> |
| ] [ |
| -classpath <i><tt>classpathlist</tt></i> |
| ] [-d <i><tt>path</tt></i>] [-help] [-package] [-protected] [-private] [-public] [-overview <i><tt>overviewFile</tt></i>] [ |
| -sourcepath <i><tt>sourcepathlist</tt></i> |
| ] [-verbose] [-version] [<i><tt>sourcefiles...</tt></i> | <i><tt>packages...</tt></i> | @<i><tt>file...</tt></i> | -argfile <i><tt>file...</tt></i>]</div></div><div class="refsect1"><a name="d0e707"></a><h2>Description</h2><p> |
| Similar to <b>javadoc</b>, |
| <b>ajdoc</b> renders HTML documentation for pointcuts, |
| advice, and inter-type declarations, as |
| well as the Java constructs that Javadoc renders. |
| <b>ajdoc</b> 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. |
| </p><p> |
| To run <b>ajdoc</b>, use one of the scripts in the |
| AspectJ <tt>bin</tt> directory. |
| The <b>ajdoc</b> implementation builds on Sun's <b>javadoc</b> |
| command line tool, and you use it in the same way with many of |
| the same options |
| (<b>javadoc</b> options are not documented here; |
| for more information on <b>javadoc</b> usage, see the |
| <a href="http://java.sun.com/j2se/javadoc/" target="_top">Javadoc homepage</a>.) |
| </p><p> |
| As with <b>ajc</b> (but unlike <b>javadoc</b>), |
| you pass <b>ajdoc</b> all your aspect source files |
| and any files containing types affected by the aspects; |
| it's often easiest to just pass all the <tt>.java</tt> files |
| in your system. |
| Unlike <b>ajc</b>, |
| <b>ajdoc</b> will try to find package sources using the |
| specified sourcepath if you list packages on the command line. |
| </p><p> |
| To provide an argfile listing the source files, you can use |
| use the same argfile (<tt>@filename</tt>) conventions |
| as with <b>ajc</b>. |
| For example, the following documents all the source files listed |
| in <tt>argfile.lst</tt>, sending the output to |
| the <tt>docDir</tt> output directory. |
| |
| <pre class="programlisting">ajdoc -d docDir @argfile.lst</pre> |
| |
| See the <a href="#ajc" title="Description">ajc documentation</a> |
| for details on the text file format. |
| </p><p> |
| <b>ajdoc</b> currently requires the |
| <tt>tools.jar</tt> from J2SE 1.3 to be on the classpath. |
| Normally the scripts set this up, assuming that your <tt>JAVA_HOME</tt> |
| 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. |
| </p></div><div class="refsect1"><a name="d0e795"></a><h2>Known limitations</h2><p> |
| <b>ajdoc</b> documents advice and pointcut members, shows where advice applies and |
| links affected members back to the advice. |
| It currently does not document or add structural links for any inter-type declarations or other declare forms. |
| </p></div><div class="refsect1"><a name="d0e803"></a><h2>Examples</h2><div class="example"><p><a name="ajdocdocumentingspacewar"></a><b>Example 4. Documenting Spacewar</b></p><div class="itemizedlist"><ul><li><p><a name="d0e811"></a> |
| Change into the <tt>examples</tt> directory. |
| </p></li><li><p><a name="d0e817"></a> |
| Type <b><tt>mkdir doc</tt></b> to create the |
| destination directory for the documentation. |
| </p></li><li><p><a name="d0e823"></a> |
| Type <b><tt>ajdoc -private -d doc spacewar |
| coordination</tt></b> to generate the documentation. |
| </p><div class="itemizedlist"><ul><li><p><a name="d0e830"></a> |
| (Use <tt>-private</tt> to get all members, since |
| may of the interesting ones in spacewar are not public.) |
| </p></li></ul></div></li><li><p><a name="d0e836"></a> |
| Type <b><tt>ajdoc -private -d doc @spacewar/demo.lst</tt></b> |
| to use the argfile associated with Spacewar. |
| </p></li><li><p><a name="d0e842"></a> |
| To view the documentation, open the file <tt>index.html</tt> |
| in the <tt>doc</tt> directory using a web browser. |
| </p></li></ul></div></div></div></div></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="ajbrowser"></a>Chapter 1. AspectJ Browser</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#ajbrowser-intro"></a></dt><dt><a href="#d0e886">Building Programs</a></dt><dd><dl><dt><a href="#d0e889">Build Configurations</a></dt><dt><a href="#d0e920">Compiling a Program Build Configuration</a></dt></dl></dd><dt><a href="#d0e944">Navigating Program Structure</a></dt><dd><dl><dt><a href="#d0e951">Example: Exploring the "Spacewar" sample code </a></dt></dl></dd><dt><a href="#d0e1077">Running Programs</a></dt><dt><a href="#ajbrowser-problems">Isolating problems running the AspectJ browser</a></dt><dd><dl><dt><a href="#ajbrowser-knownProblems">Known issues with the AspectJ browser</a></dt><dt><a href="#ajbrowser-limitations">Limitations</a></dt><dt><a href="#ajbrowser-feedback">AspectJ Browser questions and bugs</a></dt></dl></dd></dl></div><div class="sect1"><a name="ajbrowser-intro"></a><div class="titlepage"></div><p> |
| AJBrowser presents a GUI for compiling programs with ajc |
| and navigating crosscutting structure. |
| </p><p> |
| The AspectJ Browser can edit program source files, |
| compile using the AspectJ compiler <tt>ajc</tt> |
| run a program, |
| and graphically navigate the program's |
| crosscutting structure. |
| For more information on <tt>ajc</tt>, |
| see <a href="#ajc-ref">The ajc Command-line Reference</a>. |
| |
| |
| </p><p> |
| Launch the browser from the command line either |
| by typing "ajbrowser" to invoke the script in |
| <tt>{aspectj}/bin</tt> |
| (if AspectJ is installed correctly) |
| or by using the |
| <tt>aspectjtools.jar</tt> directly, |
| and specifying no arguments or some number of |
| build configuration files |
| (suffix <tt>.lst</tt>): |
| <pre class="programlisting"> |
| java -jar aspectj1.1/lib/aspectjtools.jar aspectj1.1/doc/examples/spacewar/debug.lst |
| </pre> |
| </p></div><div class="sect1"><a name="d0e886"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="d0e886"></a>Building Programs</h2></div></div><div class="sect2"><a name="d0e889"></a><div class="titlepage"><div><h3 class="title"><a name="d0e889"></a>Build Configurations</h3></div></div><p>A build configuration is a set of files to compile for a |
| program (and optionally some additional compile arguments). |
| Because <tt>ajc</tt> requires all sources to be specified |
| (at least using the <tt>-sourceroots</tt> option), |
| most users create <tt>.lst</tt> files that list |
| the files to compile (one argument per line, globbing |
| permitted - for more details, see <a href="#ajc-ref">The ajc Command-line Reference</a>). |
| </p><p> |
| To work with a particular program, select the |
| corresponding ".lst" build configuration file |
| from the GUI using the File menu, "open" item, |
| or by using the |
| "Open Build Configuration" button |
| (<span class="inlinemediaobject"><img src="openConfig.gif"></span>). |
| |
| You can populate the build list from the command line |
| by passing any number of ".lst" paths. |
| (However, if you pass in any non-".lst" arguments, |
| it will run the command-line compiler directly.) |
| </p><p> |
| To switch between build configurations, |
| select, add, or remove them |
| using the corresponding toolbar buttons. |
| </p><p>Global build options are stored in an |
| <tt>.ajbrowser</tt> file in your HOME directory. |
| Edit these from the GUI by clicking the "Options" button |
| or selecting the Tools menu item "Options...". |
| This is how to set classpath, aspectpath, etc. |
| </p><p>The following sections walk through a build. |
| </p></div><div class="sect2"><a name="d0e920"></a><div class="titlepage"><div><h3 class="title"><a name="d0e920"></a>Compiling a Program Build Configuration</h3></div></div><p> |
| To compile click the "Build" button |
| (<span class="inlinemediaobject"><img src="build.gif"></span>), or |
| or use the tools menu. |
| </p><p>To build using AspectJ 1.1's incremental mode, |
| click the <tt>incremental compile</tt> checkbox in |
| the <tt>AspectJ Build Options</tt> tab |
| of the <tt>Options</tt> dialog. |
| Once in incremental mode, you can force a full rebuild |
| by holding the shift key down when selecting the |
| build menu item or button. |
| </p><p> |
| You may select |
| from different build configurations in the GUI |
| (see label 1 in the graphic below). |
| (If you get classpath or other errors, set up the |
| global build options as described above.) |
| </p><img src="ajbrowser-building.gif"></div></div><div class="sect1"><a name="d0e944"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="d0e944"></a>Navigating Program Structure</h2></div></div><p> |
| Select nodes in the program structure by clicking them (see 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. |
| </p><img src="ajbrowser-building.gif"><div class="sect2"><a name="d0e951"></a><div class="titlepage"><div><h3 class="title"><a name="d0e951"></a>Example: Exploring the "Spacewar" sample code </h3></div></div><p> |
| <div class="itemizedlist"><ul><li><p><a name="d0e957"></a>Launch <tt>ajbrowser</tt></p></li><li><a name="d0e962"></a> Choose "File -> Open" or click the "Open Build |
| Configuration" button |
| (<span class="inlinemediaobject"><img src="openConfig.gif"></span>) and select the configuration file for debugging |
| the spacewar example, in |
| <tt>examples/spacewar/debug.lst</tt>. |
| </li><li><p><a name="d0e971"></a>Click the "Build" button (<span class="inlinemediaobject"><img src="build.gif"></span>) 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. |
| </p><p>Note: If you did not set up your classpath, 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 |
| (<span class="inlinemediaobject"><img src="browseroptions.gif"></span>). Click the <tt>Build Options</tt> tab |
| to view the Build Paths pane. Edit the classpath entry to use your |
| install location. For example, if you ran from the base Aspectj |
| directory, the classpath need only include |
| <tt>lib/aspectjrt.jar</tt> (though the browser may populate |
| the classpath with the bootclasspath and classpath initially.) |
| Be sure to use the |
| <tt>lib/aspectjrt.jar</tt> that came with the browser. |
| </p><p> |
| <img src="ajbrowser-options.gif"> |
| </p></li><li><p><a name="d0e998"></a>Different structure views: The structure tree at the |
| left can display different orderings and granularity for structure: |
| |
| <div class="itemizedlist"><ul><li><a name="d0e1002"></a> The package hierarchy view shows the traditional hierarchy |
| of package, class, and members. </li><li><a name="d0e1004"></a> The inheritance view shows the hierarchy from topmost |
| parent classes through subclasses to members. </li><li><a name="d0e1006"></a> The crosscutting view shows the aspect members |
| and the code they affect. </li><li><a name="d0e1008"></a> Additional buttons in the pane can be used to change the |
| granularity and filter out items. |
| </li></ul></div> |
| |
| </p><p>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.) |
| </p></li><li><p><a name="d0e1013"></a>When working with aspects, it helps to be able to navigate |
| between different program elements: |
| </p><div class="itemizedlist"><ul><li><p><a name="d0e1017"></a>When looking at a method, find the advice that |
| affects it. </p></li><li><p><a name="d0e1020"></a>When looking at a pointcut, find the advice that |
| uses it. </p></li><li><p><a name="d0e1023"></a>When looking at advice, find what it advises - |
| e.g., method calls or executions, initializers, etc. |
| </p></li><li><p><a name="d0e1026"></a>When looking at a type, find any aspects that |
| declare members or supertypes of the type, or |
| vice-versa. |
| </p></li></ul></div><p>You can view the advice on a particular method using the |
| default, hierarchical view. Navigate to the tree item for |
| <tt>spacewar.Registry.register(SpaceObject)</tt> |
| in the <tt>debug.lst</tt> config file. Now, in |
| the lower, file view, you can see and navigate to the advice |
| using the subtree whose parent is the <tt>method |
| affected by</tt> relation. |
| </p><p>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 |
| <tt>spacewar.Debug.allConstructorsCut()</tt> in |
| the <tt>debug.lst</tt> config file. You can see |
| and navigate to the advice that uses the pointcut using the |
| <tt>pointcut used by</tt> relation. |
| </p><p>As an example of seeing the methods affected by advice, |
| while still in the same view, select the first |
| <tt>before</tt> advice in |
| <tt>spacewar.Debug</tt>. It has relation |
| sub-trees for both <tt>uses pointcut</tt> and |
| <tt>affects constructions</tt>. The |
| <tt>affects</tt> relations will list different |
| kinds of join points - constructor or method calls, etc. |
| </p><p>Note that the AspectJ browser can only display |
| static structure (whether hierarchical or crosscutting). |
| That means that dynamicly-determined pointcuts (like |
| <tt>cflow(pointcut)</tt>) |
| will not be shown as picking out static points in |
| source code. Displayable pointcuts roughly correspond |
| to those that can be used in a |
| <tt>declare error</tt> statement. |
| </p></li></ul></div> |
| </p></div></div><div class="sect1"><a name="d0e1077"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="d0e1077"></a>Running Programs</h2></div></div><p> |
| The browser supports a limited form of running compiled programs. |
| To run programs that have been built, click the run button |
| or select one of the run menu items in the project menu. |
| You can run in the same VM or spawn a new process; |
| the latter is generally better for GUI programs. |
| </p><p>Both require that any classpath you set be specified |
| using platform-specific paths and path separators (the |
| compiler might be more tolerant). |
| Output and error streams will be |
| merged into the streams of the browser (using separate |
| threads, so it may take a few seconds for the pipe |
| threads to gain control.) Errors should |
| be detected and displayed in a dialog. |
| </p><p> |
| The GUI does not support killing a running program, |
| so if your program might hang, |
| be sure to save your files since you may need to |
| kill the browser itself to kill its child processes. |
| </p></div><div class="sect1"><a name="ajbrowser-problems"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="ajbrowser-problems"></a>Isolating problems running the AspectJ browser</h2></div></div><p> |
| If you have problems with the browser not solved by the documentation, |
| please try to see if you have the same problems when running ajc |
| directly on the command line. |
| </p><div class="itemizedlist"><ul><li><p><a name="d0e1092"></a> |
| If the problem occurs on the command line also, then the problem |
| is not in the browser. |
| (It may be in the compiler; please send bug reports.) |
| </p></li><li><p><a name="d0e1095"></a> |
| If the problem does not occur on the command line, then it may |
| lie in the parameters you are supplying in the build options. |
| </p></li><li><p><a name="d0e1098"></a> |
| If the build options look correct and the problem only occurs |
| when building from the browser, then please submit a bug report. |
| </p></li></ul></div><div class="sect2"><a name="ajbrowser-knownProblems"></a><div class="titlepage"><div><h3 class="title"><a name="ajbrowser-knownProblems"></a>Known issues with the AspectJ browser</h3></div></div><p> |
| For the most up-to-date information on known problems, |
| see the |
| <a href="http://bugs.eclipse.org/bugs" target="_top">bug database</a> |
| for unresolved |
| <a href="http://bugs.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=Compiler&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED" target="_top"> |
| compiler bugs |
| </a> or |
| <a href="http://bugs.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=IDE&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED" target="_top"> |
| IDE bugs |
| </a>. |
| </p><p> |
| <div class="itemizedlist"><ul><li><p><a name="d0e1118"></a> |
| Memory and forking: Users email most about the browser task running |
| out of memory. |
| This is not a problem with the browser; some compiles take a lot of |
| memory, often more than similar compiles using javac. |
| The browser does not support forking, so the only solution is to |
| edit the java command line or script that launches the browser |
| to add memory. |
| </p></li><li><p><a name="d0e1121"></a> |
| Editing build configuration files: this is not currently supported. |
| </p></li><li><p><a name="d0e1124"></a> |
| The structure model is incomplete after incremental compiles. |
| To get a complete structure model requires a full build. |
| </p></li><li><p><a name="d0e1127"></a> |
| If you change the output directory, you must do a |
| full build. |
| </p></li></ul></div> |
| </p></div><div class="sect2"><a name="ajbrowser-limitations"></a><div class="titlepage"><div><h3 class="title"><a name="ajbrowser-limitations"></a>Limitations</h3></div></div><p> |
| <div class="itemizedlist"><ul><li><p><a name="d0e1137"></a> |
| The AJBrowser expects the package and directory structure to match. If they do not |
| it will be unable to browse to the corresponding file. |
| </p></li><li><p><a name="d0e1140"></a> |
| The "Run" feature launches applications in the same VM. As a result, if a Swing application |
| is disposed the AJBrowser will be disposed as well. |
| </p></li></ul></div> |
| </p></div><div class="sect2"><a name="ajbrowser-feedback"></a><div class="titlepage"><div><h3 class="title"><a name="ajbrowser-feedback"></a>AspectJ Browser questions and bugs</h3></div></div><p> |
| You can send email to |
| <a href="mailto:aspectj-users@dev.eclipse.org" target="_top"> |
| aspectj-users@dev.eclipse.org</a>. |
| (Do join the list to participate!) |
| We also welcome any bug reports, patches, and feature requests; |
| you can submit them to the bug database at |
| <a href="http://bugs.eclipse.org/bugs" target="_top"> |
| http://bugs.eclipse.org/bugs</a> |
| using the AspectJ product and IDE component. |
| </p></div></div></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="antTasks"></a>Chapter 2. AspectJ Ant Tasks</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#antTasks-intro">Introduction</a></dt><dt><a href="#antTasks-install">Installing Ant Tasks</a></dt><dt><a href="#antTasks-iajc">AjcTask (iajc)</a></dt><dd><dl><dt><a href="#antTasks-iajc-options">AjcTask (iajc) Options</a></dt><dt><a href="#antTasks-nested-includes">AjcTask matching parameters specified as nested elements</a></dt><dt><a href="#antTasks-iajc-paths">AjcTask Path-like Structures</a></dt><dt><a href="#antTasks-iajc-sample">Sample of iajc task</a></dt><dt><a href="#antTasks-iajc-uptodate">Avoiding clean compiles</a></dt><dt><a href="#d0e1878">Programmatically handling compiler messages</a></dt></dl></dd><dt><a href="#antTasks-adapter">Ajc11CompilerAdapter (javac)</a></dt><dd><dl><dt><a href="#antTasks-adapter-sample">Sample of compiler adapter</a></dt><dt><a href="#antTasks-adapter-options">Compiler adapter compilerarg options</a></dt></dl></dd><dt><a href="#antTasks-ajc">Ajc10 (ajc)</a></dt><dd><dl><dt><a href="#antTasks-ajc-options">Ajc10 (ajc) Options</a></dt><dt><a href="#antTasks-ajc-nested">Ajc10 parameters specified as nested elements</a></dt><dt><a href="#antTasks-ajc-sample">Sample of ajc task</a></dt></dl></dd><dt><a href="#antTasks-problems">Isolating problems running the Ant tasks</a></dt><dd><dl><dt><a href="#antTasks-knownProblems">Known issues with the Ant tasks</a></dt><dt><a href="#antTasks-feedback">Ant task questions and bugs</a></dt></dl></dd></dl></div><div class="sect1"><a name="antTasks-intro"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="antTasks-intro"></a>Introduction</h2></div></div><p> |
| AspectJ contains a compiler, <tt>ajc</tt>, |
| that can be run from Ant. |
| Included in the <tt>aspectjtools.jar</tt> |
| are Ant binaries to support three |
| ways of running the compiler: |
| <div class="orderedlist"><ol type="1"><li><p><a name="d0e1175"></a> |
| <a href="#antTasks-iajc">AjcTask (iajc)</a>, |
| a task to run the AspectJ post-1.1 compiler, |
| which supports all the eclipse and ajc options, including incremental mode. |
| </p></li><li><p><a name="d0e1180"></a> |
| <a href="#antTasks-adapter">Ajc11CompilerAdapter (javac)</a>, |
| an adapter class to run the new compiler using Javac tasks |
| by setting the build.compiler property |
| </p></li><li><p><a name="d0e1185"></a> |
| <a href="#antTasks-ajc">Ajc10 (ajc)</a>, |
| a task to run build scripts compatible with the AspectJ 1.0 tasks |
| </p></li></ol></div> |
| </p><p> |
| This describes how to install and use the tasks and the adapter. |
| For an example Ant script, see |
| <a href="../examples/build.xml" target="_top">examples/build.xml</a>. |
| </p></div><div class="sect1"><a name="antTasks-install"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="antTasks-install"></a>Installing Ant Tasks</h2></div></div><p> |
| Install Jakarta Ant 1.5.1: |
| Please see the official Jakarta Ant website for more information |
| and the 1.5.1 distribution. This release is source-compatible |
| with Ant 1.3 and Ant 1.4, but the task sources must be |
| compiled with those versions of the Ant libraries to be used |
| under those versions of Ant. |
| Sources are available under the Common Public License v. 1.0 |
| at <a href="http://eclipse.org/aspectj" target="_top">http://eclipse.org/aspectj</a>. |
| </p><p> |
| In Ant, third-party tasks can be declared using a taskdef entry in |
| the build script, to identify the name and classes. |
| When declaring a task, include the |
| <tt>aspectjtools.jar</tt> either in the |
| taskdef classpath or in ${ANT_HOME}/lib where it will be added |
| to the system class path by the ant script. |
| You may specify the task script names directly, |
| or use the "resource" attribute to specify the default names: |
| </p><pre class="programlisting"> |
| |
| <taskdef |
| resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties"/> |
| |
| </pre><p> |
| The current resource file retains the name "ajc" for the Ajc10 task, |
| and uses "iajc" for the AspectJ post-1.1 task. |
| </p><p> |
| For more information on using Ant, please refer to Jakarta's |
| documentation on integrating user-defined Ant tasks into builds. |
| </p></div><div class="sect1"><a name="antTasks-iajc"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="antTasks-iajc"></a>AjcTask (iajc)</h2></div></div><p> |
| This task uses the AspectJ post-1.1 compiler ajc. |
| The AspectJ compiler can be used like Javac to compile Java sources, |
| but it can also compile AspectJ sources or weave binary aspects |
| with Java bytecode. |
| It can run in normal "batch" mode or in an "incremental" mode, |
| where it only recompiles files it has to revisit. |
| For more information on ajc, see <a href="#ajc-ref">The ajc Command-line Reference</a>. |
| Unlike Javac or the Javac Ant task, this task always compiles the |
| specified files since aspects can apply to other (updated) files. |
| For a workaround, see <a href="#antTasks-iajc-uptodate">Avoiding clean compiles</a>. |
| </p><p> |
| Beyond the normal ajc compiler options, this task also supports |
| an experimental option for an incremental "tag" file, and it |
| can copy resources from source directories or |
| input jars to the output jar or directory. |
| </p><p> |
| This task is named iajc to avoid conflict with the 1.0 task ajc. |
| </p><div class="sect2"><a name="antTasks-iajc-options"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-iajc-options"></a>AjcTask (iajc) Options</h3></div></div><p> |
| The following tables list the supported parameters. |
| For any parameter specified as a Path, a single path can be |
| specified directly as an attribute, |
| multiple paths can be specified using a nested element of |
| the same name, and a common path can be reused by defining it as a |
| global and passing the id to the corresponding {name}ref attribute. |
| See <a href="#antTasks-iajc-paths">Path</a> |
| below for more details. |
| </p><p> |
| Most attributes and nested elements are optional. |
| The compiler requires that the same version of |
| <tt>aspectjrt.jar</tt> |
| be specified on the classpath, and that some sources be |
| be specified |
| (using one or more of |
| <tt>sourceroots</tt>, |
| <tt>injars</tt>, |
| <tt>inpath</tt>, |
| <tt>argfiles</tt>, and/or |
| <tt>srcdir</tt> (with patterns)). |
| When in incremental mode, only |
| <tt>sourceroots</tt> may be specified. |
| </p><p>Boolean parameters default to <tt>false</tt> |
| unless otherwise stated. |
| </p><div class="table"><p><a name="d0e1266"></a><b>Table 2.1. AjcTask (iajc) options for specifying sources</b></p><table summary="AjcTask (iajc) options for specifying sources" border="1"><colgroup><col><col></colgroup><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody><tr><td><p>argfiles, argfilesRef |
| (<a href="#antTasks-iajc-paths">Path</a>) |
| </p></td><td><p> |
| An argument file contains a list of arguments read by the compiler. |
| Each line is read into one element of the argument array |
| and may include another argfile by reference. |
| </p></td></tr><tr><td><p>sourceRoots, sourceRootsRef |
| (<a href="#antTasks-iajc-paths">Path</a>) |
| </p></td><td><p> |
| Directories containing source files (ending with .java or .aj) to compile. |
| </p></td></tr><tr><td><p>srcdir |
| (<a href="#antTasks-iajc-paths">Path</a>) |
| </p></td><td><p> |
| Base directory of sources to compile, assuming there are |
| <a href="#antTasks-nested-includes">nested matches</a>. |
| This approach uses the Ant process |
| for matching .java files and is not compatible with incremental |
| mode. Unless using filters to limit the sources included, |
| use sourceroots instead. |
| </p></td></tr><tr><td><p>injars, injarsRef |
| (<a href="#antTasks-iajc-paths">Path</a>) |
| </p></td><td><p> |
| Deprecated - use inpath instead. |
| Read .class files for bytecode weaving |
| from zip files (only). |
| </p></td></tr><tr><td><p>inpath, inpathRef |
| (<a href="#antTasks-iajc-paths">Path</a>) |
| </p></td><td><p> |
| Read .class files for bytecode weaving |
| from directories or zip files (like classpath). |
| </p></td></tr><tr><td><p>classpath, classpathRef |
| (<a href="#antTasks-iajc-paths">Path</a>) |
| </p></td><td><p> |
| The classpath used by the sources being compiled. |
| When compiling aspects, include the same version of the |
| <tt>aspectjrt.jar</tt>. |
| </p></td></tr><tr><td><p>bootclasspath, bootclasspathRef |
| (<a href="#antTasks-iajc-paths">Path</a>) |
| </p></td><td><p> |
| The bootclasspath specifies types to use instead of the |
| invoking VM's when seeking types during compilation. |
| </p></td></tr><tr><td><p>extDirs, extDirsRef |
| (<a href="#antTasks-iajc-paths">Path</a>) |
| </p></td><td><p> |
| The extension directories to use instead of those in the |
| invoking VM when seeking types during compilation. |
| </p></td></tr><tr><td><p>aspectPath, aspectPathRef |
| (<a href="#antTasks-iajc-paths">Path</a>) |
| </p></td><td><p> |
| Similar to classpath, aspectpath contains read-only, |
| binary aspect libraries that are woven into sources |
| but not included in the output. |
| <tt>aspectpath</tt> accepts jar/zip files |
| (but, unlike classpath, not directories). |
| </p></td></tr></tbody></table></div><div class="table"><p><a name="d0e1366"></a><b>Table 2.2. AjcTask (iajc) options for specifying output</b></p><table summary="AjcTask (iajc) options for specifying output" border="1"><colgroup><col><col></colgroup><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody><tr><td><p>destDir |
| </p></td><td><p> |
| The directory in which to place the generated class files. |
| Only one of <tt>destDir</tt> and |
| <tt>outJar</tt> may be set. |
| </p></td></tr><tr><td><p>outJar |
| </p></td><td><p> |
| The zip file in which to place the generated output class files. |
| Only one of <tt>destDir</tt> and |
| <tt>outJar</tt> may be set. |
| </p></td></tr><tr><td><p>copyInjars |
| </p></td><td><p> |
| If true, copy all non-.class files from input jar(s) |
| to the output jar or destination directory after the |
| compile (or incremental compile) completes. |
| In forked mode, this copies only after the process |
| completes, not after incremental compiles. |
| </p></td></tr><tr><td><p>sourceRootCopyFilter |
| </p></td><td><p> |
| When set, copy all files from the sourceroot directories to the output jar |
| or destination directory except those specified in the filter pattern. |
| The pattern should be compatible with an Ant fileset excludes filter; |
| when using this, most developers pass |
| <tt>**/CVS/*,**/*.java</tt> to exclude any CVS directories |
| or source files. |
| </p></td></tr></tbody></table></div><div class="table"><p><a name="d0e1420"></a><b>Table 2.3. AjcTask (iajc) options for specifying compiler behavior</b></p><table summary="AjcTask (iajc) options for specifying compiler behavior" border="1"><colgroup><col><col></colgroup><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody><tr><td><p>fork |
| </p></td><td><p> |
| Run process in another VM. |
| This gets the forking classpath either explicitly |
| from a <tt>forkclasspath</tt> entry |
| or by searching the task or system/Ant classpath for the |
| first readable file with a name of the form |
| <tt>aspectj{-}tools{.*}.jar</tt>. |
| When forking you can specify the amount of memory used |
| with <tt>maxmem</tt>. |
| Fork cannot be used in incremental mode, |
| unless using a tag file. |
| </p></td></tr><tr><td><p>forkclasspath, forkclasspathRef |
| (<a href="#antTasks-iajc-paths">Path</a>) |
| </p></td><td><p> |
| Specify the classpath to use for the compiler when forking. |
| </p></td></tr><tr><td><p>maxmem |
| </p></td><td><p> |
| The maximum memory to use for the new VM when fork is true. |
| Values should have the same form as accepted by the VM, e.g., "128m". |
| </p></td></tr><tr><td><p>incremental |
| </p></td><td><p> |
| incremental mode: Build once, then recompile only required source |
| files when user provides input. |
| Requires that source files be specified only using |
| <tt>sourceroots</tt>. |
| Incompatible with forking. |
| </p></td></tr><tr><td><p>tagfile |
| </p></td><td><p> |
| incremental mode: Build once, then recompile only required source |
| files when the tag file is updated, finally exiting when tag file |
| is deleted. |
| Requires that source files be specified only using |
| <tt>sourceroots</tt>. |
| </p></td></tr><tr><td><p>X |
| </p></td><td><p> |
| Set experimental option(s), using comma-separated list of accepted options |
| (unlisted here). Options should not contain the leading X. |
| XLint options should be specified using the xlint... entries. |
| </p></td></tr><tr><td><p>Xnoweave |
| </p></td><td><p> |
| Experimental option to produce binaries that can only be used as input |
| for the <tt>-injars</tt> or <tt>-inpath</tt> option. |
| Usually aspects are compiled normally and put on the |
| <tt>aspectpath</tt>. |
| </p></td></tr></tbody></table></div><div class="table"><p><a name="d0e1506"></a><b>Table 2.4. AjcTask (iajc) options for specifying compiler side-effects and messages</b></p><table summary="AjcTask (iajc) options for specifying compiler side-effects and messages" border="1"><colgroup><col><col></colgroup><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody><tr><td><p>emacssym |
| </p></td><td><p> |
| If true, emit <tt>.ajesym</tt> symbol files for Emacs support. |
| </p></td></tr><tr><td><p>verbose |
| </p></td><td><p> |
| If true, emit compiler status messages during the compile. |
| </p></td></tr><tr><td><p>Xlistfileargs |
| </p></td><td><p> |
| If true, emit list of file arguments during |
| the compile (but behaves now like verbose). |
| </p></td></tr><tr><td><p>version |
| </p></td><td><p> |
| If true, do not compile - just print AspectJ version. |
| </p></td></tr><tr><td><p>help |
| </p></td><td><p> |
| If true, just print help for the command-line compiler. |
| </p></td></tr><tr><td><p>Xlintwarnings |
| </p></td><td><p> |
| Same as <tt>xlint:warning</tt>: |
| if true, set default level of all language |
| usage messages to warning. |
| </p></td></tr><tr><td><p>Xlint |
| </p></td><td><p> |
| Specify default level of all language usage messages to one of |
| [<tt>error warning ignore</tt>]. |
| </p></td></tr><tr><td><p>XlintFile |
| </p></td><td><p> |
| Specify property file containing <tt>name:level</tt> associations |
| setting level for language messages emitted during compilation. |
| Any levels set override the default associations in |
| <tt>org/aspectj/weaver/XLintDefault.properties</tt>. |
| </p></td></tr><tr><td><p>failonerror |
| </p></td><td><p> |
| If true, throw BuildException to halt build if there |
| are any compiler errors. |
| If false, continue notwithstanding compile errors. |
| Defaults to <tt>true</tt>. |
| </p></td></tr><tr><td><p>messageHolderClass |
| </p></td><td><p> |
| Specify a class to use as the message holder for the compile process. |
| The entry must be a fully-qualified name of a class resolveable from |
| the task classpath complying with the |
| <tt>org.aspectj.bridge.IMessageHolder</tt> interface |
| and having a public no-argument constructor. |
| </p></td></tr><tr><td><p>showWeaveInfo |
| </p></td><td><p> |
| If true, emit weaver messages. |
| Defaults to <tt>false</tt>. |
| </p></td></tr></tbody></table></div><div class="table"><p><a name="d0e1618"></a><b>Table 2.5. AjcTask (iajc) options for specifying Eclipse compiler options</b></p><table summary="AjcTask (iajc) options for specifying Eclipse compiler options" border="1"><colgroup><col><col></colgroup><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody><tr><td><p>nowarn |
| </p></td><td><p> |
| If true, same as <tt>warn:none</tt>. |
| </p></td></tr><tr><td><p>deprecation |
| </p></td><td><p> |
| If true, same as <tt>warn:deprecation</tt> |
| </p></td></tr><tr><td><p>warn |
| </p></td><td><p> |
| One or more comma-separated warning specifications from |
| [<tt>constructorName packageDefaultMethod deprecation, |
| maskedCatchBlocks unusedLocals unusedArguments, |
| unusedImports syntheticAccess assertIdentifier</tt>]. |
| </p></td></tr><tr><td><p>debug |
| </p></td><td><p> |
| If true, same as <tt>debug:lines,vars,source</tt> |
| </p></td></tr><tr><td><p>debugLevel |
| </p></td><td><p> |
| One or more comma-separated debug specifications from |
| [<tt>lines vars source</tt>]. |
| </p></td></tr><tr><td><p>PreserveAllLocals |
| </p></td><td><p> |
| If true, code gen preserves all local variables (for debug purposes). |
| </p></td></tr><tr><td><p>noimporterror |
| </p></td><td><p> |
| If true, emit no errors for unresolved imports. |
| </p></td></tr><tr><td><p>referenceinfo |
| </p></td><td><p> |
| If true, compute reference info. |
| </p></td></tr><tr><td><p>log |
| </p></td><td><p> |
| File to log compiler messages to. |
| </p></td></tr><tr><td><p>encoding |
| </p></td><td><p>Default source encoding format |
| (per-file encoding not supported in Ant tasks). |
| </p></td></tr><tr><td><p>proceedOnError |
| </p></td><td><p> |
| If true, keep compiling after errors encountered, |
| dumping class files with problem methods. |
| </p></td></tr><tr><td><p>progress |
| </p></td><td><p> |
| If true, emit progress (requires log). |
| </p></td></tr><tr><td><p>time |
| </p></td><td><p> |
| If true, display speed information. |
| </p></td></tr><tr><td><p>target |
| </p></td><td><p> |
| Specify target class file format as one of |
| [<tt>1.1 1.2</tt>]. |
| Defaults to 1.1 class file. |
| </p></td></tr><tr><td><p>source |
| </p></td><td><p> |
| Set source compliance level to one of |
| [<tt>1.3 1.4</tt>] |
| (e.g., in 1.4 no assert identifiers |
| and no import from default package). |
| Defaults to 1.3 compliance level. |
| </p></td></tr><tr><td><p>source |
| </p></td><td><p> |
| Set source assertion mode to one of |
| [<tt>1.3 1.4</tt>]. |
| Default depends on compliance mode. |
| </p></td></tr></tbody></table></div></div><div class="sect2"><a name="antTasks-nested-includes"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-nested-includes"></a>AjcTask matching parameters specified as nested elements</h3></div></div><p> |
| This task forms an implicit FileSet and supports all attributes of |
| <tt><fileset></tt> (dir becomes srcdir) as well as |
| the nested |
| <tt><include></tt>, |
| <tt><exclude></tt>, and |
| <tt><patternset></tt> elements. |
| These can be used to specify source files. |
| However, it is better to use <tt>sourceroots</tt> |
| to specify source directories unless using filters to exclude |
| some files from compilation. |
| </p></div><div class="sect2"><a name="antTasks-iajc-paths"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-iajc-paths"></a>AjcTask Path-like Structures</h3></div></div><p> |
| Some parameters are path-like structures containing one or more |
| elements; these are |
| <tt>sourceroots</tt>, |
| <tt>argfiles</tt>, |
| <tt>injars</tt>, |
| <tt>inpath</tt>, |
| <tt>classpath</tt>, |
| <tt>bootclasspath</tt>, |
| <tt>forkclasspath</tt>, and |
| <tt>aspectpath</tt>. |
| In all cases, these may be specified as nested elements, something |
| like this: |
| </p><pre class="programlisting"> |
| |
| <iajc {attributes..} /> |
| <{name}> |
| <pathelement path="{first-location}"/> |
| <pathelement path="{second-location}"/> |
| ... |
| <{name}> |
| ... |
| </iajc> |
| |
| </pre><p> |
| As with other Path-like structures, they may be defined elsewhere |
| and specified using the refid attribute: |
| </p><pre class="programlisting"> |
| |
| <path id="aspect.path"> |
| <pathelement path="${home}/lib/persist.jar"/> |
| <pathelement path="${home}/lib/trace.jar"/> |
| </path> |
| ... |
| <iajc {attributes..} /> |
| <aspectpath refid="aspect.path"/> |
| ... |
| </iajc> |
| |
| </pre><p> |
| The task also supports an attribute <tt>{name}ref</tt> |
| for each such parameter. E.g., for <tt>aspectpath</tt>: |
| </p><pre class="programlisting"> |
| |
| <iajc {attributes..} aspectpathref="aspect.path"/> |
| |
| </pre></div><div class="sect2"><a name="antTasks-iajc-sample"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-iajc-sample"></a>Sample of iajc task</h3></div></div><p> |
| A minimal build script defines the task and runs it, specifying the sources: |
| </p><pre class="programlisting"> |
| |
| <project name="simple-example" default="compile" > |
| <taskdef |
| resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties"> |
| <classpath> |
| <pathelement location="${home.dir}/tools/aspectj/lib/aspectjtools.jar"/> |
| </classpath> |
| </taskdef> |
| |
| <target name="compile" > |
| <iajc sourceroots="${home.dir}/ec/project/src" |
| classpath="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/> |
| </target> |
| </project> |
| |
| </pre><p> |
| Below is script with most everything in it. The compile process... |
| </p><div class="orderedlist"><ol type="1"><li><p><a name="d0e1841"></a>Runs in incremental mode, recompiling when the user hits return; |
| </p></li><li><p><a name="d0e1844"></a>Reads all the sources from two directories; |
| </p></li><li><p><a name="d0e1847"></a>Reads extrinsic module bytecode as input jar for weaving; |
| </p></li><li><p><a name="d0e1850"></a>Uses a binary aspect library for persistence; |
| </p></li><li><p><a name="d0e1853"></a>Outputs to an application jar; and |
| </p></li><li><p><a name="d0e1856"></a>Copies resources from the input jar and source directories into the application jar. |
| </p></li></ol></div><p> |
| When this target is built, the compiler will build once and then |
| wait for input from the user. |
| Messages are printed as usual. |
| When the user has quit, then this runs the application. |
| </p><pre class="programlisting"> |
| |
| <target name="build-test" > |
| <iajc outjar="${home.dir}/output/application.jar" |
| injars="${home.dir}/build/module.jar" |
| copyInjars="true" |
| sourceRootCopyFilter="**/CVS/*,**/*.java" |
| incremental="true" > |
| <sourceroots> |
| <pathelement location="${home.dir}/ec/project/src"/> |
| <pathelement location="${home.dir}/ec/project/testsrc"/> |
| </sourceroots> |
| <aspectpath> |
| <pathelement location="${home.dir}/ec/int/persist.jar"/> |
| </aspectpath> |
| <classpath> |
| <pathelement location="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/> |
| </classpath> |
| </iajc> |
| |
| <java classname="org.smart.app.Main"> |
| <classpath> |
| <pathelement location="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/> |
| <pathelement location="${home.dir}/ec/int/persist.jar"/> |
| <pathelement location="${home.dir}/output/application.jar"/> |
| </classpath> |
| </java> |
| </target> |
| |
| </pre><p> |
| For an example of a build script, |
| see <a href="../examples/build.xml" target="_top"> |
| ../examples/build.xml</a>. |
| </p></div><div class="sect2"><a name="antTasks-iajc-uptodate"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-iajc-uptodate"></a>Avoiding clean compiles</h3></div></div><p> |
| Unlike javac, the ajc compiler always processes all input because |
| new aspects can apply to updated classes and vice-versa. |
| However, in the case where no files have been updated, there |
| is no reason to recompile sources. One way to implement that |
| is with an explicit dependency check using the uptodate task: |
| </p><pre class="programlisting"> |
| |
| <target name="check.aspects.jar"> |
| <uptodate property="build.unnecessary" |
| targetfile="${aspects.module-jar}" > |
| <srcfiles dir="${src1}" includes="**/*.aj"/> |
| <srcfiles dir="${src2}/" includes="**/*.aj"/> |
| </uptodate> |
| </target> |
| |
| <target name="compile.aspects" depends="prepare,check.aspects.jar" |
| unless="build.unnecessary"> |
| <iajc ... |
| |
| </pre><p> |
| When using this technique, be careful to verify that binary |
| input jars are themselves up-to-date after they would have been |
| modified by any build commands. |
| </p></div><div class="sect2"><a name="d0e1878"></a><div class="titlepage"><div><h3 class="title"><a name="d0e1878"></a>Programmatically handling compiler messages</h3></div></div><p> |
| Users may specify a message holder to which the compiler will pass |
| all messages as they are generated. This will override all of the |
| normal message printing, but does not prevent the task from failing |
| if exceptions were thrown or if failonerror is true and the compiler |
| detected errors in the sources. |
| </p><p> |
| Handling messages programmatically could be useful when using the |
| compiler to verify code. If aspects consist of declare [error|warning], |
| then the compiler can act to detect invariants in the code being |
| processed. For code to compare expected and actual messages, see the |
| AspectJ testing module (which is not included in the binary |
| distribution). |
| </p></div></div><div class="sect1"><a name="antTasks-adapter"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="antTasks-adapter"></a>Ajc11CompilerAdapter (javac)</h2></div></div><p> |
| This CompilerAdapter can be used in javac task calls by setting the |
| <tt>build.compiler</tt> property. |
| This enables users to to easily switch between the Javac and AspectJ |
| compilers. |
| However, the Javac task's pruning of source files prevents the |
| adapter from doing a correct compile in some cases, |
| so use AjcTask where possible. |
| </p><div class="sect2"><a name="antTasks-adapter-sample"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-adapter-sample"></a>Sample of compiler adapter</h3></div></div><p> |
| To build using the adapter, put the |
| <tt>aspectjtools.jar</tt> |
| on the system/ant classpath (e.g., in |
| <tt>${ANT_HOME}/lib</tt>) |
| and define the |
| <tt>build.compiler</tt> |
| property as the fully-qualified name of the class, |
| <tt>org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter</tt>. |
| </p><p> |
| The AspectJ compiler should run for any compile using the Javac task |
| (for options, see the Ant documentation for the Javac task). |
| For example, the call below passes all out-of-date source files in the |
| <tt>src/org/aspectj</tt> subdirectories to the |
| <tt>ajc</tt> command along with the destination directory: |
| </p><pre class="programlisting"> |
| |
| -- command: |
| |
| cp aspectj1.1/lib/aspectjtools.jar ant/lib |
| ant/bin/ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter ... |
| |
| -- task invocation in the build script: |
| |
| <javac srcdir="src" includes="org/aspectj/**/*.java" destdir="dest" /> |
| |
| </pre><p> |
| To pass ajc-specific arguments, use a compilerarg entry. |
| </p><pre class="programlisting"> |
| |
| -- command |
| |
| Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter |
| |
| -- build script |
| |
| <property name="ajc" |
| value="org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter"/> |
| |
| <javac srcdir="src" includes="org/aspectj/**/*.java" destdir="dest" > |
| <compilerarg compiler="${ajc}" line="-argfile src/args.lst"/> |
| <javac/> |
| |
| </pre></div><div class="sect2"><a name="antTasks-adapter-options"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-adapter-options"></a>Compiler adapter compilerarg options</h3></div></div><p> |
| The adapter supports any ajc command-line option passed using compilerarg, |
| as well as the following options available only in AjcTask. |
| Find more details on the following options in <a href="#antTasks-iajc">AjcTask (iajc)</a>. |
| </p><div class="itemizedlist"><ul><li><p><a name="d0e1933"></a> |
| <tt>-Xmaxmem</tt>: |
| set maximum memory for forking (also settable in javac). |
| </p></li><li><p><a name="d0e1939"></a> |
| <tt>-Xlistfileargs</tt>: |
| list file arguments (also settable in javac). |
| </p></li><li><p><a name="d0e1945"></a> |
| <tt>-Xfailonerror</tt>: |
| throw BuildException on compiler error (also settable in javac). |
| </p></li><li><p><a name="d0e1951"></a> |
| <tt>-Xmessageholderclass</tt>: |
| specify fully-qualified name of class to use as the message holder. |
| </p></li><li><p><a name="d0e1957"></a> |
| <tt>-Xcopyinjars</tt>: |
| copy resources from any input jars to output |
| (default behavior since 1.1.1) |
| </p></li><li><p><a name="d0e1963"></a> |
| <tt>-Xsourcerootcopyfilter {filter}</tt>: |
| copy resources from source directories to output (minus files specified in filter) |
| </p></li><li><p><a name="d0e1969"></a> |
| <tt>-Xtagfile {file}</tt>: |
| use file to control incremental compilation |
| </p></li><li><p><a name="d0e1975"></a> |
| <tt>-Xsrcdir {dir}</tt>: |
| add to list of ajc source roots (all source files will be included). |
| </p></li></ul></div><p> |
| Special considerations when using Javac and compilerarg: |
| </p><div class="itemizedlist"><ul><li><p><a name="d0e1984"></a> |
| The names above may differ slightly from what you might expect |
| from AjcTask; use these forms when specifying compilerarg. |
| </p></li></ul></div><div class="itemizedlist"><ul><li><p><a name="d0e1988"></a> |
| By default the adapter will mimic the Javac task's copying of resource |
| files by specifying |
| <tt>"**/CVS/*,**/*.java,**/*.aj"</tt> |
| for the sourceroot copy filter. |
| To change this behavior, supply your own value |
| (e.g., <tt>"**/*"</tt> to copy nothing). |
| </p></li></ul></div><div class="itemizedlist"><ul><li><p><a name="d0e1998"></a> |
| Warning - define the system property |
| <tt>build.compiler.clean</tt> to compile all files, |
| when available. |
| Javac prunes the source file list of "up-to-date" source files |
| based on the timestamps of corresponding .class files, |
| and will not compile if no sources are out of date. |
| This is wrong for ajc which requires all the files for each compile |
| and which may refer indirectly to sources using argument files. |
| </p><p> |
| To work around this, set the global property |
| <tt>build.compiler.clean</tt>. |
| This tells the compiler adapter to delete all .class files |
| in the destination directory and re-execute the javac |
| task so javac can recalculate the list of source files. e.g., |
| </p><pre class="programlisting"> |
| |
| Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter |
| -Dbuild.compiler.clean=anything ... |
| |
| </pre><p> |
| Caveats to consider when using this global |
| <tt>build.compiler.clean</tt> property: |
| </p><div class="orderedlist"><ol type="1"><li><p><a name="d0e2017"></a> |
| If javac believes there are no out-of-date source files, |
| then the adapter is never called and cannot clean up, |
| and the "compile" will appear to complete successfully |
| though it did nothing. |
| </p></li><li><p><a name="d0e2020"></a> |
| Cleaning will makes stepwise build processes fail if |
| they depend on the results of the prior compilation being |
| in the same directory, since cleaning deletes all .class files. |
| </p></li><li><p><a name="d0e2023"></a> |
| This clean process only permits one compile process at a |
| time for each destination directory because it tracks |
| recursion by writing a tag file to the destination directory. |
| </p></li><li><p><a name="d0e2026"></a> |
| When running incrementally, the clean happens only before |
| the initial compile. |
| </p></li></ol></div></li></ul></div></div></div><div class="sect1"><a name="antTasks-ajc"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="antTasks-ajc"></a>Ajc10 (ajc)</h2></div></div><p> |
| This task handles the same arguments as those used by the AspectJ 1.0 task. |
| This should permit those with existing build scripts using the Ajc Ant |
| task to continue using the same scripts when compiling with 1.1. |
| This will list any use of options no longer supported in 1.1 |
| (e.g., <tt>lenient, strict, workingdir, preprocess, usejavac</tt>,...), |
| and does not provide access to the new features of AspectJ 1.1. |
| (Developers using AspectJ 1.1 only should upgrade their scripts |
| to use AjcTask instead. This will not work for AspectJ 1.2 or later.) |
| </p><div class="sect2"><a name="antTasks-ajc-options"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-ajc-options"></a>Ajc10 (ajc) Options</h3></div></div><p> |
| </p><p> |
| Most attributes and nested elements are optional. |
| The compiler requires that the same version of |
| <tt>aspectjrt.jar</tt> |
| be specified on the classpath, and that some sources be |
| be specified |
| (using one or more of |
| <tt>argfiles</tt> and |
| <tt>srcdir</tt> (with patterns)). |
| </p><p>Boolean parameters default to <tt>false</tt> |
| unless otherwise stated. |
| </p><div class="table"><p><a name="d0e2060"></a><b>Table 2.6. AjcTask (ajc) options for specifying sources</b></p><table summary="AjcTask (ajc) options for specifying sources" border="1"><colgroup><col><col></colgroup><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody><tr><td><p>srcdir |
| </p></td><td><p> |
| The base directory of the java files. |
| See |
| </p></td></tr><tr><td><p>destdir |
| </p></td><td><p> |
| The target directory for the output .class files |
| </p></td></tr><tr><td><p>includes |
| </p></td><td><p> |
| Comma-separated list of patterns of files that must be included. |
| No files are included when omitted. |
| </p></td></tr><tr><td><p>includesfile |
| </p></td><td><p> |
| The path to a file containing include patterns. |
| </p></td></tr><tr><td><p>excludes |
| </p></td><td><p> |
| Comma-separated list of patterns of files that must be excluded. |
| No files (except default excludes) are excluded when omitted. |
| </p></td></tr><tr><td><p>excludesfile |
| </p></td><td><p> |
| The path to a file containing exclude patterns. |
| </p></td></tr><tr><td><p>defaultexcludes |
| </p></td><td><p> |
| If true, then default excludes are used. |
| Default excludes are used when omitted |
| (i.e., defaults to <tt>true</tt>). |
| </p></td></tr><tr><td><p>classpath, classpathref |
| </p></td><td><p> |
| The classpath to use, |
| optionally given as a reference to a classpath Path |
| element defined elsewhere. |
| </p></td></tr><tr><td><p>bootclasspath, bootclasspathref |
| </p></td><td><p> |
| The bootclasspath to use, |
| optionally given as a reference to a bootclasspath Path |
| element defined elsewhere. |
| </p></td></tr><tr><td><p>extdirs |
| </p></td><td><p> |
| Paths to directories containting installed extensions. |
| </p></td></tr><tr><td><p>debug |
| </p></td><td><p> |
| If true, emit debug info in the .class files. |
| </p></td></tr><tr><td><p>deprecation |
| </p></td><td><p> |
| If true, emit messages about use of deprecated API. |
| </p></td></tr><tr><td><p>verbose |
| </p></td><td><p> |
| Emit compiler status messages during the compile. |
| </p></td></tr><tr><td><p>version |
| </p></td><td><p> |
| Emit version information and quit. |
| </p></td></tr><tr><td><p>failonerror |
| </p></td><td><p> |
| If true, throw BuildException to halt build if there |
| are any compiler errors. |
| If false, continue notwithstanding compile errors. |
| Defaults to <tt>true</tt>. |
| </p></td></tr><tr><td><p>source |
| </p></td><td><p> |
| Value of -source option - ignored unless <tt>1.4</tt>. |
| </p></td></tr></tbody></table></div><div class="table"><p><a name="d0e2192"></a><b>Table 2.7. Parameters ignored by the old ajc taskdef, |
| but now supported or buggy</b></p><table summary="Parameters ignored by the old ajc taskdef, 
 but now supported or buggy" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Attribute</th><th>Description</th><th>Supported?</th></tr></thead><tbody><tr><td><p>encoding |
| </p></td><td><p>Default encoding of source files. |
| </p></td><td><p>yes |
| </p></td></tr><tr><td><p>optimize |
| </p></td><td><p> |
| Whether source should be compiled with optimization. |
| </p></td><td><p>yes? |
| </p></td></tr><tr><td><p>target |
| </p></td><td><p> |
| Generate class files for specific VM version, one of |
| [<tt>1.1 1.2</tt>]. |
| </p></td><td><p>yes |
| </p></td></tr><tr><td><p>depend |
| </p></td><td><p> |
| Enables dependency-tracking. |
| </p></td><td><p>no |
| </p></td></tr><tr><td><p>includeAntRuntime |
| </p></td><td><p> |
| Whether to include the Ant run-time libraries. |
| </p></td><td><p>no |
| </p></td></tr><tr><td><p>includeJavaRuntime |
| </p></td><td><p> |
| Whether to include the run-time libraries from the executing VM. |
| </p></td><td><p>no |
| </p></td></tr><tr><td><p>threads |
| </p></td><td><p>Multi-threaded compilation |
| </p></td><td><p>no |
| </p></td></tr></tbody></table></div><p> |
| The following table shows that many of the unique parameters in |
| AspectJ 1.0 are no longer supported. |
| </p><div class="table"><p><a name="d0e2280"></a><b>Table 2.8. Parameters unique to ajc</b></p><table summary="Parameters unique to ajc" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody><tr><td><p>X |
| </p></td><td><p> |
| comma-delimited list of extended (-X...) options, |
| entered without -X (e.g., |
| <tt>X="lint"</tt> for -Xlint). |
| </p></td></tr><tr><td><p>emacssym |
| </p></td><td><p> |
| Generate symbols for Emacs IDE support. |
| </p></td></tr><tr><td><p>argfiles |
| </p></td><td><p> |
| A comma-delimited list of argfiles that contain a line-delimited |
| list of source file paths (absolute or relative to the argfile). |
| </p></td></tr></tbody></table></div><div class="sect3"><a name="d0e2315"></a><div class="titlepage"><div><h4 class="title"><a name="d0e2315"></a>argfiles - argument list files</h4></div></div><p> |
| An argument file is a file (usually <tt>{file}.lst</tt>) |
| containing a list of source file paths |
| (absolute or relative to the argfile). |
| You can use it to specify all source files to be compiled, |
| which ajc requires to avoid searching every possible source file |
| in the source path when building aspects. |
| If you specify an argfile to the ajc task, it will not include all |
| files in any specified source directory (which is the default |
| behavior for the Javac task when no includes are specified). |
| Conversely, if you specify excludes, they will be removed from |
| the list of files compiled even if they were specified |
| in an argument file. |
| </p><p> |
| The compiler also accepts arguments that are not source files, |
| but the IDE support for such files varies, and Javac does not |
| support them. Be sure to include exactly one argument on each line. |
| </p></div></div><div class="sect2"><a name="antTasks-ajc-nested"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-ajc-nested"></a>Ajc10 parameters specified as nested elements</h3></div></div><p> |
| This task forms an implicit FileSet and supports all attributes of |
| <tt><fileset></tt> (dir becomes srcdir) as well as |
| the nested |
| <tt><include></tt>, |
| <tt><exclude></tt>, and |
| <tt><patternset></tt> elements. |
| These can be used to specify source files. |
| </p><p> |
| <tt>ajc</tt>'s |
| <tt>srcdir</tt>, |
| <tt>classpath</tt>, |
| <tt>bootclasspath</tt>, |
| <tt>extdirs</tt>, and |
| <tt>jvmarg</tt> |
| attributes are path-like structures and can also be set via nested |
| <tt><src></tt>, |
| <tt><classpath></tt>, |
| <tt><bootclasspath></tt>, |
| <tt><extdirs></tt>, and |
| <tt><jvmargs></tt> elements, respectively. |
| </p></div><div class="sect2"><a name="antTasks-ajc-sample"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-ajc-sample"></a>Sample of ajc task</h3></div></div><p> |
| Following is a declaration for the ajc task and a sample invocation |
| that uses the ajc compiler to compile the files listed in |
| <tt>default.lst</tt> into the dest dir: |
| </p><pre class="programlisting"> |
| |
| <project name="example" default="compile" > |
| <taskdef name="ajc" |
| classname="org.aspectj.tools.ant.taskdefs.Ajc10" > |
| <!-- declare classes needed to run the tasks and tools --> |
| <classpath> |
| <pathelement location="${home.dir}/tools/aspectj/lib/aspectjtools.jar"/> |
| </classpath> |
| </taskdef> |
| |
| <target name="compile" > |
| <mkdir dir="dest" /> |
| <ajc destdir="dest" argfiles="default.lst" > |
| <!-- declare classes needed to compile the target files --> |
| <classpath> |
| <pathelement location="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/> |
| </classpath> |
| </ajc> |
| </target> |
| </project> |
| |
| </pre><p> |
| This build script snippet |
| </p><pre class="programlisting"> |
| |
| <ajc srcdir="${src}" |
| destdir="${build}" |
| argfiles="demo.lst" |
| /> |
| |
| </pre><p> |
| compiles all .java files specified in the demo.lst and stores the .class files in the ${build} directory. Unlike the Javac task, the includes attribute is empty by default, so only those files specified in demo.lst are included. |
| </p><p> |
| This next example |
| </p><pre class="programlisting"> |
| |
| <ajc srcdir="${src}" |
| destdir="${build}" |
| includes="spacewar/*,coordination/*" |
| excludes="spacewar/Debug.java" |
| /> |
| |
| </pre><p> |
| compiles .java files under the <tt>${src}</tt> directory in the |
| spacewar and coordination packages, and stores the .class files in the |
| <tt>${build}</tt> directory. |
| All source files under spacewar/ and coordination/ are used, except Debug.java. |
| </p><p> |
| See <a href="../examples/build.xml" target="_top">../examples/build.xml</a> |
| for an example build script. |
| </p></div></div><div class="sect1"><a name="antTasks-problems"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="antTasks-problems"></a>Isolating problems running the Ant tasks</h2></div></div><p> |
| If you have problems with the tasks not solved by the documentation, |
| please try to see if you have the same problems when running ajc |
| directly on the command line. |
| </p><div class="itemizedlist"><ul><li><p><a name="d0e2417"></a> |
| If the problem occurs on the command line also, then the problem |
| is not in the task. |
| (It may be in the tools; please send bug reports.) |
| </p></li><li><p><a name="d0e2420"></a> |
| If the problem does not occur on the command line, then it may |
| lie in the parameters you are supplying in Ant or in the task's |
| handling of them. |
| </p></li><li><p><a name="d0e2423"></a> |
| If the build script looks correct and the problem only occurs when |
| building from Ant, then please send a report |
| (including your build file, if possible). |
| </p></li></ul></div><div class="sect2"><a name="antTasks-knownProblems"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-knownProblems"></a>Known issues with the Ant tasks</h3></div></div><p> |
| For the most up-to-date information on known problems, |
| see the |
| <a href="http://bugs.eclipse.org/bugs" target="_top">bug database</a> |
| for unresolved |
| <a href="http://bugs.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=Compiler&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED" target="_top"> |
| compiler bugs |
| </a> or |
| <a href="http://bugs.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=Ant&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED" target="_top"> |
| taskdef bugs |
| </a>. |
| </p><p> |
| When running Ant build scripts under Eclipse 2.x variants, you will get a |
| VerifyError because the Eclipse Ant support fails to isolate the Ant runtime |
| properly. To run in this context, set up iajc to fork (and use forkclasspath). |
| Eclipse 3.0 will fork Ant processes to avoid problems like this. |
| </p><p> |
| Memory and forking: Users email most often about the ajc task running |
| out of memory. |
| This is not a problem with the task; some compiles take a lot of |
| memory, often more than similar compiles using javac. |
| </p><p> |
| Forking is now supported in both the |
| <a href="#antTasks-adapter">Ajc11CompilerAdapter (javac)</a> and |
| <a href="#antTasks-iajc">AjcTask (iajc)</a>, |
| and you can set the maximum memory available. |
| You can also not fork and increase the memory available to Ant |
| (see the Ant documentation, searching for ANT_OPTS, |
| the variable they use in their scripts to pass VM options, |
| e.g., ANT_OPTS=-Xmx128m). |
| </p></div><div class="sect2"><a name="antTasks-feedback"></a><div class="titlepage"><div><h3 class="title"><a name="antTasks-feedback"></a>Ant task questions and bugs</h3></div></div><p> |
| For questions, you can send email to |
| <a href="mailto:aspectj-users@dev.eclipse.org" target="_top"> |
| aspectj-users@dev.eclipse.org</a>. |
| (Do join the list to participate!) |
| We also welcome any bug reports, patches, and features; |
| you can submit them to the bug database at |
| <a href="http://bugs.eclipse.org/bugs" target="_top"> |
| http://bugs.eclipse.org/bugs</a> |
| using the AspectJ product and Ant component. |
| </p></div></div></div></div></body></html> |
