Browse Source

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
master
Steve Loughran 20 years ago
parent
commit
4b901d5a84
2 changed files with 52 additions and 18 deletions
  1. +5
    -5
      docs/manual/CoreTypes/selectors.html
  2. +47
    -13
      docs/manual/running.html

+ 5
- 5
docs/manual/CoreTypes/selectors.html View File

@@ -260,7 +260,7 @@
<h4>Depth Selector</h4> <h4>Depth Selector</h4>


<p>The <code>&lt;depth&gt;</code> tag selects files based on <p>The <code>&lt;depth&gt;</code> 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. directory of the fileset.
</p> </p>


@@ -759,7 +759,7 @@
</ul></p> </ul></p>


<table border="1" cellpadding="2" cellspacing="0"> <table border="1" cellpadding="2" cellspacing="0">
<tr><td colspan="2"><font size="+1"><b> Algorithm's </b></font></td></tr>
<tr><td colspan="2"><font size="+1"><b> Algorithm options</b></font></td></tr>
<tr> <tr>
<td valign="top"><b>Name</b></td> <td valign="top"><b>Name</b></td>
<td valign="top"><b>Description</b></td> <td valign="top"><b>Description</b></td>
@@ -792,7 +792,7 @@
</ul> </ul>
</td> </td>
</tr> </tr>
<tr><td colspan="2"><font size="+1"><b> Cache's </b></font></td></tr>
<tr><td colspan="2"><font size="+1"><b> Cache options </b></font></td></tr>
<tr> <tr>
<td valign="top"> propertyfile </td> <td valign="top"> propertyfile </td>
<td valign="top"> Use the java.util.Properties class and its possibility <td valign="top"> Use the java.util.Properties class and its possibility
@@ -804,7 +804,7 @@
</ul> </ul>
</td> </td>
</tr> </tr>
<tr><td colspan="2"><font size="+1"><b> Comparator's </b></font></td></tr>
<tr><td colspan="2"><font size="+1"><b> Comparator options</b></font></td></tr>
<tr> <tr>
<td valign="top"> equal </td> <td valign="top"> equal </td>
<td valign="top"> Very simple object comparison. </td> <td valign="top"> Very simple object comparison. </td>
@@ -1319,7 +1319,7 @@
<a href="selectors-program.html">Programming Selectors in Ant</a>.</p> <a href="selectors-program.html">Programming Selectors in Ant</a>.</p>


<hr> <hr>
<p align="center">Copyright &copy; 2002-2004 The Apache Software
<p align="center">Copyright &copy; 2002-2005 The Apache Software
Foundation. All rights Reserved.</p> Foundation. All rights Reserved.</p>


</body> </body>


+ 47
- 13
docs/manual/running.html View File

@@ -106,6 +106,8 @@ Options:
-s &lt;file&gt; the filesystem and use it -s &lt;file&gt; the filesystem and use it
-nice number A niceness value for the main thread: -nice number A niceness value for the main thread:
1 (lowest) to 10 (highest); 5 is the default 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
</pre> </pre>
<p>For more information about <code>-logger</code> and <p>For more information about <code>-logger</code> and
<code>-listener</code> see <code>-listener</code> 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 ${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. 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 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.
</p> </p>


<p> <p>
Additional directories to be searched may be added by using the -lib option. 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 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 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:-
</p> </p>


<ul> <ul>
<li>-lib jars in the order specified by the -lib elements on the command line</li> <li>-lib jars in the order specified by the -lib elements on the command line</li>
<li>jars from ${user.home}/.ant/lib</li>
<li>jars from ${user.home}/.ant/lib (unless -nouserlib is set)</li>
<li>jars from ANT_HOME/lib</li> <li>jars from ANT_HOME/lib</li>
</ul> </ul>


<p> <p>
Note that the CLASSPATH environment variable is passed to Ant using a -lib 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.

</p> </p>


<p> <p>
@@ -213,14 +218,14 @@ set):</p>
</ul> </ul>


