AspectJ Ant Tasks

Version @build.version.long@ released on @build.date@.

About the AspectJ Ant tasks

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:
  1. Ajc10 (options), a task to run build scripts compatible with the AspectJ 1.0 tasks,
  2. AjcTask (options), a task to run the new AspectJ 1.1 compiler, which supports all the eclipse and ajc options, including incremental mode;
  3. Ajc11CompilerAdapter, an adapter class to run the new compiler using Javac tasks by setting the build.compiler property.
This describes how to install and use the tasks and the adapter. For an example Ant script, see examples/build.xml.

Installation

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: 

  <taskdef 
      resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties">
The current resource file retains the name "ajc" for the Ajc10 task, using "iajc" for the AspectJ 1.1 task. This may change in the final release of AspectJ 1.1.

For more information on using Ant, please refer to Jakarta's documentation on integrating user-defined Ant tasks into builds.

Ajc10 (script name: 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 (e.g., fork, 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.)

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. 

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

AjcTask (script name: iajc)

This task handles all the ajc 1.1 compiler options, as well as an incremental "tag" file to avoid depending on Ant input/output for controlling Ant-based incremenal compilation.

Below is an example of incrementally compiling src and testsrc root source directories, using tagfile.txt to control recompilation and halting. When this script is run, the compiler will build once and then wait for incremental builds, recompiling each time the last-modified date changes on the tag file. When the tag file no longer exists, the build will complete. Messages are printed as usual. 

<project name="incremental-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" >
    <mkdir dir="dest" />
    <inc-ajc destdir="dest" 
            tagfile="tagfile.txt" 
            sourceroots="src${path.separator}testsrc" >
      <!-- declare classes needed to compile the target files -->
      <classpath>
        <pathelement location="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/>
      </classpath>
    </inc-ajc>
  </target>
</project>

Ajc11CompilerAdapter

This CompilerAdapter can be used in javac tasks calls by setting the build.compiler property to the class name. This enables users to to easily switch between Javac and the AspectJ compiler. To build this way, install aspectjtools.jar in ${ANT_HOME}/lib and define the build.compiler property as the fully-qualified name of the class: 
    cp aspectj1.1/lib/aspectjtools.jar ant/lib
    ant/bin/ant -Dbuild.compiler=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).

To pass ajc-specific arguments, use a compilerarg entry. For example, 


-- command

  Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11BuildCompiler

-- build script

  <property name="ajc" 
              value="org.aspectj.tools.ant.taskdefs.Ajc11BuildCompiler"/>

  <javac srcdir="src" destdir="dest" >
    <compilerarg compiler="$${ajc}" line="-argfile src/args.lst"/>
  <javac >
Beware of using regular source lists with this; javac may prune unchanged files, which excludes them from the compile process for ajc, which requires that all files affected by any aspects be listed explicitly.

4. What to do if you encounter problems

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, but only if the code is pure-Java.)
  • 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 Problems
    For the most up-to-date information on known problems, see the bug database.

  • 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 the same compiles using javac. Forking is not supported in this release, so the only solution is to 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).
  • Messages suppressed: In the incremental task, messages from the compiler are printed but not segregated.

    • You can send email to mailto:aspectj-users@dev.eclipse.org. (Do join the list to participate!) We also welcome any bug reports; you can submit them to the bug database at http://dev.eclipse.org using the AspectJ product and Ant component.