常用Ant 的元素详细介绍

常用Ant 的元素详细介绍

按照元素功能的不同我们又把这些元素分为两大类：
Tasks ：使用中我们也是使用 Tasks 的元素比较多
Types：主要是一个文件操作的功能。

1.tasks

元素	作用	属性
project	ant中一个project，project可以有多个target	name,default,basedir
target	target（执行单元/任务），多个target之间有depends关系	name,depends,if,unless,description
property	参量或者参数的定义，project 的属性可以通过 property 元素来设定 ,也可在 Ant 之外设定。若要在外部引入某文件，例如 build.properties 文件(<property file=“build.properties”/> )
copy	copy 将文件或者 FileSet 复制到一个新的文件或者目录	file,todir,tofile
delect	删除	dir,file,fileset
mkdir	创建目录	dir
move	移动文件或目录	file,todir,tofile
echo	根据日志或监控器的级别输出信息	message、 file 、append 和 level
jar	用来生成一个jar文件	destfile,basedir,includes,exchudes,compress
javadoc
environment

属性介绍：
例子：

远程的 copy

sshexec 连接到服务器，接下来就可以使用 scp 命令复制了

mainfest 是jar包中的 MEAT-INF 中的 MANIFEST.MF 中的文件内容。
javadoc

javadoc 是一个非常复杂的 task，一共有50多个 attribute，幸好只有四个 attribute 是必须的，那就是 sourcepath、sourcefiles、sourcepathref 和 destdir，对于sourcepath、sourcefiles 和 sourcepathref 只需要指定其中一个，如果都没有指定，那么必须提供嵌套的 sourcepath、 fileset 或者 packageset，从字面上很容易理解 sourcepath、sourcefiles、sourcepathref 是源文件所在的目录，而 destdir 是生成的 javadoc API 所在的目录。
下面是一些我们常用的 attribute：
attribute description
sourcepath 源文件目录，可用嵌套的 sourcepath 代替
sourcefiles 逗号分割的文件列表，可用嵌套的 source 代替
destdir 输出文件所在的目录，通常我们习惯将结果保存在 doc/api 下
packagenames 逗号分割的 java 包列表，可用嵌套的 package 代替
packageList 指定一个文件，文件内容是 javadoc 需要处理的包的列表
classpath 指定 class 文件所在的位置，可用嵌套的 classpath 代替
use 生成 class 和 package 的用法
version 生成 @version 的信息
author 生成 @author 的信息
windowtitle 生成的 doc 的浏览的窗口的标题
header 每一页的 header 信息
footer 每一页的 footer 信息
bottom 每一页的 bottom 信息
nodeprecated 不生成 @deprecated 的信息

常见的可以嵌套的参数如下：packageset、fileset、package、excludepackage、source、doctitle、header、footer 和 bottom，它们的具体用法请参考官方文档。
javadoc 的 sourcepath、classpath 和 bootclasspath 是 path-like 机构，也就是完全可以用嵌套的 sourcepath、 classpath 和 bootclasspath 来代替。

<javadoc packagenames="com.dummy.test.*"
           sourcepath="src"
           defaultexcludes="yes"
           destdir="docs/api"
           author="true"
           version="true"
           use="true"
           windowtitle="Test API">
           <classpath refid="compile.classpath"/>
</javadoc>
 
<javadoc author="true"
         destdir="{javadoc.dir}"
         packagenames="org.example.helloworld.*"
         sourcepath="src"
         use="true"
         version="true"
         windowtitle="Helloworld api spec"
         private="true">
         <classpath refid="compile.classpath"/>
</javadoc>
 
