ANT 自动化构建

本文就日常开发中常用到的一些 ant task 作一些说明，假设项目目录层次如下：
[root dir]
   |-build.properties
   |-build.xml
   +--build 由 build 任务生成
   +--db   数据库脚本及相关数据模型
   +--deploy   部暑目录及 war 包
   +--dist   jar 文件 
   --|-doc
     |--api   java doc
     |--test  测试报告
   +--etc   各种配置文件
   --|-lib
     |--core  用过的第三方库文件
     |--ext    测试或构建依赖包
   +--src
   +--test
   +--web   展示层相关文件
把一些常规的变量设置存放于 build.properties 中，这样利于构建文件的重用及常量变更。下面就以任务为单位讲起。

 

1.javac 编译

典型的 ant task 中一般如下设置 javac 任务:

<javac destdir="${build.dir}" target="1.5" source="1.5" debug="true">  
      <src path="${src.dir}" />  
      <classpath refid="classpath" />  
 </javac>

debug (default off) 编译时是否输出调试信息

optimize (default off) 指示编译时是否进行优化 。注意：从 JDK1.3 开始 sun javac 忽略这个标记。

target 指定生成 class 文件的 JVM 版本，一般取决于 ANT 实际运行的 JDK 版本。

fork(default on) 是否使用外部 JDK 编译

failonerror (default true) 编译出现错误时，build 将失败

如果还需要其它的编译参数设置，具体请参考官方文档 Javac 部分，里面有详细说明。

 

2.native2ascii 命令的 ant 支持

在处理 I18N 国际化编码时，非西欧字符集常会碰到一些乱码问题。虽然 JDK 自带了 native2ascii 转换工具，但调用起来不方便，如果使用 ANT 可以事半功倍地处理这个问题。 在 ant 中可以如下定义一个 native2asii 任务：

<native2ascii dest="${build.dir}" encoding="UTF-8" src="${etc.dir}/classes" includes="**/*_zh.properties" />

encoding 本地文件的编码，默认跟 JVM 编码相同

ext 重命名输出文件的扩展名

其它的可参考官网关于 Native2Ascii 的详细说明。

 

3.Junit 任务支持

在项目开发过程中常用到单元或集成测试，单纯依靠手动执行较容易混淆，时间长了很容易忘记，所以初期建立一个自动化任务很重要。ant 对 Junit 的支持已经相当不错了，足够平常测试使用，更重要的是能生成详细的测试报告，很有吸引力。下面是在 ant 中对一个 Junit 任务的定义。

<target name="tests" depends="build,buildtests" description="Run tests">
  <delete dir="${doc.dir}/test" />
  <mkdir dir="${doc.dir}/test" />
  <junit printsummary="on" failureproperty="tests.failed" showoutput="true">
    <classpath refid="classpath" />
    <formatter type="xml" />
    <batchtest todir="${doc.dir}/test">
      <fileset dir="${build.dir}">
        <include name="**/*Tests.*" />
        <exclude name="**/Jdbc*Tests.*" />
      </fileset>
    </batchtest>
  </junit>

  <fail if="tests.failed">
      ***********************************************************
      ****  One or more tests failed!  Check the output ...  ****
      ***********************************************************
  </fail>

  <junitreport todir="${doc.dir}/">
    <fileset dir="${doc.dir}/test">
      <include name="TEST-*.xml" />
    </fileset>
    <report format="frames" todir="${doc.dir}/test/html" />
  </junitreport>
</target>

<junit> ，定义一个junit task
　　- <batchtest> ，位于<junit>中，运行多个TestCase
　　- <test> ，位于<junit>中，运行单个TestCase
　　- <formatter> ，位于<junit>中，定义一个测试结果输出格式
<junitreport> ，定义一个junitreport task
　　- <report> ，位于<junitreport>中，输出一个junit report

 

junit 中的一些属性

