http://git-wip-us.apache.org/repos/asf/ant/blob/97d81a72/manual/install.html ---------------------------------------------------------------------- diff --git a/manual/install.html b/manual/install.html index 6fb04ae..f6699ce 100644 --- a/manual/install.html +++ b/manual/install.html @@ -169,21 +169,21 @@ target="_top">https://archive.apache.org/dist/ant/</a>. The files are organized <td><samp>ant-current-*.asc</samp></td> <td> Security file for checking the correctness of the zip file. This one is - the <a href="https://en.wikipedia.org/wiki/Pretty_Good_Privacy"; target="_blank">PGP</a> signature. + the <a href="https://en.wikipedia.org/wiki/Pretty_Good_Privacy"; target="_top">PGP</a> signature. </td> </tr> <tr> <td><samp>ant-current-*.md5</samp></td> <td> Security file for checking the correctness of the zip file. This one is - the <a href="https://en.wikipedia.org/wiki/Md5"; target="_blank">MD5</a> checksum. + the <a href="https://en.wikipedia.org/wiki/Md5"; target="_top">MD5</a> checksum. </td> </tr> <tr> <td><samp>ant-current-*.sha1</samp></td> <td> Security file for checking the correctness of the zip file. This one is - the <a href="https://en.wikipedia.org/wiki/SHA-1"; target="_blank">SHA1</a> checksum. + the <a href="https://en.wikipedia.org/wiki/SHA-1"; target="_top">SHA1</a> checksum. </td> </tr> <tr> @@ -241,7 +241,7 @@ The more up-to-date the version of Java, the more Ant tasks you get. <h3>Open Source Java Runtimes</h3> <p> -The Ant team strongly supports users running Ant on <a target="_blank" href="http://openjdk.java.net/";>OpenJDK</a> and +The Ant team strongly supports users running Ant on <a href="http://openjdk.java.net/"; target="_top">OpenJDK</a> and other open source Java runtimes, and so strives to have a product that works well on those platforms. </p> @@ -665,8 +665,8 @@ installed. See <a href="#installing">Installing Ant</a> for examples on how to d </p> <p> -<strong>Note</strong>: The bootstrap process of Ant requires a greedy compiler like OpenJDK or Oracle's javac. It does not work -with gcj or kjc. +<strong>Note</strong>: The bootstrap process of Ant requires a greedy compiler like OpenJDK or Oracle's javac. It does +not work with gcj or kjc. </p> <p> @@ -684,8 +684,8 @@ on how to do this. </p> <p> -<em>Since Ant 1.7.0</em>, Ant has a hard dependency on JUnit. The <samp>fetch.xml</samp> build script will download JUnit -automatically, but if you don't use this you must install it manually into <samp>lib/optional</samp> (download it +<em>Since Ant 1.7.0</em>, Ant has a hard dependency on JUnit. The <samp>fetch.xml</samp> build script will download +JUnit automatically, but if you don't use this you must install it manually into <samp>lib/optional</samp> (download it from <a href="https://junit.org/"; target="_top">JUnit.org</a>) if you are using a source distribution of Ant. </p> @@ -708,7 +708,7 @@ The above action does the following: <li>If necessary it will bootstrap the Ant code. Bootstrapping involves the manual compilation of enough Ant code to be able to run Ant. The bootstrapped Ant is used for the remainder of the build steps.</li> <li>Invokes the bootstrapped Ant with the parameters passed to the build script. In this case, these parameters define -an Ant property value and specify the "dist" target in Ant's own <samp>build.xml</samp> file.</li> +an Ant property value and specify the <q>dist</q> target in Ant's own <samp>build.xml</samp> file.</li> <li>Create the <samp>ant.jar</samp> and <samp>ant-launcher.jar</samp> JAR files</li> <li>Create optional JARs for which the build had the relevant libraries. If a particular library is missing from <samp>lib/optional</samp>, then the matching ant-library JAR file will not be created. For @@ -876,7 +876,7 @@ these tasks available. Please refer to the <a href="#optionalTasks">Installing A and <a href="Tasks/telnet.html">telnet</a> tasks<br/> A minimum version of commons-net of 1.4.0 is needed to compile Ant, earlier versions did not support the full range of configuration options.<br/>jakarta-oro 2.0.8 is required together with commons-net 1.4.x at run time.<br/><strong>Note</strong>: do not use commons-net 3.2 - because of <a href="https://issues.apache.org/jira/browse/NET-493";>performance issues</a> + because of <a href="https://issues.apache.org/jira/browse/NET-493"; target="_top">performance issues</a> </td> <td><a href="https://commons.apache.org/net/"; target="_top">https://commons.apache.org/net/</a></td> </tr> @@ -890,8 +890,7 @@ these tasks available. Please refer to the <a href="#optionalTasks">Installing A <td>javax.mail-api.jar</td> <td><a href="Tasks/mail.html">mail</a> task with MIME encoding, and <em><u>deprecated</u></em> <a href="Tasks/mimemail.html">mimemail</a> task</td> - <td><a href="https://javaee.github.io/javamail/"; - target="_top">https://javaee.github.io/javamail/</a></td> + <td><a href="https://javaee.github.io/javamail/"; target="_top">https://javaee.github.io/javamail/</a></td> </tr> <tr> <td>activation.jar<br/>(included in Java 6 and later runtime)</td> @@ -903,8 +902,7 @@ these tasks available. Please refer to the <a href="#optionalTasks">Installing A <tr> <td>jdepend.jar</td> <td><a href="Tasks/jdepend.html">jdepend</a> task</td> - <td><a href="https://github.com/clarkware/jdepend"; - target="_top">https://github.com/clarkware/jdepend</a></td> + <td><a href="https://github.com/clarkware/jdepend"; target="_top">https://github.com/clarkware/jdepend</a></td> </tr> <tr> <td>resolver.jar <strong>1.1 or later</strong></td>
http://git-wip-us.apache.org/repos/asf/ant/blob/97d81a72/manual/listeners.html ---------------------------------------------------------------------- diff --git a/manual/listeners.html b/manual/listeners.html index 12f9243..7677b81 100644 --- a/manual/listeners.html +++ b/manual/listeners.html @@ -27,8 +27,8 @@ <h2 id="Overview">Overview</h2> -<p>Apache Ant has two related features to allow the build process to be monitored: -listeners and loggers.</p> +<p>Apache Ant has two related features to allow the build process to be monitored: listeners and +loggers.</p> <h3 id="Listeners">Listeners</h3> @@ -44,19 +44,16 @@ listeners and loggers.</p> <li>message logged</li> </ul> -<p> - These are used internally for various recording and housekeeping operations, - however new listeners may registered on the command line through the <code>-listener</code> - argument. -</p> +<p>These are used internally for various recording and housekeeping operations, however new +listeners may registered on the command line through the <code>-listener</code> argument.</p> <h3 id="Loggers">Loggers</h3> <p>Loggers extend the capabilities of listeners and add the following features:</p> <ul> - <li>Receives a handle to the standard output and error print streams and - therefore can log information to the console or the <code>-logfile</code> specified file.</li> + <li>Receives a handle to the standard output and error print streams and therefore can log + information to the console or the <code>-logfile</code> specified file.</li> <li>Logging level (<code>-quiet</code>, <code>-verbose</code>, <code>-debug</code>) aware</li> <li>Emacs-mode aware</li> </ul> @@ -71,8 +68,8 @@ listeners and loggers.</p> </tr> <tr> <td><code><a href="#DefaultLogger">org.apache.tools.ant.DefaultLogger</a></code></td> - <td>The logger used implicitly unless overridden with the - <code>-logger</code> command-line switch.</td> + <td>The logger used implicitly unless overridden with the <code>-logger</code> command-line + switch.</td> <td>BuildLogger</td> </tr> <tr> @@ -82,8 +79,8 @@ listeners and loggers.</p> </tr> <tr> <td><code><a href="#MailLogger">org.apache.tools.ant.listener.MailLogger</a></code></td> - <td>Extends DefaultLogger such that output is still generated - the same, and when the build is finished an e-mail can be sent.</td> + <td>Extends DefaultLogger such that output is still generated the same, and when the build is + finished an e-mail can be sent.</td> <td>BuildLogger</td> </tr> <tr> @@ -93,9 +90,9 @@ listeners and loggers.</p> </tr> <tr> <td><code><a href="#Log4jListener">org.apache.tools.ant.listener.Log4jListener</a></code></td> - <td>Passes events to Apache Log4j for highly customizable logging.<br/> - <em><u>Deprecated</u></em>: Apache Log4j (1.x) is not developed any more. Last - release is 1.2.17 from 26 May 2012 and contains vulnerability issues.</td> + <td>Passes events to Apache Log4j for highly customizable + logging.<br/><em><u>Deprecated</u></em>: Apache Log4j (1.x) is not developed any more. Last + release is 1.2.17 from 26 May 2012 and contains vulnerability issues.</td> <td>BuildListener</td> </tr> <tr> @@ -115,13 +112,14 @@ listeners and loggers.</p> </tr> <tr> <td><code><a href="#SimpleBigProjectLogger">org.apache.tools.ant.listener.SimpleBigProjectLogger</a></code></td> - <td>Prints the project name for subprojects only, otherwise like NoBannerLogger <em>Since Ant 1.8.1</em></td> + <td>Prints the project name for subprojects only, otherwise like NoBannerLogger <em>Since Ant + 1.8.1</em></td> <td>BuildLogger</td> </tr> <tr> <td><code><a href="#ProfileLogger">org.apache.tools.ant.listener.ProfileLogger</a></code></td> - <td>The default logger, with start times, end times and - durations added for each task and target.</td> + <td>The default logger, with start times, end times and durations added for each task and + target.</td> <td>BuildLogger</td> </tr> </table> @@ -137,9 +135,9 @@ listeners and loggers.</p> <pre>ant -logger org.apache.tools.ant.NoBannerLogger</pre> <h3 id="MailLogger">MailLogger</h3> -<p>The MailLogger captures all output logged through DefaultLogger (standard Ant -output) and will send success and failure messages to unique e-mail lists, with -control for turning off success or failure messages individually.</p> +<p>The MailLogger captures all output logged through DefaultLogger (standard Ant output) and will +send success and failure messages to unique e-mail lists, with control for turning off success or +failure messages individually.</p> <p>Properties controlling the operation of MailLogger:</p> <table> @@ -161,19 +159,18 @@ control for turning off success or failure messages individually.</p> <tr> <td><code>MailLogger.user</code></td> <td>user name for SMTP auth</td> - <td>Yes, if SMTP auth is required on your SMTP server<br/> - the email message will be then sent using MIME and requires JavaMail</td> + <td>Yes, if SMTP auth is required on your SMTP server<br/> the email message will be then sent + using MIME and requires JavaMail</td> </tr> <tr> <td><code>MailLogger.password</code></td> <td>password for SMTP auth</td> - <td>Yes, if SMTP auth is required on your SMTP server<br/> - the email message will be then sent using MIME and requires JavaMail</td> + <td>Yes, if SMTP auth is required on your SMTP server<br/> the email message will be then sent + using MIME and requires JavaMail</td> </tr> <tr> <td><code>MailLogger.ssl</code></td> - <td>on or true if SSL is needed<br/> - This feature requires JavaMail</td> + <td>on or true if SSL is needed<br/>This feature requires JavaMail</td> <td>No</td> </tr> <tr> @@ -258,7 +255,8 @@ control for turning off success or failure messages individually.</p> </tr> <tr> <td><code>MailLogger.starttls.enable</code></td> - <td>on or true if <code>STARTTLS</code> should be supported (requires JavaMail). <em>Since Ant 1.8.0</em></td> + <td>on or true if <code>STARTTLS</code> should be supported (requires JavaMail). <em>Since Ant + 1.8.0</em></td> <td>No; default is <q>false</q></td> </tr> <tr> @@ -272,42 +270,35 @@ control for turning off success or failure messages individually.</p> <h3 id="AnsiColorLogger">AnsiColorLogger</h3> -<p>The AnsiColorLogger adds color to the standard Ant output -by prefixing and suffixing ANSI color code escape sequences to -it. It is just an extension of <a href="#DefaultLogger">DefaultLogger</a> +<p>The AnsiColorLogger adds color to the standard Ant output by prefixing and suffixing ANSI color +code escape sequences to it. It is just an extension of <a href="#DefaultLogger">DefaultLogger</a> and hence provides all features that DefaultLogger does.</p> -<p>AnsiColorLogger differentiates the output by assigning -different colors depending upon the type of the message.</p> -<p>If used with the <code>-logfile</code> option, the output file -will contain all the necessary escape codes to -display the text in colorized mode when displayed -in the console using applications like <code>cat</code>, <code>more</code>, etc.</p> -<p>This is designed to work on terminals that support ANSI -color codes. It works on XTerm, ETerm, Win9x Console -(with ANSI.SYS loaded.), etc.</p> -<p><strong>Note</strong>: It doesn't work on WinNT and successors, -even when a <code>COMMAND.COM</code> console loaded with ANSI.SYS is used.</p> -<p>If the user wishes to override the default colors -with custom ones, a file containing zero or more of the -custom color key-value pairs must be created. The recognized keys -and their default values are shown below:</p> +<p>AnsiColorLogger differentiates the output by assigning different colors depending upon the type +of the message.</p> +<p>If used with the <code>-logfile</code> option, the output file will contain all the necessary +escape codes to display the text in colorized mode when displayed in the console using applications +like <code>cat</code>, <code>more</code>, etc.</p> +<p>This is designed to work on terminals that support ANSI color codes. It works on XTerm, ETerm, Win9x Console (with +ANSI.SYS loaded.), etc.</p> +<p><strong>Note</strong>: It doesn't work on WinNT and successors, even when +a <code>COMMAND.COM</code> console loaded with ANSI.SYS is used.</p> +<p>If the user wishes to override the default colors with custom ones, a file containing zero or +more of the custom color key-value pairs must be created. The recognized keys and their default +values are shown below:</p> <pre> AnsiColorLogger.ERROR_COLOR=2;31 AnsiColorLogger.WARNING_COLOR=2;35 AnsiColorLogger.INFO_COLOR=2;36 AnsiColorLogger.VERBOSE_COLOR=2;32 AnsiColorLogger.DEBUG_COLOR=2;34</pre> -<p>Each key takes as value a color combination defined as -<q>Attribute;Foreground;Background</q>. In the above example, background -value has not been used.</p> +<p>Each key takes as value a color combination defined as <q>Attribute;Foreground;Background</q>. +In the above example, background value has not been used.</p> <p>This file must be specified as the value of a system variable -named <code>ant.logger.defaults</code> and passed as an argument using -the <code>-D</code> option to the <code>java</code> command that -invokes the Ant application. An easy way to achieve this is to -add <code>-Dant.logger.defaults=</code><samp>/path/to/your/file</samp> -to the <code>ANT_OPTS</code> environment variable. Ant's launching -script recognizes this flag and will pass it to the <code>java</code> -command appropriately.</p> +named <code>ant.logger.defaults</code> and passed as an argument using the <code>-D</code> option to +the <code>java</code> command that invokes the Ant application. An easy way to achieve this is to +add <code>-Dant.logger.defaults=</code><samp>/path/to/your/file</samp> to the <code>ANT_OPTS</code> +environment variable. Ant's launching script recognizes this flag and will pass it to +the <code>java</code> command appropriately.</p> <p>Format:</p> <pre> AnsiColorLogger.*=Attribute;Foreground;Background @@ -344,34 +335,32 @@ Background is one of the following: <pre>ant -logger org.apache.tools.ant.listener.AnsiColorLogger</pre> <h3 id="Log4jListener">Log4jListener</h3> -<p><em><u>Deprecated</u></em>: Apache Log4j (1) is not developed any more. Last -release is 1.2.17 from 26 May 2012 and contains vulnerability issues.</p> -<p>Passes build events to Log4j, using the full classname's of the generator of -each build event as the category:</p> +<p><em><u>Deprecated</u></em>: Apache Log4j (1) is not developed any more. Last release is 1.2.17 +from 26 May 2012 and contains vulnerability issues.</p> +<p>Passes build events to Log4j, using the full classname's of the generator of each build event as +the category:</p> <ul> <li>build started / build finished—<code>org.apache.tools.ant.Project</code></li> <li>target started / target finished—<code>org.apache.tools.ant.Target</code></li> <li>task started / task finished—the fully qualified classname of the task</li> - <li>message logged—the classname of one of the above, so if a task logs a - message, its classname is the category used, and so on.</li> + <li>message logged—the classname of one of the above, so if a task logs a message, its + classname is the category used, and so on.</li> </ul> -<p>All start events are logged as INFO. Finish events are either logged as -INFO or ERROR depending on whether the build failed during that stage. Message -events are logged according to their Ant logging level, mapping directly to a -corresponding Log4j level.</p> +<p>All start events are logged as INFO. Finish events are either logged as INFO or ERROR depending +on whether the build failed during that stage. Message events are logged according to their Ant +logging level, mapping directly to a corresponding Log4j level.</p> <pre>ant -listener org.apache.tools.ant.listener.Log4jListener</pre> -<p>To use Log4j you will need the Log4j JAR file and a <samp>log4j.properties</samp> -configuration file. Both should be placed somewhere in your Ant -classpath. If the <samp>log4j.properties</samp> is in your project root folder you can -add this with <code>-lib</code> option:</p> +<p>To use Log4j you will need the Log4j JAR file and a <samp>log4j.properties</samp> configuration +file. Both should be placed somewhere in your Ant classpath. If the <samp>log4j.properties</samp> +is in your project root folder you can add this with <code>-lib</code> option:</p> <pre>ant -listener org.apache.tools.ant.listener.Log4jListener -lib .</pre> -<p>If, for example, you wanted to capture the same information output to the -console by the DefaultLogger and send it to a file named <samp>build.log</samp>, you -could use the following configuration:</p> +<p>If, for example, you wanted to capture the same information output to the console by the +DefaultLogger and send it to a file named <samp>build.log</samp>, you could use the following +configuration:</p> <pre> log4j.rootLogger=ERROR, LogFile @@ -385,22 +374,22 @@ log4j.appender.LogFile.layout=org.apache.log4j.PatternLayout log4j.appender.LogFile.layout.ConversionPattern=[%6r] %8c{1} : %m%n log4j.appender.LogFile.file=build.log</pre> -<p>For more information about configuring Log4J see <a href="https://logging.apache.org/log4j/1.2/";>its -documentation page</a>.</p> +<p>For more information about configuring Log4J see <a href="https://logging.apache.org/log4j/1.2/"; +target="_top">its documentation page</a>.</p> <h4>Using the Log4j 1.2 Bridge</h4> -You could use the <a href="https://logging.apache.org/log4j/2.x/log4j-1.2-api/index.html";>Log4j Bridge</a> -if your application is written against the Log4j (1.x) API, but you want to use the Log4j 2.x runtime. -For using the bridge with Ant you have to add +<p>You could use the <a href="https://logging.apache.org/log4j/2.x/log4j-1.2-api/index.html"; +target="_top">Log4j Bridge</a> if your application is written against the Log4j (1.x) API, but you +want to use the Log4j 2.x runtime. For using the bridge with Ant you have to add</p> <ul> <li><samp>log4j-1.2-api-${log4j.version}.jar</samp></li> <li><samp>log4j-api-${log4j.version}.jar</samp></li> <li><samp>log4j-core-${log4j.version}.jar</samp></li> <li><samp>log4j2.xml</samp></li> </ul> -to your classpath, e.g. via the <code>-lib</code> option. -(For using the bridge, Ant 1.9.10/1.10.2 or higher is required.) -Translating the 1.x properties file into the 2.x xml syntax would result in +<p>to your classpath, e.g. via the <code>-lib</code> option. (For using the bridge, Ant +1.9.10/1.10.2 or higher is required.) Translating the 1.x properties file into the 2.x XML syntax +would result in</p> <pre> <?xml version="1.0" encoding="UTF-8"?> <Configuration status="WARN"> @@ -423,40 +412,31 @@ Translating the 1.x properties file into the 2.x xml syntax would result in </Configuration></pre> <h3 id="XmlLogger">XmlLogger</h3> -<p>Writes all build information out to an XML file -named <samp>log.xml</samp>, or the value of -the <code>XmlLogger.file</code> property if present, when used as a -listener. When used as a logger, it writes all output to either the -console or to the value of <code>-logfile</code>. Whether used as a -listener or logger, the output is not generated until the build is -complete, as it buffers the information in order to provide timing -information for task, targets, and the project.</p> -<p>By default the XML file creates a reference to an XSLT -file <samp>log.xsl</samp> in the current directory; look -in <samp>ANT_HOME/etc</samp> for one of these. You can set the -property <code>ant.XmlLogger.stylesheet.uri</code> to provide a URI -to a style sheet. This can be a relative or absolute file path, or -an HTTP URL. If you set the property to the empty string, <q></q>, -no XSLT transform is declared at all.</p> +<p>Writes all build information out to an XML file named <samp>log.xml</samp>, or the value of +the <code>XmlLogger.file</code> property if present, when used as a listener. When used as a logger, +it writes all output to either the console or to the value of <code>-logfile</code>. Whether used as +a listener or logger, the output is not generated until the build is complete, as it buffers the +information in order to provide timing information for task, targets, and the project.</p> +<p>By default the XML file creates a reference to an XSLT file <samp>log.xsl</samp> in the current +directory; look in <samp>ANT_HOME/etc</samp> for one of these. You can set the +property <code>ant.XmlLogger.stylesheet.uri</code> to provide a URI to a style sheet. This can be a +relative or absolute file path, or an HTTP URL. If you set the property to the empty +string, <q></q>, no XSLT transform is declared at all.</p> <pre>ant -listener org.apache.tools.ant.XmlLogger ant -logger org.apache.tools.ant.XmlLogger -verbose -logfile build_log.xml</pre> <h3 id="TimestampedLogger">TimestampedLogger</h3> -<p> -Acts like the default logger, except that the final success/failure message also includes -the time that the build completed. For example: -</p> +<p>Acts like the default logger, except that the final success/failure message also includes the +time that the build completed. For example:</p> <pre>BUILD SUCCESSFUL - at 16/08/05 16:24</pre> <p>To use this listener, use the command:</p> <pre>ant -logger org.apache.tools.ant.listener.TimestampedLogger</pre> <h3 id="BigProjectLogger">BigProjectLogger</h3> -<p> -This logger is designed to make examining the logs of a big build easier, -especially those run under continuous integration tools. It -</p> +<p>This logger is designed to make examining the logs of a big build easier, especially those run +under continuous integration tools. It</p> <ol> <li>When entering a child project, prints its name and directory</li> <li>When exiting a child project, prints its name</li> @@ -464,12 +444,9 @@ especially those run under continuous integration tools. It <li>Omits logging the names of all targets that have no direct task output</li> <li>Includes the build finished timestamp of the TimeStamp logger</li> </ol> -<p> -This is useful when using <code><subant></code> to build a large project -from many smaller projects—the output shows which particular -project is building. Here is an example in which "clean" is being called -on all a number of child projects, only some of which perform work: -</p> +<p>This is useful when using <code><subant></code> to build a large project from many smaller +projects—the output shows which particular project is building. Here is an example in which +"clean" is being called on all a number of child projects, only some of which perform work:</p> <pre> ====================================================================== Entering project "xunit" @@ -493,20 +470,16 @@ In /home/ant/components/junit Exiting project "junit" ======================================================================</pre> -<p> -The entry and exit messages are very verbose in this example, but in -a big project compiling or testing many child components, the messages -are reduced to becoming clear delimiters of where different projects -are in charge—or, more importantly, which project is failing. -</p> +<p>The entry and exit messages are very verbose in this example, but in a big project compiling or +testing many child components, the messages are reduced to becoming clear delimiters of where +different projects are in charge—or, more importantly, which project is failing.</p> <p>To use this listener, use the command:</p> <pre>ant -logger org.apache.tools.ant.listener.BigProjectLogger</pre> <h3 id="SimpleBigProjectLogger">SimpleBigProjectLogger</h3> <p><em>Since Ant 1.8.1</em></p> -<p>Like <code>BigProjectLogger</code>, project-qualified target names -are printed, useful for big builds with subprojects. Otherwise it is -as quiet as <code>NoBannerLogger</code>:</p> +<p>Like <code>BigProjectLogger</code>, project-qualified target names are printed, useful for big +builds with subprojects. Otherwise it is as quiet as <code>NoBannerLogger</code>:</p> <pre> Buildfile: /sources/myapp/build.xml @@ -532,10 +505,9 @@ Total time: 1 second</pre> <h3 id="ProfileLogger">ProfileLogger</h3> <!-- This is the 'since' as described in the Loggers JavaDoc --> <p><em>Since Ant 1.8.0</em></p> -<p>This logger stores the time needed for executing a task, target and -the whole build and prints these information. The output contains a -timestamp when entering the build, target or task and a timestamp -and the needed time when exiting.</p> +<p>This logger stores the time needed for executing a task, target and the whole build and prints +these information. The output contains a timestamp when entering the build, target or task and a +timestamp and the needed time when exiting.</p> <h4>Example</h4> Having that buildfile <pre> @@ -550,7 +522,8 @@ Having that buildfile <echo>another-echo-task</echo> </target> </project></pre> -and executing with <code>ant -logger org.apache.tools.ant.listener.ProfileLogger anotherTarget</code> gives that output (with other timestamps and duration of course ;-): +<p>and executing with <code>ant -logger org.apache.tools.ant.listener.ProfileLogger +anotherTarget</code> gives that output (with other timestamps and duration of course ;-):</p> <pre> Buildfile: ...\build.xml @@ -588,22 +561,24 @@ Total time: 2 seconds</pre> <ul> <li> - A listener or logger should not write to standard output or error in the <code>messageLogged()</code> method; - Ant captures these internally and it will trigger an infinite loop. + A listener or logger should not write to standard output or error in + the <code>messageLogged()</code> method; Ant captures these internally and it will trigger an + infinite loop. </li> <li> - Logging is synchronous; all listeners and loggers are called one after the other, with the build blocking until - the output is processed. Slow logging means a slow build. + Logging is synchronous; all listeners and loggers are called one after the other, with the build + blocking until the output is processed. Slow logging means a slow build. </li> - <li>When a build is started, and <code>BuildListener.buildStarted(BuildEvent event)</code> is called, - the project is not fully functional. The build has started, yes, and the <code>event.getProject()</code> method call - returns the Project instance, but that project is initialized with JVM and Ant properties, nor has it - parsed the build file yet. You cannot call <code>Project.getProperty()</code> for property lookup, or + <li>When a build is started, and <code>BuildListener.buildStarted(BuildEvent event)</code> is + called, the project is not fully functional. The build has started, yes, and + the <code>event.getProject()</code> method call returns the Project instance, but that project + is initialized with JVM and Ant properties, nor has it parsed the build file yet. You cannot + call <code>Project.getProperty()</code> for property lookup, or <code>Project.getName()</code> to get the project name (it will return null). </li> <li> - Classes that implement <code>org.apache.tools.ant.SubBuildListener</code> receive notifications when child projects - start and stop. + Classes that implement <code>org.apache.tools.ant.SubBuildListener</code> receive notifications + when child projects start and stop. </li> </ul> http://git-wip-us.apache.org/repos/asf/ant/blob/97d81a72/manual/platform.html ---------------------------------------------------------------------- diff --git a/manual/platform.html b/manual/platform.html index 29158f1..f1ee98f 100644 --- a/manual/platform.html +++ b/manual/platform.html @@ -27,100 +27,83 @@ <h2>Java versions</h2> <h3>Java 5</h3> <p> -You may need a bigger stack than default, especially if you are using -the built in XSLT engine. We recommend you use Apache Xalan; indeed, -some tasks (JUnit report in XML, for example) may not work against the -shipping XSL engine. +You may need a bigger stack than default, especially if you are using the built in XSLT engine. We +recommend you use Apache Xalan; indeed, some tasks (JUnit report in XML, for example) may not work +against the shipping XSL engine. </p> <h2>Unix and Linux</h2> <ul> -<li>You should use a GNU version of <code>tar</code> to untar the Apache -Ant source tree, if you have downloaded this as a tar file. If you get -weird errors about missing files, this is the problem.</li> -<li>Ant does not preserve file permissions when a file is copied, -moved or archived, because Java does not let it read or write the -permissions. Use <code><chmod></code> to set permissions, and -when creating a tar archive, use the <var>mode</var> attribute -of <code><tarfileset></code> to set the permissions in the tar -file, or <code><apply></code> the real tar program.</li> -<li>Ant is not symbolic link aware in moves, deletes and when -recursing down a tree of directories to build up a list of -files. Unexpected things can happen.</li> -<li>Linux on IA-64: apparently you need a larger heap than the default -one (64M) to compile big projects. If you get out of heap errors, -either increase the heap or use a forking javac. Better yet, use jikes -for extra compilation speed.</li> +<li>You should use a GNU version of <code>tar</code> to untar the Apache Ant source tree, if you +have downloaded this as a tar file. If you get weird errors about missing files, this is the +problem.</li> +<li>Ant does not preserve file permissions when a file is copied, moved or archived, because Java +does not let it read or write the permissions. Use <code><chmod></code> to set permissions, +and when creating a tar archive, use the <var>mode</var> attribute +of <code><tarfileset></code> to set the permissions in the tar file, +or <code><apply></code> the real tar program.</li> +<li>Ant is not symbolic link aware in moves, deletes and when recursing down a tree of directories +to build up a list of files. Unexpected things can happen.</li> +<li>Linux on IA-64: apparently you need a larger heap than the default one (64M) to compile big +projects. If you get out of heap errors, either increase the heap or use a +forking <code>javac</code>. Better yet, use jikes for extra compilation speed.</li> </ul> <h2>Microsoft Windows</h2> <p> -Windows 9x (win95, win98, win98SE and winME) are not supported in Ant1.7, +Windows 9x (win95, win98, win98SE and winME) are not supported <em>since Ant 1.7</em>. </p> <p> -The Ant team has retired support for these products because they are -outdated and can expose customers to security risks. We recommend that -customers who are still running Windows 98 or Windows Me upgrade to a -newer, more secure operating system, as soon as possible. +The Ant team has retired support for these products because they are outdated and can expose +customers to security risks. We recommend that customers who are still running Windows 98 or Windows +ME upgrade to a newer, more secure operating system, as soon as possible. </p> <p> -Customers who upgrade to Linux report improved security, richer -functionality, and increased productivity. +Customers who upgrade to Linux report improved security, richer functionality, and increased +productivity. </p> <h2>Microsoft Windows 2K, XP and Server 2K03</h2> <p> -Windows 9x (win95, win98, win98SE and winME) has a batch file system -which does not work fully with long file names, so we recommend that -ant and the JDK are installed into directories without spaces, and -with 8.3 filenames. The Perl and Python launcher scripts do not -suffer from this limitation. +Windows 9x (win95, win98, win98SE and winME) has a batch file system which does not work fully with +long file names, so we recommend that Ant and JDK are installed into directories without spaces, and +with 8.3 filenames. The Perl and Python launcher scripts do not suffer from this limitation. </p> <p> -All versions of Windows are usually case insensitive, although mounted -file systems (Unix drives, ClearCase views) can be case sensitive -underneath, confusing patternsets. +All versions of Windows are usually case insensitive, although mounted file systems (Unix drives, +ClearCase views) can be case sensitive underneath, confusing patternsets. </p> <p> -Ant can often not delete a directory which is open in an Explorer -window. There is nothing we can do about this short of spawning a -program to kill the shell before deleting directories. Nor can files -that are in use be overwritten. +Ant can often not delete a directory which is open in an Explorer window. There is nothing we can +do about this short of spawning a program to kill the shell before deleting directories. Nor can +files that are in use be overwritten. </p> <p> -Finally, if any Ant task fails with an <code>error=2</code>, it -means that whatever native program Ant is trying to run, it is not -on the path. +Finally, if any Ant task fails with an <code>error=2</code>, it means that whatever native program +Ant is trying to run, it is not on the path. </p> <h2>Microsoft Windows Vista</h2> <p> -There are reports of problems with Windows Vista security bringing -up dialog boxes asking if the user wants to run an untrusted -executable during an Ant run, such as when the <signjar> task -runs the <code>jarsigner.exe</code> program. This is beyond Ant's -control, and stems from the OS trying to provide some illusion of -security by being reluctant to run unsigned native executables. The -latest Java versions appear to resolve this problem by having signed -binaries. +There are reports of problems with Windows Vista security bringing up dialog boxes asking if the +user wants to run an untrusted executable during an Ant run, such as when the <signjar> task +runs the <code>jarsigner.exe</code> program. This is beyond Ant's control, and stems from the OS +trying to provide some illusion of security by being reluctant to run unsigned native executables. +The latest Java versions appear to resolve this problem by having signed binaries. </p> <h2>Cygwin</h2> <p> -Cygwin is not an operating system; rather it is an application suite -running under Windows and providing some UNIX like functionality. Sun -has not created any specific Java Development Kit or Java Runtime -Environment for cygwin. See this -link: <a href="http://www.inonit.com/cygwin/faq/";>http://www.inonit.com/cygwin/faq/</a>. -Only Windows path names are supported by JDK and JRE tools under -Windows or cygwin. Relative path names such as "src/org/apache/tools" -are supported, but Java tools do not -understand <samp>/cygdrive/c</samp> to mean <samp>c:\</samp>. +Cygwin is not an operating system; rather it is an application suite running under Windows and +providing some UNIX like functionality. Sun has not created any specific Java Development Kit or +Java Runtime Environment for cygwin. See this link: <a href="http://www.inonit.com/cygwin/faq/"; +target="_top">http://www.inonit.com/cygwin/faq/</a>. Only Windows path names are supported by JDK +and JRE tools under Windows or cygwin. Relative path names such as <samp>src/org/apache/tools</samp> +are supported, but Java tools do not understand <samp>/cygdrive/c</samp> to mean <samp>c:\</samp>. </p> <p> -The utility <code>cygpath</code> (used industrially in -the <code>ant</code> script to support cygwin) can convert cygwin path -names to Windows. You can use the <code><exec></code> task in +The utility <code>cygpath</code> (used industrially in the <code>ant</code> script to support +cygwin) can convert cygwin path names to Windows. You can use the <code><exec></code> task in Ant to convert cygwin paths to Windows path, for instance like that: </p> <pre> @@ -132,42 +115,38 @@ Ant to convert cygwin paths to Windows path, for instance like that: <echo message="${windows.pathname}"/> </pre> <p> -We get lots of support calls from Cygwin users. Either it is -incredibly popular, or it is trouble. If you do use it, remember that -Java is a Windows application, so Ant is running in a Windows process, -not a Cygwin one. This will save us having to mark your bug reports as -invalid. +We get lots of support calls from Cygwin users. Either it is incredibly popular, or it is +trouble. If you do use it, remember that Java is a Windows application, so Ant is running in a +Windows process, not a Cygwin one. This will save us having to mark your bug reports as invalid. </p> <h2>Apple MacOS X/macOS</h2> <p> -MacOS X a.k.a. macOS is the first of the Apple platforms that Ant -supports completely; it is treated like any other Unix. +MacOS X a.k.a. macOS is the first of the Apple platforms that Ant supports completely; it is treated +like any other Unix. </p> <h2>Novell Netware</h2> <p> -To give the same level of sophisticated control as Ant's startup -scripts on other platforms, it was decided to make the main ant -startup on NetWare be via a Perl Script, <code>runant.pl</code>. This -is found in the <samp>bin</samp> directory (for -instance—<samp>bootstrap\bin</samp> +To give the same level of sophisticated control as Ant's startup scripts on other platforms, it was +decided to make the main ant startup on NetWare be via a Perl Script, <code>runant.pl</code>. This +is found in the <samp>bin</samp> directory (for instance—<samp>bootstrap\bin</samp> or <samp>dist\bin</samp>). </p> <p>One important item of note is that you need to set up the following to run Ant:</p> <ul> - <li><code>CLASSPATH</code>—put <samp>ant.jar</samp> and any other needed jars on the system classpath.</li> - <li><code>ANT_OPTS</code>—On NetWare, <code>ANT_OPTS</code> - needs to include a parameter of the - form, <code>-envCWD=<i>ANT_HOME</i></code>, - with <code><i>ANT_HOME</i></code> being the fully expanded location - of Ant, <strong>not</strong> an environment variable. This is due - to the fact that the NetWare System Console has no notion of a - current working directory.</li> + <li><code>CLASSPATH</code>—put <samp>ant.jar</samp> and any other needed jars on the system + classpath.</li> + <li><code>ANT_OPTS</code>—On NetWare, <code>ANT_OPTS</code> needs to include a parameter of + the form, <code>-envCWD=<i>ANT_HOME</i></code>, with <code><i>ANT_HOME</i></code> being the + fully expanded location of Ant, <strong>not</strong> an environment variable. This is due to + the fact that the NetWare System Console has no notion of a current working directory.</li> </ul> -<p>It is suggested that you create up an ant.ncf that sets up these parameters, and calls <samp>perl ANT_HOME/dist/bin/runant.pl</samp></p> -<p>The following is an example of such an NCF file (assuming Ant is installed in <samp>sys:/apache-ant/</samp>):</p> +<p>It is suggested that you create up an <samp>ant.ncf</samp> that sets up these parameters, and +calls <samp>perl ANT_HOME/dist/bin/runant.pl</samp></p> +<p>The following is an example of such an NCF file (assuming Ant is installed +in <samp>sys:/apache-ant/</samp>):</p> <pre> envset CLASSPATH=sys:/apache-ant/bootstrap/lib/ant.jar envset CLASSPATH=$CLASSPATH;sys:/apache-ant/lib/optional/junit.jar @@ -180,18 +159,16 @@ envset ANT_HOME=sys:/apache-ant/dist/lib perl sys:/apache-ant/dist/bin/runant.pl</pre> -<p>Ant works on JVM version 1.3 or higher. You may have some luck -running it on JVM 1.2, but serious problems have been found running -Ant on JVM 1.1.7B. These problems are caused by JVM bugs that will -not be fixed.</p> +<p>Ant works on JVM version 1.3 or higher. You may have some luck running it on JVM 1.2, but +serious problems have been found running Ant on JVM 1.1.7B. These problems are caused by JVM bugs +that will not be fixed.</p> <p>JVM 1.3 is supported on Novell NetWare versions 5.1 and higher.</p> <h2>Other platforms</h2> <p> -Support for other platforms is not guaranteed to be complete, as -certain techniques to hide platform details from build files need to -be written and tested on every particular platform. Contributions in -this area are welcome. +Support for other platforms is not guaranteed to be complete, as certain techniques to hide platform +details from build files need to be written and tested on every particular platform. Contributions +in this area are welcome. </p> </body> http://git-wip-us.apache.org/repos/asf/ant/blob/97d81a72/manual/properties.html ---------------------------------------------------------------------- diff --git a/manual/properties.html b/manual/properties.html index a8439a8..224d9a3 100644 --- a/manual/properties.html +++ b/manual/properties.html @@ -25,67 +25,61 @@ <body> <h1>Properties</h1> - <p>Properties are key-value pairs where Apache Ant tries to - expand <code>${key}</code> to <code>value</code> at runtime.</p> - - <p>There are many tasks that can set properties, the most common one - is the <a href="Tasks/property.html">property</a> task. In - addition properties can be defined - via <a href="running.html">command line arguments</a> or similar - mechanisms from outside of Ant.</p> - - <p>Normally property values can not be changed, once a property is - set, most tasks will not allow its value to be modified. In - general properties are of global scope, i.e. once they have been - defined they are available for any task or target invoked - subsequently—it is not possible to set a property in a child - build process created via + <p>Properties are key-value pairs where Apache Ant tries to expand <code>${key}</code> + to <code>value</code> at runtime.</p> + + <p>There are many tasks that can set properties, the most common one is + the <a href="Tasks/property.html">property</a> task. In addition properties can be defined + via <a href="running.html">command line arguments</a> or similar mechanisms from outside of + Ant.</p> + + <p>Normally property values can not be changed, once a property is set, most tasks will not allow + its value to be modified. In general properties are of global scope, i.e. once they have been + defined they are available for any task or target invoked subsequently—it is not possible + to set a property in a child build process created via the <a href="Tasks/ant.html">ant</a>, <a href="Tasks/antcall.html">antcall</a> - or <a href="Tasks/subant.html">subant</a> tasks and make it - available to the calling build process, though.</p> + or <a href="Tasks/subant.html">subant</a> tasks and make it available to the calling build + process, though.</p> - <p><em>Since Ant 1.8.0</em> the <a href="Tasks/local.html">local</a> - task can be used to create properties that are locally scoped to a - target or a <a href="Tasks/sequential.html">sequential</a> element - like the one of the <a href="Tasks/macrodef.html">macrodef</a> - task.</p> + <p><em>Since Ant 1.8.0</em> the <a href="Tasks/local.html">local</a> task can be used to create + properties that are locally scoped to a target or + a <a href="Tasks/sequential.html">sequential</a> element like the one of + the <a href="Tasks/macrodef.html">macrodef</a> task.</p> <h2 id="built-in-props">Built-in Properties</h2> - <p>Ant provides access to all system properties as if they had been - defined using a <code><property></code> task. For - example, <samp>${os.name}</samp> expands to the name of the - operating system.</p> + <p>Ant provides access to all system properties as if they had been defined using + a <code><property></code> task. For example, <samp>${os.name}</samp> expands to the name + of the operating system.</p> <p>For a list of system properties, - see <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#getProperties--";>the javadoc of System.getProperties</a>. + see <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#getProperties--"; + target="_top">the javadoc of System.getProperties</a>. </p> <p>In addition, Ant has some built-in properties:</p> <dl> <dt><code>basedir</code></dt> - <dd>the absolute path of the project's basedir (as set - with the <var>basedir</var> attribute of <a href="using.html#projects"><project></a>).</dd> + <dd>the absolute path of the project's basedir (as set with + the <var>basedir</var> attribute + of <a href="using.html#projects"><project></a>).</dd> <dt><code>ant.file</code></dt> <dd>the absolute path of the buildfile.</dd> <dt><code>ant.version</code></dt> <dd>the version of Ant</dd> <dt><code>ant.project.name</code></dt> - <dd>the name of the project that is currently executing; it is set - in the <var>name</var> attribute of <project>.</dd> + <dd>the name of the project that is currently executing; it is set in the <var>name</var> + attribute of <project>.</dd> <dt><code>ant.project.default-target</code></dt> - <dd>the name of the currently executing project's default target; - it is set via the <var>default</var> attribute - of <code><project></code>.</dd> + <dd>the name of the currently executing project's default target; it is set via + the <var>default</var> attribute of <code><project></code>.</dd> <dt><code>ant.project.invoked-targets</code></dt> - <dd>a comma separated list of the targets that have been specified - on the command line (the IDE, an <code><ant></code> task - ...) when invoking the current project.<br/> - This property is set properly when the first target is executed. - If you use it in the implicit target (directly under - the <code><project></code> tag) the list will be empty if - no target has been specified while it will contain the project's - default target in this case for tasks nested into targets.</dd> + <dd>a comma separated list of the targets that have been specified on the command line (the IDE, + an <code><ant></code> task ...) when invoking the current project.<br/> This property + is set properly when the first target is executed. If you use it in the implicit target + (directly under the <code><project></code> tag) the list will be empty if no target has + been specified while it will contain the project's default target in this case for tasks + nested into targets.</dd> <dt><code>ant.java.version</code></dt> <dd>the JVM version Ant detected; currently it can hold the values <q>9</q>, <q>1.8</q>, <q>1.7</q>, <q>1.6</q>, <q>1.5</q>, <q>1.4</q>, <q>1.3</q> @@ -94,83 +88,69 @@ <dd>the absolute path of the <samp>ant.jar</samp> file.</dd> </dl> - <p>There is also another property, but this is set by the launcher - script and therefore maybe not set inside IDEs:</p> + <p>There is also another property, but this is set by the launcher script and therefore maybe not + set inside IDEs:</p> <dl> <dt><code>ant.home</code></dt> <dd>home directory of Ant</dd> </dl> - <p>The following property is only set if Ant is started via the - Launcher class (which means it may not be set inside IDEs - either):</p> + <p>The following property is only set if Ant is started via the Launcher class (which means it may + not be set inside IDEs either):</p> <dl> <dt><code>ant.library.dir</code></dt> - <dd>the directory that has been used to load Ant's - jars from. In most cases this is <samp>ANT_HOME/lib</samp>.</dd> + <dd>the directory that has been used to load Ant's jars from. In most cases this + is <samp>ANT_HOME/lib</samp>.</dd> </dl> <h1 id="propertyHelper">PropertyHelpers</h1> <p>Ant's property handling is accomplished by an instance - of <code>org.apache.tools.ant.PropertyHelper</code> associated - with the current Project. You can learn more about this class by - examining Ant's Java API. In Ant 1.8 the PropertyHelper class was - much reworked and now itself employs a number of helper classes - (actually instances of - the <code>org.apache.tools.ant.PropertyHelper$Delegate</code> - marker interface) to take care of discrete tasks such as property - setting, retrieval, parsing, etc. This makes Ant's property + of <code>org.apache.tools.ant.PropertyHelper</code> associated with the current Project. You + can learn more about this class by examining Ant's Java API. In Ant 1.8 the PropertyHelper class + was much reworked and now itself employs a number of helper classes (actually instances of + the <code>org.apache.tools.ant.PropertyHelper$Delegate</code> marker interface) to take care of + discrete tasks such as property setting, retrieval, parsing, etc. This makes Ant's property handling highly extensible; also of interest is the - new <a href="Tasks/propertyhelper.html">propertyhelper</a> task - used to manipulate the PropertyHelper and its delegates from the - context of the Ant buildfile.</p> + new <a href="Tasks/propertyhelper.html">propertyhelper</a> task used to manipulate the + PropertyHelper and its delegates from the context of the Ant buildfile.</p> - <p>There are three sub-interfaces of <code>Delegate</code> that may be - useful to implement.</p> + <p>There are three sub-interfaces of <code>Delegate</code> that may be useful to implement.</p> <ul> - <li><code>org.apache.tools.ant.property.PropertyExpander</code> is - responsible for finding the property name inside a string in the - first place (the default extracts <samp>foo</samp> + <li><code>org.apache.tools.ant.property.PropertyExpander</code> is responsible for finding the + property name inside a string in the first place (the default extracts <samp>foo</samp> from <samp>${foo}</samp>). - <p>This is the interface you'd implement if you wanted to invent - your own property syntax—or allow nested property expansions - since the default implementation doesn't balance braces - (see <a href="https://git-wip-us.apache.org/repos/asf?p=ant-antlibs-props.git;a=blob;f=src/main/org/apache/ant/props/NestedPropertyExpander.java;hb=HEAD";><code>NestedPropertyExpander</code> - in the <samp>props</samp> Antlib</a> for an example).</p> + <p>This is the interface you'd implement if you wanted to invent your own property + syntax—or allow nested property expansions since the default implementation doesn't + balance braces + (see <a href="https://git-wip-us.apache.org/repos/asf?p=ant-antlibs-props.git;a=blob;f=src/main/org/apache/ant/props/NestedPropertyExpander.java;hb=HEAD"; + target="_top"><code>NestedPropertyExpander</code> in the <samp>props</samp> Antlib</a> for + an example).</p> </li> - <li><code>org.apache.tools.ant.PropertyHelper$PropertyEvaluator</code> - is used to expand <samp>${some-string}</samp> into - an <code>Object</code>. - - <p>This is the interface you'd implement if you want to provide - your own storage independent of Ant's project instance—the - interface represents the reading end. An example for this - would - be <code>org.apache.tools.ant.property.LocalProperties</code> - which implements storage - for <a href="Tasks/local.html">local properties</a>.</p> - - <p>Another reason to implement this interface is if you wanted - to provide your own "property protocol" like - expanding <code>toString:foo</code> by looking up the project - reference <samp>foo</samp> and invoking <code>toString()</code> on it - (which is already implemented in Ant, see below).</p> + <li><code>org.apache.tools.ant.PropertyHelper$PropertyEvaluator</code> is used to + expand <samp>${some-string}</samp> into an <code>Object</code>. + + <p>This is the interface you'd implement if you want to provide your own storage independent + of Ant's project instance—the interface represents the reading end. An example for + this would be <code>org.apache.tools.ant.property.LocalProperties</code> which implements + storage for <a href="Tasks/local.html">local properties</a>.</p> + + <p>Another reason to implement this interface is if you wanted to provide your own "property + protocol" like expanding <code>toString:foo</code> by looking up the project + reference <samp>foo</samp> and invoking <code>toString()</code> on it (which is already + implemented in Ant, see below).</p> </li> - <li><code>org.apache.tools.ant.PropertyHelper$PropertySetter</code> - is responsible for setting properties. + <li><code>org.apache.tools.ant.PropertyHelper$PropertySetter</code> is responsible for setting + properties. - <p>This is the interface you'd implement if you want to provide - your own storage independent of Ant's project instance—the - interface represents the reading end. An example for this - would - be <code>org.apache.tools.ant.property.LocalProperties</code> - which implements storage - for <a href="Tasks/local.html">local properties</a>.</p> + <p>This is the interface you'd implement if you want to provide your own storage independent + of Ant's project instance—the interface represents the reading end. An example for + this would be <code>org.apache.tools.ant.property.LocalProperties</code> which implements + storage for <a href="Tasks/local.html">local properties</a>.</p> </li> </ul> @@ -195,10 +175,9 @@ public class DefaultExpander implements PropertyExpander { } }</pre> - <p>The logic that replaces <samp>${toString:<i>some-id</i>}</samp> with the - stringified representation of the object with - <var>id</var> <samp>some-id</samp> inside the current build is contained in a - PropertyEvaluator similar to the following code:</p> + <p>The logic that replaces <samp>${toString:<i>some-id</i>}</samp> with the stringified + representation of the object with <var>id</var> <samp>some-id</samp> inside the current build is + contained in a PropertyEvaluator similar to the following code:</p> <pre> public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { @@ -215,22 +194,17 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { <h1>Property Expansion</h1> - <p>When Ant encounters a construct <samp>${some-text}</samp> the - exact parsing semantics are subject to the configured property - helper delegates.</p> + <p>When Ant encounters a construct <samp>${some-text}</samp> the exact parsing semantics are + subject to the configured property helper delegates.</p> <h2><code>$$</code> Expansion</h2> - <p>In its default configuration Ant will expand the text <q>$$</q> - to a single <q>$</q> and suppress the normal property expansion - mechanism for the text immediately following it, - i.e. <samp>$${key}</samp> expands to <samp>${key}</samp> and - not <code>value</code> even though a property - named <code>key</code> was defined and had the - value <samp>value</samp>. This can be used to escape - literal <q>$</q> characters and is useful in constructs that only - look like property expansions or when you want to provide - diagnostic output like in</p> + <p>In its default configuration Ant will expand the text <q>$$</q> to a single <q>$</q> and + suppress the normal property expansion mechanism for the text immediately following it, + i.e. <samp>$${key}</samp> expands to <samp>${key}</samp> and not <code>value</code> even though + a property named <code>key</code> was defined and had the value <samp>value</samp>. This can be + used to escape literal <q>$</q> characters and is useful in constructs that only look like + property expansions or when you want to provide diagnostic output like in</p> <pre><echo>$${builddir}=${builddir}</echo></pre> @@ -238,65 +212,50 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { <pre>${builddir}=build/classes</pre> - <p>if the property <code>builddir</code> has the - value <samp>build/classes</samp>.</p> + <p>if the property <code>builddir</code> has the value <samp>build/classes</samp>.</p> - <p>In order to maintain backward compatibility with older Ant - releases, a single <q>$</q> character encountered apart from a - property-like construct (including a matched pair of french - braces) will be interpreted literally; that is, as <q>$</q>. The - "correct" way to specify this literal character, however, is by - using the escaping mechanism unconditionally, so that <q>$$</q> is - obtained by specifying <q>$$$$</q>. Mixing the two approaches - yields unpredictable results, as <q>$$$</q> results - in <q>$$</q>.</p> + <p>In order to maintain backward compatibility with older Ant releases, a single <q>$</q> + character encountered apart from a property-like construct (including a matched pair of french + braces) will be interpreted literally; that is, as <q>$</q>. The "correct" way to specify this + literal character, however, is by using the escaping mechanism unconditionally, so + that <q>$$</q> is obtained by specifying <q>$$$$</q>. Mixing the two approaches yields + unpredictable results, as <q>$$$</q> results in <q>$$</q>.</p> <h2>Nesting of Braces</h2> - <p>In its default configuration Ant will not try to balance braces - in property expansions, it will only consume the text up to the - first closing brace when creating a property name. I.e. when - expanding something like <samp>${a${b}}</samp> it will be - translated into two parts:</p> + <p>In its default configuration Ant will not try to balance braces in property expansions, it will + only consume the text up to the first closing brace when creating a property name. I.e. when + expanding something like <samp>${a${b}}</samp> it will be translated into two parts:</p> <ol> - <li>the expansion of property <samp>a${b</samp>—likely nothing - useful.</li> - <li>the literal text <samp>}</samp> resulting from the second - closing brace</li> + <li>the expansion of property <samp>a${b</samp>—likely nothing useful.</li> + <li>the literal text <samp>}</samp> resulting from the second closing brace</li> </ol> - <p>This means you can't use easily expand properties whose names are - given by properties, but there - are <a href="https://ant.apache.org/faq.html#propertyvalue-as-name-for-property";>some - workarounds</a> for older versions of Ant. With Ant 1.8.0 and the - <a href="https://ant.apache.org/antlib/props/";>the props Antlib</a> - you can configure Ant to use - the <code>NestedPropertyExpander</code> defined there if you need - such a feature.</p> + <p>This means you can't use easily expand properties whose names are given by properties, but + there are <a href="https://ant.apache.org/faq.html#propertyvalue-as-name-for-property"; + target="_top">some workarounds</a> for older versions of Ant. With Ant 1.8.0 and + the <a href="https://ant.apache.org/antlib/props/"; target="_top">the props Antlib</a> you can + configure Ant to use the <code>NestedPropertyExpander</code> defined there if you need such a + feature.</p> <h2>Expanding a "Property Name"</h2> - <p>In its most simple form <samp>${key}</samp> is supposed to look - up a property named <code>key</code> and expand to the value of - the property. Additional <code>PropertyEvaluator</code>s may - result in a different interpretation of <code>key</code>, - though.</p> + <p>In its most simple form <samp>${key}</samp> is supposed to look up a property + named <code>key</code> and expand to the value of the property. + Additional <code>PropertyEvaluator</code>s may result in a different interpretation + of <code>key</code>, though.</p> - <p>The <a href="https://ant.apache.org/antlibs/props/";>props Antlib</a> - provides a few interesting evaluators but there are - also a few built-in ones.</p> + <p>The <a href="https://ant.apache.org/antlibs/props/"; target="_top">props Antlib</a> provides a + few interesting evaluators but there are also a few built-in ones.</p> - <h3 id="toString">Getting the value of a Reference with - <samp>${toString:}</samp></h3> + <h3 id="toString">Getting the value of a Reference with <samp>${toString:}</samp></h3> - <p>Any Ant type which has been declared with a reference can also - its string value extracted by using the <samp>${toString:}</samp> - operation, with the name of the reference listed after - the <code>toString:</code> text. The <code>toString()</code> - method of the Java class instance that is referenced is - invoked—all built in types strive to produce useful and - relevant output in such an instance.</p> + <p>Any Ant type which has been declared with a reference can also its string value extracted by + using the <samp>${toString:}</samp> operation, with the name of the reference listed after + the <code>toString:</code> text. The <code>toString()</code> method of the Java class instance + that is referenced is invoked—all built in types strive to produce useful and relevant + output in such an instance.</p> <p>For example, here is how to get a listing of the files in a fileset,<p> @@ -304,49 +263,42 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { <fileset id="sourcefiles" dir="src" includes="**/*.java"/> <echo> sourcefiles = ${toString:sourcefiles} </echo></pre> - <p>There is no guarantee that external types provide meaningful - information in such a situation</p> + <p>There is no guarantee that external types provide meaningful information in such a + situation</p> <h3 id="ant.refid">Getting the value of a Reference with <samp>${ant.refid:}</samp></h3> - <p>Any Ant type which has been declared with a reference can also be - used as a property by using the <samp>${ant.refid:}</samp> - operation, with the name of the reference listed after - the <code>ant.refid:</code> text. The difference between this - operation and <a href="#toString"><samp>${toString:}</samp></a> is - that <samp>${ant.refid:}</samp> will expand to the referenced - object itself. In most circumstances the <code>toString</code> - method will be invoked anyway, for example if - the <samp>${ant.refid:}</samp> is surrounded by other text.</p> + <p>Any Ant type which has been declared with a reference can also be used as a property by using + the <samp>${ant.refid:}</samp> operation, with the name of the reference listed after + the <code>ant.refid:</code> text. The difference between this operation + and <a href="#toString"><samp>${toString:}</samp></a> is that <samp>${ant.refid:}</samp> will + expand to the referenced object itself. In most circumstances the <code>toString</code> method + will be invoked anyway, for example if the <samp>${ant.refid:}</samp> is surrounded by other + text.</p> - <p>This syntax is most useful when using a task with attribute - setters that accept objects other than String. For example, if - the setter accepts a Resource object as in</p> + <p>This syntax is most useful when using a task with attribute setters that accept objects other + than String. For example, if the setter accepts a Resource object as in</p> <pre>public void setAttr(Resource r) { ... }</pre> - <p>then the syntax can be used to pass in resource subclasses - previously defined as references like</p> + <p>then the syntax can be used to pass in resource subclasses previously defined as references + like</p> <pre> <url url="http://ant.apache.org/"; id="anturl"/> <my:task attr="${ant.refid:anturl}"/></pre> <h2 id="if+unless">If/Unless Attributes</h2> <p> - The <code><target></code> element and various tasks (such - as <code><fail></code>) and task elements (such - as <code><test></code> in <code><junit></code>) - support <var>if</var> and <var>unless</var> attributes which can - be used to control whether the item is run or otherwise takes - effect. + The <code><target></code> element and various tasks (such as <code><fail></code>) + and task elements (such as <code><test></code> in <code><junit></code>) + support <var>if</var> and <var>unless</var> attributes which can be used to control whether the + item is run or otherwise takes effect. </p> <p> - In Ant 1.7.1 and earlier, these attributes could only be property - names. The item was enabled if a property with that name was - defined—even to be the empty string - or <q>false</q>—and disabled if the property was not - defined. For example, the following works but there is no way to - override the file existence check negatively (only positively): + In Ant 1.7.1 and earlier, these attributes could only be property names. The item was enabled + if a property with that name was defined—even to be the empty string + or <q>false</q>—and disabled if the property was not defined. For example, the following + works but there is no way to override the file existence check negatively (only positively): </p> <pre> <target name="-check-use-file"> @@ -357,16 +309,14 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { </target> <target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/></pre> <p> - <em>Since Ant 1.8.0</em>, you may instead use property expansion; - a value of <q>true</q> (or <q>on</q> or <q>yes</q>) will enable - the item, while <q>false</q> (or <q>off</q> or <q>no</q>) will - disable it. Other values are still assumed to be property names - and so the item is enabled only if the named property is defined. + <em>Since Ant 1.8.0</em>, you may instead use property expansion; a value of <q>true</q> + (or <q>on</q> or <q>yes</q>) will enable the item, while <q>false</q> (or <q>off</q> + or <q>no</q>) will disable it. Other values are still assumed to be property names and so the + item is enabled only if the named property is defined. </p> <p> - Compared to the older style, this gives you additional - flexibility, because you can override the condition from the - command line or parent scripts: + Compared to the older style, this gives you additional flexibility, because you can override the + condition from the command line or parent scripts: </p> <pre> <target name="-check-use-file" <strong>unless="file.exists"</strong>> @@ -377,9 +327,8 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { </target> <target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/></pre> <p> - Now <code>ant -Dfile.exists=false lots-of-stuff</code> will - run <q>other-unconditional-stuff</q> but not <q>use-file</q>, as - you might expect, and you can disable the condition from another + Now <code>ant -Dfile.exists=false lots-of-stuff</code> will run <q>other-unconditional-stuff</q> + but not <q>use-file</q>, as you might expect, and you can disable the condition from another script too: </p> <pre> @@ -387,12 +336,10 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator { <param name="file.exists" value="false"/> </antcall></pre> <p> - Similarly, an <var>unless</var> attribute disables the item if it - is either the name of property which is defined, or if it - evaluates to a <q>true</q>-like value. For example, the following - allows you to define <code>skip.printing.message=true</code> - in <samp>my-prefs.properties</samp> with the results you might - expect: + Similarly, an <var>unless</var> attribute disables the item if it is either the name of property + which is defined, or if it evaluates to a <q>true</q>-like value. For example, the following + allows you to define <code>skip.printing.message=true</code> in <samp>my-prefs.properties</samp> + with the results you might expect: </p> <pre> <property file="my-prefs.properties"/> http://git-wip-us.apache.org/repos/asf/ant/blob/97d81a72/manual/proxy.html ---------------------------------------------------------------------- diff --git a/manual/proxy.html b/manual/proxy.html index 9b378cc..4071503 100644 --- a/manual/proxy.html +++ b/manual/proxy.html @@ -234,10 +234,10 @@ For csh/tcsh: <p> Any program that is executed with <code><java></code> without - setting <var>fork</var>=<q>true</q> will pick up the Ant's - settings. If you need different values, - set <var>fork</var>=<q>false</q> and provide the values - in <code><sysproperty></code> elements. + setting <var>fork</var>=<q>true</q> will pick up the Ant's + settings. If you need different values, + set <var>fork</var>=<q>false</q> and provide the values + in <code><sysproperty></code> elements. </p> <p> If you wish to have a forked process pick up the Ant's settings, use @@ -282,7 +282,8 @@ For csh/tcsh: <h4>Further reading</h4> <ul> - <li><a href="https://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.html";>Java Networking Properties</a>.</li> + <li><a href="https://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.html"; + target="_top">Java Networking Properties</a>.</li> </ul> </body> http://git-wip-us.apache.org/repos/asf/ant/blob/97d81a72/manual/running.html ---------------------------------------------------------------------- diff --git a/manual/running.html b/manual/running.html index be6ca20..e9d0ef2 100644 --- a/manual/running.html +++ b/manual/running.html @@ -404,10 +404,9 @@ properties are available via Project instance, I searched for them with a</p> for <var>srcencoding</var>, <var>destencoding</var> and <var>bundleencoding</var> in <a href="Tasks/translate.html">translate</a><br/> see JavaDoc - of <a target="_blank" - href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html";>java.nio.charset.Charset</a> - for more information about character sets (not used in Ant, but - has nice docs). + of <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html"; + target="_top">java.nio.charset.Charset</a> for more information + about character sets (not used in Ant, but has nice docs). </td> </tr> <tr> @@ -416,7 +415,7 @@ properties are available via Project instance, I searched for them with a</p> <td>The specified path is added to the classpath if Jikes is used as compiler.</td> </tr> <tr> - <td><code>MailLogger.properties.file, MailLogger.*</code></td> + <td><code>MailLogger.properties.file</code>, <code>MailLogger.*</code></td> <td>filename (optional, defaults derived from Project instance)</td> <td>Name of the file holding properties for sending emails by the <a href="listeners.html#MailLogger">MailLogger</a>. Override http://git-wip-us.apache.org/repos/asf/ant/blob/97d81a72/manual/tasksoverview.html ---------------------------------------------------------------------- diff --git a/manual/tasksoverview.html b/manual/tasksoverview.html index 2f4c41f..8eb702e 100644 --- a/manual/tasksoverview.html +++ b/manual/tasksoverview.html @@ -172,10 +172,10 @@ documentation.</p> <tr> <td><a href="Tasks/jdepend.html">JDepend</a></td> <td><p>Invokes - the <a href="http://www.clarkware.com/software/JDepend.html";> - JDepend</a> parser. This parser "traverses a set of Java - source-file directories and generates design-quality metrics for - each Java package".</p></td> + the <a href="http://www.clarkware.com/software/JDepend.html"; + target="_top">JDepend</a> parser. This parser "traverses a + set of Java source-file directories and generates design-quality + metrics for each Java package".</p></td> </tr> </table> @@ -520,8 +520,7 @@ documentation.</p> </tr> <tr> - <td><a href="Tasks/replaceregexp.html"> - ReplaceRegExp</a></td> + <td><a href="Tasks/replaceregexp.html">ReplaceRegExp</a></td> <td><p>Replaces the occurrence of a given regular expression with a substitution pattern in a file or set of files.</p></td> </tr> @@ -788,23 +787,24 @@ documentation.</p> <tr> <td><a href="Tasks/jjdoc.html">JJDoc</a></td> - <td><p>Invokes the <a href="https://javacc.org/";>JJDoc</a> - documentation generator for the JavaCC compiler-compiler. JJDoc - takes a JavaCC parser specification and produces documentation - for the BNF grammar. It can operate in three modes, determined - by command line options. This task only invokes JJDoc if the - grammar file is newer than the generated BNF grammar - documentation.</p></td> + <td><p>Invokes the <a href="https://javacc.org/"; + target="_top">JJDoc</a> documentation generator for the JavaCC + compiler-compiler. JJDoc takes a JavaCC parser specification and + produces documentation for the BNF grammar. It can operate in + three modes, determined by command line options. This task only + invokes JJDoc if the grammar file is newer than the generated BNF + grammar documentation.</p></td> </tr> <tr> <td><a href="Tasks/jjtree.html">JJTree</a></td> - <td><p>Invokes the <a href="https://javacc.org/";>JJTree</a> - preprocessor for the JavaCC compiler-compiler. It inserts - parse-tree building actions at various places in the JavaCC - source that it generates. The output of JJTree is run through - JavaCC to create the parser. This task only invokes JJTree if the - grammar file is newer than the generated JavaCC file.</p></td> + <td><p>Invokes the <a href="https://javacc.org/"; + target="_top">JJTree</a> preprocessor for the JavaCC + compiler-compiler. It inserts parse-tree building actions at + various places in the JavaCC source that it generates. The output + of JJTree is run through JavaCC to create the parser. This task + only invokes JJTree if the grammar file is newer than the + generated JavaCC file.</p></td> </tr> <tr> @@ -813,8 +813,7 @@ documentation.</p> </tr> <tr> - <td><a href="Tasks/native2ascii.html"> - Native2Ascii</a></td> + <td><a href="Tasks/native2ascii.html">Native2Ascii</a></td> <td><p>Converts files from native encodings to ASCII with escaped Unicode. A common usage is to convert source files maintained in a native operating system encoding to ASCII, prior to @@ -919,8 +918,7 @@ documentation.</p> </tr> <tr> - <td><a href="Tasks/propertyfile.html"> - PropertyFile</a></td> + <td><a href="Tasks/propertyfile.html">PropertyFile</a></td> <td><p>Creates or modifies property files. Useful when wanting to make unattended modifications to configuration files for application servers and applications. Typically used for things @@ -1050,8 +1048,7 @@ documentation.</p> </tr> <tr> - <td><a href="Tasks/vss.html"> - Microsoft Visual SourceSafe</a></td> + <td><a href="Tasks/vss.html">Microsoft Visual SourceSafe</a></td> <td><p>Tasks to perform the Visual SourceSafe <em>vssget</em>, <em>vsslabel</em>, <em>vsshistory</em>, <em>vsscheckin</em>, <em>vsscheckout</em>, <em>vssadd</em>, <em>vsscp</em>, @@ -1084,9 +1081,10 @@ documentation.</p> <tr> <td><a href="Tasks/junit.html">Junit</a></td> - <td><p>Runs tests from the <a href="https://junit.org";>Junit</a> - testing framework. This task has been tested with JUnit 3.0 and - later; it won't work with versions prior to JUnit 3.0.</p></td> + <td><p>Runs tests from the <a href="https://junit.org"; + target="_top">Junit</a> testing framework. This task has been + tested with JUnit 3.0 and later; it won't work with versions + prior to JUnit 3.0.</p></td> </tr> <tr> http://git-wip-us.apache.org/repos/asf/ant/blob/97d81a72/manual/tutorial-HelloWorldWithAnt.html ---------------------------------------------------------------------- diff --git a/manual/tutorial-HelloWorldWithAnt.html b/manual/tutorial-HelloWorldWithAnt.html index 186f84e..45c301a 100644 --- a/manual/tutorial-HelloWorldWithAnt.html +++ b/manual/tutorial-HelloWorldWithAnt.html @@ -244,13 +244,13 @@ because</p> <li>it's from Apache ;-)</li> </ul> <p>We store our external libraries in a new directory <samp>lib</samp>. Log4J can -be <a href="https://archive.apache.org/dist/logging/log4j/1.2.17/logging-log4j-1.2.17.zip";>downloaded [1]</a> from -Logging's Homepage. Create the <samp>lib</samp> directory and extract the <samp>log4j-1.2.17.jar</samp> into that -directory. After that we have to modify our Java source file to use that library and our buildfile so that this library -could be accessed during compilation and run.</p> -<p>Working with Log4J is documented inside its manual. Here we use the <var>MyApp</var>-example from -the <a href="https://logging.apache.org/log4j/1.2/manual.html";>Short Manual [2]</a>. First we have to modify the java -source to use the logging framework:</p> +be <a href="https://archive.apache.org/dist/logging/log4j/1.2.17/logging-log4j-1.2.17.zip"; target="_top">downloaded +[1]</a> from Logging's Homepage. Create the <samp>lib</samp> directory and extract the <samp>log4j-1.2.17.jar</samp> +into that directory. After that we have to modify our Java source file to use that library and our buildfile so that +this library could be accessed during compilation and run.</p> +<p>Working with Log4J is documented inside its manual. Here we use the <samp>MyApp</samp>-example from +the <a href="https://logging.apache.org/log4j/1.2/manual.html"; target="_top">Short Manual [2]</a>. First we have to +modify the java source to use the logging framework:</p> <pre class="code"> package oata; @@ -413,9 +413,9 @@ junit instruction to our buildfile:</p> ...</pre> <p>We reuse the path to our own jar file as defined in run-target by giving it an ID and making it globally available. -The <code>printsummary=yes</code> lets us see more detailed information than just a "FAILED" or "PASSED" message. How -much tests failed? Some errors? <var>printsummary</var> lets us know. The classpath is set up to find our classes. To -run tests the <code>batchtest</code> here is used, so you could easily add more test classes in the future just by +The <var>printsummary</var>=<q>yes</q> lets us see more detailed information than just a "FAILED" or "PASSED" message. +How much tests failed? Some errors? <var>printsummary</var> lets us know. The classpath is set up to find our classes. +To run tests the <code>batchtest</code> here is used, so you could easily add more test classes in the future just by naming them <code>*Test.java</code>. This is a common naming scheme.</p> <p>After a <code>ant junit</code> you'll get:</p> @@ -470,9 +470,11 @@ don't need the HTML report just for testing, e.g. if you are fixing an error or <h2 id="resources">Resources</h2> <ol class="refs"> - <li><a href="https://archive.apache.org/dist/logging/log4j/1.2.17/logging-log4j-1.2.17.zip";>https://archive.apache.org/dist/logging/log4j/1.2.17/logging-log4j-1.2.17.zip</a></li> - <li><a href="https://logging.apache.org/log4j/1.2/manual.html";>https://logging.apache.org/log4j/1.2/manual.html</a></li> - <li><a href="https://junit.org/junit4";>https://junit.org/junit4</a></li> + <li><a href="https://archive.apache.org/dist/logging/log4j/1.2.17/logging-log4j-1.2.17.zip"; + target="_top">https://archive.apache.org/dist/logging/log4j/1.2.17/logging-log4j-1.2.17.zip</a></li> + <li><a href="https://logging.apache.org/log4j/1.2/manual.html"; + target="_top">https://logging.apache.org/log4j/1.2/manual.html</a></li> + <li><a href="https://junit.org/junit4"; target="_top">https://junit.org/junit4</a></li> </ol> </body>
