AspectJ Ant Tasks

Version 1.0.6 released on July 24, 2002.

1 About this package

This package contains Ant tasks for the AspectJ compiler (ajc) and for the AspectJ documentation tool (ajdoc).

These releases do not yet support some of the options available in the underlying tools or in similar tasks from Apache, but they have been used successfully by a number of people. (The sources are provided with the release so you can fix bugs yourself if you are that sort of person.) Please email us ( support@aspectj.org) if you have any comments, bugs, or fixes.

2 Requirements

  • Jakarta Ant 1.3. or later:  Please see the official Jakarta Ant website for more information and the 1.3 distribution.
  • AspectJ tools:  Please see http://aspectj.org  for the binaries required to run the ajc and ajdoc tools and run AspectJ programs. These tasks are tested only with the current version, 1.0.6.
  • J2SE tools.jar:  If you are using ajdoc or the -usejavac flag of ajc, then you will need to include the tools.jar from your Java SDK on the taskdef classpath. For ajdoc, the tools.jar must be from J2SE 1.3 (not 1.4 or 1.2).

    • 3 Installation and use

    In Ant, third-party tasks must be declared using taskdefs in the build script, to identify the name and classes. When you declare these tasks, include classes for both the tasks and the AspectJ tools they use (ajc and ajdoc) in the classpath. The tool classes are in aspectjtools.jar. You will also have to include the aspectjrt.jar in the user class path when you invoke the task in order to compile.

    Defining and using the task

    Like any task not built-in to Ant, these must be declared in your build script. You can set the classpath for the task at the same time to include aspectj-ant.jar and aspectj-tools.jar, or you can install the libraries in ${ant.home}/lib. Following is a declaration for the ajc taskdef and a sample invocation that uses the ajc compiler via the ajc taskdef 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.Ajc" >
    <!-- declare classes needed to run the tasks and tools -->
    <classpath>
      <pathelement location="${home.dir}/tools/aspectj/lib/aspectj-ant.jar"/>
      <pathelement location="${home.dir}/tools/aspectj/lib/aspectjtools.jar"/>
      <pathelement location="${home.dir}/tools/jdk13/lib/tools.jar"/>
    </classpath>
  </taskdef>

  <target name="compile" >
    <mkdir dir="dest" />
    <ajc workingdir="temp" 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>

    The declaration would be similar for the ajdoc task, except to use the class name org.aspectj.tools.ant.taskdefs.Ajdoc.

    Classpath Alternatives

    If for some reason you do not want to include the libraries in the taskdef, you have to set up the classpath accordingly. The Ant distribution includes scripts that add library jars to its classpath. If you use these scripts, then you can put aspectj-ant.jar and aspectjtools.jar in the {ANT_HOME}/lib directory, where it will be added to the class path by the ant script. For example, if Ant is installed in /home/user/tools/ant then put aspectj-ant.jar and aspectj-tools.jar in /home/user/tools/ant/lib. (However, for invoking ajdoc you must include a tools.jar from J2SE 1.3 on the classpath, which may conflict with users of tools.jar expecting another version. In this case it is usually better to use the ant taskdef entry to define the task classpath.) If you are otherwise invoking Ant, make sure the classes are on the classpath when you run Ant.

  • For more examples of using the Ant taskdefs, see the build.xml Ant script included with the examples in the AspectJ documentation distribution.

  • For more information on invoking the tasks, please refer to the taskdef documentation linked above, which lists the available options and parameters.

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

    • 4. What to do if you have 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 the ajc or ajdoc tools directly on the command line.

  • 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 problem occurs on the command line also, then the problem is not in the taskdef. (It may be in the tools; please send bug reports!)
  • 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 compiler bugs, ajdoc bugs, or taskdef bugs.
    ajc tool

  • Does not clear out the workingdir before generating .java files thereto.

    • ajdoc task
  • ajdoc does not support grouping or package groups.
  • All required code must be supplied as input (as packages or source files or via argument files) or the compile required for the documentation will fail.
  • ajdoc does not emit complete documentation in the target class for publically introduced members; it only emits a link back to the documentation in the source aspect.
  • ajdoc might not run correctly repeatedly because it saves options in static state. A warning will be emitted when more than one instance is run.
  • ajdoc requires the J2SE 1.3 tools.jar. When running under J2SE 1.4.x or 1.3.x, the 1.3 tools.jar must be available (first) on the classpath. If not, the error presents differently in different configurations. Under Java 1.4, you may get an IllegalAccessError trying to access HtmlWriter.configuration. To check this under Ant, run with the -debug option and make sure that the tools classes are being loaded from the ant class loader set up by the taskdef, and not by the parent or system class loader.

    • You can send email to users@aspectj.org. (Do join the list to participate!) We also welcome any bug reports; you can submit them to http://aspectj.org/bugs.