From b9421dc80af485591a9c50cc8921f912e0def11e Mon Sep 17 00:00:00 2001 From: Ashlee Young Date: Fri, 23 Oct 2015 10:05:40 -0700 Subject: Removing sources to replace with download links instead. Change-Id: Ie28789a725051aec0d1b04dd291b7690a7898668 Signed-off-by: Ashlee Young --- .../src/ant/apache-ant-1.9.6/manual/running.html | 622 --------------------- 1 file changed, 622 deletions(-) delete mode 100644 framework/src/ant/apache-ant-1.9.6/manual/running.html (limited to 'framework/src/ant/apache-ant-1.9.6/manual/running.html') diff --git a/framework/src/ant/apache-ant-1.9.6/manual/running.html b/framework/src/ant/apache-ant-1.9.6/manual/running.html deleted file mode 100644 index 529afc7d..00000000 --- a/framework/src/ant/apache-ant-1.9.6/manual/running.html +++ /dev/null @@ -1,622 +0,0 @@ - - - - - - -Running Apache Ant - - - - -

Running Apache Ant

Command Line

If you've installed Apache Ant as described in the - Installing Ant section, -running Ant from the command-line is simple: just type -ant.

When no arguments are specified, Ant looks for a build.xml -file in the current directory and, if found, uses that file as the -build file and runs the target specified in the default -attribute of the <project> tag. -To make Ant use -a build file other than build.xml, use the command-line -option -buildfile file, -where file is the name of the build file you want to use -(or a directory containing a build.xml file).

-If you use the -find [file] option, -Ant will search for a build file first in the current directory, then in -the parent directory, and so on, until either a build file is found or the root -of the filesystem has been reached. By default, it will look for a build file -called build.xml. To have it search for a build file other -than build.xml, specify a file argument. -Note: If you include any other flags or arguments -on the command line after -the -find flag, you must include the file argument -for the -find flag, even if the name of the -build file you want to find is build.xml. - -

You can also set properties on the -command line. This can be done with -the -Dproperty=value option, -where property is the name of the property, -and value is the value for that property. If you specify a -property that is also set in the build file -(see the property task), -the value specified on the -command line will override the value specified in the -build file. -Defining properties on the command line can also be used to pass in -the value of environment variables; just pass --DMYVAR=%MYVAR% (Windows) or --DMYVAR=$MYVAR (Unix) -to Ant. You can then access -these variables inside your build file as ${MYVAR}. -You can also access environment variables using the - property task's -environment attribute. -

- -

Options that affect the amount of logging output by Ant are: --quiet, -which instructs Ant to print less -information to the console; --verbose, which causes Ant to print -additional information to the console; -debug, -which causes Ant to print considerably more additional information; and --silent which makes Ant print nothing but task -output and build failures (useful to capture Ant output by scripts). -

- -

It is also possible to specify one or more targets that should be executed. -When omitted, the target that is specified in the -default attribute of the -project tag is -used.

- -

The -projecthelp option prints out a list -of the build file's targets. Targets that include a -description attribute are listed as "Main targets", -those without a description are listed as -"Other targets", then the "Default" target is listed -("Other targets" are only displayed if there are no main -targets, or if Ant is invoked in -verbose or -debug mode). - -

Command-line Options Summary

ant [options] [target [target2 [target3] ...]]
-Options:
-  -help, -h              print this message and exit
-  -projecthelp, -p       print project help information and exit
-  -version               print the version information and exit
-  -diagnostics           print information that might be helpful to
-                         diagnose or report problems and exit
-  -quiet, -q             be extra quiet
-  -silent, -S            print nothing but task outputs and build failures
-  -verbose, -v           be extra verbose
-  -debug, -d             print debugging information
-  -emacs, -e             produce logging information without adornments
-  -lib <path>            specifies a path to search for jars and classes
-  -logfile <file>        use given file for log
-    -l     <file>                ''
-  -logger <classname>    the class which is to perform logging
-  -listener <classname>  add an instance of class as a project listener
-  -noinput               do not allow interactive input
-  -buildfile <file>      use given buildfile
-    -file    <file>              ''
-    -f       <file>              ''
-  -D<property>=<value>   use value for given property
-  -keep-going, -k        execute all targets that do not depend
-                         on failed target(s)
-  -propertyfile <name>   load all properties from file with -D
-                         properties taking precedence
-  -inputhandler <class>  the class which will handle input requests
-  -find <file>           (s)earch for buildfile towards the root of
-    -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
-  -autoproxy             Java 1.5+ : use the OS proxies
-  -main <class>          override Ant's normal entry point
-

For more information about -logger and --listener see -Loggers & Listeners. -

For more information about -inputhandler see -InputHandler. -

Easiest way of changing the exit-behaviour is subclassing the original main class: -

-public class CustomExitCode extends org.apache.tools.ant.Main {
-    protected void exit(int exitCode) {
-        // implement your own behaviour, e.g. NOT exiting the JVM
-    }
-}
-

and starting Ant with access (-lib path-to-class) to this class. -

- -

Library Directories

