Return-Path: Delivered-To: apmail-jakarta-ant-dev-archive@apache.org Received: (qmail 16453 invoked from network); 20 Jun 2002 18:22:31 -0000 Received: from unknown (HELO nagoya.betaversion.org) (192.18.49.131) by daedalus.apache.org with SMTP; 20 Jun 2002 18:22:31 -0000 Received: (qmail 24606 invoked by uid 97); 20 Jun 2002 18:22:36 -0000 Delivered-To: qmlist-jakarta-archive-ant-dev@jakarta.apache.org Received: (qmail 24590 invoked by uid 97); 20 Jun 2002 18:22:36 -0000 Mailing-List: contact ant-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Ant Developers List" Reply-To: "Ant Developers List" Delivered-To: mailing list ant-dev@jakarta.apache.org Received: (qmail 24579 invoked by uid 97); 20 Jun 2002 18:22:35 -0000 X-Antivirus: nagoya (v4198 created Apr 24 2002) Date: 20 Jun 2002 18:22:23 -0000 Message-ID: <20020620182223.70767.qmail@icarus.apache.org> From: holtdl@apache.org To: jakarta-ant-cvs@apache.org Subject: cvs commit: jakarta-ant/docs/manual running.html X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N holtdl 2002/06/20 11:22:23 Modified: docs/manual Tag: ANT_15_BRANCH running.html Log: Add note about -find (and some general clean-up tweaks). Revision Changes Path No revision No revision 1.13.2.2 +68 -49 jakarta-ant/docs/manual/running.html Index: running.html =================================================================== RCS file: /home/cvs/jakarta-ant/docs/manual/running.html,v retrieving revision 1.13.2.1 retrieving revision 1.13.2.2 diff -u -r1.13.2.1 -r1.13.2.2 --- running.html 3 May 2002 09:40:28 -0000 1.13.2.1 +++ running.html 20 Jun 2002 18:22:22 -0000 1.13.2.2 @@ -15,34 +15,49 @@ 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 -buildfile and runs the "default" target. -If you use the -find option, -Ant will search for a buildfile first in the current directory, then in -the parent directory, and so on, until either a buildfile is found or the root -of the filesystem has been reached. To make Ant use -a buildfile other than build.xml, use the command-line -option -buildfile file, -where file is the name of the buildfile you want to use.

- -

You can also set properties that -override properties specified in the -buildfile (see the property task). -This can be done with +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.

+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. -This can also be used to pass in the value of environment variables. -Just pass -DMYVAR=%MYVAR% (Windows) or +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 buildfile as ${MYVAR}. -You can also access environment variables using the -property task. +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, +

Options that affect the amount of logging output by Ant are: +-quiet, which instructs Ant to print less -information on the console when running; +information to the console; -verbose, which causes Ant to print additional information to the console; and -debug, which causes Ant to print considerably more additional information. @@ -55,9 +70,10 @@ used.

The -projecthelp option prints out a list -of the buildfile's targets, along with the -text in the description attribute of the target, -if one was specified, followed by a list of those targets without one.

+of the build file's targets. Targets that include a +description attribute are listed as "Main targets", +those without a description are listed as +"Subtargets", then the "Default" target is listed.

Command-line Options Summary

ant [options] [target [target2 [target3] ...]]
  @@ -69,22 +85,22 @@
     -verbose               be extra verbose
     -debug                 print debugging information
     -emacs                 produce logging information without adornments
  -  -logfile <file>        use given file for log
  -  -logger <classname>    the class which is to perform logging
  -  -listener <classname>  add an instance of class as a project listener
  -  -buildfile <file>      use given buildfile
  +  -logfile <file>        write logging output to given file
  +  -logger <classname>    the class that is to perform logging
  +  -listener <classname>  add an instance of classname as a project listener
  +  -buildfile <file>      use given build file
     -D<property>=<value>   use value for given property
  -  -propertyfile <name>   load all properties from file with -D
  -                         properties taking precedence
  -  -inputhandler <class>  the class which will handle input requests
  -  -find <file>           search for buildfile towards the root of the
  -                         filesystem and use it
  +  -propertyfile <file>   load all properties from file (with -D taking precedence)
  +  -inputhandler <class>  the class that will handle input requests
  +  -find [<file>]         search for build.xml, or file, towards the root of the
  +                         filesystem

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

For more information about -inputhandler see the -section InputHandler +-listener see +Loggers & Listeners. +

For more information about -inputhandler see +InputHandler. +

Examples

ant
@@ -99,23 +115,23 @@ 
ant -buildfile test.xml dist
-

runs Ant using the test.xml file in the current directory, on a -target called 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 a -target called dist, setting the build property to the -value build/classes.

+

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.

Files

The Ant wrapper script for Unix will source (read and evaluate) the -file ~/.antrc before it does anything - the Windows batch -file invokes %HOME%\antrc_pre.bat at the start and +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 to set/unset environment variables that should only be visible -during the execution of Ant. See the next section for example.

+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

@@ -131,8 +147,11 @@ the maximum Java heap size here.
  • ANT_ARGS - Ant command-line arguments. For example, - set ANT_ARGS to point to a different logger and to - include the -find flag.
    • + set ANT_ARGS to point to a different logger, include a + listener, and to include the -find flag. + Note: If you include -find + in ANT_ARGS, you should include the name of the build file + to find, even if the file is called build.xml.

    Running Ant via Java

    -- To unsubscribe, e-mail: For additional commands, e-mail: