ant (zh)

Ant1.7.1用户手册--安装  

2008-10-19 13:41:31|  分类： Ant 1.7.1 |  标签： |字号大中小 订阅

得到Ant

二进制版本

最新的稳定版本可以在http://ant.apache.org/直接下载。

作为RPM包中的二进制版本

在jpackage一节介绍。

和IDE绑定

所有主流的Java IDE都支持Ant，例如Eclipse，NetBeans和IntelliJ IDEA。如果您使用这种方式安装ant，需要得到和IDE发布时间最近的Ant。一些IDE需要在IDE工具中设置Ant的路径才能运行，除了（Eclipse和NetBeans）。如果想要使用命令行的Ant相关的Jar文件要作为附加的二进制文件或任务添加到Ant中。注意，如果IDE任务或插件不能运行，Ant组织不会发布bug报告。请首先尝试IDE的发布列表，如果合适的话里面会有bug记录。

当指向不同的Ant时，IDE可以不变。这样作可以让开发者升级最新版本的Ant，同时消除命令行和IDE中Ant的不一致性。

和Java程序绑定

很多Java程序，很可能是服务器，发布时会附带Ant。在应用程序内部主要的应用是使用Java的API在Ant运行时代理JSP页面的编译。不是所有程序都支持这样发布。通常如果不使用自带的Ant而使用其他版本的Ant，可能出现问题，所以在PATH中他们有自己版本的Ant.BAT或ant.sh。如果Ant在安装一些其他东西后运行不正常，试一下诊断一节中的建议。

源代码版本

如果您想得到源码，可以从http://ant.apache.org/srcdownload.cgi下载最新发布的源码。如果您想得到最新版本的代码，可以从SVN中下载。在accessing SVN上可以访问Ant的详细情况。所有bug都在源码树的顶端解决，对一些bug的第一反应应该是“是否您已经下载了最新的源码”。不要害怕卸载到还未发布的版本，因为除了新功能的其他功能还是很稳定的。

参考Building Ant一节，看一下如何编译源码。您也可以在在线访问Ant SVN repository。

系统需求

Ant在许多平台中都可以成功使用，包括Linux，Unix商用版本比如Solaris和HP-UX，WindowsNT平台，OS/2，Novell Netware 6, OpenVMS 以及 MacOS X。这些平台是开发者使用最多的，排序没有特殊的区别，Linux, MacOS X, Windows XP 以及 Unix；在这些平台上都可以工作的很好。从Ant1.7开始，Windows 9x系列不再支持。

要构建和使用Ant，您必须安装一个JAXP-compliant XML解析器并且配置在classpath中，例如Xerces。

可以下载Apache Xerces2 XML解析器。要了解JAXP，请参考http://java.sun.com/xml/。如果想使用一个不同的JAXP-compliant解析器，应该将ant的lib目录下的xercesImpl.jar 和 xml-apis.jar删除。

您可以将您想使用解析器的Jar文件拷贝到Ant的lib目录下或放在系统的classpath中。如果您使用一个老版本的解析器，Ant的一些部分可能不能解析，尤其是不能识别名字空间的解析器。尤其是不能使用Crimson解析器。

提示：“ant -diagnostics”将展示使用的XML解析器和位置。

对于当前版本的Ant来说，您也需要系统中安装一个JDK，1.2或以后版本都可以，强烈建议使用1.5或以后版本。使用越新的Java，就可以使用更多的Ant任务。

注意：如果没有JDK只有JRE运行时，那么一些任务将不能运行。

开源Java运行时

Ant组织强烈支持用户将Ant运行在Kaffe或其他开源Java运行时中，同时努力让产品支持这些平台。例如使用Kaffe以及Gnu Classpath配合Xerces以及Xalan的库。

安装Ant

