1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "strict.dtd">
|
---|
2 | <HTML>
|
---|
3 | <HEAD>
|
---|
4 | <TITLE>Ant Specification, version 0.5</TITLE>
|
---|
5 | </HEAD>
|
---|
6 | <BODY>
|
---|
7 | <H1>Ant Specification</H1>
|
---|
8 | <P>Version 0.5 (2000/04/20)</P>
|
---|
9 | <P>This document specifies the behavior of Ant. At this time, this is a
|
---|
10 | working document with no implementation. It is hoped that this specification
|
---|
11 | will lead to a simplier and more consistent implementation of Ant.</P>
|
---|
12 | <P>This document is not intended to be used as an end user manual or user
|
---|
13 | guide to Ant. To adequatly explain the concepts herein in a way appropriate to
|
---|
14 | such a use would potentially complicate this document.</P>
|
---|
15 | <H2>Design Goals</H2>
|
---|
16 | <P>The following are the overall design goals of Ant:</P>
|
---|
17 | <UL>
|
---|
18 | <LI>Simplicity</LI>
|
---|
19 | <LI>Understandability</LI>
|
---|
20 | <LI>Extensibility</LI>
|
---|
21 | </UL>
|
---|
22 | <H3>Simplicity</H3>
|
---|
23 | <P>Ant must be simple to use. Of course, as the definition of simple varies
|
---|
24 | according to the audience of the program. For Ant, since it is a build tool
|
---|
25 | aimed at programmers, the goal is to be simple to use for a competent
|
---|
26 | programmer.</P>
|
---|
27 | <H3>Understandability</H3>
|
---|
28 | <P>Ant must be clearly understandible for a first time as well as a veteran
|
---|
29 | user. This means that a new user should be able to use Ant comfortably the
|
---|
30 | first time and understand how to modify a build file by looking at it. And it
|
---|
31 | should not require much experience with Ant to understand how it works and how
|
---|
32 | to configure it for particular situtations.</P>
|
---|
33 | <H3>Extensibility</H3>
|
---|
34 | <P>Ant must be easy to extend. The API used to extend Ant must be easy to
|
---|
35 | use and the way in which these extensions are located and used by the core
|
---|
36 | runtime should be clear.</P>
|
---|
37 | <H2>Conceptual Overview</H2>
|
---|
38 | <P>This is a conceptual overview of the components used by Ant. Full APIs
|
---|
39 | will be defined later.</P>
|
---|
40 | <H3>Project</H3>
|
---|
41 | <P>The base unit of work in Ant is the <STRONG>Project</STRONG>. A Project
|
---|
42 | is defined by an editable text file and is represented by an object of type
|
---|
43 | <CODE>org.apache.ant.Project</CODE> at runtime.</P>
|
---|
44 | <P>A Project is a collection of <STRONG>Properties</STRONG> and
|
---|
45 | <STRONG>Targets</STRONG>.</P>
|
---|
46 | <H3>Properties</H3>
|
---|
47 | <P>Properties are mutable name-value pairs that are scoped to the Project
|
---|
48 | and held in a table. Only one pair is allowed per name. It is anticipated that
|
---|
49 | this data structure would be of type <CODE>java.util.Properties</CODE> or a type that has approximatly
|
---|
50 | the same contract.</P>
|
---|
51 | <P>Properties can be defined in a hierarchical manner. The order of
|
---|
52 | precidence in this hiearchy is:</P>
|
---|
53 | <UL>
|
---|
54 | <LI>Properties defined on the command line or via a GUI tool</LI>
|
---|
55 | <LI>Properties defined in the text file which defines the project.</LI>
|
---|
56 | <LI>Properties defined in a file in the users <CODE>user.home</CODE> directory</LI>
|
---|
57 | <LI>Properties defined in the installation directory that can be shared
|
---|
58 | by multiple users.</LI>
|
---|
59 | </UL>
|
---|
60 | <P>Note: The current version of Ant allows the System property list to be
|
---|
61 | consulted for a return value if the property list doesn't satisfy the requested
|
---|
62 | property name. As all Java code has access to the system property list via the
|
---|
63 | <CODE>java.lang.System</CODE> class, this functionality is considered to be confusing and to be
|
---|
64 | removed.</P>
|
---|
65 | <P>Note: The current version of Ant allows property substitution to be
|
---|
66 | performed in the project file. This functionality is being removed.</P>
|
---|
67 | <H3>Targets</H3>
|
---|
68 | <P>Targets are ordered collections of <STRONG>Tasks</STRONG>, units of work
|
---|
69 | to be performed if a Target is executed. </P>
|
---|
70 | <P>Targets can define dependancies on other Targets within the Project. If
|
---|
71 | a Target is deemed to be executed, either directly on the command line, or via
|
---|
72 | a dependancy from some other Target, then all of its dependencies must first be
|
---|
73 | executed. Circular depenancies are resolved by examination of the dependancy
|
---|
74 | stack when a Target is evaluated. If a dependancy is already on the stack of
|
---|
75 | targets to be executed, then the dependancy is considered to have been
|
---|
76 | satisfied.</P>
|
---|
77 | <P>After all dependancies of a Target have been satisfied, all of the Tasks
|
---|
78 | contained by the target are configured and executed in sequential order. </P>
|
---|
79 | <H3>Tasks</H3>
|
---|
80 | <P>A Task is a unit of work. When a Task is to be executed, an instance of
|
---|
81 | the class that defines the behavior of the particular task specified is
|
---|
82 | instantiated and then configured. This class implements the <CODE>org.apache.ant.Task</CODE> interface.
|
---|
83 | It is then executed so that it may be able to perform its function. It is
|
---|
84 | important to note that this configuration occurs just before execution of the
|
---|
85 | task, and after execution of any previous tasks, so that configuration
|
---|
86 | information that was modified by any other Task can be properly set.</P>
|
---|
87 | <P>When a Task is executed, it is provided access to the object
|
---|
88 | representing the Project it is running in allowing it to examine the Property
|
---|
89 | list of the project and access to various methods needed to operate.</P>
|
---|
90 | <H2>Task Jar Layout</H2>
|
---|
91 | <P>Tasks are defined within Java Archive files. The name of the JAR
|
---|
92 | determines the name under which the task is known by in the system. For
|
---|
93 | example, if a Task JAR is named mvdir.jar, the task is known to the system as
|
---|
94 | <CODE>"mvdir"</CODE>.</P>
|
---|
95 | <P><EM>Question: Should we say that tasks belong in a JAR file with the
|
---|
96 | .tsk extension?</EM></P>
|
---|
97 | <P>The class within the Jar file that implements the <CODE>org.apache.ant.Task</CODE> interface is
|
---|
98 | specified by a manifest attribute named <CODE>Ant-Task-Class</CODE> in the Jar manifest. An example
|
---|
99 | manifest would look like:</P>
|
---|
100 | <PRE> Manifest-Version: 1.0
|
---|
101 | Ant-Task-Class: org.apache.ant.task.javac.JavacTask</PRE>
|
---|
102 | <P>When the task is used by Ant, a class loader is created that reads
|
---|
103 | classes from the JAR file. This ensures that there is no chance of namespace
|
---|
104 | collision in the classes of various task JAR files.</P>
|
---|
105 | <H2>Installation</H2>
|
---|
106 | <P>When Ant is installed on a user system, it installs a directory
|
---|
107 | structure with the following form:</P>
|
---|
108 | <PRE><installdir>/ant (unix shell script)
|
---|
109 | /ant.bat
|
---|
110 | /ant.jar
|
---|
111 | /ant.properties
|
---|
112 | /tasks/[task jar files]
|
---|
113 | /docs/[documentation]
|
---|
114 | /README</PRE>
|
---|
115 | <P>Note: Current Jakarta practice is to name the Unix shell script with a
|
---|
116 | .sh extension. This goes against Unix conventions and is unecessary. Testing
|
---|
117 | has shown that the leaving the extension off on Unix will not interfere with
|
---|
118 | the working of the Windows batch file.</P>
|
---|
119 | <P>Note: The ant.jar file has been moved from the lib/ directory and placed
|
---|
120 | alongside the shell startup scripts (which have also been moved out of the bin/
|
---|
121 | directory). This is because on windows platforms, the .jar file is an
|
---|
122 | executable file of sorts.</P>
|
---|
123 | <H3>Ant Properties</H3>
|
---|
124 | <P>The <CODE>ant.properties</CODE> file contains a list of all the properties that should be
|
---|
125 | set by default when ant is run. In addition there are a few special properties
|
---|
126 | that are used directly by ant. An example of these properties in use is:</P>
|
---|
127 | <PRE> system.taskdir=tasks/
|
---|
128 | user.taskdir=anttasks/</PRE>
|
---|
129 | <P>The <CODE>system.taskdir</CODE> property sets where the system looks for Java ARchive files
|
---|
130 | containing tasks. If this property defines a relative path, then the path is
|
---|
131 | taken as relative from the installation directory.</P>
|
---|
132 | <P>The <CODE>user.taskdir</CODE> property defines where users can locate Java Archive files
|
---|
133 | containing tasks. If this property defines a realtive path, then the path is
|
---|
134 | taken as relative from the users home directory (as defined by the <CODE>user.home</CODE>
|
---|
135 | system property). Task JAR files in this directory take precendence of those in
|
---|
136 | the system directory.</P>
|
---|
137 | <P>Note: <EM>It has been suggested to add a properties file hook to the
|
---|
138 | command line to roll in props. Pending investigation.</EM></P>
|
---|
139 | <H3>User Preferences</H3>
|
---|
140 | <P>In addition to the Ant installation directory, an <CODE>ant.properties</CODE> file can be
|
---|
141 | located in the user's home directory (as found by the system property <CODE>user.home</CODE>)
|
---|
142 | which can define user preferences such as the location of a user tasks
|
---|
143 | directory. Properties defined in this file take precidence over those set in
|
---|
144 | the installation's <CODE>ant.properties</CODE> file. Such a file could look like:</P>
|
---|
145 | <PRE> user.taskdir=anttasks/
|
---|
146 | javac.debug=off</PRE>
|
---|
147 | <P>Properties starting with <CODE>"system."</CODE> in the user's <CODE>ant.properties</CODE> file are not
|
---|
148 | allowed and must cause a warning to be thrown.</P>
|
---|
149 | <H2>Project Configuration</H2>
|
---|
150 | <P>Ant's Project text file is structured using XML and reflects the
|
---|
151 | structure of the various components described in the Conceptual Overview.</P>
|
---|
152 | <P>A sample Project file:</P>
|
---|
153 | <PRE><project name="projectname" defaulttarget="main" taskdir="tasks/">
|
---|
154 | <property name="javac.debug" value="on"/>
|
---|
155 | <target name="main">
|
---|
156 | <taskimpl ...>
|
---|
157 | ...
|
---|
158 | </taskimpl>
|
---|
159 | </target>
|
---|
160 | </project></PRE>
|
---|
161 | <H3>The Project Element</H3>
|
---|
162 | <P>The <CODE>project</CODE> element has the following required attributes:</P>
|
---|
163 | <UL>
|
---|
164 | <LI><CODE><STRONG>defaulttarget</STRONG></CODE> defining the default target to be executed if no other target
|
---|
165 | is specified when Ant is run</LI>
|
---|
166 | </UL>
|
---|
167 | <P>It also has the following optional allowed attributes:</P>
|
---|
168 | <UL>
|
---|
169 | <LI><CODE><CODE><STRONG>name</STRONG></CODE></CODE> defining a name for this project</LI>
|
---|
170 | <LI><CODE><STRONG>taskdir</STRONG></CODE> defining a directory in which project specific tasks can be
|
---|
171 | located. Tasks in this directory take precedence over those in the either the
|
---|
172 | user taskdir or the installation taskdir.</LI>
|
---|
173 | </UL>
|
---|
174 | <P>The following elements are allowed as children of the project
|
---|
175 | element:</P>
|
---|
176 | <UL>
|
---|
177 | <LI><CODE><STRONG>property</STRONG></CODE> defining a property scoped to the project</LI>
|
---|
178 | <LI><CODE><STRONG>target</STRONG></CODE> defining a target</LI>
|
---|
179 | </UL>
|
---|
180 | <H3>The Property Element</H3>
|
---|
181 | <P>asdf</P>
|
---|
182 | <H3>The Target Element</H3>
|
---|
183 | <P>asfd</P>
|
---|
184 | <H2>Configuration of Tasks</H2>
|
---|
185 | <P>The Task section of the configuration file is structured as such:</P>
|
---|
186 | <PRE> <[taskname] [attname=value] [attname=value]...]>
|
---|
187 | [<[elementname] [attname=value] ...> ... </[elementname]>]
|
---|
188 | </[taskname]></PRE>
|
---|
189 | <P>The taskname is used to find the class of the Task. Once the class has
|
---|
190 | been located and an instance of it created, all of the attributes of the Task
|
---|
191 | are reflected into the task instance using bean patterns. For example, if a
|
---|
192 | Task contains an attribute named "directory", the method named
|
---|
193 | setDirectory would be called with the attribute value cast to the appropriate
|
---|
194 | type desired by the method. <EM>(What to do if the type isn't a file or a
|
---|
195 | simple type, look for the class and see if it has a setString method?)</EM></P>
|
---|
196 |
|
---|
197 | <P>Text blocks contained by the element are added to task using an addText
|
---|
198 | method. <EM>Place an example...</EM></P>
|
---|
199 | <P>For each element contained in the Task definition, an addElementname
|
---|
200 | method is found on the task. The parameter type of the method defines an object
|
---|
201 | that will be loaded and instantiated. The attributes of the element are
|
---|
202 | reflected into the object using bean methods. Any text is set using the addText
|
---|
203 | method. Any elements are recursed in the same fashion.</P>
|
---|
204 | <P>Search order of tasks.... project/user/system</P>
|
---|
205 | <H2>Command Line</H2>
|
---|
206 | <P>The command line utility provided with Ant must support the following
|
---|
207 | allowable syntax:</P>
|
---|
208 | <P><CODE>ant projectfile [prop=value [prop=value...]] [target]</CODE></P>
|
---|
209 | <P>Internally, the command line shell scripts should call the <CODE>org.apache.ant.Main</CODE> class
|
---|
210 | with the following arguments:</P>
|
---|
211 | <PRE>java -Dant.home=installdir org.apache.ant.Main $*</PRE>
|
---|
212 | <P>or its equivalent on the host platform. Note that the ant installation
|
---|
213 | directory is a System property. The above syntax results in ant.home being
|
---|
214 | placed in the System property list.</P>
|
---|
215 | <P>Note: <EM>On unix, finding the directory of the script that was launched
|
---|
216 | is relatively easy. However on Windows, I'm not sure the best way of handling
|
---|
217 | this.</EM></P>
|
---|
218 | <H2>File Naming Conventions</H2>
|
---|
219 | <P>File naming in a cross platform tool is tricky. For maximum portability
|
---|
220 | and understandiblity it is recommended that project files use the following
|
---|
221 | conventions:</P>
|
---|
222 | <UL>
|
---|
223 | <LI>The '/' character is used as a directory seperator</LI>
|
---|
224 | <LI>The ':' character is used as a path seperator</LI>
|
---|
225 | <LI>Only relative paths are used</LI>
|
---|
226 | </UL>
|
---|
227 | <P>However, to allow for maximum flexibility and to allow project authors
|
---|
228 | to use conventions that make sense on their native platform, Ant allows for a
|
---|
229 | representation of file names which has the following rules:</P>
|
---|
230 | <UL>
|
---|
231 | <LI>Directories are seperated by the forward slash ('/') or backwards
|
---|
232 | slash ('\') character.</LI>
|
---|
233 | <LI>File names starting with either of the above directory seperators are
|
---|
234 | considered to be absolute paths.</LI>
|
---|
235 | <LI>On systems that support multiple file roots (e.g. Windows), a file
|
---|
236 | name that starts with a single alphabetical character followed by a colon (':')
|
---|
237 | followed by a directory seperator defines an absolute path where the letter
|
---|
238 | corresponds with a directory root.</LI>
|
---|
239 | <LI>File names starting with any other character are considered to be
|
---|
240 | relative paths. In project files, all relative paths are resolved relative to
|
---|
241 | the directory in which the project file is located.</LI>
|
---|
242 | </UL>
|
---|
243 | <P>Absolute paths are not recommended for build files as they reduce the
|
---|
244 | ability to share a project between u sers or machines.</P>
|
---|
245 | <P>In situtations where a set of filenames need to be specified, such as
|
---|
246 | defining a classpath, both the colon (':') andsemicolon (';') are allowable
|
---|
247 | characters to seperate each filename. The only case that has to be
|
---|
248 | disambiguated is if a user specifies paths that contain windows style absolute
|
---|
249 | paths. In this case, the colon is not treated as a path seperator if the
|
---|
250 | following rules are met:</P>
|
---|
251 | <UL>
|
---|
252 | <LI>The character two places before the colon is either of the allowable
|
---|
253 | path seperators (':' or ';') or if the colon is the second character of the
|
---|
254 | string.</LI>
|
---|
255 | <LI>The character immediately before the colon is a alphabetic character
|
---|
256 | in the range a-z or A-Z.</LI>
|
---|
257 | <LI>The character immediately after the colon is either of the allowable
|
---|
258 | directory seperators ('/' or '\').</LI>
|
---|
259 | </UL>
|
---|
260 | <H2>Scripting Model</H2>
|
---|
261 | <P>Sam, I'm leaving this to you. </P>
|
---|
262 | <H2>Runtime Requirements</H2>
|
---|
263 | <P>The following requirements are system requirements that Ant should have
|
---|
264 | in order to run correctly. We should not bundle in any of these into the
|
---|
265 | distribution of ant.</P>
|
---|
266 | <UL>
|
---|
267 | <LI>JDK 1.1 or greater</LI>
|
---|
268 | <LI>A JAXP compliant parser on the classpath</LI>
|
---|
269 | </UL>
|
---|
270 | <P>Note: <EM>When running on JDK 1.2 or greater, the tools.jar isn't on the
|
---|
271 | classpath by default. There's a few different ways we can take care of this.
|
---|
272 | One is to put it on the classpath in the execute script (I don't like this
|
---|
273 | one). Another is to find the location of tools.jar at runtime and put it on the
|
---|
274 | classpath of class loaders that load in task.jars so that, at least in the
|
---|
275 | scope of the Tasks, the relevant classes are there. </EM></P>
|
---|
276 | <P></P>
|
---|
277 | <P></P> </BODY>
|
---|
278 | </HTML>
|
---|