第三章：组成 Apache Ant 的元素

指示

在命令行中使用Ant，全部都是通过ant命令来进行的。
格式如下，指定选项和目标来执行。
※关于目标在后面会介绍。

ant [オプション] [ターゲット1 ターゲット2...]

只需要一个自然的选项 – ワンオプション

您可以通过ant -help命令来查看可用的Ant选项列表，但如果只是简单使用的话，确保掌握以下内容即可，没有问题。

• -buildfile <ファイル>

• 参照するビルドファイルをパスで指定します。

• 指定しない場合、カレントディレクトリのbuild.xmlというファイルが指定されます。

• -find <ディレクトリ>

• 指定したディレクトリのサブディレクトリを検索し、ビルドファイルを探す。

• -verbose

ビルドに関する詳細な情報を出力しながらビルドを実行します。

建筑文件

通常，我们会使用build.xml作为构建文件的命名惯例。但也可以使用其他名称，但在运行时需要指定文件。

1. 项目

每个项目要素都必须在一个构建文件中。在构建文件中，所有的要素必须在这个项目要素内定义。
项目要素可以设置以下三个属性。

名称：项目名称
设置任意的项目名称。

默认：默认目标名称
用于指定在未指定目标时要执行的目标。
在Ant1.4之前，它是必需的，但从Ant1.5开始，如果省略default属性，则将执行main目标，
因此可以省略。

基础目录：基础目录是指定的。将./foo目录指定为基础目录，并在mkdir元素的dir属性中指定为”sample”，则将创建./foo/sample。换句话说，在进行构建操作时，起点位于./foo目录。

2. 目标（Target）

目标是完成一系列任务以达到特定目的的集合。
以“创建EAR文件”为例，目标是创建EAR文件，
一系列任务包括源代码编译、编译后的类文件和资源的布局等等，
这些是创建EAR文件所需的一系列处理。
target元素可以进行多个定义，并且可以设置以下属性。

名称：目标名称
在target元素中，这是唯一必需的属性。它定义了在ant命令中指定的目标名称。

在执行此目标之前，指定要完成执行的其他目标。可以使用逗号进行多个目标的指定。

如果必要的话：必须属性。
可以指定属性名称，并在运行时跳过此任务的执行，如果指定的属性没有设置。

除非：不要属性
进行与”if”相反的设定。可以指定属性名称，在运行时如果指定的属性已经设置，将跳过此任务的执行。

描述：处理概要
设置了”projecthelp”选项后，在运行Ant时会显示目标的处理概要。

3. 任务 (Task)

如前所述的目标一节中所解释的那样，任务是为了实现目标而进行的一系列处理，一个目标可以通过组合多个任务来实现。
一个任务只负责单个处理，例如编译、文件复制等。

Ant提供了预定义的内置任务。
内置任务大致分为核心任务和可选任务。
核心任务是在构建过程中频繁执行的任务，比如编译、将制表符转换为空格等。只要安装了Ant，就可以立即使用这些任务。
可选任务则是一些不太常用的任务。有时需要将特定的模块添加到Ant中才能使用，比如添加jar文件等。

在嵌入任务中，有诸如属性任务和创建目录任务等，每个任务都会通过元素、来进行描述和使用。
如果想了解还有哪些任务可用，建议查阅 Ant 的官方文档或者参考总结了常用任务的文章。

在Ant中，用户可以创建独自的任务。
创建方式有些复杂，因为大部分构建工作可以通过内置任务来完成，
所以如果想深入学习Ant，只需要查阅一下相关资料即可。

数据结构

在构建工作中，经常需要对多个文件（集合）进行处理，包括资源的配置和编译目标的指定等。借助Ant，可以将这些多个文件和集合以数据结构的形式表示，从而更方便地对集合进行处理。

数据结构可以被定义为项目、目标和任务的子元素。
由于定义的位置不同，因此具有不同的范围。
可以根据情况选择定义的位置，比如在多个目标和任务中使用，或者仅在一个任务内使用。

1. 模式

