61、Ant任务参考：全面指南与操作详解

Ant任务参考：全面指南与操作详解

1. 引言

Ant的发行版附带了丰富的HTML格式文档，涵盖每个任务的详细信息。不过，为了让读者在阅读相关资料时能有更便捷的快速参考，我们整理了这份简洁的任务参考。它能让你在阅读时随时查阅，甚至在离开电脑时也能翻阅，快速了解任务的有效属性和元素。

2. 参考约定

任务以特定格式列出，如 <task-name> 任务简要描述 。属性按字母顺序排列，随后是子元素，子元素也按字母顺序排列，并用尖括号 < > 括起来。所有属性都有类型说明，元素类型仅针对常见数据类型提供。布尔属性在值为 on 、 yes 或 true 时视为 true ，其他值视为 false 。路径属性接受与平台无关的路径，使用冒号 : 或分号 ; 作为分隔符，正斜杠 / 或反斜杠 \ 作为目录分隔符。部分任务基于 MatchingTask 父类，这些任务用星号 * 表示，支持额外的属性和子元素。

3. 通用任务属性

所有任务都支持三个通用属性：
| 属性 | 描述 | 类型 |
| ---- | ---- | ---- |
| id | 唯一的任务实例标识符，可用于从 <script> 引用任务 | String |
| taskname | 任务的别名，用于日志记录 | String |
| description | 用于注释的字段，Ant不使用或显示 | String |

3.1 *MatchingTask

带有星号 * 的任务还支持以下属性和子元素，这些任务操作隐式文件集，通常有一个表示文件集基目录的属性。
- 属性 ：
- casesensitive ：文件系统的大小写敏感性，布尔类型。
- defaultexcludes ：若为 false ，关闭默认排除项，布尔类型。
- excludes ：用逗号或空格分隔的要排除的文件模式列表，字符串类型。
- excludesfile ：文件名，文件的每行视为一个排除模式，文件类型。
- followsymlinks ：指示是否跟随符号链接，布尔类型。
- includes ：用逗号或空格分隔的要包含的文件模式列表，字符串类型。
- includesfile ：文件名，文件的每行视为一个包含模式，文件类型。
- 子元素 ：
- <and> ：选择所有包含的选择器都选择的文件，选择器类型。
- <contains> ：将选择的文件限制为仅包含特定字符串的文件，选择器类型。
- <custom> ：添加自定义选择器，选择器类型。
- <date> ：根据最后修改时间戳选择文件，选择器类型。
- <depend> ：选择最后修改日期晚于另一个文件的文件，选择器类型。
- <depth> ：根据文件相对于基目录的目录级别深度选择文件，选择器类型。
- <exclude> ：向排除列表添加单个模式。
- <excludesfile> ：向排除列表添加文件中包含的模式。
- <filename> ：功能类似于 <include> 和 <exclude> 元素，选择器类型。
- <include> ：向包含列表添加单个模式。
- <includesfile> ：向包含列表添加文件中包含的模式。
- <majority> ：如果包含的选择器中大多数也选择该文件，则选择该文件，选择器类型。
- <none> ：选择不被其包含的任何选择器选择的文件，选择器类型。
- <not> ：反转其包含的单个选择器的含义，选择器类型。
- <or> ：选择被其包含的任何一个元素选择的文件，选择器类型。
- <patternset> ：添加模式集，模式集类型。
- <present> ：选择在另一个目录树中有等效文件的文件，选择器类型。
- <selector> ：通过引用添加选择器，选择器类型。
- <size> ：按大小限制选择的文件，选择器类型。

4. Ant的任务

Ant包含众多任务，以下是部分常见任务的详细介绍。

4.1 <ant>

构建子项目。

4.2 <antcall>

调用同一项目中的另一个目标。

4.3 <antlr>

对语法文件调用ANTLR翻译器生成器。
- 属性 ：
- antfile ：要使用的构建文件，字符串类型。
- dir ：用作新Ant项目基目录的目录，文件类型。
- inheritall ：若为 true ，将所有属性传递给新Ant项目，默认 true ，布尔类型。
- inheritrefs ：若为 true ，将所有引用传递给新Ant项目，默认 false ，布尔类型。
- output ：要写入输出的文件名，字符串类型。
- target ：要执行的新Ant项目的目标，字符串类型。
- 子元素 ：
- <property> ：传递给新项目的属性。
- <reference> ：标识要传递到新项目的数据类型的引用元素。

4.4 <antstructure>

从当前已知任务创建Ant的部分DTD。

4.5 <apply>

