运行 Apache Ant

命令行

如果您按照 安装 Ant 部分中的说明安装了 Apache Ant，则从命令行运行 Ant 很简单：只需键入 ant。

如果没有指定任何参数，Ant 会在当前目录中查找 build.xml 文件，如果找到，则使用该文件作为构建文件并运行在 <project> 标签的 default 属性中指定的 target。要让 Ant 使用除 build.xml 之外的构建文件，请使用命令行选项 -buildfile file，其中 file 是您要使用的构建文件的名称（或包含 build.xml 文件的目录）。

如果您使用 -find [file] 选项，Ant 将首先在当前目录中搜索构建文件，然后在父目录中搜索，依此类推，直到找到构建文件或到达文件系统的根目录。默认情况下，它将查找名为 build.xml 的构建文件。要让它搜索除 build.xml 之外的构建文件，请指定文件参数。注意：如果您在 -find 标志之后在命令行中包含任何其他标志或参数，则必须包含 -find 标志的文件参数，即使您要查找的构建文件的名称是 build.xml。

您也可以在命令行上设置 属性。这可以通过 -Dproperty=value 选项完成，其中 property 是属性的名称，value 是该属性的值。如果您指定一个在构建文件中也设置的属性（参见 property 任务），则在命令行上指定的 value 将覆盖在构建文件中指定的 value。在命令行上定义属性也可以用于传递环境变量的值；只需将 -DMYVAR=%MYVAR%（Windows）或 -DMYVAR=$MYVAR（Unix）传递给 Ant。然后，您可以在构建文件中以 ${MYVAR} 的形式访问这些变量。您也可以使用 property 任务的 environment 属性来访问环境变量。

影响 Ant 日志输出量的选项有：-quiet，它指示 Ant 向控制台打印更少的信息；-verbose，它会导致 Ant 向控制台打印更多信息；-debug，它会导致 Ant 打印更多额外信息；以及 -silent，它使 Ant 只打印任务输出和构建失败（这对通过脚本捕获 Ant 输出很有用）。

还可以指定一个或多个要执行的 target。省略时，将使用在 project 标签的 default 属性中指定的 target。

-projecthelp 选项打印出构建文件的 target 列表。包含 description 属性的 target 列为“主要 target”，没有 description 的 target 列为“其他 target”，然后列出“默认”target（只有在没有主要 target 或 Ant 以 -verbose 或 -debug 模式调用时才会显示“其他 target”）。

命令行选项摘要

ant [options] [target [target2 [target3] ...]]
Options:
  -help, -h              print this message and exit
  -projecthelp, -p       print project help information and exit
  -version               print the version information and exit
  -diagnostics           print information that might be helpful to
                         diagnose or report problems and exit
  -quiet, -q             be extra quiet
  -silent, -S            print nothing but task outputs and build failures
  -verbose, -v           be extra verbose
  -debug, -d             print debugging information
  -emacs, -e             produce logging information without adornments
  -lib <path>            specifies a path to search for jars and classes
  -logfile <file>        use given file for log
    -l     <file>                ''
  -logger <classname>    the class which is to perform logging
  -listener <classname>  add an instance of class as a project listener
  -noinput               do not allow interactive input
  -buildfile <file>      use given buildfile
    -file    <file>              ''
    -f       <file>              ''
  -D<property>=<value>   use value for given property
  -keep-going, -k        execute all targets that do not depend
                         on failed target(s)
  -propertyfile <name>   load all properties from file with -D
                         properties taking precedence
  -inputhandler <class>  the class which will handle input requests
  -find <file>           (s)earch for buildfile towards the root of
    -s  <file>           the filesystem and use it
  -nice  number          A niceness value for the main thread:
                         1 (lowest) to 10 (highest); 5 is the default
  -nouserlib             Run ant without using the jar files from ${user.home}/.ant/lib
  -noclasspath           Run ant without using CLASSPATH
  -autoproxy             Java 5+ : use the OS proxies
  -main <class>          override Ant's normal entry point

有关 -logger 和 -listener 的更多信息，请参见 日志记录器和监听器。

有关 -inputhandler 的更多信息，请参见 InputHandler。

更改退出行为的最简单方法是子类化原始主类

public class CustomExitCode extends org.apache.tools.ant.Main {
    protected void exit(int exitCode) {
        // implement your own behaviour, e.g. NOT exiting the JVM
    }
}

并使用对该类的访问权限启动 Ant（-lib path-to-class）。

库目录

在 Ant 1.6 之前，ANT_HOME/lib 中的所有 jar 文件都会被添加到用于运行 Ant 的 CLASSPATH 中。这是在启动 Ant 的脚本中完成的。从 Ant 1.6 开始，默认情况下会扫描两个目录，并且可以根据需要添加更多目录。默认扫描的目录是 ANT_HOME/lib 和一个用户特定目录 ${user.home}/.ant/lib。这种安排允许许多用户共享 Ant 安装，同时仍然允许每个用户部署额外的 jar 文件。这些额外的 jar 文件可能是 Ant 可选任务的支持 jar 文件，或者包含用于构建的第三方任务的 jar 文件。它还允许锁定主 Ant 安装，这将使系统管理员满意。

