123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878 |
- [[antTasks]]
- = AspectJ Ant Tasks
-
- [[antTasks-intro]]
- == 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:
-
- [arabic]
- . xref:#antTasks-iajc[AjcTask (iajc)], a task to run the AspectJ
- post-1.1 compiler, which supports all the eclipse and ajc options,
- including incremental mode.
- . xref:#antTasks-adapter[Ajc11CompilerAdapter (javac)], an adapter class
- to run the new compiler using Javac tasks by setting the build.compiler
- property
- . xref:#antTasks-ajc[Ajc10 (ajc)], 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 xref:../examples/build.xml[examples/build.xml].
-
- [[antTasks-install]]
- == 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 Eclipse Public License
- v 2.0 at https://eclipse.org/aspectj.
-
- In Ant 1.5, 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:
-
- [source, xml]
- ....
- <taskdef resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties"/>
- ....
-
- The current resource file retains the name "ajc" for the Ajc10 task, and
- uses "iajc" for the AspectJ post-1.1 task.
-
- In Ant 1.6, third-party tasks are declared in their own namespace using
- `antlib.xml`. For example, the following script would build and run the
- spacewar example, if you put the script in the examples directory and
- `aspectjtools.jar` in the `$\{ANT_HOME}/lib` directory.
-
- [source, xml]
- ....
- <project name="aspectj-ant1.6" default="spacewar"
- xmlns:aspectj="antlib:org.aspectj" basedir=".">
- <target name="spacewar">
- <aspectj:iajc
- argfiles="spacewar/debug.lst"
- outjar="spacewar.jar"
- classpath="../../lib/aspectjrt.jar"
- />
- <java classname="spacewar.Game"
- classpath="spacewar.jar:../../lib/aspectjrt.jar"/>
- </target>
- </project>
- ....
-
- For more information on using Ant, please refer to Jakarta's
- documentation on integrating user-defined Ant tasks into builds.
-
- [[antTasks-iajc]]
- == AjcTask (iajc)
-
- 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
- xref:ajc.adoc[`ajc`, the AspectJ compiler/weaver]. 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 xref:#antTasks-iajc-uptodate[Avoiding clean
- compiles].
-
- 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.
-
- This task is named iajc to avoid conflict with the 1.0 task ajc.
-
- [[antTasks-iajc-options]]
- === 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
- xref:#antTasks-iajc-paths[Path] 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`, `inpath`, `argfiles`, and/or `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*
-
- [cols=",",options="header",]
- |===
- |Attribute |Description
- |argfiles, argfilesRef (xref:#antTasks-iajc-paths[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.
-
- |sourceRoots, sourceRootsRef (xref:#antTasks-iajc-paths[Path])
- |Directories containing source files (ending with .java or .aj) to
- compile.
-
- |srcdir (xref:#antTasks-iajc-paths[Path]) |Base directory of sources to
- compile, assuming there are xref:#antTasks-nested-includes[nested
- matches]. 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 (xref:#antTasks-iajc-paths[Path]) |Deprecated - use
- inpath instead. Read .class files for bytecode weaving from zip files
- (only).
-
- |inpath, inpathRef (xref:#antTasks-iajc-paths[Path]) |Read .class files
- for bytecode weaving from directories or zip files (like classpath).
-
- |classpath, classpathRef (xref:#antTasks-iajc-paths[Path]) |The
- classpath used by the sources being compiled. When compiling aspects,
- include the same version of the `aspectjrt.jar`.
-
- |bootclasspath, bootclasspathRef (xref:#antTasks-iajc-paths[Path]) |The
- bootclasspath specifies types to use instead of the invoking VM's when
- seeking types during compilation.
-
- |extDirs, extDirsRef (xref:#antTasks-iajc-paths[Path]) |The extension
- directories to use instead of those in the invoking VM when seeking
- types during compilation.
-
- |aspectPath, aspectPathRef (xref:#antTasks-iajc-paths[Path]) |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*
-
- [cols=",",options="header",]
- |===
- |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 |(Deprecated/ignored; ajc does this.) 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. See
- `inpathDirCopyFilter`. Requires `destDir` or `outJar`.
-
- |inpathDirCopyFilter |When set, copy all files from the inpath
- 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,**/*.class` to exclude any CVS directories, source
- files, or unwoven .class files. (If `**/*.class` is not specified, it
- will be prepended to the filter.) See `sourceRootCopyFilter`. (Note that
- ajc itself copies all resources from input jar/zip files on the inpath.)
- Requires `destDir` or `outJar`.
- |===
-
- *AjcTask (iajc) options for specifying compiler behavior*
-
- [cols=",",options="header",]
- |===
- |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 (xref:#antTasks-iajc-paths[Path])
- |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 Options should not contain the leading X. Some commonly-used
- experimental options have their own entries. The other permitted ones
- (currently) are serializableAspects, incrementalFile, lazyTjp,
- reweavable, notReweavable, noInline, terminateAfterCompilation,
- ajruntimelevel:1.2, and ajruntimelevel:1.5. Of these, some were
- deprecated in AspectJ 5 (reweavable, terminateAfterCompilation, etc.).
-
- |XterminateAfterCompilation |Terminates before the weaving process,
- dumping out unfinished class files.
- |===
-
- *AjcTask (iajc) options for specifying compiler side-effects and
- messages*
-
- [cols=",",options="header",]
- |===
- |Attribute |Description
- |emacssym |If true, emit `.ajesym` symbol files for Emacs support.
-
- |crossref |If true, emit `.ajsym` file into the output directory.
-
- |verbose |If true, log compiler verbose messages as Project.INFO during
- the compile.
-
- |logCommand |If true, log compiler command elements as Project.INFO
- (rather than the usual Project.VERBOSE level).
-
- |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.
-
- |showWeaveInfo |If true, emit weaver messages. Defaults to `false`.
- |===
-
- *AjcTask (iajc) options for specifying Eclipse compiler options*
-
- [cols=",",options="header",]
- |===
- |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 1.5`] (default
- is 1.4). 1.3 implies -source 1.3 and -target 1.1. 1.4 implies -source
- 1.4 and -target 1.2. 1.5 implies -source 1.5 and -target 1.5.
-
- |source |Set source assertion mode to one of [`1.3 1.4`]. Default
- depends on compliance mode.
- |===
-
- [[antTasks-nested-includes]]
- === 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.
-
- [[antTasks-iajc-paths]]
- === AjcTask Path-like Structures
-
- Some parameters are path-like structures containing one or more
- elements; these are `sourceroots`, `argfiles`, `injars`, `inpath`,
- `classpath`, `bootclasspath`, `forkclasspath`, and `aspectpath`. In all
- cases, these may be specified as nested elements, something like this:
-
- [source, xml]
- ....
- <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:
-
- [source, xml]
- ....
- <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`:
-
- [source, xml]
- ....
- <iajc {attributes..} aspectpathref="aspect.path"/>
- ....
-
- [[antTasks-iajc-sample]]
- === Sample of iajc task
-
- A minimal build script defines the task and runs it, specifying the
- sources:
-
- [source, xml]
- ....
- <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>
- ....
-
- Below is script with most everything in it. The compile process...
-
- [arabic]
- . Runs in incremental mode, recompiling when the user hits return;
- . Reads all the source files from two directories;
- . Reads binary .class files from input jar and directory;
- . Uses a binary aspect library for persistence;
- . Outputs to an application jar; and
- . Copies resources from the source directories and binary input jar and
- directories to 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.
-
- [source, xml]
- ....
- <target name="build-test" >
- <iajc outjar="${home.dir}/output/application.jar"
- sourceRootCopyFilter="**/CVS/*,**/*.java"
- inpathDirCopyFilter="**/CVS/*,**/*.java,**/*.class"
- incremental="true" >
- <sourceroots>
- <pathelement location="${home.dir}/ec/project/src"/>
- <pathelement location="${home.dir}/ec/project/testsrc"/>
- </sourceroots>
- <inpath>
- <pathelement location="${home.dir}/build/module.jar"/>
- <pathelement location="${home.dir}/build/binary-input"/>
- </inpath>
- <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>
- ....
-
- For an example of a build script, see ../examples/build.xml.
-
- [[antTasks-iajc-uptodate]]
- === Avoiding clean compiles
-
- 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:
-
- [source, xml]
- ....
- <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 ...
- ....
-
- 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.
-
- === 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).
-
- [[antTasks-adapter]]
- == 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, because there are
- differences in source file handling between the Javac task and the ajc
- compiler, not all Javac task invocations can be turned over to iajc.
- However, ajc can compile anything that Javac can, so it should be
- possible for any given compile job to restate the Javac task in a way
- that can be handled by iajc/ajc.
-
- [[antTasks-adapter-sample]]
- === 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:
-
- [source, text]
- ....
- -- 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" />
- ....
-
- To pass ajc-specific arguments, use a compilerarg entry.
-
- [source, text]
- ....
- -- 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/>
- ....
-
- The Javac task does special handling of source files that can interfere
- with ajc. It removes any files that are not out-of-date with respect to
- the corresponding .class files. But ajc requires all source files, since
- an aspect may affect a source file that is not out of date. (For a
- solution to this, see the `build.compiler.clean` property described
- below.) Conversely, developers sometimes specify a source directory to
- javac, and let it search for files for types it cannot find. AspectJ
- will not do this kind of searching under the source directory (since the
- programmer needs to control which sources are affected). (Don't confuse
- the source directory used by Javac with the source root used by ajc; if
- you specify a source root to ajc, it will compile any source file under
- that source root (without exception or filtering).) To replace source
- dir searching in Javac, use an Ant filter to specify the source files.
-
- [[antTasks-adapter-options]]
- === 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
- xref:#antTasks-iajc[AjcTask (iajc)].
-
- * `-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 (default
- behavior since 1.1.1)
- * `-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.,
- +
- [source, text]
- ....
- Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter
- -Dbuild.compiler.clean=anything ...
- ....
- +
- Caveats to consider when using this global `build.compiler.clean`
- property:
- [arabic]
- . 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.
-
- [[antTasks-ajc]]
- == 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.
- This will not work for AspectJ 1.2 or later.)
-
- [[antTasks-ajc-options]]
- === 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
- [cols=",",options="header",]
- |===
- |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
- [cols=",,",options="header",]
- |===
- |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
- [cols=",",options="header",]
- |===
- |Attribute |Description
- |X |deprecated X options include reweavable (on by default)
- reweavable:compress (compressed by default)
-
- |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.
-
- [[antTasks-ajc-nested]]
- === 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.
-
- [[antTasks-ajc-sample]]
- === 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:
-
- [source, xml]
- ....
- <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>
- ....
-
- This build script snippet
-
- [source, xml]
- ....
- <ajc srcdir="${src}"
- destdir="${build}"
- argfiles="demo.lst"
- />
- ....
-
- 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
-
- [source, xml]
- ....
- <ajc srcdir="${src}"
- destdir="${build}"
- includes="spacewar/*,coordination/*"
- excludes="spacewar/Debug.java"
- />
- ....
-
- 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/build.xml for an example build script.
-
- [[antTasks-problems]]
- == 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).
-
- [[antTasks-knownProblems]]
- === Known issues with the Ant tasks
-
- For the most up-to-date information on known problems, see the
- https://bugs.eclipse.org/bugs[bug database] for unresolved
- https://bugs.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=Compiler&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED[compiler
- bugs] or
- https://bugs.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=Ant&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED[taskdef
- bugs] .
-
- 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.
-
- 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
- xref:#antTasks-adapter[Ajc11CompilerAdapter (javac)] and
- xref:#antTasks-iajc[AjcTask (iajc)], 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).
-
- [[antTasks-feedback]]
- === 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
- https://bugs.eclipse.org/bugs using the AspectJ product and Ant
- component.
|