source: release-kits/lirk3/resources/gs3-release-maker/ant/docs/ant2/actionlist.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

initial import of LiRK3
File size: 20.1 KB
Line 
1<html>
2 <head><title>Ant1.9 Action List</title></head>
3 <body bgcolor="#ffffff">
4 <center>
5 <h1>Ant1.9 Action List</h1>
6 <h2>Precursor to Ant2</h2>
7 <i>Peter Donald [<a href="mailto:peter at apache.org">peter at apache.org</a>]</i>
8 </center>
9
10 <div align="center">
11 <table width="80%"><tr><td>
12 <blockquote>
13 <p>
14 This document aims to contain a list of actions that people can take
15 to produce Ant1.9. Ant1.9 is a refactoring of the Ant1.x line and a jump
16 point for Ant2. Some changes will be backported to Ant1.x over time when
17 they have proven themselves while other changes may only become available
18 via Ant2.0. Ant1.9 is our melting pot where we can experiment and refactor
19 without a thought to backwards compatability but only to the "right" way
20 of doing things.
21 </p>
22 </blockquote></td></tr>
23 </table>
24 </div>
25
26 <h2>Introduction</h2>
27
28 <blockquote>
29 <p>
30 This document will list a bunch of actions that will guide us in the evolution
31 of Ant1.x and provide a solid basis on which to launch Ant2.0. Feel free to add to
32 this list of actions as our vision of Ant2 solidifies. Associated with each action
33 is a list of victims who have "volunteered" to have a go at the action and a status.
34 The status just tells us where they are at while the victim column will tell us exactly
35 who is doing what. It is fine for a group of people to work on a single area.
36 </p>
37 <br />
38 <br />
39 <br />
40 <div align="center">
41 <table cellspacing="2" cellpadding="5" width="80%">
42 <tr>
43 <td bgcolor="#eeeeee" align="center">Action</td>
44 <td bgcolor="#eeeeee" align="center">Victims</td>
45 <td bgcolor="#eeeeee" align="center">Status</td>
46 </tr>
47 <tr>
48 <td><a href="#vfs">Create a Virtual Filesystem layer</a></td>
49 <td>None</td>
50 <td>Not Started</td>
51 </tr>
52 <tr>
53 <td><a href="#naming">Formalize a naming scheme for task attributes/elements</a></td>
54 <td>None</td>
55 <td>Not Started</td>
56 </tr>
57 <tr>
58 <td><a href="#selector">Design and implement s Selector API for Filesets and other Itemsets</a></td>
59 <td>None</td>
60 <td>Not Started</td>
61 </tr>
62 <tr>
63 <td><a href="#coloring">Develope the infrastructure for coloring (or "environmental" dependency analysis)</a></td>
64 <td>None</td>
65 <td>Not Started</td>
66 </tr>
67 <tr>
68 <td><a href="#structural">Develope the infrastructure for structural dependency analysis</a></td>
69 <td>None</td>
70 <td>Not Started</td>
71 </tr>
72 <tr>
73 <td><a href="#exec">Refactor the Exec infrastructure into JavaBeans</a></td>
74 <td>Peter Donald</td>
75 <td>80%</td>
76 </tr>
77 <tr>
78 <td><a href="#java">Refactor the Java infrastructure into JavaBeans</a></td>
79 <td>None</td>
80 <td>Not Started</td>
81 </tr>
82 <tr>
83 <td><a href="#facade">Design and implement a generic solution for creating Task facades</a></td>
84 <td>None</td>
85 <td>Not Started</td>
86 </tr>
87 <tr>
88 <td><a href="#packaging">Sketch out a basic way of separating all the tasks into type libraries</a></td>
89 <td>None</td>
90 <td>Not Started</td>
91 </tr>
92 <tr>
93 <td><a href="#mapperext">Design and implement an API that allows mapping of file attributes during copy/move/etc tasks</a></td>
94 <td>None</td>
95 <td>Not Started</td>
96 </tr>
97 <tr>
98 <td><a href="#filters">Design and implement an API so that Filters could be implemented as FilteredOutputStreams</a></td>
99 <td>None</td>
100 <td>Not Started</td>
101 </tr>
102 <tr>
103 <td><a href="#catalog">Design and implement a XML "catalog" so the snippets of XML can be injected based on URI rather than relative location</a></td>
104 <td>None</td>
105 <td>Not Started</td>
106 </tr>
107 <tr>
108 <td><a href="#i18n">Look at the feasability of i18n'ing tasks and the runtime</a></td>
109 <td>None</td>
110 <td>Not Started</td>
111 </tr>
112 <tr>
113 <td><a href="#doco">Write a document describing the way that tasks should be written in context of Ant2</a></td>
114 <td>Peter Donald<br />(peter at apache.org)</td>
115 <td>Not Started</td>
116 </tr>
117 <tr>
118 <td><a href="#embeddor">Design an API to embed Ant into other applications</a></td>
119 <td>None</td>
120 <td>Not Started</td>
121 </tr>
122 <tr>
123 <td><a href="#info">Design a TypeInfo system similar to BeanInfo to describe Tasks</a></td>
124 <td>None</td>
125 <td>Not Started</td>
126 </tr>
127 <tr>
128 <td><a href="#antdoc">Design Antdoc to generate manual from .java files</a></td>
129 <td>None</td>
130 <td>Not Started</td>
131 </tr>
132 </table>
133 </div>
134 </blockquote>
135
136 <h3>Virtual File System</h3>
137 <a name="vfs" />
138 <blockquote>
139 <p>
140 There has long been a recognition that it would be nice if ant supported some
141 notion of a virtual filesystem layer. This layer would allow you to treat
142 resources located and retrieved from different mechanisms in a uniform way.
143 For instance it would allow the copy task to copy from a http server, a cvs server,
144 a ftp server or the local filesystem using a uniform mechanism. So instead of
145 having separate tasks to operate on each different resource type we would use
146 just one task that plugged into multiple filesystems.
147 </p>
148 <p>
149 When we are talking about a virtual filesystem or VFS, one of the concerns we must
150 address is how to "name" the resource. In most cases a URL or URI style access will
151 be sufficient but in other cases we may need to consider other options. So
152 "cvs://localhost:/home/cvs/jakarta-avalon/README.txt?version=1.1",
153 "ftp://some.server.com/dir/file.zip" and "file://C/WINDOWS/Desktop/MyFile.txt"
154 are all examples of referring to different resources.
155 </p>
156 <p>
157 Another concern that must be addressed is capabilities of both the resources and
158 the filesystem. For instance it is possible to both read and write to resources
159 using the "file" protocol but only possible to write resources using "mailto".
160 The act of copying a file to a "mailto" url would actuall post the files as
161 resources while copying to a "file" would duplicate the resource somewhere on
162 the local filesystem.
163 </p>
164 <p>
165 So we need to determine a list of capabilities. Some examples would be "read",
166 "write", "list" (can you list dirs), "type" (can you get mime type),
167 "access permissions" (can you tell if resource has permissions),
168 "modify permissions" (can you modify permissions) etc. Some of these capabilities
169 can be associated with the particular reosurces, while others may need to be
170 associated with a whole filesystem/protocol (ie there is no standard mechanism
171 to perform "list" on general "http" URLs). Thus a list of all these capabilities
172 and mapping to various protocols will need to be established.
173 </p>
174 <p>
175 Next we need to determine if we are going to support the notion of "mounting"
176 URLs. For instance if we need to copy files from a FTP server do we allways
177 need to specify the full URL - no matter how convoluted it is (ie
178 "ftp://fred:[email protected]:28763/home/fred/project2/dir/file.zip")
179 or can we mount this on a VFS and access it via that shorter url. ie We could
180 mount "ftp://fred:[email protected]:28763/home/fred/" onto "vfs:/home"
181 and then just access the resources via "vfs:/home/project2/dir/file.zip".
182 This would make dealing with large urls easier and more uniform.
183 </p>
184 <p>
185 So after we have decided what our options are we need to actually go about
186 implementing the solution. It may be the case that existing VFS solutions
187 could be reused with minor changes and thus we could save ourselves a lot of
188 work. Candidates would be the Netbeans VFS, Suns XFile API or other
189 available directory APIs (like JNDI). If none of them suit then we will need
190 to write our own layer.
191 </p>
192 </blockquote>
193
194 <h3>Naming</h3>
195 <a name="naming" />
196 <blockquote>
197 <p>
198 Currently Ant has a mixture of tasks from various stages it's evolution, with different
199 authors and each utilizing different naming patterns. Some tasks use names such as
200 "src" and "dest" while others use "file" and "tofile". It would be preferrable if
201 consistent naming patterns were used. It is recomended that we come up with a "best
202 practices" document to document our recomended naming patterns.
203 </p>
204 <p>
205 Before we can come up with such a document we need to identify common patterns through
206 out the tasks. Several tasks have the notion of transforming input from a "source"
207 to a "destination". So we should have consistent naming schemes for these attributes and
208 elements. Analysis of existing tasks will likely bring out other similar patterns. Once
209 we have identified and documented these similarities then we can establish conventions.
210 </p>
211 </blockquote>
212
213 <h3>Selector API</h3>
214 <a name="selector" />
215 <blockquote>
216 <p>
217 Currently our filesets allow us to select a set of files based on name patterns.
218 For instance we could create a set of all the files that end with ".java". However
219 there are cases when you wish to select files based on their other attributes, such as
220 if they are read only or if they are older than a specified date etc.
221 </p>
222 <p>
223 The selector API is one such mechanism to do this. The selector API will allow you to
224 build file sets based on criteria other than name. Some possible criteria would be
225 </p>
226 <ul>
227 <li>Is the file readable?</li>
228 <li>Is the file writeable?</li>
229 <li>What date was the file modified on?</li>
230 <li>What size is the file?</li>
231 <li>Does the contents contain the string "magic"?</li>
232 </ul>
233 <p>
234 If we end up supporting a VFS then we could expand the number of selectors
235 considerably. A mock representation that has been proposed before is the following.
236 Of course this is subject to change as soon as someone wants to tackle this action ;)
237 </p>
238<pre>
239 &lt;include&gt;
240 &lt;selector type="name" value="**/*.java"/&gt;
241 &lt;selector type="permission" value="r"/&gt;
242
243 &lt;!-- could optionally be directory/or some other system specific features --&gt;
244 &lt;selector type="type" value="file"/&gt;
245 &lt;selector type="modify-time"
246 operation="greater-than"
247 value="29th Feb 2003"/&gt;
248 &lt;/include&gt;
249</pre>
250 </blockquote>
251
252 <h3>Coloring API</h3>
253 <a name="coloring" />
254 <blockquote>
255 <p>
256 When you execute a task such as "javac" there is two types of dependency information
257 that is important to analyze before we determine if we need to recompile a file. Say
258 we are compiling <code>Foo.java</code>, it may depend on the <code>Bar.java</code>
259 file. We call this "structural" dependency information - the structure of the source file
260 determines what other files it depend upon. However there is also "environmental"
261 dependency information. For instance if the <code>Foo.java</code> file was compiled with
262 <code>debug="true"</code> last run and this time needs to be compiled with
263 <code>debug="false"</code> then it is out of date and needs to be recompiled. We call this
264 "environmental" dependency information "coloring".
265 </p>
266 <p>
267 So we need to create an infrastructure that allows tasks to manage "coloring". So a task
268 should be able to add coloring information for each resource processed. When the task
269 comes to process the resource again it will detect if the coloring has changed and if it
270 has will force a recompile.
271 </p>
272 <p>
273 An API for such a bean has yet to be established but an example API would be.
274 </p>
275 <pre>
276ColoringManager cm = ...;
277cm.addColor( "debug", "true" );
278cm.addColor( "optimize", "false" );
279cm.setFileSet( myFileSet );
280File[] files = cm.getOutOfDate();
281 </pre>
282 </blockquote>
283
284 <h3>Structural Dependency Utils</h3>
285 <a name="structural" />
286 <blockquote>
287 <p>
288 In the present ant, it is required that each task manage dependency separately.
289 This makes it a lot of work to implement even simple dependency checking. To this
290 day many of the core tasks do not implement it correctly. I am specifically
291 talking about "structural" dependency information. The main reason is that it is
292 painful to implement.
293 </p>
294 <p>
295 Some tasks do no dependency checking and will recompile/transform/etc everytime.
296 Others may perform a simple dependency checking (ie if source file is newer than
297 destination file then recompile). Ideally a dependency system would actually
298 calculate the dependencies correctly. So we need to have some mechanism to determine
299 that <code>foo.c</code> actually depends upon <code>foo.h</code>, <code>bar.h</code>
300 and <code>baz.h</code>. As this information is particular to each different task
301 we need to allow tasks to implement this behaviour. Possibly by supplying an interface
302 of the form;
303 </p>
304 <pre>
305public interface DependencyGenerator
306{
307 File[] generateDependencies( File file );
308}
309 </pre>
310 <p>
311 Generating the dependency information is a costly operation and thus we do not want to
312 be doing it everytime you run ant. We want to generate it on the initial build and then
313 persist somewhere. Everytime a file is out of date, it's dependency information would
314 be regenerated and stored in the dependency cache. Ideally this cache would also store the
315 above mentioned coloring information. So the entry for <code>foo.c</code> may declare that
316 it is dependent upon <code>foo.h</code>, <code>bar.h</code> and <code>baz.h</code>, aswell
317 as being compiled with -O2 flag. If any of the dependencies have changed or are out of date
318 then foo.c would need to be recompiled.
319 </p>
320 <p>
321 A possible API would be
322 </p>
323 <pre>
324DependencyManager dm = ...;
325dm.setFileSet( myFileSet );
326dm.setDependencyCache( myDependencyCacheFile );
327File[] files = cm.getOutOfDate();
328 </pre>
329 </blockquote>
330
331 <h3>Refactor &lt;exec&gt; infrastructure into Beans</h3>
332 <a name="exec" />
333 <blockquote>
334 <p>
335 Exec and its related classes have currently evolved through several iterations and thus
336 it is not as cleanly designed and as reusable as it could be. Someone needs to pull apart
337 exec and analyze which parts can be turned into JavaBeans and decouple them from the Ant
338 infrastructure. Once that is done it will make these beans much easier to reuse from other
339 tasks without relying on gaining access to the other task instance.
340 </p>
341 </blockquote>
342
343 <h3>Refactor &lt;java&gt; infrastructure into Beans</h3>
344 <a name="java" />
345 <blockquote>
346 <p>
347 Much like Exec should be decoupled from Ant runtime, so should classes to implement java
348 task for the same benefits.
349 </p>
350 </blockquote>
351
352 <h3>Generic Task Facades</h3>
353 <a name="facade" />
354 <blockquote>
355 <p>
356 Currently we have a few tasks that have multiple implementations. For instance Javac task
357 can actually call jikes, jvc, classic javac or modern javac. Similar things will be seen
358 with the jspc task and the cc task (if it ever gets written). We need to examine this
359 pattern and see if there is a way to generalize this and make it easier to write such tasks.
360 </p>
361 </blockquote>
362
363 <h3>Task Packaging</h3>
364 <a name="packaging" />
365 <blockquote>
366 <p>
367 We have already decided that we are going to package Ant tasks in separate jars and
368 have some sort of descriptor that to describe the contents of the jar. However we have
369 not yet decided how we will break up the tasks. Do we break up the tasks up into
370 related tasks or into groups that ar elikely to be used together or what? A possible
371 breakdown would be
372 </p>
373 <ul>
374 <li>jdk tasks: javac, javadoc, rmic etc</li>
375 <li>text tasks: regex replace, fixcrlf etc</li>
376 <li>unix tasks: chmod, etc</li>
377 <li>file tasks: copy, move, etc</li>
378 </ul>
379 </blockquote>
380
381 <h3>Mapping File Attributes during transformation</h3>
382 <a name="mapperext" />
383 <blockquote>
384 <p>
385 When we are copying files from one location to another it is currently possible
386 to rename them using a mapper. So we could rename <code>Foo.java</code> to
387 <code>Foo.java.bak</code>. On occasion it is useful to modify file attributes
388 other than its name in such operations. So we could copy the files to another
389 location and make them read-only in one operation.
390 </p>
391 </blockquote>
392
393 <h3>Filters extensions</h3>
394 <a name="filters" />
395 <blockquote>
396 <p>
397 This is partially related to the above action. Filters could be seen as a way
398 to modify the content attribute of a file during a copy/move. It would be
399 preferrable if filtering could be abstracted to use <code>FilteredOutputStream</code>s
400 to perform the content modification. That way new Filter types could be constructed
401 and used during file copy (ie an example would be a Perl FilterOutputStream that
402 allowed you to use perl expressions to transform input).
403 </p>
404 </blockquote>
405
406 <h3>XML Catalog to load XML Fragments</h3>
407 <a name="catalog" />
408 <blockquote>
409 <p>
410 When including fragments of XML we are currently forced to use relative paths.
411 However this is sometimes undesirable when a single fragment needs to be used
412 across several projects in several different locations. Instead we could use
413 a Catalog to name the fragment and then each developer would only need to install
414 the fragment once and it would be accessible from all the projects.
415 </p>
416 </blockquote>
417
418 <h3>i18n the Runtime and tasks</h3>
419 <a name="i18n" />
420 <blockquote>
421 <p>
422 Look at the feasability of performing i18n on Ant runtime and core tasks. Look at
423 how much work it will be and how useful it would be. Look at utilizing i18n from
424 existing projects such as Avalon.
425 </p>
426 </blockquote>
427
428 <h3>Embeddor API for Ant</h3>
429 <a name="embeddor" />
430 <blockquote>
431 <p>
432 Identify different environments in which it would be useful to embed Ant or an Ant-like
433 tool. Identify what these environments are likely to demand in terms of API and support
434 and then design a system that works in these environments without compromising ants
435 core goal (ie a build system). Some suggestions for such an API include;
436 </p>
437 <ul>
438 <li>Pluggable ProjectBuilders to allow building of project from a variety of sources,
439 file, URL, InputStream, SAX etc</li>
440 <li>Pluggable ClassLoader arrangement</li>
441 <li>Ability to set User Properties</li>
442 <li>Ability to add Task/Data/Type definitions</li>
443 <li>Ability to add/remove Listeners</li>
444 <li>Ability to add/remove Loggers</li>
445 <li>Ability to get meta-information about targets (such as name and description)</li>
446 <li>The ability to execute a task and/or targets</li>
447 <li>The ability to add tasklibs</li>
448 <li>The ability to add VFS mount points</li>
449 <li>The ability to manipulate ProjectModel and build it from GUIs</li>
450 <li>A general task engine API</li>
451 </ul>
452 </blockquote>
453
454 <h3>TypeInfo system</h3>
455 <a name="info" />
456 <blockquote>
457 <p>
458 Add in the ability to represent tasks using specified meta-info, This would allow
459 generation and manipulation of information such as what attributes are available,
460 what elements are supported etc.
461 </p>
462 </blockquote>
463
464 <h3>Antdoc</h3>
465 <a name="antdoc" />
466 <blockquote>
467 <p>
468 This is partially based on the above TypeInfo system. It involves the ability to
469 take the TypeInfo made available and generate documentation for the tasks. This
470 would allow multiple formats of documentaiton to be easily maintained and reduce
471 the chance that documentation gets out of whack.
472 </p>
473 </blockquote>
474
475 </body>
476</html>
Note: See TracBrowser for help on using the repository browser.