二进制发布版的Ant包含如下目录：

 

  ant

   +--- README, LICENSE, fetch.xml, other text files. //basic information

   +--- bin  // contains launcher scripts

   |

   +--- lib  // contains Ant jars plus necessary dependencies

   |

   +--- docs // contains documentation

   |      |

   |      +--- images  // various logos for html documentation

   |      |

   |      +--- manual  // Ant documentation (a must read ;-)

   |

   +--- etc // contains xsl goodies to:

            //   - create an enhanced report from xml output of various tasks.

            //   - migrate your build files and get rid of 'deprecated' warning

            //   - ... and more ;-)

 

 

运行Ant只需要bin和lib文件夹。要安装Ant，选择一个目录并且将发布文件拷贝到目录中即可。这个目录就是ANT_HOME。

 

Windows 95, Windows 98 & Windows ME 注意事项：

在这些系统中，如果ANT_HOME是一个长文件名（不是8.3格式的文件名），运行ant是会出错。这个问题是OS在批处理文件中处理for关键字的限制造成的。如果出现了这种情况，建议使用短目录名作为ant安装目录，8.3格式的，例如：C:\Ant。

在这些系统中，您还需要为Ant运行脚本中的环境变量配置更多的环境变量空间。完成这项工作，需要在config.sys文件中添加或更新以下命令：

 

shell=c:\command.com c:\ /p /e:32768

 

安装

在运行Ant之前还需要一些设置，除非您安装RPM version from jpackage.org，配置方式如下：

l         将bin目录添加到path中。

l         将ANT_HOME环境变量设置为安装Ant的文件夹。在一些操作系统中，Ant的启动脚本可以猜测ANT_HOME的位置（Unix部分版本以及Windows NT/2000），但最好不要依赖这个特性。

l         可选的，设置JAVA_HOME环境变量。这个环境变量的值是您安装JDK的目录。

注意：不要将Ant的ant.jar文件拷贝到JDK/JRE的lib/ext目录下。Ant是一个应用程序，以上扩展目录的目的是扩展JDK。特别的，当从扩展目录加载类是有一些安全限制。

 

Windows Note:

ant.bat脚本使用以下环境变量：ANT_HOME, CLASSPATH 以及 JAVA_HOME。确定已经设置ANT_HOME和JAVA_HOME，同时它们中不能含有引号（不论是单引号还是双引号），并且不能以\结尾或包含 /.这样环境变量会不设置或为空。

 

检查安装

您可以通过打开一个shell窗口，输入ant可以验证ant是否安装成功。您应该会得到如下信息：

 

Buildfile: build.xml does not exist!

Build failed

 

Ant已经正常工作。出现这种提示的原因是您需要为您的工程编写特定的buildfile。使用ant –version命令可以得到如下输出：

 

Apache Ant version 1.7.0 compiled on December 13 2006

 

可选任务

Ant支持许多可选任务。可选任务是指那些需要外部库才能运行的任务。可选任务是和ant的内核一起打包的。

每一个可选任务需要的外部库在Library Dependencies一节有详细说明。这些外部库必须添加到Ant的classpath中，使用下列任何一种方式都可以：

l         加入ANT_HOME/lib目录。这样Jar文件可以被Ant的所有用户和工程可见。

l         加入/home/kev/.ant/lib目录。这种方式运行不同的用户为Ant安装新库。添加到目录下的所有Jar文件使用命令行的Ant都可见。

l         在命令行中使用-lib参数。可以使用case-by-case的方式添加新的Jar文件。

l         加入CLASSPATH环境变量。不要使用这种方式，这会让Jar文件为所有的Java程序可见，可能导致无停止的调用请求。

l         添加到任务自己的<classpath>标签中。例如，使用Ant1.7.1运行<junit>任务但Ant的classpath中没有junit.jar文件，只要它在运行任务时包含在classpath中即可。
如果可能，这种情况是最提倡的，因为Ant脚本可以确定从最合适的路径加载库：通过basedir的相对目录（如果您将库保存在工程中进行版本控制），根据Ant的属性，环境变量，Ivy下载，任何一种方式。

IDE使用不同的方式添加外部的Jar文件和Ant的第三方任务。通常这些配置使用配置对话框完成。有时，添加到工程中的Jar文件自动添加到Ant的classpath中。

