Hi, I've updated the commandline option -projecthelp to output two sorted list of targets, those with and those without a description. This way you get a hint as to which targets are meant to be called from the outside and which are more like internal targets, without losing the complete picture. And ofcourse I also updated the docs :), ahum should have done that the first time around. The patches for build.xml and buildant.xml are a first try to use descriptions on ant itself. Could someone check to see if there are more targets that are meant to be called directly?
A second smaller documentation change was triggered by Paul Arzul's question on ant-user: the possibility to specify more than one target on the commandline was not documented. Regards, Marcel--- iindex.html Sat Sep 09 08:36:54 2000 +++ index.html Mon Sep 11 09:32:41 2000 @@ -99,13 +99,13 @@
To build and use ant you must have a JAXP compliant XML parser installed and available on your classpath.
- If you do not have a JAXP compliant XML parse installed, you may use the reference implementation + If you do not have a JAXP compliant XML parse installed, you may use the reference implementation available from Sun. It is available from http://java.sun.com/xml. Once installed make sure the "jaxp.jar" and "parser.jar" files are in your classpath.
- You will also need the JDK installed on your system, version 1.1 or later. + You will also need the JDK installed on your system, version 1.1 or later. -
+
Building Ant
Go to the directory jakarta-ant.
Make sure the JDK is in you path.
@@ -151,12 +151,12 @@Advanced
There are lots of variants that can be used to run Ant. What you need is at least the following:
-The classpath for Ant must contain ant.jar and any jars/classes
+
The classpath for Ant must contain ant.jar and any jars/classes
needed for your chosen JAXP compliant XML parser.
When you need JDK functionality (like a javac task, or a
rmic task), then for JDK 1.1, the classes.zip
file of the JDK must be added to the classpath; for JDK 1.2, tools.jar
-must be added. The scripts supplied with ant, in the bin directory, will add
+must be added. The scripts supplied with ant, in the bin directory, will add
tools.jar automatically if the JAVA_HOME environment variable is set.
When you are executing platform specific applications (like the exec task, or the cvs task), the property ant.home
@@ -170,25 +170,27 @@
another buildfile, use the commandline option -buildfile <file>,
where <file> is the buildfile you want to use.
You can also set properties which override properties specified in the -buildfile (see the property task). +buildfile (see the property task). This can be done with the -D<property>=<value> option, where <property> is the name of the property and <value> the value.
-To more options are -quiet which instructs Ant to print less +
Two more options are -quiet which instructs Ant to print less information on the console when running. The option -verbose on the other hand makes Ant print more information on the console.
-It is also possible to specify the target that should be executed. Default -the target that is mentioned in the default attribute of the project is -used. This can be overridden by adding the target name to the end of the -commandline.
+It is also possible to specify one or more targets that should be executed. When omitted the target that is mentioned in the default attribute of the project is +used.
+The -projecthelp option gives a list of this projects targets. First those with a description and then those without one.
Commandline option summary:
-ant [options] [target] +ant [options] [targets] Options: -help print this message +-projecthelp print project help information -version print the version information and exit -quiet be extra quiet -verbose be extra verbose +-emacs produce logging information without adornments -logfile <file> use given file for log +-logger <classname> the class which is to perform logging -listener <classname> add an instance of class as a project listener -buildfile <file> use given buildfile -D<property>=<value> use value for given property@@ -295,13 +297,14 @@<target name="build-module-A" if="module-A-present"/><target name="build-own-fake-module-A" unless="module-A-present"/>-If no if and no unless attribute is present, the target will +
If no if and no unless attribute is present, the target will always be executed.
It is a good practice to place your tstamp tasks in a so called initialization target, on which all other targets depend. Make sure that target is always the first one in the depends list of the other targets. In this manual, most initialization targets have the name "init".
+The optional description attribute can be used to provide a one line description of this target that is printed by the -projecthelp commandline option.
A target has the following attributes:
| unless | -the name of the property that must not be set in order + | the name of the property that must not be set in order for this target to execute. | No |
| description | +a short description of this targets function. | +No | +
Tasks
A task is a piece of code that can be executed.
@@ -493,23 +501,23 @@Patterns can be specified inside the buildfile via task attributes or nested elements and via external files. Each line of the external file -is taken as pattern that is added to the list of include or exclude +is taken as pattern that is added to the list of include or exclude patterns.
Patterns
As described earlier, patterns are used for the inclusion and exclusion.
@@ -698,7 +706,7 @@
"**/CVS/*",
"**/.cvsignore"
-If you do not want these default excludes applied, you may disable them with the
+If you do not want these default excludes applied, you may disable them with the
defaultexcludes="no" attribute.
PatternSets
Patterns can be grouped to sets and later be referenced by their id
@@ -755,7 +763,7 @@
that support this feature or at the same level as target
- i.e. as children of project.
PatternSets can be specified as nested
-<patternset>
+<patternset>
elements. In addition FileSet holds an implicit PatternSet and
supports the nested <include> and
<exclude> elements of PatternSet directly as well
@@ -921,9 +929,9 @@
AntStructure
-Description:
+Description:
Generates a DTD for Ant build files which contains information -about all tasks currently known to Ant.
+about all tasks currently known to Ant.Note that the DTD generated by this task is incomplete, you can
always add XML entities using Handles packages/modules retrieved from a
+ Handles packages/modules retrieved from a
CVS repository. When doing automated builds, the get task should be
preferred over the checkout command, because of speed. deletes all files with the extension " deletes all files with the extension "<taskdef>. See
file
- the file or single directory of which the permissions
+ the file or single directory of which the permissions
must be changed.
exactly one of the two or nested
<fileset> elements.
dir
- the directory which holds the files whose permissions
+ the directory which holds the files whose permissions
must be changed.
@@ -1246,7 +1254,7 @@
Cvs
Description
-
@@ -1388,7 +1396,7 @@
includes="**/*.bak"
/>
-includes
Comma separated list of patterns of files that must be
- deleted. All files are in the current directory
+ deleted. All files are in the current directory
and any sub-directories are deleted when omitted.
No
.bak" from the current directory
+.bak" from the current directory
and any sub-directories.
Deltree
@@ -1815,7 +1823,7 @@
Examples
-@@ -1964,10 +1972,10 @@ archive with http/ftp. The usetimestamps option enables you to control downloads so that the remote file is -only fetched if newer than the local copy. If there is no local copy, the download always takes +only fetched if newer than the local copy. If there is no local copy, the download always takes place. When a file is downloaded, the timestamp of the downloaded file is set to the remote timestamp, -if the JVM is Java1.2 or later. -NB: This timestamp facility only works on downloads using the HTTP protocol. +if the JVM is Java1.2 or later. +NB: This timestamp facility only works on downloads using the HTTP protocol.
<genkey alias="apache-group" storepass="secret" +
<genkey alias="apache-group" storepass="secret" dname="CN=Ant Group, OU=Jakarta Division, O=Apache.org, C=US" />
Parameters
| offline | -True if this link is not available online at the time of + | True if this link is not available online at the time of generating the documentation | No | Only if the offline attribute is true |
groups
+ +groups
Separates packages on the overview page into whatever groups you specify, one group per table. This performs the same role as the group attribute. You can use either syntax (or both at once), but with the @@ -2930,7 +2938,7 @@ <link offline="true" href="" packagelistLoc="C:\tmp"/> <link href="" </javadoc> - +
Mkdir
Description
@@ -2966,40 +2974,40 @@--- a/mod1.0/A Mon Jun 5 17:28:41 2000 +++ a/mod1.1/A Mon Jun 5 17:28:49 2000 -+ the leading a/ will be stripped.
Property
@@ -3079,7 +3087,7 @@ builds using the following: <property file="${user.home}/.ant-global.properties" />
since the "user.home" property is defined by the Java virtual machine -to be your home directory. This technique is more appropriate for Unix than +to be your home directory. This technique is more appropriate for Unix than Windows since the notion of a home directory doesn't exist on Windows. On the JVM that I tested, the home directory on Windows is "C:\". Different JVM implementations may use other values for the home directory on Windows. @@ -3111,14 +3119,14 @@
Examples
- <rename src="" dest="${name}-${version}.jar" />
+ <rename src="" dest="${name}-${version}.jar" />
Renames the file foo.jar to ${name}-${version}.jar (assuming name
and version being predefined properties). If a file named ${name}-${version}.jar
already exists, it will be removed prior to renaming foo.jar.
Replace
Description
-Replace is a directory based task for replacing the occurrence of a given string with another string +
Replace is a directory based task for replacing the occurrence of a given string with another string in selected file.
If you want to replace a text that crosses line boundaries, you
must use a nested <replacetoken> element.
Examples
-+<replace dir="${src}" value="wombat"> <include name="**/*.html" /> <replacetoken><[CDATA[multi line @@ -3206,7 +3214,7 @@ line\ntoken" with the string "wombat", in all HTML files in the directory${src}.Where \n is the platform specific line separator. -+<replace file="${src}/index.html"> <replacetoken><[CDATA[two line token]]></replacetoken> @@ -3312,7 +3320,7 @@
Unjar/Unzip
Description
Unzips a zip- or jarfile.
-For JDK 1.1 "last modified time" field is set to current time instead of being +
For JDK 1.1 "last modified time" field is set to current time instead of being carried from zipfile.
File permissions will not be restored on extracted files.
Parameters
@@ -3713,7 +3721,7 @@Description
Untars a tarfile.
File permissions will not be restored on extracted files. -
For JDK 1.1 "last modified time" field is set to current time instead of being +
For JDK 1.1 "last modified time" field is set to current time instead of being carried from tarfile.
Parameters
| remotedir | -the directory to which to upload files on the + | the directory to which to upload files on the ftp server. | No |
| action | -the ftp action to perform, defaulting to "send". + | the ftp action to perform, defaulting to "send". Currently supports"put", "get", "del", and "list". | No |
| binary | -selects binary-mode ("yes") or text-mode - ("no") transfers. + | selects binary-mode ("yes") or text-mode + ("no") transfers. Defaults to "yes" | No |
| verbose | -displays information on each file transferred if set + | displays information on each file transferred if set to "yes". Defaults to "no". | No |
| depends | -transfers only new or changed files if set to + | transfers only new or changed files if set to "yes". Defaults to "no". | No |
| strictargs | Tells the NetRexx compiler that method calls always
- need parentheses, even if no arguments are needed, e.g.
- aStringVar.getBytes vs.
+ need parentheses, even if no arguments are needed, e.g.
+ aStringVar.getBytes vs.
aStringVar.getBytes() |
No | |
| strictimport | -Whether classes need to be imported explicitly using an
- import statement. By default the NetRexx compiler will
+ | Whether classes need to be imported explicitly using an
+ import statement. By default the NetRexx compiler will
import certain packages automatically |
No |
