1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
<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>Ajc10</tt> (<a href="ant-ajc10-task.html">options</a>),
a task to run build scripts compatible with the AspectJ 1.0 tasks,</li>
<li><tt>AjcTask</tt> (<a href="ant-ajc-task.html">options</a>),
a task to run the new AspectJ 1.1 compiler, which supports
all the eclipse and ajc options, including incremental mode;
<li><tt>Ajc11CompilerAdapter</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.
This may change in the final release of AspectJ 1.1. <!-- XXX -->
</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)</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)</a></h3>
This task handles all the ajc 1.1 compiler options,
as well as an incremental "tag" file to avoid depending
on Ant input/output for controlling Ant-based incremenal compilation.
<p>Below is an example of incrementally compiling <tt>src</tt>
and <tt>testsrc</tt> root source directories, using <tt>tagfile.txt</tt>
to control recompilation and halting.
When this script is run, the compiler will build once and
then wait for incremental builds, recompiling each time the
last-modified date changes on the tag file. When the tag file no longer
exists, the build will complete. Messages are printed as usual.
<pre>
<project name="incremental-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" >
<mkdir dir="dest" />
<iajc destdir="dest"
tagfile="tagfile.txt"
sourceroots="src${path.separator}testsrc" >
<!-- declare classes needed to compile the target files -->
<classpath>
<pathelement location="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/>
</classpath>
</iajc>
</target>
</project>
</pre>
<h3><a name="#adapter">Ajc11CompilerAdapter</a></h3>
This CompilerAdapter can be used in <tt>javac</tt> tasks calls
by setting the <code>build.compiler</code>
property to the class name. This enables users to
to easily switch between Javac and the AspectJ compiler.
To build this way, install <tt>aspectjtools.jar</tt> in <tt>${ANT_HOME}/lib</tt>
and define the <tt>build.compiler</tt>
property as the fully-qualified name of the class:
<pre>
cp aspectj1.1/lib/aspectjtools.jar ant/lib
ant/bin/ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter ...
</pre>
The AspectJ compiler should run for any compile using the <tt>Javac</tt> task
(for options, see the Ant documentation for the Javac task).
<p>
To pass <tt>ajc</tt>-specific arguments, use a <code>compilerarg</code> entry.
For example,
<pre>
-- command
Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11BuildCompiler
-- build script
<property name="ajc"
value="org.aspectj.tools.ant.taskdefs.Ajc11BuildCompiler"/>
<javac srcdir="src" destdir="dest" >
<compilerarg compiler="$${ajc}" line="-argfile src/args.lst"/>
<javac >
</pre>
Beware of using regular source lists with this; javac may prune unchanged
files, which excludes them from the compile process for ajc, which requires
that all files affected by any aspects be listed explicitly.
<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>.
<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.
<u>Forking is not supported in this release</u>, so the only solution is to
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>
<li><u>Messages suppressed</u>: In the incremental task,
messages from the compiler are printed but not segregated.
</li>
<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>
|
