Ant Front Page News Documentation External Tools and Tasks Resources Ant FAQ Download Binaries Source Code Jakarta News & Status Mission Guidelines Notes FAQs Get Involved Overview CVS Repositories Mailing Lists Reference Library Bug Database Enhancement Requests |
Questions
> General
> What is Ant? Why do you call it Ant? Tell us a little bit about Ant's history.
> Installation
> I get checksum errors when I try to extract the `tar.gz` distribution file. Why?
> Using Ant
> Why does Ant always recompile all my Java files? How do I pass parameters from the command line to my build file? How can I use Jikes specific command line switches? How do I include a < character in my command line arguments? How do I redirect standard input or standard output in the `<exec>` task?
> Ant and IDEs/Editors
> Is Ant supported by my IDE/Editor? Why doesn't (X)Emacs/vi/MacOS X's project builder parse the error messages generated by Ant correctly?
> Advanced issues
> Is there a DTD that I can use to validate my build files? How do I include an XML snippet in my build file? How do I send an email with the result of my build process?
> Known problems
> <chmod> or <exec> don't work in Ant 1.3 on Unix JavaDoc failed: java.io.IOException: javadoc: cannot execute
Answers
> What is Ant?
> Ant is a Java based build tool. In theory it is kind of like "make" without makes wrinkles and with the full portability of pure Java code.
> Why do you call it Ant?
> According to Ant's original author James Duncan Davidson, the name is an acronym for "Another Neat Tool". Later explanations go along the lines of "Ants are doing an extremely good job at building things" or "Ants are very small and can carry a weight a dozen times of their own" - describing what Ant is intended to be.
> Tell us a little bit about Ant's history.
> > Initially Ant was part of the Tomcat code base when it was donated to the Apache Software Foundation - it has been created by James Duncan Davidson, who also is the original author of Tomcat. Ant was there to build Tomcat, nothing else. Soon thereafter several open source Java projects realized that Ant could solve the problems they had with makefiles. Starting with the projects hosted at Jakarta and the old Java Apache project, Ant spread like a virus and now is the build tool of choice for a lot of projects. In January 2000 Ant was moved to a separate CVS module and was promoted to a project of its own, independent of Tomcat. The first version of Ant that was exposed a lager audience was the one that shipped with Tomcat's 3.1 release on 19 April 2000. This version has later been referenced to as Ant 0.3.1. The first official release of Ant as a stand alone product was Ant 1.1 released on 19 July 2000. The complete release history:
> > Ant Version | Release Date
> > 1.1 | 19 July 2000
> > 1.2 | 24 October 2000
> > 1.3 | 3 March 2001
> I get checksum errors when I try to extract the `tar.gz` distribution file. Why?
> Ant's distribution contains file names that are longer than 100 characters, which is not supported by the standard tar file format. Several different implementations of tar use different and incompatible ways to work around this restriction. Ant's <tar> task can create tar archives that use the GNU tar extension, and this has been used when putting together the distribution. If you are using a different version of tar (for example, the one shipping with Solaris), you cannot use it to extract the archive. The solution is to either install GNU tar, which can be found here or use the zip archive instead (you can extract it using `jar xf`).
> Why does Ant always recompile all my Java files?
> In order to find out which files should be compiled, Ant compares the timestamps of the source files to those of the resulting `.class` files. Opening all source files to find out which package they belong to would be very inefficient - instead of this, Ant expects you to place your source files in a directory hierarchy that mirrors your package hierarchy and to point Ant to the root of this directory tree with the `srcdir` attribute. Say you have `<javac srcdir="src" destdir="dest" />`. If Ant finds a file `src/a/b/C.java` it expects it to be in package `a.b` so that the resulting `.class` file is going to be `dest/a/b/C.class`. If your setup is different, Ant's heuristic won't work and it will recompile classes that are up to date. Ant is not the only tool, that expects a source tree layout like this.
> How do I pass parameters from the command line to my build file?
> Use properties: `ant -D<name>=<value>` lets you define values for properties. These can then be used within your build file as any normal property: `${<name>}` will put in `<value>`.
> How can I use Jikes specific command line switches?
> > A couple of switches are supported via magic properties:
> > switch | property | default
> > +E | build.compiler.emacs | false == not set
> > -nowarn | build.compiler.warnings | true == not set
> > +P | build.compiler.pedantic | false == not set
> > +F | build.compiler.fulldepend | false == not set
> How do I include a < character in my command line arguments?
> The short answer is "Use `&lt;`". The long answer is, that this probably won't do what you want anyway, see the next section.
> How do I redirect standard input or standard output in the `<exec>` task?
> > Say you want to redirect the standard input stream of the `cat` command to read from a file, something like
> >     shell-prompt> cat < foo
> > and try to translate it into
> >     <exec executable="cat">
> >       <arg value="&lt;" />
> >       <arg value="foo" />
> >     </exec>
> > This will not do what you expect. The input-redirection is performed by your shell, not the command itself, so this should read:
> >     <exec executable="/bin/sh">
> >       <arg value="-c" />
> >       <arg value="cat &lt; foo" />
> >     </exec>
> Note, that you must use the `value` attribute of `<arg>` in the last element.
> Is Ant supported by my IDE/Editor?
> See the section on IDE integration on our external tools page.
> Why doesn't (X)Emacs/vi/MacOS X's project builder parse the error messages generated by Ant correctly?
> > Ant adds a "banner" with the name of the current task in front of all messages - and there are no built-in regular expressions in your Editor that would account for this. You can disable this banner by invoking Ant with the `-emacs` switch. Alternatively you can add the following snippet to your `.emacs` to make Emacs understand Ant's output.
> >     (require 'compile)
> >     (setq compilation-error-regexp-alist
> >       (append (list
> >          ;; works for jikes
> >          '("^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):\\([0-9]+\\):[0-9]+:[0-9]+:" 1 2 3)
> >          ;; works for javac
> >          '("^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):" 1 2))
> >       compilation-error-regexp-alist))
> > Yet another alternative that preserves most of Ant's formatting is to pipe Ant's output through the following Perl script by Dirk-Willem van Gulik:
> >     #!/usr/bin/perl
> >     #
> >     # May 2001 dirkx@apache.org - remove any
> >     # [foo] lines from the output; keeping
> >     # spacing more or less there.
> >     #
> >     $|=1;
> >     while(<STDIN>) {
> >     	if (s/^(\s+)\[(\w+)\]//) {
> >     		if ($2 ne $last) {
> >     			print "$1\[$2\]";
> >     			$s = ' ' x length($2);
> >     		} else {
> >     			print "$1 $s ";
> >     		};
> >     		$last = $2;
> >     	};
> >     	print;
> >     };
> Is there a DTD that I can use to validate my build files?
> An incomplete DTD can be created by the `<antstructure>` task - but this one has a few problems: It doesn't know about required attributes. Only manual tweaking of this file can help here. It is not complete - if you add new tasks via `<taskdef>` it won't know about it. See this page by Michel Casabianca for a solution to this problem. Note that the DTD you can download at this page is based on Ant 0.3.1. It may even be an invalid DTD. As Ant allows tasks writers to define arbitrary elements, name collisions will happen quite frequently - if your version of Ant contains the optional `<test>` and `<junit>` tasks, there are two XML elements named test (the task and the nested child element of `<junit>`) with different attribute lists. This problem cannot be solved, DTDs don't give a syntax rich enough to support this.
> How do I include an XML snippet in my build file?
> > You can use XML's way of including external files and let the parser do the job for Ant:
> >     <?xml version="1.0"?>

> >     <!DOCTYPE project [
> >         <!ENTITY common SYSTEM "file:./common.xml">
> >     ]>

> >     <project name="test" default="test" basedir=".">

> >       <target name="setup">
> >         ...
> >       </target>

> >       &common;

> >       ...

> >     </project>
> > will literally include the contents of `common.xml` where you've placed the `&common;` entity. In combination with a DTD, this would look like this:
> >     <!DOCTYPE project PUBLIC "-//ANT//DTD project//EN" "file:./ant.dtd" [
> >        <!ENTITY include SYSTEM "file:./header.xml">
> >     ]>
> How do I send an email with the result of my build process?
> > You can use a custom BuildListener, that sends out an email in the buildFinished() method. Will Glozer <will.glozer@jda.com> has written such a listener based on JavaMail, the source is
> >     import java.io.*;
> >     import java.util.*;
> >     import javax.mail.*;
> >     import javax.mail.internet.*;
> >     import org.apache.tools.ant.*;

> >     /**
> >      * A simple listener that waits for a build to finish and sends an email
> >      * of the results.  The settings are stored in "monitor.properties" and
> >      * are fairly self explanatory.
> >      *
> >      * @author      Will Glozer
> >      * @version     1.05a 09/06/2000
> >      */
> >     public class BuildMonitor implements BuildListener {
> >         protected Properties props;

> >         /**
> >          * Create a new BuildMonitor.
> >          */
> >         public BuildMonitor() throws Exception {
> >             props = new Properties();
> >             InputStream is = getClass().getResourceAsStream("monitor.properties");
> >             props.load(is);
> >             is.close();
> >         }

> >         public void buildStarted(BuildEvent e) {
> >         }

> >         /**
> >          * Determine the status of the build and the actions to follow, now that
> >          * the build has completed.
> >          *
> >          * @param       e       Event describing the build tatus.
> >          */
> >         public void buildFinished(BuildEvent e) {
> >             Throwable th = e.getException();
> >             String status = (th != null) ? "failed" : "succeeded";

> >             try {
> >                 String key = "build." + status;
> >                 if (props.getProperty(key + ".notify").equalsIgnoreCase("false")) {
> >                         return;
> >                 }

> >                 Session session = Session.getDefaultInstance(props, null);

> >                 MimeMessage message = new MimeMessage(session);
> >                 message.addRecipients(Message.RecipientType.TO, parseAddresses(
> >                     props.getProperty(key + ".email.to")));
> >                 message.setSubject(props.getProperty(key + ".email.subject"));

> >                 BufferedReader br = new BufferedReader(new FileReader(
> >                     props.getProperty("build.log")));
> >                 StringWriter sw = new StringWriter();

> >                 String line = br.readLine();
> >                 while (line != null) {
> >                     sw.write(line);
> >                     sw.write("\n");
> >                     line = br.readLine();
> >                 }
> >                 br.close();

> >                 message.setText(sw.toString(), "UTF-8");
> >                 sw.close();

> >                 Transport transport = session.getTransport();
> >                 transport.connect();
> >                 transport.send(message);
> >                 transport.close();
> >             } catch (Exception ex) {
> >                 System.out.println("BuildMonitor failed to send email!");
> >                 ex.printStackTrace();
> >             }
> >         }

> >         /**
> >          * Parse a comma separated list of internet email addresses.
> >          *
> >          * @param       s       The list of addresses.
> >          * @return      Array of Addresses.
> >          */
> >         protected Address[] parseAddresses(String s) throws Exception {
> >             StringTokenizer st = new StringTokenizer(s, ",");
> >             Address[] addrs = new Address[st.countTokens()];

> >             for (int i = 0; i < addrs.length; i++) {
> >                 addrs[i] = new InternetAddress(st.nextToken());
> >             }
> >             return addrs;
> >         }

> >         public void messageLogged(BuildEvent e) {
> >         }

> >         public void targetStarted(BuildEvent e) {
> >         }

> >         public void targetFinished(BuildEvent e) {
> >         }

> >         public void taskStarted(BuildEvent e) {
> >         }

> >         public void taskFinished(BuildEvent e) {
> >         }
> >     }
> > With a `monitor.properties` like this
> >     # configuration for build monitor

> >     mail.transport.protocol=smtp
> >     mail.smtp.host=<host>
> >     mail.from=Will Glozer <will.glozer@jda.com>

> >     build.log=build.log

> >     build.failed.notify=true
> >     build.failed.email.to=will.glozer@jda.com
> >     build.failed.email.subject=Nightly build failed!

> >     build.succeeded.notify=true
> >     build.succeeded.email.to=will.glozer@jda.com
> >     build.succeeded.email.subject=Nightly build succeeded!
> > `monitor.properties` should be placed right next to your compiled `BuildMonitor.class`. To use it, invoke Ant like
> >     ant -listener BuildMonitor
> Make sure that `mail.jar` from JavaMail and `activation.jar` from the Java Beans Activation Framework in your `CLASSPATH`.
> <chmod> or <exec> don't work in Ant 1.3 on Unix
> > The `antRun` script in `ANT_HOME/bin` has DOS instead of Unix line endings, you must remove the carriage return characters from this file. This can be done by using Ant's <fixcrlf> task or something like:
> >     tr -d '\r' < $ANT_HOME/bin/antRun > /tmp/foo
> >     mv /tmp/foo $ANT_HOME/bin/antRun
> JavaDoc failed: java.io.IOException: javadoc: cannot execute
> There is a bug in the Solaris reference implementation of the JDK, see http://developer.java.sun.com/developer/bugParade/bugs/4230399.html. This also appears to be true under Linux, moving the JDK to the front of the PATH fixes the problem.
Copyright © 1999-2001, Apache Software Foundation