可以使用 -lib 选项添加要搜索的其他目录。 -lib 选项指定一个搜索路径。路径目录中的任何 jar 文件或类都将被添加到 Ant 的类加载器中。将 jar 文件添加到类路径的顺序如下

• 命令行上 -lib 选项指定的顺序的 jar 文件
• 来自 ${user.home}/.ant/lib 的 jar 文件（除非设置了 -nouserlib）
• 来自 ANT_HOME/lib 的 jar 文件

请注意，CLASSPATH 环境变量是使用 -lib 选项传递给 Ant 的。Ant 本身是以一个非常简单的类路径启动的。Ant 应该能够很好地处理空的 CLASSPATH 环境变量，实际上 -noclasspath 选项强制执行这一点。我们收到的与类路径问题（尤其是引用问题）相关的支持电话比我们想要的要多。

${user.home}/.ant/lib 的位置在一定程度上取决于 JVM。在 Unix 系统上，${user.home} 映射到用户的 home 目录，而在最近版本的 Windows 上，它将位于类似 C:\Users\username\.ant\lib 的位置。您应该查阅 JVM 文档以了解更多详细信息。

示例

ant

使用当前目录中的 build.xml 文件在默认 target 上运行 Ant。

ant -buildfile test.xml

使用当前目录中的 test.xml 文件在默认 target 上运行 Ant。

ant -buildfile test.xml dist

使用当前目录中的 test.xml 文件在名为 dist 的 target 上运行 Ant。

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

使用当前目录中的 test.xml 文件在名为 dist 的 target 上运行 Ant，将 build 属性设置为值 build/classes。

ant -lib /home/ant/extras

运行 Ant，从 /home/ant/extras 位置获取额外的任务和支持 jar 文件

ant -lib one.jar;another.jar

ant -lib one.jar -lib another.jar

将两个 jar 文件添加到 Ant 的类路径中。

文件

Unix 的 Ant 包装器脚本将在执行任何操作之前源（读取和评估）文件 ~/.antrc。在 Windows 上，Ant 包装器批处理文件在开始时调用 %HOME%\antrc_pre.bat，在结束时调用 %HOME%\antrc_post.bat。您可以使用这些文件（例如）设置/取消设置仅在 Ant 执行期间可见的环境变量。有关示例，请参见下一节。

环境变量

包装器脚本使用以下环境变量（如果设置了）：

• JAVACMD—Java 可执行文件的完整路径。使用它来调用与 JAVA_HOME/bin/java(.exe) 不同的 JVM。
• ANT_OPTS—应该传递给 JVM 的命令行参数。例如，您可以在此处定义系统属性或设置最大 Java 堆大小。
• ANT_ARGS—Ant 命令行参数。例如，将 ANT_ARGS 设置为指向不同的日志记录器，包括监听器，以及包括 -find 标志。
  注意：如果您在 ANT_ARGS 中包含 -find，则应包含要查找的构建文件的名称，即使该文件名为 build.xml。

Java 系统属性

Ant 的一些核心类可以通过系统属性进行配置。

以下是代码库搜索的结果。由于系统属性可以通过 Project 实例获得，因此我使用

grep -r -n "getPropert" * > ..\grep.txt

命令搜索它们。之后，我过滤掉了经常使用但不太重要的值（其中大多数是只读值）：path.separator、ant.home、basedir、user.dir、os.name、line.separator、java.home、java.version、java.version、user.home、java.class.path
并且我过滤掉了 getPropertyHelper 访问。

如果添加了新的属性（会发生这种情况），则预计它们将出现在ant.和org.apache.tools.ant.前缀下，除非开发人员有充分的理由使用其他前缀。因此，请避免使用以这些前缀开头的属性。这可以保护您免受将来Ant版本破坏您的构建文件的影响。

返回码

Ant启动脚本（在Windows和Unix版本中）返回java程序的返回码。因此，成功的构建返回0，失败的构建返回其他值。

临时目录

在调用Ant时设置系统属性并不简单，因为相应的命令行参数必须发送到Java可执行文件，而不是Ant的主类。当使用ant(.cmd)包装器脚本时，可以使用ANT_OPTS环境变量来实现。

从Ant 1.10.8开始，我们引入了一个新的Ant属性ant.tmpdir，它在设置时优先于java.io.tmpdir。由于这是一个普通的Ant属性，因此可以通过命令行甚至从构建文件中设置它。

使用临时目录的任务将在各自的手册页中说明这一事实。此外，在OpenVMS上执行每个外部命令都会创建一个临时文件，其中包含一个DCL脚本，用于调用实际命令。

