很想把Ant好好的學(xué)習(xí)一下，最好的學(xué)習(xí)方法就是看官方文檔，所以決定把原版英文文檔翻譯一下，如果有翻譯不對的地方，請大家指出來，謝謝

英文部份為還沒有翻譯的部份

文檔原始地址：http://ant.apache.org/manual/index.html

參考資料：孫鑫老師的JAVA WEB開發(fā)詳解 

Using Ant

簡單的構(gòu)建文件：

ant的構(gòu)建文件是xml格式的，每一個(gè)構(gòu)建文件包含一個(gè)project和至少一個(gè)(缺省)target，目標(biāo)包含任務(wù)(task)元素，構(gòu)建文件里的每一個(gè)任務(wù)元素（task）可以指定一個(gè)id元素，可以用它的值來引用這個(gè)task，這個(gè)值是唯一的，

（更多說明，請看下面的 Tasks）

Projects（工程）

Project　有三個(gè)屬性

對一個(gè)工程的描述（description）可以用頂級(jí)的元素<description>（請看description 元素）

每個(gè)工程都定義了一個(gè)或多個(gè)目標(biāo)(target)，目標(biāo)就是一系列你要執(zhí)行的任務(wù)，當(dāng)執(zhí)行ant的時(shí)候，你可以選擇執(zhí)行你想要執(zhí)行的目標(biāo)，當(dāng)沒有指定目標(biāo)時(shí)，使用<project>元素中default指定的目標(biāo)。

Targets

一個(gè)目標(biāo)可以依賴其它的目標(biāo)，例如，你可以有一個(gè)編譯的目標(biāo)，一個(gè)發(fā)布的目標(biāo)，只有編譯之后才可以發(fā)布，所以以布目標(biāo)要依賴于編譯，Ant解決這種依賴關(guān)系。

應(yīng)該說明的是，Ant的這種依賴只是指定的目標(biāo)的執(zhí)行順序，這并不影響執(zhí)行那些沒有必要執(zhí)行的依賴目標(biāo)。

Ant執(zhí)行目標(biāo)的順序是按照它們從左到右的出現(xiàn)順序，一個(gè)目標(biāo)比它依賴的目標(biāo)更早執(zhí)行是有可能的。

<target name="A"/>
<target name="B" depends="A"/>
<target name="C" depends="B"/>
<target name="D" depends="C,B,A"/>

我們要執(zhí)行目標(biāo)D.從依賴屬性(depends)看，你可能認(rèn)為應(yīng)該先執(zhí)行目標(biāo)C,然后是B，最后是A，錯(cuò)了!C依賴B，B依賴A，因此，先執(zhí)行A，再是B，接著是C，最后是D

上面從給定目標(biāo)D延伸到依賴的A目標(biāo)的這個(gè)依賴鏈中，每一個(gè)目標(biāo)只執(zhí)行一次，即使多個(gè)目標(biāo)依賴一個(gè)目標(biāo)，因此，執(zhí)行目標(biāo)D首先會(huì)調(diào)用C執(zhí)行，C又會(huì)調(diào)用B執(zhí)行，B將會(huì)導(dǎo)致A第一次被執(zhí)行，然后執(zhí)行B，接著是C，一直執(zhí)行到依賴鏈中的D，這個(gè)過程中，不會(huì)再執(zhí)行B和A，因?yàn)樗麄円呀?jīng)執(zhí)行過了，如果B和C沒有依賴關(guān)系，那么，B和A將在C處理D的依賴時(shí)就被執(zhí)行。

可以設(shè)置某個(gè)特性(Property)執(zhí)行目標(biāo)，例如，這可以依賴系統(tǒng)環(huán)境(java 版本,操作系統(tǒng)，命令行特性定義，等)更好的控制構(gòu)造過程,由特性來添加目標(biāo)，你應(yīng)該添加屬性if(或者 unless屬性)，屬性值為你要作用于此目標(biāo)上的特性。注意：Ant僅檢查這個(gè)特性是否被設(shè)置，這個(gè)特性的值并不重要，一個(gè)空字符串的特性仍然是一個(gè)存在的特性。比如：

<target name="build-module-A" if="module-A-present"/>

<target name="build-own-fake-module-A" unless="module-A-present"/>

在第一個(gè)例子中，如果設(shè)置了module-A-present特性（可以是任何值，比如：false）,目標(biāo)都會(huì)執(zhí)行。

在第二個(gè)例子中，如果設(shè)置了module-A-present（也是任意值），目標(biāo)都不會(huì)被運(yùn)行。