printsummary (default no) 为每一个测试案例打印单行统计，可设置的值有on,off 和 withOutAndErr.其中 withOutAndErr 和 on 基本相同，但前者能把测试输出写入到 System.out 和 System.err 中。
fork (default no) 在一个隔离的 VM 中运行测试
haltonerror (default no) 在测试期间如发生错误将停止构建过程
haltonffailure(default no) 如测试失败将停止构建过程
showoutput 测试产生的任何输出将格式化并被发送到系统日志。默认情况下仅格式化输出。

formatter 中几个常用属性
type 预定义有 xml,plain 和 brief 格式，plain 格式会为所有测试案例给出一行概略统计,brief 仅为失败案例给出详细信息，而 xml 可以被转换为 html 文件，但不包含案例中的一些非法 XML 描述。也可以自己定义输出格式，只需实现 org.apache.tools.ant.taskdefs.optional.junit.JUnitResultFormatter 就行。

 

JUnitReport 内嵌元素 report 一些常用属性
format (default frames) 生成报告的格式，必须为 "noframes" 或 "frames"
styledir 定义 stylesheets 的目录

 

关于ANT Junit 任务的其它更多最新信息请查看 ANT 官方文档，请分别参考 JUnit 和 JUnitReport .

 

4. Javadoc API 文档生成

使用 ant 通过 javadoc 工具生成代码文档，在开发中很常见。javadoc 在处理 Java 源文件时会递归扫描符合规则的源文件目录。可以使用通配符来选择包名，来减少冗赘和管理的时间花费。这个任务不像 javac 能根据文件的变更来处理，所以每次运行时所有包都将被处理，辛好这个任务的使用频率不大。这个任务可以运行在所在 JDK 版本中，假使定义的属性高于运行版本将被乎略。下面给个一般定义的 javadoc 任务：

<javadoc classpathref="classpath" packagenames="${javadoc.pkg.name}.*" 
           sourcepath="${src.dir}" charset="${encode}" encoding="${encode}" 
           destdir="${doc.dir}" author="true" version="true" use="true" 
           windowtitle="${name} API">
  <doctitle><![CDATA[<h1>${name}</h1>]]></doctitle>
  <bottom><![CDATA[<i>Copyright©2007 ${organization}. All Rights Reserved.</i>]]></bottom>
  <tag name="todo" scope="all" description="To do:" />
</javadoc>

sourcepath 指定源文件路径
packagenames 逗号分隔包文件清单（带一个终止通配符）
classpathref 通过一个引用指定用户类路径
Use 分页创建类和包
Windowtitle 文档的浏览器窗口标题(文本)
charset 生成文档的跨平台视图字符集
Encoding 源文件编码名称
docencoding 输出文件的编码名称
Version 包含 @version 标签
link 根据给定 URL 创建链接到文档输出
bottom 每页包含的底部描述(html-code)
Doctitle 为首页的包包含一个标题(html-code)
tag 指定客户自定义标签，JDK 需大于等于1.4

 

更多关于 javadoc 的信息，请参考 javadoc task 官方文档。

 

5. manifest Jar 文件信息

打开 Java 的 JAR 文件我们经常可以看到文件中包含着一个META-INF目录，这个目录下会有一些文件，其中必有一个 MANIFEST.MF ，这个文件描述了该Jar文件的很多信息，下面将详细介绍 MANIFEST.MF 文件的内容：

<tstamp>
  <format property="TODAY" pattern="yyyy-MM-dd HH:mm:ss" />
</tstamp>
<manifest file="${deploy.dir}/${name}/META-INF/MANIFEST.MF">
  <attribute name="Built-By" value="${user.name}" />
  <section name="common">
    <attribute name="Specification-Title" value="Springapp example" />
    <attribute name="Specification-Version" value="${version}" />
    <attribute name="Specification-Vendor" value="${organization}" />
    <attribute name="Implementation-Version" 
         value="${jar.name}-${version.num}-b${build.number}" />
    <attribute name="Built-Date" value="${TODAY}" />
  </section>
