AjcTask Ant Support for AspectJ 1.1

Description

This task uses the AspectJ^tm 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 the links from the AspectJ docs home, especially the usage notes in the Development Environment Guide for command-line mode of the compiler.

This task is named iajc now to avoid conflict with the 1.0 task ajc, but the name may change to ajc in the future.

See below for an introduction to handling compiler messages programmatically.

Parameters

The following table lists 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 Nested Elements below for more information.

Some sources must be specified, but all other attributes and nested elements are optional (except that the compiler requires aspectjrt.jar to be on the classpath).

Attribute Description Required

Specifying sources

argfiles, argfilesRef
(Path) 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. No

sourceRoots, sourceRootsRef
(Path) Directories containing source files (ending with .java or .aj) to compile. Yes, in incremental mode.

srcdir
(Path) Base directory of sources to compile, assuming there are nested elements for includes or excludes. This 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. No

injars, injarsRef
(Path) Input zip files with .class file entries for bytecode weaving No

classpath, classpathRef
(Path) The classpath required by the input being compiled. Strictly-speaking not required, but the compiler insists aspectjrt.jar be on the classpath. No

bootclasspath, bootclasspathRef
(Path) The bootclasspath specified types to use instead of the invoking VM's when seeking types during compilation. No

extdirs, extdirsRef
(Path) The extension directories to use instead of those in the invoking VM when seeking types during compilation. No

aspectpath, aspectpathref
(Path) Similar to classpath, aspectpath contains read-only, binary aspect libraries; unlike classpath, it only accepts jar/zip files, not directories. No

Specifying output
destdir The directory in which to place the generated class files. Conflicts with outjar. No

outjar The zip file in which to place the generated output class files. Conflicts with destdir. No

copyInjars Copy all non-.class files from input jar(s) to the output jar or destination directory after the compile (or incremental compile) completes -- defaults to false. No

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. No

Specifying compiler behavior

incremental incremental mode: Build once, then recompile only required source files when user provides input. Requires that source files be specified only using sourceroots. Defaults to false. No

tagfile incremental mode: Build once, then recompile only required source files when the tag file is updated, finally exiting when tag file is deleted (also requires sourceroots). No

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. No

Xnoweave Experimental option to produce binaries that can only be used as input for the -injars option -- defaults to false. No

Specifying compiler side-effects and messages

emacssym Whether to emit .ajesym symbol files for Emacs support; defaults to false. No

verbose Whether to emit compiler status messages during the compile; defaults to false. No

Xlistfileargs Whether to emit list of file arguments during the compile (but behaves now like verbose); defaults to false No

version If true, do not compile - just print AspectJ version; defaults to false. No

help If true, just print help for the command-line compiler; defaults to false. No

Xlintwarnings Same as xlint:warning - if enabled, set default level of all language usage messages to warning; defaults to false. No

Xlint Specify default level of all language usage messages to one of (error, warning, ignore). No

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. No

failonerror Whether the build continues notwithstanding compile errors; defaults to true. No

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. No

Eclipse compiler options

nowarn Same as warn:none; defaults to false. No

deprecation Same as warn:deprecation; defaults to false. No

warn One or more comma-separated warning specifications: constructorName, packageDefaultMethod, deprecation, maskedCatchBlocks, unusedLocals, unusedArguments, unusedImports, syntheticAccess, or assertIdentifier. No

debug Same as debug:lines,vars,source No

debuglevel One or more comma-separated debug specifications: lines, vars, or source. No

PreserveAllLocals Code gen preserves all local variables (for debug purposes); defaults to false. No

noimporterror No errors for unresolved imports; defaults to false. No

referenceinfo Compute reference info; defaults to false. No

log File to log compiler messages to. No

encoding Default source encoding format No

proceedonerror Keep compiling when error, dumping class files with problem methods; defaults to false. No

progress Show progress (requires log); defaults to false. No

time Display speed information; defaults to false. No

target Specify target class file format (must be "1.1" or "1.2"); defaults to 1.1 class file. No

compliance Set "1.3" or "1.4" source compliance level (e.g., no import from default package in 1.4); defaults to 1.3 compliance level. No

source Source assertion mode ("1.3" or "1.4"); default depends on compliance mode. No

