kaz 02/03/20 19:51:14
Modified: xdocs dirlayout.xml
Log:
First crack at the Maven directory structure. This document describes
all of the documentation that is generated by Maven.
Revision Changes Path
1.4 +269 -288 jakarta-turbine-maven/xdocs/dirlayout.xml
Index: dirlayout.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/xdocs/dirlayout.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- dirlayout.xml 5 Mar 2002 01:42:59 -0000 1.3
+++ dirlayout.xml 21 Mar 2002 03:51:14 -0000 1.4
@@ -2,298 +2,279 @@
<document>
<properties>
+ <author email="[EMAIL PROTECTED]">Pete Kazmier</author>
<author email="[EMAIL PROTECTED]">Ceki Gülcü</author>
<author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
<author email="[EMAIL PROTECTED]">Peter Donald</author>
- <title>Jakarta Directory Layout</title>
+ <title>Maven Directory Layout</title>
</properties>
-<body>
+ <body>
-<section name="Rationale">
-<p>
-Having a common directory layout would allow for users familiar with
-one Jakarta project to immediately feel at home in another Jakarta
-project. The advantages are analogous to adopting a site-wide
-look-and-feel. Common Jakarta procedures strengthen the Jakarta brand.
-</p>
-
-<p>
-The directory structure proposed here is based on best-practices as
-suggested by Jakarta committers. We recognize that the cost of
-changing an existing directory structure can be high. As such, this
-proposal is not binding.
-</p>
-
-<p>Unless specified otherwise, the term project refers to a
-sub-project of the Jakarta project. The terms sub-project and project
-are used interchangeably and the intended meaning should be clear from
-the context.</p>
-
-<p>
-<b>This proposal is subject to approval.</b>
-</p>
-
-</section>
-
-<section name="Common Directory Layout">
-
-<table>
-
- <tr>
- <th>Directory name</th>
- <th>Content</th>
- <th>Comment</th>
- <th>Under CVS Control?</th>
- </tr>
-
- <tr>
- <td>LICENSE.txt</td>
- <td>A copy of the Apache License</td>
-
- <td>The LICENSE.txt should be placed at a prominent location.
- This file should have the suffix .txt so that it can be opened
- easily on platforms that use suffix mappings.</td>
- <td>YES</td>
- </tr>
-
-
- <tr>
- <td>src/</td>
- <td>Source code.</td>
-
- <td><p>The code may be placed into separate source code directories
- by language, as in src/java/ and src/php/ for source code in the Java
- and PHP languages respectively. Other projects may separate the code
- according to function (src/share, src/testcases, src/compat). It is
- highly recomended that sub-directories be used under src/.</p>
-
- </td>
- <td>YES</td>
- </tr>
-
-
- <tr>
- <td>src/xdocs/</td>
- <td>Documentation files in XML format.</td>
-
- <td>The Jakarta site uses Velocity/Anakia or Stylebook to transform
- dcumentation files in XML into HTML. The generated HTML files automatically
- inherit the Jakarta look-and-feel. Documentation is <a
- href="http://jakarta.apache.org/site/jakarta-site2.html";>available</a>.
- </td>
- <td>YES</td>
- </tr>
-
- <tr>
- <td>docs/</td>
- <td>Documentation files intended for the end user.</td>
-
- <td>The docs/ directory contain most of the documentation for the
- Jakarta sub-project. This includes Velocity/Anakia or Stylebook
- generated HTML files. This directory may also contain other
- documentation files. Generally, all documentation is stored in the
- src/xdocs/ directory and then "transformed" into this directory.
-
- It is then checked into
- CVS and checked out of CVS on the live website. This allows the user
- to browse the documentation on the local host without requiring
- network connectivity as well as on the live website. Alternatively
- some projects may place
- </td>
- <td>NO</td>
- </tr>
-
- <tr>
- <td>docs/ or www/</td>
- <td>Web site documentation.</td>
-
- <td>Some projects choose to check in documentation for their website
- to ease maintanence of site. This may be a superset of the
- documentation included in the documentation provided in
- distributions. If the project includes regular distributions then the
- website should be an image of documentation of last release. For
- projects that don't have regular releases and whos website does not
- have highly volatile information (news, bug reports etc.) then it is
- acceptable to use docs/ subdirectory otherwise the www/ directory is
- recomended. Once checked into the CVS it is expected that the
- documentation will also be checked out on live website.
- </td>
- <td>YES</td>
- </tr>
-
- <tr>
- <td>www/index.html</td>
- <td>Starting point for browsing the documentation.</td>
-
- <td>Browsing the documentation locally should yield the same results
- as browsing the documentation on the sub-project home page on the
- Jakarta web site.
- </td>
- <td>YES</td>
- </tr>
-
- <tr>
- <td>docs/api</td>
- <td>API documentation as generated by the Javadoc tool.</td>
-
- <td>Placing the API documenation under docs/api/ makes it slightly
- easier for other documentation files under docs/ to reference API
- documentation and vice versa. It is not recommended to check this
- into CVS. At some point, we will have the <a
- href="http://jakarta.apache.org/alexandria/";>Alexandria</a> project
- building the documentation for all of the Jakarta Projects and making
- the API documentation available that way.
- </td>
- <td>NO</td>
- </tr>
-
- <tr>
- <td>tools/ or build/</td>
- <td>Files required for building the sub-project.</td>
-
- <td>Building includes compiling source code, generating javadoc
- documentation, the creation of jar files and the distribution files
- in tar.gz or zip formats.
- </td>
- <td>YES</td>
- </tr>
-
- <tr>
- <td>build.xml or build/build.xml</td>
- <td>The ANT build script.</td>
-
- <td>All Jakarta projects are required to use ANT as their build tool.
- Note, it is allowable to place this file at the top level directory
- structure.
- </td>
- <td>YES</td>
- </tr>
-
- <tr>
- <td>build.sh build.bat</td>
- <td>Shell scripts for Unix and DOS environments to bootstrap the ANT
- build process.</td>
-
- <td>The existence of these files implies the existence of binary jar
- files, such as ant.jar and xerces.jar under CVS control
- Note, it is allowable to place the shell scripts in subdirectory build/.
- </td>
- <td>YES</td>
- </tr>
-
- <tr>
- <td>tools/lib or build/lib/</td>
- <td>Binary jar files required for building the sub-project.</td>
-
- <td>The jar files are added to the classpath by the bootstrapping
- shell scripts before invoking ANT. The jar files should consist of
- ant.jar as well as jar files needed for XML parsing.
-
- <p>The tools/lib/ or build/lib/ directory should contain jar files needed during
- build time and during build time only. If an XML parser
- is also required during the runtime of the project, then the jar
- files for the parser should be placed under dist/lib/.</p>
-
- </td>
- <td>YES</td>
- </tr>
-
- <tr>
- <td>dist/</td>
-
- <td>This directory is an image of the distribution files. Hence why it is called
"dist" (short
- for distribution).</td>
-
- <td>The contents of the dist/ directory should be enough to use the
- project. The particular format of distribution is project dependent. Some may
generate
- a project.jar and a README while others may have dist the image of a .war file. It
is
- commong to have dist/bin for scripts and dist/lib for jars related to runtime.
- </td>
-
- <td>NO</td>
- </tr>
-
- <tr>
- <td>bin/ or build/</td>
- <td>Intermediate files files generated while building the project.</td>
-
- <td><p>It is to this directory that intermediate files are generated.
- Different types are generally generated to sub-directories (ie .class files
- stored in bin/classes, build/classes, .jar files in bin/lib or build/lib.</p>
- </td>
- <td>NO</td>
- </tr>
-
- <tr>
- <td>distributions/</td>
-
- <td>This directory contains the project release distributions. These are often
- project.tar.gz, project.zip, project.rpm or project.war format.</td>
-
- <td>
- <p>There are generally two forms of releases. Binary releases and
- source releases. Binary releases consist of all the components end-users
- require to use the product. This may include jars and generated documentation.</p>
-
- <p>A source release generally includes an image of CVS repository. Files excluded
- include any proposals/ or whiteboard/ code and the www/ directory. The source
- release will often include generated documentation.</p>
-
- <p>This directory is meaningful only to release managers. End-users
- should be oblivious to it.</p>
-
- </td>
- <td>NO</td>
- </tr>
-
- <tr>
- <td>contribs/</td>
- <td>Contributions not officially part of the sub-project.</td>
-
- <td></td>
- <td>YES</td>
- </tr>
-
- <tr>
- <td>whiteboard/ or proposals/</td>
- <td>Revolutions and other untested code bases.</td>
-
- <td>It is here where developers will host revolutions, forks and other deviations
of codebase.
- </td>
- <td>YES</td>
- </tr>
-
-</table>
-
-</section>
-
-<section name="Points to keep in mind">
-
-<p>It is recommended to include a <code>.cvsignore</code> file in top-level
-directory under CVS control in order to avoid the distracting
-"?" message output during CVS update.
-</p>
-
-<p>If the source is in the Java language, then the package hierrarchy
- for a given project should start at org.apache.PROJECT. For example,
- for the <a href="http://jakarta.apache.org/velocity/";>Velocity</a>
- project, the top-most package is org.apache.velocity.
-</p>
-
-<p>When adding binary files to CVS, the -kb option is automatically
- used for common binary types. See the
- <code>/home/cvs/CVSROOT/cvswrappers</code> file for the exact types.
-</p>
-
-</section>
-
-<section name="ANT build files">
-
-<p>Should we also include directives for ANT build scripts, common
-target names, etc. in this document? [JSS] Yes.
-</p>
-</section>
-
-</body>
+ <section name="Rationale">
+ <p>
+ Having a common directory layout would allow for users familiar
+ with one Maven project to immediately feel at home in another
+ Maven project. The advantages are analogous to adopting a
+ site-wide look-and-feel. Common Maven procedures strengthen the
+ Maven brand.
+ </p>
+ <p>
+ The directory structure proposed here is based on best-practices
+ as suggested by Jakarta committers. We recognize that the cost
+ of changing an existing directory structure can be high. As
+ such, this proposal is not binding. However, integrating Maven
+ into a project that does not follow the recommendations in this
+ proposal will require additional integration work.
+ </p>
+ </section>
+
+ <section name="Common Directory Layout">
+ <table>
+ <tr>
+ <th>Directory name</th>
+ <th>Content</th>
+ <th>Comment</th>
+ <th>Under CVS Control?</th>
+ </tr>
+ <tr>
+ <td>src/</td>
+ <td>Source code.</td>
+ <td>
+ The code may be placed into separate source code directories
+ by language, as in src/java/ and src/php/ for source code in
+ the Java and PHP languages respectively. Other projects may
+ separate the code according to function (src/share,
+ src/test, src/rttest). It is highly recommended that
+ sub-directories be used under src/.
+ </td>
+ <td>YES</td>
+ </tr>
+ <tr>
+ <td>src/test</td>
+ <td>Unit test source code.</td>
+ <td>
+ This directory typically contains all of the unit testing
+ code. JUnit is the framework used by Maven for unit testing
+ so classes in these files should use the JUnit framework.
+ </td>
+ <td>YES</td>
+ </tr>
+ <tr>
+ <td>src/rttest</td>
+ <td>Real-time test source code.</td>
+ <td>
+ This directory typically contains all of the real-time
+ testing code. Real-time testing might utilize tools such as
+ <a href="/cactus">Cactus</a>.
+ </td>
+ <td>YES</td>
+ </tr>
+ <tr>
+ <td>xdocs/</td>
+ <td>Documentation files in XML format.</td>
+ <td>
+ Maven projects use Velocity/DVSL to transform documentation
+ files in XML into HTML. Project documentation should be
+ placed in this directory. Maven converts all user
+ documentation in this directory using DVSL. The generated
+ HTML files automatically inherit the Jakarta look-and-feel
+ by default. Documentation on the xdoc format is <a
+
href="http://jakarta.apache.org/site/jakarta-site2.html";>available</a>.
+ </td>
+ <td>YES</td>
+ </tr>
+ <tr>
+ <td>docs/</td>
+ <td>Documentation files intended for the website publication.</td>
+ <td>
+ The docs/ directory contains only generated documentation
+ that is intended to be published as the project's website.
+ This directory includes the Velocity/DVSL generated HTML
+ files, JavaDocs, cross-referenced sources, and various
+ generated reports. Generally, all documentation is stored
+ in the xdocs/ directory and then "transformed" into this
+ directory. The specific documents that Maven generates are
+ described below.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>docs/index.html</td>
+ <td>Starting point for browsing the documentation.</td>
+ <td>
+ Browsing the documentation locally should yield the same
+ results as browsing the documentation on the project's home
+ page. If a project does not provide an index.xml in the
+ xdocs/ directory, Maven will automatically generate a simple
+ front page based on the <a
+ href="project-descriptor.html#project">description</a>
+ element in the project descriptor.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>docs/apidocs</td>
+ <td>API documentation.</td>
+ <td>
+ Maven automatically generates JavaDocs for projects using
+ the JavaDoc utility. Placing the API documentation under
+ docs/apidocs/ makes it slightly easier for other
+ documentation files under docs/ to reference API
+ documentation and vice versa.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>docs/xref</td>
+ <td>Cross-referenced source code.</td>
+ <td>
+ Maven automatically generates cross-referenced source code
+ that enables easy browsing of an entire source tree.
+ Placing the cross-referenced sources under docs/xref/ makes
+ it slightly easier for other documentation files under docs/
+ to reference API documentation and vice versa.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>docs/mail-lists.html</td>
+ <td>Mailing list documentation.</td>
+ <td>
+ Maven automatically generates a list of mailing lists based
+ on the information provided in the <a
+ href="project-descriptor.html#mailingLists">project
+ descriptor</a>.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>docs/developer-list.html</td>
+ <td>The list of developers.</td>
+ <td>
+ Maven automatically generates a list of developers based
+ on the information provided in the <a
+ href="project-descriptor.html#developers">project
+ descriptor</a>.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>docs/dependencies.html</td>
+ <td>The list of dependencies.</td>
+ <td>
+ Maven automatically generates a list of dependencies based
+ on the information provided in the <a
+ href="project-descriptor.html#dependencies">project
+ descriptor</a>.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>docs/changelog.html</td>
+ <td>The CVS change log.</td>
+ <td>
+ Maven automatically generates a change log from CVS log
+ messages. This log is currently limited to the past 5 days
+ (but will be configurable in the future).
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>docs/jdepend-report.html</td>
+ <td>Metric report.</td>
+ <td>
+ Maven automatically generates a report on various <a
+ href="metrics.html">source code metrics</a>. This report
+ can provide further insight into a project.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>docs/junit-report.html</td>
+ <td>Unit test report.</td>
+ <td>
+ Maven automatically generates a report on the results of
+ unit testing. This report provides a confidence level for
+ users of your project.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>build.xml</td>
+ <td>The ANT build script.</td>
+ <td>
+ All Maven projects are required to use ANT as their build
+ tool. The Maven installation provides a set of generic
+ build files that are referenced from the project's build
+ file using delegators as described in the <a
+ href="build-file.html">build file</a> documentation.
+ </td>
+ <td>YES</td>
+ </tr>
+ <tr>
+ <td>${lib.repo}</td>
+ <td>Binary jar files required for compile / runtime.</td>
+ <td>
+ Maven automatically downloads dependencies into this
+ directory. In addition, all dependencies are automatically
+ added to the classpath. This is the central repository of
+ JARs that is shared across multiple projects.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>target/</td>
+ <td>Contains compiled classes and JARs.</td>
+ <td>
+ The contents of the target/ directory should be enough to
+ use the project. This directory contains the final JARs
+ that are generated.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>target/classes</td>
+ <td>Contains compiled classes and JARs.</td>
+ <td>
+ The target/classes directory contains all compiled classes.
+ This directory is used when packaging the final JAR for a
+ project.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>target/generated-docs</td>
+ <td>Contains Maven generated xdocs.</td>
+ <td>
+ The target/generated-docs directory contains all of the
+ Maven-generated xdocs. All content generated by Maven is
+ first converted to xdoc format, so the same stylesheet used
+ to transform the rest of the site, can be used on generated
+ content. The contents of this directory are transformed and
+ stored in the docs/ directory.
+ </td>
+ <td>NO</td>
+ </tr>
+ <tr>
+ <td>test-reports</td>
+ <td>Contains the individual unit test results.</td>
+ <td>
+ The test-reports/ directory contains individual unit test
+ reports in both XML and plain text formats. The reports in
+ this directory is used when Maven creates the final unit
+ test report.
+ </td>
+ <td>NO</td>
+ </tr>
+ </table>
+ </section>
+ <section name="Points to keep in mind">
+ <p>
+ It is recommended to include a <code>.cvsignore</code> file in
+ top-level directory under CVS control in order to avoid the
+ distracting "?" message output during CVS update.
+ </p>
+ </section>
+ </body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