执行给定命令，将一组文件作为参数提供。
- 属性 ：
- output ：输出文件，文件类型。
- append ：设置输出是追加到现有文件还是覆盖，布尔类型。
- dest ：目标文件要放置的目录，文件类型。
- dir ：进程的工作目录，文件类型。
- executable ：要执行的命令，字符串类型。
- failifexecutionfails ：若程序无法启动，停止构建，布尔类型。
- failonerror ：若命令以非零返回码退出，失败，布尔类型。
- newenvironment ：指定新环境变量时，不传播旧环境，布尔类型。
- os ：命令可执行的操作系统列表，字符串类型。
- output ：进程输出重定向到的文件，文件类型。
- outputproperty ：其值应设置为进程输出的属性名，字符串类型。
- parallel ：若为 true ，仅运行一次命令，将所有文件作为参数追加，布尔类型。
- relative ：设置文件名在命令行上是作为绝对路径还是相对路径传递，布尔类型。
- resultproperty ：用于存储命令返回码的属性名，字符串类型。
- skipemptyfilesets ：若未找到源文件或源文件不比其对应的目标文件新，不运行命令，布尔类型。
- type ：要操作的文件类型，可选 file 、 dir 、 both 。
- vmlauncher ：若为 true ，使用VM启动新进程，否则使用操作系统的shell，布尔类型。
- 子元素 ：
- <arg> ：添加命令行参数。
- <env> ：向启动的进程添加环境变量。
- <fileset> ：要操作的源文件，文件集类型。
- <mapper> ：添加源文件到目标文件的映射，映射器类型。
- <srcfile> ：指示源文件名应放在命令行的位置的标记。
- <targetfile> ：指示目标文件名应放在命令行的位置的标记。

4.6 <available>

若请求的资源在运行时可用，则设置给定属性。
- 属性 ：
- classname ：必须可用才能设置给定属性的类的类名，字符串类型。
- classpath ：搜索类和资源时使用的类路径，路径类型。
- classpathref ：通过引用的类路径，引用类型。
- file ：文件系统中必须存在才能设置给定属性的文件，文件类型。
- filepath ：查找文件时使用的路径，路径类型。
- ignoresystemclasses ：设置搜索类时是否忽略运行时类，仅使用给定类路径，布尔类型。
- property ：若特定资源可用将设置的属性名，字符串类型。
- resource ：设置属性所需的Java资源名，字符串类型。
- type ：所需的文件类型，可选 file 、 dir 。
- value ：若所需资源可用，赋予属性的值，字符串类型。
- 子元素 ：
- <classpath> ：搜索类和资源时使用的类路径，路径类型。
- <filepath> ：搜索文件资源的路径，路径类型。

5. 其他任务简介

除了上述任务，还有许多其他任务，如：
- <basename> ：将指定文件的基名（可选去掉后缀）设置为属性。
- <blgenclient> ：使用EJB JAR文件作为输入，生成Borland应用服务器4.5客户端JAR。
- <buildnumber> ：读取、递增并将构建号写入文件。
- <bunzip2> ：扩展用BZIP2算法压缩的文件。

这些任务都有各自的属性和子元素，以满足不同的需求。例如， <bunzip2> 任务的 src 属性指定要扩展的文件， dest 属性指定目标文件或目录（可选）。

graph LR
    A[Ant任务] --> B[通用任务属性]
    A --> C[*MatchingTask属性和子元素]
    A --> D[具体任务]
    D --> D1[<ant>]
    D --> D2[<antcall>]
    D --> D3[<antlr>]
    D --> D4[<apply>]
    D --> D5[<available>]
    D --> D6[<basename>]
    D --> D7[<blgenclient>]
    D --> D8[<buildnumber>]
    D --> D9[<bunzip2>]

6. 总结

通过本文，我们详细介绍了Ant任务的参考约定、通用任务属性以及众多具体任务。了解这些任务的属性和子元素，能让你在使用Ant进行项目构建和管理时更加得心应手。无论是简单的文件操作，还是复杂的项目构建，Ant都能提供强大的支持。在实际应用中，你可以根据具体需求选择合适的任务，并合理配置其属性和子元素，以实现高效的项目管理和自动化构建。

7. 更多Ant任务详解

7.1 <cab>*

创建CAB存档。
- 属性 ：
| 属性 | 描述 | 类型 |
| ---- | ---- | ---- |
| basedir | 查找要CAB的文件的基目录 | File |
| cabfile | 创建 .cab 文件的名称/位置 | File |
| compress | 若为 true ，压缩文件；否则仅存储 | Boolean |
| options | 设置不直接支持的额外 cabarc 选项 | String |
| verbose | 若为 true ，显示 cabarc 输出 | Boolean |
- 子元素 ：
- <fileset> ：添加要存档的文件集，文件集类型。

7.2 <cccheckin>

使用ClearCase签入文件。
- 属性 ：
- cleartooldir ： cleartool 可执行文件所在的目录，字符串类型。
- comment ：注释字符串，字符串类型。
- commentfile ：指定包含注释的文件，字符串类型。
- identical ：若为 true ，即使文件与原始文件相同也允许签入，布尔类型。
- keepcopy ：若为 true ，保留带有 .keep 扩展名的文件副本，布尔类型。
- nowarn ：若为 true ，抑制警告消息，布尔类型。
- preservetime ：若为 true ，保留修改时间，布尔类型。
- viewpath ：要操作的ClearCase视图中项目的路径，字符串类型。

7.3 <cccheckout>

