donaldp 01/01/16 05:45:42
Added: docs/ant2 original-specification.html
Log:
moved original specification to here
Revision Changes Path
1.1 jakarta-ant/docs/ant2/original-specification.html
Index: original-specification.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "strict.dtd">
<HTML>
<HEAD>
<TITLE>Ant Specification, version 0.5</TITLE>
</HEAD>
<BODY>
<H1>Ant Specification</H1>
<P>Version 0.5 (2000/04/20)</P>
<P>This document specifies the behavior of Ant. At this time, this is a
working document with no implementation. It is hoped that this
specification
will lead to a simplier and more consistent implementation of
Ant.</P>
<P>This document is not intended to be used as an end user manual or
user
guide to Ant. To adequatly explain the concepts herein in a way
appropriate to
such a use would potentially complicate this document.</P>
<H2>Design Goals</H2>
<P>The following are the overall design goals of Ant:</P>
<UL>
<LI>Simplicity</LI>
<LI>Understandability</LI>
<LI>Extensibility</LI>
</UL>
<H3>Simplicity</H3>
<P>Ant must be simple to use. Of course, as the definition of simple
varies
according to the audience of the program. For Ant, since it is
a build tool
aimed at programmers, the goal is to be simple to use for a
competent
programmer.</P>
<H3>Understandability</H3>
<P>Ant must be clearly understandible for a first time as well as a
veteran
user. This means that a new user should be able to use Ant
comfortably the
first time and understand how to modify a build file by looking
at it. And it
should not require much experience with Ant to understand how
it works and how
to configure it for particular situtations.</P>
<H3>Extensibility</H3>
<P>Ant must be easy to extend. The API used to extend Ant must be easy
to
use and the way in which these extensions are located and used
by the core
runtime should be clear.</P>
<H2>Conceptual Overview</H2>
<P>This is a conceptual overview of the components used by Ant. Full
APIs
will be defined later.</P>
<H3>Project</H3>
<P>The base unit of work in Ant is the <STRONG>Project</STRONG>. A
Project
is defined by an editable text file and is represented by an
object of type
<CODE>org.apache.ant.Project</CODE> at runtime.</P>
<P>A Project is a collection of <STRONG>Properties</STRONG> and
<STRONG>Targets</STRONG>.</P>
<H3>Properties</H3>
<P>Properties are mutable name-value pairs that are scoped to the
Project
and held in a table. Only one pair is allowed per name. It is
anticipated that
this data structure would be of type
<CODE>java.util.Properties</CODE> or a type that has approximatly
the same contract.</P>
<P>Properties can be defined in a hierarchical manner. The order of
precidence in this hiearchy is:</P>
<UL>
<LI>Properties defined on the command line or via a GUI
tool</LI>
<LI>Properties defined in the text file which defines the
project.</LI>
<LI>Properties defined in a file in the users
<CODE>user.home</CODE> directory</LI>
<LI>Properties defined in the installation directory that can
be shared
by multiple users.</LI>
</UL>
<P>Note: The current version of Ant allows the System property list to
be
consulted for a return value if the property list doesn't
satisfy the requested
property name. As all Java code has access to the system
property list via the
<CODE>java.lang.System</CODE> class, this functionality is
considered to be confusing and to be
removed.</P>
<P>Note: The current version of Ant allows property substitution to be
performed in the project file. This functionality is being
removed.</P>
<H3>Targets</H3>
<P>Targets are ordered collections of <STRONG>Tasks</STRONG>, units of
work
to be performed if a Target is executed. </P>
<P>Targets can define dependancies on other Targets within the
Project. If
a Target is deemed to be executed, either directly on the
command line, or via
a dependancy from some other Target, then all of its
dependencies must first be
executed. Circular depenancies are resolved by examination of
the dependancy
stack when a Target is evaluated. If a dependancy is already on
the stack of
targets to be executed, then the dependancy is considered to
have been
satisfied.</P>
<P>After all dependancies of a Target have been satisfied, all of the
Tasks
contained by the target are configured and executed in
sequential order. </P>
<H3>Tasks</H3>
<P>A Task is a unit of work. When a Task is to be executed, an
instance of
the class that defines the behavior of the particular task
specified is
instantiated and then configured. This class implements the
<CODE>org.apache.ant.Task</CODE> interface.
It is then executed so that it may be able to perform its
function. It is
important to note that this configuration occurs just before
execution of the
task, and after execution of any previous tasks, so that
configuration
information that was modified by any other Task can be properly
set.</P>
<P>When a Task is executed, it is provided access to the object
representing the Project it is running in allowing it to
examine the Property
list of the project and access to various methods needed to
operate.</P>
<H2>Task Jar Layout</H2>
<P>Tasks are defined within Java Archive files. The name of the JAR
determines the name under which the task is known by in the
system. For
example, if a Task JAR is named mvdir.jar, the task is known to
the system as
<CODE>"mvdir"</CODE>.</P>
<P><EM>Question: Should we say that tasks belong in a JAR file with the
.tsk extension?</EM></P>
<P>The class within the Jar file that implements the
<CODE>org.apache.ant.Task</CODE> interface is
specified by a manifest attribute named
<CODE>Ant-Task-Class</CODE> in the Jar manifest. An example
manifest would look like:</P>
<PRE> Manifest-Version: 1.0
Ant-Task-Class: org.apache.ant.task.javac.JavacTask</PRE>
<P>When the task is used by Ant, a class loader is created that reads
classes from the JAR file. This ensures that there is no chance
of namespace
collision in the classes of various task JAR files.</P>
<H2>Installation</H2>
<P>When Ant is installed on a user system, it installs a directory
structure with the following form:</P>
<PRE><installdir>/ant (unix shell script)
/ant.bat
/ant.jar
/ant.properties
/tasks/[task jar files]
/docs/[documentation]
/README</PRE>
<P>Note: Current Jakarta practice is to name the Unix shell script
with a
.sh extension. This goes against Unix conventions and is
unecessary. Testing
has shown that the leaving the extension off on Unix will not
interfere with
the working of the Windows batch file.</P>
<P>Note: The ant.jar file has been moved from the lib/ directory and
placed
alongside the shell startup scripts (which have also been moved
out of the bin/
directory). This is because on windows platforms, the .jar file
is an
executable file of sorts.</P>
<H3>Ant Properties</H3>
<P>The <CODE>ant.properties</CODE> file contains a list of all the
properties that should be
set by default when ant is run. In addition there are a few
special properties
that are used directly by ant. An example of these properties
in use is:</P>
<PRE> system.taskdir=tasks/
user.taskdir=anttasks/</PRE>
<P>The <CODE>system.taskdir</CODE> property sets where the system
looks for Java ARchive files
containing tasks. If this property defines a relative path,
then the path is
taken as relative from the installation directory.</P>
<P>The <CODE>user.taskdir</CODE> property defines where users can
locate Java Archive files
containing tasks. If this property defines a realtive path,
then the path is
taken as relative from the users home directory (as defined by
the <CODE>user.home</CODE>
system property). Task JAR files in this directory take
precendence of those in
the system directory.</P>
<P>Note: <EM>It has been suggested to add a properties file hook to the
command line to roll in props. Pending investigation.</EM></P>
<H3>User Preferences</H3>
<P>In addition to the Ant installation directory, an
<CODE>ant.properties</CODE> file can be
located in the user's home directory (as found by the system
property <CODE>user.home</CODE>)
which can define user preferences such as the location of a
user tasks
directory. Properties defined in this file take precidence over
those set in
the installation's <CODE>ant.properties</CODE> file. Such a
file could look like:</P>
<PRE> user.taskdir=anttasks/
javac.debug=off</PRE>
<P>Properties starting with <CODE>"system."</CODE> in the
user's <CODE>ant.properties</CODE> file are not
allowed and must cause a warning to be thrown.</P>
<H2>Project Configuration</H2>
<P>Ant's Project text file is structured using XML and reflects the
structure of the various components described in the Conceptual
Overview.</P>
<P>A sample Project file:</P>
<PRE><project name="projectname"
defaulttarget="main" taskdir="tasks/">
<property name="javac.debug" value="on"/>
<target name="main">
<taskimpl ...>
...
</taskimpl>
</target>
</project></PRE>
<H3>The Project Element</H3>
<P>The <CODE>project</CODE> element has the following required
attributes:</P>
<UL>
<LI><CODE><STRONG>defaulttarget</STRONG></CODE> defining the
default target to be executed if no other target
is specified when Ant is run</LI>
</UL>
<P>It also has the following optional allowed attributes:</P>
<UL>
<LI><CODE><CODE><STRONG>name</STRONG></CODE></CODE> defining a
name for this project</LI>
<LI><CODE><STRONG>taskdir</STRONG></CODE> defining a directory
in which project specific tasks can be
located. Tasks in this directory take precedence over those
in the either the
user taskdir or the installation taskdir.</LI>
</UL>
<P>The following elements are allowed as children of the project
element:</P>
<UL>
<LI><CODE><STRONG>property</STRONG></CODE> defining a property
scoped to the project</LI>
<LI><CODE><STRONG>target</STRONG></CODE> defining a target</LI>
</UL>
<H3>The Property Element</H3>
<P>asdf</P>
<H3>The Target Element</H3>
<P>asfd</P>
<H2>Configuration of Tasks</H2>
<P>The Task section of the configuration file is structured as
such:</P>
<PRE> <[taskname] [attname=value] [attname=value]...]>
[<[elementname] [attname=value] ...> ... </[elementname]>]
</[taskname]></PRE>
<P>The taskname is used to find the class of the Task. Once the class
has
been located and an instance of it created, all of the
attributes of the Task
are reflected into the task instance using bean patterns. For
example, if a
Task contains an attribute named "directory", the
method named
setDirectory would be called with the attribute value cast to
the appropriate
type desired by the method. <EM>(What to do if the type isn't a
file or a
simple type, look for the class and see if it has a setString
method?)</EM></P>
<P>Text blocks contained by the element are added to task using an
addText
method. <EM>Place an example...</EM></P>
<P>For each element contained in the Task definition, an addElementname
method is found on the task. The parameter type of the method
defines an object
that will be loaded and instantiated. The attributes of the
element are
reflected into the object using bean methods. Any text is set
using the addText
method. Any elements are recursed in the same fashion.</P>
<P>Search order of tasks.... project/user/system</P>
<H2>Command Line</H2>
<P>The command line utility provided with Ant must support the
following
allowable syntax:</P>
<P><CODE>ant projectfile [prop=value [prop=value...]]
[target]</CODE></P>
<P>Internally, the command line shell scripts should call the
<CODE>org.apache.ant.Main</CODE> class
with the following arguments:</P>
<PRE>java -Dant.home=installdir org.apache.ant.Main $*</PRE>
<P>or its equivalent on the host platform. Note that the ant
installation
directory is a System property. The above syntax results in
ant.home being
placed in the System property list.</P>
<P>Note: <EM>On unix, finding the directory of the script that was
launched
is relatively easy. However on Windows, I'm not sure the best
way of handling
this.</EM></P>
<H2>File Naming Conventions</H2>
<P>File naming in a cross platform tool is tricky. For maximum
portability
and understandiblity it is recommended that project files use
the following
conventions:</P>
<UL>
<LI>The '/' character is used as a directory seperator</LI>
<LI>The ':' character is used as a path seperator</LI>
<LI>Only relative paths are used</LI>
</UL>
<P>However, to allow for maximum flexibility and to allow project
authors
to use conventions that make sense on their native platform,
Ant allows for a
representation of file names which has the following rules:</P>
<UL>
<LI>Directories are seperated by the forward slash ('/') or
backwards
slash ('\') character.</LI>
<LI>File names starting with either of the above directory
seperators are
considered to be absolute paths.</LI>
<LI>On systems that support multiple file roots (e.g. Windows),
a file
name that starts with a single alphabetical character
followed by a colon (':')
followed by a directory seperator defines an absolute path
where the letter
corresponds with a directory root.</LI>
<LI>File names starting with any other character are considered
to be
relative paths. In project files, all relative paths are
resolved relative to
the directory in which the project file is located.</LI>
</UL>
<P>Absolute paths are not recommended for build files as they reduce
the
ability to share a project between u sers or machines.</P>
<P>In situtations where a set of filenames need to be specified, such
as
defining a classpath, both the colon (':') andsemicolon (';')
are allowable
characters to seperate each filename. The only case that has to
be
disambiguated is if a user specifies paths that contain windows
style absolute
paths. In this case, the colon is not treated as a path
seperator if the
following rules are met:</P>
<UL>
<LI>The character two places before the colon is either of the
allowable
path seperators (':' or ';') or if the colon is the second
character of the
string.</LI>
<LI>The character immediately before the colon is a alphabetic
character
in the range a-z or A-Z.</LI>
<LI>The character immediately after the colon is either of the
allowable
directory seperators ('/' or '\').</LI>
</UL>
<H2>Scripting Model</H2>
<P>Sam, I'm leaving this to you. </P>
<H2>Runtime Requirements</H2>
<P>The following requirements are system requirements that Ant should
have
in order to run correctly. We should not bundle in any of these
into the
distribution of ant.</P>
<UL>
<LI>JDK 1.1 or greater</LI>
<LI>A JAXP compliant parser on the classpath</LI>
</UL>
<P>Note: <EM>When running on JDK 1.2 or greater, the tools.jar isn't
on the
classpath by default. There's a few different ways we can take
care of this.
One is to put it on the classpath in the execute script (I
don't like this
one). Another is to find the location of tools.jar at runtime
and put it on the
classpath of class loaders that load in task.jars so that, at
least in the
scope of the Tasks, the relevant classes are there. </EM></P>
<P></P>
<P></P> </BODY>
</HTML>
