kaz 02/03/28 10:57:11
Modified: xdocs bootstrap.xml download.xml getting-started.xml
project.xml
Added: xdocs install.xml integrate.xml powered.xml status.xml
use.xml
Log:
Changed the layout of the Maven site. It should be much easier for new
users to find their way through all of the docs. I created a new
section called "Getting Started" that has all the info one needs to get
started with Maven.
Also added a "News and Status" and "Powered By" section to the site.
Revision Changes Path
1.14 +155 -70 jakarta-turbine-maven/xdocs/bootstrap.xml
Index: bootstrap.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/xdocs/bootstrap.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- bootstrap.xml 26 Mar 2002 01:04:29 -0000 1.13
+++ bootstrap.xml 28 Mar 2002 18:57:11 -0000 1.14
@@ -11,30 +11,46 @@
<p>
Building Maven is a little different than your typical Java
build because Maven uses itself to build itself! Thus, in order
- to build, you must first bootstrap Maven. This document details
- the necessary steps to successfully build Maven.
+ to successfully build Maven, a bootstrapping process is required
+ to jumpstart the build. Fortunately, the details of this have
+ been encapsulated in a separate build file called
+ <code>build-bootstrap.xml</code>. This document details the
+ necessary steps to successfully build Maven from source. After
+ completing the process, not only will Maven be built, it will
+ also be installed on your system, which will enable you to build
+ any other Maven-enabled project (i.e. all Turbine projects).
</p>
<p>
- You'll need <a href="http://jakarta.apache.org/ant/";>Jakarta
- Ant</a> 1.4.1 or higher installed on your system, with
- junit.jar in your ant's <code>lib</code> directory.
+ Before you can build Maven, you'll need to make sure you have
+ <a href="http://jakarta.apache.org/ant/";>Ant</a> 1.4.1 or higher
+ installed on your system. In addition, you'll also need the <a
+ href="http://www.junit.org/";>JUnit</a> unit testing framework
+ installed. Be sure to install <code>junit.jar</code> in your
+ <code>$ANT_HOME/lib</code> directory. Failure to do so will
+ result in build errors.
</p>
<p>
- For the impatient (assuming you have <code>${lib.repo}</code>
+ For the impatient reader that doesn't want to read the rest of
+ this document, and assuming you have <code>${lib.repo}</code>
and optionally <code>${maven.home}</code> defined in your
- ${user.home}/build properties):
+ ${user.home}/build properties, type the following:
</p>
- <source><![CDATA[ant -f build-bootstrap.xml update-jars
-ant -f build-bootstrap.xml
-ant maven:update-jars
-ant maven:jar]]></source>
+ <source><![CDATA[
+ant -f build-bootstrap.xml bootstrap
+ ]]></source>
<p/>
+ <p>
+ If you are new to Maven, it is recommended that you read the
+ rest of the document as it explains the build process in a
+ little more detail.
+ </p>
<subsection name="Bootstrapping Maven">
<p>
- Maven must be bootstrapped before you can actually build the
- full distribution. First you must download the source from
- the <a href="/site/cvsindex.html"><code>jakarta-turbine-maven</code></a>
- CVS repository.
+ Before you can begin the process, you'll need to download the
+ source from the <code>jakarta-turbine-maven</code> CVS
+ repository. If you are not familiar with the Jakarta CVS
+ repositories, please see the
+ <a href="/site/cvsindex.html">documentation</a>.
</p>
<p>
Next, you must define the <code>${lib.repo}</code> property in
@@ -44,67 +60,136 @@
file, create one in your home directory and add the following
lines:
</p>
- <source><![CDATA[lib.repo = /path/to/some/directory
-maven.home = /path/to/some/other/directory]]></source>
+ <source><![CDATA[
+lib.repo = /path/to/some/directory
+maven.home = /path/to/some/other/directory
+ ]]></source>
<p>
The value of <code>${lib.repo}</code> property determines the
- location that the dependencies will be stored after they have
- been downloaded. Note: this directory must already exist in
- the filesystem. The other value, <code>${maven.home}</code>
- specifies the location that the build system will be stored
- after it has been generated. It is optional and has a default
- of <code>${user.home}/maven</code>.
- </p>
- <p>
- You'll then need to download the dependencies for Maven before
- you can start the bootstrapping process. This can be done
- automatically. Type the following to automatically download
- the required jars:
- </p>
- <source><![CDATA[ant -f build-bootstrap.xml update-jars]]></source>
- <p>
- After you've downloaded all of the dependencies, bootstrapping
- is very easy. Type the following:
- </p>
- <source><![CDATA[ant -f build-bootstrap.xml]]></source>
+ location that the dependencies (JARs) will be stored after
+ they have been downloaded. This repository is used by Maven
+ when building any Maven-enabled project. It is not unique to
+ the bootstrapping process. Note: this directory must already
+ exist in the filesystem. The other value,
+ <code>${maven.home}</code> specifies the location that the
+ Maven build system will be installed after it has been
+ generated. It is optional and has a default of
+ <code>${user.home}/maven</code>.
+ </p>
+ <p>
+ After setting up your properties file, you are now ready to
+ build and install Maven on your system using the bootstrapping
+ process. As mentioned earlier, the bootstrapping process is
+ defined in <code>build-bootstrap.xml</code>, and can be
+ initiated by typing the following:
+ </p>
+ <source><![CDATA[
+ant -f build-bootstrap.xml bootstrap
+ ]]></source>
+ <p>
+ Thats it! Congratulations! You have now built Maven with
+ Maven and installed Maven on your system! What does that
+ mean?
+ </p>
+ <ul>
+ <li>
+ The Maven build system has been installed in
+ <code>${maven.home}</code>.
+ </li>
+ <li>
+ The Maven JAR has been installed in your
+ <code>${lib.repo}</code>.
+ </li>
+ <li>
+ You can now build any Maven-enabled project with ease!
+ Please see the <a href="use.html">Using Maven</a>
+ document for instructions on how to build Maven-enabled
+ projects.
+ </li>
+ <li>
+ You can now integrate Maven into your own projects! Please
+ see the <a href="integrate.html">Integrate Maven</a>
+ document for instructions on how to do this.
+ </li>
+ </ul>
</subsection>
- <subsection name="Building Maven with Maven">
+ <subsection name="Gory Details (if interested)">
<p>
- Now that you have successfully bootstrapped, you can use the
- resulting jar file to build Maven, run unit tests, generate
- documentation including cross-references and source metrics.
- The bootstrapping process created <code>maven.jar</code> in
- your <code>${lib.repo}</code> directory. It also created a <a
- href="build-file.html">build system</a> in
- <code>${maven.home}</code> (if it was not defined, you'll find
- a <code>maven</code> directory in your home directory). To
- complete the building of maven using the build system that was
- generated, type the following:
- </p>
- <source><![CDATA[ant maven:update-jars
-ant maven:jar]]></source>
- <p>
- Thats it! You have now built Maven with Maven (and partially
- installed Maven)! You can find the Maven jar file in the
- <code>target</code> directory. Keep in mind that the
- <code>maven.jar</code> file in your <code>${lib.repo}</code>
- directory can only be used to bootstrap Maven. It is not the
- full Maven distribution which was created in your
- <code>target</code> directory. To complete the installation
- of Maven, you should replace the jar in
- <code>${lib.repo}</code> with the one in <code>target</code>.
- </p>
- <p>
- <b>Note:</b> If your Maven build fails at this point then you
- may need to add a copy of junit.jar to your
- <code>${ant.home}/lib</code> directory. This is a known
- problem that is currently being worked on, but for now you
- can download a copy of the JUnit jar from
- <a href="http://jakarta.apache.org/turbine/jars";>here.</a>
+ If you are interested in how the Maven bootstrap process
+ actually works, then read on. Otherwise, you can stop here.
+ This section will briefly talk about the steps that are hidden
+ from the user in the <code>bootstrap</code> Ant target. It
+ also provides instructions if you want to manually bootstrap
+ Maven.
+ </p>
+ <p>
+ The bootstrap process first downloads all JARs required to
+ bootstrap. These are stored in the <code>${lib.repo}</code>
+ directory. Downloading the JARs can be done automatically,
+ type the following:
+ </p>
+ <source><![CDATA[
+ ant -f build-bootstrap.xml update-jars
+ ]]></source>
+ <p>
+ After the bootstrap has downloaded all of the dependencies, it
+ builds the core Maven Java classes, installs the Maven build
+ system in <code>${maven.home}</code>, and installs the
+ bootstrap <code>maven.jar</code> in <code>${lib.repo}</code>
+ You can manually do this by typing:
+ </p>
+ <source><![CDATA[
+ant -f build-bootstrap.xml generate-build
+ ]]></source>
+ <p>
+ The resulting JAR file can then be used by the bootstrap
+ process to build the complete Maven JAR. The first step of
+ any Maven build (bootstrap or not) is to update the JAR files
+ required for the project (note this downloads all of the JARs
+ required to build Maven, the first update-jars only downloaded
+ the ones need to create the bootstrap JAR). These JARs are
+ stored in <code>${lib.repo}</code>. Type the following:
</p>
+ <source><![CDATA[
+ant maven:update-jars
+ ]]></source>
<p>
- Congratulations! For more information on the generated build
- system, see the <a href="build-file.html">documentation</a>.
+ After the required JARs have been downloaded, the bootstrap
+ process can then invoke the standard Maven build target to
+ build the complete Maven JAR which is deposited in
+ <code>${basedir}/target</code>. All unit tests are run when
+ this JAR is created. You can manually do this by typing:
+ </p>
+ <source><![CDATA[
+ant maven:jar
+ ]]></source>
+ <p>
+ After the bootstrap process builds the complete Maven, it
+ creates a distribution in the
+ <code>${maven.home}/install</code> directory that includes all
+ of the required JARs and the complete <code>maven.jar</code>.
+ Type the following to create the distribution:
+ </p>
+ <source><![CDATA[
+ant -f build-bootstrap.xml dist
+ ]]></source>
+ <p>
+ After the bootstrap process builds the complete Maven, it
+ creates a distribution in the
+ <code>${maven.home}/install</code> directory that includes all
+ of the required JARs and the complete <code>maven.jar</code>.
+ Type the following to create the distribution:
+ </p>
+ <source><![CDATA[
+cd ${maven.home}/install
+ant
+ ]]></source>
+ <p>
+ Finally, to complete the bootstrap process, which fully
+ installs Maven on your system, all of the required JARs are
+ copied to your <code>${lib.repo}</code> directory, including
+ the full <code>maven.jar</code> which overwrites the JAR used
+ to bootstrap Maven.
</p>
</subsection>
</section>
1.2 +13 -11 jakarta-turbine-maven/xdocs/download.xml
Index: download.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/xdocs/download.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- download.xml 18 Mar 2002 16:17:34 -0000 1.1
+++ download.xml 28 Mar 2002 18:57:11 -0000 1.2
@@ -8,14 +8,13 @@
<body>
<section name="Download Maven">
-
<p>
- Maven is distributed via an installer. The installer will setup
- a <code>${maven.home}</code> directory containing all of the
- resources (stylesheets, build files, images) required to use
- Maven. It will also install any JARs that Maven requires in
- your <code>${lib.repo}</code> directory. This installer is
- available for several platforms.
+ Maven is currently distributed via an installer. The installer
+ will setup a <code>${maven.home}</code> directory containing all
+ of the resources (stylesheets, build files, images) required to
+ use Maven. It will also install any JARs that Maven requires in
+ your <code>${lib.repo}</code> directory. There are several
+ versions of the installer depending on your operating platform.
</p>
<table>
@@ -48,15 +47,18 @@
<td>
This is a JAR install of Maven. It requires manual
installation as described in
- <a href="getting-started.html">Getting Started</a>.
+ <a href="install.html">Installing Maven</a>.
</td>
</tr>
</table>
<p>
- After downloading the installer, see the <a
- href="getting-started.html">Getting Started</a> document for
- instructions on how to use Maven.
+ Please be aware that these installers are still being developed
+ and may be problematic. If you are not adventurous, it is
+ advised that you use the JAR Install method because this is the
+ most reliable method of installation. After downloading an
+ appropriate installer, see the <a href="getting-started.html">Getting
+ Started</a> document for instructions on how to proceed.
</p>
</section>
1.9 +68 -349 jakarta-turbine-maven/xdocs/getting-started.xml
Index: getting-started.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/xdocs/getting-started.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- getting-started.xml 26 Mar 2002 01:04:29 -0000 1.8
+++ getting-started.xml 28 Mar 2002 18:57:11 -0000 1.9
@@ -10,355 +10,74 @@
<body>
<section name="Getting Started with Maven">
<p>
- This document provides an introduction to Maven and how to use
- it within a project. For those that have already skimmed the
- documentation on this site, you may be asking yourself, what
- *exactly* does it mean to use Maven? That question will have
- different answers over time as Maven <a
- href="goals.html">evolves</a>, but this document attempts to
- illustrate (using the Turbine projects as an example) how one
- might integrate and leverage the power of Maven in a project.
- </p>
- <p>
- For those of you that have been referred to this document
- because you are trying to build one of the Turbine projects,
- this document will provide you with all of the necessary
- information required to build any Turbine project (or more
- importantly, any project that uses Maven).
- </p>
- <p>
- The rest of this document is sectioned into three parts:
- installing Maven on your system, integrating Maven with a
- project, and using Maven. If you are only interested in
- building a project that uses Maven, you can probably skip the
- second section (integrating Maven) and just jump to the last
- section after you have successfully installed Maven. However, it
- is recommended that you read the entire document because it will
- provide you with a better understanding of the Maven project.
- </p>
- </section>
- <section name="Installing Maven">
- <p>
- You must first <a href="download.html">download</a> Maven
- (please refer to the documentation). From the download page,
- you can either select an installer that is appropriate for your
- system, or use the JAR installation method. This document will
- describe the JAR installation as it is the most reliable at this
- time. If you choose to try an installer, please verify that it
- has performed all of the steps outlined here.
- </p>
- <p>
- Before you begin the JAR installation (the other installers
- should do this automatically for you), you'll need to define two
- Ant properties in your
- <code>${user.home}/build.properties</code> file. You'll need to
- determine the location you want your Maven installation to
- reside, as well as the location of your JAR repository. If you
- don't have a <code>${user.home}/build.properties</code>,
- create a file that contains the following two lines with
- appropriate values for your environment:
- </p>
- <source><![CDATA[lib.repo = /home/kaz/src/lib.repo
-maven.home = /home/kaz/maven]]></source>
- <p>
- Download the <code>maven-install.jar</code> file to your local
- filesystem. This JAR contains everything required to install
- Maven on your system. The installation process consists of two
- steps: the installation of Maven specific files, and the
- installation of the required JARs that Maven utilizes.
- Lets start by installing Maven specific files in your
- filesystem. Simply, unjar the JAR file in the directory you
- want your Maven installation to reside. Note: the JAR has been
- packaged with a top-level <code>maven</code> directory for
- convenience.
- </p>
- <source><![CDATA[jar xf maven-install.jar]]></source>
- <p>
- Verify that your <code>${maven.home}</code> property points to
- the correct location. In the top-level directory of
- <code>${maven.home}</code>, you should see several build files
- as well as some directories. Next, you must install all of the
- JARs that Maven requires in your <code>${lib.repo}</code>
- directory. These JARs are included in
- <code>${maven.home}/install</code> directory. To install these
- files, type the following:
- </p>
- <source><![CDATA[cd ${maven.home}/install
-ant]]></source>
- <p>
- Verify the your <code>${lib.repo}</code> directory contains
- several JAR files, including the most important one:
- <code>maven.jar</code>. You have now successfully completed the
- installation of Maven on your system. In the next section, you
- will learn how to integrate Maven into a project.
- </p>
- </section>
- <section name="Integrating Maven with a Project">
- <p>
- Now that you have Maven installed on your system, this section
- will show you how to integrate it with an existing project. All
- of the current Turbine projects have been Mavenized, and can be
- used as references. They will be used as examples in this
- section. There are two primary steps to the integration of
- Maven with a project: the creation of the project descriptor,
- and the creation of a build file (or modification of an existing
- one) that contains targets to delegate to Maven.
- </p>
- <subsection name="Creating a Project Descriptor">
- <p>
- Everything in Maven gravitates around the definition of a
- project. The unit of work in Maven is the project, so before
- you can get started with Maven you need to create your project
- definition. The easiest way to do this is to create an XML
- representation of this definition. In Maven-terms, this is
- called the <a href="project-descriptor.html">project
- descriptor</a>.
- </p>
- <p>
- You'll need to create a project descriptor to use Maven with
- your project. The project descriptor must be called
- <code>project.xml</code> and must reside in the top-level
- directory of your project's directory hierarchy. The contents
- of the descriptor are described in detail in the <a
- href="project-descriptor.html">documentation</a>. A sample
- project descriptor is included in the documentation. In
- addition, all of the Turbine projects have valid project
- descriptors that you can examine.
- </p>
- <p>
- We are working on a tool that will help you create your
- project descriptor automatically, but if you want to get
- started right away with Maven, then you'll have to create your
- own <code>project.xml</code> file manually (probably easiest
- to just modify an existing one).
- </p>
+ This document (as well as the others in this section) provide
+ an introduction to Maven and how to use it within a project.
+ For those that have already skimmed the documentation on this
+ site, you may be asking yourself, what *exactly* does it mean to
+ use Maven? That question will have different answers over time
+ as Maven <a href="goals.html">evolves</a>, but these documents
+ attempt to illustrate (using the Turbine projects as an example)
+ how one might install, integrate and leverage the power of Maven
+ in a project.
+ </p>
+
+ <p>
+ To avoid overwhelming you with unnecessary information, this
+ document attempts to provide references to various documents
+ depending upon your Maven interests. It is meant to provide you
+ with a starting point that can be effectively used to get to the
+ information you need without going through all of the
+ documentation on the site, which might be a little overwhelming.
+ </p>
+
+ <subsection name="Overview of the Getting Started Documentation">
+ <table>
+ <tr><th>Document</th><th>Description</th></tr>
+ <tr><td><a href="download.html">Download</a></td>
+ <td>
+ Before you can start using Maven in any form, you'll have
+ to download the Maven distribution to your system (unless
+ you plan on building Maven from source). This document
+ provides links to the various distributions available.
+ </td>
+ </tr>
+ <tr><td><a href="install.html">Install</a></td>
+ <td>
+ After you have downloaded a distribution, you'll need to
+ install this on your system before you can start using
+ Maven (unless you plan on building Maven from source).
+ This document provides step-by-step instructions on the
+ installation process.
+ </td>
+ </tr>
+ <tr><td><a href="integrate.html">Integrate</a></td>
+ <td>
+ If you are interested in integrating Maven with your
+ project, this document will provide such information. The
+ document details the process of creating a Maven project
+ descriptor for your project.
+ </td>
+ </tr>
+ <tr><td><a href="use.html">Use</a></td>
+ <td>
+ For those of you that have been referred to this document
+ because you are trying to build a Maven-enabled project
+ (i.e. one of the Turbine projects), this document will
+ provide you with all of the necessary information required
+ to build any Maven-enabled project.
+ </td>
+ </tr>
+ <tr><td><a href="bootstrap.html">Build</a></td>
+ <td>
+ For the adventurous (its actually quite easy), you can
+ build Maven from source instead of downloading and
+ installing via an installer. As a result of building
+ Maven directly, it will also be installed on your system.
+ This document provides you with step by step instructions.
+ </td>
+ </tr>
+ </table>
</subsection>
- <subsection name="Adding Maven Delegators">
- <p>
- After you have created a project descriptor for your project,
- the next step (assuming your project follows the standard <a
- href="dirlayout.html">directory layout</a>) is to add a few
- delegators to your project's build file. These delegators
- invoke Ant targets in the various Maven build files that are
- part of the Maven installation. There is a standard set of
- delegators that you should add to your build file. These are
- documented in the <a href="build-file.html">build file</a>
- documentation.
- </p>
- <p>
- If you want to slowly migrate the use of Maven into your
- project, you can follow the approach that the Turbine projects
- have taken. Create a separate build file called
- <code>build-maven.xml</code> and insert the delegators in that
- file. This will allow users of your project to continue to
- use the old build system until you are comfortable with the
- new Maven build system (at which point you would probably
- rename <code>build-maven.xml</code> to
- <code>build.xml</code>). For example, here is the beginning
- of the Fulcrum's <code>build-maven.xml</code> file:
- </p>
- <source><![CDATA[<?xml version="1.0"?>
-
-<project name="maven" default="maven:jar" basedir=".">
-
- <!-- Give user a chance to override without editing this file
- (and without typing -D each time they invoke a target) -->
-
- <!-- Allow any user specific values to override the defaults -->
- <property file="${user.home}/build.properties" />
- <!-- Allow user defaults for this project -->
- <property file="build.properties" />
- <!-- Set default values for the build -->
- <property file="project.properties" />
-
- <!-- maven:start -->
-
- <!-- ========================================================== -->
- <!-- D E L E G A T O R S -->
- <!-- ========================================================== -->
-
- <target
- name="maven:site">
- <ant antfile="${maven.home}/build-docs.xml" target="site"/>
- </target>
-
- <target
- name="maven:jar"
- depends="om">
- <ant antfile="${maven.home}/build-maven.xml" target="jar"/>
- </target>
-
- <target
- name="maven:compile"
- depends="om">
- <ant antfile="${maven.home}/build-maven.xml" target="compile"/>
- </target>
-
- .
- .
- .
-
- <!-- maven:end -->
-</project>]]></source>
-
- </subsection>
- <subsection name="Custom Properties">
- <p>
- There are a few assumptions that Maven makes at this time
- regarding various defaults. In the future, the project
- descriptor should eliminate all of these assumptions.
- However, some of these revolve around the layout of a
- project's directory structure. Maven does assume a project
- adheres to a standard <a href="dirlayout.html"> directory
- layout</a>. In the event that a project cannot follow
- these guidelines, you may have to define your own custom
- properties to override the defaults that Maven currently
- uses. The current defaults are specified in the
- <code>${maven.home}/default.properties</code> file (shown
- below):
- </p>
-<source><![CDATA[# ------------------------------------------------------------
-# D E F A U L T M A V E N P R O P E R T I E S
-# ------------------------------------------------------------
-# These are the properties that we believe are immutable so we
-# keep them apart from the project specific properties.
-# ------------------------------------------------------------
-
-test.reportsDirectory = ${basedir}/test-reports
-
-src.dir = ${basedir}/src
-conf.dir = ${basedir}/conf
-build.dir = ${basedir}/target
-build.src = ${build.dir}/src
-build.dest = ${build.dir}/classes
-
-docs.src = ${basedir}/xdocs
-docs.dest = ${basedir}/docs
-gen.docs = ${build.dir}/generated-xdocs
-
-final.name = ${id}-${currentVersion}
-final.dir = ${basedir}/${final.name}
-
-javadoc.destdir = ${basedir}/docs/apidocs
-javadoc.windowtitle = ${name} ${currentVersion} API
-javadoc.doctitle = ${name} ${currentVersion} API
-javadoc.author = true
-javadoc.private = true
-javadoc.version = true
-javadoc.use = true]]></source>
- <p>
- If you wish to override these properties, you can do so by
- creating your own properties file in your project's directory
- hierarchy. You will then have to load this property file into
- your project's build file. The example build file in the
- previous section illustrates this point. The three
- <code><property></code> lines load various property files. In
- that example, you would save your properties to a file called
- <code>project.properties</code>. Again, if your project
- follows the standard directory layout, you will not have to
- modify these values.
- </p>
- </subsection>
- </section>
- <section name="Using Maven">
- <p>
- Congratulations! Now that you have installed Maven and integrated
- it with your project, you are now ready to start reaping the
- benefits of Maven. The rest of this document will be a guided
- tour through the basic operation of Maven's build system. You
- will learn how to build any of the following Mavenized Turbine
- projects: Torque, Stratum, Fulcrum, and Turbine. The process for
- each project is the identical thanks to Maven (as are the
- results).
- </p>
- <p>
- First, checkout the source for any of the above Turbine projects.
- If you do not know how to do this, please refer to the <a
- href="http://jakarta.apache.org/site/cvsindex.html";>CVS
- Repositories</a> document. For those familiar with the growing
- family of Jakarta projects, several of the projects include all
- of the JAR files required to build and distribute the projects in
- their CVS repositories. Maven eliminates this practice
- altogether because it provides facilities to automatically
- download and update all dependencies from a central repository.
- Thus, before you compile any Mavenized project, you should always
- download/update all of the required dependencies. Maven makes
- this easy, type the following:
- </p>
- <source><![CDATA[ant -f build-maven.xml maven:update-jars]]></source>
- <p>
- As you can tell by the above command, the current Turbine
- projects have their Maven delegators in a separate build file to
- facilitate the migration to Maven (as described in a previous
- section). In the future, the Maven delegators will be part of
- the main build files of all the Turbine family of projects. The
- Maven project uses this approach itself (thus the above command
- would be <code>ant maven:update-jars</code>).
- </p>
- <p>
- After executing the above command, all of the project's
- dependencies have been downloaded to your
- <code>${lib.repo}</code> directory. Recall, Maven uses this to
- store all JAR files. There is one exception, non-distributable
- JARs will result in a message pointing you to the location where
- you can download the JAR yourself. You'll have to download those
- yourself (legal issues) and manually place them in
- <code>${lib.repo}</code>. After you have downloaded all of the
- dependent JARs, generating a JAR for a Mavenized Turbine project
- is easy. Type the following:
- </p>
- <source><![CDATA[ant -f build-maven.xml maven:jar]]></source>
- <p>
- You'll notice that all of the code is compiled, and then unit
- tested, before it is packaged into a JAR file. The unit tests
- generate reports that are later parsed to create an HTML report
- that is part of the generated site documentation. The JAR file
- can also be automatically distributed.
- </p>
- <p>
- The biggest bang for you buck right now is the generation of your
- site documentation. Maven will generate documentation that is
- consistent with the rest of the site. This list of documentation
- includes: developer lists, mailing lists, dependencies, unit test
- reports, source code metrics, change logs, JavaDocs, and
- cross-referenced source code (not too bad considering all you
- have to do is produce a project descriptor)! It will also create
- a standard navigation system that is added to all of your <a
- href="/site/jakarta-site2.html"> xdocs</a>. To generate all of
- the documentation mentioned above, type the following:
- </p>
- <source><![CDATA[ant -f build-maven.xml maven:site]]></source>
- <p>
- The result of this command is a <code>docs</code> directory in
- the project's base directory that contains an entire web site of
- documentation. If you are a maintainer of the project's website
- and you want to publish this site to the web server, type the
- following:
- </p>
- <source><![CDATA[ant -f build-maven.xml maven:deploy-site]]></source>
- <p>
- Assuming you have access to the web server, your entire site
- would have been published. This makes updating the project's web
- site very easy. It can also be easily automated. Finally, to
- conclude the example, you might want to clean the project
- directory because you are so excited about Maven that you want to
- try everything again! Type the following:
- </p>
- <source><![CDATA[ant -f build-maven.xml maven:clean]]></source>
- <p>
- For a full description of all of the Maven targets available,
- please refer to the <a href="build-file.html">build file</a>
- documentation. Each Maven target is described in detail, as well
- as each of the Maven build files that were installed in your
- <code>${maven.home}</code> directory.
- </p>
- <p>
- That concludes the tour of Maven. All of the Turbine projects
- currently use Maven to generate their web sites, please have a
- look and see what Maven can do for you. The Maven-specific
- content can be found in the navigation section called "Maven
- Generated Docs".
- </p>
- </section>
+ </section>
</body>
</document>
1.23 +10 -5 jakarta-turbine-maven/xdocs/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/xdocs/project.xml,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- project.xml 28 Mar 2002 04:54:46 -0000 1.22
+++ project.xml 28 Mar 2002 18:57:11 -0000 1.23
@@ -17,9 +17,17 @@
</links>
<menu name="Overview">
<item name="Goals" href="/goals.html"/>
- <item name="Getting Started" href="/getting-started.html"/>
- <item name="Download" href="/download.html"/>
<item name="Features" href="/features.html"/>
+ <item name="News and Status" href="/status.html"/>
+ <item name="Powered By" href="/powered.html"/>
+ </menu>
+ <menu name="Getting Started">
+ <item name="Start Here" href="/getting-started.html"/>
+ <item name="Download" href="/download.html"/>
+ <item name="Install" href="/install.html"/>
+ <item name="Integrate" href="/integrate.html"/>
+ <item name="Use" href="/use.html"/>
+ <item name="Build" href="/bootstrap.html"/>
</menu>
<menu name="Reference">
<item name="Project Descriptor" href="/project-descriptor.html"/>
@@ -27,9 +35,6 @@
<item name="Directory Layout" href="/dirlayout.html"/>
<item name="JRCS" href="/jrcs.html"/>
<item name="Metrics" href="/metrics.html"/>
- </menu>
- <menu name="Development">
- <item name="Building Maven" href="/bootstrap.html"/>
<item name="Musings" href="/musings.html"/>
</menu>
</body>
1.1 jakarta-turbine-maven/xdocs/install.xml
Index: install.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Installing Maven</title>
<author email="[EMAIL PROTECTED]">Jason van Zyl</author>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
</properties>
<body>
<section name="Installing Maven">
<p>
You must first <a href="download.html">download</a> Maven
(please refer to the documentation). From the download page,
you can either select an installer that is appropriate for your
system, or use the JAR installation method. This document will
describe the JAR installation as it is the most reliable at this
time. If you choose to try an installer, please verify that it
has performed all of the steps outlined here.
</p>
<p>
Before you begin the JAR installation (the other installers
should do this automatically for you), you'll need to define two
Ant properties in your
<code>${user.home}/build.properties</code> file. You'll need to
determine the location you want your Maven installation to
reside, as well as the location of your JAR repository. If you
don't have a <code>${user.home}/build.properties</code>,
create a file that contains the following two lines with
appropriate values for your environment:
</p>
<source><![CDATA[lib.repo = /home/kaz/src/lib.repo
maven.home = /home/kaz/maven]]></source>
<p>
Download the <code>maven-install.jar</code> file to your local
filesystem. This JAR contains everything required to install
Maven on your system. The installation process consists of two
steps: the installation of Maven specific files, and the
installation of the required JARs that Maven utilizes.
Lets start by installing Maven specific files in your
filesystem. Simply, unjar the JAR file in the directory you
want your Maven installation to reside. Note: the JAR has been
packaged with a top-level <code>maven</code> directory for
convenience.
</p>
<source><![CDATA[jar xf maven-install.jar]]></source>
<p>
Verify that your <code>${maven.home}</code> property points to
the correct location. In the top-level directory of
<code>${maven.home}</code>, you should see several build files
as well as some directories. Next, you must install all of the
JARs that Maven requires in your <code>${lib.repo}</code>
directory. These JARs are included in
<code>${maven.home}/install</code> directory. To install these
files, type the following:
</p>
<source><![CDATA[cd ${maven.home}/install
ant]]></source>
<p>
Verify the your <code>${lib.repo}</code> directory contains
several JAR files, including the most important one:
<code>maven.jar</code>. You have now successfully completed the
installation of Maven on your system. Please refer to the <a
href="getting-started.html">Getting Started</a> document for
instructions on how to proceed depending upon your interests.
</p>
</section>
</body>
</document>
1.1 jakarta-turbine-maven/xdocs/integrate.xml
Index: integrate.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Integrating Maven</title>
<author email="[EMAIL PROTECTED]">Jason van Zyl</author>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
</properties>
<body>
<section name="Integrating Maven with a Project">
<p>
Now that you have Maven installed on your system, this section
will show you how to integrate it with an existing project. All
of the current Turbine projects have been Maven-enabled, and can be
used as references. They will be used as examples in this
section. There are two primary steps to the integration of
Maven with a project: the creation of the project descriptor,
and the creation of a build file (or modification of an existing
one) that contains targets to delegate to Maven.
</p>
<subsection name="Creating a Project Descriptor">
<p>
Everything in Maven gravitates around the definition of a
project. The unit of work in Maven is the project, so before
you can get started with Maven you need to create your project
definition. The easiest way to do this is to create an XML
representation of this definition. In Maven-terms, this is
called the <a href="project-descriptor.html">project
descriptor</a>.
</p>
<p>
You'll need to create a project descriptor to use Maven with
your project. The project descriptor must be called
<code>project.xml</code> and must reside in the top-level
directory of your project's directory hierarchy. The contents
of the descriptor are described in detail in the <a
href="project-descriptor.html">documentation</a>. A sample
project descriptor is included in the documentation. In
addition, all of the Turbine projects have valid project
descriptors that you can examine.
</p>
<p>
We are working on a tool that will help you create your
project descriptor automatically, but if you want to get
started right away with Maven, then you'll have to create your
own <code>project.xml</code> file manually (probably easiest
to just modify an existing one).
</p>
</subsection>
<subsection name="Adding Maven Delegators">
<p>
After you have created a project descriptor for your project,
the next step (assuming your project follows the standard <a
href="dirlayout.html">directory layout</a>) is to add a few
delegators to your project's build file. These delegators
invoke Ant targets in the various Maven build files that are
part of the Maven installation. There is a standard set of
delegators that you should add to your build file. These are
documented in the <a href="build-file.html">build file</a>
documentation.
</p>
<p>
If you want to slowly migrate the use of Maven into your
project, you can follow the approach that the Turbine projects
have taken. Create a separate build file called
<code>build-maven.xml</code> and insert the delegators in that
file. This will allow users of your project to continue to
use the old build system until you are comfortable with the
new Maven build system (at which point you would probably
rename <code>build-maven.xml</code> to
<code>build.xml</code>). For example, here is the beginning
of the Fulcrum's <code>build-maven.xml</code> file:
</p>
<source><![CDATA[<?xml version="1.0"?>
<project name="maven" default="maven:jar" basedir=".">
<!-- Give user a chance to override without editing this file
(and without typing -D each time they invoke a target) -->
<!-- Allow any user specific values to override the defaults -->
<property file="${user.home}/build.properties" />
<!-- Allow user defaults for this project -->
<property file="build.properties" />
<!-- Set default values for the build -->
<property file="project.properties" />
<!-- maven:start -->
<!-- ========================================================== -->
<!-- D E L E G A T O R S -->
<!-- ========================================================== -->
<target
name="maven:site">
<ant antfile="${maven.home}/build-docs.xml" target="site"/>
</target>
<target
name="maven:jar"
depends="om">
<ant antfile="${maven.home}/build-maven.xml" target="jar"/>
</target>
<target
name="maven:compile"
depends="om">
<ant antfile="${maven.home}/build-maven.xml" target="compile"/>
</target>
.
.
.
<!-- maven:end -->
</project>]]></source>
</subsection>
<subsection name="Custom Properties">
<p>
There are a few assumptions that Maven makes at this time
regarding various defaults. In the future, the project
descriptor should eliminate all of these assumptions.
However, some of these revolve around the layout of a
project's directory structure. Maven does assume a project
adheres to a standard <a href="dirlayout.html"> directory
layout</a>. In the event that a project cannot follow
these guidelines, you may have to define your own custom
properties to override the defaults that Maven currently
uses. The current defaults are specified in the
<code>${maven.home}/default.properties</code> file (shown
below):
</p>
<source><![CDATA[# ------------------------------------------------------------
# D E F A U L T M A V E N P R O P E R T I E S
# ------------------------------------------------------------
# These are the properties that we believe are immutable so we
# keep them apart from the project specific properties.
# ------------------------------------------------------------
test.reportsDirectory = ${basedir}/test-reports
src.dir = ${basedir}/src
conf.dir = ${basedir}/conf
build.dir = ${basedir}/target
build.src = ${build.dir}/src
build.dest = ${build.dir}/classes
docs.src = ${basedir}/xdocs
docs.dest = ${basedir}/docs
gen.docs = ${build.dir}/generated-xdocs
final.name = ${id}-${currentVersion}
final.dir = ${basedir}/${final.name}
javadoc.destdir = ${basedir}/docs/apidocs
javadoc.windowtitle = ${name} ${currentVersion} API
javadoc.doctitle = ${name} ${currentVersion} API
javadoc.author = true
javadoc.private = true
javadoc.version = true
javadoc.use = true]]></source>
<p>
If you wish to override these properties, you can do so by
creating your own properties file in your project's directory
hierarchy. You will then have to load this property file into
your project's build file. The example build file in the
previous section illustrates this point. The three
<code><property></code> lines load various property files. In
that example, you would save your properties to a file called
<code>project.properties</code>. Again, if your project
follows the standard directory layout, you will not have to
modify these values.
</p>
<p>
This concludes the introduction to integrating Maven into your
project. Please refer to the <a
href="getting-started.html">Getting Started</a> document for
instructions on how to proceed depending upon your interests.
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-turbine-maven/xdocs/powered.xml
Index: powered.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Powered By Maven</title>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
</properties>
<body>
<section name="Powered By Maven">
<p>
This page contains a list of known projects successfully using
Maven. We would be very interested if you would drop us a note
if you are using Maven with your project and would like to be
added to this list.
</p>
<subsection name="Projects Using Maven">
<table>
<tr><th>Project</th><th>Overview</th></tr>
<tr>
<td><a href="http://jakarta.apache.org/turbine";>Turbine</a></td>
<td>
A collection of projects dedicated to the development of web
applications using a model-view-controller model.
</td>
</tr>
<tr>
<td><a href="http://jakarta.apache.org/turbine/turbine-2";>Turbine
2</a></td>
<td>
Version 2 of the Turbine model-view-controller framework.
</td>
</tr>
<tr>
<td><a href="http://jakarta.apache.org/turbine/turbine-3";>Turbine
3</a></td>
<td>
Version 3 of the Turbine model-view-controller framework.
</td>
</tr>
<tr>
<td><a href="http://jakarta.apache.org/turbine/stratum";>Stratum</a></td>
<td>
A collection of reusable components from the Turbine projects.
</td>
</tr>
<tr>
<td><a href="http://jakarta.apache.org/turbine/fulcrum";>Fulcrum</a></td>
<td>
A services framework that was decoupled from Turbine.
</td>
</tr>
<tr>
<td><a href="http://jakarta.apache.org/turbine/torque";>Torque</a></td>
<td>
A object-relational mapping tool that was decoupled from Turbine.
</td>
</tr>
<tr>
<td><a href="http://jakarta.apache.org/turbine/maven";>Maven</a></td>
<td>
The future of all projects!
</td>
</tr>
</table>
</subsection>
</section>
</body>
</document>
1.1 jakarta-turbine-maven/xdocs/status.xml
Index: status.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>News and Status</title>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
</properties>
<body>
<section name="News and Status">
<p>
This document contains the latest news and status regarding the
Maven project. It is here you'll find announcements related to
Maven.
</p>
<subsection name="Current Status">
<p>
Although Maven is relatively new (only the past few weeks), we
have had significant interest from various users. Maven has
already been successfully deployed on numerous projects.
</p>
<p>
Please note, the installers that can be downloaded on this
site may not contain the latest and greatest changes. It is
recommended that you build Maven from source if you are an
early adopter. The build process will automatically install
Maven on your system for you bypassing the need to install
from an installer.
</p>
</subsection>
<subsection name="25 March 2002 - Collaborating with Style.tigris.org">
<p>
The Maven team is now collaborating with Style.tigris.org.
The look and feel of all Maven-generated sites is due in part
to the CSS gurus at Style. Thanks to the help of Daniel Rall
and Todd Fahrner for establishing Style.tigris.org so that we
can collaborate!
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-turbine-maven/xdocs/use.xml
Index: use.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Using Maven</title>
<author email="[EMAIL PROTECTED]">Jason van Zyl</author>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
</properties>
<body>
<section name="Using Maven">
<p>
Congratulations! Now that you have installed Maven and/or
integrated with your project, you are now ready to start
reaping the benefits of Maven. The rest of this document will be
a guided tour through the basic operation of Maven's build
system. You will learn how to build any of the following
Maven-enabled Turbine projects: Torque, Stratum, Fulcrum, and
Turbine. The process for each project is the identical thanks to
Maven (as are the results).
</p>
<p>
First, checkout the source for any of the above Turbine projects.
If you do not know how to do this, please refer to the <a
href="http://jakarta.apache.org/site/cvsindex.html";>CVS
Repositories</a> document. For those familiar with the growing
family of Jakarta projects, several of the projects include all
of the JAR files required to build and distribute the projects in
their CVS repositories. Maven eliminates this practice
altogether because it provides facilities to automatically
download and update all dependencies from a central repository.
Thus, before you compile any Maven-enabled project, you should always
download/update all of the required dependencies. Maven makes
this easy, type the following:
</p>
<source><![CDATA[ant -f build-maven.xml maven:update-jars]]></source>
<p>
As you can tell by the above command, the current Turbine
projects have their Maven delegators in a separate build file to
facilitate the migration to Maven (as described in a previous
section). In the future, the Maven delegators will be part of
the main build files of all the Turbine family of projects. The
Maven project uses this approach itself (thus the above command
would be <code>ant maven:update-jars</code>).
</p>
<p>
After executing the above command, all of the project's
dependencies have been downloaded to your
<code>${lib.repo}</code> directory. Recall, Maven uses this to
store all JAR files. There is one exception, non-distributable
JARs will result in a message pointing you to the location where
you can download the JAR yourself. You'll have to download those
yourself (legal issues) and manually place them in
<code>${lib.repo}</code>. After you have downloaded all of the
dependent JARs, generating a JAR for a Maven-enabled Turbine project
is easy. Type the following:
</p>
<source><![CDATA[ant -f build-maven.xml maven:jar]]></source>
<p>
You'll notice that all of the code is compiled, and then unit
tested, before it is packaged into a JAR file. The unit tests
generate reports that are later parsed to create an HTML report
that is part of the generated site documentation. The JAR file
can also be automatically distributed.
</p>
<p>
The biggest bang for you buck right now is the generation of your
site documentation. Maven will generate documentation that is
consistent with the rest of the site. This list of documentation
includes: developer lists, mailing lists, dependencies, unit test
reports, source code metrics, change logs, JavaDocs, and
cross-referenced source code (not too bad considering all you
have to do is produce a project descriptor)! It will also create
a standard navigation system that is added to all of your <a
href="/site/jakarta-site2.html"> xdocs</a>. To generate all of
the documentation mentioned above, type the following:
</p>
<source><![CDATA[ant -f build-maven.xml maven:site]]></source>
<p>
The result of this command is a <code>docs</code> directory in
the project's base directory that contains an entire web site of
documentation. If you are a maintainer of the project's website
and you want to publish this site to the web server, type the
following:
</p>
<source><![CDATA[ant -f build-maven.xml maven:deploy-site]]></source>
<p>
Assuming you have access to the web server, your entire site
would have been published. This makes updating the project's web
site very easy. It can also be easily automated. Finally, to
conclude the example, you might want to clean the project
directory because you are so excited about Maven that you want to
try everything again! Type the following:
</p>
<source><![CDATA[ant -f build-maven.xml maven:clean]]></source>
<p>
For a full description of all of the Maven targets available,
please refer to the <a href="build-file.html">build file</a>
documentation. Each Maven target is described in detail, as well
as each of the Maven build files that were installed in your
<code>${maven.home}</code> directory.
</p>
<p>
That concludes the tour of Maven. All of the Turbine projects
currently use Maven to generate their web sites, please have a
look and see what Maven can do for you. The Maven-specific
content can be found in the navigation section called "Maven
Documentation".
</p>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
