From 6b3d8a02956aad55938df6c7a1b2994a4acc5f6a Mon Sep 17 00:00:00 2001 From: James Duncan Davidson Date: Fri, 21 Apr 2000 12:46:25 +0000 Subject: [PATCH] Initial checkin of core spec. There's still pieces that need to be filled in that I know about. The big on is the task reflection stuff. git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@267655 13f79535-47bb-0310-9956-ffa450edef68 --- spec/core.html | 278 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 278 insertions(+) create mode 100644 spec/core.html diff --git a/spec/core.html b/spec/core.html new file mode 100644 index 000000000..882659efc --- /dev/null +++ b/spec/core.html @@ -0,0 +1,278 @@ + + + + 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.

+

+

+