利用ant来自动编译应用、发布应用、和制作应用的javadoc文档
玛瑞2002-4-26
=========================================


如果你是在用文本编辑器制作你的web应用，那么你可以在半小时内体会到ant的强大帮助：

1）简介ant
ant是java世界推崇的编译发布工具。

它是免费公开源代码的软件。

如果你用过makefile，你就可以理解这句话：ant是跨平台的makefile。
不只如此,ant是很瞧不上makefile的，这意味着ant还有其它很多绝活。

不过，对于我们入门者来说，还是实用为上、够用就行！

2）下载ant

ant主页
http://jakarta.apache.org/ant/index.html
ant二进制下载
http://jakarta.apache.org/builds/jakarta-ant/release/v1.4.1/bin/

3）装载ant

（1）解开jakarta-ant-1.4.1-bin.zip或jakarta-ant-1.4.1-bin.tar.gz到一个目录，
这个目录就叫ant目录
（2）将ant目录添加到系统path中。

4）运行ant
在终端窗口，在任何包含build.xml的目录下，运行ant，ant会自动执行此脚本中命令。

5）应用ant的例子

（1）获得例子的模板
假设tomcat被安装在win2000下硬盘G上，即tomcat目录是
“G:\jakarta-tomcat-4.0.1\”，则此模板在如下目录中：
“G:\jakarta-tomcat-4.0.1\webapps\tomcat-docs\appdev\sample”

建议你将此目录下内容拷贝至其它地方，以供学习。如拷贝到："G:\mytry\"

应用程序的文件结构及关键文件如下：
G:\mytrybuild.xml
 docs src web WEB-INF web.xml

其中：
build.xml是ant构建应用程序的脚本。
docs\是你自己提供应用程序文档（不包含javadoc）的地方
src\等同于tomcat应用结构中的“根目录\WEB-INF\classes\"目录，
web\等同于tomcat应用结构中的根目录
web\WEB-INF\对应于tomcat应用结构中的“根目录\WEB-INF\”目录
但不包括“根目录\WEB-INF\classes\"目录
“根目录\WEB-INF\”用来存放class和servlet以及
其它不允许用户直接访问的东东。
web\WEB-INF\web.xml等同于tomcat应用结构中的“根目录\WEB-INF\web.xml”文件，
即应用发布描述

（2）加入你自己的文件
假设你已有了包含jsp、html、java代码的应用程序。不要改变任何代码。
将jsp、html及其它静态内容按照原来的文件结构复制到web\目录下。
将java代码按原来的文件结构复制到src\目录下。

假设你新建文件，也应按照以下原则来编写：
在各个文件中，对"\WEB-INF\classes\"的引用就相当于对"src\"的引用。
其它照旧。

（3）在终端窗口中，进入"G:\mytry\"目录，运行命令“ant”。
ant会自动在此目录下建立目录:build，并在其中建立编译后的应用程序结构。
ant可以自动发布这个目录，即将其拷贝到tomcat的webapps目录下。

（4）执行不同的任务
在这个模板中，主要提供以下任务：
运行“ant clean”，则清除编译产生的文件结构，即删除build目录
运行“ant build”，则创建build目录、编译构建应用程序
运行“ant deploy”，则先执行build任务，再将build目录下内容发布到tomcat
运行“ant javadoc”，则先执行build任务，再创建dist目录，
并在此目录下自动生成应用程序javadoc

（5）build.xml的分析和修改

以下是build.xml及其修改说明：(需修改的地方用汉字说明)

只需修改3到4处！适用于任何tomcat应用。

你甚至根本不需要知道ant的具体用法。
每次修改了应用，直接运行ant，它就按照这个脚本编译和发布。
每次只编译和发布修改过的东东。


------------------ build.xml example for tomcat

<!-- A "project" describes a set of targets that may be requested
 when Ant is executed.The "default" attribute defines the
 target which is executed if no specific target is requested,
 and the "basedir" attribute defines the current working directory
 from which Ant executes the requested task.This is normally
 set to the current working directory.
-->


<project name="My Project" default="compile" basedir=".">
//将name的值改为应用程序的名字，即发布到tomcat的名字
//将default的值改为你需要的缺省任务（运行"ant"不指明任务时执行的任务）
//例如：<project name="mytry" default="deploy" basedir=".">

