From 370e5f6ad4e24f58edad4da82d64450457bdc248 Mon Sep 17 00:00:00 2001 From: wisberg Date: Mon, 5 May 2003 18:23:06 +0000 Subject: added ant tasks to the devguide as a chapter (rather than refentry), converted ajbrowser refentry to chapter (to get subsection TOC and better pagination) updated ajbrowser slightly, and updated index page to link accordingly. NOTE: links to ajc changed from devguide/rn01re01.html to devguide/ajc-ref.html Leaving ajc as refentry is awkward but seems right since it's a command-line tool. --- docs/devGuideDB/ajbrowser.xml | 230 ++++-- docs/devGuideDB/antsupport.xml | 1524 ++++++++++++++++++++++++++++++++++++- docs/devGuideDB/devguide.xml | 37 +- docs/dist/doc/ant-ajc-task.html | 585 -------------- docs/dist/doc/ant-ajc10-task.html | 383 ---------- docs/dist/doc/ant-tasks.html | 366 --------- docs/dist/doc/index.html | 27 +- 7 files changed, 1724 insertions(+), 1428 deletions(-) delete mode 100644 docs/dist/doc/ant-ajc-task.html delete mode 100644 docs/dist/doc/ant-ajc10-task.html delete mode 100644 docs/dist/doc/ant-tasks.html (limited to 'docs') diff --git a/docs/devGuideDB/ajbrowser.xml b/docs/devGuideDB/ajbrowser.xml index a2e5d79ba..704eb1446 100644 --- a/docs/devGuideDB/ajbrowser.xml +++ b/docs/devGuideDB/ajbrowser.xml @@ -1,63 +1,70 @@ - - - AspectJ Browser - - GUI tool for compiling programs with ajc and navigating the - crosscutting structure - - - - - Overview + + AspectJ Browser + + + AJBrowser presents a GUI for compiling programs with ajc + and navigating crosscutting structure. + The AspectJ Browser can edit program source files, compile using the AspectJ compiler - ajc, + run a program, and graphically navigate the program's crosscutting structure. + Launch the browser from the command line either by typing "ajbrowser" to invoke the script in {aspectj}/bin (if AspectJ is installed correctly) or by using the - aspectjtools.jar directly: + aspectjtools.jar directly, + and specifying no arguments or some number of + build configuration files + (suffix .lst): - java -jar aspectj1.1/lib/aspectjtools.jar ... + java -jar aspectj1.1/lib/aspectjtools.jar aspectj1.1/doc/examples/spacewar/debug.lst - + - - Program Build Configurations + + Building Programs + + Build Configurations + A build configuration is a set of files to compile for a + program (and optionally some additional compile arguments). + Because ajc requires all sources to be specified + (at least using the -sourceroots option), + most users create .lst files that list + the files to compile (one argument per line, globbing + permitted - for more details, see ). + - To work with a particular program, point the - AspectJ browser to the program source files - listed in a ".lst" build configuration file. - (Build configuration files are described - in the documentation for - ajc.) - Open a build configuration file from the GUI using - the File menu, "open" item, or by using the + To work with a particular program, select the + corresponding ".lst" build configuration file + from the GUI using the File menu, "open" item, + or by using the "Open Build Configuration" button ( ). - From the command line - you can also pass any number of ".lst" paths. - (If you pass in any non-".lst" arguments, it will run the - command-line compiler directly.) + + You can populate the build list from the command line + by passing any number of ".lst" paths. + (However, if you pass in any non-".lst" arguments, + it will run the command-line compiler directly.) - You can work with multiple build configurations; + To switch between build configurations, select, add, or remove them using the corresponding toolbar buttons. @@ -65,13 +72,13 @@ .ajbrowser file in your HOME directory. Edit these from the GUI by clicking the "Options" button or selecting the Tools menu item "Options...". - This is how you can set classpath, aspectpath, etc. - (ajbrowser, unlike ajc, does not support setting these - options from the ".lst" files.). + This is how to set classpath, aspectpath, etc. + + The following sections walks through a build. - - - Compiling a Program Build Configuration + + + Compiling a Program Build Configuration To compile click the "Build" button @@ -79,21 +86,33 @@ - ), or click <ctrl>F11. + ), or + or use the tools menu. + + To build using AspectJ 1.1's incremental mode, + click the incremental compile checkbox in + the AspectJ Build Options tab + of the Options dialog. + Once in incremental mode, you can force a full rebuild + by holding the shift key down when selecting the + build menu item or button. + + You may select from different build configurations in the GUI (see label 1 in the graphic below). (If you get classpath or other errors, set up the global build options as described above.) - - - - - - - Navigating the Program Structure - + + + + + + + + Navigating Program Structure + Select nodes in the program structure by clicking them (see label 2). If one node is related to one or more other nodes by an association the @@ -102,10 +121,11 @@ below the association. If there is no corresponding source for the link it will appear light-blue. + + + - - - + Example: Exploring the "Spacewar" sample code @@ -134,7 +154,7 @@ shows up as in label 4. - Note: If you did not install in the default location, the + Note: If you did not set up your classpath, the compile will fail with a message that you need to install aspectjrt.jar on your compile classpath. To do that, select "Tools -> Options" or click the "Options" button @@ -144,8 +164,12 @@ ). Click the Build Options tab to view the Build Paths pane. Edit the classpath entry to use your - install location, ok the dialog, and retry the compile. - + install location. For example, if you ran from the base Aspectj + directory, the classpath need only include + lib/aspectjrt.jar (though the browser may populate + the classpath with the bootclasspath and classpath initially.) + Be sure to use the + lib/aspectjrt.jar that came with the browser. @@ -250,8 +274,108 @@ - - + + + + Running Programs + + The browser supports a limited form of running compiled programs. + To run programs that have been built, click the run button + or select one of the run menu items in the project menu. + You can run in the same VM or spawn a new process; + the latter is generally better for GUI programs. + + Both require that any classpath you set be specified + using platform-specific paths and path separators (the + compiler might be more tolerant). + Output and error streams will be + merged into the streams of the browser (using separate + threads, so it may take a few seconds for the pipe + threads to gain control.) Errors should + be detected and displayed in a dialog. + + + There GUI does not support killing a running program, + so if your program might hang, + be sure to save your files since you may need to + kill the browser itself to kill its child processes. + + + + + Isolating problems running the AspectJ browser + + + If you have problems with the browser 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 browser. + (It may be in the compiler; 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 the build options. + + + If the build options look correct and the problem only occurs + when building from the browser, then please submit a bug report. + + + + + Known issues with the AspectJ browser + + For the most up-to-date information on known problems, + see the + bug database + for unresolved + + compiler bugs + or + + IDE bugs + . + + + + + Memory and forking: Users email most about the browser task running + out of memory. + This is not a problem with the browser; some compiles take a lot of + memory, often more than similar compiles using javac. + The browser does not support forking, so the only solution is to + edit the java command line or script that launches the browser + to add memory. + + + Editing build configuration files: this is not currently supported. + + + Key bindings: these do not seem to work on some machines. + + + + + + AspectJ browser questions and bugs + + You can send email to + + aspectj-users@dev.eclipse.org. + (Do join the list to participate!) + We also welcome any bug reports, patches, and feature requests; + you can submit them to the bug database at + + http://dev.eclipse.org/bugs + using the AspectJ product and IDE component. + + + + diff --git a/docs/devGuideDB/antsupport.xml b/docs/devGuideDB/antsupport.xml index 1b97968aa..9d5a4591a 100644 --- a/docs/devGuideDB/antsupport.xml +++ b/docs/devGuideDB/antsupport.xml @@ -1,20 +1,1510 @@ - - - Ant Support - Support of Ant - - - - - ant - - - - - Description - - - + + + AspectJ Ant Tasks + + + Introduction + + + 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: + + + + , + a task to run the new AspectJ 1.1 compiler, + which supports all the eclipse and ajc options, including incremental mode. + + + + + , + an adapter class to run the new compiler using Javac tasks + by setting the build.compiler property + + + + + , + a task to run build scripts compatible with the AspectJ 1.0 tasks + + + + + + + This describes how to install and use the tasks and the adapter. + For an example Ant script, see + examples/build.xml. + + + + + Installing Ant Tasks + + 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: + + + +]]> + + + + The current resource file retains the name "ajc" for the Ajc10 task, + and uses "iajc" for the AspectJ 1.1 task. + + + For more information on using Ant, please refer to Jakarta's + documentation on integrating user-defined Ant tasks into builds. + + + + + + AjcTask (iajc) + + This task uses the AspectJ 1.1 compiler ajc. + The AspectJ compiler can be used like Javac 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 . + + + Beyond the normal ajc 1.1 compiler options, this task also supports + an experimental option for an incremental "tag" file, and it + can copy resources from source directories or + input jars to the output jar or directory. + + + + 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. + + + + AjcTask (iajc) Options + + The following tables list 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 + below for more information. + + + Most attributes and nested elements are optional. + 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 + sourceroots + injars + argfiles and + srcdir (with patterns)). + When in incremental mode, only + sourceroots may be specified. + + Boolean parameters default to false + unless otherwise stated. + + + + + AjcTask (iajc) options for specifying sources + + + + Attribute + Description + + + + + argfiles, argfilesRef + () + + + 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. + + + + sourceRoots, sourceRootsRef + () + + + Directories containing source files (ending with .java or .aj) to compile. + + + + srcdir + () + + + Base directory of sources to compile, assuming there are + TODO link 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. + + + + injars, injarsRef + () + + + Input zip files with .class file entries for bytecode weaving. + + + + classpath, classpathRef + () + + + The classpath used by the sources being compiled. + When compiling aspects, include the same version of the + aspectjrt.jar. + + + + bootclasspath, bootclasspathRef + () + + + The bootclasspath specified types to use instead of the + invoking VM's when seeking types during compilation. + + + + extDirs, extDirsRef + () + + + The extension directories to use instead of those in the + invoking VM when seeking types during compilation. + + + + aspectPath, aspectPathRef + () + + + Similar to classpath, aspectpath contains read-only, + binary aspect libraries. + Unlike classpath, it only accepts jar/zip files, + not directories. + + + + +
+ + + AjcTask (iajc) options for specifying output + + + + Attribute + Description + + + + + destDir + + + The directory in which to place the generated class files. + Conflicts with outjar. + + + + outJar + + + The zip file in which to place the generated output class files. + Conflicts with destdir. + + + + outJar + + + Copy all non-.class files from input jar(s) to the output jar or destination + directory after the compile (or incremental compile) completes. + + + + sourceRootCopyFilter + + + When 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. + + + + +
+ + + AjcTask (iajc) options for specifying compiler behavior + + + + Attribute + Description + + + + + 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). + + + + maxmem + + + The maximum memory to use for the new VM when fork is true. + Values should have the same form as accepted by the VM, e.g., "128m". + + + + tagfile + + + incremental mode: Build once, then recompile only required source + files when user provides input. + Requires that source files be specified only using sourceroots. + + + + tagfile + + + 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). + + + + X + + + Set experimental option(s), using comma-separated list of accepted options + (unlisted here). Options should not contain the leading X. + XLint options should be specified using the xlint... entries. + + + + Xnoweave + + + Experimental option to produce binaries that can only be used as input + for the -injars option. + + + + +
+ + + AjcTask (iajc) options for specifying compiler side-effects and messages + + + + Attribute + Description + + + + + emacssym + + + Whether to emit .ajesym symbol files for Emacs support. + + + + verbose + + + Whether to emit compiler status messages during the compile. + + + + Xlistfileargs + + + Whether to emit list of file arguments during + the compile (but behaves now like verbose). + + + + version + + + If true, do not compile - just print AspectJ version. + + + + help + + + If true, just print help for the command-line compiler. + + + + Xlintwarnings + + + Same as xlint:warning: + if enabled, set default level of all language + usage messages to warning. + + + + Xlint + + + Specify default level of all language usage messages to one of + (error warning ignore]. + + + + XlintFile + + + Specify property file containing name:level associations + setting level for language messages emitted during compilation. + Any levels set override the default associations in + org/aspectj/weaver/XLintDefault.properties. + + + + failonerror + + + Whether the build continues notwithstanding compile errors. + Defaults to true. + + + + messageHolderClass + + + Specify a class to use as the message holder for the compile process. + The entry must be a fully-qualified name of a class resolveable from + the task classpath complying with the + org.aspectj.bridge.IMessageHolder interface + and having a public no-argument constructor. + + + + +
+ + + + AjcTask (iajc) options for specifying Eclipse compiler options + + + + Attribute + Description + + + + + nowarn + + + Same as warn:none. + + + + deprecation + + + Same as warn:deprecation + + + + warn + + + One or more comma-separated warning specifications from + [constructorName packageDefaultMethod deprecation, + maskedCatchBlocks unusedLocals unusedArguments, + unusedImports syntheticAccess assertIdentifier]. + + + + debug + + + Same as debug:lines,vars,source + + + + debugLevel + + + One or more comma-separated debug specifications from + [lines vars source]. + + + + PreserveAllLocals + + + Code gen preserves all local variables (for debug purposes). + + + + noimporterror + + + No errors for unresolved imports. + + + + referenceinfo + + + Compute reference info. + + + + log + + + File to log compiler messages to. + + + + encoding + + Default source encoding format + (per-file encoding not supported in Ant tasks). + + + + proceedOnError + + + Keep compiling when error, dumping class files with problem methods. + + + + progress + + + Show progress (requires log). + + + + time + + + Display speed information. + + + + target + + + Specify target class file format (one of + [1.1 1.2]. + Defaults to 1.1 class file. + + + + + + + Set source compliance level to one of + [1.3 1.4] + (e.g., no import from default package in 1.4). + Defaults to 1.3 compliance level. + + + + source + + + Set source assertion mode to one of + [1.3 1.4]. + Default depends on compliance mode. + + + + + + + + + + + + + + + + +
+ + + + + + + + + AjcTask 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. + + + + + AjcTask Path-like Structures + + 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: + + + + <{name}> + + + ... + <{name}> + ... + +]]> + + + As with other Path-like structures, they may be defined elsewhere + and specified using the refid attribute: + + + + + + + ... + + + ... + +]]> + + + The task also supports an attribute {name}ref + for each such parameter. E.g., for aspectpath: + + + +]]> + + + + + Sample of iajc task + + A minimal build script defines the task and runs it, specifying the sources: + + + + + + + + + + + + + +]]> + + + Below is script with most everything in it. The compile process... + + + + Runs in incremental mode, recompiling when the user hits return; + + + + Reads all the sources from two directories; + + + + Reads extrinsic module bytecode as input jar for weaving; + + + + Uses a binary aspect library for persistence; + + + + Outputs to an application jar; and + + + + + Copies resources from the input jar and source directories into the application jar. + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + + For an in-depth example of a build script, + see + ../examples/build.xml. + + + + + Programmatically handling compiler messages + + 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 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). + + + + + + + Ajc11CompilerAdapter (javac) + + This CompilerAdapter can be used in javac task calls by setting the + build.compiler property. + This enables users to to easily switch between the Javac and AspectJ + compilers. + However, the Javac task's pruning of source files prevents the + adapter from doing a correct compile in some cases, + so use AjcTask where possible. + + + Sample of compiler adapter + + 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, + 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). + For example, the call below passes all out-of-date source files in the + src/org/aspectj subdirectories to the + ajc command along with the destination directory: + + + +]]> + + + + To pass ajc-specific arguments, use a compilerarg entry. + + + + + + + +]]> + + + + + Compiler adapter compilerarg options + + 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 . + + + + -Xmaxmem: + set maximum memory for forking (also settable in javac). + + + -Xlistfileargs: + list file arguments (also settable in javac). + + + -Xfailonerror: + throw BuildException on compiler error (also settable in javac). + + + -Xmessageholderclass: + specify fully-qualified name of class to use as the message holder. + + + -Xcopyinjars: + copy resources from any input jars to output + + + -Xsourcerootcopyfilter {filter}: + copy resources from source directories to output (minus files specified in filter) + + + -Xtagfile {file}: + use file to control incremental compilation + + + -Xsrcdir {dir}: + add to list of ajc source roots (all source files will be included). + + + + Special considerations when using Javac and compilerarg: + + + + The names above may differ slightly from what you might expect + from AjcTask; use these forms when specifying compilerarg. + + + + + By default the adapter will mimic the Javac task's copying of resource + files by specifying + "**/CVS/*,**/*.java,**/*.aj" + for the sourceroot copy filter. + To change this behavior, supply your own value + (e.g., "**/*" to copy nothing). + + + + + 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). + 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., + + + + + + Caveats to consider when using this global + build.compiler.clean property: + + + + 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. + + + 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. + + + 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. + + + When running incrementally, the clean happens only before + the initial compile. + + + + + + + + + + Ajc10 (ajc) + + 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., 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.) + + + + Ajc10 (ajc) Options + + + + Most attributes and nested elements are optional. + 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 + argfiles and + srcdir (with patterns)). + + Boolean parameters default to false + unless otherwise stated. + + + + + AjcTask (ajc) options for specifying sources + + + + Attribute + Description + + + + + srcdir + + + The base directory of the java files. + See + + + + destdir + + + The target directory for the output .class files + + + + includes + + + Comma-separated list of patterns of files that must be included. + No files are included when omitted. + + + + includesfile + + + The path to a file containing include patterns. + + + + excludes + + + Comma-separated list of patterns of files that must be excluded. + No files (except default excludes) are excluded when omitted. + + + + excludesfile + + + The path to a file containing exclude patterns. + + + + defaultexcludes + + + If true, then default excludes are used. + Default excludes are used when omitted + (i.e., defaults to true). + + + + classpath, classpathref + + + The classpath to use, + optionally given as a reference to a classpath Path + element defined elsewhere. + + + + bootclasspath, bootclasspathref + + + The bootclasspath to use, + optionally given as a reference to a bootclasspath Path + element defined elsewhere. + + + + extdirs + + + Paths to directories containting installed extensions. + + + + debug + + + If true, emit debug info in the .class files. + + + + deprecation + + + If true, emit messages about use of deprecated API. + + + + verbose + + + Emit compiler status messages during the compile. + + + + version + + + Emit version information and quit. + + + + failonerror + + + If true, build continues notwithstanding compile errors. + Defaults to true. + + + + source + + + Value of -source option - ignored unless 1.4. + + + + +
+ + + Parameters ignored by the old ajc taskdef, + but now supported or buggy + + + + Attribute + Description + Supported? + + + + + encoding + + Default encoding of source files. + + yes + + + + optimize + + + Whether source should be compiled with optimization. + + yes? + + + + target + + + Generate class files for specific VM version, one of + [1.1 1.2]. + + yes + + + + depend + + + Enables dependency-tracking. + + no + + + + includeAntRuntime + + + Whether to include the Ant run-time libraries. + + no + + + + includeJavaRuntime + + + Whether to include the run-time libraries from the executing VM. + + no + + + + threads + + Multi-threaded compilation + + no + + + + +
+ + + The following table shows that many of the unique parameters in + AspectJ 1.0 are no longer supported. + + + Parameters unique to ajc + + + + Attribute + Description + + + + + X + + + comma-delimited list of extended (-X...) options, + entered without -X (e.g., + X="lint" for -Xlint). + + + + emacssym + + + Generate symbols for Emacs IDE support. + + + + argfiles + + + A comma-delimited list of argfiles that contain a line-delimited + list of source file paths (absolute or relative to the argfile). + + + + +
+ + + + argfiles - argument list files + + An argument file is a file (usually {file}.lst) + containing a list of source file paths + (absolute or relative to the argfile). + You can use it to specify all source files to be compiled, + which ajc requires to avoid searching every possible source file + in the source path when building aspects. + If you specify an argfile to the ajc task, it will not include all + files in any specified source directory (which is the default + behavior for the Javac task when no includes are specified). + Conversely, if you specify excludes, they will be removed from + the list of files compiled even if they were specified + in an argument file. + + + The compiler also accepts arguments that are not source files, + but the IDE support for such files varies, and Javac does not + support them. Be sure to include exactly one argument on each line. + + + + + + Ajc10 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. + + + ajc's + srcdir, + classpath, + bootclasspath, + extdirs, and + jvmarg + attributes are path-like structures and can also be set via nested + <src>, + <classpath>, + <bootclasspath>, + <extdirs>, and + <jvmargs> elements, respectively. + + + + + + Sample of ajc task + + 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: + + + + + + + + + + + + + + + + + + + + +]]> + + + This build script snippet + + + +]]> + + + compiles all .java files specified in the demo.lst and stores the .class files in the ${build} directory. Unlike the Javac task, the includes attribute is empty by default, so only those files specified in demo.lst are included. + + + This next example + + + +]]> + + + compiles .java files under the ${src} directory in the + spacewar and coordination packages, and stores the .class files in the + ${build} directory. + All source files under spacewar/ and coordination/ are used, except Debug.java. + + + See ../examples/builds.xml + for an example build script. + + + + + + + Isolating problems running the Ant tasks + + + 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 issues with the Ant tasks + + 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 now supported in both the + and + , + and you can set the maximum memory available. + You can also not fork and 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). + + + + Ant task questions and bugs + + For questions, you can send email to + + aspectj-users@dev.eclipse.org. + (Do join the list to participate!) + We also welcome any bug reports, patches, and features; + you can submit them to the bug database at + + http://dev.eclipse.org/bugs + using the AspectJ product and Ant component. + + + + diff --git a/docs/devGuideDB/devguide.xml b/docs/devGuideDB/devguide.xml index 1c93ce2cb..205af29db 100644 --- a/docs/devGuideDB/devguide.xml +++ b/docs/devGuideDB/devguide.xml @@ -35,20 +35,43 @@ This guide describes the tools in the AspectJ 1.1 development - environment. See also The - AspectJ Programming Guide, the documentation for the - AspectJ Ant tasks, and the - documentation available with the AspectJ support available for - various integrated development environments (e.g., Eclipse, Emacs, - JBuilder, and NetBeans). + environment. See also + The + AspectJ Programming Guide, + the documentation available with the AspectJ support available for + various integrated development environments (e.g., Eclipse, Emacs, + JBuilder, and NetBeans), + and the most-recent documentation available from + the AspectJ project page, at + + http://eclipse.org/aspectj. + &ajc; - &ajbrowser; + + &ajbrowser; + &antsupport; diff --git a/docs/dist/doc/ant-ajc-task.html b/docs/dist/doc/ant-ajc-task.html deleted file mode 100644 index 8376ac22c..000000000 --- a/docs/dist/doc/ant-ajc-task.html +++ /dev/null @@ -1,585 +0,0 @@ - - - - - - - AjcTask Ant Support for AspectJ 1.1 - - - -

