kaz 02/03/05 08:21:47
Modified: xdocs build-file.xml
Log:
Revamped the build-file documentation. The document presents an
overview of all the build files that are generated by Maven, then each
build file is discussed in detail as well as the targets in each build
file. Finally, sample use of Maven delegators is presented for new
users.
Revision Changes Path
1.8 +335 -144 jakarta-turbine-maven/xdocs/build-file.xml
Index: build-file.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/xdocs/build-file.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- build-file.xml 5 Mar 2002 01:41:20 -0000 1.7
+++ build-file.xml 5 Mar 2002 16:21:47 -0000 1.8
@@ -7,24 +7,29 @@
</properties>
<body>
- <section name="Maven Build File">
+ <section name="Maven Build Files">
<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
+ href="project-descriptor.html">project descriptor</a>.
+ The build files that Maven <a href="getting-started.html">
+ generates</a> are stored in the <code>maven</code> to avoid
+ clobbering project-specific build files.
+ </p>
+ <p>
+ The Ant build files, generated by Maven, contain 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.
+ be provided such as a CLI, GUI, 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
+ This document describes the various Ant build files and 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,
@@ -33,58 +38,119 @@
<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:
+ The current recommended approach to using Maven is to add
+ delegators to these Maven-provided targets in your project's
+ main build file. This will enable you to use your existing
+ build file with the additional Maven functionality. For
+ example, you could add the following to your build.xml file to
+ Maven:
+ </p>
+ <source><![CDATA[
+<!-- maven:start -->
+
+<!-- ======================================================== -->
+<!-- D E L E G A T O R S -->
+<!-- ======================================================== -->
+
+<target name="maven:site">
+ <ant antfile="maven/build-docs.xml" target="site"/>
+</target>
+
+<target name="maven:jar">
+ <ant antfile="maven/build-maven.xml" target="jar"/>
+</target>
+
+<target name="maven:install-jar">
+ <ant antfile="maven/build-maven.xml" target="install-jar"/>
+</target>
+
+<target name="maven:env">
+ <ant antfile="maven/build-maven.xml" target="env"/>
+</target>
+
+<target name="maven:docs">
+ <ant antfile="maven/build-docs.xml" target="docs"/>
+</target>
+
+<target name="maven:test">
+ <ant antfile="maven/build-test.xml" target="test"/>
+</target>
+
+<target name="maven:clean">
+ <ant antfile="maven/build-maven.xml" target="clean"/>
+</target>
+
+<target name="maven:metrics">
+ <ant antfile="maven/build-metrics.xml" target="metrics"/>
+</target>
+
+<target name="maven:dist">
+ <ant antfile="maven/build-maven.xml" target="dist"/>
+</target>
+
+<target name="maven:deploy-site">
+ <ant antfile="maven/build-docs.xml" target="deploy-site"/>
+</target>
+
+<target name="maven:gump-descriptor">
+ <ant antfile="maven/build-maven.xml" target="gump-descriptor"/>
+</target>
+
+<target name="maven:javadocs">
+ <ant antfile="maven/build-docs.xml" target="javadocs"/>
+</target>
+
+<target name="maven:compile">
+ <ant antfile="maven/build-maven.xml" target="compile"/>
+</target>
+
+<target name="maven:update-jars">
+ <ant antfile="maven/build-maven.xml" target="update-jars"/>
+</target>
+
+<!-- maven:end -->
+ ]]></source>
+ <p>
+ It is important to note the use of the <code>maven:start</code>
+ and <code>maven:end</code> delimeters. This will enable Maven
+ to be upgraded in a seamless manner.
+ </p>
+ <p>
+ The following is a brief overview of the various build files
+ that are generated by Maven in the <code>maven</code> directory.
+ Targets in each of these files are discussed in subsequent
+ sections.
</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><th>Build File</th><th>Description</th></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>metrics</td>
- <td>Generate metric information for the source.</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>
+ <td><a href="#build-maven.xml">build-maven.xml</a></td>
+ <td>
+ Contains targets to compile and generate distributions and
+ jars.
+ </td>
</tr>
<tr>
- <td>install-jar</td>
- <td>Installs JAR file in local filesystem.</td>
+ <td><a href="#build-docs.xml">build-docs.xml</a></td>
+ <td>
+ Contains targets to generate all of the documentation
+ including cross-referenced sources, change logs, and site
+ documentation.
+ </td>
</tr>
<tr>
- <td>gump-descriptor</td>
- <td>Generate a <a href="/gump.html">Gump</a> project descriptor.</td>
+ <td><a href="#build-metrics">build-metrics.xml</a></td>
+ <td>
+ Contains targets to generate all of the source metrics of a
+ project.
+ </td>
</tr>
<tr>
- <td>clean</td>
- <td>Cleans the build directory.</td>
+ <td><a href="#build-test.xml">build-test.xml</a></td>
+ <td>
+ Contains targets to run all of the unit tests and run-time
+ tests.
+ </td>
</tr>
</table>
<p>
@@ -104,7 +170,7 @@
<td>
Specifies the directory on the file system that downloaded
jars are stored. Used by the
- <a href="#update-jars">update-jars</a> target.
+ <a href="#maven:update-jars">maven:update-jars</a> target.
</td>
</tr>
<tr>
@@ -112,7 +178,7 @@
<td>Yes</td>
<td>
Specifies a proxy server to use when downloading jars. Used
- by the <a href="#update-jars">update-jars</a> target.
+ by the <a href="#maven:update-jars">maven:update-jars</a> target.
</td>
</tr>
<tr>
@@ -121,7 +187,7 @@
<td>
Specifies the port of the proxy server to use when
downloading jars. Used by the
- <a href="#update-jars">update-jars</a> target.
+ <a href="#maven:update-jars">maven:update-jars</a> target.
</td>
</tr>
<tr>
@@ -129,22 +195,64 @@
<td>Yes</td>
<td>
Specifies that Aspects are included during compilation. Used by the
- <a href="#compile">compile</a> target.
+ <a href="#maven:compile">maven:compile</a> target.
</td>
</tr>
</table>
- <p>
- <!-- Placeholder to add whitespace until site.dvsl is fixed -->
- </p>
</section>
- <section name="Ant Target Descriptions">
+ <section name="build-maven.xml">
<p>
- The following sections detail the Ant targets included in
- build file provided by Maven.
+ The following is an overview of the most common targets in this
+ build file:
</p>
- <subsection name="update-jars">
+ <table>
+ <tr><th>Target</th><th>Description</th></tr>
+ <tr>
+ <td><a href="#maven:env">maven:env</a></td>
+ <td> Displays the current environment settings.</td>
+ </tr>
+ <tr>
+ <td><a href="#maven:update-jars">maven:update-jars</a></td>
+ <td>Updates JARs required for building.</td>
+ </tr>
+ <tr>
+ <td><a href="#maven:compile">maven:compile</a></td>
+ <td>Compile project source code.</td>
+ </tr>
+ <tr>
+ <td><a href="#maven:jar">maven:jar</a></td>
+ <td> Generates the JAR file (default build target).</td>
+ </tr>
+ <tr>
+ <td><a href="#maven:dist">maven:dist</a></td>
+ <td>Generates source and binary distributions.</td>
+ </tr>
+ <tr>
+ <td><a href="#maven:install-jar">maven:install-jar</a></td>
+ <td>Installs JAR file in local filesystem.</td>
+ </tr>
+ <tr>
+ <td><a href="#maven:gump-descriptor">maven:gump-descriptor</a></td>
+ <td>Generate a <a href="/gump.html">Gump</a> project descriptor.</td>
+ </tr>
+ <tr>
+ <td><a href="#maven:clean">maven:clean</a></td>
+ <td>Cleans the build directory.</td>
+ </tr>
+ </table>
+ <p/>
+ <subsection name="maven:env">
+ <p>
+ The <code>maven:env</code> target displays the current
+ classpath which is generated automatically from the <code><a
+ href="project-descriptor.html#dependencies">dependencies</a></code>
+ element of the project descriptor. It is used mostly for
+ debugging purposes.
+ </p>
+ </subsection>
+ <subsection name="maven:update-jars">
<p>
- The <code>update-jars</code> target uses HTTP to download the jar files
+ The <code>maven:update-jars</code> target uses HTTP to download the jar
files
required to build the project. The dependencies of
a project are determined from the
<a
href="project-descriptor.html#dependencies"><code>dependencies</code></a>
@@ -166,9 +274,9 @@
Internet.
</p>
</subsection>
- <subsection name="compile">
+ <subsection name="maven:compile">
<p>
- The <code>compile</code> target compiles all of the source
+ The <code>maven: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>
@@ -193,78 +301,9 @@
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">
+ <subsection name="maven:jar">
<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, source metrics, 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. In addition, any
- documentation in the <code>xdoc</code> directory is
- transformed to HTML.
- </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.
- Additionally, all images from the <code>xdoc/images</code>
- directory are copied to the <code>docs/images</code> directory.
- </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="metrics">
- <p>
- The <code>metrics</code> target generates metrics on the
- project's source code. These metrics include dependencies,
- number of classes, types of classes, etc. This information
- can be presented in various formats such as text and in a gui.
- To use the gui, you must set the Ant property
- <code>use.jdepend.gui</code>. In addition, metrics are
- generated as HTML when the <code>docs</code> target is
- invoked.
- </p>
- </subsection>
- <subsection name="jar">
- <p>
- The <code>jar</code> target generates the project's jar file.
+ The <code>maven: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
@@ -282,9 +321,9 @@
<code>projectid-version</code>.
</p>
</subsection>
- <subsection name="dist">
+ <subsection name="maven:dist">
<p>
- The <code>dist</code> target generates both a binary and
+ The <code>maven: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
@@ -303,16 +342,16 @@
<code>projectid-version-src</code> for source distributions.
</p>
</subsection>
- <subsection name="install-jar">
+ <subsection name="maven:install-jar">
<p>
- The <code>install-jar</code> target installs the project's jar
+ The <code>maven: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="gump-descriptor">
+ <subsection name="maven:gump-descriptor">
<p>
- The <code>gump-descriptor</code> target builds a <a
+ The <code>maven:gump-descriptor</code> target builds a <a
href="/gump.html">Gump</a> project descriptor from a Maven
project descriptor. This target is for those that wish to
participate in the Gump continuous integration project. In
@@ -321,10 +360,162 @@
interim.
</p>
</subsection>
- <subsection name="clean">
+ <subsection name="maven:clean">
<p>
- The <code>clean</code> target deletes the build directory
+ The <code>maven:clean</code> target deletes the build directory
which is currently the <code>target</code> directory.
+ </p>
+ </subsection>
+ </section>
+ <section name="build-docs.xml">
+ <p>
+ The following is an overview of the most common targets in this
+ build file:
+ </p>
+ <table>
+ <tr><th>Target</th><th>Description</th></tr>
+ <tr>
+ <td><a href="#maven:docs">maven:docs</a></td>
+ <td>Generate HTML project documentation.</td>
+ </tr>
+ <tr>
+ <td><a href="#maven:javadocs">maven:javadocs</a></td>
+ <td>Generate the Javadoc API documentation.</td>
+ </tr>
+ <tr>
+ <td><a href="#maven:cvs-change-log">maven:cvs-change-log</a></td>
+ <td>Generate the change log from CVS.</td>
+ </tr>
+ <tr>
+ <td><a href="#maven:site">maven:site</a></td>
+ <td>
+ Generate the entire site including docs, javadocs,
+ change log, and cross-referenced sources.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#maven:deploy-site">maven:deploy-site</a></td>
+ <td>
+ Generate the entire site including docs, javadocs,
+ change log, and cross-referenced sources.
+ </td>
+ </tr>
+ </table>
+ <p/>
+ <subsection name="maven:docs">
+ <p>
+ The <code>maven: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, source metrics, 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. In addition, any
+ documentation in the <code>xdoc</code> directory is
+ transformed to HTML.
+ </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.
+ Additionally, all images from the <code>xdoc/images</code>
+ directory are copied to the <code>docs/images</code> directory.
+ </p>
+ </subsection>
+ <subsection name="maven:javadocs">
+ <p>
+ The <code>maven: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="maven:cvs-change-log">
+ <p>
+ The <code>maven:cvs-change-log</code> target generates a
+ change log for the project by parsing the output of a
+ <code>cvs log</code> command. This output is then sorted and
+ displayed in an easy to read manner. Developer names are
+ displayed by mapping usernames to full names using the <code>
+ <a href="project-descriptor.html#developers">developers</a>
+ </code> element from the project descriptor.
+ </p>
+ </subsection>
+ <subsection name="maven:site">
+ <p>
+ The <code>maven:site</code> target executes all of the targets
+ necessary to build the entire web site documentation. This
+ includes all site docs, javadocs, cross-referenced sources,
+ change logs, metrics, and unit testing reports.
+ </p>
+ </subsection>
+ </section>
+ <section name="build-metrics.xml">
+ <p>
+ The following is an overview of the most common targets in this
+ build file:
+ </p>
+ <table>
+ <tr><th>Target</th><th>Description</th></tr>
+ <tr>
+ <td><a href="#maven:metrics">maven:metrics</a></td>
+ <td>Generate metric information for the source.</td>
+ </tr>
+ </table>
+ <p/>
+ <subsection name="maven:metrics">
+ <p>
+ The <code>maven:metrics</code> target generates metrics on the
+ project's source code. These metrics include dependencies,
+ number of classes, types of classes, etc. This information
+ can be presented in various formats such as text and in a gui.
+ To use the gui, you must set the Ant property
+ <code>use.jdepend.gui</code>. In addition, metrics are
+ generated as HTML when the <code>docs</code> target is
+ invoked.
+ </p>
+ </subsection>
+ </section>
+ <section name="build-test.xml">
+ <p>
+ The following is an overview of the most common targets in this
+ build file:
+ </p>
+ <table>
+ <tr><th>Target</th><th>Description</th></tr>
+ <tr>
+ <td><a href="#maven:test">maven:test</a></td>
+ <td>Execute all the unit tests and run-time tests.</td>
+ </tr>
+ </table>
+ <p/>
+ <subsection name="maven:test">
+ <p>
+ The <code>maven: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>
</section>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