</manifest>

上面 ant task 任务,首先定义了一个 tstamp 时间模式, 并在 <manifest> 中引用这个定义。接着定义了一些 manifest 的基本信息,<manifest> 标签中可以定义以下属性：
file 创建或更新的文件
mode (default replace)   "update" 或 "replace" 中的一个，
encoding (defaults UTF-8)   更新时读取已存在文件的编码

内嵌 <attribute> 标签属性
name 属性名，须匹配[A-Za-z0-9][A-Za-z0-9-_]*.
value 属性值
内嵌 <section> 可以有 <attribute> 标签属性

下面就一些常见的属性名作下说明
Manifest-Version   用来定义 manifest 文件的版本
Created-By   声明该文件的生成者，一般该属性是由 jar 命令行工具生成
Signature-Version   定义 jar 文件的签名版本
Class-Path   应用程序或者类装载器使用该值来构建内部的类搜索路径
Main-Class 定义 jar 文件的入口类，该类必须是一个可执行的类，一旦定义了该属性即可通过 java -jar x.jar 来运行该jar文件
Implementation-Title   定义了扩展实现的标题
Implementation-Version   定义扩展实现的版本
Implementation-Vendor   定义扩展实现的组织  
Implementation-Vendor-Id   定义扩展实现的组织的标识
Implementation-URL   定义该扩展包的下载地址(URL)
Specification-Title   定义扩展规范的标题
Specification-Version   定义扩展规范的版本
Specification-Vendor   声明了维护该规范的组织
Sealed   定义jar文件是否封存，值可以是 true 或者 false

Jar 构建时会产生如下 MANIFEST.MF 文件信息：

Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7.0
Created-By: 1.5.0_15-b04 (Sun Microsystems Inc.)
Built-By: Janwer

Name: common
Specification-Title: Springapp example
Specification-Version: 1.0
Specification-Vendor: Dematch Info Tech. Co.,Ltd
Implementation-Version: 1-b1
Built-Date: 2007-12-15 11:39:17

 

有关 Manifest 的更详细说明可参考SUN Mainfest 说明, 有关 manifest 任务可参考 ant manifest 说明档。

 

6. sql 任务

通过 JDBC 连接数据库能执行一系列 SQL 语句，也能从其 src 属性中指定 sql 文件读取文本语句。支持;分隔的多语句，也支持语句内的 -- 或 // 注解

<sql driver="${db.driver}" url="${db.url}" userid="${db.user}" password="${db.pw}" 
  onerror="continue" src="db/create_products.sql">
  <classpath refid="classpath" />
</sql>

src 指定SQL文件
encoding sql 文件的编码
onerror (default abort) 当执行sql脚本失败时，可继续( continue ) ,停止( stop ) ,中止( abort )
autocommit (default false) 对于数据库连接是否自动提交

 

如果还要更详细的信息请参考 ant sql 文档。

 

7. taskdef 任务定义

其主要功能是增加一些任务定义到当前项目中。如下定义了一个 tomcat reload 任务：

<path id="catalina-ant-classpath">
<!-- We need the Catalina jars for Tomcat -->
<!--  * for other app servers - check the docs -->
<fileset dir="${appserver.lib}">
  <include name="catalina-ant.jar" />
</fileset>
</path>
<taskdef name="reload" classname="org.apache.catalina.ant.ReloadTask">
  <classpath refid="catalina-ant-classpath" />
</taskdef>

 <taskdef> 任务定义格式基本如上例所示。ant 文档中对它的说明很简短，可见 ant taskdef 官方对其描述。

 

其它的如 jar,war 等都比较简单，这里就不要描述，可参考文档来定义。附件中我给出了个日常使用的简单 build 定义，有兴趣可以看看。但 注意 ：我的使用环境是(eclipse 3.3 + JDK 1.5) ，请根据自己的实际开发环境作相应的变更。