From a5094b960f6b95ebdca130074eb883d69f945af4 Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Fri, 27 Apr 2001 07:57:29 +0000 Subject: [PATCH] Added a couple of FAQs. git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@268976 13f79535-47bb-0310-9956-ffa450edef68 --- webpage/docs/faq.html | 520 +++++++++++++++++++++++++++++++++++++++++- webpage/xdocs/faq.xml | 295 +++++++++++++++++++++++- 2 files changed, 812 insertions(+), 3 deletions(-) diff --git a/webpage/docs/faq.html b/webpage/docs/faq.html index 6507bc7ca..8330a9d46 100644 --- a/webpage/docs/faq.html +++ b/webpage/docs/faq.html @@ -86,6 +86,28 @@
+ + +
+ + General + +
+
+ +
+
+ +
Installation @@ -101,6 +123,26 @@
+ + +
+ + Ant and IDEs/Editors + +
+
+ +
+
+
@@ -113,6 +155,27 @@ + +
+ + + +
+ + Known problems + +
+
+
@@ -130,7 +193,141 @@
- + + + + +
+ + + 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 + +
+
+
+ +
@@ -142,7 +339,7 @@
-

Ant's distibution contains file names that are longer +

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 @@ -159,6 +356,74 @@

+ + + + + +
+ + + Is Ant supported by my IDE/Editor? + + +
+
+

See the section + on IDE integration on our external resource page.

+
+
+ + + + + +
+ + + Why doesn't (X)Emacs 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 Emacs 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))
+
+
+
+
@@ -226,6 +491,257 @@ <!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 -logger BuildMonitor
+
+
+
+
+ + + + +
+ + + <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:

+
+ + + + + + + + + diff --git a/webpage/xdocs/faq.xml b/webpage/xdocs/faq.xml index 887c2a49b..3e268d38a 100644 --- a/webpage/xdocs/faq.xml +++ b/webpage/xdocs/faq.xml @@ -6,12 +6,93 @@ Frequently Asked Questions + + + 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:

+ + 
+tr -d '\r' < $ANT_HOME/bin/antRun > /tmp/foo
+mv /tmp/foo $ANT_HOME/bin/antRun
+ + + + + + + + + + + + + + + + + + + +
Ant VersionRelease Date
1.119 July 2000
1.224 October 2000
1.33 March 2001
+ + + + + I get checksum errors when I try to extract the tar.gz distribution file. Why? -

Ant's distibution contains file names that are longer +

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 @@ -31,6 +112,44 @@ + + + Is Ant supported by my IDE/Editor? + +

See the section + on IDE integration on our external resource page.

+ + + + + Why doesn't (X)Emacs 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 Emacs 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.

+ + + + + + + How do I include an XML snippet in my build file? @@ -67,8 +186,182 @@ ]> +]]> + + + + + 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

+ + + +

With a monitor.properties like this

+ + +mail.from=Will Glozer + +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

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

+ + /tmp/foo +mv /tmp/foo $ANT_HOME/bin/antRun ]]> +