CLASSPATH环境变量

CLASSPATH环境变量是出现问题最多的部分。因为诊断Ant用户提出的问题的周期很长，同时很多bug都是关于“ant.bat”不能正常运行的bug，这种bug的修改一般会被开发者拒绝，拒绝理由是“这是配置文件，不是bug。”使用下列步骤可以节省您很多时间：

1.       不设置CLASSPATH。Ant不需要它，它经常造成令人迷惑或重大的问题。

2.       如果您忽略第一条规则，不要在CLASSPATH中添加引号，甚至当目录中含有空格时。这会让Ant无法运行，并且也没有必要。

3.       如果您忽略第一条规则，不要在CLASSPATH后面添加反斜杠，这使得Ant不能引用字符串。同时，这也不是环境变量的正确操作方式，即使添加一个DOS的目录时。

4.       您可以使用“-noclasspath”命令行参数来禁止Ant适合用CLASSPATH环境变量。这在测试classpath-related问题时很容易。

CLASSPATH问题的一般征兆是ant不能正常运行，抛出类似不能找到org.apache.tools.ant.launch.Launcher，或者，您错误的使用引号或反斜杠，以及其他怪异的Java启动异常。排查这种问题时，运行“ant -noclasspath”命令或不设置CLASSPATH环境变量。

您可以在脚本中使用以下方法拒绝使用环境变量：

 

<property environment="env."/>

<property name="env.CLASSPATH" value=""/>

<fail message="Unset $CLASSPATH / %CLASSPATH% before running Ant!">

    <condition>

        <not>

            <equals arg1="${env.CLASSPATH}" arg2=""/>

        </not>

    </condition>

</fail>

 

代理配置

一些内置的或第三方任务使用网络从HTTP服务器中得到文件。如果您在防火墙后面并且使用代理服务器，Ant需要配置代理。有以下几种配置方式：

l         使用Java1.5
当您使用Java1.5启动Ant时，可以尝试使用“-autoproxy”进行自动代理设置。

l         显式使用JVM属性
属性以及这个控制JVM代理行为的方式，请查看Sun的文档。如果要在Ant中设置它们，将它们声明在ANT_OPTS环境变量中。这是在不经常移动的系统中配置的最好方式。如果您使用笔记本电脑，请按照实际的需要修改这些设置。

l         在构建文件中配置
如果您使用的构建文件总是在防火墙之后，使用<setproxy>标签可以进行代理设置（它也是通过设置JVM属性实现）。如果您这样做，强烈建议使用ant属性定义代理服务器主机名和端口号，这样其他应用更可以直接覆盖缺省设置。

Ant团队知道这是不够的。在直到JVM自动代理设置可以在所有情况下使用之前，通过ANT_ARGS进行显式的JVM设置是最好的选择。在Ant的命令行中设置属性是没用的，因为这些属性是Ant属性，不是JVM的属性。这意味着不能按照下列方式进行命令行设置：

 

ant -Dhttp.proxyHost=proxy -Dhttp.proxyPort=81

 

所有上述做法都只是设置了两个Ant属性。

代理的另一个问题是使用认证代理。Ant不能超出JVM在这里所做的，这样做很难进行远程诊断，测试和修改关联代理的问题，在安全代理后面的用户需要很长时间进行JVM书信配置，直到成功。

Windows 和 OS/2

假设ANT安装在c:\ant\目录下，以下方式设置了环境变量：

 

set ANT_HOME=c:\ant

set JAVA_HOME=c:\jdk-1.5.0.05

set PATH=%PATH%;%ANT_HOME%\bin

 

Linux/Unix (bash)

假设ANT安装在/usr/local/ant目录下，以下方式设置了环境变量：

 

export ANT_HOME=/usr/local/ant

export JAVA_HOME=/usr/local/jdk-1.5.0.05

export PATH=${PATH}:${ANT_HOME}/bin

 

Linux/Unix (csh)

