jvanzyl 2003/02/14 10:11:05
Modified: xdocs/reference user-guide.xml
Log:
o Added section on project setup and generating an app skeleton.
o Using SNAPSHOT dependencies
o How to resolve SNAPSHOT dependencies for deployment.
Revision Changes Path
1.41 +153 -71 jakarta-turbine-maven/xdocs/reference/user-guide.xml
Index: user-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/xdocs/reference/user-guide.xml,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -r1.40 -r1.41
--- user-guide.xml 14 Feb 2003 15:43:09 -0000 1.40
+++ user-guide.xml 14 Feb 2003 18:11:04 -0000 1.41
@@ -30,12 +30,19 @@
<li><a href="#Properties Processing">Properties Processing</a></li>
<li><a href="#Behavioural Properties">Behavioural Properties</a></li>
<li><a href="#Using Proxies">Using Proxies</a></li>
+ <li><a href="#Setup">Setup</a>
+ <br/>
+ <ol>
+ <li><a href="#Starting a New Project">Starting a New Project</a></li>
+ </ol>
+ </li>
<li><a href="#Building">Building</a>
<br/>
<ol>
<li><a href="#Build Lifecyle">Build Lifecycle</a></li>
<li><a href="#Storing JARs in CVS">Storing JARs in CVS</a></li>
<li><a href="#Overriding Stated Dependencies">Overriding Stated
Dependencies</a></li>
+ <li><a href="#Using SNAPSHOT Dependencies">Using SNAPSHOT
Dependencies</a></li>
<li><a href="#Multi Project Builds and the Reactor">Multi Project
Builds and the Reactor</a></li>
</ol>
</li>
@@ -55,6 +62,7 @@
<li><a href="#Deploying">Deploying</a>
<br/>
<ol>
+ <li><a href="#Resolving SNAPSHOT Dependencies">Resolving SNAPSHOT
Dependencies</a></li>
<li><a href="#Copying Dependency JARs">Copying Dependency
JARs</a></li>
</ol>
</li>
@@ -66,7 +74,6 @@
<li><a href="#Colors">Colors</a></li>
<li><a href="#Stylesheets">Stylesheets</a></li>
<li><a href="#Reports">Reports</a></li>
- <li><a href="#Displaying the Publish Date">Displaying the Publish
Date</a></li>
</ol>
</ol>
</p>
@@ -146,8 +153,8 @@
<logo>/images/jakarta-logo-blue.gif</logo>
</organization>
<inceptionYear>2001</inceptionYear>
- <package>org.apache.${pom.artifactId}</package>
- <logo>/images/${pom.artifactId}.jpg</logo>
+ <package>org.apache.${pom.id}</package>
+ <logo>/images/${pom.id}.jpg</logo>
<description>Maven is a project that was created in
${pom.inceptionYear}.</description>
<shortDescription>${pom.name} is a Java Project Management Tool</shortDescription>
@@ -212,19 +219,19 @@
<gumpRepositoryId>jakarta</gumpRepositoryId>
- <url>http://jakarta.apache.org/commons/${pom.artifactId}.html</url>
+ <url>http://jakarta.apache.org/commons/${pom.id}.html</url>
<issueTrackingUrl>http://nagoya.apache.org/</issueTrackingUrl>
<siteAddress>jakarta.apache.org</siteAddress>
- <siteDirectory>/www/jakarta.apache.org/commons/${pom.artifactId}/</siteDirectory>
+ <siteDirectory>/www/jakarta.apache.org/commons/${pom.id}/</siteDirectory>
<distributionDirectory>
- /www/jakarta.apache.org/builds/jakarta-commons/${pom.artifactId}/
+ /www/jakarta.apache.org/builds/jakarta-commons/${pom.id}/
</distributionDirectory>
<repository>
<connection>
-
scm:cvs:pserver:[EMAIL PROTECTED]:/home/cvspublic:jakarta-commons/${pom.artifactId}
+
scm:cvs:pserver:[EMAIL PROTECTED]:/home/cvspublic:jakarta-commons/${pom.id}
</connection>
- <url>http://cvs.apache.org/viewcvs/jakarta-commons/${pom.artifactId}/</url>
+ <url>http://cvs.apache.org/viewcvs/jakarta-commons/${pom.id}/</url>
</repository>
...
</project>
@@ -243,7 +250,7 @@
]]></source>
<p>
- And what you will get is the child's ${pom.artifactId} value substituted
into
+ And what you will get is the child's ${pom.id} value substituted into
the parent template. So for projects like the commons where you have
many builds that are basically set up the same way you can use a master
template and leave very little in the child's project.xml file.
@@ -255,9 +262,9 @@
builds.
</p>
<p>
- If you're wondering what the JSL reports will look like using this
- mechanism then you're on the ball! The JSL reporting
- works on the POM itself i.e. the Jelly JSL transformation is performed on
a
+ If you're wondering what the DVSL reports will look like using this
+ mechanism then you're on the ball! I have changed the DVSL reporting to
+ work on the POM itself i.e. the DVSL transformation is performed on a
Java object. This was necessary in order for reports to come out
correctly when interpolation and inheritance are involved. You can't use
the child template listed above and expect it to work. We need to use
@@ -667,6 +674,67 @@
</section>
+ <section name="Setup">
+ <subsection name="Starting a New Project">
+ <p>
+ If you using Maven for the first time or starting a new project you
+ can use the GenApp plugin to automate the creation of a Maven
+ project tree.
+ </p>
+<source><![CDATA[
+maven -Dpackage=com.mycompany.app genapp
+]]></source>
+
+ <p>
+ When you execute this command you will see something like the
+ following:
+ </p>
+<source><![CDATA[
+ __ __
+| \/ |__ Jakarta _ ___
+| |\/| / _ \ V / -_) ' \ ~ intelligent projects ~
+|_| |_\__,_|\_/\___|_||_| v. 1.0-beta-9
+
+
+ [mkdir] Created dir: <target-directory>/genapp/src/java/com/mycompany/app
+ [copy] Copying 1 file to <target-directory>/genapp/src/java/com/mycompany/app
+ [mkdir] Created dir: <target-directory>/genapp/src/test/com/mycompany/app
+ [copy] Copying 3 files to <target-directory>/genapp/src/test/com/mycompany/app
+ [copy] Copying 2 files to <target-directory>/genapp
+ [copy] Copying 1 file to <target-directory>/genapp/src/conf
+ BUILD SUCCESSFUL
+ Total time: 3 seconds
+]]></source>
+
+ <p>
+ When the command finishes executing you should have a complete
+ project tree that looks something like the following:
+ </p>
+<source><![CDATA[
+.
+|-- project.properties
+|-- project.xml
+`-- src
+ |-- conf
+ | `-- app.properties
+ |-- java
+ | `-- com
+ | `-- mycompany
+ | `-- app
+ | `-- App.java
+ `-- test
+ `-- com
+ `-- mycompany
+ `-- app
+ |-- AbstractTestCase.java
+ |-- AppTest.java
+ `-- NaughtyTest.java
+
+]]></source>
+ </subsection>
+
+ </section>
+
<section name="Building">
<p>
Maven works using the notion of a central repository. All artifacts
@@ -759,6 +827,41 @@
]]></source>
</subsection>
+ <subsection name="Using SNAPSHOT Dependencies">
+ <p>
+ In Maven SNAPSHOTs are artifacts aproximate the latest build of a
particular
+ project. If a project that you depend on is changing frequently you can
state
+ in your POM that you wish to try and keep up with that project by
declaring
+ it a SNAPSHOT dependency. So, for example, you may be trying to stay
abreast
+ of changes in <a
href="http://jakarta.apache.org/commons/jelly/";>Jelly</a> so
+ you might put the following in your POM:
+ </p>
+<source><![CDATA[
+<project>
+ ...
+ <dependencies>
+
+ <dependency>
+ <id>commons-jelly</id>
+ <version>SNAPSHOT</version>
+ </dependency>
+
+ </dependencies>
+ ...
+</project>
+]]></source>
+
+ <p>
+ This tells Maven that you are always looking to use the latest build of
+ Jelly that is available in the Maven repository. Internally to Maven
+ SNAPSHOT dependencies are always considered failed dependencies. That
+ being the case Maven will always try to retrieve a copy of SNAPSHOT
+ dependency from the Maven repository. If you are working offline Maven
+ will warn you that your SNAPSHOT dependencies may be out of date.
+ </p>
+
+ </subsection>
+
<subsection name="Multi Project Builds and the Reactor">
<p>
With Maven the Reactor is the tool that is used to control multi
@@ -926,6 +1029,44 @@
<p>
</p>
+ <subsection name="Resolving SNAPSHOT Dependencies">
+ <p>
+ It is convenient to use SNAPSHOT dependencies while developing but when
you
+ deploy you need to resolve all your SNAPSHOT dependencies so that your
+ releases consist of all immutable artifacts. If you release a project with
+ SNAPSHOT dependencies and some of the SNAPSHOTs change after your release
+ you could wind up very quickly with a release that doesn't work.
+ </p>
+
+ <p>
+ When SNAPSHOTs are deployed in Maven a timestamped version for the
+ artifact being deployed is created. So Maven would know that
foo-SNAPSHOT.jar
+ actually refers to foo-20030101.010101.jar in the Maven Repository. When
it
+ comes time to deploy you can ask Maven to convert your SNAPSHOT versions
+ into timestamped versions using the following command:
+ </p>
+
+<source><![CDATA[
+maven convert-snapshots
+]]></source>
+
+ <p>
+ You will be presented with an interactive console where you can choose
which
+ SNAPSHOT dependencies you want to resolve. When this process is complete
Maven
+ will write out your POM with your modified dependency entries.
+ </p>
+
+ <p>
+ If you wish Maven just to simply do its best at resolving SNAPSHOT
dependencies
+ you can use the following command:
+ </p>
+
+<source><![CDATA[
+maven convert-snapshots-auto
+]]></source>
+
+ </subsection>
+
<subsection name="Copying Dependency JARs">
<p>
The easiest way to copy your project' dependency JARs is to
@@ -1065,7 +1206,6 @@
<dependency>
<groupId>org.foo.bar</groupId>
<artifactId>foo</artifactId>
- <category>runtime</category>
<version>1.0</version>
</dependency>
@@ -1280,43 +1420,6 @@
selectively choose which reports to include and exclude as
well as the order of the reports.
</p>
-
- <p>
- If you would like to use the report customization feature you
- might have a POM that looks like the following:
- </p>
-
-<source><![CDATA[
-<project>
- <id>bar</id>
- <name>Baradelic Groove Machine</name>
- <groupId>org.bar.foo</groupId>
-
- ...
-
- <reports>
- <report>maven-jdepend-plugin</report>
- <report>maven-checkstyle-plugin</report>
- <report>maven-changelog-plugin</report>
- <report>maven-file-activity-plugin</report>
- <report>maven-developer-activity-plugin</report>
- <report>maven-javadoc-plugin</report>
- <report>maven-jxr-plugin</report>
- <report>maven-junit-report-plugin</report>
- <report>maven-tasklist-plugin</report>
- <report>maven-jellydoc-plugin</report>
- </reports>
-</project>
-]]></source>
-
- <p>
- So you can choose from any of the default reports that Maven
- provides or you can create your own report plugins and hook
- them in using this mechanism. To find out how to make your
- report plugins conform please refer to the
- <a href="developer-guide.html#Reporting Protocol">Reporting
- Protocol</a> section in the Developer's Guide.
- </p>
</subsection>
<subsection name="Exclusion of All Maven-Generated Content">
<p>
@@ -1330,27 +1433,6 @@
navigation bar which includes information about the project as
well as links to the numerous Maven-generated reports.
</p>
- </subsection>
- <subsection name="Displaying the Publish Date">
- <p>
- If you wish to display the date that the site was published add the
- following to your project.properties file:
- </p>
-
-<source><![CDATA[
-# ------------------------------------------------------------------------
-# P U B L I S H D A T E L O C A T I O N
-# ------------------------------------------------------------------------
-# options: bottom, left, right, navigation-top, navigation-bottom
-# ------------------------------------------------------------------------
-maven.xdoc.date = left
-
-# ------------------------------------------------------------------------
-# P R O J E C T V E R S I O N
-# ------------------------------------------------------------------------
-maven.xdoc.version = ${pom.currentVersion}
-]]></source>
-
</subsection>
</section>
<!--
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