<h3><a name="sysprops">Java System Properties</a></h3> <h3><a name="sysprops">Java System Properties</a></h3>
<p>Some of Ants core classes ant tasks can be configured via system properties.</p>
<p>So here the result of a search through the codebase. Because system properties are
<p>Some of Ant's core classes ant tasks can be configured via system properties.</p>
<p>Here is the result of a search through the codebase. Because system properties are
available via Project instance, I searched for them with a available via Project instance, I searched for them with a
<pre> <pre>
grep -r -n "getPropert" * &gt; ..\grep.txt grep -r -n "getPropert" * &gt; ..\grep.txt
</pre> </pre>
command. After that I filtered out the often-used but not-so-important values (most of them command. After that I filtered out the often-used but not-so-important values (most of them
read-only values): <i>path.separator, ant.home, basedir, user.dir, os.name, ant.file,
read-only values): <i>path.separator, ant.home, basedir, user.dir, os.name,
line.separator, java.home, java.version, java.version, user.home, java.class.path</i><br> line.separator, java.home, java.version, java.version, user.home, java.class.path</i><br>
And I filtered out the <i>getPropertyHelper</i> access.</p> And I filtered out the <i>getPropertyHelper</i> access.</p>
<table border="1"> <table border="1">
@@ -231,11 +236,31 @@ And I filtered out the <i>getPropertyHelper</i> access.</p>
</tr> </tr>
<tr> <tr>
<td><code>ant.executor.class</code></td> <td><code>ant.executor.class</code></td>
<td>classname; default is org.apache.tools.ant.helper.DefaultExecutor</td>
<td>classname; default is org. apache. tools. ant. helper. DefaultExecutor</td>
<td><b>Since Ant 1.6.3</b> Ant will delegate Target invocation to the <td><b>Since Ant 1.6.3</b> Ant will delegate Target invocation to the
org.apache.tools.ant.Executor implementation specified here. org.apache.tools.ant.Executor implementation specified here.
</td> </td>
</tr> </tr>

<tr>
<td><code>ant.file</code></td>
<td>read only: full filename of the build file</td>
<td>This is set to the name of the build file. In
<a href="CoreTasks/import.html">
&lt;import&gt;-ed</a> files, this is set to the containing build file.
</td>
</tr>

<tr>
<td><code>ant.file.*</code></td>
<td>read only: full filename of the build file of Ant projects
</td>
<td>This is set to the name of a file by project;
this lets you determine the location of <a href="CoreTasks/import.html">
&lt;import&gt;-ed</a> files,
</td>
</tr>

<tr> <tr>
<td><code>ant.input.properties</code></td> <td><code>ant.input.properties</code></td>
<td>filename (required)</td> <td>filename (required)</td>
@@ -269,7 +294,7 @@ org.apache.tools.ant.Executor implementation specified here.
<td><code>ant.regexp.regexpimpl</code></td> <td><code>ant.regexp.regexpimpl</code></td>
<td>classname</td> <td>classname</td>
<td>classname for a RegExp implementation; if not set Ant tries to <td>classname for a RegExp implementation; if not set Ant tries to
find another (Jdk14, Oro...);
find another (JDK14+, Apache Oro...);
<a href="CoreTypes/mapper.html#regexp-mapper">RegExp-Mapper</a> <a href="CoreTypes/mapper.html#regexp-mapper">RegExp-Mapper</a>
"Choice of regular expression implementation" "Choice of regular expression implementation"
</td> </td>
@@ -373,7 +398,7 @@ org.apache.tools.ant.Executor implementation specified here.
<tr> <tr>
<td><code>org.apache.tools.ant.ProjectHelper</code></td> <td><code>org.apache.tools.ant.ProjectHelper</code></td>
<!-- add the blank after the slash, so the browser can do a line break --> <!-- add the blank after the slash, so the browser can do a line break -->
<td>classname (optional, default 'org. apache. tools. ant. ProjectHelper')</td>
<td>classname (optional, default 'org.apache.tools.ant.ProjectHelper')</td>
<td>specifies the classname to use as ProjectHelper. The class must extend <td>specifies the classname to use as ProjectHelper. The class must extend
org.apache.tools.ant.ProjectHelper. org.apache.tools.ant.ProjectHelper.
</td> </td>
@@ -400,6 +425,15 @@ org.apache.tools.ant.Executor implementation specified here.
</tr> </tr>
</table> </table>


<p>
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.
</p>


<h2><a name="cygwin">Cygwin Users</a></h2> <h2><a name="cygwin">Cygwin Users</a></h2>
<p>The Unix launch script that come with Ant works correctly with Cygwin. You <p>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 should not have any problems launching Ant form the Cygwin shell. It is important
@@ -413,7 +447,7 @@ path.
</p> </p>


<h2><a name="os2">OS/2 Users</a></h2> <h2><a name="os2">OS/2 Users</a></h2>
<p>The OS/2 lanuch script was developed so as it can perform complex task. It has two parts:
<p>The OS/2 launch script was developed so as it can perform complex tasks. It has two parts:
<code>ant.cmd</code> which calls Ant and <code>antenv.cmd</code> which sets environment for Ant. <code>ant.cmd</code> which calls Ant and <code>antenv.cmd</code> which sets environment for Ant.
Most often you will just call <code>ant.cmd</code> using the same command line options as described Most often you will just call <code>ant.cmd</code> using the same command line options as described
above. The behaviour can be modified by a number of ways explained below.</p> above. The behaviour can be modified by a number of ways explained below.</p>
@@ -476,7 +510,7 @@ classpath possible, generally just the ant-launcher.jar.


<br> <br>
<hr> <hr>
<p align="center">Copyright &copy; 2000-2004 The Apache Software Foundation. All rights
<p align="center">Copyright &copy; 2000-2005 The Apache Software Foundation. All rights
Reserved.</p> Reserved.</p>


</body> </body>


Loading…
Cancel
Save