-AjcTask Ant Support for AspectJ 1.1

-AspectJ Ant Tasks - -

-Description

- -This task uses the AspectJtm 1.1 compiler -ajc. - -The AspectJ compiler can be used like - Javac -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, -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. -

-See below for -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). -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
Specifying sources
argfiles, argfilesRef -
(Path) -		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
sourceRoots, - sourceRootsRef -
(Path) -		 - Directories containing source files - (ending with .java or .aj) to compile. -Yes, in incremental mode.
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
injars, injarsRef -
(Path) -		 - Input zip files with .class file entries for bytecode weaving -No
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
bootclasspath, bootclasspathRef -
(Path) -		The bootclasspath specified types to use instead of -the invoking VM's when seeking types during compilation. -No
extdirs, extdirsRef -
(Path) -		The extension directories to use instead of those -in the invoking VM when seeking types during compilation. -No
aspectpath, aspectpathref -
(Path) -		Similar to classpath, aspectpath contains -read-only, binary aspect libraries; unlike classpath, -it only accepts jar/zip files, not directories. -No
Specifying output
destdirThe directory in which to place the generated class files. -Conflicts with outjar. -No
outjarThe zip file in which to place the generated output class files. -Conflicts with destdir. -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
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
Specifying compiler behavior
forkrun 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). - Defaults to false. - No
maxmemThe maximum memory to use for the new VM - when fork is true. Values should have the same form - as accepted by the VM, e.g., "128m". - No
incrementalincremental 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
tagfileincremental 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
XSet experimental option(s), using comma-separated list - of accepted options (unlisted here). - Options should not contain the leading X. - XLint options should be specified using the xlint... entries. - 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
emacssymWhether to emit .ajesym symbol files for Emacs support; -defaults to false.No
verboseWhether to emit compiler status messages during the compile; -defaults to false.No
XlistfileargsWhether to emit list of file arguments during the compile -(but behaves now like verbose); -defaults to falseNo
versionIf true, do not compile - just print AspectJ version; -defaults to false.No
helpIf true, just print help for the command-line compiler; -defaults to false.No
XlintwarningsSame as xlint:warning - -if enabled, set default level of all language usage messages to warning; -defaults to false.No
XlintSpecify default level of all language usage messages -to one of (error, warning, ignore). -No
XlintfileSpecify property file containing name:level -associations setting level for language messages emitted -during compilation. Any levels set override the default -associations in -org/aspectj/weaver/XLintDefault.properties. -No
failonerrorWhether the build continues notwithstanding compile errors; - defaults to true. No
messageholderclassSpecify a class to use as the message holder for the compile -process. The entry must be a fully-qualified name of a class resolveable -from the task classpath complying with the org.aspectj.bridge.IMessageHolder -interface and having a public no-argument constructor.No
Eclipse compiler options
nowarnSame as warn:none; - defaults to false. No
deprecationSame as warn:deprecation; - defaults to false. No
warnOne or more comma-separated warning specifications: -constructorName, -packageDefaultMethod, -deprecation, -maskedCatchBlocks, -unusedLocals, -unusedArguments, -unusedImports, -syntheticAccess, or -assertIdentifier.No
debugSame as debug:lines,vars,sourceNo
debuglevelOne or more comma-separated debug specifications: - lines, - vars, or - source. - No
PreserveAllLocalsCode gen preserves all local variables (for debug purposes); - defaults to false. No
noimporterrorNo errors for unresolved imports; - defaults to false. No
referenceinfoCompute reference info; - defaults to false. No
logFile to log compiler messages to.No
encodingDefault source encoding formatNo
proceedonerrorKeep compiling when error, dumping class files with problem methods; - defaults to false. No
progressShow progress (requires log); - defaults to false. No
timeDisplay speed information; - defaults to false. No
targetSpecify target class file format (must be "1.1" or "1.2"); - defaults to 1.1 class file. No
complianceSet "1.3" or "1.4" source compliance level - (e.g., no import from default package in 1.4); - defaults to 1.3 compliance level. No
sourceSource assertion mode ("1.3" or "1.4"); - default depends on compliance mode. No
- -
  - -

