source: other-projects/trunk/realistic-books/packages/AntInstaller/web/manual1.7.0/manual/OptionalTasks/jjtree.html@ 19253

Last change on this file since 19253 was 19253, checked in by davidb, 15 years ago

Establishing a source code repository for Veronica's Realistic Book's software
File size: 15.7 KB
Line 
1<!--
2 Licensed to the Apache Software Foundation (ASF) under one or more
3 contributor license agreements. See the NOTICE file distributed with
4 this work for additional information regarding copyright ownership.
5 The ASF licenses this file to You under the Apache License, Version 2.0
6 (the "License"); you may not use this file except in compliance with
7 the License. You may obtain a copy of the License at
8
9 http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16-->
17<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
18<html>
19<head>
20 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
21 <meta http-equiv="Content-Language" content="en-us">
22 <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
23<title>JJTree Task</title>
24</head>
25<body>
26
27<h2>
28<a NAME="jjtree"></a>JJTree</h2>
29
30<h3>
31Description</h3>
32<p>Invokes the <a href="http://javacc.dev.java.net/">JJTree</a> preprocessor
33for the JavaCC compiler compiler. It inserts parse tree building actions
34at various places in the JavaCC source that it generates. The output of
35JJTree is run through JavaCC to create the parser.
36<p>To use the jjtree task, set the <i>target</i> attribute to the name
37of the JJTree grammar file to process. You also need to specify the directory
38containing the JavaCC installation using the <i>javacchome</i> attribute,
39so that ant can find the JavaCC classes. Optionally, you can also set the
40<i>outputdirectory</i>
41to write the generated JavaCC grammar and node files to a specific directory.
42Otherwise jjtree writes the generated JavaCC grammar and node files to the directory
43containing the JJTree grammar file. As an extra option, you can also set the
44<i>outputfile</i> to write the generated JavaCC grammar file to a specific (directory and) file.
45Otherwise jjtree writes the generated JavaCC grammar file as the JJTree
46grammar file with a suffix .jj.</p>
47<p>This task only invokes JJTree if the grammar file is newer than the
48generated JavaCC file.</p>
49
50<h3>Parameters</h3>
51
52<table BORDER CELLSPACING=0 CELLPADDING=2 >
53<tr>
54<td VALIGN=TOP><b>Attribute</b></td>
55
56<td VALIGN=TOP><b>Description</b></td>
57
58<td ALIGN=CENTER VALIGN=TOP><b>Required</b></td>
59</tr>
60
61<tr>
62<td VALIGN=TOP>target</td>
63
64<td VALIGN=TOP>The jjtree grammar file to process.</td>
65
66<td ALIGN=CENTER VALIGN=TOP>Yes</td>
67</tr>
68
69<tr>
70<td VALIGN=TOP>javacchome</td>
71
72<td VALIGN=TOP>The directory containing the JavaCC distribution.</td>
73
74<td ALIGN=CENTER VALIGN=TOP>Yes</td>
75</tr>
76
77<tr>
78<td VALIGN=TOP>outputdirectory</td>
79
80<td VALIGN=TOP>The directory to write the generated JavaCC grammar and node files to.
81If not set, the files are written to the directory containing the grammar file.&nbsp;</td>
82
83<td ALIGN=CENTER VALIGN=TOP>No</td>
84</tr>
85
86<tr>
87<td VALIGN=TOP>outputfile</td>
88
89<td VALIGN=TOP>The file to write the generated JavaCC grammar file
90to. If not set, the file is written with the same name as the JJTree
91grammar file but with a the suffix <code>.jj</code>. This is a
92filename relative to <em>outputdirectory</em> if specified, the
93project's basedir.</td>
94
95<td ALIGN=CENTER VALIGN=TOP>No</td>
96</tr>
97
98<tr>
99<td VALIGN=TOP>buildnodefiles</td>
100
101<td VALIGN=TOP>Sets the BUILD_NODE_FILES grammar option. This is a boolean
102option.</td>
103
104<td ALIGN=CENTER VALIGN=TOP>No</td>
105</tr>
106
107<tr>
108<td VALIGN=TOP>multi</td>
109
110<td VALIGN=TOP>Sets the MULTI grammar option. This is a boolean option.</td>
111
112<td ALIGN=CENTER VALIGN=TOP>No</td>
113</tr>
114
115<tr>
116<td VALIGN=TOP>nodedefaultvoid</td>
117
118<td VALIGN=TOP>Sets the NODE_DEFAULT_VOID grammar option. This is a boolean
119option.</td>
120
121<td ALIGN=CENTER VALIGN=TOP>No</td>
122</tr>
123
124<tr>
125<td VALIGN=TOP>nodefactory</td>
126
127<td VALIGN=TOP>Sets the NODE_FACTORY grammar option. This is boolean option.</td>
128
129<td ALIGN=CENTER VALIGN=TOP>No</td>
130</tr>
131
132<tr>
133<td VALIGN=TOP>nodescopehook</td>
134
135<td VALIGN=TOP>Sets the NODE_SCOPE_HOOK grammar option. This is a boolean
136option.</td>
137
138<td ALIGN=CENTER VALIGN=TOP>No</td>
139</tr>
140
141<tr>
142<td VALIGN=TOP>nodeusesparser</td>
143
144<td VALIGN=TOP>Sets the NODE_USES_PARSER grammar option. This is a boolean
145option.</td>
146
147<td ALIGN=CENTER VALIGN=TOP>No</td>
148</tr>
149
150<tr>
151<td VALIGN=TOP>static</td>
152
153<td VALIGN=TOP>Sets the STATIC grammar option. This is a boolean option.</td>
154
155<td ALIGN=CENTER VALIGN=TOP>No</td>
156</tr>
157
158<tr>
159<td VALIGN=TOP>visitor</td>
160
161<td VALIGN=TOP>Sets the VISITOR grammar option. This is a boolean option.</td>
162
163<td ALIGN=CENTER VALIGN=TOP>No</td>
164</tr>
165
166<tr>
167<td VALIGN=TOP>nodepackage</td>
168
169<td VALIGN=TOP>Sets the NODE_PACKAGE grammar option. This is a string option.</td>
170
171<td ALIGN=CENTER VALIGN=TOP>No</td>
172</tr>
173
174<tr>
175<td VALIGN=TOP>visitorexception</td>
176
177<td VALIGN=TOP>Sets the VISITOR_EXCEPTION grammar option. This is a string
178option.</td>
179
180<td ALIGN=CENTER VALIGN=TOP>No</td>
181</tr>
182
183<tr>
184<td VALIGN=TOP>nodeprefix</td>
185
186<td VALIGN=TOP>Sets the NODE_PREFIX grammar option. This is a string option.</td>
187
188<td ALIGN=CENTER VALIGN=TOP>No</td>
189</tr>
190</table>
191
192<h3>
193Example</h3>
194
195<blockquote>
196<pre>&lt;jjtree&nbsp;
197&nbsp;&nbsp;&nbsp; target="src/Parser.jjt"&nbsp;
198&nbsp;&nbsp;&nbsp; outputdirectory="build/src"
199&nbsp;&nbsp;&nbsp; javacchome="c:/program files/JavaCC"&nbsp;
200&nbsp;&nbsp;&nbsp; nodeusesparser="true"
201/&gt;</pre>
202</blockquote>
203This invokes JJTree on grammar file src/Parser.jjt, writing the generated
204grammar file, Parser.jj, file to build/src. The grammar option NODE_USES_PARSER
205is set to true when invoking JJTree.
206<br>
207
208<h3>Comparison output locations between command line JJTree and different Ant taskdef versions</h3>
209
210<table cellpadding="3" border="1">
211<tr>
212 <td><b>Command Line JJTree options</b>
213 <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<i>and Generated Files</i> (working directory: <code>/tmp</code>)</td>
214 <td><b>Ant 1.5.3</b> versus command line</td>
215 <td><b>Ant 1.6</b> versus command line</td>
216</tr>
217<tr>
218 <td><pre><b>jjtree grammar.jjt</b>
219 /tmp/grammar.jj
220 /tmp/&lt;generated&gt;.java</pre>
221 </td>
222 <td>Same</td>
223 <td>Same</td>
224</tr>
225<tr>
226 <td><pre><b>jjtree relative/grammar.jjt</b>
227 /tmp/grammar.jj
228 /tmp/&lt;generated&gt;.java</pre>
229 </td>
230 <td><pre>
231/tmp/relative/grammar.jj
232/tmp/relative/&lt;generated&gt;.java</pre>
233 </td>
234 <td>Same</td>
235</tr>
236<tr>
237 <td><pre><b>jjtree /tmp/absolute/grammar.jjt</b>
238 /tmp/grammar.jj
239 /tmp/&lt;generated&gt;.java</pre>
240 </td>
241 <td><pre>
242/tmp/absolute/grammar.jj
243/tmp/absolute/&lt;generated&gt;.java</pre>
244 </td>
245 <td>Same</td>
246</tr>
247<tr>
248 <td><pre><b>jjtree -OUTPUT_DIRECTORY:relative grammar.jjt</b>
249 /tmp/relative/grammar.jj
250 /tmp/relative/&lt;generated&gt;.java</pre>
251 </td>
252 <td>Same</td>
253 <td>Same</td>
254</tr>
255<tr>
256 <td><pre><b>jjtree -OUTPUT_DIRECTORY:relative relative/grammar.jjt</b>
257 /tmp/relative/grammar.jj
258 /tmp/relative/&lt;generated&gt;.java</pre>
259 </td>
260 <td>Same</td>
261 <td>Same</td>
262</tr>
263<tr>
264 <td><pre><b>jjtree -OUTPUT_DIRECTORY:relative /tmp/absolute/grammar.jjt</b>
265 /tmp/relative/grammar.jj
266 /tmp/relative/&lt;generated&gt;.java</pre>
267 </td>
268 <td>Same</td>
269 <td>Same</td>
270</tr>
271<tr>
272 <td><pre><b>jjtree -OUTPUT_DIRECTORY:/tmp/absolute/ grammar.jjt</b>
273 /tmp/absolute/grammar.jj
274 /tmp/absolute/&lt;generated&gt;.java</pre>
275 </td>
276 <td>Same</td>
277 <td>Same</td>
278</tr>
279<tr>
280 <td><pre><b>jjtree -OUTPUT_DIRECTORY:/tmp/absolute/ relative/grammar.jjt</b>
281 /tmp/absolute/grammar.jj
282 /tmp/absolute/&lt;generated&gt;.java</pre>
283 </td>
284 <td>Same</td>
285 <td>Same</td>
286</tr>
287<tr>
288 <td><pre><b>jjtree -OUTPUT_DIRECTORY:/tmp/absolute/ /tmp/absolute/grammar.jjt</b>
289 /tmp/absolute/grammar.jj
290 /tmp/absolute/&lt;generated&gt;.java</pre>
291 </td>
292 <td>Same</td>
293 <td>Same</td>
294</tr>
295<tr>
296 <td><pre><b>jjtree -OUTPUT_FILE:output.jj grammar.jjt</b>
297 /tmp/output.jj
298 /tmp/&lt;generated&gt;.java</pre>
299 </td>
300 <td>Not Supported</td>
301 <td>Same</td>
302</tr>
303<tr>
304 <td><pre><b>jjtree -OUTPUT_FILE:output.jj relative/grammar.jjt</b>
305 /tmp/output.jj
306 /tmp/&lt;generated&gt;.java</pre>
307 </td>
308 <td>Not Supported</td>
309 <td>Same</td>
310</tr>
311<tr>
312 <td><pre><b>jjtree -OUTPUT_FILE:output.jj /tmp/absolute/grammar.jjt</b>
313 /tmp/output.jj
314 /tmp/&lt;generated&gt;.java</pre>
315 </td>
316 <td>Not Supported</td>
317 <td>Same</td>
318</tr>
319<tr>
320 <td><pre><b>jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:relative grammar.jjt</b>
321 /tmp/relative/output.jj
322 /tmp/relative/&lt;generated&gt;.java</pre>
323 </td>
324 <td>Not Supported</td>
325 <td>Same</td>
326</tr>
327<tr>
328 <td><pre><b>jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:relative relative/grammar.jjt</b>
329 /tmp/relative/output.jj
330 /tmp/relative/&lt;generated&gt;.java</pre>
331 </td>
332 <td>Not Supported</td>
333 <td>Same</td>
334</tr>
335<tr>
336 <td><pre><b>jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:relative /tmp/absolute/grammar.jjt</b>
337 /tmp/relative/output.jj
338 /tmp/relative/&lt;generated&gt;.java</pre>
339 </td>
340 <td>Not Supported</td>
341 <td>Same</td>
342</tr>
343<tr>
344 <td><pre><b>jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ grammar.jjt</b>
345 /tmp/absolute/output.jj
346 /tmp/absolute/&lt;generated&gt;.java</pre>
347 </td>
348 <td>Not Supported</td>
349 <td>Same</td>
350</tr>
351<tr>
352 <td><pre><b>jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ relative/grammar.jjt</b>
353 /tmp/absolute/output.jj
354 /tmp/absolute/&lt;generated&gt;.java</pre>
355 </td>
356 <td>Not Supported</td>
357 <td>Same</td>
358</tr>
359<tr>
360 <td><pre><b>jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ /tmp/absolute/grammar.jjt</b>
361 /tmp/absolute/output.jj
362 /tmp/absolute/&lt;generated&gt;.java</pre>
363 </td>
364 <td>Not Supported</td>
365 <td>Same</td>
366</tr>
367<tr>
368 <td><pre><b>jjtree -OUTPUT_FILE:subdir/output.jj grammar.jjt</b>
369 /tmp/subdir/output.jj
370 /tmp/&lt;generated&gt;.java</pre>
371 </td>
372 <td>Not Supported</td>
373 <td>Same</td>
374</tr>
375<tr>
376 <td><pre><b>jjtree -OUTPUT_FILE:subdir/output.jj relative/grammar.jjt</b>
377 /tmp/subdir/output.jj
378 /tmp/&lt;generated&gt;.java</pre>
379 </td>
380 <td>Not Supported</td>
381 <td>Same</td>
382</tr>
383<tr>
384 <td><pre><b>jjtree -OUTPUT_FILE:subdir/output.jj /tmp/absolute/grammar.jjt</b>
385 /tmp/subdir/output.jj
386 /tmp/&lt;generated&gt;.java</pre>
387 </td>
388 <td>Not Supported</td>
389 <td>Same</td>
390</tr>
391<tr>
392 <td><pre><b>jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:relative grammar.jjt</b>
393 /tmp/relative/subdir/output.jj
394 /tmp/relative/&lt;generated&gt;.java</pre>
395 </td>
396 <td>Not Supported</td>
397 <td>Same</td>
398</tr>
399<tr>
400 <td><pre><b>jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:relative relative/grammar.jjt</b>
401 /tmp/relative/subdir/output.jj
402 /tmp/relative/&lt;generated&gt;.java</pre>
403 </td>
404 <td>Not Supported</td>
405 <td>Same</td>
406</tr>
407<tr>
408 <td><pre><b>jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:relative /tmp/absolute/grammar.jjt</b>
409 /tmp/relative/subdir/output.jj
410 /tmp/relative/&lt;generated&gt;.java</pre>
411 </td>
412 <td>Not Supported</td>
413 <td>Same</td>
414</tr>
415<tr>
416 <td><pre><b>jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ grammar.jjt</b>
417 /tmp/absolute/subdir/output.jj
418 /tmp/absolute/&lt;generated&gt;.java</pre>
419 </td>
420 <td>Not Supported</td>
421 <td>Same</td>
422</tr>
423<tr>
424 <td><pre><b>jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ relative/grammar.jjt</b>
425 /tmp/absolute/subdir/output.jj
426 /tmp/absolute/&lt;generated&gt;.java</pre>
427 </td>
428 <td>Not Supported</td>
429 <td>Same</td>
430</tr>
431<tr>
432 <td><pre><b>jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ /tmp/absolute/grammar.jjt</b>
433 /tmp/absolute/subdir/output.jj
434 /tmp/absolute/&lt;generated&gt;.java</pre>
435 </td>
436 <td>Not Supported</td>
437 <td>Same</td>
438</tr>
439<tr>
440 <td><pre><b>jjtree -OUTPUT_FILE:/tmp/subdir/output.jj grammar.jjt</b>
441 /tmp/subdir/output.jj
442 /tmp/&lt;generated&gt;.java</pre>
443 </td>
444 <td>Not Supported</td>
445 <td>Same</td>
446</tr>
447<tr>
448 <td><pre><b>jjtree -OUTPUT_FILE:/tmp/subdir/output.jj relative/grammar.jjt</b>
449 /tmp/subdir/output.jj
450 /tmp/&lt;generated&gt;.java</pre>
451 </td>
452 <td>Not Supported</td>
453 <td>Same</td>
454</tr>
455<tr>
456 <td><pre><b>jjtree -OUTPUT_FILE:/tmp/subdir/output.jj /tmp/absolute/grammar.jjt</b>
457 /tmp/subdir/output.jj
458 /tmp/&lt;generated&gt;.java</pre>
459 </td>
460 <td>Not Supported</td>
461 <td>Same</td>
462</tr>
463<tr>
464 <td><pre><b>jjtree -OUTPUT_FILE:<i><u>D:</u></i>/tmp/subdir/output.jj grammar.jjt</b>
465 /tmp/subdir/output.jj
466 /tmp/&lt;generated&gt;.java</pre>
467 </td>
468 <td>Not Supported</td>
469 <td>Not Supported *)</td>
470</tr>
471<tr>
472 <td><pre><b>jjtree -OUTPUT_FILE:<i><u>D:</u></i>/tmp/subdir/output.jj relative/grammar.jjt</b>
473 /tmp/subdir/output.jj
474 /tmp/&lt;generated&gt;.java</pre>
475 </td>
476 <td>Not Supported</td>
477 <td>Not Supported *)</td>
478</tr>
479<tr>
480 <td><pre><b>jjtree -OUTPUT_FILE:<i><u>D:</u></i>/tmp/subdir/output.jj /tmp/absolute/grammar.jjt</b>
481 /tmp/subdir/output.jj
482 /tmp/&lt;generated&gt;.java</pre>
483 </td>
484 <td>Not Supported</td>
485 <td>Not Supported *)</td>
486</tr>
487<tr>
488 <td><pre><b>jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:relative grammar.jjt</b>
489 /tmp/relative/tmp/subdir/output.jj
490 /tmp/relative/&lt;generated&gt;.java</pre>
491 </td>
492 <td>Not Supported</td>
493 <td>Same</td>
494</tr>
495<tr>
496 <td><pre><b>jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:relative relative/grammar.jjt</b>
497 /tmp/relative/tmp/subdir/output.jj
498 /tmp/relative/&lt;generated&gt;.java</pre>
499 </td>
500 <td>Not Supported</td>
501 <td>Same</td>
502</tr>
503<tr>
504 <td><pre><b>jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:relative /tmp/absolute/grammar.jjt</b>
505 /tmp/relative/tmp/subdir/output.jj
506 /tmp/relative/&lt;generated&gt;.java</pre>
507 </td>
508 <td>Not Supported</td>
509 <td>Same</td>
510</tr>
511<tr>
512 <td><pre><b>jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ grammar.jjt</b>
513 /tmp/absolute/tmp/subdir/output.jj
514 /tmp/absolute/&lt;generated&gt;.java</pre>
515 </td>
516 <td>Not Supported</td>
517 <td>Same</td>
518</tr>
519<tr>
520 <td><pre><b>jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ relative/grammar.jjt</b>
521 /tmp/absolute/tmp/subdir/output.jj
522 /tmp/absolute/&lt;generated&gt;.java</pre>
523 </td>
524 <td>Not Supported</td>
525 <td>Same</td>
526</tr>
527<tr>
528 <td><pre><b>jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ /tmp/absolute/grammar.jjt</b>
529 /tmp/absolute/tmp/subdir/output.jj
530 /tmp/absolute/&lt;generated&gt;.java</pre>
531 </td>
532 <td>Not Supported</td>
533 <td>Same</td>
534</tr>
535</table>
536
537<p>*) <u>Footnote</u>: When running JJTree with the Ant taskdef <i>jjtree</i> the option <code>-OUTPUT_DIRECTORY</code> must always
538be set, because the project's basedir and the ant working directory might differ. So even if you don't specify the jjtree taskdef
539<i>outputdirectory</i> JJTree will be called with the <code>-OUTPUT_DIRECTORY</code> set to the project's basedirectory.
540But when the <code>-OUTPUT_DIRECTORY</code> is set, the <code>-OUTPUT_FILE</code> setting is handled as if relative to this
541<code>-OUTPUT_DIRECTORY</code>. Thus when the <code>-OUTPUT_FILE</code> is absolute or contains a drive letter we have a
542problem.
543Therefore absolute <i>outputfile</i>s (when the <i>outputdirectory</i> isn't specified) are made relative to the default directory.
544And for this reason <i>outputfile</i>s that contain a drive letter can't be supported.</p>
545
546<p>By the way: specifying a drive letter in the <code>-OUTPUT_FILE</code> when the <code>-OUTPUT_DIRECTORY</code> is set, also
547results in strange behavior when running JJTree from the command line.</p>
548
549<br>
550
551
552
553
554</body>
555</html>
556
Note: See TracBrowser for help on using the repository browser.