-Prior to Ant 1.6, all jars in the ANT_HOME/lib would be added to the CLASSPATH -used to run Ant. This was done in the scripts that started Ant. From Ant 1.6, -two directories are scanned by default and more can be added as required. The -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 administrators. -

- -

-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: -

- -

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

- -

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

- -

-The location of ${user.home}/.ant/lib is somewhat dependent on the JVM. On Unix -systems ${user.home} maps to the user's home directory whilst on recent -versions of Windows it will be somewhere such as -C:\Documents and Settings\username\.ant\lib. You should consult your -JVM documentation for more details. -

- -

Examples

-
ant
-

runs Ant using the build.xml file in the current directory, on -the default target.

- -

ant -buildfile test.xml

runs Ant using the test.xml file in the current directory, on -the default target.

- -

ant -buildfile test.xml dist

runs Ant using the test.xml file in the current directory, on -the target called dist.

- -

ant -buildfile test.xml -Dbuild=build/classes dist

runs Ant using the test.xml file in the current directory, on -the target called dist, setting the build property -to the value build/classes.

- -

ant -lib /home/ant/extras

runs Ant picking up additional task and support jars from the -/home/ant/extras location

- -

ant -lib one.jar;another.jar

ant -lib one.jar -lib another.jar

adds two jars to Ants classpath.

- - - -

Files

- -

The Ant wrapper script for Unix will source (read and evaluate) the -file ~/.antrc before it does anything. On Windows, the Ant -wrapper batch-file invokes %HOME%\antrc_pre.bat at the start and -%HOME%\antrc_post.bat at the end. You can use these -files, for example, to set/unset environment variables that should only be -visible during the execution of Ant. See the next section for examples.

- -

Environment Variables

- -

The wrapper scripts use the following environment variables (if -set):

- -

JAVACMD - full path of the Java executable. Use this - to invoke a different JVM than JAVA_HOME/bin/java(.exe).
ANT_OPTS - command-line arguments that should be - passed to the JVM. For example, you can define system properties or set - the maximum Java heap size here.
ANT_ARGS - Ant command-line arguments. For example, - set ANT_ARGS to point to a different logger, include a - listener, and to include the -find flag.

Note:

-find

ANT_ARGS

build.xml

- -

Java System Properties

Some of Ant's core classes 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, -line.separator, java.home, java.version, java.version, user.home, java.class.path
-And I filtered out the getPropertyHelper access.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

