Apache Ant 中文手册

引言

Apache Ant是一个基于Java的编译工具。它从功能上类似于make,但它以克服了make的缺点。

为什么在make, gnumake, nmake, jam这些编译工具后，还要产生一个Ant呢？因为这些编译工具都有一定的限制。Ant的最初开发者在开发跨平台的应用时，发现以前的那些开发工具都有一定的限制。例如make工具，它是基于Shell的，它判断一系列的条件，并像在shell下面那样执行编译命令，这样做的好处的：针对特定的平台（如unix），可以容易的利用这些工具做编译；但同时，这也意味着，你的编译限制在固定的操作系统下，如只能用于unix。

同时，Make文件也有一些先天的缺陷。好多人都会遇到恐怖的tab问题。Ant的最初开发者多次说“我的命令不能执行因为我在tab前面加了一个空格！”。一些工具如Jam一定程序上解决了这个问题，但仍有其它的格式问题。

Ant与从基于命令的那些扩展开来的那些工具不同，Ant是由java类扩展的。不用编写shell命令，而是配置基于XML的文件，形成多个任务的目标配置树。每一个任务都是通过一个实现了一个规定接口的java类来运行的。

ant缺少了一些直接执行shell命令的能力，如find . -name foo -exec rm {}，但它给用户提供了跨平台的能力，可以在任何地方工作。实际上，Ant也提供了命令execute用来执行shell命令,这就是它的<exec>任务，它允许执行基于操作系统的命令。

安装Ant

下载Ant。Ant有两个版本，二进制版本和原代码版本。

要编译和使用Ant，你必须要有一个兼容JAXP的XML解析器。

二进制版本中自己带有了最新的Apache Xerces2 XML解析器。如果你想用不同的兼容JAXP的解析器，你可以移去Ant库目录下的xercesImpl.jar和xml-apis.jar两个文件。你可以要用的解析器放到Ant的库目录下，也可以把jars文件放到系统的类路径中。

在Ant的当前版本中，还需要安装JDK。下面的二进制片版本的安装后的目录结构。

 ant   安装目录

 ant/bin   包含了运行脚本

 ant/lib   ant运行所需的类库

 ant/docs   文档

 ant/etc   一些配置，如何通过任务的xml输出建立详细的报告，

                           移动编译后的文件，忽略错误警告

 在运行前还要做一些设置：

1) 在path路径中加入ant/bin目录；

2) 设置ANT_HOME为安装目录；

3) 通常还要设置JAVA_HOME为JAVA的安装路径。

例如下：

set ANT_HOME=c:\ant

set JAVA_HOME=c:\jdk1.5.1

set PATH=%PATH%;%ANT_HOME%\bin

 使用Ant 
  

1 写一个简单的编译文件
  

Ant的编译文件是写成XML格式的，每一个编译文件包含一个project和至少一个
target。 Targets包含了一些task元素。每一个task元素可以有一个id 属性
(attribute)可以被其它的引用。


2 Projects

 一个projext可以有如下的属性attribute：


  
 
   

    
 
     
attribute
 
     
说明
 
     
是否必须
 
    
 
    
 
     
name
 
     
项目名称
 
     
No
 
    
 
    
 
     
default
 
     
当没有target支持时，缺省使用的target 
 
     
Yes.
 
    
 
    
 
     
basedir
 
     
基目录，其它的目录都是相对于此. 这个attribute可以被"basedir" property 覆盖。当"basedir" property设置后,basedir attribute就不起作用了。如果两者都没有设置，则buildfile本身的父目录作为基目录。 
 
     
No
 
    
 
   
  
 
 根据需要，还可以设定项目的说明，在<description>元素中。

 第一个project可以有一个或多个targets。一个target就是一系列的你要执行的任务组。在运行Ant时， 
你可以选择哪一个任务组被执行。如果没有给出执行的任务组，则project缺省的任务组被执行。



3 Targets




 target可能依赖于其它的target而存在。你可能用一个target用来编译，用
 另一个target且用来布署。只有编译完成后，布署才可执行，这样布署就
 依赖于编译。

 要说明的是，ant的depends attribute只是规定了target之间的前后执行
 关系，并不表示真正的依赖性。

 依赖的次序是按照排列次序从左到右。但如果这些依赖本身之间还有依赖
 关系，也可能在后面的先执行，如下面的例子： 

<target name="A"/>

<target name="B" depends="A"/>