-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 and -ant-tasks.html -for introductory scripts. - - -

Programmatically handling compiler messages

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

- -

- - - diff --git a/docs/dist/doc/ant-ajc10-task.html b/docs/dist/doc/ant-ajc10-task.html deleted file mode 100644 index 03d4b3e88..000000000 --- a/docs/dist/doc/ant-ajc10-task.html +++ /dev/null @@ -1,383 +0,0 @@ - - - - - - - Ajc10 Ant Task - - - -

-Ajc10 Ant Task

- -

-Description

-This task is provided for backwards compatibility with build scripts -created for the AspectJ 1.0 ajc task. Developers using only -AspectJ 1.1 should upgrade their scripts to use the newer task. -This task is deprecated and may not be supported in the future. -Options no longer supported in 1.1 are still accepted, but have -no effect, other than to be listed in a warning emitted by the task. -

-This task compiles using the AspectJtm compiler ajc; -you can use it in place of the - Javac task. - -The interface is like the Javac task interface, except it also accepts -parameters unique to ajc. -Of these, most no longer have any effect (nocomments, preprocess, workingdir, -maxmemory, jvmarg), but argfiles are still supported. (For more information -on argfiles, see below.) -

- -

-Parameters

- -

Parameters supported by ajc

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
srcdirthe base directory of the java files. (See note)Yes, unless you use argfile -or nested <src> elements. -
destdirSpecify where to place the generated class files.No
includescomma-separated list of patterns of files that must be included; -no -files are included when omitted.No
includesfilethe name of a file that contains include patterns.No
excludescomma-separated list of patterns of files that must be excluded; -no files (except default excludes) are excluded when omitted.No
excludesfilethe name of a file that contains exclude patterns.No
defaultexcludeswhether default excludes should be used (yes -| no); default excludes are used when omitted.No
classpaththe classpath to use.No
bootclasspathlocation of bootstrap class files.No
classpathrefthe classpath to use, given as a -reference to a PATH defined elsewhere.No
bootclasspathreflocation of bootstrap class files, given as a reference -to a PATH defined elsewhere.No
extdirslocation of installed extensions No
debugwhether debug information should be included in classes output; -defaults to false.No
deprecationwhether compiler should emit messages about -usage of deprecated API; defaults to false.No
verbosewhether to emit compiler status messages during the compiler; -defaults to false.No
versionprint ajc version and exitNo
failonerrorwhether the build continues notwithstanding compile errors; - defaults to true. No
sourceValue of -source option - ignored unless "1.4"No
- -

