From 3971734b088041462a70a920bcff9150e48141a9 Mon Sep 17 00:00:00 2001 From: wisberg Date: Thu, 13 Mar 2003 02:58:27 +0000 Subject: [PATCH] revamped for normalized path handling and generalized resource-copying --- docs/dist/doc/ant-ajc-task.html | 269 +++++++++++++++++++++++--------- 1 file changed, 194 insertions(+), 75 deletions(-) diff --git a/docs/dist/doc/ant-ajc-task.html b/docs/dist/doc/ant-ajc-task.html index 22bdb4b99..e9ffbd791 100644 --- a/docs/dist/doc/ant-ajc-task.html +++ b/docs/dist/doc/ant-ajc-task.html @@ -23,15 +23,12 @@ 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 the links from -the AspectJ docs home. The main things to remember: - +the AspectJ docs home, +especially the usage notes in +the Development Environment Guide +for command-line mode of the compiler. + +

This task is named iajc now to avoid conflict with the 1.0 task ajc, but the name may change to ajc in the future. @@ -43,6 +40,19 @@ an introduction to handling compiler messages programmatically.

Parameters

+The following table lists 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 Nested Elements below for more information. + +

+Some sources must be specified, but all other attributes and +nested elements are optional +(except that the compiler requires aspectjrt.jar +to be on the classpath).

@@ -54,119 +64,167 @@ Parameters - + - - - + - + + - - - + + + - - - - - - - - + + + - - + - - + - + - - + + + + - - - + + + - - - - - + + + + + - - - + + + + + - - - + - + - + + of accepted options (unlisted here). + Options should not contain the leading X. + XLint options should be specified using the xlint... entries. + + + + + + + @@ -381,30 +439,91 @@ interface and having a public no-argument constructor.
Specifying source and destination filesSpecifying sources
sourceRootsBase directory of the source files. -All source files (.java and .aj) in the base directories are compiled. - May also be specified as a nested element. +
argfiles, argfilesRef +
(Path) 		Yes, in incremental mode.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. +No
sourceRootsListComma-delimited list of base directories source root -directories. - May also be specified as a nested element. +
sourceRoots, + sourceRootsRef +
(Path) 		+ Directories containing source files + (ending with .java or .aj) to compile. +Yes, in incremental mode.
outjarPath to an output jar to generate with all output classes.No
destdirSpecify where to place the generated class files.
srcdir +
(Path) +		Base directory of sources to compile, + assuming there are nested elements + for includes or excludes. + This 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. + No
classpathThe classpath required by the source files to compile. - May also be specified as a nested element. +injars, injarsRef +
(Path) +		 + Input zip files with .class file entries for bytecode weaving No
srcdirThe nested source base directory to compile, - specified as a nested element. +classpath, classpathRef +
(Path) +		The classpath required by the input being compiled. + Strictly-speaking not required, but the compiler + insists aspectjrt.jar be on the classpath. No
aspectpathaspectpath, aspectpathref +
(Path) +		 The aspectpath to use -- like classpath, only for read-only, binary aspect libraries (only accepts jar/zip files, no directories). -May also be specified as a nested element. No
bootclasspathLocation of bootstrap class files.Specifying output
destdirThe directory in which to place the generated class files. +Conflicts with outjar. + No
classpathrefThe classpath to use, given as a -reference to a PATH defined elsewhere.
outjarThe zip file in which to place the generated output class files. +Conflicts with destdir. + No
bootclasspathrefLocation of bootstrap class files, given as a reference -to a PATH defined elsewhere.No
copyInjarsCopy all non-.class files from input jar(s) to the output jar + or destination directory + after the compile (or incremental compile) completes + -- defaults to false. + No
Specifying compiler behavior
sourceRootCopyFilterWhen 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. + No
noweaveIf true, produce binaries for the -injars option (only) -- -defaults to false.NoSpecifying compiler behavior
incrementalBuild once, then recompile on demand only required files; - defaults to false. - By default, files are recompiled based on input passed to stdin - (see tagfile)incremental mode: + Build once, then recompile only required source files + when user provides input. + Requires that source files be specified only using + sourceroots. + Defaults to false. No
tagfileFile that controls when incremental builds are done - and when the task completes.incremental mode: + Build once, then recompile only required source files + when the tag file is updated, + finally exiting when tag file is deleted + (also requires sourceroots). + No
X Set experimental option(s), using comma-separated list - of accepted options (unlisted here -- for XLint, use - the xlint entries). Options should not contain the leading X. No
XnoweaveExperimental option to +produce binaries that can only be used as input for the +-injars option -- +defaults to false.No
Specifying compiler side-effects and messages
+
  -

Nested Elements

-This taskdef should support nested elements as the old one did; -see taskdef-ajc10.html#nestedElements. +

+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, we recommend using sourceRoots +to specify source directories +unless using filters to exclude some files from compilation. +

+Some parameters are path-like structures containing one or +more elements; these are +sourceroots, +argfiles, +injars, +classpath, and +aspectpath. + +In all cases, these may be specified as nested elements, +something like this: +

+    <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: +
+    <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: +
+    <iajc {attributes..} aspectpathref="aspect.path"/>    
+
+ +

+ +

+Examples

+ +See examples/build.xml +for an example build script.

Programmatically handling compiler messages

-Users may specify a message holder which is passed all -messages generated by the compiler synchronously. This overrides all of the normal -message printing, but does not prevent the task from failing if failonerror is true -and errors or exceptions were encountered. +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 inspect code. +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). - +

-
-
-- 2.39.5