Section 1.5. Running Ant
|
1.5. Running AntRunning Ant from the command-line is simple: %ant [options] [target [target2 [target3] ...]] 1.5.1. Command-Line Optionsoptions are one or more of the command-line options that begin with a hyphen, listed in Table 1-14; target, target2, etc., are the specific targets you want to run in the event you don't want to defer to the project element's default target.
1.5.2. Executing AntIf you want to use a build file named build.xml and want to run the default target, enter ant in the directory containing the build file: %ant For example, if you ran the build file from Example 1-2, that command gives this result: -bash-2.05b$ ant Buildfile: build.xml compile: [javac] Compiling 1 source file compress: [jar] Building jar: /home/httpd/vhosts/builder/Project.jar main: [echo] [echo] Building the .jar file. [echo] BUILD SUCCESSFUL Total time: 2 seconds Each build file requires a default target, but you can specify the target(s) you want Ant to run via the command line. For example, add a target named clean to the build file (using Example 1-2 as a starting point): <project default="main"> <target name="main" depends="compile, compress"> <echo> Building the .jar file. </echo> </target> <target name="compile"> <javac srcdir="."/> </target> <target name="compress"> <jar jarfile="Project.jar" basedir="." includes="*.class" /> </target> <target name="clean"> <delete file="*.class"/> <delete file="*.jar"/> </target> </project> You can then specify the clean target from the command line: %ant clean If you want to run multiple targets, you can list them (in the order they should be run): %ant clean compile compress
By default, the build file that Ant looks for is build.xml, but you can name the file as you want.
For example, if you have a build file named project.xml that you want to use, you can specify that Ant should use that build file with -f (or -file or -buildfile): %ant -f project.xml
1.5.3. Customizable Environment VariablesAnt scripts, which start Ant, use some customizable environment variables:
1.5.4. Failed BuildsEvery Ant developer has builds that fail for one reason or another. Ant does its best to pinpoint the problem. For example, say you misspelled the name of the javac task: <?xml version="1.0" ?> <project default="main"> <target name="main" depends="compile, compress"> <echo> Building the .jar file. </echo> </target> <target name="compile"> <jjavac srcdir="."/> </target> . . .Ant will diagnose this problem when it runs and give you some feedback: %ant build.xml:10: Could not create task or type of type: jjavac. Ant could not find the task or a class this task relies upon. This is common and has a number of causes; the usual solutions are to read the manual pages then download and install needed JAR files, or fix the build file: - You have misspelt 'jjavac'. Fix: check your spelling. - The task needs an external JAR file to execute and this is not found at the right place in the classpath. Fix: check the documentation for dependencies. Fix: declare the task. - The task is an Ant optional task and optional.jar is absent Fix: look for optional.jar in ANT_HOME/lib, download if needed - The task was not built into optional.jar as dependent libraries were not found at build time. Fix: look in the JAR to verify, then rebuild with the needed libraries, or download a release version from apache.org - The build file was written for a later version of Ant Fix: upgrade to at least the latest release version of Ant - The task is not an Ant core or optional task and needs to be declared using <taskdef>. Remember that for JAR files to be visible to Ant tasks implemented in ANT_HOME/lib, the files must be in the same directory or on the classpath Please neither file bug reports on this problem, nor email the Ant mailing lists, until all of these causes have been explored, as this is not an Ant bug. Total time: 0 seconds Sometimes errors won't stop a build, and you may want to change that behavior so the build will terminate when there's been any kind of problem. Most tasks have a failonerror attribute, which is set to false by default. Setting this attribute's value to true makes the build fail if the task encounters an error, allowing you to stop a build if a specific task generates errors . Keep in mind that this won't affect your build in the case where you've previously executed the build and your output files are up to date. By default, Ant tasks check to see if the output files they're supposed to create are current (i.e., the output file is more recent than the files used to create it); if they are, Ant tasks won't recreate them because Ant considers the target executed. For example, here's what you'd see when you run the example build file a second timeAnt displays the names of the various targets but, because they're up to date, it doesn't execute them: %ant Buildfile: build.xml compile: compress: main: [echo] [echo] Building the .jar file. [echo] BUILD SUCCESSFUL Total time: 3 seconds
1.5.5. Verbose OutputYou can control the amount of output Ant gives you when it runs with the -verbose, -quiet, and -debug command-line options. If you ask Ant to be quiet, it won't display anything except for build failure or success, total build time, and any text you specifically output via the echo task. Here's an example of a quiet build: %ant -quiet [echo] [echo] Building the .jar file. [echo] BUILD SUCCESSFUL Total time: 2 seconds On the other side of the coin, the -verbose option gives you a lot more information than normal, including whether Ant is skipping up-to-date output files, what OS or JDK you're using, and a lot more. Here's what you might see from a verbose build on Unix: -bash-2.05b$ ant -verbose Apache Ant version 1.6.1 compiled on February 12 2004 Buildfile: build.xml Detected Java version: 1.4 in: /opt/j2sdk1.4.2_02/jre Detected OS: Linux parsing buildfile /home/build.xml Project base dir set to: /home Build sequence for target `main' is [compile, compress, main] Complete build sequence is [compile, compress, main, clean, ] compile: [javac] Project.class skipped - don't know how to handle it [javac] Project.jar skipped - don't know how to handle it [javac] Project.java omitted as Project.class is up to date. [javac] build.xml skipped - don't know how to handle it compress: [jar] Project.class omitted as Project.class is up to date. main: [echo] [echo] Building the .jar file. [echo] BUILD SUCCESSFUL Total time: 1 second This output shows that Ant is skipping up-to-date output targets. Here's similar output in Windows: %ant -verbose Apache Ant version 1.6.1 compiled on February 12 2004 Buildfile: build.xml Detected Java version: 1.4 in: C:\jdk1.4 Detected OS: Windows 2000 parsing buildfile C:\ant\ch01\build.xml with URI = file:///C:/ant/ch01/build.xml Project base dir set to: C:\ant\ch01 Build sequence for target `main' is [compile, compress, main] Complete build sequence is [compile, compress, main, clean, ] compile: [javac] Project.class skipped - don't know how to handle it [javac] Project.jar skipped - don't know how to handle it [javac] Project.java omitted as Project.class is up to date. [javac] build.xml skipped - don't know how to handle it compress: [jar] Project.class omitted as Project.class is up to date. main: [echo] [echo] Building the .jar file. [echo] BUILD SUCCESSFUL Total time: 2 seconds The -debug options prints out even more informationoften pages of itwhich isn't reproduced here. Included in a debugging build is information about classes as they're loaded, classes that Ant looked for but couldn't find, the locations where Ant is picking up library files, and almost everything else you could think of. Another useful command-line option for displaying information is the -projecthelp option, which 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 "Subtargets", and then the "Default" target is listed. Here's the example build file, with the addition of a description attribute for each target element: <?xml version="1.0" ?> <project default="main"> <target name="main" depends="compile, compress" description="Main target"> <echo> Building the .jar file. </echo> </target> <target name="compile" description="Compilation target"> <javac srcdir="."/> </target> <target name="compress" description="Compression target"> <jar jarfile="Project.jar" basedir="." includes="*.class" /> </target> </project> Here's what you'd see when running Ant with the -projecthelp option: %ant -projecthelp Buildfile: build.xml Main targets: compile Compilation target compress Compression target main Main target Default target: main 1.5.6. Logging and LibrariesYou can log the output of running Ant using the -logfile option. For example, here's how you'd sent output to a file named file.log: %ant -logfile file.log You can log part of a build file's results with the record task; for example, if you were using the javac task to compile code and wanted to log the output of this task to a file named log.txt, you could start and stop that logging this way: <record name="log.txt" action="start"/> <javac ... /> <record name="log.txt" action="stop"/> Another handy option is the -lib option, which adds additional directories to be searched for .jar or .class files. Here's an example, which adds /home/ant/morejars to the library search path: %ant -lib /home/ant/morejars The -lib option is useful when you're working on a system where you don't have access to the Ant lib directory as is often the case when dealing with Internet Service Providers (ISPs). Using this option, you can make sure Ant has access to JAR files needed for Ant's optional tasks without having to load them into directories you don't have permission to access.
|
|
EAN: 2147483647
Pages: 115