<!-- ===================== Property Definitions =========================== -->

<!--

Each of the following properties are used in the build script.
Values for these properties are set by the first place they are
defined, from the following list:
* Definitions on the "ant" command line (ant -Dcatalina.home=xyz compile)
* Definitions from a "build.properties" file in the top level
source directory
* Definitions from a "build.properties" file in the developer's
home directory
* Default definitions in this build.xml file

You will note below that property values can be composed based on the
contents of previously defined properties.This is a powerful technique
that helps you minimize the number of changes required when your development
environment is modified.Note that property composition is allowed within
"build.properties" files as well as in the "build.xml" script.

-->



<!-- ==================== File and Directory Names ======================== -->

<!--

These properties generally define file and directory names (or paths) that
affect where the build process stores its outputs.

app.name Base name of this application, used to
 construct filenames and directories.
 Defaults to "myapp".

app.versionVersion identifier for this application.

build.home The directory into which the "prepare" and
 "compile" targets will generate their output.
 Defaults to "build".

catalina.homeThe directory in which you have installed
 a binary distribution of Tomcat 4.This will
 be used by the "deploy" target.

deploy.homeThe name of the directory into which the
 deployment hierarchy will be created, and into
 which the build directory will be copied.
 Defaults to "${catalina.home}/webapps/${app.name}".

dist.homeThe name of the base directory in which
 distribution files are created.
 Defaults to "dist".

-->

<property name="app.name"value="myapp"/>
//将value的值改为应用程序的名字，即发布到tomcat的名字
//例如：<property name="app.name"value="mytry"/>

<property name="app.version" value="1.0"/>
<property name="build.home"value="build"/>
<property name="catalina.home" value="../../../.."/> <!-- UPDATE THIS! -->
//将value的值改为你安装tomcat的路径
//例如：<property name="catalina.home" value="G:\jakarta-tomcat-4.0.1\"/>

<property name="deploy.home" value="${catalina.home}/webapps/${app.name}"/>
<property name="dist.home" value="dist"/>



<!--==================== Compilation Control Options ==================== -->

<!--

These properties control option settings on the Javac compiler when it
is invoked using the <javac> task.

compile.debugShould compilation include the debug option?

compile.deprecationShould compilation include the deprecation option?

compile.optimize Should compilation include the optimize option?

-->

<property name="compile.debug" value="true"/>
<property name="compile.deprecation" value="false"/>
<property name="compile.optimize"value="true"/>



<!-- ==================== External Dependencies =========================== -->


<!--

Use property values to define the locations of external JAR files on which
your application will depend.In general, these values will be used for
two purposes:
* Inclusion on the classpath that is passed to the Javac compiler
* Being copied into the "/WEB-INF/lib" directory during execution
of the "deploy" target.

Because we will automatically include all of the Java classes that Tomcat 4
exposes to web applications, we will not need to explicitly list any of those
dependencies.You only need to worry about external dependencies for JAR
files that you are going to include inside your "/WEB-INF/lib" directory.

-->

<!-- Dummy external dependency -->
<!--
<property name="foo.jar"
 value="/path/to/foo.jar"/>
-->


<!-- ==================== Compilation Classpath =========================== -->

<!--

Rather than relying on the CLASSPATH environment variable, Ant includes
features that makes it easy to dynamically construct the classpath you
need for each compilation.The example below constructs the compile
classpath to include the servlet.jar file, as well as the other components
that Tomcat makes available to web applications automatically, plus anything
that you explicitly added.

-->

<path id="compile.classpath">

<!-- Include all JAR files that will be included in /WEB-INF/lib -->
<!-- *** CUSTOMIZE HERE AS REQUIRED BY YOUR APPLICATION *** -->
<!--
<pathelement location="${foo.jar}"/>
-->

<!-- Include all elements that Tomcat exposes to applications -->
<pathelement location="${catalina.home}/common/classes"/>
<fileset dir="${catalina.home}/common/lib">
<include name="*.jar"/>
</fileset>
<pathelement location="${catalina.home}/classes"/>
<fileset dir="${catalina.home}/lib">
<include name="*.jar"/>
</fileset>

</path>



<!-- ==================== All Target ====================================== -->

<!--