在if/unless屬性中只能指定一個(gè)特性，如果想指定多種情況，可以通過依賴目標(biāo)來計(jì)算這種檢查結(jié)果。

<target name="myTarget" depends="myTarget.check" if="myTarget.run">
<echo>Files foo.txt and bar.txt are present.</echo>
</target>
<target name="myTarget.check">
<condition property="myTarget.run">
<and>
<available file="foo.txt"/>
<available file="bar.txt"/>
</and>
</condition>
</target>

如果不存在if和unless屬性，目標(biāo)總是會(huì)被執(zhí)行。

Important: if和unless屬性只是讓使用了這二個(gè)屬性的目標(biāo)執(zhí)行或不執(zhí)行，而不能控制目標(biāo)依賴的目標(biāo)的執(zhí)行。

可選的description屬性能對目標(biāo)進(jìn)行描述，可以用-projecthelp選項(xiàng)查看，沒有Description的目標(biāo)不會(huì)被選項(xiàng)令列出來，除非使用-verbose或-debug選項(xiàng)。

在其它目標(biāo)依賴的初始化目標(biāo)(initialization target)中放置 tstamp 是一個(gè)好的實(shí)踐，確保這個(gè)目標(biāo)總是第一個(gè)被執(zhí)行的，在這本手冊中，大多數(shù)的初始化目標(biāo)都命名叫“init”。

如果設(shè)置了依賴目標(biāo)和if/unless屬性，依賴的屬性會(huì)先執(zhí)行。

一個(gè)目標(biāo)（target）有以下屬性。

A target name can be any alphanumeric string valid in the encoding of the XML file. The empty string "" is in this set, as is comma "," and space " ". Please avoid using these, as they will not be supported in future Ant versions because of all the confusion they cause. IDE support of unusual target names, or any target name containing spaces, varies with the IDE.

Targets beginning with a hyphen such as "-restart" are valid, and can be used to name targets that should not be called directly from the command line.

Tasks

A task is a piece of code that can be executed.

A task can have multiple attributes (or arguments, if you prefer). The value of an attribute might contain references to a property. These references will be resolved before the task is executed.

Tasks have a common structure:

<name attribute1="value1" attribute2="value2" ... />

where name is the name of the task, attributeN is the attribute name, and valueN is the value for this attribute.

There is a set of built-in tasks, along with a number of optional tasks, but it is also very easy to write your own.

All tasks share a task name attribute. The value of this attribute will be used in the logging messages generated by Ant.

Tasks can be assigned an id attribute:

<taskname id="taskID" ... />

where taskname is the name of the task, and taskID is a unique identifier for this task. You can refer to the corresponding task object in scripts or other tasks via this name. For example, in scripts you could do:

<script ... > task1.setFoo("bar"); </script>

to set the foo attribute of this particular task instance. In another task (written in Java), you can access the instance via project.getReference("task1").

Note¹: If "task1" has not been run yet, then it has not been configured (ie., no attributes have been set), and if it is going to be configured later, anything you've done to the instance may be overwritten.

Note²: Future versions of Ant will most likely not be backward-compatible with this behaviour, since there will likely be no task instances at all, only proxies.

Properties

A project can have a set of properties. These might be set in the buildfile by the property task, or might be set outside Ant. A property has a name and a value; the name is case-sensitive. Properties may be used in the value of task attributes. This is done by placing the property name between "${" and "}" in the attribute value. For example, if there is a "builddir" property with the value "build", then this could be used in an attribute like this: ${builddir}/classes. This is resolved at run-time as build/classes.

In the event you should need to include this construct literally (i.e. without property substitutions), simply "escape" the '$' character by doubling it. To continue the previous example: <echo>$${builddir}=${builddir}</echo>

will echo this message: 
${builddir}=build/classes
 
 
 
 
In order to maintain backward compatibility with older Ant releases, a single '$' character encountered apart from a property-like construct (including a matched pair of french braces) will be interpreted literally; that is, as '$'. The "correct" way to specify this literal character, however, is by using the escaping mechanism unconditionally, so that "$$" is obtained by specifying "$$$$". Mixing the two approaches yields unpredictable results, as "$$$" results in "$$".
Built-in Properties
Ant provides access to all system properties as if they had been defined using a <property> task. For example, ${os.name} expands to the name of the operating system.
For a list of system properties see the Javadoc of System.getProperties. 
In addition, Ant has some built-in properties:
basedir the absolute path of the project's basedir (as set with the basedir attribute of <project>). ant.file the absolute path of the buildfile. ant.version the version of Ant ant.project.name the name of the project that is currently executing; it is set in the name attribute of <project>. ant.java.version the JVM version Ant detected; currently it can hold the values "1.2", "1.3", "1.4" and "1.5". 
 
 
 
