Version 0.5 (2000/04/20)
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.
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.
The following are the overall design goals of Ant:
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.
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.
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.
This is a conceptual overview of the components used by Ant. Full APIs will be defined later.
The base unit of work in Ant is the Project. A Project
is defined by an editable text file and is represented by an object of type
org.apache.ant.Project
at runtime.
A Project is a collection of Properties and Targets.
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 java.util.Properties
or a type that has approximatly
the same contract.
Properties can be defined in a hierarchical manner. The order of precidence in this hiearchy is:
user.home
directoryNote: 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
java.lang.System
class, this functionality is considered to be confusing and to be
removed.
Note: The current version of Ant allows property substitution to be performed in the project file. This functionality is being removed.
Targets are ordered collections of Tasks, units of work to be performed if a Target is executed.
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.
After all dependancies of a Target have been satisfied, all of the Tasks contained by the target are configured and executed in sequential order.
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 org.apache.ant.Task
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.
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.
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
"mvdir"
.
Question: Should we say that tasks belong in a JAR file with the .tsk extension?
The class within the Jar file that implements the org.apache.ant.Task
interface is
specified by a manifest attribute named Ant-Task-Class
in the Jar manifest. An example
manifest would look like:
Manifest-Version: 1.0 Ant-Task-Class: org.apache.ant.task.javac.JavacTask
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.
When Ant is installed on a user system, it installs a directory structure with the following form:
<installdir>/ant (unix shell script) /ant.bat /ant.jar /ant.properties /tasks/[task jar files] /docs/[documentation] /README
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.
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.
The ant.properties
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:
system.taskdir=tasks/ user.taskdir=anttasks/
The system.taskdir
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.
The user.taskdir
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 user.home
system property). Task JAR files in this directory take precendence of those in
the system directory.
Note: It has been suggested to add a properties file hook to the command line to roll in props. Pending investigation.
In addition to the Ant installation directory, an ant.properties
file can be
located in the user's home directory (as found by the system property user.home
)
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 ant.properties
file. Such a file could look like:
user.taskdir=anttasks/ javac.debug=off
Properties starting with "system."
in the user's ant.properties
file are not
allowed and must cause a warning to be thrown.
Ant's Project text file is structured using XML and reflects the structure of the various components described in the Conceptual Overview.
A sample Project file:
<project name="projectname" defaulttarget="main" taskdir="tasks/"> <property name="javac.debug" value="on"/> <target name="main"> <taskimpl ...> ... </taskimpl> </target> </project>
The project
element has the following required attributes:
defaulttarget
defining the default target to be executed if no other target
is specified when Ant is runIt also has the following optional allowed attributes:
name
defining a name for this projecttaskdir
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.The following elements are allowed as children of the project element:
property
defining a property scoped to the projecttarget
defining a targetasdf
asfd
The Task section of the configuration file is structured as such:
<[taskname] [attname=value] [attname=value]...]> [<[elementname] [attname=value] ...> ... </[elementname]>] </[taskname]>
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. (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?)
Text blocks contained by the element are added to task using an addText method. Place an example...
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.
Search order of tasks.... project/user/system
The command line utility provided with Ant must support the following allowable syntax:
ant projectfile [prop=value [prop=value...]] [target]
Internally, the command line shell scripts should call the org.apache.ant.Main
class
with the following arguments:
java -Dant.home=installdir org.apache.ant.Main $*
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.
Note: 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.
File naming in a cross platform tool is tricky. For maximum portability and understandiblity it is recommended that project files use the following conventions:
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:
Absolute paths are not recommended for build files as they reduce the ability to share a project between u sers or machines.
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:
Sam, I'm leaving this to you.
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.
Note: 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.