Attribute	Description	Required
Specifying sources
argfiles, argfilesRef (Path)	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.	No
sourceRoots, sourceRootsRef (Path)	Directories containing source files (ending with .java or .aj) to compile.	Yes, in incremental mode.
srcdir (Path)	Base directory of sources to compile, assuming there are nested elements for `includes` or `excludes`. This 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.	No
injars, injarsRef (Path)	Input zip files with .class file entries for bytecode weaving	No
classpath, classpathRef (Path)	The classpath required by the input being compiled. Strictly-speaking not required, but the compiler insists `aspectjrt.jar` be on the classpath.	No
bootclasspath, bootclasspathRef (Path)	The bootclasspath specified types to use instead of the invoking VM's when seeking types during compilation.	No
extdirs, extdirsRef (Path)	The extension directories to use instead of those in the invoking VM when seeking types during compilation.	No
aspectpath, aspectpathref (Path)	Similar to classpath, aspectpath contains read-only, binary aspect libraries; unlike classpath, it only accepts jar/zip files, not directories.	No
Specifying output
destdir	The directory in which to place the generated class files. Conflicts with `outjar`.	No
outjar	The zip file in which to place the generated output class files. Conflicts with `destdir`.	No
copyInjars	Copy all non-.class files from input jar(s) to the output jar or destination directory after the compile (or incremental compile) completes -- defaults to `false`.	No
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.	No
Specifying compiler behavior
incremental	incremental mode: Build once, then recompile only required source files when user provides input. Requires that source files be specified only using `sourceroots`. Defaults to `false`.	No
tagfile	incremental mode: Build once, then recompile only required source files when the tag file is updated, finally exiting when tag file is deleted (also requires `sourceroots`).	No
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.	No
Xnoweave	Experimental option to produce binaries that can only be used as input for the -injars option -- defaults to `false`.	No
Specifying compiler side-effects and messages
emacssym	Whether to emit `.ajesym` symbol files for Emacs support; defaults to `false`.	No
verbose	Whether to emit compiler status messages during the compile; defaults to `false`.	No
Xlistfileargs	Whether to emit list of file arguments during the compile (but behaves now like verbose); defaults to `false`	No
version	If true, do not compile - just print AspectJ version; defaults to `false`.	No
help	If true, just print help for the command-line compiler; defaults to `false`.	No
Xlintwarnings	Same as `xlint:warning` - if enabled, set default level of all language usage messages to warning; defaults to `false`.	No
Xlint	Specify default level of all language usage messages to one of (error, warning, ignore).	No
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`.	No
failonerror	Whether the build continues notwithstanding compile errors; defaults to `true`.	No
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.	No
Eclipse compiler options
nowarn	Same as `warn:none`; defaults to `false`.	No
deprecation	Same as `warn:deprecation`; defaults to `false`.	No
warn	One or more comma-separated warning specifications: `constructorName`, `packageDefaultMethod`, `deprecation`, `maskedCatchBlocks`, `unusedLocals`, `unusedArguments`, `unusedImports`, `syntheticAccess`, or `assertIdentifier`.	No
debug	Same as `debug:lines,vars,source`	No
debuglevel	One or more comma-separated debug specifications: `lines`, `vars`, or `source`.	No
PreserveAllLocals	Code gen preserves all local variables (for debug purposes); defaults to `false`.	No
noimporterror	No errors for unresolved imports; defaults to `false`.	No
referenceinfo	Compute reference info; defaults to `false`.	No
log	File to log compiler messages to.	No
encoding	Default source encoding format	No
proceedonerror	Keep compiling when error, dumping class files with problem methods; defaults to `false`.	No
progress	Show progress (requires log); defaults to `false`.	No
time	Display speed information; defaults to `false`.	No
target	Specify target class file format (must be "1.1" or "1.2"); defaults to 1.1 class file.	No
compliance	Set "1.3" or "1.4" source compliance level (e.g., no import from default package in 1.4); defaults to 1.3 compliance level.	No
source	Source assertion mode ("1.3" or "1.4"); default depends on compliance mode.	No

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, we recommend using sourceRoots to specify source directories unless using filters to exclude some files from compilation.

Some parameters are path-like structures containing one or more elements; these are sourceroots, argfiles, injars, classpath, and aspectpath. In all cases, these may be specified as nested elements, something like this:

    <iajc {attributes..} />
        <{name}>    
            <pathelement path="{first-location}"/>
            <pathelement path="{second-location}"/>
            ...
        <{name}>    
        ...
    </iajc>

As with other Path-like structures, they may be defined elsewhere and specified using the refid attribute:

    <path id="aspect.path">
        <pathelement path="${home}/lib/persist.jar"/>
        <pathelement path="${home}/lib/trace.jar"/>
    </path>
    ...
    <iajc {attributes..} />
        <aspectpath refid="aspect.path"/>    
        ...
    </iajc>

The task also supports an attribute {name}ref for each such parameter. E.g., for aspectpath:

    <iajc {attributes..} aspectpathref="aspect.path"/>

Examples

See examples/build.xml for an example build script and ant-tasks.html for introductory scripts.

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).