<target name="C" depends="B"/>

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

 如果我们要运行target D。从它的依赖attribute列表上看，可能先执行C，
 然后B，再后是A。其实这是不对的。C依赖于B，B依赖于A。因此是A先执行，
 然是B，然后C，最后是D。
 一个target只执行一次，虽然可能好多的target都依赖于它。如上例中所示。

 Target还可以根据它的attribute的设置情况来判定执行情况。这允许根据
 系统的状况（如java版本，OS，命令行属性定义等等）更好的控制编译过程。
 这就引入if或unless属性(attribute)。
 注意：Ant只是检查属性(attribute)是否被设置，而不查它的值，即使属性
 (attribute)值为空字符串，它仍认为这是一个存在的属性(attribute)。
 例如：

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

 在第一行中，如果module-A-present属性(attribute)被设置，则target执行。
 在第二个中，如果module-A-present属性(attribute)被设置，同target不执行。

 如果没有if或unless属性(attribute)，则目标总会被执行。


 可选的description属性(attribute)可以用来表示一行的target的说明，可以
 在命令行中用-projecthelp参数显示出来。没有description属性(attribute)
 的target被认为是内部的，并不显示出来，除非利用了-verbose或-debug参数。
 初始化target，所有的其它target都依赖于它。通常都位于依赖列表的第一项。
 在这个手册中，大都的初始化targets用init来命名。
Target有如下的属性：



 


  

   
 
    
 
属性(attribute)
 
 
    
 
说明
 
 
    
 
是否必须
 
 
   
 
   
 
    
 
name
 
 
    
 
Target的名字
 
 
    
 
Yes
 
 
   
 
   
 
    
 
depends
 
 
    
 
依赖target列表
 
 
    
 
No
 
 
   
 
   
 
    
 
if
 
 
    
 
要执行target，某属性(attribute)必须要被设置
 
 
    
 
No
 
 
   
 
   
 
    
 
unless
 
 
    
 
要执行target，某属性(attribute)必须不能被设置
 
 
    
 
No
 
 
   
 
   
 
    
 
description
 
 
    
 
有关target功能的简短说明 
 
 
    
 
No
 
 
   
 
  
 

Target命名说明：可以使用任何XML编码支持的字母表中的字符，如空串，逗号，
空格。但最好避免使用它们，为了避免引起歧义，将来版本的Ant不支持这些特殊
的字符。而各种IDE中时target的命名规则，则跟具体的开发厂家相关。
以横线开头的target名，如”-restart”是有效的命名，但不能被用来在命令行
中执行。


4 Tasks


 Task是一段可执行的代码。

 Task可以有多种属性(attribute)（或参数，只要你喜欢），

 属性(attribute)的值可能包含了对属性(attribute)的引用。 这些引用在task执行
 以前要解析开。

Task的通用结构如下：
<name attribute1="value1" attribute2="value2" ... />

name是task的名字，attributeN是属性(attribute)的名字，而valueN则是属性
(attribute)的值。
一些是内建的任务，而另一些是可选的任务，用户可自由定义。

所有的tasks都有共享task名字，属性(attribute)值将会在ant生成消息时用到。
Task可以指定一个id属性(attribute)：<taskname id="taskID" ... />
Taskname是task的名字，taskID是一个独一无二的标识。你可以在脚本程序或
其它的task中通过这个名字引用相应的task对象。例如：
 <script ... >

 task1.setFoo("bar");

 </script>
这样可以task1的Foo属性值为bar；而在java程序中，则通过project.getReference
("task1")访问task1实例。


5 Properties


项目可以有一系列的属性（property）。这些可能在编译文件通过property任务
（task）设置，或可能在Ant外设置。一个属性（property）由名字和值对应起来。
名字是大小写敏感的。属性（property）可以用在task的(attribute)中。能够在
”{property名}”的方式进行引用。例如，如果有一个builddir属性
（property），值为build，则在属性(attribute)中可以这样用：${builddir}/classes。
在运行时，它被转换成build/classes。

内建的Properties
Ant提供了所有的系统属性的访问就像这些系统属性（property）已经定义在
<property>任务中一样。
例如：${os.name}表示操作系统的名称。
下面列出了一些内建属性（property）：

         basedir 项目的绝对路径 （就像在<project>的basedir属性中定义中的一样）

     ant.file 编译文件的绝对路径

     ant.version Ant的版本

     ant.project.name 正在执行的项目的名字，（就像在<project>的name属性中设置的那样）.

         ant.java.version JVM的版本，其值可能是"1.1", "1.2", "1.3" and "1.4".


 编译文件的例子：

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

上面，我们把属性（property）定义在任何target的外部，<property>，
<typedef>和<taskdef>这些task是特殊的task，可以在任何的target外部定义。
这样做时，它们会在任何target执行前被执行。其它任何的task不能target目录
外定义。
 上面一些target给了description，这样，在使用projecthelp选项时，会列出
 这些公共的targets，而那些没有description的target则被认为是内部的，
 并不显示。
最后，要使target工作，则source子目录要存在相应的位置。

 注： 英文中有两个单词都是属性attribute, property,这里不好区分。因此，
 实际翻译时，把原文的这两个单词也写了出来。