利用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：瑪瑞從來只發自己寫的貼子。歡迎轉載。


    
        
    
    
    

原文轉自：http://www.anti-gravitydesign.com