Ant基本使用指南

<!----><!----><!---->  <!---->

在学习 struts+spring+hibernate, 尤其是 Appfuse 的过程中大量涉及到 ant 的使用，因此我觉得有必要对 ant 做个比较深入的学习，以下是在学习过程中搜集的材料。比较详细，很适合没有接触过 ant 的初学者。

Ant 基本使用指南

1 Ant 是什么？

Apache Ant 是一个基于 Java 的生成工具。

生成工具在软件开发中用来将源代码和其他输入文件转换为可执行文件的形式（也有可能转换为可安装的产品映像形式）。随着应用程序的生成过程变得更加复杂，确保在每次生成期间都使用精确相同的生成步骤，同时实现尽可能多的自动化，以便及时产生一致的生成版本

2 下载、安装 Ant

安装 Ant

下载 .zip 文件，解压缩到 c:\ant1.3( 后面引用为 %ANT_HOME%)

 

2.1 在你运行 Ant 之前需要做一些配置工作。

· 将 bin 目录加入 PATH 环境变量。

· 设定 ANT_HOME 环境变量，指向你安装 Ant 的目录。在一些 OS 上， Ant 的脚本可以猜测 ANT_HOME （ Unix 和 Windos NT/2000 ）－但最好不要依赖这一特性。

· 可选地，设定 JAVA_HOME 环境变量（参考下面的高级小节），该变量应该指向你安装 JDK 的目录。

注意：不要将 Ant 的 ant.jar 文件放到 JDK/JRE 的 lib/ext 目录下。 Ant 是个应用程序，而 lib/ext 目录是为 JDK 扩展使用的（如 JCE ， JSSE 扩展）。而且通过扩展装入的类会有安全方面的限制。

2.2 运行 Ant

运行 Ant 非常简单，当你正确地安装 Ant 后，只要输入 ant 就可以了。

 

没有指定任何参数时， Ant 会在当前目录下查询 build.xml 文件。如果找到了就用该文件作为 buildfile 。如果你用 -find 选项。 Ant 就会在上级目录中寻找 buildfile ，直至到达文件系统的根。要想让 Ant 使用其他的 buildfile ，可以用参数 -buildfile file ，这里 file 指定了你想使用的 buildfile 。

 

可以指定执行一个或多个 target 。当省略 target 时， Ant 使用标签 <project> 的 default 属性所指定的 target 。

 

 

命令行选项总结：

ant [options] [target [target2 [target3] ...]]

Options:

-help print this message

-projecthelp print project help information

-version print the version information and exit

-quiet be extra quiet

-verbose be extra verbose

-debug print debugging information

-emacs produce logging information without adornments

-logfile file use given file for log output

-logger classname the class that is to perform logging

-listener classname add an instance of class as a project listener

-buildfile file use specified buildfile

-find file search for buildfile towards the root of the filesystem and use the first one found

-Dproperty=value set property to value