-Parameters that used to be ignored by -the ajc taskdef, but now are supported or cause failures

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AttributeDescriptionSupport
encodingencoding of source files.Yes?
optimizewhether source should be compiled with optimizationYes?
targetgenerate class files for specific VM version (e.g., 1.1 -or 1.2).Yes
dependenables dependency-tracking No
includeAntRuntimewhether to include the Ant run-time librariesNo
includeJavaRuntimewhether to include the run-time libraries from the -executing VMNo
threadsMulti-threaded compilationNo
- - -

-Parameters unique to ajc

-Note: Many of the unique parameters in AspectJ 1.0 are no longer supported, -and fork is not supported yet. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
Xcomma-delimited list of extended (-X...) options, - entered without -X - (e.g., X="lint" for - -Xlint). No
emacssymGenerate symbols for Emacs IDE support - (defaults to off)No
argfilesa comma-delimited list of argfiles that - contain a line-delimited list of source file paths - (absolute or relative to the argfile) No
- - -

argfiles - Argument list files

-An argument file is a file (usually <file>.lst) containing a list of source file -paths (absolute or relative to the argfile). -You can use it to specify all source files to be compiled, which ajc requires -to avoid searching every possible source file in the source path when building aspects. -If you specify an argfile to the ajc task, it will not include all files in any specified -source directory (which is the default behavior for the Javac task when no includes are -specified). Conversely, if you specify excludes, they will be removed from the list of -files compiled even if they were specified in an argument file. - -
  - -

