From 9da3b4c2b56c1061beea60a562d5a572fcdfbdf2 Mon Sep 17 00:00:00 2001 From: wisberg Date: Wed, 9 Apr 2003 14:18:02 +0000 Subject: [PATCH] updated forking, adapter option --- docs/dist/doc/ant-tasks.html | 125 +++++++++++++++++++++++++++++------ 1 file changed, 103 insertions(+), 22 deletions(-) diff --git a/docs/dist/doc/ant-tasks.html b/docs/dist/doc/ant-tasks.html index 585bacdba..5c265acab 100644 --- a/docs/dist/doc/ant-tasks.html +++ b/docs/dist/doc/ant-tasks.html @@ -17,12 +17,14 @@ 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), +
  2. Ajc10 + (parameters), a task to run build scripts compatible with the AspectJ 1.0 tasks,
    3. -
  3. AjcTask (parameters), +
  4. AjcTask + (parameters), a task to run the new AspectJ 1.1 compiler, which supports all the eclipse and ajc options, including incremental mode; -
  5. Ajc11CompilerAdapter, +
  6. Ajc11CompilerAdapter, an adapter class to run the new compiler using Javac tasks by setting the build.compiler property.
@@ -60,14 +62,13 @@ the "resource" attribute to specify the default names: 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) +

Ajc10 (script name: ajc) parameters

This task handles the same arguments as those used by the AspectJ 1.0 task. @@ -106,7 +107,7 @@ that uses the ajc compiler to compile the files listed in </project> -

AjcTask (script name: iajc) +

AjcTask (script name: iajc) parameters

This task handles all the ajc 1.1 compiler options, including @@ -187,48 +188,123 @@ When the user has quit, then this runs the application. -

Ajc11CompilerAdapter

+

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. +However, javac's handling of source files prevents the adapter from +doing a correct compile in some cases, so use +AjcTask where possible. -To build this way, install aspectjtools.jar in ${ANT_HOME}/lib +

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: +property as the fully-qualified name of the class. +The AspectJ compiler should run for any compile using the Javac task +(for options, see the Ant documentation for the Javac task). +For example, this passes all out-of-date source files in the +src/org/aspectj/ subdirectories to the ajc command +along with the destination directory: 

+-- 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" />
+
-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
+  Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter
 
 -- build script
 
   <property name="ajc" 
-              value="org.aspectj.tools.ant.taskdefs.Ajc11BuildCompiler"/>
+              value="org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter"/>
 
-  <javac srcdir="src" destdir="dest" >
-    <compilerarg compiler="$${ajc}" line="-argfile src/args.lst"/>
+  <javac srcdir="src" includes="org/aspectj/**/*.java" 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. +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 the +AjcTask documentation. + +Note the names above may differ slightly here from what you might +expect from AjcTask; use these forms when specifying compilerarg. + +

Warning - use build.compiler.clean + to get 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., +

+  Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter
+      -Dbuild.compiler.clean=anything ...
+
+Caveats to consider when using this global property: +
    +
  1. 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. +
    2. +
  2. 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. +
    3. +
  3. 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. +
    4. +
  4. When running incrementally, the clean happens only before + the initial compile. +
    5. +

4. What to do if you encounter problems

@@ -257,15 +333,20 @@ from Ant, then please send a report (including your build file, if possible).taskdef bugs. +