The "all" target is a shortcut for running the "clean" target followed
by the "compile" target, to force a complete recompile.

-->

<target name="all" depends="clean,compile"
 description="Clean build and dist, then compile"/>



<!-- ==================== Clean Target ==================================== -->

<!--

The "clean" target deletes any previous "build" and "dist" directory,
so that you can be ensured the application can be built from scratch.

-->

<target name="clean"
 description="Delete old build and dist directories">
<delete dir="${build.home}"/>
<delete dir="${dist.home}"/>
</target>



<!-- ==================== Compile Target ================================== -->

<!--

The "compile" target transforms source files (from your "src" directory)
into object files in the appropriate location in the build directory.
This example assumes that you will be including your classes in an
unpacked directory hierarchy under "/WEB-INF/classes".

-->

<target name="compile" depends="prepare"
 description="Compile Java sources">

<!-- Compile Java classes as necessary -->
<mkdirdir="${build.home}/WEB-INF/classes"/>
<javac srcdir="src"
destdir="${build.home}/WEB-INF/classes"
 debug="${compile.debug}"
 deprecation="${compile.deprecation}"
optimize="${compile.optimize}">
<classpath refid="compile.classpath"/>
</javac>

<!-- Copy associated resource files -->
<copytodir="${build.home}/library/classes">
<fileset dir="src" includes="**/*.properties"/>
</copy>

</target>



<!-- ==================== Deploy Target =================================== -->

<!--

The "deploy" target copies the contents of the build directory into a
location required by our servlet container, and picks up any external
dependencies along the way.AFter restarting the servlet container, you
can now test your web application.

-->

<target name="deploy" depends="compile"
 description="Deploy application to servlet container">

<!-- Copy the contents of the build directory -->
<mkdir dir="${deploy.home}"/>
<copytodir="${deploy.home}">
<fileset dir="${build.home}"/>
</copy>

<!-- Copy external dependencies as required -->
<!-- *** CUSTOMIZE HERE AS REQUIRED BY YOUR APPLICATION *** -->
<mkdirdir="${deploy.home}/WEB-INF/lib"/>
<!--
<copy todir="${deploy.home}/WEB-INF/lib" file="${foo.jar}"/>
-->

</target>



<!-- ==================== Dist Target ===================================== -->


<!--

The "dist" target creates a binary distribution of your application
in a directory structure ready to be archived in a tar.gz or zip file.
Note that this target depends on two others:
* "deploy" so that the entire web application (including external
dependencies) will have been assembled
* "javadoc" so that the application Javadocs will have been created

-->

<target name="dist" depends="deploy,javadoc"
 description="Create binary distribution">

<!-- Copy documentation subdirectory -->
<copytodir="${dist.home}/docs">
<fileset dir="docs"/>
</copy>

<!-- Create application JAR file -->
<jar jarfile="${dist.home}/${app.name}.war"
 basedir="${deploy.home}"/>

<!-- Copy additional files to ${dist.home} as necessary -->

</target>



<!-- ==================== Javadoc Target ================================== -->

<!--

The "javadoc" target creates Javadoc API documentation for the Java
classes included in your application.Normally, this is only required
when preparing a distribution release, but is available as a separate
target in case the developer wants to create Javadocs independently.

-->

<target name="javadoc" depends="compile"
 description="Create Javadoc API documentation">

<mkdirdir="${dist.home}/docs/api"/>
<javadoc sourcepath="src"
destdir="${dist.home}/docs/api"
 packagenames="mypackage.*"/>
//改为需要制作javadoc的包名。如果不做javadoc，这里不必改。
//例如：packagenames="see.*"/>

</target>



<!-- ==================== Prepare Target ================================== -->

<!--

The "prepare" target is used to create the "build" destination directory,
and copy the static contents of your web application to it.If you need
to copy static files from external dependencies, you can customize the
contents of this task.

Normally, this task is executed indirectly when needed.

-->

<target name="prepare">

<!-- Create build directory and copy static content -->
<mkdirdir="${build.home}"/>
<copy todir="${build.home}">
<fileset dir="web"/>
</copy>

<!-- Copy static files from external dependencies as needed -->

</target>



</project>


----------------------------------------------


btw：玛瑞从来只发自己写的贴子。欢迎转载。