| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>AjcTask (iajc)</title><meta name="generator" content="DocBook XSL Stylesheets V1.44"><link rel="home" href="index.html" title="The AspectJtm Development Environment Guide"><link rel="up" href="antTasks.html" title="Chapter 2. AspectJ Ant Tasks"><link rel="previous" href="antTasks-install.html" title="Installing Ant Tasks"><link rel="next" href="antTasks-adapter.html" title="Ajc11CompilerAdapter (javac)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">AjcTask (iajc)</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="antTasks-install.html">Prev</a> </td><th width="60%" align="center">Chapter 2. AspectJ Ant Tasks</th><td width="20%" align="right"> <a accesskey="n" href="antTasks-adapter.html">Next</a></td></tr></table><hr></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.html">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.html#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.html#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.html#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.html#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.html#antTasks-iajc-paths">Path</a>) |
| </p></td><td><p> |
| Base directory of sources to compile, assuming there are |
| <a href="antTasks-iajc.html#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.html#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.html#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.html#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.html#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.html#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.html#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.html#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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="antTasks-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="antTasks-adapter.html">Next</a></td></tr><tr><td width="40%" align="left">Installing Ant Tasks </td><td width="20%" align="center"><a accesskey="u" href="antTasks.html">Up</a></td><td width="40%" align="right"> Ajc11CompilerAdapter (javac)</td></tr></table></div></body></html> |
