-
-
diff --git a/docs/ant2/actionlist.html b/docs/ant2/actionlist.html
deleted file mode 100644
index 61392a8a10..0000000000
--- a/docs/ant2/actionlist.html
+++ /dev/null
@@ -1,492 +0,0 @@
-
-
- Ant1.9 Action List
-
-
- Ant1.9 Action List
- Precursor to Ant2
- Peter Donald [peter at apache.org]
-
-
-
-
-
-
- This document aims to contain a list of actions that people can take
- to produce Ant1.9. Ant1.9 is a refactoring of the Ant1.x line and a jump
- point for Ant2. Some changes will be backported to Ant1.x over time when
- they have proven themselves while other changes may only become available
- via Ant2.0. Ant1.9 is our melting pot where we can experiment and refactor
- without a thought to backwards compatability but only to the "right" way
- of doing things.
-
- |
-
-
-
- Introduction
-
-
-
- This document will list a bunch of actions that will guide us in the evolution
- of Ant1.x and provide a solid basis on which to launch Ant2.0. Feel free to add to
- this list of actions as our vision of Ant2 solidifies. Associated with each action
- is a list of victims who have "volunteered" to have a go at the action and a status.
- The status just tells us where they are at while the victim column will tell us exactly
- who is doing what. It is fine for a group of people to work on a single area.
-
-
-
-
-
-
-
- Virtual File System
-
-
-
- There has long been a recognition that it would be nice if ant supported some
- notion of a virtual filesystem layer. This layer would allow you to treat
- resources located and retrieved from different mechanisms in a uniform way.
- For instance it would allow the copy task to copy from a http server, a cvs server,
- a ftp server or the local filesystem using a uniform mechanism. So instead of
- having separate tasks to operate on each different resource type we would use
- just one task that plugged into multiple filesystems.
-
-
- When we are talking about a virtual filesystem or VFS, one of the concerns we must
- address is how to "name" the resource. In most cases a URL or URI style access will
- be sufficient but in other cases we may need to consider other options. So
- "cvs://localhost:/home/cvs/jakarta-avalon/README.txt?version=1.1",
- "ftp://some.server.com/dir/file.zip" and "file://C/WINDOWS/Desktop/MyFile.txt"
- are all examples of referring to different resources.
-
-
- Another concern that must be addressed is capabilities of both the resources and
- the filesystem. For instance it is possible to both read and write to resources
- using the "file" protocol but only possible to write resources using "mailto".
- The act of copying a file to a "mailto" url would actuall post the files as
- resources while copying to a "file" would duplicate the resource somewhere on
- the local filesystem.
-
-
- So we need to determine a list of capabilities. Some examples would be "read",
- "write", "list" (can you list dirs), "type" (can you get mime type),
- "access permissions" (can you tell if resource has permissions),
- "modify permissions" (can you modify permissions) etc. Some of these capabilities
- can be associated with the particular reosurces, while others may need to be
- associated with a whole filesystem/protocol (ie there is no standard mechanism
- to perform "list" on general "http" URLs). Thus a list of all these capabilities
- and mapping to various protocols will need to be established.
-
-
- Next we need to determine if we are going to support the notion of "mounting"
- URLs. For instance if we need to copy files from a FTP server do we allways
- need to specify the full URL - no matter how convoluted it is (ie
- "ftp://fred:secret@some.server.com:28763/home/fred/project2/dir/file.zip")
- or can we mount this on a VFS and access it via that shorter url. ie We could
- mount "ftp://fred:secret@some.server.com:28763/home/fred/" onto "vfs:/home"
- and then just access the resources via "vfs:/home/project2/dir/file.zip".
- This would make dealing with large urls easier and more uniform.
-
-
- So after we have decided what our options are we need to actually go about
- implementing the solution. It may be the case that existing VFS solutions
- could be reused with minor changes and thus we could save ourselves a lot of
- work. Candidates would be the Netbeans VFS, Suns XFile API or other
- available directory APIs (like JNDI). If none of them suit then we will need
- to write our own layer.
-
-
-
- Naming
-
-
-
- Currently Ant has a mixture of tasks from various stages it's evolution, with different
- authors and each utilizing different naming patterns. Some tasks use names such as
- "src" and "dest" while others use "file" and "tofile". It would be preferrable if
- consistent naming patterns were used. It is recomended that we come up with a "best
- practices" document to document our recomended naming patterns.
-
-
- Before we can come up with such a document we need to identify common patterns through
- out the tasks. Several tasks have the notion of transforming input from a "source"
- to a "destination". So we should have consistent naming schemes for these attributes and
- elements. Analysis of existing tasks will likely bring out other similar patterns. Once
- we have identified and documented these similarities then we can establish conventions.
-
-
-
- Selector API
-
-
-
- Currently our filesets allow us to select a set of files based on name patterns.
- For instance we could create a set of all the files that end with ".java". However
- there are cases when you wish to select files based on their other attributes, such as
- if they are read only or if they are older than a specified date etc.
-
-
- The selector API is one such mechanism to do this. The selector API will allow you to
- build file sets based on criteria other than name. Some possible criteria would be
-
-
- - Is the file readable?
- - Is the file writeable?
- - What date was the file modified on?
- - What size is the file?
- - Does the contents contain the string "magic"?
-
-
- If we end up supporting a VFS then we could expand the number of selectors
- considerably. A mock representation that has been proposed before is the following.
- Of course this is subject to change as soon as someone wants to tackle this action ;)
-
-
- <include>
- <selector type="name" value="**/*.java"/>
- <selector type="permission" value="r"/>
-
- <!-- could optionally be directory/or some other system specific features -->
- <selector type="type" value="file"/>
- <selector type="modify-time"
- operation="greater-than"
- value="29th Feb 2003"/>
- </include>
-
-
-
- Coloring API
-
-
-
- When you execute a task such as "javac" there is two types of dependency information
- that is important to analyze before we determine if we need to recompile a file. Say
- we are compiling Foo.java
, it may depend on the Bar.java
- file. We call this "structural" dependency information - the structure of the source file
- determines what other files it depend upon. However there is also "environmental"
- dependency information. For instance if the Foo.java
file was compiled with
- debug="true"
last run and this time needs to be compiled with
- debug="false"
then it is out of date and needs to be recompiled. We call this
- "environmental" dependency information "coloring".
-
-
- So we need to create an infrastructure that allows tasks to manage "coloring". So a task
- should be able to add coloring information for each resource processed. When the task
- comes to process the resource again it will detect if the coloring has changed and if it
- has will force a recompile.
-
-
- An API for such a bean has yet to be established but an example API would be.
-
-
-ColoringManager cm = ...;
-cm.addColor( "debug", "true" );
-cm.addColor( "optimize", "false" );
-cm.setFileSet( myFileSet );
-File[] files = cm.getOutOfDate();
-
-
-
- Structural Dependency Utils
-
-
-
- In the present ant, it is required that each task manage dependency separately.
- This makes it a lot of work to implement even simple dependency checking. To this
- day many of the core tasks do not implement it correctly. I am specifically
- talking about "structural" dependency information. The main reason is that it is
- painful to implement.
-
-
- Some tasks do no dependency checking and will recompile/transform/etc everytime.
- Others may perform a simple dependency checking (ie if source file is newer than
- destination file then recompile). Ideally a dependency system would actually
- calculate the dependencies correctly. So we need to have some mechanism to determine
- that foo.c
actually depends upon foo.h
, bar.h
- and baz.h
. As this information is particular to each different task
- we need to allow tasks to implement this behaviour. Possibly by supplying an interface
- of the form;
-
-
-public interface DependencyGenerator
-{
- File[] generateDependencies( File file );
-}
-
-
- Generating the dependency information is a costly operation and thus we do not want to
- be doing it everytime you run ant. We want to generate it on the initial build and then
- persist somewhere. Everytime a file is out of date, it's dependency information would
- be regenerated and stored in the dependency cache. Ideally this cache would also store the
- above mentioned coloring information. So the entry for foo.c
may declare that
- it is dependent upon foo.h
, bar.h
and baz.h
, aswell
- as being compiled with -O2 flag. If any of the dependencies have changed or are out of date
- then foo.c would need to be recompiled.
-
-
- A possible API would be
-
-
-DependencyManager dm = ...;
-dm.setFileSet( myFileSet );
-dm.setDependencyCache( myDependencyCacheFile );
-File[] files = cm.getOutOfDate();
-
-
-
- Refactor <exec> infrastructure into Beans
-
-
-
- Exec and its related classes have currently evolved through several iterations and thus
- it is not as cleanly designed and as reusable as it could be. Someone needs to pull apart
- exec and analyze which parts can be turned into JavaBeans and decouple them from the Ant
- infrastructure. Once that is done it will make these beans much easier to reuse from other
- tasks without relying on gaining access to the other task instance.
-
-
-
- Refactor <java> infrastructure into Beans
-
-
-
- Much like Exec should be decoupled from Ant runtime, so should classes to implement java
- task for the same benefits.
-
-
-
- Generic Task Facades
-
-
-
- Currently we have a few tasks that have multiple implementations. For instance Javac task
- can actually call jikes, jvc, classic javac or modern javac. Similar things will be seen
- with the jspc task and the cc task (if it ever gets written). We need to examine this
- pattern and see if there is a way to generalize this and make it easier to write such tasks.
-
-
-
- Task Packaging
-
-
-
- We have already decided that we are going to package Ant tasks in separate jars and
- have some sort of descriptor that to describe the contents of the jar. However we have
- not yet decided how we will break up the tasks. Do we break up the tasks up into
- related tasks or into groups that ar elikely to be used together or what? A possible
- breakdown would be
-
-
- - jdk tasks: javac, javadoc, rmic etc
- - text tasks: regex replace, fixcrlf etc
- - unix tasks: chmod, etc
- - file tasks: copy, move, etc
-
-
-
- Mapping File Attributes during transformation
-
-
-
- When we are copying files from one location to another it is currently possible
- to rename them using a mapper. So we could rename Foo.java
to
- Foo.java.bak
. On occasion it is useful to modify file attributes
- other than its name in such operations. So we could copy the files to another
- location and make them read-only in one operation.
-
-
-
- Filters extensions
-
-
-
- This is partially related to the above action. Filters could be seen as a way
- to modify the content attribute of a file during a copy/move. It would be
- preferrable if filtering could be abstracted to use FilteredOutputStream
s
- to perform the content modification. That way new Filter types could be constructed
- and used during file copy (ie an example would be a Perl FilterOutputStream that
- allowed you to use perl expressions to transform input).
-
-
-
- XML Catalog to load XML Fragments
-
-
-
- When including fragments of XML we are currently forced to use relative paths.
- However this is sometimes undesirable when a single fragment needs to be used
- across several projects in several different locations. Instead we could use
- a Catalog to name the fragment and then each developer would only need to install
- the fragment once and it would be accessible from all the projects.
-
-
-
- i18n the Runtime and tasks
-
-
-
- Look at the feasability of performing i18n on Ant runtime and core tasks. Look at
- how much work it will be and how useful it would be. Look at utilizing i18n from
- existing projects such as Avalon.
-
-
-
- Embeddor API for Ant
-
-
-
- Identify different environments in which it would be useful to embed Ant or an Ant-like
- tool. Identify what these environments are likely to demand in terms of API and support
- and then design a system that works in these environments without compromising ants
- core goal (ie a build system). Some suggestions for such an API include;
-
-
- - Pluggable ProjectBuilders to allow building of project from a variety of sources,
- file, URL, InputStream, SAX etc
- - Pluggable ClassLoader arrangement
- - Ability to set User Properties
- - Ability to add Task/Data/Type definitions
- - Ability to add/remove Listeners
- - Ability to add/remove Loggers
- - Ability to get meta-information about targets (such as name and description)
- - The ability to execute a task and/or targets
- - The ability to add tasklibs
- - The ability to add VFS mount points
- - The ability to manipulate ProjectModel and build it from GUIs
- - A general task engine API
-
-
-
- TypeInfo system
-
-
-
- Add in the ability to represent tasks using specified meta-info, This would allow
- generation and manipulation of information such as what attributes are available,
- what elements are supported etc.
-
-
-
- Antdoc
-
-
-
- This is partially based on the above TypeInfo system. It involves the ability to
- take the TypeInfo made available and generate documentation for the tasks. This
- would allow multiple formats of documentaiton to be easily maintained and reduce
- the chance that documentation gets out of whack.
-
-
-
-
-
diff --git a/docs/ant2/features.html b/docs/ant2/features.html
deleted file mode 100644
index 0cb8314f7c..0000000000
--- a/docs/ant2/features.html
+++ /dev/null
@@ -1,381 +0,0 @@
-
-
-
-
-
- Ant2 feature list
-
-
-
-
-
-
-
-
-
- Ant2 Goals
-
- Even though Ant2 is expected to be incompatible with the
- current Ant1 series, it still has the same goals. Ant is a Java
- based build tool and this remains the main focus of it. The
- original goals of simplicity, understandability and extensibility
- still stand and Ant2 will try to achieve them even better than
- Ant1 does.
-
- Simplicity and Understandability
-
- These two goals are closely related. Ant build files shall be
- easy to read and understand - at the same time it should be easy
- to write a custom Ant task and to use the utility classes that
- Ant2 provides.
-
- Ant2 shall be more consistent than Ant1 is - this means:
-
-
-
- - core tasks will use the same attribute names for common
- functionality
-
- - similar tasks will be unified to use similar forms.
-
- - different implementations for the same functionality will be
- hidden behind facade tasks.
-
- - properties and data types will be unified so that they share
- the same namespace and inheritance rules.
-
-
-
- Furthermore some things will have to become more explicit:
-
-
-
- - remove all magic properties
-
- - make build file writers explicitly state which
- filters/filtersets a copy task will use
-
- - add scoping rules for properties so that not all of them
- will be inherited by sub-builds, only those that have been
- specified explicitly.
-
-
-
- The front-ends for Ant2 shall be smart enough to automatically
- detect the required libraries (like tools.jar
), the
- use of native scripts shall be kept to a minimum.
-
- Build file writers can attach a message to targets that will be
- presented to the user if that target is going to be skipped (based
- on the if/unless attribute of the target).
-
- Even though Ant installation already is quite simple in Ant1
- (extract the archive and set two environment variables),
- alternative ways to install Ant like using
- Webstart or
- a "self-extracting" JAR file will be explored.
-
- Extensibility
-
- Ant2 like Ant1 uses build files written in XML as its main
- input, but it will not be restricted to it. The core of Ant2 will
- work on an object model of Project/Target/Task that is independent
- of any external representation.
-
- As an extension of the current <taskdef>
- concept, tasks can be bundled into task libraries (together with
- data types and other utility classes). These task libraries are
- special JAR archives that somehow describe the contained tasks to
- Ant. Ant will automatically know all tasks contained in task
- libraries that have been placed into a special directory - in
- addition task libraries can be referenced and used in a build file
- explicitly.
-
- It has become apparent, that several "aspects" of
- tasks are so common that task writers find themselves duplicating
- code all over again - things like classpath handling or "do
- we stop the build if this task fails?" functionality for
- example. Ant2 will provide a way to let the user attach an
- "aspect handler" to a project - all attributes that live
- in a certain namespace are going to be passed to this handler.
-
- Ant2 will farm out common functionality from tasks into utility
- classes so that task writers can benefit from a tested and stable
- framework - they shouldn't need to deal with existing tasks
- directly (like some tasks "abuse" the
- <touch>
task in Ant1).
-
- Ant2 will provide a way to define tasks that itself can have
- tasks as child elements without knowing all defined tasks at
- compile time. Discussions on ant-dev usually talk about
- "container tasks" in this context.
-
- The only way to "include" common XML snippets so far
- has been the usage of external SYSTEM entities, a mechanism that
- is tied to DTDs and doesn't mix well with alternative
- approaches like XML Schema. Ant2 will provide a built-in include
- mechanism.
-
- New/Modified Features
-
- Ant2 will run the build process fully dynamically, which means
- that task won't be instantiated before they are actually being run
- and ${}
expansion will see the very latest value of a
- property. It will be possible to reassign values of properties via
- a built-in task.
-
- Compatibility with Ant1
-
- Ant2 is going to break Ant1 in several ways:
-
-
-
- - Tasks written for Ant1 won't work in Ant2 as the API of
- Ant's core and the names of utility classes are going to
- change. There will probably be adaptors and utility classes to
- ease the transition for task writers.
-
- - Build files written for Ant1 will probably not be valid in
- Ant2 or at least not yield the same results. It is expected that
- Ant2 will come with a tool to translate Ant1 build files into
- equivalent Ant2 versions
-
- - magic properties like
build.compiler
may
- disappear and be replaced by a different customization
- concept.
-
- - Ant2 is going to require a JDK version 1.2 or above and a
- JAXP compliant parser version 1.1 or above.
-
- - If you specify more than one target in another target's
- depends attribute, Ant1 will execute these targets from left to
- right (as long as the dependency tree permits it) - Ant2 will
- not guarantee this behavior but will allow build file writers to
- specify the order explicitly.
-
- - Dereferencing a non existent property a via ${a} will result
- in a build failure.
-
-
-
- Support Integration of Ant Into Other Tools
-
- Ant2 will have a clear separation between the front-end that is
- responsible for user interactions, the object model that
- represents the project to build and the part of Ant that runs the
- build process itself . This separation is
- expected to ease the integration of Ant (or parts of it) into
- other products.
-
- Ant2 itself will include a command line front-end and Antidote
- will become the GUI front-end to it. Other front-ends like a
- servlet front-end are expected as well.
-
- In addition to this separation, the following features should
- help people who want to integrate Ant into their products:
-
-
-
- - It will be possible to cancel a running build process.
-
- - Ant will detach from
System.err/.out/.in
- completely and communicate with the front-end via a well defined
- API. The front-end will have to handle user input for tasks
- that need it (tasks that ask for a password for example).
-
- - Tasks will provide some way to identify their attributes
- from the outside. fill in details
-
-
-
- More Control for Users and Build File Writers
-
- Ant2 will use a BuildListener
concept similar to
- the one of Ant1 but may provide a richer set of events. It will be
- possible to attach and detach listeners to a build process from
- within the build file and to modify the behavior of attached
- listeners.
-
- In Ant1 users have little control over how things work. There
- are a couple of magic properties to make Ant chose a preferred
- compiler or modify the CLASSPATH, but they are barely documented.
- If users want to set these properties for every build process,
- they have to learn the undocumented tricks of the
- ANT_OPTS
environment variable or the
- ~/.antrc
file.
-
- Ant2 will have a well defined system to specify user
- preferences. This system will not only let user chose their
- compiler but also give them a chance to provide default values for
- attributes (say you always want the debug
attribute
- of the javac
task to be true - unless it has been
- disabled explicitly).
-
- Documentation System
-
- All tasks will be documented in XML files using a common DTD - task libraries are
- expected to include the documentation using this DTD inside the
- library itself.
-
- Better Subbuild Handling
-
-
-
- Data Types
-
- Ant1 supports a limited set of data types (fileset, patternset
- and path) and at least up to Ant 1.3 it is not possible to
- register custom data types without writing a task that does this.
- Ant2 will provide a built-in mechanism to define new data
- types.
-
- Existing data-types will be improved, the files in a fileset
- can be chosen based on more than just pattern matching for example
- (modification time or permissions for example). Ant2 will have
- built-in tasks for set operations.
-
- Data types and properties will share the same name space and
- follow the same scoping and precedence rules.
-
-
- Multi-Threading of Tasks Within a Target
-
- It will be possible to run several tasks in parallel - these
- tasks will belong to the same target and all tasks will be joined
- at the end of the target.
-
- Internationalization
-
- Ant2 itself will provide internationalized (error) messages and
- provide utility classes to help task writers to do the same.
- .
-
- Ant's primary language and the language of the build file
- will continue to be English.
-
- Rejected Features
-
- This is list is not complete, it just highlights some of the
- rejected features and tries to explain why they've been
- rejected. Two very common reasons to reject something were, that
- the request has been too vague or the same functionality could
- already be provided by some other accepted new feature.
-
- For a complete listing of all requested features, see requested-features.html. The
- discussion on all topics can be followed in the archives
- for ant-dev in threads starting from 2001-03-21 - the subject
- lines contained either [VOTE]
or
- [DISC]
.
-
- Simple Flow-Control
-
- People asking for these kind of things have often heard the
- standard "Ant shall not become yet another scripting language, Ant
- shall not fall into the same traps make/Perl did ..." response
- from the committers and some long-term ant-dev people.
-
- The long version of that answer is:
-
-
- - There are lots of open source scripting languages, there is
- no need to define a new one.
-
- - Ant has been created to be a build tool. While you can use
- it for a whole lot of other things, this is not Ant's primary
- focus (and it shouldn't be). Most use-cases that ask for
- flow-control are out of Ant's scope.
-
- - Ant already provides the requested functionality for many
- common situations. The execon and apply tasks can be used to
- iterate over a set of files as the (planed for Ant2) javaon and
- anton tasks will do.
-
- - Providing flow-control inside Ant's core would increase the
- complexity of this core. This would make it difficult for new
- contributors to understand how Ant works and increase the
- maintenance cost for Ant at the same time. The goal of the Ant
- developers is to push as much complexity and functionality out
- of Ant's core into the tasks as possible.
-
-
- That being said, Ant2 will make it easy to write iteration or
- conditional tasks via the new container task concept. We expect
- foreach, switch and if tasks to be written, but they will probably
- not become core parts of the Ant distribution.
-
- Advanced Conditionals for if/unless Attributes
-
- The argument here is the same as for flow-control. We are
- talking about complexity that can be pushed from the core to tasks
- - and that is what will be done. Instead of additional power for
- the if/unless attributes, Ant2 will have a new task that can set
- properties based on the values of other properties or logical
- combinations of other conditions, something like (making up
- syntax):
-
-
-<condition name="javamail-complete">
- <and>
- <available class="javax.mail.Transport"/>
- <available class="javax.activation.DataHandler"/>
- </and>
-</condition>
-
-
- will become possible
-
- Multi-Threaded Execution of Targets
-
- The general feeling was, that the combination of target
- dependencies and multi-threading would soon become too complex,
- especially since Ant2 will allow people to explicitly enforce the
- order in which (independent) targets will be executed.
-
- This issue will be explored again later, it has not been
- rejected for all time being, but it is out of scope for
- Ant 2.0
-
- Ideas for New Tasks and Tools
-
- Please refer to requested-features.html in the
- section "I. Things that don't affect the core but are
- requests for new tasks or enhancements to existing tasks."
- for this.
-
-
-
diff --git a/docs/ant2/original-specification.html b/docs/ant2/original-specification.html
deleted file mode 100644
index 9c13e9c000..0000000000
--- a/docs/ant2/original-specification.html
+++ /dev/null
@@ -1,294 +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
- - Understandability
- - Extensibility
-
- 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:
-
- - Properties defined on the command line or via a GUI tool
- - Properties defined in the text file which defines the project.
- - Properties defined in a file in the users
user.home
directory
- - Properties defined in the installation directory that can be shared
- by multiple users.
-
- 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:
-
- defaulttarget
defining the default target to be executed if no other target
- is specified when Ant is run
-
- It also has the following optional allowed attributes:
-
- name
defining a name for this project
- taskdir
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 project
- target
defining a target
-
- 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:
-
- - The '/' character is used as a directory seperator
- - The ':' character is used as a path seperator
- - Only relative paths are used
-
- 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:
-
- - Directories are seperated by the forward slash ('/') or backwards
- slash ('\') character.
- - File names starting with either of the above directory seperators are
- considered to be absolute paths.
- - 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.
- - 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.
-
- 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:
-
- - 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.
- - The character immediately before the colon is a alphabetic character
- in the range a-z or A-Z.
- - The character immediately after the colon is either of the allowable
- directory seperators ('/' or '\').
-
- 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.
-
- - JDK 1.1 or greater
- - A JAXP compliant parser on the classpath
-
- 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.
-
-
-
diff --git a/docs/ant2/requested-features.html b/docs/ant2/requested-features.html
deleted file mode 100644
index b6aa8ab438..0000000000
--- a/docs/ant2/requested-features.html
+++ /dev/null
@@ -1,1106 +0,0 @@
-
-
-
-
-
-Requested Features for Ant2
-
-
-
-I. Things that don't affect the core but are requests for new tasks or
-enhancements to existing tasks.
-
-
-"Accepted" for a task doesn't mean that
-task will be a core task (or even be supplied by a voter), just that having
-it (as an optional task) would be acceptable.
-
-
-
- Accepted
-
-
-
--
-Add a new datatype filterset to group token-filters.
-
-
-
-
--
-Make usage of particular filters/filtersets explicit in copy tasks.
-
-
-
-
--
-Make facade tasks for things like
<javac>
-(JikesImpl, ModernImpl, etc.).
-(One candidate is <jar>
, with implementations for
-a <fastjar>
, for example.)
-
-
-
-
--
-Unify multiple similar tasks to use similar forms (eg., all the
-
<javacc>
-type
-tools).
-
-
-
-
-
-
-
-
--
-Better scripting/notification support so the hooks are available to
-send notifications at certain times.
-
-
-
-
--
-Add an
<ant>
task that will find build files according
-to a fileset and invoke a common target in them. (<anton>
?)
-
-
-
-
--
-Add a JavaApply task that executes a given class with files from a
-fileset as arguments (similar to
<apply>
).
-
-
-
-
--
-Include some more sophisticated loggers with the Ant distribution
-especially for sending emails. Make the existing one more flexible
-(stylesheet used by XmlLogger). (Could be part of the same module tasks
-would be developed in?)
-
-
-
-
--
-Better docs (eg., more examples, tutorials, beginner documents, reference
-sheets for tasks, printable version, etc.).
-
-
-
-
-
-
-
-
--
-Task for splitting files (head/tail/split-like functionality).
-
-
-
-
--
-Task to create XMI from Java.
-
-
-
-
--
-Socksified networking tasks, SSH tasks.
-(Peter Donald expressed some legal concerns that might need to be overcome,
-depending on the implementation.)
-
-
-
-
--
-A reachable task that works much like
<available>
,
-for network URLs.
-
-
-
-
--
-Task to extract classes from a jar-file that a given class depends on.
-(Based on
<depend>
or IBM's JAX, for example.)
-
-
-
-
--
-Unify
<available>
and <uptodate>
-into a more general
-<condition>
task support
-AND
/OR
of
-several tests here.
-(Will need more discussion because of vote by Peter Donald.)
-
-
-
-
--
-JSP-compilation task. (Sounds like a candidate for a facade task.)
-
-
-
-
--
-URL-spider task that checks links for missing content or server errors.
-
-
-
-
- Rejected
-
-
--
-Make the default logger's output clear, informative, and terse. (Rejectors
-think it already is.)
-
-
-
-
--
-Add an attribute to
<property>
to read in an entire file
-as the value of a property.
-
-
-
-
--
-Make PATH-handling consistent. Every task that has a PATH attribute
-must also accept references to PATHs.
-
-
-
-
-
-II. Goals that need to be abstract until we get into design
-decisions.
-
-
-During the discussion it became obvious that some things from this list
-are goals for Ant and some should be guidelines for developers.
-Therefore, there are two flavors, "Accepted" and
-"Accepted As Guideline".
-
-
-
- Accepted
-
-
-
--
-Provide a clear mission statement for Ant.
-
-
-
-
--
-Main goals: simplicity, understandability, extensibility.
-
-
-
-
--
-Remove magic properties if at all humanly possible.
-
-
-
-
--
-Remove as much dependency on native scripts as possible.
-
-
-
-
--
-Clean object model (ie., Project/Target/Task).
-
-
-
-
--
-Good event model to integrate well with IDE/GUI/etc.
-
-
-
-
--
-Use a consistent naming scheme for attributes across all tasks.
-
-
-
-
--
-Keep build-file syntax as compatible to Ant1 as possible
-(ie., don't break something just because we can).
-
-
-
-
--
-Keep the interface for tasks as similar to that of Ant1 as
-possible (ie., don't break something just because we can).
-
-
-
-
--
-Ant should be cancelable.
-
-
-
-
- Accepted As Guideline
-
-
-
--
-No commit of new features without documentation.
-
-
-
-
--
-No commit of new features without test-cases.
-
-
-
-
-
-III. Things that are simple and easy to implement, where we expect the
-committers to agree.
-
-
-
- Accepted
-
-
-
--
-Namespace support so different concerns can occupy different namespaces
-from Ant (thus, SAX2/JAXP1.1).
-
-
-
-
-
-
-
-
--
-Remove all deprecated methods, attributes, tasks.
-
-
-
-
--
-Allow all datatypes to be defined anywhere (ie., as children of
-project as well as of target).
-
-
-
-
--
-Make properties fully dynamic (ie., allow their value to be reassigned).
-
-
-
-
--
-Unify the namespace of all data types (ie., properties + filesets +
-patternsets + filtersets).
-
-
-
-
--
-Add a user-defined message if a target will be skipped as a
-result of the specified
if/unless
.
-
-
-
-
--
-Allow user datatypes to be defined via a
<typedef>
-similar to <taskdef>
.
-
-
-
-
-
-IV. Things we probably agree on but need to discuss the details or
-decide between several possible options.
-
-
-"Accepted" means the goal/idea is fine, not that a decision on a
-particular implementation has been made.
-
-
-
- Accepted
-
-
-
--
-The ability for GUI/IDE tools to integrate easily with object model
-without reinventing the wheel and writing their own parser (which
-Antidote was forced to do).
-(Two suggested solutions were allowing GUI developers to extend
-the object model (ie., GUITask extends Task) or to have Task as an
-interface (ie., GUITask implements Task). This way, the GUI tasks could
-be W3C DOM elements, have property vetoers/listeners, etc.)
-
-
-
-
--
-Support for numerous front-ends from command-line over GUI to servlets.
-(Corollary of the above?)
-
-
-
-
--
-Fully interpreted at run-time. (This almost requires some form of
-abstraction/proxy that stands in place of tasks till it is
-interpreted. This can be hash-tables/simple DOM-like model/whatever.)
-
-
-
-
--
-Provide utility classes to aid in building tasks (ie., like
-
<uptodate>
functionality abstracted).
-(Need to become more specific here.)
-
-
-
-
--
-Make ant-call a low-cost operation so it can do certain
-optional/template-like operations.
-(Corollary of "fully interpreted at run-time"?)
-
-
-
-
--
-Allow facilities to build projects from multiple sources (ie., CSS+XML,
-XSLT+XML, Velocity+text or database, from inside jars or normal
-
build.xml
files, etc.)
-(Allow the project tree to be built dynamically.)
-
-
-
-
--
-Move to a system that allows docs to be generated doc snippets
-should be included with the tasks they document.
-(Which DTD? Which tools for generation?)
-
-
-
-
--
-Allow tasks to be loaded from jars. (Use
-either an XML file in
TSK-INF/taskdefs.xml
or a
-manifest file.)
-
-
-
-
--
-Allow documentation to be stored in
.tsk
jars.
-(Corollary of the above two points?)
-
-
-
-
--
-Separate tasks into
.tsk
jars somehow.
-(Decide on categories.
-Probably via function ie., java tasks, file tasks, EJB tasks, etc.)
-
-
-
-
--
-Make having separate build-files easy (à la AntFarm) and importing different
-projects a breeze.
-
-
-
-
--
-Provide support for user-defined task configurations (ie., give
-users the ability to specify a default value for attributes (eg., always
-use
debug="true"
in <javac>
unless
-something else has been specified).
-(Three ideas so far: a CSS-like language,
-a <taskconfig>
element, or
-properties following a specific naming scheme.)
-
-
-
-
--
-Support more control over the properties that are going to be passed
-to subprojects (modules).
-
-
-
-
--
-Task to prompt for user input.
-(Does affect core, as we need a means to request input from the front-end.)
-
-
-
-
--
-Add CVS login feature.
-(Requires handling of user input.)
-
-
-
-
--
-Easier installation process. GUI, maybe webstart from the homepage.
-This includes asking the user whether he wants to use optional tasks
-and downloads the required libs, automatic upgrades and so on.
-
-Self-extracting jar installer:
-
- java -jar jakarta-ant-1.3-bin.jar
-
-Prompts for destination directory, extracts archive, fixes all
-text files with <fixCRLF>
task; on UNIX,
-makes scripts executable.
-Could also modify ant scripts with the location of ANT_HOME
.
-
-
-
-
-
-
-
-
--
-Detach Ant from
System.err
/.in
/.out
.
-(Beware of problems with spawned processes.)
-
-
-
-
--
-Build-files should be declarative in nature.
-
-
-
-
- Rejected
-
-
--
-It should be possible to modify details of the actual build (e.g. classpath,
-compiler used, etc.) without the need to change the build specification.
-(Do
build.compiler
and build.sysclasspath
-cover everything, or do we need to add more stuff like this?)
-
-
-
-
--
-Better sub-project handling
-(whatever that means in detail).
-
-
-
-
-
-V. Things we probably don't agree on.
-
-Datatypes
-
-
-
- Accepted
-
-
-
-
-
-
-
--
-Provide support for non-hardwired (ie., loadable) low-level
-components (mappers/itemset-filters/converters). Allow them to be
-loaded in either globally or via a new classloader.
-
-
-
-
--
-Provide support for non-hardwired (ie., loadable) converters.
-
-Q: What is a converter? Is this an implementation detail?
-
-A: Not an implementation detail, but a way to extend the engine
-to convert more datatypes. Currently, we have a fixed set that is
-expanded on occasion (ie., includes primitive types + File). Instead
-of spreading converting code throughout the tasks, it can be centralized
-into one component and used by the engine. This becomes particularly
-relevent if you build Ant-based testing systems and use Ant in certain
-web-related areas.
-
-
-
-
--
-Set-arithmetic for fileset/patternset/*set.
-
-
-
-
--
-Inheritance of Ant properties/datatypes/context/etc. in project hierarchy.
-
-
-
-
- Rejected
-
-
-
-
-
-
-
-
-
-
-
--
-Make all datatypes interfaces to allow them to be customized in many
-ways.
-
-
-
-
--
-Inheritance between Ant datatypes (ie., fileset A inherits from
-fileset B (includes all entries in A).
-
-
-
-
--
-Homogenize notion of PATHs and filesets.
-
-
-
-Ant's goals
-
-
-
- Accepted
-
-
-
--
-Provide support for CJAN.
-
-Q: In what way?
-A: Probably by supplying a set of tasks that download versioned
-binaries and their associated dependencies, caching the downloads
-in a known place and updating binaries when required.
-("When required" being indicated by a change in property values).
-
-
-
-
- Rejected (as a primary goal)
-
-
-
--
-Make it possible to re-use the task engine for other things
-(ie., Installshield-type app, Peter's cron-server, and other task-based
-operations).
-
-
-
-Class-loading
-
-
-
- Rejected
-
-
-
--
-Force resolution of classes on loading, to identify class-loader
-issues early (at least in global classloader).
-
-
-
-
-
--
-Ignore any classes contained in the damned ext dirs of a
-JVM possibly by launching with something like:
-
- jar -Djava.ext.dir=foo -jar ant.jar
-
-(Accepted if optional.)
-
-
-
-
-Workspace/sub-build issues
-
-
-
- Accepted
-
-
-
--
-Create the concept of workspace so that projects can be built in a
-DAG and thus enable projects like Catalina/Tomcat to have an easy
-build process. It also helps CJAN to a lesser degree and would
-partially solve the jars-in-CVS thing.
-
-
-
-
--
-Allow a target to depend on a target in another build-file.
-
-
-
-
-
- Rejected
-
-
-
--
-Project inheritance. (What's this?)
-
-
-
-
--
-Target inheritance. That is, the ability to include targets from other
-project files, overriding them as necessary (so, cascading project
-files).
-
-
-
-
--
-Add an attribute to
<ant>
to feed back the environment
-(properties and taskdefs) from the child build to the parent.
-
-
-
-
--
-Allow a target to reference properties defined in another build-file.
-
-
-
-
-Documentation system
-
-
-
- Accepted (with no decision on which system to use)
-
-
-
--
-Generate docs by Anakia/XSLT.
-(Corollary of "move to a system that allows docs to be generated"?)
-
-
-
-
-Task API
-
-
-
- Accepted
-
-
-
--
-Tasks provide some way to identify their attributes from the outside.
-
-Possible solutions include a special method like
getProperties()
,
-an external describing file shipping with the task class or special
-Javadoc comments parsed by a custom doclet. Whatever the method, it
-should not impose any cost on run-time, as it is only used a small
-percentage of the time (design-time).
-
-
-
-
--
-Provide
"failonerror"
-like functionality to all tasks.
-(Provide this as an aspect?? Much like logging aspect or classloader aspect).
-
-
-
-
- Rejected
-
-
-
--
-Tasks should have access to its own XML representation.
-
-
-
-
--
-Task level if and unless attributes.
-
-
-
-
--
-Allow tasks to find out, whether another task has completed successfully.
-
-
-
-
-Logging
-
-
--
-Allow build-file writers to modify logging (verbosity, for example)
-on a target-by-target or task-by-task basis.
-
-
-
-
--
-Make loggers configurable via build.xml.
-
-
-
-
-Multi-threading
-
-
-
- Accepted
-
-
-
--
-Multi-threaded execution of tasks within the same target.
-
-
-
-
- Rejected
-
-
-
--
-Multithreaded execution of targets.
-
-
-
-
-Procedural versus purely declarative
-
-
-
- Rejected
-
-
-
--
-Simple flow-control (
if-then-else
, for
)
-
-
-
-
--
-Targets should be like methods, including a return value.
-
-
-
-
--
-Build-files should be purely declarative.
-
-
-
-
-Properties
-
-
-
- Accepted
-
-
-
--
-Ability to manage scoping of properties in general
-(ie., target/project/workspace).
-
-
-
-
-Templates
-
-
-
- Rejected
-
-
-
--
-It should be possible to provide general/(template?) build
-specifications, and to declare, for a concrete item, that it should be
-built according to such a general specification.
-
-
-
-
-XML issues
-
-
-
- Accepted
-
-
-
--
-A built-in mechanism to include build-file fragments something
-that doesn't use
SYSTEM
entities at all and therefore is
-XSchema-friendly, allows for property expansions, etc.
-
-
-
-
--
-Allow Ant to farm out attributes and elements that are not
-in the Ant namespace to other components (ie., hand
doc:
elements
-to the Documentation component or log:
attributes to the Log
-policy component, etc.
-
-
-
-
- Rejected
-
-
-
--
-Let Ant ignore but warn if unknown XML elements or attributes
-occur in a build-file.
-
-
-
-
-Core extensions
-
-
-
- Accepted
-
-
-
--
-Allow sequence to be specified in
"depends"
attribute,
-or enhance <antcall>
to work with current list of executed
-targets.
-
-
-
-
--
-Provide a way to define the order in which targets that a given target
-depends upon get executed. (Same as above?)
-
-
-
-
--
-Support nesting tasks into other elements not just as children of
-target as proposed by Thomas Christen in
-
-his mail message.
-
-
-
-
--
-Define task contexts that define various common aspects (logging,
-failure handling, etc.), and assign them to tasks.
-
-
-
-
- Rejected
-
-
-
--
-Allow named tasks to be defined by
<script>
elements.
-
-
-
-
--
-Specify an OnFail task or target that runs in case of a build
-failure.
-
-
-
-
--
-Make
if/unless
attributes check for the value of a property, not
-only its existance.
-
-
-
-
--
-Check for more than one condition in
if/unless
attributes.
-
-
-
-
-Organization
-
-
-
- Rejected
-
-
-
--
-Separate CVSes and code hierarchies for:
-
-
-- task engine [org.apache.task.*]
-- project engine (ie., model of targets/projects/workspaces) +
-support/utility classes [org.apache.ant.*]
-- core tasks (ie., tasks supported by Ant contributors) [org.apache.???]
-
-
-
-
-Miscellaneous
-
-
-
- Accepted
-
-
-
-
-
-
-
-
-VI. Things that were submitted late
-
-
-
-
- Rejected
-
-
-
--
-Integration of the
<depend>
and <javac>
-tasks.
-
-
-
-
--
-Recursive property resolution (ie., resolving
${dist.${name}.dir}
)
-
-
-
-
-
-
diff --git a/docs/ant2/requested-features.txt b/docs/ant2/requested-features.txt
deleted file mode 100644
index ba8d855072..0000000000
--- a/docs/ant2/requested-features.txt
+++ /dev/null
@@ -1,782 +0,0 @@
-
-Status:
-=======
-
-The committers have cast votes on all items (except those that came in
-too late) and the results are listed below - the next step will be a
-design phase.
-
-This list of items will be summarized into an Ant2 specification soon.
-
-I. Things that don't affect the core but are requests for new tasks or
-enhancements of existing tasks.
-======================================================================
-
-[ACCEPTED] for a task doesn't mean that task will be core tasks (or
-even be supplied by a voter), just that having them (as optional
-tasks) would be acceptable.
-
-* Add a new datatype filterset to group token-filters
-
- [ACCEPTED]
-
-* make usage of particular filters/filtersets explicit in copy tasks
-
- [ACCEPTED]
-
-* make facade tasks for things like javac (JikesImpl, ModernImpl etc)
-
- One candidate is jar with implementations for fastjar
- for example.
-
- [ACCEPTED]
-
-* unify multiple similar tasks to use similar forms (ie all the javacc
- type tools)
-
- [ACCEPTED]
-
-* Obfuscating task
-
- [ACCEPTED]
-
-* Add an task that will find build files according to a fileset
- and invokes a common target in them.
-
- ?
-
- [will need more discussion because of votes by Peter Donald and
- Stefan Bodewig]
-
- [finally ACCEPTED]
-
-* Add a JavaApply task that executes a given class with files from a
- fileset as arguments - similar to .
-
- [will need more discussion because of votes by Peter Donald and
- Stefan Bodewig]
-
- [finally ACCEPTED]
-
-* Include some more sophisticated loggers with the Ant distribution -
- especially for sending emails. Make the existing one more flexible
- (stylesheet used by XmlLogger).
-
- Could be part of the same module tasks would be developed in?
-
- [will need more discussion because of vote by Conor MacNeill]
-
- [finally ACCEPTED]
-
-* make the default logger's output clear, informative, and terse.
-
- Actually, this is a little bit abstract, but doesn't apply to the
- core either.
-
- [will need more discussion because of vote by Conor MacNeill]
-
- [REJECTED - vetoes by Conot MacNeill and Stefan Bodewig]
-
-* Better docs.
-
- More examples. Tutorials, beginner documents, reference sheets for
- tasks, printable version.
-
- [ACCEPTED]
-
-* RPM task.
-
- [ACCEPTED]
-
-* add an attribute to to read in an entire file as the
- value of a property.
-
- [will need more discussion because of vote by Peter Donald]
-
- [REJECTED - veto by Peter Donald]
-
-* Task for splitting files (head/tail/split like functionality).
-
- [ACCEPTED]
-
-* Task to create XMI from Java.
-
- [ACCEPTED]
-
-* socksified networking tasks, SSH tasks.
-
- [Peter Donald expressed some legal concerns that might be overcome,
- depending on the implementation]
-
-* a reachable task that works much like available for network URLs.
-
- [ACCEPTED]
-
-* make PATH handling consistent. Every task that has a PATH attribute
- must also accept references to PATHs.
-
- [will need more discussion because of vote by Stefan Bodewig]
-
- [REJECTED - vetoes by Conor MacNeill, Glenn McAllister and Stefan Bodewig]
-
-* Task to extract classes from a JAR file that a given class depends
- on.
-
- Based on or IBM's JAX for example.
-
- [ACCEPTED]
-
-* Unify and into a more general
- task, support AND/OR of several tests here.
-
- [will need more discussion because of vote by Peter Donald]
-
-* jsp-compilation task
-
- Sounds like a candidate for a facade task.
-
- [ACCEPTED]
-
-* URL-spider task that checks links for missing content or server errors
-
- [ACCEPTED]
-
-II. Abstract goals that need to be abstract until we get into design
-decisions.
-======================================================================
-
-During discussion it became obvious, that some things from this list
-are goals for Ant and some should be guidelines for developers,
-therefore there are two flavors, [ACCEPTED] and [ACCEPTED AS GUIDELINE].
-
-* Provide a clear mission statement for Ant.
-
- [ACCEPTED]
-
-* Main goals: Simplicity, Understandability, Extensibility
-
- [ACCEPTED]
-
-* remove magic properties if at all humanly possible
-
- [ACCEPTED]
-
-* remove as much dependency on native scripts as possible.
-
- [ACCEPTED]
-
-* clean object model (ie Project/Target/Task)
-
- [ACCEPTED]
-
-* good event model to integrate well with IDE/GUI/whatever
-
- [ACCEPTED]
-
-* use a consistent naming scheme for attributes across all tasks
-
- [ACCEPTED]
-
-* keep build file syntax as compatible to Ant1 as possible -
- i.e. don't break something just because we can.
-
- [ACCEPTED]
-
-* keep the interface for Tasks as similar to the one of Ant1 as
- possible - i.e. don't break something just because we can.
-
- [ACCEPTED]
-
-* Ant should be cancelable
-
- [ACCEPTED]
-
-* no commit of new features without documentation
-
- [ACCEPTED AS GUIDELINE]
-
-* no commit of new features without testcases
-
- [ACCEPTED AS GUIDELINE]
-
-III. Things that are simple, easy to implement, where we expect the
-committers to agree
-======================================================================
-
-* namespace support so different concerns can occupy different namespaces
- from ant (thus SAX2/JAXP1.1)
-
- [ACCEPTED]
-
-* Java2
-
- [ACCEPTED]
-
-* remove all deprecated methods, attributes, tasks
-
- [ACCEPTED]
-
-* allow all datatypes to be defined anywhere - i.e. as children of
- project as well as of target.
-
- [ACCEPTED]
-
-* make properties fully dynamic, i.e. allow their value to be reassigned
-
- [will need more discussion because of vote by Glenn McAllister and
- Conor MacNeill]
-
- [finally ACCEPTED]
-
-* unify the namespace of all data types (ie properties + filesets +
- patternset + filtersets).
-
- [ACCEPTED]
-
-* add a user defined message if a target will be skipped because the
- if/unless attribute says so.
-
- [ACCEPTED]
-
-* allow user-datatypes to be defined via a similar to .
-
- [ACCEPTED]
-
-IV. Things we probably agree upon but need to discuss the details or
-decide between several possible options.
-======================================================================
-
-[ACCEPTED] means, the goal/idea is fine, not that a decission on a
-particular implementation has been made.
-
-* The ability for GUI/IDE tools to integrate easily with object model
- without reinventing the wheel and writing their own parser (which
- antidote was forced to do).
-
- Two suggested solutions were allowing GUI developers to extend
- object model (ie GUITask extends Task) or to have Task as interface
- (ie GUITask implements Task). This way the GUI tasks could be W3C
- DOM Elements, have property vetoers/listeners etc.
-
- [ACCEPTED]
-
-* support for numerous frontends - from command line over GUI to servlets
-
- corollary of the above?
-
- [ACCEPTED]
-
-* Fully interpreted at runtime. This almost requires some form of
- abstraction/proxy that stands in place of tasks till it is
- interpreted. This can be hashtables/simple dom-like model/whatever
-
- [ACCEPTED]
-
-* provide utility classes to aid in building tasks. ie like up-to-date
- functionality abstracted
-
- Need to become more specific here.
-
- [ACCEPTED]
-
-* make ant-call a low cost operations so it can certain
- optional/template-like operations
-
- corollary of "fully interpreted at runtime"?
-
- [ACCEPTED]
-
-* allow facilities to build projects from multiple sources. ie CSS+xml
- or XSLT+ XML or Velocity+text or database or from inside jars or normal
- build.xmls etc.
-
- allow the project tree to be built dynamically.
-
- [ACCEPTED]
-
-* move to a system that allows docs to be generated - doc snippets
- should be included with the tasks they document.
-
- Which DTD? Which tools for generation?
-
- [ACCEPTED]
-
-* allow tasks to be loaded from jars. tasks should be indicated by
- either xml file in TSK-INF/taskdefs.xml or manifest file.
-
- [ACCEPTED]
-
-* allow documentation to be stored in .tsk jars
-
- corollary of the two points above?
-
- [ACCEPTED]
-
-* better scripting/notification support so the hooks are available to
- send notifications at certain times.
-
- Which hooks and where?
-
- [will need more discussion because of vote by Peter Donald and
- Simeon Fitch]
-
- [REJECTED - vetoes by Conor MacNeill, Peter Donald and Simeon Fitch]
-
-* separate tasks into .tsk jars somehow. (Probably via function - ie
- java tasks, file tasks, ejb tasks).
-
- Decide on categories.
-
- [will need more discussion because of vote by Conor MacNeill]
-
- [finally ACCEPTED]
-
-* make separate build files easy (ala AntFarm) and importing different
- projects a breeze
-
- [ACCEPTED]
-
-* provide support for user defined task configurations - i.e. give
- users the ability to specify a default value for attributes (always
- use debug="true" in unless something else has been
- specified).
-
- Three ideas so far: a CSS like language, a element,
- properties following a specific naming scheme.
-
- [ACCEPTED]
-
-* support more control over the properties that are going to be passed
- to subprojects (modules)
-
- [ACCEPTED]
-
-* Ask for a new CVS module for Ant tasks.
-
- We need to define rules for this to work - maybe the rules proposed
- for the commons project could give us a start.
-
- [will need more discussion because of vote by Conor MacNeill]
-
- [REJECTED - vetoes by Conor MacNeill and Glenn McAllister]
-
-* It should be possible to modify details of the actual build (e.g. classpath,
- used compiler) without the need to change the build specification.
-
- Do build.compiler and build.sysclasspath cover everything or do we
- need to add more stuff like this?
-
- [will need more discussion because of vote by Conor MacNeill]
-
- [REJECTED - veto by Conor MacNeill]
-
-* Task to prompt for user input.
-
- Does affect core as we need a means to request input from the Frontend.
-
- [ACCEPTED]
-
-* Add cvs login feature.
-
- Requires handling of user input.
-
- [ACCEPTED]
-
-* Easier installation process. GUI - maybe webstart from the homepage.
-
- This includes asking the user whether he wants to use optional tasks
- and downloads the required libs. Automatic upgrades and so on.
-
- Self-extracting jar installer: java -jar jakarta-ant-1.3-bin.jar.
- Prompts for destination directory, extracts archive, fixes all
- text files with fixCRLF task; on UNIX, makes scripts executable.
- Could also modify ant scripts with the location of ANT_HOME.
-
- [ACCEPTED]
-
-* Logo for Ant.
-
- [ACCEPTED]
-
-* detach Ant from System.err/.in/.out.
-
- Beware of problems with spawned processes.
-
- [ACCEPTED]
-
-* better subproject handling
-
- Whatever that means in detail.
-
- [will need more discussion because of vote by Conor MacNeill]
-
- [REJECTED - vetoes by Conor MacNeill and Stefan Bodewig]
-
-* build files should be declarative in nature
-
- [ACCEPTED]
-
-V. Things we probably don't agree on.
-======================================================================
-
-[DISC] Datatypes
-----------------
-
- * Allow mappers to be genericised so that particular features can be modified
- during mapping. Something similar to
-
-
-
-
-
-
-
-
-
-
- [REJECTED - vetoes by Stefan Bodewig and Conor MacNeill, not enough
- positive votes anyway.]
-
- * Allow include/exclude tow work with multiple characteristerics of a file.
- ie include into fileset if file is readable, modified after 29th of Feb,
- has a name that matches patter "**/*.java" and the property "foo.present"
- is set. Something similar to
-
-
-
-
-
-
-
-
-
-
- [ACCEPTED]
-
-* provide datatypes through property tag and remove need for separate free
- standing entities. ie
-
-
-
-
-
-
- [REJECTED - only one +1 vote]
-
-* provide support for non-hardwired (ie loadable) low-level
- components (mappers/itemset-filters/converters). Allow them to be
- loaded in either global or a new classloader.
-
- [ACCEPTED]
-
-* provide support for non-hardwired (ie loadable) converters.
-
- Q: What is a converter? Is this an implementation detail?
- A: Not an implementation detail but a way to extend the engine
- to convert more data types. Currently we have fixed set that is
- expanded on occasion (ie includes primitive types + File). Instead
- of spreading converting code through out tasks it can be centralized
- into one component and used by engine. This becomes particularly
- relevent if you build ant based testing systems and use ant in certain
- web-related areas.
-
- [ACCEPTED]
-
-* Make all datatypes interfaces to allow them to be customized in many
- ways.
-
- [REJECTED - vetoes by Conor MacNeill, Peter Donald and Stefan Bodewig]
-
-* Set arithmetic for fileset/patternset/*set
-
- [ACCEPTED]
-
-* inheritance of ant properties/datatypes/context etc in project hierarchy
-
- [ACCEPTED]
-
-* inheritance of between ant datatypes. ie fileset A inherits from fileset B (includes
- all entries in A).
-
- [REJECTED - vetoes by Conor MacNeill, Peter Donald and Stefan Bodewig]
-
-* Homogenize notion of PATHs and filesets.
-
- [REJECTED - vetoes by Conor MacNeill, Peter Donald and Stefan Bodewig]
-
-[DISC] Ant's goals
-------------------
-
-* make it possible to reuse taskengine for other things. ie
- Installshield type app, Peter's cron-server and other task based
- operations.
-
- [REJECTED as a primary goal - only two +1 votes]
-
-* provide support for CJAN
-
- Q: In what way?
- A: Probably by supplying a set of tasks that download versioned
- binaries and their associated dependencies, caching the downloads
- in a known place and updating binaries when required. ("When required"
- being indicated by a change in property values).
-
- [REJECTED as part of Ant's core - veto by Conor MacNeill, no single +1]
-
-[DISC] class loading
---------------------
-
- * force resolution of classes on loading to identify classloader
- issues early. (At least in global classloader).
-
- [REJECTED - only one +1 vote]
-
-* Ignore any classes contained in the damned ext dirs of a JVM - possibly by launching
- with something like jar -Djava.ext.dir=foo -jar ant.jar
-
- [REJECTED - vetoes by Conor MacNeill, Glenn McAllister and Stefan
- Bodewig, ACCEPTED if optional]
-
-
-[DISC] workspace/subbuild issues
---------------------------------
-
-* create the concept of workspace so that projects can be built in a
- DAG and thus enable projects like catalina/tomcat to have an easy
- build process. It also helps CJAN to a lesser degree and would
- partially solve the JARs in CVS thing.
-
- [ACCEPTED]
-
-* Project inheritance
-
- What's this?
-
- [REJECTED - vetoes by Conor MacNeill, Peter Donald and Stefan Bodewig]
-
-* Target inheritance. ie The ability to include targets from other
- project files overidining them as necessary (so cascading project
- files).
-
- [REJECTED - vetoes by Conor MacNeill, Peter Donald and Stefan Bodewig]
-
-* Add an attribute to to feed back the environment (properties and
- taskdefs) from the child build to the parent.
-
- [REJECTED - vetoes by Conor MacNeill, Peter Donald, Simeon Fitch and
- Stefan Bodewig]
-
-* Allow a target to depend on a target which is in another buildfile.
-
- [ACCEPTED]
-
-* Allow a target to reference properties defined in another buildfile.
-
- [REJECTED - only one +1 vote]
-
-[DISC] documentation system
----------------------------
-
-* generate docs by anakia/XSLT
-
- Corollary of "move to a system that allows docs to be generated"?
-
- [ACCEPTED - with no decision on which system to use]
-
-[DISC] Task API
----------------
-
-* tasks provide some way to identify their attributes from the
- outside.
-
- Possible solutions include a special method like getProperties(), an
- external describing file shipping with the task class or special
- javadoc comments parsed by a custom doclet. Whatever the method it
- should not impose any cost on runtime as it is only used a small
- proportion of the time (design-time).
-
- [ACCEPTED]
-
-* tasks should have access to its own XML representation.
-
- [REJECTED - vetoes by Christoph Wilhelms, Conor MacNeill and Simeon Fitch]
-
-* Task level if and unless attributes.
-
- [REJECTED - no single +1 vote]
-
-* Allow tasks to find out, whether another task has completed successfully.
-
- [REJECTED - vetoes by Conor MacNeill, Glenn McAllister, Peter Donald
- and Stefan Bodewig]
-
-* provide failonerror like functionality to all tasks. (Provide this as an aspect??
- much like logging aspect or classloader aspect).
-
- [ACCEPTED]
-
-[DISC] logging
---------------
-
-* allow build file writers to modify logging (verbosity for example)
- on a target by target or task by task basis.
-
- [ACCEPTED]
-
-* Make loggers configurable via build.xml.
-
- [ACCEPTED]
-
-[DISC] multithrading
---------------------
-
-* Multithreaded execution of tasks within the same target.
-
- [ACCEPTED]
-
-* Multithreaded execution of targets.
-
- [REJECTED - vetoes by Conor MacNeill, Glenn McAllister and Stefan Bodewig]
-
-[DISC] procedural versus purely declarative
--------------------------------------------
-
-* Simple flow control (if-then-else, for)
-
- [REJECTED - vetoes by Conor MacNeill, Glenn McAllister, Peter Donald
- and Stefan Bodewig]
-
-* targets should be like methods including a return value
-
- [REJECTED - vetoes by Conor MacNeill, Glenn McAllister, Peter Donald,
- Simeon Fitch and Stefan Bodewig]
-
-* build files should be purely declarative
-
- [REJECTED - veto by Stefan Bodewig]
-
-[DISC] Properties
------------------
-
-* Ability to manage scopping of properties in general (ie target/project/workspace).
-
- [ACCEPTED]
-
-[DISC] Templates
-----------------
-
-* it should be possible to provide general /(template?)/ build
- specifications, and to declare for a concrete item that it should be
- built according to such a general specification.
-
- [REJECTED - vetoes by Conor MacNeill, Glenn McAllister, Peter Donald
- and Stefan Bodewig]
-
-[DISC] XML issues
------------------
-
-* a built-in mechanism to include build-file fragments - something
- that doesn't use SYSTEM entities at all and therefore is XSchema
- friendly, allows for property expansions ...
-
- [ACCEPTED]
-
-* Let Ant ignore - but warn - if unknown XML elements or attributes
- occur in a build file.
-
- [REJECTED - vetoes by Conor MacNeill, Glenn McAllister, Peter Donald
- and Stefan Bodewig]
-
-* Allow ant to farm out attributes and elements that are NOT in the ant
- namespace to other components. ie hand doc: elements to the Documentation
- component or log: attributes to Log policy component etc
-
- [ACCEPTED]
-
-[DISC] core extensions
-----------------------
-
-* Allow named tasks to be defined by
-