You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@turbine.apache.org by ka...@apache.org on 2002/02/22 19:24:19 UTC
cvs commit: jakarta-turbine-maven/xdocs build-file.xml
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="pete@kazmier.com">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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>