diff --git a/spec/core.html b/spec/core.html deleted file mode 100644 index 882659efc..000000000 --- a/spec/core.html +++ /dev/null @@ -1,278 +0,0 @@ - - - - Ant Specification, version 0.5 - - -

Ant Specification

-

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.

-

Design Goals

-

The following are the overall design goals of Ant:

- -

Simplicity

-

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.

-

Understandability

-

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.

-

Extensibility

-

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.

-

Conceptual Overview

-

This is a conceptual overview of the components used by Ant. Full APIs - will be defined later.

-

Project

-

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

-

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:

- -

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 - 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

-

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.

-

Tasks

-

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.

-

Task Jar Layout

-

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.

-

Installation

-

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.

-

Ant Properties

-

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.

-

User Preferences

-

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.

-

Project Configuration

-

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

-

The project element has the following required attributes:

- -

It also has the following optional allowed attributes:

- -

The following elements are allowed as children of the project - element:

- -

The Property Element

-

asdf

-

The Target Element

-

asfd

-

Configuration of Tasks

-

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

-

Command Line

-

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 Conventions

-

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:

- -

Scripting Model

-

Sam, I'm leaving this to you.

-

Runtime Requirements

-

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.

-

-

-