setenv ANT_HOME /usr/local/ant

setenv JAVA_HOME /usr/local/jdk/jdk-1.5.0.05

set path=( $path $ANT_HOME/bin )

 

有一个象征性的连接到JVM/JDK版本号可以更准确的进行升级。

RPM version from jpackage.org

JPackage project发布Ant的RPM版本。使用这个版本，不需要配置JAVA_HOME 或 ANT_HOME环境变量，同时RPM安装程序会在您的环境中将Ant配置称为可执行的。

注意：从Ant1.7.0开始，如果ANT_HOME环境变量已经配置，那么jpackage发布包可以忽略。

在JPackage中，可选的Jar文件有两种操作方式。最简单的方式是从JPackage中得到外部库。（注意：对于这种库，您需要得到外部包和ant中使用的外部包）。

然而，JPackage没有打包proprietary software，因为一些可选包依赖proprietary jars，必须使用如下方式进行设置。这违背了JPackage的思想，但如果您需要proprietary packages，就要这样设置。例如，您向安装对starteam的支持，但jpakcage不支持，按照如下方式设置：

1.                决定怎样部署而外的jar文件。一种方法是部署到$ANT_HOME/lib目录，对于JPackage来说一般是/usr/share/ant/lib目录。另一个稍微复杂的方法是在您的home目录中创建.ant/lib子目录，然后将不是jpackage的ant jar文件放在这里，这样做可以避免和jpakcage原有的jar文件混淆。

2.                从Apache Ant site下载non-jpackage二进制发布包。

3.                将文件解压到临时文件夹。

4.                拷贝关联jar到第一步选择的文件夹中，在这里是ant-starteam.jar。

5.                将proprietary jar拷贝都相同目录中。

最后，如果因为一些原因，您的系统中同时使用JPackage和Apache 版本的Ant，如果您想运行Apache版本（可能使用一个绝对文件名），应该使用Ant的“--noconfig”命令行，避免使用JPackage的classpath。

高级

有许多变量可以在ant运行时使用。您至少需要了解以下几个：

l         Ant的classpath中必须有ant.jar文件以及您选择作为JAXP-compliant XML解析器的jars/classes。

l         如果您需要使用JDK的功能（例如javac任务或rmic任务），tools.jar文件必须添加到classpath。bin目录中Ant提供的脚本，在JAVA_HOME环境变量设置或会自动添加需要的JDK类。

l         当您运行平台相关的应用程序时，例如exec任务或cvs任务，ant.home属性文件必须保存到安装Ant的目录下。再次说明，这个路径使用ANT_HOME环境变量的值在Ant脚本中进行设置。

扩展的ant shell脚本都支持ANT_OPTS环境变量，这个环境变量可以为ant提供扩展的属性。一些脚本同时需要读取保存在user home目录下的其他脚本来运行部分选项。详细信息需要查看您使用平台中相应脚本文件的源代码。

编译Ant

如果需要编译Ant源代码，您可以安装Ant的源码发布版本，也可以从SVN中下载ant模块。

当您安装源代码后，需要修改安装目录。

将JAVA_HOME环境变量设置为JDK安装目录。详细信息请查看安装Ant一节。

注意：Ant启动执行的过程是贪婪编译的方式，和Sun的javac或jikes一致，与gcj或kjc不一致。

确定您已经下载可编译相关的所有jar文件。这些需要添加到源码目录树中的lib/optional目录下。不同属性需要的Jar文件请参考库依赖一节。注意，只是在编译Ant的过程中需要辅助的Jar文件。如果需要运行Ant，还要按照安装Ant一节中的描述提供需要的Jar文件。

您已经准备好编译Ant了：

 

build -Ddist.dir=<directory_to_contain_Ant_distribution> dist    (Windows)

sh build.sh -Ddist.dir=<directory_to_contain_Ant_distribution> dist    (Unix)

以上命令在您指定的目录下创建Ant的二进制发布版。

以上构建的具体过程如下所示：

