From 4b901d5a842154a5cdd6aab05031405bcebfdefc Mon Sep 17 00:00:00 2001 From: Steve Loughran Date: Thu, 13 Jan 2005 23:09:32 +0000 Subject: [PATCH] doc updates; especially command line options, why we hate CLASSPATH and ant.file.* I have declared a policy on what we will name new properties. Is this a good formal policy to have? git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@277357 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/CoreTypes/selectors.html | 10 ++--- docs/manual/running.html | 60 ++++++++++++++++++++++------ 2 files changed, 52 insertions(+), 18 deletions(-) diff --git a/docs/manual/CoreTypes/selectors.html b/docs/manual/CoreTypes/selectors.html index b841f2261..149f4de3a 100755 --- a/docs/manual/CoreTypes/selectors.html +++ b/docs/manual/CoreTypes/selectors.html @@ -260,7 +260,7 @@

Depth Selector

The <depth> tag selects files based on - how many directy levels deep they are in relation to the base + how many directory levels deep they are in relation to the base directory of the fileset.

@@ -759,7 +759,7 @@

- + @@ -792,7 +792,7 @@ - + - + @@ -1319,7 +1319,7 @@ Programming Selectors in Ant.

-

Copyright © 2002-2004 The Apache Software +

Copyright © 2002-2005 The Apache Software Foundation. All rights Reserved.

diff --git a/docs/manual/running.html b/docs/manual/running.html index d2cd43a5f..877bacb79 100644 --- a/docs/manual/running.html +++ b/docs/manual/running.html @@ -106,6 +106,8 @@ Options: -s <file> the filesystem and use it -nice number A niceness value for the main thread: 1 (lowest) to 10 (highest); 5 is the default + -nouserlib Run ant without using the jar files from ${user.home}/.ant/lib + -noclasspath Run ant without using CLASSPATH

For more information about -logger and -listener see @@ -122,26 +124,29 @@ default directories scanned are ANT_HOME/lib and a user specific directory, ${user.home}/.ant/lib. This arrangement allows the Ant installation to be shared by many users while still allowing each user to deploy additional jars. Such additional jars could be support jars for Ant's optional tasks or jars -containing third-party tasks to be used in the build. It also allows the main Ant -installation to be locked down which will please system adminstrators. +containing third-party tasks to be used in the build. It also allows the main Ant installation to be locked down which will please system adminstrators.

Additional directories to be searched may be added by using the -lib option. The -lib option specifies a search path. Any jars or classes in the directories of the path will be added to Ant's classloader. The order in which jars are -added to the classpath is as follows +added to the classpath is as follows:-

Note that the CLASSPATH environment variable is passed to Ant using a -lib -option. Ant itself is started with a very minimalistic classpath. +option. Ant itself is started with a very minimalistic classpath. +Ant should work perfectly well with an empty CLASSPATH environment variable, +something the the -noclasspath option actually enforces. We get many more support calls related to classpath problems (especially quoting problems), than +we like. +

@@ -213,14 +218,14 @@ set):

Java System Properties

-

Some of Ants core classes ant tasks can be configured via system properties.

-

So here the result of a search through the codebase. Because system properties are +

Some of Ant's core classes ant tasks can be configured via system properties.

+

Here is the result of a search through the codebase. Because system properties are available via Project instance, I searched for them with a 

     grep -r -n "getPropert" * > ..\grep.txt
command. After that I filtered out the often-used but not-so-important values (most of them -read-only values): path.separator, ant.home, basedir, user.dir, os.name, ant.file, +read-only values): path.separator, ant.home, basedir, user.dir, os.name, line.separator, java.home, java.version, java.version, user.home, java.class.path
And I filtered out the getPropertyHelper access.

Algorithm's
Algorithm options
Name Description
Cache's
Cache options
propertyfile Use the java.util.Properties class and its possibility @@ -804,7 +804,7 @@
Comparator's
Comparator options
equal Very simple object comparison.
@@ -231,11 +236,31 @@ And I filtered out the getPropertyHelper access.

 - + + + + + + + + + + + + + + @@ -269,7 +294,7 @@ org.apache.tools.ant.Executor implementation specified here. @@ -373,7 +398,7 @@ org.apache.tools.ant.Executor implementation specified here. - + @@ -400,6 +425,15 @@ org.apache.tools.ant.Executor implementation specified here.
ant.executor.classclassname; default is org.apache.tools.ant.helper.DefaultExecutorclassname; default is org. apache. tools. ant. helper. DefaultExecutor Since Ant 1.6.3 Ant will delegate Target invocation to the org.apache.tools.ant.Executor implementation specified here.
ant.fileread only: full filename of the build fileThis is set to the name of the build file. In + + <import>-ed files, this is set to the containing build file. +
ant.file.*read only: full filename of the build file of Ant projects + This is set to the name of a file by project; + this lets you determine the location of + <import>-ed files, +
ant.input.properties filename (required)ant.regexp.regexpimpl classname classname for a RegExp implementation; if not set Ant tries to - find another (Jdk14, Oro...); + find another (JDK14+, Apache Oro...); RegExp-Mapper "Choice of regular expression implementation"
org.apache.tools.ant.ProjectHelper classname (optional, default 'org. apache. tools. ant. ProjectHelper')classname (optional, default 'org.apache.tools.ant.ProjectHelper') specifies the classname to use as ProjectHelper. The class must extend org.apache.tools.ant.ProjectHelper.
+

+If new properties get added (it happens), expect them to appear under the +"ant." and "org.apache.tools.ant" prefixes, unless the developers have a +very good reason to use another prefix. Accordingly, please avoid using +properties that begin with these prefixes, to reduce the risk that future +Ant releases break your build file. +

+ +

Cygwin Users

The Unix launch script that come with Ant works correctly with Cygwin. You should not have any problems launching Ant form the Cygwin shell. It is important @@ -413,7 +447,7 @@ path.

OS/2 Users

-

The OS/2 lanuch script was developed so as it can perform complex task. It has two parts: +

The OS/2 launch script was developed so as it can perform complex tasks. It has two parts: ant.cmd which calls Ant and antenv.cmd which sets environment for Ant. Most often you will just call ant.cmd using the same command line options as described above. The behaviour can be modified by a number of ways explained below.

@@ -476,7 +510,7 @@ classpath possible, generally just the ant-launcher.jar.
-

Copyright © 2000-2004 The Apache Software Foundation. All rights +

Copyright © 2000-2005 The Apache Software Foundation. All rights Reserved.