kaz 02/03/18 15:11:04
Modified: xdocs getting-started.xml
Log:
This document provides the following:
- Maven installation procedures (using the JAR install).
- How to integrate Maven into an existing project.
- Basic overview of using Maven.
Now that the Turbine projects have been mavenized, this document should
provide enough information for individuals to build, compile, and
generate documentation for any of the Turbine projects.
Revision Changes Path
1.5 +351 -20 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.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- getting-started.xml 2 Mar 2002 20:32:46 -0000 1.4
+++ getting-started.xml 18 Mar 2002 23:11:04 -0000 1.5
@@ -4,33 +4,364 @@
<properties>
<title>Getting Started with Maven</title>
<author email="[EMAIL PROTECTED]">Jason van Zyl</author>
+ <author email="[EMAIL PROTECTED]">Pete Kazmier</author>
</properties>
<body>
<section name="Getting Started with Maven">
<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. You
- can take a look at the Maven project descriptor
- <a href="project-descriptor.html">here</a>.
- </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 all you need to do is create your project.xml
- file and generate a build system for your project.
+ This document provides an introduction to Maven and how to use
+ it with 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>
-
- <!--
+ </section>
+ <section name="Installing Maven">
<p>
- One of the most important aspect of the project definition is the
- accurate listing of the project dependencies.
+ 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
+ convienence.
+ </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>
- </body>
+ <section name="Maven-izing 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>
+ </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 documentaion. The JAR file
+ can also be automatically distributed.
+ </p>
+ <p>
+ The biggest bang for you buck right now is the generation of your
+ site documenation. 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>
+ </body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