l         如果需要会启动Ant。启动过程涉及运行Ant需要足够Ant代码的手动编译。启动Ant在以后的编译过程中用到。

l         使用build脚本中的相应参数调用启动Ant。这样，这些参数定义了一个Ant属性值并且在Ant自己的build.xml文件中指定dist目标。

l         创建ant.jar以及ant-launcher.jar文件。

l         创建需要关联类库才可以使用的可选Jar。如果在ANT_HOME/lib/optional目录中找不到相应的Jar文件，相应的Jar文件不会被创建。例如，只有当junit.jar文件在可选库目录中存在时，才创建ant-junit.jar文件。

大多数情况下，build脚本已经帮助您做好了ant的初始运行。可以通过在build脚本文件中设置相应特性的方式关闭自动的Ant初始运行，这样您需要手动运行。运行bootstrap.bat（Windows）或bootstrap.sh (UNIX)创建初始运行版本的Ant。

如果您想将生成的版本保存到当前ANT_HOME目录下，您可以使用下列方式实现：

 

build install    (Windows)

sh build.sh install    (Unix)

 

 

可以避免生成Javadoc的过程，如果需要，使用下列方式：

 

build install-lite    (Windows)

sh build.sh install-lite    (Unix)

 

上述命令只生成bin和lib目录。

install和install-lite两个目标都会覆盖当前的ANT_HOME。

依赖库

如果你使用相应Ant特性，以下是Ant的classpath中需要的类库文件。注意，使用映射时只需要一个regexp库（同时，Java1.4及以后版本包含了regexp，Ant可以自动找到）。您同时需要安装包括特定任务定义的Ant可选Jar，才可以使用相应任务。请参靠安装/可选任务一节。

 

Jar Name	Needed For	Available At
An XSL transformer like Xalan	style task	If you use JDK 1.4+, an XSL transformer is already included, so you need not do anything special. XALAN : http://xml.apache.org/xalan-j/index.html
jakarta-regexp-1.3.jar	regexp type with mappers	http://jakarta.apache.org/regexp/
jakarta-oro-2.0.8.jar	regexp type with mappers and the perforce tasks To use the FTP task, you need jakarta-oro 2.0.8 or later, and commons-net	http://jakarta.apache.org/oro/
junit.jar	<junit> task. May be in classpath passed to task rather than Ant's classpath.	http://www.junit.org/
xalan.jar	junitreport task	http://xml.apache.org/xalan-j/
stylebook.jar	stylebook task	SVN repository of http://xml.apache.org/svn.html
antlr.jar	antlr task	http://www.antlr.org/
bsf.jar	script task Note: Ant 1.6 and later require Apache BSF, not the IBM version. I.e. you need BSF 2.3.0-rc1 or later. Note: BSF 2.4.0 is needed to use a post 1.5R3 version of rhino's javascript. Note: BSF 2.4.0 uses jakarata-commons-logging so it needs the commons-logging.jar.	http://jakarta.apache.org/bsf/
Groovy jars	Groovy with script and scriptdef tasks You need to get the groovy jar and two asm jars from a groovy installation. The jars are groovy-[version].jar, asm-[vesion].jar and asm-util-[version].jar and antlr-[version].jar. As of groovy version 1.0-JSR-06, the jars are groovy-1.0-JSR-06.jar, antlr-2.7.5.jar, asm-2.2.jar and asm-util-2.2.jar. Alternatively one may use the embedded groovy jar file. This is located in the embedded directory of the groovy distribution. This bundles all the needed jar files into one jar file. It is called groovy-all-[version].jar.	http://groovy.codehaus.org/ The asm jars are also available from the creators of asm - http://asm.objectweb.org/
netrexx.jar	netrexx task, Rexx with the script task	http://www.ibm.com/software/awdtools/netrexx/download.html
js.jar	Javascript with script task If you use Apache BSF 2.3.0-rc1, you must use rhino 1.5R3 (later versions of BSF (e.g. version 2.4.0) work with 1.5R4 and higher).	http://www.mozilla.org/rhino/
jyt