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 | <html lang="en-us"><head>
|
---|
18 | <meta http-equiv="Content-Language" content="en-us"><link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
---|
19 | <title>Apt Task</title></head>
|
---|
20 |
|
---|
21 | <body>
|
---|
22 |
|
---|
23 | <h2><a name="Apt">Apt</a></h2>
|
---|
24 | <h3>Description</h3>
|
---|
25 | <p>Runs the annotation processor tool (apt), and then optionally compiles
|
---|
26 | the original code, and any generated source code. This task requires Java 1.5.
|
---|
27 | It may work on later versions, but this cannot be confirmed until those
|
---|
28 | versions ship. Be advised that the Apt tool does appear to be an unstable
|
---|
29 | part of the JDK framework, so may change radically in future versions.
|
---|
30 | In particular it is likely to be obsolete in JDK 6, which can run annotation
|
---|
31 | processors as part of javac.
|
---|
32 | If the <apt> task does break when upgrading JVM, please
|
---|
33 | check to see if there is a more recent version of Ant that tracks
|
---|
34 | any changes.</p>
|
---|
35 |
|
---|
36 |
|
---|
37 | <p>This task inherits from the <a href="javac.html">Javac Task</a>, and thus
|
---|
38 | supports nearly all of the same attributes, and subelements.
|
---|
39 | There is one special case, the <tt>fork</tt> attribute, which is present
|
---|
40 | but which can only be set to <tt>true</tt>. That is, apt only works as
|
---|
41 | a forked process.
|
---|
42 | </p>
|
---|
43 | <p>
|
---|
44 | In addition, it supports
|
---|
45 | the following addition items:</p>
|
---|
46 |
|
---|
47 | <h3>Parameters</h3>
|
---|
48 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
49 | <tbody><tr>
|
---|
50 | <td valign="top"><b>Attribute</b></td>
|
---|
51 | <td valign="top"><b>Description</b></td>
|
---|
52 | <td align="center" valign="top"><b>Required</b></td>
|
---|
53 | </tr>
|
---|
54 | <tr>
|
---|
55 | <td valign="top">compile</td>
|
---|
56 | <td valign="top">After running the Apt, should the code be compiled. (see the
|
---|
57 | <code>-nocompile</code> flag on the Apt executable)</td>
|
---|
58 | <td align="center" valign="top">No, defaults to false.</td>
|
---|
59 | </tr>
|
---|
60 | <tr>
|
---|
61 | <td valign="top">factory</td>
|
---|
62 | <td valign="top">The fully qualified classname of the AnnotationProcessFactory to be used
|
---|
63 | to construct annotation processors. This represents the <code>-factory</code>
|
---|
64 | command line flag of the Apt executable.</td>
|
---|
65 | <td align="center" valign="top">No</td>
|
---|
66 | </tr>
|
---|
67 | <tr>
|
---|
68 | <td valign="top">factorypathref</td>
|
---|
69 | <td valign="top">The reference id of the path used to find the classes needed by the
|
---|
70 | AnnotationProcessorFactory (and the location of the factory itself).
|
---|
71 | This represents the <code>-factorypath</code> flag on the Apt executable.</td>
|
---|
72 | <td align="center" valign="top">No</td>
|
---|
73 | </tr>
|
---|
74 | <tr>
|
---|
75 | <td valign="top">preprocessdir</td>
|
---|
76 | <td valign="top">The directory used for preprocessing. This is the directory where the
|
---|
77 | generated source code will be place. This represents the <code>-s</code> flag on
|
---|
78 | the Apt executable.</td>
|
---|
79 | <td align="center" valign="top">No</td>
|
---|
80 | </tr>
|
---|
81 | </tbody></table>
|
---|
82 |
|
---|
83 | <h3>Parameters specified as nested elements</h3>
|
---|
84 |
|
---|
85 |
|
---|
86 | <h4>factorypath</h4>
|
---|
87 |
|
---|
88 | <p>You can specify the path used to find the classes needed by the AnnotationProcessorFactory
|
---|
89 | at runtime, using this element. It is represents as a generic path like structure. This
|
---|
90 | represents the <code>-factorypath</code> flag on the Apt executable.</p>
|
---|
91 |
|
---|
92 |
|
---|
93 | <h4>option</h4>
|
---|
94 |
|
---|
95 | <p>Used to represent a generic option to pass to Apt. This represents the <code>-A</code> flag on the
|
---|
96 | Apt executable. You can specify zero or more <code><option></code> elements.</p>
|
---|
97 |
|
---|
98 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
99 | <tbody><tr>
|
---|
100 | <td valign="top" width="12%"><b>Attribute</b></td>
|
---|
101 | <td valign="top" width="78%"><b>Description</b></td>
|
---|
102 | <td valign="top" width="10%"><b>Required</b></td>
|
---|
103 | </tr>
|
---|
104 | <tr>
|
---|
105 | <td valign="top">name</td>
|
---|
106 | <td align="center">The name of the option</td>
|
---|
107 | <td align="center">Yes.</td>
|
---|
108 | </tr>
|
---|
109 | <tr>
|
---|
110 | <td valign="top">value</td>
|
---|
111 | <td align="center">The value to set the option to</td>
|
---|
112 | <td align="center">Yes.</td>
|
---|
113 | </tr>
|
---|
114 | </tbody></table>
|
---|
115 |
|
---|
116 | <h3>Examples</h3>
|
---|
117 | <blockquote><pre>
|
---|
118 | <apt srcdir="${src}"
|
---|
119 | destdir="${build}"
|
---|
120 | classpath="xyz.jar"
|
---|
121 | debug="on"
|
---|
122 | compile="true"
|
---|
123 | factory="com.mycom.MyAnnotationProcessorFactory"
|
---|
124 | factorypathref="my.factorypath.id"
|
---|
125 | preprocessdir="${preprocess.dir}">
|
---|
126 | </apt>
|
---|
127 | </pre></blockquote>
|
---|
128 | <p>compiles all <code>.java</code> files under the <code>${src}</code>
|
---|
129 | directory, and stores
|
---|
130 | the <code>.class</code> files in the <code>${build}</code> directory.
|
---|
131 | The classpath used includes <code>xyz.jar</code>, and compiling with
|
---|
132 | debug information is on. It also forces the generated source code to
|
---|
133 | be compiled. The generated source code will be placed in
|
---|
134 | <code>${preprocess.dir}</code> directory, using the class
|
---|
135 | <code>com.mycom.MyAnnotationProcessorFactory</code> to supply
|
---|
136 | AnnotationProcessor instances.</p>
|
---|
137 |
|
---|
138 |
|
---|
139 | <h3>Notes</h3>
|
---|
140 |
|
---|
141 | <p>
|
---|
142 | The inherited "fork" attribute is set to true by default; please do not change it.
|
---|
143 | </p>
|
---|
144 |
|
---|
145 | <p>
|
---|
146 | The inherited "compiler" attribute is ignored, as it is forced to use the Apt compiler
|
---|
147 | </p>
|
---|
148 |
|
---|
149 | <p>Using the Apt compiler with the "compile" option set to "true"
|
---|
150 | forces you to use Sun's Apt compiler, which will use the JDK's Javac compiler.
|
---|
151 | If you wish to use another compiler, you will first need run the Apt processor
|
---|
152 | with the "compile" flag set to "false", and then use a
|
---|
153 | <code><javac></code> task to compile first your original source code, and then the
|
---|
154 | generated source code:</p>
|
---|
155 |
|
---|
156 | <blockquote><pre>
|
---|
157 | <apt srcdir="${src}"
|
---|
158 | destdir="${build}"
|
---|
159 | classpath="xyz.jar"
|
---|
160 | debug="true"
|
---|
161 | compile="false"
|
---|
162 | factory="com.mycom.MyAnnotationProcessorFactory"
|
---|
163 | factorypathref="my.factorypath.id"
|
---|
164 | preprocessdir="${preprocess.dir}">
|
---|
165 | </apt>
|
---|
166 |
|
---|
167 | <javac srcdir="${src}"
|
---|
168 | destdir="${build}"
|
---|
169 | classpath="xyz.jar"
|
---|
170 | debug="on"/>
|
---|
171 |
|
---|
172 | <javac srcdir="${preprocess.dir}"
|
---|
173 | destdir="${build}"
|
---|
174 | classpath="xyz.jar"
|
---|
175 | debug="true"/>
|
---|
176 | </pre></blockquote>
|
---|
177 |
|
---|
178 | This may involve more build file coding, but the speedup gained from switching
|
---|
179 | to jikes may justify the effort.
|
---|
180 | <p>
|
---|
181 | </p>
|
---|
182 |
|
---|
183 | </body></html>
|
---|