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.tags/V1_1_0_RC2
@@ -1,63 +1,70 @@ | |||
<refentry> | |||
<refnamediv> | |||
<refname>AspectJ Browser</refname> | |||
<refpurpose>GUI tool for compiling programs with ajc and navigating the | |||
crosscutting structure</refpurpose> | |||
</refnamediv> | |||
<refsect1 id="ajbrowser" xreflabel="AspectJ Browser"> | |||
<title>Overview</title> | |||
<chapter id="ajbrowser" xreflabel="AspectJ Browser"> | |||
<title>AspectJ Browser</title> | |||
<sect1 id="ajbrowser-intro"> | |||
<para> | |||
AJBrowser presents a GUI for compiling programs with ajc | |||
and navigating crosscutting structure. | |||
</para> | |||
<para> | |||
The AspectJ Browser can edit program source files, | |||
compile using the AspectJ compiler | |||
<xref linkend="ajc">ajc</xref>, | |||
<xref linkend="ajc-ref"/> | |||
run a program, | |||
and graphically navigate the program's | |||
crosscutting structure. | |||
</para> | |||
<para> | |||
Launch the browser from the command line either | |||
by typing "ajbrowser" to invoke the script in | |||
<literal>{aspectj}/bin</literal> | |||
(if AspectJ is installed correctly) | |||
or by using the | |||
<literal>aspectjtools.jar</literal> directly: | |||
<literal>aspectjtools.jar</literal> directly, | |||
and specifying no arguments or some number of | |||
build configuration files | |||
(suffix <literal>.lst</literal>): | |||
<programlisting> | |||
java -jar aspectj1.1/lib/aspectjtools.jar ... | |||
java -jar aspectj1.1/lib/aspectjtools.jar aspectj1.1/doc/examples/spacewar/debug.lst | |||
</programlisting> | |||
</para> | |||
</refsect1> | |||
</sect1> | |||
<refsect1> | |||
<title>Program Build Configurations</title> | |||
<sect1> | |||
<title>Building Programs</title> | |||
<sect2> | |||
<title>Build Configurations</title> | |||
<para>A build configuration is a set of files to compile for a | |||
program (and optionally some additional compile arguments). | |||
Because <literal>ajc</literal> requires all sources to be specified | |||
(at least using the <literal>-sourceroots</literal> option), | |||
most users create <literal>.lst</literal> files that list | |||
the files to compile (one argument per line, globbing | |||
permitted - for more details, see <xref linkend="ajc-ref"/>). | |||
</para> | |||
<para> | |||
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 | |||
<xref linkend="ajc">ajc</xref>.) | |||
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 | |||
(<inlinemediaobject> | |||
<imageobject> | |||
<imagedata fileref="openConfig.gif"/> | |||
</imageobject> | |||
</inlinemediaobject>). | |||
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.) | |||
</para> | |||
<para> | |||
You can work with multiple build configurations; | |||
To switch between build configurations, | |||
select, add, or remove them | |||
using the corresponding toolbar buttons. | |||
</para> | |||
@@ -65,13 +72,13 @@ | |||
<literal>.ajbrowser</literal> 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. | |||
</para> | |||
<para>The following sections walks through a build. | |||
</para> | |||
</refsect1> | |||
<refsect1> | |||
<title>Compiling a Program Build Configuration</title> | |||
</sect2> | |||
<sect2> | |||
<title>Compiling a Program Build Configuration</title> | |||
<para> | |||
To compile click the "Build" button | |||
@@ -79,21 +86,33 @@ | |||
<imageobject> | |||
<imagedata fileref="build.gif"/> | |||
</imageobject> | |||
</inlinemediaobject>), or click <ctrl>F11. | |||
</inlinemediaobject>), or | |||
or use the tools menu. | |||
</para> | |||
<para>To build using AspectJ 1.1's incremental mode, | |||
click the <literal>incremental compile</literal> checkbox in | |||
the <literal>AspectJ Build Options</literal> tab | |||
of the <literal>Options</literal> 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. | |||
</para> | |||
<para> | |||
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.) | |||
</para> | |||
<imageobject> | |||
<imagedata fileref="ajbrowser-building.gif"/> | |||
</imageobject> | |||
</refsect1> | |||
<refsect1> | |||
<title>Navigating the Program Structure</title> | |||
<imageobject> | |||
<imagedata fileref="ajbrowser-building.gif"/> | |||
</imageobject> | |||
</sect2> | |||
</sect1> | |||
<sect1> | |||
<title>Navigating Program Structure</title> | |||
<para> | |||
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. | |||
</para> | |||
<imageobject> | |||
<imagedata fileref="ajbrowser-building.gif"/> | |||
</imageobject> | |||
</refsect1> | |||
<refsect1> | |||
<sect2> | |||
<title>Example: Exploring the "Spacewar" sample code </title> | |||
<para> | |||
<itemizedlist> | |||
@@ -134,7 +154,7 @@ | |||
shows up as in label 4. | |||
</para> | |||
<para>Note: If you did not install in the default location, the | |||
<para>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 @@ | |||
</imageobject> | |||
</inlinemediaobject>). Click the <literal>Build Options</literal> 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 | |||
<literal>lib/aspectjrt.jar</literal> (though the browser may populate | |||
the classpath with the bootclasspath and classpath initially.) | |||
Be sure to use the | |||
<literal>lib/aspectjrt.jar</literal> that came with the browser. | |||
</para> | |||
<para> | |||
@@ -250,8 +274,108 @@ | |||
</listitem> | |||
</itemizedlist> | |||
</para> | |||
</refsect1> | |||
</refentry> | |||
</sect2> | |||
</sect1> | |||
<sect1> | |||
<title>Running Programs</title> | |||
<para> | |||
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. | |||
</para> | |||
<para>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. | |||
</para> | |||
<para> | |||
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. | |||
</para> | |||
</sect1> | |||
<sect1 id="ajbrowser-problems"> | |||
<title>Isolating problems running the AspectJ browser</title> | |||
<para> | |||
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. | |||
</para> | |||
<itemizedlist> | |||
<listitem><para> | |||
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.) | |||
</para></listitem> | |||
<listitem><para> | |||
If the problem does not occur on the command line, then it may | |||
lie in the parameters you are supplying in the build options. | |||
</para></listitem> | |||
<listitem><para> | |||
If the build options look correct and the problem only occurs | |||
when building from the browser, then please submit a bug report. | |||
</para></listitem> | |||
</itemizedlist> | |||
<sect2 id="ajbrowser-knownProblems"> | |||
<title>Known issues with the AspectJ browser</title> | |||
<para> | |||
For the most up-to-date information on known problems, | |||
see the | |||
<ulink url="http://dev.eclipse.org/bugs">bug database</ulink> | |||
for unresolved | |||
<ulink url="http://dev.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=Compiler&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED"> | |||
compiler bugs | |||
</ulink> or | |||
<ulink url="http://dev.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=IDE&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED"> | |||
IDE bugs | |||
</ulink>. | |||
</para> | |||
<para> | |||
<itemizedlist> | |||
<listitem><para> | |||
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. | |||
</para></listitem> | |||
<listitem><para> | |||
Editing build configuration files: this is not currently supported. | |||
</para></listitem> | |||
<listitem><para> | |||
Key bindings: these do not seem to work on some machines. | |||
</para></listitem> | |||
</itemizedlist> | |||
</para> | |||
</sect2> | |||
<sect2 id="ajbrowser-feedback"> | |||
<title>AspectJ browser questions and bugs</title> | |||
<para> | |||
You can send email to | |||
<ulink url="mailto:aspectj-users@dev.eclipse.org"> | |||
aspectj-users@dev.eclipse.org</ulink>. | |||
(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 | |||
<ulink url="http://dev.eclipse.org/bugs"> | |||
http://dev.eclipse.org/bugs</ulink> | |||
using the AspectJ product and IDE component. | |||
</para> | |||
</sect2> | |||
</sect1> | |||
</chapter> | |||
<!-- Local variables: --> | |||
<!-- fill-column: 79 --> |
@@ -35,20 +35,43 @@ | |||
<abstract> | |||
<para> | |||
This guide describes the tools in the AspectJ 1.1 development | |||
environment. See also <ulink url="../progguide/index.html">The | |||
AspectJ Programming Guide</ulink>, the documentation for the | |||
AspectJ <ulink url="../ant-tasks.html">Ant tasks</ulink>, and the | |||
documentation available with the AspectJ support available for | |||
various integrated development environments (e.g., Eclipse, Emacs, | |||
JBuilder, and NetBeans). | |||
environment. See also | |||
<ulink url="../progguide/index.html">The | |||
AspectJ Programming Guide</ulink>, | |||
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 | |||
<ulink url="http://eclipse.org/aspectj"> | |||
http://eclipse.org/aspectj</ulink>. | |||
<!-- | |||
<itemizedlist> | |||
<listitem><ulink url="../progguide/index.html">The | |||
AspectJ Programming Guide</ulink> | |||
</listitem> | |||
<listitem>the | |||
documentation available with the AspectJ support available for | |||
various integrated development environments (e.g., Eclipse, Emacs, | |||
JBuilder, and NetBeans) | |||
</listitem> | |||
<listitem>the most-recent documentation available from | |||
the AspectJ project page, at | |||
<ulink url="http://eclipse.org/aspectj"> | |||
http://eclipse.org/aspectj</ulink>. | |||
</listitem> | |||
</itemizedlist> | |||
--> | |||
</para> | |||
</abstract> | |||
</bookinfo> | |||
<reference> | |||
&ajc; | |||
&ajbrowser; | |||
</reference> | |||
&ajbrowser; | |||
&antsupport; | |||
</book> | |||
@@ -1,585 +0,0 @@ | |||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | |||
<html> | |||
<head> | |||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |||
<meta http-equiv="Content-Language" content="en-us"> | |||
<title>AjcTask Ant Support for AspectJ 1.1</title> | |||
</head> | |||
<body> | |||
<h2> | |||
<a NAME="ajc"></a>AjcTask Ant Support for AspectJ 1.1</h2> | |||
<small><a href="ant-tasks.html">AspectJ Ant Tasks</a></small> | |||
<h3> | |||
Description</h3> | |||
This task uses the AspectJ<small><sup>tm</sup></small> 1.1 compiler | |||
<code>ajc</code>. | |||
The AspectJ compiler can be used like | |||
<a href="http://jakarta.apache.org/ant/manual/CoreTasks/javac.html">Javac</a> | |||
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 <tt>ajc</tt>, see the links from | |||
the <a href="index.html">AspectJ docs home</a>, | |||
especially the usage notes in | |||
the <a href="devguide/devguide.html">Development Environment Guide</a> | |||
for command-line mode of the compiler. | |||
<p> | |||
This task is named <tt>iajc</tt> now to avoid conflict with the | |||
1.0 task <tt>ajc</tt>, but the name may change to <tt>ajc</tt> in | |||
the future. | |||
<p> | |||
See <a href="#compilerMessages">below</a> for | |||
an introduction to handling compiler messages programmatically. | |||
<p> | |||
<h3> | |||
Parameters</h3> | |||
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 <a href="#nestedElements">Nested Elements</a> below for more information. | |||
<p> | |||
Some sources must be specified, but all other attributes and | |||
nested elements are optional | |||
(except that the compiler requires <code>aspectjrt.jar</code> | |||
to be on the classpath). | |||
<p> | |||
<table BORDER CELLSPACING=0 CELLPADDING=2 > | |||
<tr> | |||
<td VALIGN=TOP><b>Attribute</b></td> | |||
<td VALIGN=TOP><b>Description</b></td> | |||
<td ALIGN=CENTER VALIGN=TOP><b>Required</b></td> | |||
</tr> | |||
<tr> | |||
<th colspan="3">Specifying sources</th> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>argfiles, argfilesRef | |||
<br>(<a href="#nestedElements">Path</a>) | |||
</td> | |||
<td VALIGN=TOP>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. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>sourceRoots, | |||
sourceRootsRef | |||
<br>(<a href="#nestedElements">Path</a>) | |||
</td> | |||
<td VALIGN=TOP> | |||
Directories containing source files | |||
(ending with .java or .aj) to compile. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>Yes, in incremental mode.</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>srcdir | |||
<br>(<a href="#nestedElements">Path</a>) | |||
</td> | |||
<td VALIGN=TOP>Base directory of sources to compile, | |||
assuming there are <a href="#nestedElements">nested elements</a> | |||
for <code>includes</code> or <code>excludes</code>. | |||
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 <code>sourceroots</code> instead. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>injars, injarsRef | |||
<br>(<a href="#nestedElements">Path</a>) | |||
</td> | |||
<td VALIGN=TOP> | |||
Input zip files with .class file entries for bytecode weaving | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>classpath, classpathRef | |||
<br>(<a href="#nestedElements">Path</a>) | |||
</td> | |||
<td VALIGN=TOP>The classpath required by the input being compiled. | |||
Strictly-speaking not required, but the compiler | |||
insists <code>aspectjrt.jar</code> be on the classpath. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>bootclasspath, bootclasspathRef | |||
<br>(<a href="#nestedElements">Path</a>) | |||
</td> | |||
<td VALIGN=TOP>The bootclasspath specified types to use instead of | |||
the invoking VM's when seeking types during compilation. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>extdirs, extdirsRef | |||
<br>(<a href="#nestedElements">Path</a>) | |||
</td> | |||
<td VALIGN=TOP>The extension directories to use instead of those | |||
in the invoking VM when seeking types during compilation. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>aspectpath, aspectpathref | |||
<br>(<a href="#nestedElements">Path</a>) | |||
</td> | |||
<td VALIGN=TOP>Similar to classpath, aspectpath contains | |||
read-only, binary aspect libraries; unlike classpath, | |||
it only accepts jar/zip files, not directories. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<th colspan="3">Specifying output</th> | |||
<tr> | |||
<td VALIGN=TOP>destdir</td> | |||
<td VALIGN=TOP>The directory in which to place the generated class files. | |||
Conflicts with <code>outjar</code>. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>outjar</td> | |||
<td VALIGN=TOP>The zip file in which to place the generated output class files. | |||
Conflicts with <code>destdir</code>. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>copyInjars</td> | |||
<td VALIGN=TOP>Copy all non-.class files from input jar(s) to the output jar | |||
or destination directory | |||
after the compile (or incremental compile) completes | |||
-- defaults to <tt>false</tt>. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>sourceRootCopyFilter</td> | |||
<td VALIGN=TOP>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 | |||
<code>**/CVS/*,**/*.java</code> to exclude | |||
any CVS directories or source files. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<th colspan="3">Specifying compiler behavior</th> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>fork</td> | |||
<td VALIGN=TOP>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). | |||
Defaults to <tt>false</tt>. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>maxmem</td> | |||
<td VALIGN=TOP>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". | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>incremental</td> | |||
<td VALIGN=TOP>incremental mode: | |||
Build once, then recompile only required source files | |||
when user provides input. | |||
Requires that source files be specified only using | |||
<code>sourceroots</code>. | |||
Defaults to <tt>false</tt>. | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>tagfile</td> | |||
<td VALIGN=TOP>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 <code>sourceroots</code>). | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>X</td> | |||
<td VALIGN=TOP>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. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>Xnoweave</td> | |||
<td VALIGN=TOP>Experimental option to | |||
produce binaries that can only be used as input for the | |||
-injars option -- | |||
defaults to <tt>false</tt>.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<th colspan="3">Specifying compiler side-effects and messages</th> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>emacssym</td> | |||
<td VALIGN=TOP>Whether to emit <tt>.ajesym</tt> symbol files for Emacs support; | |||
defaults to <tt>false</tt>.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>verbose</td> | |||
<td VALIGN=TOP>Whether to emit compiler status messages during the compile; | |||
defaults to <tt>false</tt>.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>Xlistfileargs</td> | |||
<td VALIGN=TOP>Whether to emit list of file arguments during the compile | |||
(but behaves now like verbose); | |||
defaults to <tt>false</tt></td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>version</td> | |||
<td VALIGN=TOP>If true, do not compile - just print AspectJ version; | |||
defaults to <tt>false</tt>.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>help</td> | |||
<td VALIGN=TOP>If true, just print help for the command-line compiler; | |||
defaults to <tt>false</tt>.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>Xlintwarnings</td> | |||
<td VALIGN=TOP>Same as <tt>xlint:warning</tt> - | |||
if enabled, set default level of all language usage messages to warning; | |||
defaults to <tt>false</tt>.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>Xlint</td> | |||
<td VALIGN=TOP>Specify default level of all language usage messages | |||
to one of (error, warning, ignore). | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>Xlintfile</td> | |||
<td VALIGN=TOP>Specify property file containing name:level | |||
associations setting level for language messages emitted | |||
during compilation. Any levels set override the default | |||
associations in | |||
<code>org/aspectj/weaver/XLintDefault.properties</code>. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>failonerror</td> | |||
<td VALIGN=TOP>Whether the build continues notwithstanding compile errors; | |||
defaults to <tt>true</tt>. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>messageholderclass</td> | |||
<td VALIGN=TOP>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 <tt>org.aspectj.bridge.IMessageHolder</tt> | |||
interface and having a public no-argument constructor.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<th colspan="3">Eclipse compiler options</th> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>nowarn</td> | |||
<td VALIGN=TOP>Same as <tt>warn:none</tt>; | |||
defaults to <tt>false</tt>. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>deprecation</td> | |||
<td VALIGN=TOP>Same as <tt>warn:deprecation</tt>; | |||
defaults to <tt>false</tt>. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>warn</td> | |||
<td VALIGN=TOP>One or more comma-separated warning specifications: | |||
<tt>constructorName</tt>, | |||
<tt>packageDefaultMethod</tt>, | |||
<tt>deprecation</tt>, | |||
<tt>maskedCatchBlocks</tt>, | |||
<tt>unusedLocals</tt>, | |||
<tt>unusedArguments</tt>, | |||
<tt>unusedImports</tt>, | |||
<tt>syntheticAccess</tt>, or | |||
<tt>assertIdentifier</tt>.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>debug</td> | |||
<td VALIGN=TOP>Same as <tt>debug:lines,vars,source</tt></td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>debuglevel</td> | |||
<td VALIGN=TOP>One or more comma-separated debug specifications: | |||
<tt>lines</tt>, | |||
<tt>vars</tt>, or | |||
<tt>source</tt>. | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>PreserveAllLocals</td> | |||
<td VALIGN=TOP>Code gen preserves all local variables (for debug purposes); | |||
defaults to <tt>false</tt>. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>noimporterror</td> | |||
<td VALIGN=TOP>No errors for unresolved imports; | |||
defaults to <tt>false</tt>. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>referenceinfo</td> | |||
<td VALIGN=TOP>Compute reference info; | |||
defaults to <tt>false</tt>. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>log</td> | |||
<td VALIGN=TOP>File to log compiler messages to.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>encoding</td> | |||
<td VALIGN=TOP>Default source encoding format</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>proceedonerror</td> | |||
<td VALIGN=TOP>Keep compiling when error, dumping class files with problem methods; | |||
defaults to <tt>false</tt>. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>progress</td> | |||
<td VALIGN=TOP>Show progress (requires log); | |||
defaults to <tt>false</tt>. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>time</td> | |||
<td VALIGN=TOP>Display speed information; | |||
defaults to <tt>false</tt>. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<!-- | |||
<tr> | |||
<td VALIGN=TOP>noexit</td> | |||
<td VALIGN=TOP>Disable System.exit; defaults to <tt>true</tt>. | |||
(<em>If false, this kills the Ant process</em>; | |||
to halt compile gracefully, use <tt>failonerror</tt>); | |||
</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
--> | |||
<tr> | |||
<td VALIGN=TOP>target</td> | |||
<td VALIGN=TOP>Specify target class file format (must be "1.1" or "1.2"); | |||
defaults to 1.1 class file. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>compliance</td> | |||
<td VALIGN=TOP>Set "1.3" or "1.4" source compliance level | |||
(e.g., no import from default package in 1.4); | |||
defaults to 1.3 compliance level. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>source</td> | |||
<td VALIGN=TOP>Source assertion mode ("1.3" or "1.4"); | |||
default depends on compliance mode. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
</table> | |||
<br> | |||
<a name="nestedElements"></a> | |||
<h3> | |||
Parameters specified as nested elements</h3> | |||
This task forms an implicit | |||
<a href="http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html">FileSet</a> | |||
and supports all attributes of <tt><fileset></tt> | |||
(<tt>dir</tt> becomes <tt>srcdir</tt>) | |||
as well as the nested | |||
<tt><include></tt>, <tt><exclude></tt>, | |||
and <tt><patternset></tt> elements. | |||
These can be used to specify source files. | |||
However, we recommend using <code>sourceRoots</code> | |||
to specify source directories | |||
unless using filters to exclude some files from compilation. | |||
<p> | |||
Some parameters are path-like structures containing one or | |||
more elements; these are | |||
<tt>sourceroots</tt>, | |||
<tt>argfiles</tt>, | |||
<tt>injars</tt>, | |||
<tt>classpath</tt>, and | |||
<tt>aspectpath</tt>. | |||
In all cases, these may be specified as nested elements, | |||
something like this: | |||
<pre> | |||
<iajc {attributes..} /> | |||
<{name}> | |||
<pathelement path="{first-location}"/> | |||
<pathelement path="{second-location}"/> | |||
... | |||
<{name}> | |||
... | |||
</iajc> | |||
</pre> | |||
As with other Path-like structures, they may be defined | |||
elsewhere and specified using the refid attribute: | |||
<pre> | |||
<path id="aspect.path"> | |||
<pathelement path="${home}/lib/persist.jar"/> | |||
<pathelement path="${home}/lib/trace.jar"/> | |||
</path> | |||
... | |||
<iajc {attributes..} /> | |||
<aspectpath refid="aspect.path"/> | |||
... | |||
</iajc> | |||
</pre> | |||
The task also supports an attribute | |||
<code>{name}ref</code> for each such parameter. E.g., for | |||
<code>aspectpath</code>: | |||
<pre> | |||
<iajc {attributes..} aspectpathref="aspect.path"/> | |||
</pre> | |||
<p> | |||
<h3> | |||
Examples</h3> | |||
See <a href="examples/build.xml">examples/build.xml</a> | |||
for an example build script and | |||
<a href="ant-tasks.html">ant-tasks.html</a> | |||
for introductory scripts. | |||
<a name="compilerMessages"></> | |||
<h3>Programmatically handling compiler messages</h3> | |||
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 <tt>failonerror</tt> is true and the compiler detected errors in the sources. | |||
<p> | |||
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). | |||
<p> | |||
<hr> | |||
</body> | |||
</html> |
@@ -1,383 +0,0 @@ | |||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | |||
<html> | |||
<head> | |||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |||
<meta http-equiv="Content-Language" content="en-us"> | |||
<title>Ajc10 Ant Task</title> | |||
</head> | |||
<body> | |||
<h2> | |||
<a NAME="ajc10"></a>Ajc10 Ant Task</h2> | |||
<h3> | |||
Description</h3> | |||
This task is provided for backwards compatibility with build scripts | |||
created for the AspectJ 1.0 <tt>ajc</tt> 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. | |||
<p> | |||
This task compiles using the AspectJ<small><sup>tm</sup></small> compiler <code>ajc</code>; | |||
you can use it in place of the | |||
<a href="http://jakarta.apache.org/ant/manual/CoreTasks/javac.html">Javac</a> task. | |||
The interface is like the <tt>Javac</tt> task interface, except it also accepts | |||
<a href="#ajc-parameters">parameters unique to <code>ajc</code></a>. | |||
Of these, most no longer have any effect (nocomments, preprocess, workingdir, | |||
maxmemory, jvmarg), but argfiles are still supported. (For more information | |||
on argfiles, see <a href="#argfiles">below</a>.) | |||
<p> | |||
<h3> | |||
Parameters</h3> | |||
<h4>Parameters supported by <code>ajc</code></h4> | |||
<table BORDER CELLSPACING=0 CELLPADDING=2 > | |||
<tr> | |||
<td VALIGN=TOP><b>Attribute</b></td> | |||
<td VALIGN=TOP><b>Description</b></td> | |||
<td ALIGN=CENTER VALIGN=TOP><b>Required</b></td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>srcdir</td> | |||
<td VALIGN=TOP>the base directory of the java files. (See <a href="#nestedElements">note</a>)</td> | |||
<td ALIGN=CENTER VALIGN=TOP>Yes, unless you use <tt>argfile</tt> | |||
or nested <tt><src></tt> elements. | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>destdir</td> | |||
<td VALIGN=TOP>Specify where to place the generated class files.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>includes</td> | |||
<td VALIGN=TOP>comma-separated list of patterns of files that must be included; | |||
<b>no</b> | |||
files are included when omitted.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>includesfile</td> | |||
<td VALIGN=TOP>the name of a file that contains include patterns.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>excludes</td> | |||
<td VALIGN=TOP>comma-separated list of patterns of files that must be excluded; | |||
no files (except default excludes) are excluded when omitted.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>excludesfile</td> | |||
<td VALIGN=TOP>the name of a file that contains exclude patterns.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>defaultexcludes</td> | |||
<td VALIGN=TOP>whether default excludes should be used (<tt>yes</tt> | |||
| <tt>no</tt>); default excludes are used when omitted.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>classpath</td> | |||
<td VALIGN=TOP>the classpath to use.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>bootclasspath</td> | |||
<td VALIGN=TOP>location of bootstrap class files.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>classpathref</td> | |||
<td VALIGN=TOP>the classpath to use, given as a<a href="http://jakarta.apache.org/ant/manual/using.html#references"> | |||
reference</a> to a PATH defined elsewhere.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>bootclasspathref</td> | |||
<td VALIGN=TOP>location of bootstrap class files, given as a <a href="http://jakarta.apache.org/ant/manual/using.html#references">reference</a> | |||
to a PATH defined elsewhere.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>extdirs</td> | |||
<td VALIGN=TOP>location of installed extensions </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>debug</td> | |||
<td VALIGN=TOP>whether debug information should be included in classes output; | |||
defaults to <tt>false</tt>.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>deprecation</td> | |||
<td VALIGN=TOP>whether compiler should emit messages about | |||
usage of deprecated API; defaults to <tt>false</tt>.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>verbose</td> | |||
<td VALIGN=TOP>whether to emit compiler status messages during the compiler; | |||
defaults to <tt>false</tt>.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>version</td> | |||
<td VALIGN=TOP>print ajc version and exit</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>failonerror</td> | |||
<td VALIGN=TOP>whether the build continues notwithstanding compile errors; | |||
defaults to <tt>true</tt>. </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>source</td> | |||
<td VALIGN=TOP>Value of -source option - ignored unless "1.4"</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
</table> | |||
<h4> | |||
<a NAME="ajc-parameters-ignored"></a>Parameters that used to be ignored by | |||
the <code>ajc</code> taskdef, but now are supported or cause failures</h4> | |||
<table BORDER CELLSPACING=0 CELLPADDING=2 > | |||
<tr> | |||
<td VALIGN=TOP><b>Attribute</b></td> | |||
<td VALIGN=TOP><b>Description</b></td> | |||
<td ALIGN=CENTER VALIGN=TOP><b>Support</b></td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>encoding</td> | |||
<td VALIGN=TOP>encoding of source files.</td> | |||
<td ALIGN=CENTER VALIGN=TOP>Yes?</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>optimize</td> | |||
<td VALIGN=TOP>whether source should be compiled with optimization</td> | |||
<td ALIGN=CENTER VALIGN=TOP>Yes?</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>target</td> | |||
<td VALIGN=TOP>generate class files for specific VM version (e.g., <tt>1.1</tt> | |||
or <tt>1.2</tt>).</td> | |||
<td ALIGN=CENTER VALIGN=TOP>Yes</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>depend</td> | |||
<td VALIGN=TOP>enables dependency-tracking </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>includeAntRuntime</td> | |||
<td VALIGN=TOP>whether to include the Ant run-time libraries</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>includeJavaRuntime</td> | |||
<td VALIGN=TOP>whether to include the run-time libraries from the | |||
executing VM</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>threads</td> | |||
<td VALIGN=TOP>Multi-threaded compilation</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
</table> | |||
<h4> | |||
<a NAME="ajc-parameters"></a>Parameters unique to <code>ajc</code></h4> | |||
<u>Note</u>: Many of the unique parameters in AspectJ 1.0 are no longer supported, | |||
and fork is not supported yet. | |||
<table BORDER CELLSPACING=0 CELLPADDING=2 > | |||
<tr> <td VALIGN=TOP><b>Attribute</b></td> | |||
<td VALIGN=TOP><b>Description</b></td> | |||
<td ALIGN=CENTER VALIGN=TOP><b>Required</b></td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>X</td> | |||
<td VALIGN=TOP>comma-delimited list of extended (-X...) options, | |||
entered without -X | |||
(e.g., <code>X="lint"</code> for | |||
<code>-Xlint</code>). </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>emacssym</td> | |||
<td VALIGN=TOP>Generate symbols for Emacs IDE support | |||
(defaults to off)</td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
<tr> | |||
<td VALIGN=TOP>argfiles</td> | |||
<td VALIGN=TOP>a comma-delimited list of argfiles that | |||
contain a line-delimited list of source file paths | |||
(absolute or relative to the argfile) </td> | |||
<td ALIGN=CENTER VALIGN=TOP>No</td> | |||
</tr> | |||
</table> | |||
<a name="argfiles"></a> | |||
<h3>argfiles - Argument list files</h3> | |||
An argument file is a file (usually <tt><file>.lst</tt>) 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 <code>ajc</code> requires | |||
to avoid searching every possible source file in the source path when building aspects. | |||
If you specify an argfile to the <tt>ajc</tt> 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. | |||
<br> | |||
<a name="nestedElements"></a> | |||
<h3> | |||
Parameters specified as nested elements</h3> | |||
This task forms an implicit <a href="http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html">FileSet</a> | |||
and supports all attributes of <tt><fileset></tt> (<tt>dir</tt> becomes | |||
<tt>srcdir</tt>) | |||
as well as the nested | |||
<tt><include></tt>, <tt><exclude></tt>, | |||
<tt><patternset>, | |||
and <argfile></tt> elements. | |||
<h4> | |||
<tt>src</tt>, <tt>classpath</tt>, <tt>bootclasspath</tt> and <tt>extdirs</tt></h4> | |||
<tt>ajc</tt>'s <i>srcdir</i>, <i>classpath</i>, | |||
<i>bootclasspath, extdirs</i> | |||
and <i>jvmarg</i> attributes are <a href="http://jakarta.apache.org/ant/manual/using.html#path">path-like | |||
structures</a> and can also be set via nested | |||
<tt><src></tt>, | |||
<tt><classpath></tt>, | |||
<tt><bootclasspath>, | |||
<extdirs> </tt>and <tt><jvmarg> </tt>elements, respectively. | |||
<p> | |||
<h3> | |||
Examples</h3> | |||
See <a href="../examples/builds.xml">../examples/builds.xml</a> | |||
for an example build script. | |||
<p> | |||
This build script snippet | |||
<pre> <ajc srcdir="${src}" | |||
destdir="${build}" | |||
argfiles="demo.lst" | |||
/></pre> | |||
compiles all <tt>.java</tt> files specified in the <tt>demo.lst</tt> and | |||
stores the <tt>.class</tt> files in the <tt>${build}</tt> directory. | |||
Unlike the Javac task, the | |||
<i>includes</i> attribute is empty by default, so only those | |||
files specified in <tt>demo.lst</tt> are included. | |||
<p>This next example | |||
<pre> <ajc srcdir="${src}" | |||
destdir="${build}" | |||
includes="spacewar/*,coordination/*" | |||
excludes="spacewar/Debug.java" | |||
/></pre> | |||
compiles <tt>.java</tt> files under the <tt>${src}</tt> directory in the | |||
<tt>spacewar | |||
</tt>and<tt> | |||
coordination </tt>packages, and stores the | |||
<tt>.class</tt> files in the | |||
<tt>${build}</tt> directory. All source files under | |||
<tt>spacewar/</tt> and | |||
<tt>coordination/</tt> are used, except <tt>Debug.java</tt>. | |||
<hr> | |||
</body> | |||
</html> |
@@ -1,366 +0,0 @@ | |||
<html> | |||
<head> | |||
<title>AspectJ Ant Tasks</title> | |||
</head> | |||
<BODY> | |||
<h2 align="center">AspectJ Ant Tasks</h2> | |||
<p align="center"><i>Version @build.version.long@ released on @build.date@.</i></p> | |||
<h3>About the AspectJ Ant tasks</h3> | |||
AspectJ contains a compiler, <tt>ajc</tt>, that can be run from Ant. | |||
Included in the <tt>aspectjtools.jar</tt> are Ant binaries to support | |||
three ways of running the compiler: | |||
<ol> | |||
<li><tt><a href="#ajc10">Ajc10</a></tt> | |||
(<a href="ant-ajc10-task.html">parameters</a>), | |||
a task to run build scripts compatible with the AspectJ 1.0 tasks,</li> | |||
<li><tt><a href="#ajctask">AjcTask</a></tt> | |||
(<a href="ant-ajc-task.html">parameters</a>), | |||
a task to run the new AspectJ 1.1 compiler, which supports | |||
all the eclipse and ajc options, including incremental mode; | |||
<li><tt><a href="#adapter">Ajc11CompilerAdapter</a></tt>, | |||
an adapter class to run the new compiler using Javac tasks | |||
by setting the build.compiler property.</li> | |||
</ol> | |||
This describes how to install and use the tasks and the adapter. | |||
For an example Ant script, | |||
see <a href="examples/build.xml">examples/build.xml</a>. | |||
<h3>Installation</h3> | |||
<p>Install Jakarta Ant 1.5.1: | |||
Please see the official | |||
<a href="http://jakarta.apache.org/ant/index.html">Jakarta | |||
Ant website</a> for more information and | |||
the 1.5.1 <a href="http://jakarta.apache.org/builds/jakarta-ant/release/v1.5.1/bin/"> | |||
distribution</a>. | |||
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 <a href="http://eclipse.org/aspectj">http://eclipse.org/aspectj</a>. | |||
<p>In Ant, third-party tasks can be declared using a <tt>taskdef</tt> entry | |||
in the build script, to identify the name and classes. | |||
When declaring a task, include the <tt>aspectjtools.jar</tt> | |||
either in the taskdef classpath | |||
or in <tt>${ANT_HOME}/lib</tt> | |||
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: | |||
<pre> | |||
<taskdef | |||
resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties"> | |||
</pre> | |||
The current resource file retains the name "ajc" for the Ajc10 task, | |||
and uses "iajc" for the AspectJ 1.1 task. | |||
</p> | |||
<p>For more information on using Ant, please refer to | |||
Jakarta's <a href="http://jakarta.apache.org/ant/manual/develop.html">documentation</a> | |||
on integrating user-defined Ant tasks into builds.</p></li> | |||
<p> | |||
<h3><a name="ajc10">Ajc10 (script name: ajc) | |||
<small><a href="ant-ajc10-task.html">parameters</a></small> | |||
</a></h3> | |||
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.) | |||
<p> | |||
Following is a declaration for the ajc task and a sample invocation | |||
that uses the ajc compiler to compile the files listed in | |||
<tt>default.lst</tt> into the <tt>dest</tt> dir. | |||
<pre> | |||
<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> | |||
</pre> | |||
<h3><a name="ajctask">AjcTask (script name: iajc) | |||
<small><a href="ant-ajc-task.html">parameters</a></small> | |||
</a></h3> | |||
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. | |||
<p>A minimal build script defines the task | |||
and runs it, specifying the sources: | |||
<pre> | |||
<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> | |||
</pre> | |||
<p>Below is script with most everything in it. | |||
The compile process... | |||
<ul> | |||
<li>Runs in incremental mode, recompiling when the user | |||
hits return; | |||
</li> | |||
<li>Reads all the sources from two directories; | |||
</li> | |||
<li>Reads extrinsic module bytecode as input jar for weaving; | |||
</li> | |||
<li>Uses a binary aspect library for persistence; | |||
</li> | |||
<li>Outputs to an application jar; and | |||
</li> | |||
<li>Copies resources from the input jar and source directories | |||
into the application jar. | |||
</li> | |||
</ul> | |||
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. | |||
<pre> | |||
<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> | |||
</pre> | |||
<h3><a name="adapter">Ajc11CompilerAdapter</a></h3> | |||
This CompilerAdapter can be used in <tt>javac</tt> task calls | |||
by setting the <code>build.compiler</code> 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 | |||
<a href="#ajctask">AjcTask</a> where possible. | |||
<p>To build using the adapter, | |||
put the <tt>aspectjtools.jar</tt> on the system/ant | |||
classpath (e.g., in <tt>${ANT_HOME}/lib</tt>) | |||
and define the <tt>build.compiler</tt> | |||
property as the fully-qualified name of the class, | |||
<code>org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter</code>. | |||
The AspectJ compiler should run for any compile using the <tt>Javac</tt> 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 | |||
<code>src/org/aspectj/</code> subdirectories to the ajc command | |||
along with the destination directory: | |||
<pre> | |||
cp aspectj1.1/lib/aspectjtools.jar ant/lib | |||
ant/bin/ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter ... | |||
<javac srcdir="src" includes="org/aspectj/**/*.java" destdir="dest" /> | |||
</pre> | |||
<p> | |||
To pass <tt>ajc</tt>-specific arguments, use a <code>compilerarg</code> entry. | |||
<pre> | |||
Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter | |||
<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/> | |||
</pre> | |||
The adapter supports any <code>ajc</code> command-line option | |||
passed using <tt>compilerarg</tt>, as well as | |||
the following options available only in <code>AjcTask</code>. | |||
Find more details on the following options in the | |||
<a href="ant-ajc-task.html">AjcTask documentation</a>. | |||
<ul> | |||
<li>-Xmaxmem: set maximum memory for forking (also settable in javac) | |||
</li> | |||
<li>-Xlistfileargs: list file arguments (also settable in javac) | |||
</li> | |||
<li>-Xfailonerror: throw BuildException on compiler error (also settable in javac) | |||
</li> | |||
<li>-Xmessageholderclass: specify fully-qualified name of class | |||
to use as the message holder. | |||
</li> | |||
<li>-Xcopyinjars: copy resources from any input jars to output | |||
</li> | |||
<li>-Xsourcerootcopyfilter: copy resources from source directories | |||
to output (minus files specified in filter) | |||
</li> | |||
<li>-Xtagfile {file}: use file to control incremental compilation | |||
</li> | |||
<li>-Xsrcdir {dir}: add to list of ajc source roots | |||
(all source files will be included). | |||
</li> | |||
</ul> | |||
Note the names above may differ slightly here from what you might | |||
expect from AjcTask; use these forms when specifying <tt>compilerarg</tt>. | |||
<p>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). | |||
<p><u>Warning - use <code>build.compiler.clean</code></u> | |||
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., | |||
<pre> | |||
Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter | |||
-Dbuild.compiler.clean=anything ... | |||
</pre> | |||
Caveats to consider when using this global property: | |||
<ol> | |||
<li>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. | |||
</li> | |||
<li>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 <strong>all</strong> | |||
.class files. | |||
</li> | |||
<li>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. | |||
</li> | |||
<li>When running incrementally, the clean happens only before | |||
the initial compile. | |||
</li> | |||
</ol> | |||
<hr> | |||
<h3>4. What to do if you encounter problems</h3> | |||
<p>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. | |||
<p> | |||
<li>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.) </li> | |||
<li>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.</li> | |||
<li>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).</li> | |||
<p><b>Known Problems</b> | |||
<br>For the most up-to-date information on known problems, see the | |||
<a href="http://dev.eclipse.org/bugs">bug database</a> | |||
for unresolved | |||
<a href="http://dev.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=Compiler&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED">compiler bugs</a> | |||
or | |||
<a href="http://dev.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=Ant&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED">taskdef bugs</a>. | |||
<ul> | |||
<li><u>Memory and forking</u>: | |||
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. | |||
<p> | |||
Forking is <u>now supported</u> in both the adapter and AjcTask (iajc), | |||
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). | |||
</li> | |||
<ul> | |||
<p> | |||
You can send email to <a href="mailto:aspectj-users@dev.eclipse.org"> | |||
mailto:aspectj-users@dev.eclipse.org</a>. | |||
(Do join the list to participate!) We also welcome any bug reports; you can | |||
submit them to the bug database at | |||
<a href="http://dev.eclipse.org/bugs">http://dev.eclipse.org/bugs</a> | |||
using the <code>AspectJ</code> product and <code>Ant</code> component. | |||
</body> | |||
</html> |
@@ -25,7 +25,6 @@ | |||
<a href="quick.pdf">Quick Reference</a>, | |||
<a href="progguide/index.html">programming</a> and | |||
<a href="devguide/index.html">development</a> guides, | |||
<a href="ant-tasks.html">ant task summary</a>, | |||
<a href="api/overview-summary.html">API</a> and | |||
<a href="examples/">example code</a>. | |||
<tr><td><a href="#distributions">distributions</a></td><td> | |||
@@ -96,20 +95,15 @@ | |||
<!-- end strip --> | |||
) | |||
</td> | |||
<td>Find here a guide to the command-line compiler | |||
<a href="devguide/rn01re01.html">ajc</a> | |||
and the <u>AspectJ Development Environment (AJDE)</u> | |||
for managing crosscutting structure, shown in the stand-alone | |||
<a href="devguide/rn01re02.html">AspectJ Browser</a>. | |||
<td>Find here a guide to | |||
<a href="devguide/ajc-ref.html">ajc</a>, the command-line compiler; | |||
<a href="devguide/ajbrowser.html">ajbrowser</a>, the stand-alone | |||
GUI for compiling and viewing crosscutting structure; | |||
and the <a href="devguide/antTasks.html">Ant tasks</a> | |||
for building AspectJ programs. | |||
</td> | |||
</tr> | |||
<tr> <td><a href="ant-tasks.html">AspectJ Ant tasks</a> | |||
</td> | |||
<td>This shows how to use the tasks included | |||
in the <code>aspectjtools.jar</code>. | |||
</td> </tr> | |||
<tr> <td><a href="api/overview-summary.html">AspectJ API</a> | |||
<!-- start strip --> | |||
<!-- (<a href="http://eclipse.org/aspectj/doc/dist/api/overview-summary.html">web</a>) --> | |||
@@ -132,8 +126,7 @@ | |||
<!-- (<a href="http://eclipse.org/aspectj/doc/dist/porting.html">web</a>) --> | |||
<!-- end strip --> | |||
</td> | |||
<td>How users can convert code from pre-1.0 versions | |||
of AspectJ to 1.0. | |||
<td>How users can convert code from earlier versions of AspectJ. | |||
</td> </tr> | |||
<tr> <td><a href="changes.html"> Changes </a> | |||
@@ -238,8 +231,8 @@ | |||
on the | |||
<a href="mailto:aspectj-users@dev.eclipse.org"> | |||
aspectj-users@dev.eclipse.org</a> mail list. | |||
AspectJ Developers discuss issues with developing | |||
AspectJ on the | |||
AspectJ developers discuss issues with developing | |||
AspectJ tools on the | |||
<a href="mailto:aspectj-developers@dev.eclipse.org"> | |||
aspectj-developers@dev.eclipse.org</a> list. | |||
You can subscribe to the announce list | |||
@@ -299,7 +292,7 @@ | |||
<a href="progguide/index.html">Programming Guide</a>. | |||
View and navigate the crosscutting structure using | |||
the <code>ajbrowser</code> structure viewer, as described in | |||
the <a href="devguide/rn01re02.html">AspectJ Browser</a> section of | |||
the <a href="devguide/ajbrowser.html">AspectJ Browser</a> section of | |||
the <a href="devguide/index.html">Development Environment Guide</a>. | |||
<p> | |||
To start using AspectJ with your own code, |