-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>, -<patternset>, -and <argfile> elements. -

-src, classpath, bootclasspath and extdirs

-ajc's srcdir, classpath, -bootclasspath, extdirs -and jvmarg attributes are path-like -structures and can also be set via nested -<src>, -<classpath>, -<bootclasspath>, -<extdirs> and <jvmarg> elements, respectively. -

-

-Examples

- -See ../examples/builds.xml -for an example build script. -

-This build script snippet - -

  <ajc srcdir="${src}"
-       destdir="${build}"
-       argfiles="demo.lst"
-  />
-compiles all .java files specified in the demo.lst and -stores the .class files in the ${build} directory.  -Unlike the Javac task, the -includes attribute is empty by default, so only those -files specified in demo.lst are included. -

This next example -

  <ajc srcdir="${src}"
-       destdir="${build}"
-       includes="spacewar/*,coordination/*"
-       excludes="spacewar/Debug.java"
-  />
-compiles .java files under the ${src} directory in the -spacewar -and -coordination packages, and stores the -.class files in the -${build} directory.  All source files under -spacewar/ and -coordination/ are used, except Debug.java. - - -
- - diff --git a/docs/dist/doc/ant-tasks.html b/docs/dist/doc/ant-tasks.html deleted file mode 100644 index c99e29e17..000000000 --- a/docs/dist/doc/ant-tasks.html +++ /dev/null @@ -1,366 +0,0 @@ - - - -AspectJ Ant Tasks - - - - -

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

-

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 task calls -by setting the build.compiler property. - This enables users to -to easily switch between the Javac and AspectJ compilers. -However, the Javac task's pruning of source files prevents -the adapter from doing a correct compile in some cases, so use -AjcTask where possible. - -

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, - 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). -For example, the call below 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" />
-
-
- - -

-To pass ajc-specific arguments, use a compilerarg entry. - -

--- command
-
-  Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter
-
--- build script
-
-  <property name="ajc" 
-              value="org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter"/>
-
-  <javac srcdir="src" includes="org/aspectj/**/*.java" destdir="dest" >
-    <compilerarg compiler="${ajc}" line="-argfile src/args.lst"/>
-  <javac/>
-
- -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. -

Also note that - the compiler will mimic the Javac task's copying of resource files - by specifying "**/CVS/*,**/*.java,**/*.aj" for the sourceroot - copy filter by default. To change this behavior, - supply your own value (e.g., "**/*" to copy nothing). - -

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

-

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