AspectJ Ant Tasks
Introduction
AspectJ contains a compiler, ajc,
that can be run from Ant.
Included in the aspectjtools.jar
are Ant binaries to support three
ways of running the compiler:
,
a task to run the new AspectJ 1.1 compiler,
which supports all the eclipse and ajc options, including incremental mode.
,
an adapter class to run the new compiler using Javac tasks
by setting the build.compiler property
,
a task to run build scripts compatible with the AspectJ 1.0 tasks
This describes how to install and use the tasks and the adapter.
For an example Ant script, see
examples/build.xml.
Installing Ant Tasks
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 http://eclipse.org/aspectj.
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
aspectjtools.jar 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:
]]>
The current resource file retains the name "ajc" for the Ajc10 task,
and uses "iajc" for the AspectJ 1.1 task.
For more information on using Ant, please refer to Jakarta's
documentation on integrating user-defined Ant tasks into builds.
AjcTask (iajc)
This task uses the AspectJ 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 .
Beyond the normal ajc 1.1 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.
This task is named iajc to avoid conflict with the 1.0 task ajc.
AjcTask (iajc) Options
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
below for more details.
Most attributes and nested elements are optional.
The compiler requires that the same version of
aspectjrt.jar
be specified on the classpath, and that some sources be
be specified
(using one or more of
sourceroots
injars
argfiles and
srcdir (with patterns)).
When in incremental mode, only
sourceroots may be specified.
Boolean parameters default to false
unless otherwise stated.
AjcTask (iajc) options for specifying sources
Attribute
Description
argfiles, argfilesRef
()
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.
sourceRoots, sourceRootsRef
()
Directories containing source files (ending with .java or .aj) to compile.
srcdir
()
Base directory of sources to compile, assuming there are
.
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.
injars, injarsRef
()
Input zip files with .class file entries for bytecode weaving.
classpath, classpathRef
()
The classpath used by the sources being compiled.
When compiling aspects, include the same version of the
aspectjrt.jar.
bootclasspath, bootclasspathRef
()
The bootclasspath specifies types to use instead of the
invoking VM's when seeking types during compilation.
extDirs, extDirsRef
()
The extension directories to use instead of those in the
invoking VM when seeking types during compilation.
aspectPath, aspectPathRef
()
Similar to classpath, aspectpath contains read-only,
binary aspect libraries that are woven into sources
but not included in the output.
aspectpath accepts jar/zip files
(but, unlike classpath, not directories).
AjcTask (iajc) options for specifying output
Attribute
Description
destDir
The directory in which to place the generated class files.
Only one of destDir and
outJar may be set.
outJar
The zip file in which to place the generated output class files.
Only one of destDir and
outJar may be set.
copyInjars
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.
sourceRootCopyFilter
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
**/CVS/*,**/*.java to exclude any CVS directories
or source files.
AjcTask (iajc) options for specifying compiler behavior
Attribute
Description
fork
Run process in another VM.
This gets the forking classpath either explicitly
from a forkclasspath entry
or by searching the task or system/Ant classpath for the
first readable file with a name of the form
aspectj{-}tools{.*}.jar.
When forking you can specify the amount of memory used
with maxmem.
Fork cannot be used in incremental mode,
unless using a tag file.
forkclasspath, forkclasspathRef
()
Specify the classpath to use for the compiler when forking.
maxmem
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".
incremental
incremental mode: Build once, then recompile only required source
files when user provides input.
Requires that source files be specified only using
sourceroots.
Incompatible with forking.
tagfile
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
sourceroots.
X
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.
Xnoweave
Experimental option to produce binaries that can only be used as input
for the -injars option.
Usually aspects are compiled normally and put on the
aspectpath.
AjcTask (iajc) options for specifying compiler side-effects and messages
Attribute
Description
emacssym
If true, emit .ajesym symbol files for Emacs support.
verbose
If true, emit compiler status messages during the compile.
Xlistfileargs
If true, emit list of file arguments during
the compile (but behaves now like verbose).
version
If true, do not compile - just print AspectJ version.
help
If true, just print help for the command-line compiler.
Xlintwarnings
Same as xlint:warning:
if true, set default level of all language
usage messages to warning.
Xlint
Specify default level of all language usage messages to one of
[error warning ignore].
XlintFile
Specify property file containing name:level associations
setting level for language messages emitted during compilation.
Any levels set override the default associations in
org/aspectj/weaver/XLintDefault.properties.
failonerror
If true, throw BuildException to halt build if there
are any compiler errors.
If false, continue notwithstanding compile errors.
Defaults to true.
messageHolderClass
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
org.aspectj.bridge.IMessageHolder interface
and having a public no-argument constructor.
AjcTask (iajc) options for specifying Eclipse compiler options
Attribute
Description
nowarn
If true, same as warn:none.
deprecation
If true, same as warn:deprecation
warn
One or more comma-separated warning specifications from
[constructorName packageDefaultMethod deprecation,
maskedCatchBlocks unusedLocals unusedArguments,
unusedImports syntheticAccess assertIdentifier].
debug
If true, same as debug:lines,vars,source
debugLevel
One or more comma-separated debug specifications from
[lines vars source].
PreserveAllLocals
If true, code gen preserves all local variables (for debug purposes).
noimporterror
If true, emit no errors for unresolved imports.
referenceinfo
If true, compute reference info.
log
File to log compiler messages to.
encoding
Default source encoding format
(per-file encoding not supported in Ant tasks).
proceedOnError
If true, keep compiling after errors encountered,
dumping class files with problem methods.
progress
If true, emit progress (requires log).
time
If true, display speed information.
target
Specify target class file format as one of
[1.1 1.2].
Defaults to 1.1 class file.
source
Set source compliance level to one of
[1.3 1.4]
(e.g., in 1.4 no assert identifiers
and no import from default package).
Defaults to 1.3 compliance level.
source
Set source assertion mode to one of
[1.3 1.4].
Default depends on compliance mode.
AjcTask matching parameters specified as nested elements
This task forms an implicit FileSet and supports all attributes of
<fileset> (dir becomes srcdir) as well as
the nested
<include>,
<exclude>, and
<patternset> elements.
These can be used to specify source files.
However, it is better to use sourceroots
to specify source directories unless using filters to exclude
some files from compilation.
AjcTask Path-like Structures
Some parameters are path-like structures containing one or more
elements; these are
sourceroots,
argfiles,
injars,
classpath,
bootclasspath,
forkclasspath, and
aspectpath.
In all cases, these may be specified as nested elements, something
like this:
<{name}>
...
<{name}>
...
]]>
As with other Path-like structures, they may be defined elsewhere
and specified using the refid attribute:
...
...
]]>
The task also supports an attribute {name}ref
for each such parameter. E.g., for aspectpath:
]]>
Sample of iajc task
A minimal build script defines the task and runs it, specifying the sources:
]]>
Below is script with most everything in it. The compile process...
Runs in incremental mode, recompiling when the user hits return;
Reads all the sources from two directories;
Reads extrinsic module bytecode as input jar for weaving;
Uses a binary aspect library for persistence;
Outputs to an application jar; and
Copies resources from the input jar and source directories into the application jar.
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.
]]>
For an example of a build script,
see
../examples/build.xml.
Programmatically handling compiler messages
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.
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).
Ajc11CompilerAdapter (javac)
This CompilerAdapter can be used in javac task calls by setting the
build.compiler 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.
Sample of compiler adapter
To build using the adapter, put the
aspectjtools.jar
on the system/ant classpath (e.g., in
${ANT_HOME}/lib)
and define the
build.compiler
property as the fully-qualified name of the class,
org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter.
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
src/org/aspectj subdirectories to the
ajc command along with the destination directory:
]]>
To pass ajc-specific arguments, use a compilerarg entry.
]]>
Compiler adapter compilerarg options
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 .
-Xmaxmem:
set maximum memory for forking (also settable in javac).
-Xlistfileargs:
list file arguments (also settable in javac).
-Xfailonerror:
throw BuildException on compiler error (also settable in javac).
-Xmessageholderclass:
specify fully-qualified name of class to use as the message holder.
-Xcopyinjars:
copy resources from any input jars to output
-Xsourcerootcopyfilter {filter}:
copy resources from source directories to output (minus files specified in filter)
-Xtagfile {file}:
use file to control incremental compilation
-Xsrcdir {dir}:
add to list of ajc source roots (all source files will be included).
Special considerations when using Javac and compilerarg:
The names above may differ slightly from what you might expect
from AjcTask; use these forms when specifying compilerarg.
By default the adapter will mimic the Javac task's copying of resource
files by specifying
"**/CVS/*,**/*.java,**/*.aj"
for the sourceroot copy filter.
To change this behavior, supply your own value
(e.g., "**/*" to copy nothing).
Warning - define the system property
build.compiler.clean 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.
To work around this, set the global property
build.compiler.clean.
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.,
Caveats to consider when using this global
build.compiler.clean property:
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.
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.
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.
When running incrementally, the clean happens only before
the initial compile.
Ajc10 (ajc)
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., lenient, strict, workingdir, preprocess, usejavac,...),
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.)
Ajc10 (ajc) Options
Most attributes and nested elements are optional.
The compiler requires that the same version of
aspectjrt.jar
be specified on the classpath, and that some sources be
be specified
(using one or more of
argfiles and
srcdir (with patterns)).
Boolean parameters default to false
unless otherwise stated.
AjcTask (ajc) options for specifying sources
Attribute
Description
srcdir
The base directory of the java files.
See
destdir
The target directory for the output .class files
includes
Comma-separated list of patterns of files that must be included.
No files are included when omitted.
includesfile
The path to a file containing include patterns.
excludes
Comma-separated list of patterns of files that must be excluded.
No files (except default excludes) are excluded when omitted.
excludesfile
The path to a file containing exclude patterns.
defaultexcludes
If true, then default excludes are used.
Default excludes are used when omitted
(i.e., defaults to true).
classpath, classpathref
The classpath to use,
optionally given as a reference to a classpath Path
element defined elsewhere.
bootclasspath, bootclasspathref
The bootclasspath to use,
optionally given as a reference to a bootclasspath Path
element defined elsewhere.
extdirs
Paths to directories containting installed extensions.
debug
If true, emit debug info in the .class files.
deprecation
If true, emit messages about use of deprecated API.
verbose
Emit compiler status messages during the compile.
version
Emit version information and quit.
failonerror
If true, throw BuildException to halt build if there
are any compiler errors.
If false, continue notwithstanding compile errors.
Defaults to true.
source
Value of -source option - ignored unless 1.4.
Parameters ignored by the old ajc taskdef,
but now supported or buggy
Attribute
Description
Supported?
encoding
Default encoding of source files.
yes
optimize
Whether source should be compiled with optimization.
yes?
target
Generate class files for specific VM version, one of
[1.1 1.2].
yes
depend
Enables dependency-tracking.
no
includeAntRuntime
Whether to include the Ant run-time libraries.
no
includeJavaRuntime
Whether to include the run-time libraries from the executing VM.
no
threads
Multi-threaded compilation
no
The following table shows that many of the unique parameters in
AspectJ 1.0 are no longer supported.
Parameters unique to ajc
Attribute
Description
X
comma-delimited list of extended (-X...) options,
entered without -X (e.g.,
X="lint" for -Xlint).
emacssym
Generate symbols for Emacs IDE support.
argfiles
A comma-delimited list of argfiles that contain a line-delimited
list of source file paths (absolute or relative to the argfile).
argfiles - argument list files
An argument file is a file (usually {file}.lst)
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.
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.
Ajc10 parameters specified as nested elements
This task forms an implicit FileSet and supports all attributes of
<fileset> (dir becomes srcdir) as well as
the nested
<include>,
<exclude>, and
<patternset> elements.
These can be used to specify source files.
ajc's
srcdir,
classpath,
bootclasspath,
extdirs, and
jvmarg
attributes are path-like structures and can also be set via nested
<src>,
<classpath>,
<bootclasspath>,
<extdirs>, and
<jvmargs> elements, respectively.
Sample of ajc task
Following is a declaration for the ajc task and a sample invocation
that uses the ajc compiler to compile the files listed in
default.lst into the dest dir:
]]>
This build script snippet
]]>
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.
This next example
]]>
compiles .java files under the ${src} directory in the
spacewar and coordination packages, and stores the .class files in the
${build} directory.
All source files under spacewar/ and coordination/ are used, except Debug.java.
See ../examples/builds.xml
for an example build script.
Maven support
Maven is a project-based build system used by Apache and others
to integrate many open-source projects. They have a plugin to
support AspectJ 1.0, and we plan to help them support AspectJ 1.1.
In the meantime, this describes how to upgrade an existing
Maven environment to use the AspectJ 1.1 compiler.
It was verified on a 1.0-beta10-SNAPSHOT release.
For more information on Maven, see
http://maven.apache.org.
Sample Maven plugin
To integrate AspectJ requires writing a Maven plugin and
installing the AspectJ libraries in the local Maven
repositories directory.
The Maven plugin defines an "aspectj" goal;
given a project with directories "src" and "aspectsrc",
the plugin will compile everything using AspectJ.
To use the plugin, request the aspectj goal
in your project:
The plugin is mainly a Jelly script that specifies
Ant scriptlets to run when building with AspectJ.
To create your own, start with the files from
the Maven support for AspectJ 1.0.
(Unfortunately, their plugin version is 1.1.
If you want to continue using the old version,
copy the files and
use a different version number than 1.1 in the
examples below.)
Below is a plugin.jelly
script that defines the
Ant calls. The script uses XML namespace prefixes,
so find the start of the Ant compiler call
at <ant:iajc ....
Note that it uses the existing rule for defining
aspectSourcesPresent.
]]>
In this example, no special options
are supported, but nicely enough the script can read the
library jars from the plugin dependency path:
]]>
The plugin dependency path and the filenames of the library
jars are defined in the plugin
project.xml file.
Below are the relevant definitions:
${basedir}/../project.xml
3
maven-aspectj-plugin
...
aspectj:aspectjtools
1.1
root
aspectj:aspectjrt
1.1
root
...
]]>
So the actual paths are calculated from the dependencies,
which resolve to the local repository directory of your
Maven installation. After you update the Jelly script,
manually rename and copy the AspectJ 1.1 libraries to your
directory:
That should be it. Remember to go through the files
for any version or library jar name changes.
Again, long-term, we hope to the Maven folks can
have an official
version of the AspectJ plugin which supports
both AspectJ 1.0 and 1.1.
Isolating problems running the Ant tasks
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.
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.)
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.
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).
Known issues with the Ant tasks
For the most up-to-date information on known problems,
see the
bug database
for unresolved
compiler bugs
or
taskdef bugs
.
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.
Forking is now supported in both the
and
,
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).
Ant task questions and bugs
For questions, you can send email to
aspectj-users@dev.eclipse.org.
(Do join the list to participate!)
We also welcome any bug reports, patches, and features;
you can submit them to the bug database at
http://dev.eclipse.org/bugs
using the AspectJ product and Ant component.