从Ant 1.10.9开始，Ant将尝试在java.io.tmpdir中创建一个特定于构建过程的临时目录，其权限设置为仅当前用户可访问，如果未设置ant.tmpdir并且Ant能够在相关文件系统上设置权限，则使用该目录。

未随Ant发行版提供的任务将忽略ant.tmpdir属性或进程子目录，并使用java.io.tmpdir，除非它们已适应Ant 1.10.8的更改的API。

安全注意事项：使用java.io.tmpdir指定的默认临时目录可能会导致敏感信息的泄漏，或者可能允许攻击者将源文件注入构建过程。这在多用户环境中尤其如此。建议将ant.tmpdir设置为由运行Ant的用户拥有的目录，并具有0700权限。Ant 1.10.8及更高版本将尝试使其创建的临时文件仅对当前用户可读/可写，但可能会根据操作系统和文件系统静默地失败。

Cygwin用户

随Ant提供的Unix启动脚本可与Cygwin正常工作。您不应该在Cygwin shell中启动Ant时遇到任何问题。但是，重要的是要注意，一旦Ant运行，它就是JDK的一部分，JDK作为本机Windows应用程序运行。JDK不是Cygwin可执行文件，因此它不了解Cygwin路径等。特别是当使用<exec>任务时，诸如/bin/sh之类的可执行文件名将不起作用，即使这些文件名从启动Ant的Cygwin shell中工作。您可以使用诸如sh之类的可执行文件名，并依赖于该命令在Windows路径中可用。

OS/2用户

OS/2启动脚本被开发用于执行复杂的任务。它有两个部分：ant.cmd调用Ant，而antenv.cmd设置Ant的环境。大多数情况下，您只需使用上面描述的相同命令行选项调用ant.cmd即可。可以通过下面解释的几种方式修改行为。

脚本ant.cmd首先验证Ant环境是否已正确设置。要求是

1. 环境变量JAVA_HOME已设置。
2. 环境变量ANT_HOME已设置。
3. 环境变量CLASSPATH已设置，并且至少包含一个来自JAVA_HOME的元素和至少一个来自ANT_HOME的元素。

如果这些条件中的任何一个被违反，则调用脚本antenv.cmd。该脚本首先调用配置脚本（如果存在）：来自%ETC%目录的系统范围配置antconf.cmd，然后来自%HOME%目录的用户配置antrc.cmd。此时，JAVA_HOME和ANT_HOME都必须定义，因为antenv.cmd现在将classes.zip或tools.jar（取决于JVM的版本）以及来自%ANT_HOME%\lib的所有内容（除了ant-*.jar）添加到CLASSPATH中。最后，ant.cmd调用每个目录配置antrc.cmd。ant.cmd进行的所有设置都是本地的，并在脚本结束时撤消。antenv.cmd进行的设置在shell的整个生命周期内都是持久的（当然，除非从ant.cmd自动调用）。因此，可以手动调用antenv.cmd并在调用ant.cmd之前修改某些设置。

脚本envset.cmd和runrc.cmd执行辅助任务。所有脚本在内部都有一些文档。

在Unix（类Unix）系统上将Ant作为后台进程运行

如果您将Ant作为后台进程启动（如在ant &中），并且构建过程创建了另一个进程，则Ant将立即尝试从标准输入读取，这反过来很可能挂起进程。为了避免这种情况，您必须重定向Ant的标准输入或通过相应任务的输入相关属性显式地为每个生成的进程提供输入。

创建此类新进程的任务包括<exec>、<apply>或<java>（当fork属性为true时）。

通过Java运行Ant

如果您已通过DIY方式安装Ant，则可以从两个入口点之一启动Ant

java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]

java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher [options] [target]

第一种方法运行Ant的传统入口点。第二种方法使用Ant 1.6中引入的Ant启动器。前一种方法不支持-lib选项，所有必需的类都从CLASSPATH加载。您必须确保所有必需的jar文件可用。至少，CLASSPATH应包含

• ant.jar和ant-launcher.jar
• XML解析器的jar/类
• JDK的必需jar/zip文件

后一种方法支持-lib、-nouserlib、-noclasspath选项，并将从指定的ANT_HOME加载jar文件。您应该使用尽可能少的类路径启动后者，通常只是ant-launcher.jar。

可以通过<java>命令在Ant中启动Ant。这是一个示例

<java classname="org.apache.tools.ant.launch.Launcher"
      fork="true"
      failonerror="true"
      dir="${sub.builddir}"
      timeout="4000000"
      taskname="startAnt">
    <classpath>
        <pathelement location="${ant.home}/lib/ant-launcher.jar"/>
    </classpath>
    <arg value="-buildfile"/>
    <arg file="${sub.buildfile}"/>
    <arg value="-Dthis=this"/>
    <arg value="-Dthat=that"/>
    <arg value="-Dbasedir=${sub.builddir}"/>
    <arg value="-Dthe.other=the.other"/>
    <arg value="${sub.target}"/>
</java>