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 (parameters), a task to run build scripts compatible with the AspectJ 1.0 tasks,
  2. AjcTask (parameters), 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, and uses "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) parameters

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

This task handles all the ajc 1.1 compiler options, including the experimental option for an incremental "tag" file. It also can copy resources from source directories or input jars to the output jar or directory.

A minimal build script defines the task and runs it, specifying the sources: 

<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" /> 
  </target>
</project>

Below is script with most everything in it. The compile process...

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. 

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

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

    • 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/bugs using the AspectJ product and Ant component.