<javadoc destdir="docs/api" author="true" version="true" use="true" windowtitle="Test API">
    <packageset dir="src" defaultexcludes="yes">
        <include name="com/dummy/test/**" />
        <exclude name="com/dummy/test/doc-files/**"/>
    </packageset>
 
    <doctitle>
        <![CDATA[<h1>Test</h1>]]>
    </doctitle>
    <bottom>
        <![CDATA[<i>Copyright &#169; 2000 Dummy Corp. All Rights Reserved.</i>]]>
        </bottom>
    <tag name="todo" scope="all" description="To do:" />
    <group title="Group 1 Packages" packages="com.dummy.test.a*"/>
    <group title="Group 2 Packages" packages="com.dummy.test.b*:com.dummy.test.c*"/>
    <link offline="true" href="::URL::http://java.sun.com/ products/jdk/1.2/docs/api/" packagelistLoc="C:/tmp"/>
    <link href="::URL::http://developer.java.sun.com/developer/products/xml/docs/api/"/> 
  </javadoc>
11. environment

由Ant构建文件调用的外部命令或程序，env 元素制定了哪些环境变量要传递给正在执行的系统命令，env 元素可以接受以下属性。

    file表示环境变量值的文件名。此文件名要被转换位一个绝对路径。
    path表示环境变量的路径。Ant会将它转换为一个本地约定。
    value 表示环境变量的一个直接变量。
    key 表示环境变量名。

注意 file、path 或 value 只能取一个，在 property 部分我们已经介绍了该元素的功能，这里就不重复了。
12. arg

由Ant构建文件调用的程序，可以通过 arg 元素向其传递命令行参数，如 apply、exec 和 java 任务均可接受嵌套 arg 元素，可以为各自的过程调用指定参数。以下是 arg 的所有属性。

    values 是一个命令参数。如果参数中有空格，但又想将它作为单独一个值，则使用此属性。
    file 表示一个参数的文件名。在构建文件中，此文件名相对于当前的工作目录。
    line 表示用空格分隔的多个参数列表。
    表示路径，一个作为单个命令行变量的 path-like 的字符串；或作为分隔符，Ant会将其转变为特定平台的分隔符。
    pathref 引用的 path （使用 path 元素节点定义 path）的id
    prefix 前缀
    suffix 后缀

例子

<arg value="-l -a"/> 

    1

    1

是一个含有空格的单个的命令行变量。

<arg line="-l -a"/> 

    1

    1

是两个空格分隔的命令行变量。

<arg path="/dir;/dir2:\dir3"/> 

    1

    1

是一个命令行变量，其值在DOS系统上为\dir;\dir2;\dir3；在Unix系统上为/dir:/dir2:/dir3 。
13. javac

javac 使我们再熟悉不过的了，其功能就是把 java 程序编译成 class 文件，我们来看看在 Ant 中它又焕发可什么样的光彩。
先看一个基本的 javac 命令：

javac -d build/classes -classpath %CLASSPATH%;lib/outlib.jar -sourcepath src -g

    1

    1

该标签用于编译一个或一组java文件，其属性如下。

    srcdir表示源程序的目录，相当于 javac 命令的 -sourcepath 参数，srcdir 也是 javac 的隐式 implicit 的 FileSet，因此 srcdir 支持 FileSet 的所有特征。
    destdir表示 classes 文件的输出目录，相当于 javac 命令的 -d 参数。
    include表示被编译的文件的模式。
    excludes表示被排除的文件的模式。
    classpath表示所使用的类路径。
    debug表示包含的调试信息，debug=”yes” 相当于 javac 命令的 -g 参数，debug=”no” 相当于 javac 命令的 -g:none 参数。
    optimize表示是否使用优化，默认是 off，optimize=”on” 相当于 javac 命令的 -o 参数。
    verbose 表示提供详细的输出信息。
    fileonerror如果编译错误，build 是否继续，默认是 true。
    deprecation 输出对于那些使用了 deprecation 的API的源文件的位置，默认是 off，deprecation=”on” 相当于 javac 命令的 -deprecation 参数。
    fork 使用外部的JDK编译器来运行 javac，默认是 no，采用 yes 可以取得更好的效率，当然对机器的要求也高。

示例：

    <javac srcdir="${src}" destdir="${dest}"/>
    <!-- 设置jvm内存
    <javac srcdir="src" fork="true"/> 
    <javac srcdir="src" fork="true" executable="d:\sdk141\bin\javac" 
    memoryMaximumSize="128m"/> 
    -->
     
    <javac destdir="{build.classes.dir}"
           debug="{build.debug}"
           includeAntRuntime="yes"
           srcdir="{sirc.dir}">
           <classpath refid="compile.classpath"/>
           <include name="**/*.java"/>
    </javac>
    

<?xml version="1.0"?>
<project name="javacTest" default="compile" basedir=".">
    <target name="clean" description="删除编译后产生的目录及文件">
        <delete dir="build" />
    </target>
 
    <target name="compile" depends="clean" description="编译源文件">
        <mkdir dir="build/classes" />
        <javac srcdir="src" destdir="build/classes" />
    </target>
</project>

14. java

java 我们也是很熟悉，它就是用来执行编译生成的.class文件，其属性如下：

classname 表示将执行的类名。
jar表示包含该类的JAR文件名。
classpath所表示用到的类路径。
fork表示在一个新的虚拟机中运行该类。
failonerror表示当出现错误时自动停止。
output 表示输出文件。
append表示追加或者覆盖默认文件。

示例

<java classname="com.hoo.test.HelloWorld" classpath="${hello_jar}"/>

编译并运行JAVA程序

<?xml version="1.0"?>
<project name="javaTest" default="run" basedir=".">
    <target name="clean" description="清除目录">
        <delete dir="build" />
    </target>
 
    <target name="compile" depends="clean" description="编译">
        <mkdir dir="build/classes" />
        <javac srcdir="src" destdir="build/classes" />
    </target>
 
    <target name="run" depends="compile" description="运行">
        <java classname="AntTest">
            <classpath>
                <pathelement path="build/classes" />
            </classpath>
        </java>
    </target>
</project>

Types

filelist

filelist 是一个支持命名的文件列表的数据类型，包含在一个 filelist 类型中的文件不一定是存在的文件。以下是其所有的属性：

dir是用于计算绝对文件名的目录。
files 是用逗号分隔的文件名列表。
refid 是对某处定义的一个 filelist 的引用。 

注意 dir 和 files 都是必要的，除非指定了 refid (这种情况下，dir 和 files 都不允许使用)。

示例

文件集合 ${doc.src}/foo.xml和${doc.src}/bar.xml. 这些文件也许还是不存在的文件.
<filelist id="docfiles" dir="${doc.src}" files="foo.xml bar.xml"/> 
 
<filelist refid="docfiles"/> 
 
<filelist id="docfiles" dir="${doc.src}">
    <file name="foo.xml"/>
    <file name="bar.xml"/>
</filelist>

fileset

fileset 数据类型定义了一组文件，并通常表示为 fileset 元素。不过，许多 ant 任务构建成了隐式的 fileset,这说明他们支持所有的 fileset 属性和嵌套元素，与 filelist 不同的是 fileset 下的文件必须存在。以下为 fileset 的属性列表：

dir表示 fileset 的基目录。
casesensitive的值如果为 false，那么匹配文件名时，fileset 不是区分大小写的，其默认值为 true。
defaultexcludes 用来确定是否使用默认的排除模式，默认为 true。
excludes 是用逗号分隔的需要派出的文件模式列表。
excludesfile 表示每行包含一个排除模式的文件的文件名。
includes 是用逗号分隔的，需要包含的文件模式列表。
includesfile 表示每行包括一个包含模式的文件名。

示例

 <fileset id="lib.runtime" dir="${lib.path}/runtime">
        <include name="**/*.jar"/>
        <include name="**/*.so"/>
        <include name="**/*.dll"/>
    </fileset>
     
    <fileset id="lib.container" dir="${lib.path}/container">
        <include name="**/*.jar"/>
    </fileset>
     
    <fileset id="lib.extras" dir="${lib.path}">
        <include name="test/**/*.jar"/>
    </fileset>

下面看一下 fileset 和 patternset 的简单使用：

  <fileset id="sources" dir="src"
        includes="**/*.java"
        excludes="**/test/**/*.java">
    </fileset>

等价于

<fileset id="sources" dir="src">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/test/**/*.java"/>
    </patternset>
</fileset>

等价于

    <patternset id="non.test.source">
        <include name="**/*.java"/>
        <exclude name="**/test/**/*.java"/>
    </patternset>
    <fileset id="sources" dir="src">
        <patternset refid="non.test.source"/>
    </fileset>

filterset

filterset 定义了一组过滤器，这些过滤器将在文件移动或复制时完成文件的文本替换。
主要属性如下：

begintoken 表示嵌套过滤器所搜索的记号，这是标识其开始的字符串。
endtoken 表示嵌套过滤器所搜索的记号这是标识其结束的字符串。
id 是过滤器的唯一标志符。
refid 是对构建文件中某处定义一个过滤器的引用。

示例

  <!-- 将目标文件build.dir目录中的version.txt文件内容中的@DATE@替换成TODAY当前日期的值，并把替换后的文件存放在dist.dir目录中 -->
    <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
        <filterset>
            <filter token="DATE" value="${TODAY}"/>
        </filterset>
    </copy>
     
    <!-- 自定义变量的格式 -->
    <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
        <!-- 从version.txt中的%位置开始搜索，到*位置结束，进行替换内容中的@DATE@替换成TODAY当前日期的值-->
        <filterset begintoken="%" endtoken="*">
            <filter token="DATE" value="${TODAY}"/>
        </filterset>
    </copy>
     
    <!-- 使用外部的过滤定义文件 -->
    <copy toDir="${dist.dir}/docs">
        <fileset dir="${build.dir}/docs">
            <include name="**/*.html">
        </fileset>
        <filterset begintoken="%" endtoken="*">
            <!-- 过来文件从外部引入，过来的属性和值配置在dist.properties文件中 --> 
            <filtersfile file="${user.dir}/dist.properties"/>
        </filterset>
    </copy>
     
    <!-- 使用引用方式，重复利用过滤集 -->
    <filterset id="myFilterSet" begintoken="%" endtoken="*">
        <filter token="DATE" value="${TODAY}"/>
    </filterset>
     
    <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
        <filterset refid="myFilterSet"/>
    </copy>

path

path 元素用来表示一个类路径，不过它还可以用于表示其他的路径。在用作几个属性时，路经中的各项用分号或冒号隔开。在构建的时候，此分隔符将代替当前平台中所有的路径分隔符，其拥有的属性如下:

location 表示一个文件或目录。Ant在内部将此扩展为一个绝对路径。
refid 是对当前构建文件中某处定义的一个 path 的引用。
path表示一个文件或路径名列表。

path 支持的嵌套元素如下：

0..n 个嵌套的 pathelement， pathlelement 定义在路径下的一个或者多个文件，pathelement 支持 location 和 path 这两个 attribute，用法和 path 元素一样；
0..n 个嵌套的 fileset ；
0..n 个嵌套的 path； 

示例

 <path id="buildpath">
        <fileset refid="lib.runtime"/>
        <fileset refid="lib.container"/>
        <fileset refid="lib.extras"/>
    </path>
     
    <path id="src.paths">
        <fileset id="srcs" dir=".">
            <include name="src/**/*.java"/>
        </fileset>
    </path>
     
    <path>
        <pathelement location="{libdir}/servlet.jar"/>
        <pathelement location="{libdir}/logging.jar"/>
        <pathelement path="{builddir}"/>
        <pathelement path="{utilpath}"/>
    </path>

path 最常用的是 classpath 这个形式，但是也用于其他用途。

  <classpath>
        <pathelement path="{builddir}"/>
    </classpath>

等价于

<classpath path="{builddir}"/>
 
<classpath>
    <pathelement path="{builddir1}"/>
    <pathelement path="{builddir2}"/>
</classpath>

等价于

<classpath path="{builddir1};{builddir2}"/>