There is also another property, but this is set by the launcher script and therefore maybe not set inside IDEs:
ant.home home directory of Ant 
 
 
 

 
<project name="MyProject" default="dist" basedir="."> <description> simple example build file </description> <!-- set global properties for this build --> <property name="src" location="src"/> <property name="build" location="build"/> <property name="dist" location="dist"/> <target name="init"> <!-- Create the time stamp --> <tstamp/> <!-- Create the build directory structure used by compile --> <mkdir dir="${build}"/> </target> <target name="compile" depends="init" description="compile the source " > <!-- Compile the java code from ${src} into ${build} --> <javac srcdir="${src}" destdir="${build}"/> </target> <target name="dist" depends="compile" description="generate the distribution" > <!-- Create the distribution directory --> <mkdir dir="${dist}/lib"/> <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file --> <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/> </target> <target name="clean" description="clean up" > <!-- Delete the ${build} and ${dist} directory trees --> <delete dir="${build}"/> <delete dir="${dist}"/> </target> </project> 
 
Notice that we are declaring properties outside any target. As of Ant 1.6 all tasks can be declared outside targets (earlier version only allowed <property>,<typedef> and <taskdef>). When you do this they are evaluated before any targets are executed. Some tasks will generate build failures if they are used outside of targets as they may cause infinite loops otherwise (<antcall> for example).
We have given some targets descriptions; this causes the projecthelp invocation option to list them as public targets with the descriptions; the other target is internal and not listed. 
Finally, for this target to work the source in the src subdirectory should be stored in a directory tree which matches the package names. Check the <javac> task for details. 

A project can have a set of tokens that might be automatically expanded if found when a file is copied, when the filtering-copy behavior is selected in the tasks that support this. These might be set in the buildfile by the filter task.
Since this can potentially be a very harmful behavior, the tokens in the files must be of the form @token@, where token is the token name that is set in the <filter> task. This token syntax matches the syntax of other build systems that perform such filtering and remains sufficiently orthogonal to most programming and scripting languages, as well as with documentation systems.
Note: If a token with the format @token@ is found in a file, but no filter is associated with that token, no changes take place; therefore, no escaping method is available - but as long as you choose appropriate names for your tokens, this should not cause problems.
Warning: If you copy binary files with filtering turned on, you can corrupt the files. This feature should be used with text files only.
Path-like Structures
You can specify PATH- and CLASSPATH-type references using both ":" and ";" as separator characters. Ant will convert the separator to the correct character of the current operating system.
Wherever path-like values need to be specified, a nested element can be used. This takes the general form of:
<classpath> <pathelement path="${classpath}"/> <pathelement location="lib/helper.jar"/> </classpath> 
 
The location attribute specifies a single file or directory relative to the project's base directory (or an absolute filename), while the path attribute accepts colon- or semicolon-separated lists of locations. The path attribute is intended to be used with predefined paths - in any other case, multiple elements with location attributes should be preferred.
As a shortcut, the <classpath> tag supports path and location attributes of its own, so:
<classpath> <pathelement path="${classpath}"/> </classpath> 
 
can be abbreviated to:
<classpath path="${classpath}"/> 
 
In addition, one or more Resource Collections can be specified as nested elements (these must consist of file-type resources only). Additionally, it should be noted that although resource collections are processed in the order encountered, certain resource collection types such as fileset, dirset and files are undefined in terms of order.
<classpath> <pathelement path="${classpath}"/> <fileset dir="lib"> <include name="**/*.jar"/> </fileset> <pathelement location="classes"/> <dirset dir="${build.dir}"> <include name="apps/**/classes"/> <exclude name="apps/**/*Test*"/> </dirset> <filelist refid="third-party_jars"/> </classpath> 
 
This builds a path that holds the value of ${classpath}, followed by all jar files in the lib directory, the classes directory, all directories named classes under the apps subdirectory of ${build.dir}, except those that have the text Test in their name, and the files specified in the referenced FileList.
If you want to use the same path-like structure for several tasks, you can define them with a <path> element at the same level as targets, and reference them via their id attribute--see References for an example.
A path-like structure can include a reference to another path-like structure (a path being itself a resource collection) via nested <path> elements:
<path id="base.path"> <pathelement path="${classpath}"/> <fileset dir="lib"> <include name="**/*.jar"/> </fileset> <pathelement location="classes"/> </path> <path id="tests.path"> <path refid="base.path"/> <pathelement location="testclasses"/> </path> 
 