Ant 命令行参考
从命令行调用 Ant 的语法如下所示：
ant [option [option...]] [target [target...]]
option := {-help
|-projecthelp
|-version
|-quiet
|-verbose
|-debug
|-emacs
|-logfile filename
|-logger classname
|-listener classname
|-buildfile filename
|-Dproperty=value
|-find filename}
语法元素说明如下：
-help
显示描述 Ant 命令及其选项的帮助信息。
-projecthelp
显示包含在构建文件中的、所有用户编写的帮助文档。即为各个 <target>
中 description 属性的文本，以及包含在 <description> 元素中的任何文
本。将有 description 属性的目标列为主目标（ “Main target” ），没有此属
性的目标则列为子目标（ “Subtarget” ）。
-version
要求 Ant 显示其版本信息，然后退出。
-quiet
抑制并非由构建文件中的 echo 任务所产生的大多数消息。
-verbose
显示构建过程中每个操作的详细消息。此选项与 -debug 选项只能选其一。
-debug
显示 Ant 和任务开发人员已经标志为调试消息的消息。此选项与 -verbose 只
能选其一。
-emacs
对日志消息进行格式化，使它们能够很容易地由 Emacs 的 shell 模式（ shellmode ）
所解析；也就是说，打印任务事件，但并不缩排，在其之前也没有
[taskname] 。
-logfile filename
将日志输出重定向到指定文件。
-logger classname
指定一个类来处理 Ant 的日志记录。所指定的类必须实现了 org.apache.
tools.ant.BuildLogger 接口。
-listener classname
为 Ant 声明一个监听类，并增加到其监听者列表中。在 Ant 与 IDE 或其他 Java
程序集成时，此选项非常有用。可以阅读第六章以了解有关监听者的更多信
息。必须将所指定的监听类编写为可以处理 Ant 的构建消息接发。
-buildfile filename
指定 Ant 需要处理的构建文件。默认的构建文件为 build.xml 。
-Dproperty=value
在命令行上定义一个特性名－值对。
-find filename
指定 Ant 应当处理的构建文件。与 -buildfile 选项不同，如果所指定文件在当
前目录中未找到， -find 就要求 Ant 在其父目录中再进行搜索。这种搜索会继
续在其祖先目录中进行，直至达到文件系统的根为止，在此如果文件还未找
到，则构建失败。
构建文件轮廓
下面是一个通用的构建文件，它很适合作为一个模板。构建文件包括 <project>
元素，以及其中嵌套的 <target> 、 <property> 和 <path> 元素。
<project default="all">
<property name="a.property" value="a value"/>
<property name="b.property" value="b value"/>
<path id="a.path">
<pathelement location="${java.home}/jre/lib/rt.jar"/>
</path>
<target name="all">
<javac srcdir=".">
<classpath refid="a.path"/>
</javac>
</target>
</project>

关于构建文件有几点需要记住：
● 所有构建文件都要有 <project> 元素，而且至少有一个 <target> 元素。
● 对于 <project> 元素的 default 属性并没有默认值。
● 构建文件并不一定要被命名为 build.xml 。不过 build.xml 是 Ant 要搜索的默
认文件名。
● 每个构建文件只能有一个 <project> 元素。

 

 

例子

ant

使用当前目录下的 build.xml 运行 Ant ，执行缺省的 target 。

ant -buildfile test.xml

使用当前目录下的 test.xml 运行 Ant ，执行缺省的 target 。

ant -buildfile test.xml dist

使用当前目录下的 test.xml 运行 Ant ，执行一个叫做 dist 的 target 。

ant -buildfile test.xml -Dbuild=build/classes dist

使用当前目录下的 test.xml 运行 Ant ，执行一个叫做 dist 的 target ，并设定 build 属性的值为 build/classes 。

 

3 编写 build.xml

Ant 的 buildfile 是用 XML 写的。每个 buildfile 含有一个 project 。

 

buildfile 中每个 task 元素可以有一个 id 属性，可以用这个 id 值引用指定的任务。这个值必须是唯一的。（详情请参考下面的 Task 小节）

 

3.1Projects

 

project 有下面的属性：

AttributeDescriptionRequired

name 项目名称 .No

default 当没有指定 target 时使用的缺省 targetYes

basedir 用于计算所有其他路径的基路径。该属性可以被 basedir property 覆盖。当覆盖时，该属性被忽略。如果属性和 basedir property 都没有设定，就使用 buildfile 文件的父目录。 No

项目的描述以一个顶级的 <description> 元素的形式出现（参看 description 小节）。

 

一个项目可以定义一个或多个 target 。一个 target 是一系列你想要执行的。执行 Ant 时，你可以选择执行那个 target 。当没有给定 target 时，使用 project 的 default 属性所确定的 target 。

 

3.2Targets

 

一个 target 可以依赖于其他的 target 。例如，你可能会有一个 target 用于编译程序，一个 target 用于生成可执行文件。你在生成可执行文件之前必须先编译通过，所以生成可执行文件的 target 依赖于编译 target 。 Ant 会处理这种依赖关系。

 