模式是在Ant中用于指定文件夹、文件名等时的通配符。
模式中有以下三种类型的通配符可用。

2. 模式套装

模式集合允许通过组合多个模式来指定更复杂的模式。
指定可以通过组合包含xxx和排除xxx来表示。

模式集通过元素定义。
可以使用以下属性来指定模式。

在模式集合的定义中，有两种方法可以定义属性，一种是将其定义为属性值，另一种是将其定义为元素。

<!-- 属性値として定義する方法 -->
<patternset includes="Foo*,Bar*" excludes="*.java,*.class" />

<!-- 要素として定義する方法 -->
<patternset>
  <include name="Foo*,Bar*" />
  <exclude name="*.java,*.class" />
</patternset>

<!-- 別のパターンセットを利用する方法 -->
<patternset refid="common-set">
  <include name="Foo*,Bar*" />
</patternset>
<patternset id="common-set">
  <exclude name="*.java,*.class" />
</patternset>

如果将属性定义为模式集的元素来设置，则可以使用以下属性

3. 文件集

这是一个在模式设置中设定基目录的数据结构。
通过指定基目录，可以使用相对路径来指定模式。
由于上述特性，设置基目录是必需的。

文件集主要用于将一组文件作为集合处理，但也存在一种称为目录集(Dirset)的元素，用于指定一组目录。
可以指定的属性、可以定义的元素等与文件集相同。

默认的排除集合
在Ant中，已经设置了一个名为默认的排除集合。在这个集合中定义的内容不需要指定排除模式就会被排除。
例如) **/.svn、**/.git等。

可以用于文件集的属性 hé de

在文件集合元素中，除了像模式集合中介绍的包括（include）元素等元素之外，还可以定义选择器元素。
选择器是一种可以通过条件而不是路径来指定目标的功能，稍后将详细说明。

4. 类似的路径结构

定义用于确定路径相似结构的元素包括path元素和classpath元素，二者的区别在于classpath元素被用作任务的子元素，
而path元素被独立于任务的位置定义，并通过refid属性在多个任务中共同使用。

在 path 元素和 classpath 元素中，可以指定的属性和子元素的定义是共同的。

可用于路径相似结构的属性。

可以用于路径相似结构的元素。

• Filelist

• Fileset

• Dirset

• Pathelement

リソースコレクション：Ant1.8以降は使用可能

路径元素表示路径，并且仅用作路径类似结构的子元素。
与路径类似结构不同，它不能具有子元素。

在指定路径时可以使用path属性和location属性，如果要指定多个路径，则使用path属性，如果要指定单个路径，则使用location属性。
使用location属性并将每个路径定义为独立的，可以提高可读性。

<!-- path属性で複数パスを一箇所に定義した場合 -->
<classpath path="/usr/local/java/junit-3.7/junit.jar:/usr/local/java/log4j-1.2.4/dist/lib/log4j-1.2.4.jar:/usr/local/tomcat-4.0.4/common/lib/mail.jar:/usr/local/tomcat-4.0.4/common/lib/activation.jar"/>
<!-- location属性でパスを個別に定義した場合 -->
<classpath>
  <pathelement location="/usr/local/java/junit-3.7/jnit.jar" />
  <pathelement location="/usr/local/java/log4j-1.2.4/dist/lib/log4j-1.2.4.jar" />
  <pathelement location="/usr/local/tomcat-4.0.4/common/lib/mail.jar" />
  <pathelement location="/usr/local/tomcat-4.0.4/common/lib/activation.jar" />
</classpath>

5. 映射器 qì)

Mapper定义了文件名的转换规则。
以Copy任务为例，有以下使用方法。

<!-- Copyタスク：コピー先の定義 -->
<copy todir="/target" includeEmptyDirs="no">
  <!-- コピー元の定義 -->
  <fileset dir="/src" defaultexcludes="no" />
  <!-- コピー元 → コピー先にコピーする際、
       どのようにパス、ファイル名を変換するかを定義 -->
  <mapper type="glob" from="*" to="*.bk" />
</copy>

以上的复制任务实现了以下内容。