在ClearCase中签出文件。
- 属性 ：
- branch ：指定签出文件的分支，字符串类型。
- cleartooldir ： cleartool 可执行文件所在的目录，字符串类型。
- comment ：注释字符串，字符串类型。
- commentfile ：指定包含注释的文件，字符串类型。
- nodata ：若为 true ，签出文件但不创建包含其数据的可编辑文件，布尔类型。
- nowarn ：若为 true ，抑制警告消息，布尔类型。
- out ：以不同文件名创建可写文件，字符串类型。
- reserved ：若为 true ，将文件签出为保留状态，布尔类型。
- version ：若为 true ，允许签出非最新版本，布尔类型。
- viewpath ：要操作的ClearCase视图中项目的路径，字符串类型。

7.4 <ccmcheckin>

执行Continuus签入命令。
- 属性 ：
- ccmdir ： ccm 可执行文件所在的目录，字符串类型。
- comment ：指定注释，字符串类型。
- file ：命令要操作的文件路径，文件类型。
- task ：指定用于签入文件的任务编号（可使用默认值），字符串类型。

7.5 <checksum>*

创建或验证文件校验和。
- 属性 ：
- algorithm ：指定用于计算校验和的算法，字符串类型。
- file ：要计算校验和的文件，文件类型。
- fileext ：用于创建或识别目标文件的文件扩展名，字符串类型。
- forceoverwrite ：指示是否覆盖现有文件，无论其是否比源文件新，布尔类型。
- property ：用于保存生成的校验和的属性，字符串类型。
- provider ：用于计算校验和的 MessageDigest 算法提供程序，字符串类型。
- readbuffersize ：使用的读取缓冲区大小，整数类型。
- verifyproperty ：验证属性，字符串类型。
- 子元素 ：
- <fileset> ：要生成校验和的文件，文件集类型。

8. 任务操作示例

以 <apply> 任务为例，以下是一个简单的操作步骤说明：
1. 确定命令 ：明确要执行的命令，设置 executable 属性。例如，若要执行 ls 命令，可将 executable 设置为 ls 。
2. 设置工作目录 ：使用 dir 属性指定进程的工作目录。
3. 指定源文件 ：通过 <fileset> 子元素添加要操作的源文件。
4. 处理输出 ：使用 output 属性指定输出文件， append 属性设置输出方式。
5. 配置其他属性 ：根据需要设置 failifexecutionfails 、 failonerror 等属性。

graph LR
    A[开始] --> B[确定命令]
    B --> C[设置工作目录]
    C --> D[指定源文件]
    D --> E[处理输出]
    E --> F[配置其他属性]
    F --> G[执行命令]
    G --> H[结束]

9. 网络相关任务

9.1 <ftp>

使用FTP上传或下载文件。
- 属性 ：
- action ：FTP操作，可选 send 、 put 、 recv 、 get 、 del 、 delete 、 list 、 mkdir 、 chmod 。
- binary ：若为 true ，使用二进制模式；否则使用文本模式，默认 true ，布尔类型。
- chmod ：发送到服务器的文件的文件权限模式（仅Unix），字符串类型。
- depends ：若为 true ，仅传输比其远程对应文件新或更改的文件，布尔类型。
- ignorenoncriticalerrors ：若为 true ，跳过目录创建错误，布尔类型。
- listing ： list 操作的输出文件，文件类型。
- newer ： depends 的同义词，布尔类型。
- passive ：指定是否使用被动模式，布尔类型。
- password ：给定用户ID的登录密码，字符串类型。
- port ：远程服务器使用的FTP端口，整数类型。
- remotedir ：文件将放置的远程目录，字符串类型。
- separator ：远程文件分隔符字符，字符串类型。
- server ：要发送文件的FTP服务器，字符串类型。
- skipfailedtransfers ：若为 true ，跳过不成功的文件上传、删除和下载操作，仅给出警告并传输其余文件，布尔类型。
- umask ：Unix服务器上文件创建的默认掩码，字符串类型。
- userid ：指定服务器上使用的登录用户ID，字符串类型。
- verbose ：若为 true ，在传输每个文件时接收通知，布尔类型。
- 子元素 ：
- <fileset> ：要上传或下载的文件集，文件集类型。

9.2 <http>

检查指定URL的Web服务器的有效响应。可在 <condition> 任务中使用，用于条件判断。

10. 总结与展望

Ant提供了丰富多样的任务，涵盖文件操作、项目构建、网络传输等多个领域。通过合理使用这些任务及其属性和子元素，能够实现高效的项目自动化构建和管理。在未来的项目中，可以根据具体需求灵活组合任务，进一步优化构建流程，提高开发效率。

例如，在大型项目中，可以结合 <ant> 任务构建子项目，使用 <javac> 任务编译Java代码，利用 <ftp> 任务进行文件上传。同时，通过 <condition> 和 <waitfor> 任务实现条件判断和等待机制，确保任务按顺序执行。

graph LR
    A[项目构建] --> B[子项目构建<ant>]
    A --> C[代码编译<javac>]
    A --> D[文件上传<ftp>]
    B --> E[条件判断<condition>]
    D --> F[等待机制<waitfor>]
    E --> G[任务执行顺序控制]
    F --> G
    G --> H[项目完成]

总之，深入了解Ant任务的功能和使用方法，将为项目开发和管理带来极大的便利。