kaz 02/02/22 10:24:19 Added: xdocs build-file.xml Log: Initial draft. This document describes the Ant build file that will be used by projects participating in Maven. The common targets are defined and how they relate to the Maven project descriptor is documented. There are a lot of links in the document to a non-existent document (project descriptor doc) that I am now about to write. Until the documentation for Maven is straightened out, you can see the rendered version of this page on my web server: http://www.kazmier.com/~kaz/maven/build-file.html Revision Changes Path 1.1 jakarta-turbine-maven/xdocs/build-file.xml Index: build-file.xml =================================================================== <?xml version="1.0"?> <document> <properties> <author email="[EMAIL PROTECTED]">Pete Kazmier</author> <title>Maven Build File Documentation</title> </properties> <body> <section name="Maven Build File"> <p> Maven utilizes <a href="http://jakarta.apache.org/ant";>Ant</a> to provide users with an easy-to-use and familiar interface to manage projects that have been described with a valid Maven <a href="project-descriptor.html">project descriptor</a>. The Ant build file, provided by Maven, contains several targets that can be used to control the various aspects of the project lifecycle such as compilation, execution of unit tests, generation of site documentation, and much much more. These targets utilize custom Ant tasks that provide a thin wrapper to the core of Maven. In the future, other interfaces to Maven may be provided such as a CLI or JMX. </p> <p> This document describes the various Ant targets that are available when using the Ant interface to Maven. All of the user-configurable Ant properties are also documented for reference. Recall, a valid Maven project descriptor is required to use this build file. Without the project descriptor, Maven cannot generate an object model for the project. In addition, the <code>maven.jar</code> file <b>must</b> be installed in <code>$ANT_HOME/lib</code> directory. Finally, the Ant property <code>${lib.repo}</code> must be defined (see below). </p> <p> The following is an overview of the most common targets that might be used to manage a project: </p> <table> <tr><th>Target</th><th>Description</th></tr> <tr> <td>usage</td> <td>Usage instructions.</td> </tr> <tr> <td>update-jars</td> <td>Updates JARs required for building.</td> </tr> <tr> <td>compile</td> <td>Compile project source code.</td> </tr> <tr> <td>test</td> <td>Runs the unit tests and run-time tests.</td> </tr> <tr> <td>docs</td> <td>Generate HTML project documentation.</td> </tr> <tr> <td>javadocs</td> <td>Generate the Javadoc API documentation.</td> </tr> <tr> <td>jar</td> <td> Generates the JAR file (default build target).</td> </tr> <tr> <td>dist</td> <td>Generates source and binary distributions.</td> </tr> <tr> <td>install-jar</td> <td>Installs JAR file in local filesystem.</td> </tr> <tr> <td>clean</td> <td>Cleans the build directory.</td> </tr> </table> <p> The following is an overview of the user-configurable properties used by this build file. Some of these properties are optional, while others are mandatory and must be set. These properties may be configured in the <code>${user.home}/build.properties</code> file. These properties are discussed in greater detail in conjunction with the Ant target in which they apply. </p> <table> <tr><th>Property</th><th>Optional?</th><th>Description</th></tr> <tr> <td>lib.repo</td> <td>No</td> <td> Specifies the directory on the file system that downloaded jars are stored. Used by the <a href="#update-jars">update-jars</a> target. </td> </tr> <tr> <td>proxy.host</td> <td>Yes</td> <td> Specifies a proxy server to use when downloading jars. Used by the <a href="#update-jars">update-jars</a> target. </td> </tr> <tr> <td>proxy.port</td> <td>Yes</td> <td> Specifies the port of the proxy server to use when downloading jars. Used by the <a href="#update-jars">update-jars</a> target. </td> </tr> <tr> <td>build.includes.aspects</td> <td>Yes</td> <td> Specifies that Aspects are included during compilation. Used by the <a href="#compile">compile</a> target. </td> </tr> </table> <p> <!-- Placeholder to add whitespace until site.dvsl is fixed --> </p> </section> <section name="Ant Target Descriptions"> <p> The following sections detail the Ant targets included in build file provided by Maven. </p> <subsection name="update-jars"> <p> The <code>update-jars</code> target downloads the jar files required to build the project using HTTP. The dependencies of a project are determined from the <a href="project-descriptor.html#dependencies"><code>dependencies</code></a> element of the Maven project descriptor. </p> <p> The downloaded jars are stored in the directory specified by <code>lib.repo</code> property (note: this directory must exist). As an optimization, if <code>lib.repo</code> already contains the necessary jar file, Maven does not download it unless a newer jar file is available in which case it replaces the old version. </p> <p> Users behind a firewall can optionally set the <code>proxy.host</code> and <code>proxy.port</code> properties. If these properties are set, Maven will use the specified host and port when downloading jar files from the Internet. </p> </subsection> <subsection name="compile"> <p> The <code>compile</code> target compiles all of the source files that are part of the project. The list of source files, more specifically the directories, is determined from the <a href="project-descriptor.html#sourceDirectories"><code>sourceDirectories</code></a> element of the Maven project descriptor. </p> <p> The classpath used when compiling is composed of all the jar files located in the <code>lib.repo</code> directory. Upon completion, the resulting class files are placed in the <code>target/classes</code> directory relative to the base directory of the project. If this directory does not exist, it is created. </p> <p> Users interested in compiling with aspects enabled can set the <code>build.includes.aspects</code> property. If this property is set, the AspectJ compiler will be used to compile the source [TODO: add a link to a page that describes how to setup one's AspectJ environment]. The aspect source files are determined from the <a href="project-descriptor.html#aspectSourceDirectories"><code>aspectSourceDirectories</code></a> element of the Maven project descriptor. </p> </subsection> <subsection name="test"> <p> The <code>test</code> target executes all of the unit tests (junit) and run-time tests of the project. First, the source for all of the tests is compiled. The location of the test source code is determined from the <a href="project-descriptor.html#testSourceDirectories"><code>testSourceDirectories</code></a> element of the Maven project descriptor. In addition, the <a href="project-descriptor.html#unitTestClassEntries"><code>unitTestClassEntries</code></a> and <a href="project-descriptor.html#runtimeTestClassEntries"><code>runtimeTestClassEntries</code></a> specify the actual test classes to invoke. </p> <p> The results of the tests are placed in the <code>test-reports</code> directory relative to the base directory of the project. If this directory does not exist, it is created. </p> </subsection> <subsection name="docs"> <p> The <code>docs</code> target builds the project's HTML documentation using DVSL. This documentation includes a front page for the project with links to the list of developers, mailing-lists, dependencies, and other project specified documentation in xdoc format. The documentation for the project is determined from various elements of the <a href="project-descriptor.html#project"><code>project</code></a> element of the Maven project descriptor as well as the <a href="project-descriptor.html#documentation"><code>documentation</code></a> element. </p> <p> [FIXME: Waiting to see what comes of the docuemtation. Its still being worked out. As soon as its complete, I've revise this section appropriately.] </p> <p> The generated HTML documentation is placed in the <code>docs</code> directory relative to the base directory of the project. If this directory does not exist, it is created. </p> </subsection> <subsection name="javadocs"> <p> The <code>javadocs</code> target builds the project's API documentation using the JavaDoc facility. This documentation is appropriately titled and copyrighted with information provided from various elements of the <a href="project-descriptor.html#project"><code>project</code></a> element of the Maven project descriptor. </p> <p> The generated API documentation is placed in the <code>docs/apidocs</code> directory relative to the base directory of the project. If this directory does not exist, it is created. </p> </subsection> <subsection name="jar"> <p> The <code>jar</code> target generates the project's jar file. This is the default target of the build file. The contents of the jar file include the compiled classes located in <code>target/classes</code> and any other additional jar resources specified by the <a href="project-descriptor.html#jarResources"><code>jarResources</code></a> element of the Maven project descriptor. These additional resources can might include images or configuration files. </p> <p> The generated jar file is placed in the <code>target</code> directory relative to the base directory of the project. The <a href="project-descriptor.html#project"><code>project</code></a> element of the Maven project descriptor is used when creating the name of the jar file. The current naming convention is <code>projectname-version</code>. </p> </subsection> <subsection name="dist"> <p> The <code>dist</code> target generates both a binary and source distributions of the project. The binary distribution includes the jar files as well as documentation. The source distribution includes all of the source as well as both the <code>build.xml</code> and <code>default.properties</code> required for building the project. Both distributions are then packaged into <code>tar.gz</code> and <code>zip</code> format. </p> <p> The generated packages are placed in the <code>target</code> directory relative to the base directory of the project. The <a href="project-descriptor.html#project"><code>project</code></a> element of the Maven project descriptor is used when creating the name of the distributions. The current naming convention is <code>projectname-version</code> for binary distributions and <code>projectname-version-src</code> for source distributions. </p> </subsection> <subsection name="install-jar"> <p> The <code>install-jar</code> target installs the project's jar file into the <code>${lib.repo}</code> directory. If the jar file has not been created, it is first built. </p> </subsection> <subsection name="clean"> <p> The <code>clean</code> target deletes the build directory which is currently the <code>target</code> directory. </p> </subsection> </section> </body> </document>
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
