利用ant来自动编译应用、发布应用、和制作应用的javadoc文件

利用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:＼mytry                    build.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.version          Version identifier for this application.

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

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

  deploy.home          The 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.home            The 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.debug        Should compilation include the debug option?

  compile.deprecation  Should 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 -->
    <mkdir    dir="${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 -->
    <copy  todir="${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}"/>
    <copy    todir="${deploy.home}">
      <fileset dir="${build.home}"/>
    </copy>

    <!-- Copy external dependencies as required -->
    <!-- *** CUSTOMIZE HERE AS REQUIRED BY YOUR APPLICATION *** -->
    <mkdir  dir="${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 -->
    <copy    todir="${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">

    <mkdir          dir="${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 -->
    <mkdir  dir="${build.home}"/>
    <copy todir="${build.home}">
      <fileset dir="web"/>
    </copy>

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

  </target>



</project>


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

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