然而，应当注意到， Ant 的 depends 属性只指定了 target 应该被执行的顺序－如果被依赖的 target 无法运行，这种 depends 对于指定了依赖关系的 target 就没有影响。

 

Ant 会依照 depends 属性中 target 出现的顺序（从左到右）依次执行每个 target 。然而，要记住的是只要某个 target 依赖于一个 target ，后者就会被先执行。

<target name="A"/>

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

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

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

假定我们要执行 target D 。从它的依赖属性来看，你可能认为先执行 C ，然后 B ，最后 A 被执行。错了， C 依赖于 B ， B 依赖于 A ，所以先执行 A ，然后 B ，然后 C ，最后 D 被执行。

 

一个 target 只能被执行一次，即时有多个 target 依赖于它（看上面的例子）。

 

如果（或如果不）某些属性被设定，才执行某个 target 。这样，允许根据系统的状态（ java version, OS, 命令行属性定义等等）来更好地控制 build 的过程。要想让一个 target 这样做，你就应该在 target 元素中，加入 if （或 unless ）属性，带上 target 因该有所判断的属性。例如：

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

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

如果没有 if 或 unless 属性， target 总会被执行。

 

可选的 description 属性可用来提供关于 target 的一行描述，这些描述可由 -projecthelp 命令行选项输出。

 

将你的 tstamp task 在一个所谓的初始化 target 是很好的做法，其他的 target 依赖这个初始化 target 。要确保初始化 target 是出现在其他 target 依赖表中的第一个 target 。在本手册中大多数的初始化 target 的名字是 "init" 。

 

target 有下面的属性：

AttributeDescriptionRequired

nametarget 的名字 Yes

depends 用逗号分隔的 target 的名字列表，也就是依赖表。 No

if 执行 target 所需要设定的属性名。 No

unless 执行 target 需要清除设定的属性名。 No

description 关于 target 功能的简短描述。 No

 

3.3Tasks

 

一个 task 是一段可执行的代码。

 

一个 task 可以有多个属性（如果你愿意的话，可以将其称之为变量）。属性只可能包含对 property 的引用。这些引用会在 task 执行前被解析。

 

下面是 Task 的一般构造形式：

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

这里 name 是 task 的名字， attributeN 是属性名， valueN 是属性值。

 

有一套内置的（ built-in ） task ，以及一些可选 task ，但你也可以编写自己的 task 。

 

所有的 task 都有一个 task 名字属性。 Ant 用属性值来产生日志信息。

 

可以给 task 赋一个 id 属性：

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

这里 taskname 是 task 的名字，而 taskID 是这个 task 的唯一标识符。通过这个标识符，你可以在脚本中引用相应的 task 。例如，在脚本中你可以这样：

<script ... >

task1.setFoo("bar");

</script>

设定某个 task 实例的 foo 属性。在另一个 task 中（用 java 编写），你可以利用下面的语句存取相应的实例。

project.getReference("task1").

注意 1 ：如果 task1 还没有运行，就不会被生效（例如：不设定属性），如果你在随后配置它，你所作的一切都会被覆盖。

 

注意 2 ：未来的 Ant 版本可能不会兼容这里所提的属性，因为很有可能根本没有 task 实例，只有 proxies 。

 

3.4Properties

 

一个 project 可以有很多的 properties 。可以在 buildfile 中用 property task 来设定，或在 Ant 之外设定。一个 property 有一个名字和一个值。 property 可用于 task 的属性值。这是通过将属性名放在 "{" 和 "}" 之间并放在属性值的位置来实现的。例如如果有一个 property builddir 的值是 "build" ，这个 property 就可用于属性值： {builddir}/classes 。这个值就可被解析为 build/classes 。

内置属性

 

如果你使用了 <property> task 定义了所有的系统属性， Ant 允许你使用这些属性。例如， {os.name} 对应操作系统的名字。

 

要想得到系统属性的列表可参考 the Javadoc of System.getProperties 。

 

除了 Java 的系统属性， Ant