将/src目录下的所有文件（复制源）按照将.bk添加到所有文件末尾的规则，放置在/target目录下。

映射器通过组合匹配目标的匹配方法和匹配内容的转换规则来定义转换过程。此外，映射器还有内置类型(通过type属性指定)和自定义定义(通过classname属性指定)。

可以在映射器中设置的属性

在type属性中可以指定以下值作为嵌入式映射器的选项：

【身份】不转换文件名和目录结构。无论设置from属性还是to属性都将被忽略。

<!-- 例１ -->
<copy todir="/target" includeEmptyDirs="no">
  <fileset dir="/src" defaultexcludes="no" />
  <!-- from、toの設定が不要 -->
  <mapper type="identity" />
</copy>
<!-- 例２ -->
<copy todir="/target" includeEmptyDirs="no">
  <fileset dir="/src" defaultexcludes="no" />
  <!-- from、toを指定しても全てのファイルが対象となり、.bkも付与されない -->
  <mapper type="identity" from="*.java" to="*.bk" />
</copy>

【压平】
文件名保持不变，目录结构被忽略。忽略from属性和to属性。

<copy todir="/root/copy" includeEmptyDirs="no">
  <fileset dir="/root/original" defaultexcludes="no" />
  <mapper type="flatten" />
</copy>

【合并】
忽略from属性，无论目录结构和文件名如何，
将所有文件转换为以to属性指定的固定文件名。

file1.txt → convert.txt
/foo/bar/file2.txt → convert.txt

【通配符】
您可以使用一个通配符“*”。
与“*”匹配的字符串在from属性中可以使用通配符“*”进行引用。

<!-- /src/Sample.java があった場合 -->
<copy todir="/target" includeEmptyDirs="no">
  <fileset dir="/src" defaultexcludes="no" />
  <mapper type="glob" from="*.java" to="*.class" />
</copy>
<!-- /target/Sample.class がコピーされる -->

【包】
您可以使用与Glob类似的通配符「」。与Glob的区别是，当匹配到的字符串中包含目录分隔符（Unix为「/」，Windows为「\」）时，该目录分隔符将被替换为「.」。例如，将from=”.java”和to=””，那么针对源文件「a/b/c/d.java」的目标文件将变为「a.b.c.d」。

【正则表达式】
可以使用from属性来使用正则表达式，用括号括起来的部分可以指定九个正则表达式。
在to属性中，可以使用”\1″〜”\9″的方式引用从from属性中匹配的字符串。

from="(.*)/(.*).java"
to="\1\2.java"
と定義すると、
One/Test.java → OneTest.java
に変換される。

6. 选择器

数据结构基本上是根据文件名来指定文件集合，但选择器可以根据文件更新日期、大小、指定目录的深度等各种要素来指定文件集合。

在选择器中，有以下几种类型。

コアセレクタ
Antにあらかじめ組み込まれているセレクタで、単体として機能します。

セレクタコンテナ
コアセレクタのように、単体で機能するセレクタを複数内包するコンテナです。

カスタムセレクタ
ユーザが独自に定義するセレクタです。

核心选择器

● 文件名