property name	valid values /default value	description
`ant.build.javac.source`	Source-level version number	Default source value for <javac>/<javadoc>
`ant.build.javac.target`	Class-compatibility version number	Default target value for <javac>
`ant.executor.class`	classname; 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.file`	read only: full filename of the build file	This 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)	Name of the file holding the values for the - PropertyFileInputHandler. -
`ant.logger.defaults`	filename (optional, default '/org/ apache/ tools/ ant/ listener/ defaults.properties')	Name of the file holding the color mappings for the - AnsiColorLogger. -
`ant.netrexxc.*`	several formats	Use specified values as defaults for netrexxc. -
`ant.PropertyHelper`	ant-reference-name (optional)	Specify the PropertyHelper to use. The object must be of the type - org.apache.tools.ant.PropertyHelper. If not defined an object of - org.apache.tools.ant.PropertyHelper will be used as PropertyHelper. -
`ant.regexp.regexpimpl`	classname	classname for a RegExp implementation; if not set Ant uses JDK 1.4's implementation; - RegExp-Mapper - "Choice of regular expression implementation" -
`ant.reuse.loader`	boolean	allow to reuse classloaders - used in org.apache.tools.ant.util.ClasspathUtil -
`ant.XmlLogger.stylesheet.uri`	filename (default 'log.xsl')	Name for the stylesheet to include in the logfile by - XmlLogger. -
`build.compiler`	name	Specify the default compiler to use. - see javac, - EJB Tasks - (compiler attribute), - javah -
`build.compiler.emacs`	boolean (default false)	Enable emacs-compatible error messages. - see javac "Jikes Notes" -
`build.compiler.fulldepend`	boolean (default false)	Enable full dependency checking - see javac "Jikes Notes" -
`build.compiler.jvc.extensions`	boolean (default true)	enable Microsoft extensions of their java compiler - see javac "Jvc Notes" -
`build.compiler.pedantic`	boolean (default false)	Enable pedantic warnings. - see javac "Jikes Notes" -
`build.compiler.warnings`	Deprecated flag	see javac "Jikes Notes"
`build.rmic`	name	control the rmic compiler
`build.sysclasspath`	see its dedicated page, no - default value	see its dedicated page
`file.encoding`	name of a supported character set (e.g. UTF-8, ISO-8859-1, US-ASCII)	use as default character set of email messages; use as default for source-, dest- and bundleencoding - in translate - see JavaDoc of java.nio.charset.Charset - for more information about character sets (not used in Ant, but has nice docs). -
`jikes.class.path`	path	The specified path is added to the classpath if jikes is used as compiler.
`MailLogger.properties.file, MailLogger.*`	filename (optional, defaults derived from Project instance)	Name of the file holding properties for sending emails by the - MailLogger. Override properties set - inside the buildfile or via command line. -
`org.apache.tools.ant.ProjectHelper`	classname (optional, default 'org.apache.tools.ant.ProjectHelper2')	specifies the classname to use as ProjectHelper. The class must extend - org.apache.tools.ant.ProjectHelper. -
`org.apache.tools.ant.ArgumentProcessor`	classname (optional)	specifies the classname to use as ArgumentProcessor. The class must extend - org.apache.tools.ant.ArgumentProcessor. -
`websphere.home`	path	Points to home directory of websphere. - see EJB Tasks -
`XmlLogger.file`	filename (default 'log.xml')	Name for the logfile for MailLogger. -
`ant.project-helper-repo.debug`	boolean (default 'false')	Set it to true to enable debugging with Ant's - ProjectHelper internal repository. -
`ant.argument-processor-repo.debug`	boolean (default 'false')	Set it to true to enable debugging with Ant's - ArgumentProcessor internal repository. -

- -

-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. This protects you from future -Ant releases breaking your build file. -

return code

the ant start up scripts (in their Windows and Unix version) return -the return code of the java program. So a successful build returns 0, -failed builds return other values. -

- -

Cygwin Users

The Unix launch script that come with Ant works correctly with Cygwin. You -should not have any problems launching Ant from the Cygwin shell. It is -important to note, however, that once Ant is running it is part of the JDK -which operates as a native Windows application. The JDK is not a Cygwin -executable, and it therefore has no knowledge of Cygwin paths, etc. In -particular when using the <exec> task, executable names such -as "/bin/sh" will not work, even though these work from the Cygwin -shell from which Ant was launched. You can use an executable name such as -"sh" and rely on that command being available in the Windows path. -

- -

OS/2 Users

The OS/2 launch script was developed to perform complex tasks. It has two parts: -ant.cmd which calls Ant and antenv.cmd which sets the 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.

- -

Script ant.cmd first verifies whether the Ant environment is set correctly. The -requirements are:

Environment variable JAVA_HOME is set.
Environment variable ANT_HOME is set.
Environment variable CLASSPATH is set and contains at least one element from -JAVA_HOME and at least one element from ANT_HOME.

- -

If any of these conditions is violated, script antenv.cmd is called. This script -first invokes configuration scripts if there exist: the system-wide configuration -antconf.cmd from the %ETC% directory and then the user configuration -antrc.cmd from the %HOME% directory. At this moment both -JAVA_HOME and ANT_HOME must be defined because antenv.cmd -now adds classes.zip or tools.jar (depending on version of JVM) and -everything from %ANT_HOME%\lib except ant-*.jar to -CLASSPATH. Finally ant.cmd calls per-directory configuration -antrc.cmd. All settings made by ant.cmd are local and are undone when the -script ends. The settings made by antenv.cmd are persistent during the lifetime of the -shell (of course unless called automatically from ant.cmd). It is thus possible to call -antenv.cmd manually and modify some settings before calling ant.cmd.

- -

Scripts envset.cmd and runrc.cmd perform auxiliary tasks. All scripts -have some documentation inside.

- -

Running Ant as a background process on - Unix(-like) systems

- -

If you start Ant as a background process (like in ant - &) and the build process creates another process, Ant will - immediately try to read from standard input, which in turn will - most likely suspend the process. In order to avoid this, you must - redirect Ant's standard input or explicitly provide input to each - spawned process via the input related attributes of the - corresponding tasks.

- -

Tasks that create such new processes - include <exec>, <apply> - or <java> when the fork attribute is - true.

- -

Running Ant via Java

If you have installed Ant in the do-it-yourself way, Ant can be started -from one of two entry points:

java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]

- -

java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher [options] [target]

- -

-The first method runs Ant's traditional entry point. The second method uses -the Ant Launcher introduced in Ant 1.6. The former method does not support -the -lib option and all required classes are loaded from the CLASSPATH. You must -ensure that all required jars are available. At a minimum the CLASSPATH should -include: -

- -

ant.jar and ant-launcher.jar
jars/classes for your XML parser
the JDK's required jar/zip files

- -

-The latter method supports the -lib, -nouserlib, -noclasspath options and will - load jars from the specified ANT_HOME. You should start the latter with the most minimal -classpath possible, generally just the ant-launcher.jar. -

- - - -Ant can be started in Ant via the <java> command. -Here is an example: - -

-<java
-        classname="org.apache.tools.ant.launch.Launcher"
-        fork="true"
-        failonerror="true"
-        dir="${sub.builddir}"
-        timeout="4000000"
-        taskname="startAnt">
-    <classpath>
-        <pathelement location="${ant.home}/lib/ant-launcher.jar"/>
-    </classpath>
-    <arg value="-buildfile"/>
-    <arg file="${sub.buildfile}"/>
-    <arg value="-Dthis=this"/>
-    <arg value="-Dthat=that"/>
-    <arg value="-Dbasedir=${sub.builddir}"/>
-    <arg value="-Dthe.other=the.other"/>
-    <arg value="${sub.target}"/>
-</java>
-

-
- - - - -- cgit 1.2.3-korg