From: wisberg Date: Tue, 27 May 2003 09:31:32 +0000 (+0000) Subject: Ant doc updates X-Git-Tag: V1_1_0~46 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=34e71349683a530fecee85d36bb3107f9e3eb20c;p=aspectj.git Ant doc updates - forkclasspath - fork option classpath and conflicts - added maven section --- diff --git a/docs/devGuideDB/antsupport.xml b/docs/devGuideDB/antsupport.xml index 9d5a4591a..847461878 100644 --- a/docs/devGuideDB/antsupport.xml +++ b/docs/devGuideDB/antsupport.xml @@ -6,8 +6,10 @@ Introduction - AspectJ contains a compiler, ajc, that can be run from Ant. - Included in the aspectjtools.jar are Ant binaries to support three + 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: @@ -40,6 +42,7 @@ + Installing Ant Tasks @@ -55,7 +58,8 @@ 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 + 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, @@ -98,8 +102,7 @@ - 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. + This task is named iajc to avoid conflict with the 1.0 task ajc. @@ -112,11 +115,12 @@ 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 - below for more information. + below for more details. Most attributes and nested elements are optional. - The compiler requires that the same version of aspectjrt.jar + The compiler requires that the same version of + aspectjrt.jar be specified on the classpath, and that some sources be be specified (using one or more of @@ -166,8 +170,8 @@ Base directory of sources to compile, assuming there are - TODO link nested elements - for includes or excludes. This uses the Ant process + . + This approach 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. @@ -196,7 +200,7 @@ () - The bootclasspath specified types to use instead of the + The bootclasspath specifies types to use instead of the invoking VM's when seeking types during compilation. @@ -215,9 +219,10 @@ Similar to classpath, aspectpath contains read-only, - binary aspect libraries. - Unlike classpath, it only accepts jar/zip files, - not directories. + binary aspect libraries that are woven into sources + but not included in the output. + aspectpath accepts jar/zip files + (but, unlike classpath, not directories). @@ -239,7 +244,8 @@ The directory in which to place the generated class files. - Conflicts with outjar. + Only one of destDir and + outJar may be set. @@ -247,15 +253,19 @@ The zip file in which to place the generated output class files. - Conflicts with destdir. + Only one of destDir and + outJar may be set. - outJar + copyInjars - Copy all non-.class files from input jar(s) to the output jar or destination - directory after the compile (or incremental compile) completes. + If true, copy all non-.class files from input jar(s) + to the output jar or destination directory after the + compile (or incremental compile) completes. + In forked mode, this copies only after the process + completes, not after incremental compiles. @@ -288,13 +298,24 @@ fork - Run process in another VM (usually to specify memory or avoid locking any - jar files used on the classpath). - When set, this requires - aspectjtools.jar - be on the system/Ant classpath, and only uses the aspectjtools.jar - to invoke the compiler (so nothing else on the system/Ant classpath - is included implicitly in the compiler/user classpath). + Run process in another VM. + This gets the forking classpath either explicitly + from a forkclasspath entry + or by searching the task or system/Ant classpath for the + first readable file with a name of the form + aspectj{-}tools{.*}.jar. + When forking you can specify the amount of memory used + with maxmem. + Fork cannot be used in incremental mode, + unless using a tag file. + + + + forkclasspath, forkclasspathRef + () + + + Specify the classpath to use for the compiler when forking. @@ -306,12 +327,14 @@ - tagfile + incremental incremental mode: Build once, then recompile only required source files when user provides input. - Requires that source files be specified only using sourceroots. + Requires that source files be specified only using + sourceroots. + Incompatible with forking. @@ -320,7 +343,9 @@ 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 and only permits sourceroots). + is deleted. + Requires that source files be specified only using + sourceroots. @@ -337,7 +362,9 @@ Experimental option to produce binaries that can only be used as input - for the -injars option. + for the -injars option. + Usually aspects are compiled normally and put on the + aspectpath. @@ -358,21 +385,21 @@ emacssym - Whether to emit .ajesym symbol files for Emacs support. + If true, emit .ajesym symbol files for Emacs support. verbose - Whether to emit compiler status messages during the compile. + If true, emit compiler status messages during the compile. Xlistfileargs - Whether to emit list of file arguments during + If true, emit list of file arguments during the compile (but behaves now like verbose). @@ -395,7 +422,7 @@ Same as xlint:warning: - if enabled, set default level of all language + if true, set default level of all language usage messages to warning. @@ -404,7 +431,7 @@ Specify default level of all language usage messages to one of - (error warning ignore]. + [error warning ignore]. @@ -421,8 +448,10 @@ failonerror - Whether the build continues notwithstanding compile errors. - Defaults to true. + If true, throw BuildException to halt build if there + are any compiler errors. + If false, continue notwithstanding compile errors. + Defaults to true. @@ -455,14 +484,14 @@ nowarn - Same as warn:none. + If true, same as warn:none. deprecation - Same as warn:deprecation + If true, same as warn:deprecation @@ -479,7 +508,7 @@ debug - Same as debug:lines,vars,source + If true, same as debug:lines,vars,source @@ -494,21 +523,21 @@ PreserveAllLocals - Code gen preserves all local variables (for debug purposes). + If true, code gen preserves all local variables (for debug purposes). noimporterror - No errors for unresolved imports. + If true, emit no errors for unresolved imports. referenceinfo - Compute reference info. + If true, compute reference info. @@ -521,7 +550,7 @@ encoding - Default source encoding format + Default source encoding format (per-file encoding not supported in Ant tasks). @@ -529,39 +558,41 @@ proceedOnError - Keep compiling when error, dumping class files with problem methods. + If true, keep compiling after errors encountered, + dumping class files with problem methods. progress - Show progress (requires log). + If true, emit progress (requires log). time - Display speed information. + If true, display speed information. target - Specify target class file format (one of + Specify target class file format as one of [1.1 1.2]. Defaults to 1.1 class file. - + source Set source compliance level to one of [1.3 1.4] - (e.g., no import from default package in 1.4). + (e.g., in 1.4 no assert identifiers + and no import from default package). Defaults to 1.3 compliance level. @@ -574,103 +605,26 @@ Default depends on compliance mode. - - - - - - - - - - - - - - - - - AjcTask parameters specified as nested elements + + AjcTask matching 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 - as described in . - 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. + <patternset> elements. + These can be used to specify source files. + However, it is better to use sourceroots + to specify source directories unless using filters to exclude + some files from compilation. @@ -682,7 +636,9 @@ sourceroots, argfiles, injars, - classpath, and + classpath, + bootclasspath, + forkclasspath, and aspectpath. In all cases, these may be specified as nested elements, something like this: @@ -743,7 +699,8 @@ - + ]]> @@ -773,8 +730,8 @@ - - Copies resources from the input jar and source directories into the application jar. + Copies resources from the input jar and source directories into the application jar. + @@ -783,6 +740,7 @@ Messages are printed as usual. When the user has quit, then this runs the application. + - For an in-depth example of a build script, + For an example of a build script, see ../examples/build.xml. @@ -968,10 +926,12 @@ - Warning - use build.compiler.clean to get all files, when available, - because 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). + Warning - define the system property + build.compiler.clean to compile 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. @@ -1039,7 +999,8 @@ Most attributes and nested elements are optional. - The compiler requires that the same version of aspectjrt.jar + The compiler requires that the same version of + aspectjrt.jar be specified on the classpath, and that some sources be be specified (using one or more of @@ -1172,7 +1133,9 @@ failonerror - If true, build continues notwithstanding compile errors. + If true, throw BuildException to halt build if there + are any compiler errors. + If false, continue notwithstanding compile errors. Defaults to true. @@ -1341,9 +1304,7 @@ <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. + These can be used to specify source files. ajc's @@ -1430,8 +1391,215 @@ + + + Maven support + + Maven is a project-based build system used by Apache and others + to integrate many open-source projects. They have a plugin to + support AspectJ 1.0, and we plan to help them support AspectJ 1.1. + In the meantime, this describes how to upgrade an existing + Maven environment to use the AspectJ 1.1 compiler. + It was verified on a 1.0-beta10-SNAPSHOT release. + For more information on Maven, see + http://maven.apache.org. + + + Sample Maven plugin + + To integrate AspectJ requires writing a Maven plugin and + installing the AspectJ libraries in the local Maven + repositories directory. + + + The Maven plugin defines an "aspectj" goal; + given a project with directories "src" and "aspectsrc", + the plugin will compile everything using AspectJ. + To use the plugin, request the aspectj goal + in your project: + + + + + + The plugin is mainly a Jelly script that specifies + Ant scriptlets to run when building with AspectJ. + To create your own, start with the files from + the Maven support for AspectJ 1.0. + (Unfortunately, their plugin version is 1.1. + If you want to continue using the old version, + copy the files and + use a different version number than 1.1 in the + examples below.) + + + + + + Below is a plugin.jelly + script that defines the + Ant calls. The script uses XML namespace prefixes, + so find the start of the Ant compiler call + at <ant:iajc .... + Note that it uses the existing rule for defining + aspectSourcesPresent. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + + In this example, no special options + are supported, but nicely enough the script can read the + library jars from the plugin dependency path: + + + +]]> + + + The plugin dependency path and the filenames of the library + jars are defined in the plugin + project.xml file. + Below are the relevant definitions: + + + + ${basedir}/../project.xml + 3 + maven-aspectj-plugin + + ... + + + + aspectj:aspectjtools + 1.1 + + root + + + + aspectj:aspectjrt + 1.1 + + root + + + + + ... + + +]]> + + + So the actual paths are calculated from the dependencies, + which resolve to the local repository directory of your + Maven installation. After you update the Jelly script, + manually rename and copy the AspectJ 1.1 libraries to your + directory: + + + + + + That should be it. Remember to go through the files + for any version or library jar name changes. + Again, long-term, we hope to the Maven folks can + have an official + version of the AspectJ plugin which supports + both AspectJ 1.0 and 1.1. + + + Isolating problems running the Ant tasks