● 尺寸 (chǐ

〜可以设置的单位值〜

日期指定是必需的，可以使用“MM/DD/YYYY HH:MM AM[或PM]”格式，或者使用从1970年1月1日开始的毫秒进行指定。

● 包含

将基目录的深度设为0，用文件的深度指定搜索对象。

如果存在以下的文件夹结构{$src}/a/b/c/d/e，
那么b、c、d目录中的文件将被视为目标，
而a、e目录中的文件将被排除在外。

<fileset dir="{$src}">
  <depth min="2" />
  <depth max="4" />
</fileset>

检查目标目录(targetdir)进行验证，
选择满足以下条件之一的文件作为处理对象：比较目标不存在文件、比较目标更新时间较新。
默认情况下，使用相同文件名进行比较，但如果您希望使用自定义的比较模式，
则可以定义mapper子元素（例如，比较Foo.java和FooDevelop.java）。

由于并非所有文件系统都以毫秒级别来管理更新日期，所以不是所有的文件系统都能处理毫秒级别的时间。

更新时间不需要比较，只进行文件存在检查的依赖选择器。
默认情况下，会通过同名文件进行比较，但如果想要使用自定义的比较模式，
可以定义mapper子元素。（比如要比较Foo.java和FooDevelop.java）

选择器容器
选择器容器可以组合多个选择器，并实现复杂的条件指定。
以下是使用示例，在以下源代码中，
将选择“更新日期在2002年8月20日上午6点后”或者“文件大小大于100KB”的文件。

<fileset dir="{$log}" includes="**/*.log">
  <or>
    <date datetime="08/20/2002 6:00 AM" when="after" />
    <size value="100" units="Ki" when="more" />
  </or>
</fileset>

在上述示例中，是选择器容器的一种，选择器容器可以设置以下共同属性。

在选择器容器中有以下内容。

● 选择器
选择器是一个包含选择器的容器（用于保存通过refid从其他选择器引用的选择器的容器），
或者可以用作引用预先适配的选择器的标签。

<project default="all" basedir="./root">
    <!-- セレクタを保持する箱 -->
    <selector id="completed">
        <none>
            <depend targetdir="build/classes">
                <mapper type="glob" from="*.java" to="*.class"/>
            </depend>
            <depend targetdir="docs/manual/api">
                <mapper type="glob" from="*.java" to="*.html"/>
            </depend>
        </none>
    </selector>

    <target>
        <zip>
            <fileset dir="src/main" includes="**/*.java">
                <!-- 上記で作成したSelectorを参照するタグ -->
                <selector refid="completed"/>
            </fileset>
        </zip>
    </target>
</project>

在Selector中，可以设置if属性和unless属性，并且可以使用if=”属性值”的形式。如果if属性指定的属性被设置，则该Selector将被启用；如果unless属性指定的属性未被设置，则该Selector将被启用。

<fileset dir="${working.copy}">
    <or>
        <selector if="include.tests">
            <filename name="**/*Test.class">
        </selector>
        <selector if="include.source">
            <and>
                <filename name="**/*.java">
                <not>
                    <selector unless="include.tests">
                        <filename name="**/*Test.java">
                    </selector>
                </not>
            </and>
        </selector>
    </or>
</fileset>

7. 过滤器

过滤器是在执行复制或移动任务时替换文件内容的功能。在Ant中，默认情况下，将被@符号括起来的字符串视为标记并将其作为替换目标。

过滤器
标签可设定以下属性。

在以下的例子中，将文本文件中的@srcFolder@这个字符串转换为/project/main/src。

<filter token="srcFolder" value="/project/main/src" />

通常情况下，滤波器不是单独使用的，而是将多个滤波器组合成滤波器集进行使用。
滤波器集可以包含滤波器和滤波器集作为子元素，并可以设置以下属性。

过滤器链和过滤器导读器
过滤器导读器是执行高级替换的功能，通过Java类定义并指定类来调用处理。
过滤器链拥有多个过滤器导读器作为子元素，用于控制它们的执行顺序。

过滤器链会按照以下的形式进行使用。过滤器读取器将按顺序从上到下执行。

<filterchain>
  <filterreader classname="org.apache.tools.ant.filters.HeadFilter">
    <param name="lines" value="30"/>
  </filterreader>
  <filterreader>
    ...
  </filterreader>
</filterchain>

你可以使用以下属性来过滤数据。

通过将元素作为子元素来定义过滤器，可以将参数传递给执行类，并可以指定以下属性。

● 预先定义的过滤器

Ant具有预定义的过滤器，并且可以对预定义的过滤器进行简略表示。

<filterreader classname="org.apache.tools.ant.filters.HeadFilter">
  <param name="lines" value="30"/>
</filterreader>
<!-- 略記の場合 -->
<headfilter lines="30" />

请参阅“Ant的典型过滤负责人”，我们已经创建了与常用筛选器相关的单独文章。

以下是对各种数据结构再次总结。

返回主页