The shortcuts previously mentioned for <classpath> are also valid for <path>.For example: 
<path id="base.path"> <pathelement path="${classpath}"/> </path> 
 
can be written as: 
<path id="base.path" path="${classpath}"/> 
 
Command-line Arguments
Several tasks take arguments that will be passed to another process on the command line. To make it easier to specify arguments that contain space characters, nested arg elements can be used.



    

        

            
Attribute
            
Description
            
Required
        
        

            
value
            
a single command-line argument; can contain space characters.
            
Exactly one of these.
        
        

            
file
            
The name of a file as a single command-line argument; will be replaced with the absolute filename of the file.
        
        

            
path
            
A string that will be treated as a path-like string as a single command-line argument; you can use ;or :as path separators and Ant will convert it to the platform's local conventions.
        
        

            
pathref
            
Reference to a path defined elsewhere. Ant will convert it to the platform's local conventions.
        
        

            
line
            
a space-delimited list of command-line arguments.
        
    


It is highly recommended to avoid the line version when possible. Ant will try to split the command line in a way similar to what a (Unix) shell would do, but may create something that is very different from what you expect under some circumstances.
Examples
<arg value="-l -a"/>


is a single command-line argument containing a space character, not separate commands "-l" and "-a".
<arg line="-l -a"/>


This is a command line with two separate arguments, "-l" and "-a".
<arg path="/dir;/dir2:\dir3"/>


is a single command-line argument with the value \dir;\dir2;\dir3 on DOS-based systems and /dir:/dir2:/dir3 on Unix-like systems.
References
Any project element can be assigned an identifier using its id attribute. In most cases the element can subsequently be referenced by specifying the refid attribute on an element of the same type. This can be useful if you are going to replicate the same snippet of XML over and over again--using a <classpath> structure more than once, for example.
The following example:
<project ... > <target ... > <rmic ...> <classpath> <pathelement location="lib/"/> <pathelement path="${java.class.path}/"/> <pathelement path="${additional.path}"/> </classpath> </rmic> </target> <target ... > <javac ...> <classpath> <pathelement location="lib/"/> <pathelement path="${java.class.path}/"/> <pathelement path="${additional.path}"/> </classpath> </javac> </target> </project>


could be rewritten as:
<project ... > <path id="project.class.path"> <pathelement location="lib/"/> <pathelement path="${java.class.path}/"/> <pathelement path="${additional.path}"/> </path> <target ... > <rmic ...> <classpath refid="project.class.path"/> </rmic> </target> <target ... > <javac ...> <classpath refid="project.class.path"/> </javac> </target> </project>


All tasks that use nested elements for PatternSets, FileSets, ZipFileSets or path-like structures accept references to these structures as shown in the examples. Using refid on a task will ordinarily have the same effect (referencing a task already declared), but the user should be aware that the interpretation of this attribute is dependent on the implementation of the element upon which it is specified. Some tasks (the property task is a handy example) deliberately assign a different meaning to refid.
Use of external tasks
Ant supports a plugin mechanism for using third party tasks. For using them you have to do two steps: 

    
place their implementation somewhere where Ant can find them
    
declare them.
    

Don't add anything to the CLASSPATH environment variable - this is often the reason for very obscure errors. Use Ant's own mechanisms for adding libraries: 

    
via command line argument -lib
    
adding to ${user.home}/.ant/lib
    
adding to ${ant.home}/lib
    

For the declaration there are several ways: 

    
declare a single task per using instruction using <taskdef name="taskname" classname="ImplementationClass"/> 

    <taskdef name="for" classname="net.sf.antcontrib.logic.For" /> <for ... />
    
declare a bundle of tasks using a properties-file holding these taskname-ImplementationClass-pairs and <taskdef> 

    <taskdef resource="net/sf/antcontrib/antcontrib.properties" /> <for ... />
    
declare a bundle of tasks using a xml-file holding these taskname-ImplementationClass-pairs and <taskdef> 

    <taskdef resource="net/sf/antcontrib/antlib.xml" /> <for ... />
    
declare a bundle of tasks using a xml-file named antlib.xml, XML-namespace and antlib: protocoll handler 

    <project xmlns:ac="antlib:net.sf.antconrib"/> <ac:for ... />
    

If you need a special function, you should 

    
have a look at this manual, because Ant provides lot of tasks
    
have a look at the external task page in the manual (or better online)
    
have a look at the external task wiki page
    
ask on the Ant user list
    
implement (and share) your own
    

 
Token Filters
 
Example Buildfile