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
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
|
<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> 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.
However, javac's handling 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.
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, this 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>
-- 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" />
</pre>
<p>
To pass <tt>ajc</tt>-specific arguments, use a <code>compilerarg</code> entry.
<pre>
-- 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 >
</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 AjcTask.
Find more details on the following options in the
<a href="ant-ajc-task.html">AjcTask</a> documentation.
<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><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>
|
