kaz 02/04/10 12:07:38
Modified: xdocs build-file.xml dirlayout.xml project-descriptor.xml
Log:
The latest round of doc changes that incorporate the new test stuff,
announcements, and other udpates.
Revision Changes Path
1.24 +99 -23 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.23
retrieving revision 1.24
diff -u -r1.23 -r1.24
--- build-file.xml 7 Apr 2002 23:49:53 -0000 1.23
+++ build-file.xml 10 Apr 2002 19:07:37 -0000 1.24
@@ -157,10 +157,18 @@
<td>Cleans the build directory.</td>
</tr>
<tr>
+ <td><a href="#maven:announce">maven:announce</a></td>
+ <td>Sends an announcement email to various email addresses.</td>
+ </tr>
+ <tr>
<td><a href="#maven:maven-update">maven:maven-update</a></td>
<td>Checks for a new version of Maven and updates if one is
found.</td>
</tr>
+ <tr>
+ <td><a href="#maven:validate-pom">maven:validate-pom</a></td>
+ <td>Validates the project descriptor.</td>
+ </tr>
</table>
<p/>
<subsection name="maven:env">
@@ -312,8 +320,8 @@
server. SSH is used to transfer the distributions to the web
server and directory specified by the <code>siteAddress</code>
and <code>distributionDirectory</code> elements of the <a
- href="project-descriptor.html#project"> project
- descriptor</a>.
+ href="project-descriptor.html#project"> project
+ descriptor</a>.
</p>
</subsection>
<subsection name="maven:install-jar">
@@ -340,6 +348,45 @@
which is currently the <code>target</code> directory.
</p>
</subsection>
+ <subsection name="maven:announce">
+ <p>
+ The <code>maven:announce</code> target sends an announcement
+ email to various email addresses. To utilize this feature,
+ you must define a property called <code>announcement</code> in
+ one of your local property files (usually in
+ <code>project.properties</code>). The value of this property
+ is used by Maven to locate a property file containing
+ properties related to this announcement. The announcement
+ property file must reside in the
+ <code>${src.dir}/announcements</code>
+ directory and the name of this file must be in the form of
+ <code><announcement>.properties</code> where
+ <code><announcement></code> is the name of the
+ announcement that was defined in your local property file
+ (<code>project.properties</code>). For example, if the value
+ of the <code>announcement</code> property is
+ <code>beta3</code>, then the announcement property file used
+ by Maven is
+ <code>${src.dir}/announcements/beta3.announcement</code>.
+ </p>
+ <p>
+ The announcement property file must contain the following
+ properties: <code>announcementFrom</code>,
+ <code>announcementRecipients</code>,
+ <code>announcementSubject</code>,
+ <code>announcementFile</code>, and <code>mailHost</code>. The
+ <code>announcementFile</code> must point to an file containing
+ the body of the announcement. Below is an example
+ announcement property file:
+ </p>
+ <source><![CDATA[
+announcementFrom = Team XXY <[EMAIL PROTECTED]>
+announcementRecipients = [EMAIL PROTECTED],[EMAIL PROTECTED]
+announcementSubject = Beta 3 Release
+announcementFile = ${src.dir}/announcements/beta3.announcement
+mailHost = 10.10.10.10
+ ]]></source>
+ </subsection>
<subsection name="maven:maven-update">
<p>
The <code>maven:maven-update</code> target checks to see if a
@@ -351,6 +398,24 @@
will automatically update your project descriptor if the
schema has changed. New versions of Maven are checked for at
<a href="properties.html#Miscellaneous
Settings"><code>${maven.updateSite}</code></a>.
+ Please see the <a href="updating.html">Updating</a> document
+ for more information on the update process.
+ </p>
+ </subsection>
+ <subsection name="maven:validate-pom">
+ <p>
+ The <code>maven:validate-pom</code> target checks the validity
+ of the project descriptor to ensure it complies with the XML
+ schema. This can be very useful if you are encountering
+ problems, it is suggested that you validate your POM before
+ posting to the mailing lists for assistance. Note: you must
+ install Xerces2 as your XML parser in
+ <code>$ANT_HOME/lib</code> directory if you want to use the
+ validation feature of Maven. You'll have to remove any other
+ XML parsers in that directory as well (such as
+ <code>crimson.jar</code>). In the future, we hope to resolve
+ this issue and then invoke <code>maven:validate-pom</code>
+ before every invocation of a Maven target.
</p>
</subsection>
</section>
@@ -370,8 +435,8 @@
<td>Generate the change log from CVS.</td>
</tr>
<tr>
- <td><a href="#maven:cross-ref">maven:cvs-change-log</a></td>
- <td>Generate the change log from CVS.</td>
+ <td><a href="#maven:cross-ref">maven:cross-ref</a></td>
+ <td>Generate HTML cross-referenced source files.</td>
</tr>
<tr>
<td><a href="#maven:site">maven:site</a></td>
@@ -431,14 +496,17 @@
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.
+ </code> element from the project descriptor. By default, only
+ the past 5 days of changes are displayed (see the <a
+ href="properties.html#Miscellaneous Settings">Properties</a>
+ document).
</p>
</subsection>
<subsection name="maven:cross-ref">
<p>
The <code>maven:cross-ref</code> target generates
cross-referenced Java source code for a project. The
- resulting pages are then linked to by the various
+ resulting HTML pages are then linked to by the various
Maven-generated reports. The <a
href="properties.html"><code>${src.dir}</code></a> property
specifies the base directory for the cross-referenced sources.
@@ -449,7 +517,8 @@
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.
+ change logs, metrics, CheckStyle reports, and unit testing
+ reports.
</p>
</subsection>
<subsection name="maven:deploy-site">
@@ -459,7 +528,8 @@
generated site to the web server and directory specified by
the <code>siteAddress</code> and <code>siteDirectory</code>
elements of the <a href="project-descriptor.html#project">
- project descriptor</a>.
+ project descriptor</a>. After the site has been transferred,
+ it is then installed into the appropriate directory.
</p>
</subsection>
</section>
@@ -500,16 +570,15 @@
<p/>
<subsection name="maven:test">
<p>
- The <code>maven:test</code> target executes all of the unit tests
- (JUnit) 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>
+ The <code>maven:test</code> target executes all of the unit
+ tests (JUnit) of the project. First, the source for all of
+ the tests is compiled, then the JUnit is used to execute the
+ tests. The location of the test source code is determined
+ from the
+ <a
href="project-descriptor.html#build"><code>unitTestSourceDirectory</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#integrationUnitTestClassEntries"><code>integrationUnitTestClassEntries</code></a>
- specify the actual test classes to invoke.
+ <a
href="project-descriptor.html#unitTestPatterns"><code>unitTestPatterns</code></a>
+ specify the actual tests to invoke.
</p>
<p>
The results of the tests are placed in the
@@ -525,7 +594,7 @@
unit test (JUnit) 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>
+ <a
href="project-descriptor.html#build"><code>unitTestSourceDirectory</code></a>
element of the Maven project descriptor. The specific unit
test to invoke must be specified via the <code>testcase</code>
system property . From the Ant command-line, you can specify
@@ -536,7 +605,8 @@
<code>test-reports</code> directory relative to the base
directory of the project. If this directory does not exist,
it is created. In addition, an HTML report is generated when
- the <code>docs</code> target is invoked.
+ the <a href="#maven:docs"><code>maven:docs</code></a> target
+ is invoked.
</p>
</subsection>
</section>
@@ -557,8 +627,13 @@
href="http://jakarta.apache.org/cactus";>Cactus</a> framework
and execute test cases inside a running servlet container.
This harness is setup to use tomcat for the container. The
- default properties for testing are specified in the <a
- href="properties.html#Test Settings">Properties</a> document.
+ location of the test source code is determined from the
+ <a
href="project-descriptor.html#build"><code>integrationUnitTestSourceDirectory</code></a>
+ element of the Maven project descriptor. In addition, the
+ <a
href="project-descriptor.html#integrationUnitTestPatterns"><code>integrationUnitPatterns</code></a>
+ specify the actual tests to invoke. The default properties
+ for testing are specified in the <a href="properties.html#Test
+ Settings">Properties</a> document.
</p>
<p>
More information about setting up in-container tests with
@@ -569,8 +644,9 @@
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. These reports will be included when the HTML
- report is generated with the <code>maven:docs</code> target.
+ it is created. In addition, an HTML report is generated when
+ the <a href="#maven:docs"><code>maven:docs</code></a> target
+ is invoked.
</p>
</subsection>
</section>
1.9 +11 -0 jakarta-turbine-maven/xdocs/dirlayout.xml
Index: dirlayout.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/xdocs/dirlayout.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- dirlayout.xml 7 Apr 2002 23:24:37 -0000 1.8
+++ dirlayout.xml 10 Apr 2002 19:07:37 -0000 1.9
@@ -91,6 +91,17 @@
</td>
</tr>
<tr>
+ <td>src/announcements</td>
+ <td>Contains a record of announcements.</td>
+ <td>
+ This directory is used to maintain a record of announcements sent
+ out by the project. It contains announcement property files as
+ well as the announcements themselves. Please refer to the <a
+ href="build-file.html#maven:announce">Build File</a>
+ documentation for more information on announcements.
+ </td>
+ </tr>
+ <tr>
<td>xdocs/</td>
<td>Documentation files in XML format.</td>
<td>
1.17 +122 -63 jakarta-turbine-maven/xdocs/project-descriptor.xml
Index: project-descriptor.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/xdocs/project-descriptor.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- project-descriptor.xml 9 Apr 2002 14:22:06 -0000 1.16
+++ project-descriptor.xml 10 Apr 2002 19:07:37 -0000 1.17
@@ -288,59 +288,147 @@
with a project. There are several elements that describe a
project's build environment. Each one is described below:
</p>
+ <table>
+ <tr><th>Element</th><th>Description</th></tr>
+ <tr>
+ <td>name</td>
+ <td>
+ The full name of the project. This value is used when
+ generating <a href="build-file.html#javadocs">JavaDoc</a>
+ titles.
+ </td>
+ </tr>
+ <tr>
+ <td>unitTestSourceDirectory</td>
+ <td>
+ This element specifies a directory containing the unit test
+ source of the project. The generated build system will
+ compile these directories when the project is being tested.
+ The unit tests must use the JUnit test framework.
+ </td>
+ </tr>
+ <tr>
+ <td>integrationUnitTestSourceDirectory</td>
+ <td>
+ This element specifies a directory containing the
+ integration unit test source of the project. The generated
+ build system will compile these directories when the project
+ is being tested. The integration unit tests must use the
+ Cactus test framework.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#sourceDirectories">sourceDirectories</a></td>
+ <td>
+ This element specifies the directories containing the source
+ of the project. The generated build system will compile
+ these directories when the project is built. Each source
+ directory is specified by a <code>sourceDirectory</code>
+ element.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#aspectSourceDirectories">aspectSourceDirectories</a></td>
+ <td>
+ This element specifies the directories containing Aspect
+ sources of the project. The generated build system will
+ compile these directories when the project is built if
+ Aspects have been enabled (see the <a
+ href="properties.html">Properties</a> document). Each
+ Aspect source directory is specified by a
+ <code>aspectSourceDirectory</code> element.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#jarResources">jarResources</a></td>
+ <td>
+ This element specifies any additional resources that should
+ be packaged up inside the JAR file. Each resource is
+ specified by a <code>jarResource</code> element.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#jars">jars</a></td>
+ <td>
+ This element specifies the additional JARs that should be
+ packaged as part of the final JAR. [TODO: not quite sure how
+ this is different than jarResources, need further
+ clarification.] Each additional JAR is specified by a
+ <code>jar</code> element.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="#unitTestPatterns">unitTestPatterns</a></td>
+ <td>
+ This element specifies the Java source file patterns to
+ indicate which files are unit tests in the
+ <code>unitTestSourceDirectory</code>. Each pattern is
+ specified by a <code>unitTestPattern</code> element.
+ </td>
+ </tr>
+ <tr>
+ <td><a
href="#integrationUnitTestPatterns">integrationUnitTestPatterns</a></td>
+ <td>
+ This element specifies the Java source file patterns to
+ indicate which files are integration unit tests in the
+ <code>integrationUnitTestSourceDirectory</code>. Each
+ pattern is specified by a
+ <code>integrationUnitTestPattern</code> element.
+ </td>
+ </tr>
+ </table>
<subsection name="jarResources">
<table>
<tr><th>Element</th><th>Description</th></tr>
<tr>
<td>jarResource</td>
<td>
- The path name of the resource to be packaged. This path
- is relative to <code>${basedir}</code> unless it has been
- overridden via the
+ The pattern specifying the resource to be packaged in the
+ JAR file created by the <a
+ href="build-file.html#maven:jar">maven:jar</a> target. This
+ value can be either: <code>include = AntPattern</code>,
+ <code>exclude = AntPattern</code>, or a JAR descriptor
+ file. The path name is relative to
+ <code>${basedir}</code> unless it has been overridden via
+ the
<a href="properties.html#Directory Layout
Settings"><code>${jarResources.basedir}</code></a> property.</td>
</tr>
</table>
- <p>
- This element specifies any additional resources that should be
- packaged up inside the JAR file.
- </p>
</subsection>
- <subsection name="unitTestClassEntries">
+ <subsection name="unitTestPatterns">
<table>
<tr><th>Element</th><th>Description</th></tr>
<tr>
- <td>unitTestClassEntry</td>
+ <td>unitTestPattern</td>
<td>
- The pattern specifying a set of classes. This value can
- be either: <code>include = AntPattern</code>,
+ The pattern specifying a set of Java source files. This
+ value can be either: <code>include = AntPattern</code>,
<code>exclude = AntPattern</code>, or a JAR descriptor
- file.
+ file. Note: these patterns specify <code>.java</code>
+ sources and not <code>.class</code> files. These unit
+ tests must use the <a
+ href="http://www.junit.org";>JUnit</a> testing framework.
</td>
</tr>
</table>
- <p>
- This element specifies the classes which consist of the
- project's unit tests. These unit tests must use the <a
- href="http:www.junit.org">JUnit</a> testing framework.
- </p>
</subsection>
- <subsection name="integrationUnitTestClassEntries">
+ <subsection name="integrationUnitTestPatterns">
<table>
<tr><th>Element</th><th>Description</th></tr>
<tr>
- <td>integrationUnitTestClassEntry</td>
+ <td>integrationUnitTestPattern</td>
<td>
- The pattern specifying a set of classes. This value can
- be either: <code>include = AntPattern</code>,
+ The pattern specifying a set of Java source files. This
+ value can be either: <code>include = AntPattern</code>,
<code>exclude = AntPattern</code>, or a JAR descriptor
- file.
+ file. Note: these patterns specify <code>.java</code>
+ sources and not <code>.class</code> files. These unit
+ tests must use the <a
+ href="http://jakarta.apache.org/cactus";>Cactus</a>
+ testing framework.
</td>
</tr>
</table>
- <p>
- This element specifies the classes which consist of the
- project's integration unit tests.
- </p>
</subsection>
<subsection name="sourceDirectories">
<table>
@@ -349,32 +437,11 @@
<td>sourceDirectory</td>
<td>
A directory containing source that should be compiled as
- part of a project.
- </td>
- </tr>
- </table>
- <p>
- This element specifies the directories containing the source
- of the project. The generated build system will compile these
- directories when the project is built.
- </p>
- </subsection>
- <subsection name="testSourceDirectories">
- <table>
- <tr><th>Element</th><th>Description</th></tr>
- <tr>
- <td>testSourceDirectory</td>
- <td>
- A directory containing source that should be compiled as
- part of a project's tests.
+ part of a project. This directory is relative to the
+ <code>${basedir}</code>.
</td>
</tr>
</table>
- <p>
- This element specifies the directories containing the test
- source of the project. The generated build system will
- compile these directories when the project is being tested.
- </p>
</subsection>
<subsection name="aspectSourceDirectories">
<table>
@@ -383,16 +450,11 @@
<td>aspectSourceDirectory</td>
<td>
A directory containing source that should be compiled as
- part of a project's aspects.
+ part of a project's aspects. The directory is relative to
+ <code>${basedir}</code>.
</td>
</tr>
</table>
- <p>
- This element specifies the directories containing the AspectJ
- source of the project. The generated build system will
- compile these directories when the project is <a
- href="build-file.html">built</a> using Aspects.
- </p>
</subsection>
<subsection name="jars">
<table>
@@ -400,16 +462,13 @@
<tr>
<td>jar</td>
<td>
- A JAR that should be packaged in the project's JAR.
+ A JAR that should be packaged in the project's JAR. This
+ can be used to package additional JAR files with your
+ project. The JAR is relative to <code>${basedir}</code>
+ if an absolute path is not used.
</td>
</tr>
</table>
- <p>
- This element specifies the additional JARs that should be
- packaged as part of the final JAR. [TODO: not quite sure how
- this is different than jarResources, need further
- clarification.]
- </p>
</subsection>
</section>
</body>
