Pete Kazmier Ceki Gülcü Jon S. Stevens Peter Donald Maven Directory Layout

Rationale

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.

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.

The next two sections document the directory layout expected by Maven and the directory layout created by Maven. Please try to conform to this structure as much as possible; however, if you must these settings can be overridden via properties as documented in the Integration document.

Common Directory Layout

Directory or file name Content Comment
LICENSE.txt The license for the project. This file contains the license that applies to the project. Each source file should included this header. By default, if a source file does not include this file, it will be noted in the Checkstyle report that is generated.
src/ Source code. 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. The separation into directories according to function (src/share, src/core, src/web) is currently not supported by Maven. It is highly recommended that sub-directories be used under src/.
src/test Unit test source code. 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.
src/announcements Contains a record of announcements. 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 Build File documentation for more information on announcements.
xdocs/ Documentation files in XML format. Maven projects use Jelly/JSL to transform documentation files in XML into HTML. Project documentation should be placed in this directory. Maven converts all XML files in this directory using JSL. Non-XML files (and directories) are copied without modificiation to permit the inclusion of "other" types of documentation (including images). The generated HTML files automatically inherit the Maven look-and-feel by default. Documentation on the xdoc format is available.
xdocs/navigation.xml Navigation links for site. Maven projects use Jelly stylesheets to transform documentation files in XML into HTML (XHTML for the most part). This file includes the navigation links that are added to each xdoc transformed in the xdocs directory. Documentation on the xdocs/project.xml format is available. For backwards compatibility, this file may also be located in the xdocs/stylesheets directory.

See site creation documentation for more information including details of the enhancements Maven has made to the xdoc format.
project.properties A file defining project properties.

This file can be used to override Maven default properties for the core and properties for the various plugins.

It can also be used to define any Maven properties used by a project. The properties defined in this file should be applicable to most users of your project, as opposed to custom properties for a specific build/user which should be defined in ${project.home}/build.properties.

build.properties A file defining project properties for a specific build.

This file can be used to override Maven default properties for the core, plugins or any project default properties (defined in ${project.home}/project.properties).

The properties defined in this file should not be checked into CVS because they are specific to a build, as opposed to project-wide properties defined in ${project.home}/project.properties.

Maven-Generated Layout

Directory name Content Comment
target/ Contains compiled classes and JARs. The contents of the target/ directory should be enough to use the project. This directory contains the final JARs that are generated.
target/classes Contains compiled classes and JARs. The target/classes directory contains all compiled classes. This directory is used when packaging the final JAR for a project.
target/test-classes Contains compiled unit test classes. The target/test-classes directory contains all compiled unit test classes. This directory is used when executing the unit tests.
target/generated-docs Contains Maven generated xdocs. 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.
target/test-reports Contains the individual unit test results. 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.
target/docs Documentation files intended for the website publication. 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.
target/docs/index.html Starting point for browsing the documentation. 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 description element in the project descriptor.
target/docs/apidocs API documentation. 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.
target/docs/xref Cross-referenced source code. 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 cross-referenced sources and vice versa.
target/docs/xref-test Cross-referenced test source code. Maven automatically generates cross-referenced test source code that enables an easy way to show developers how to use your software properly.
target/docs/mail-lists.html Mailing list documentation. Maven automatically generates a list of mailing lists based on the information provided in the project descriptor.
target/docs/team-list.html The list of project team members. Maven automatically generates a list of project team members based on the information provided in the project descriptor.
target/docs/dependencies.html The list of dependencies. Maven automatically generates a list of dependencies based on the information provided in the project descriptor.
target/docs/changelog.html The CVS change log. Maven automatically generates a change log from CVS log messages. This log is currently limited to the past 30 days (but will be configurable in the future).
target/docs/file-activity-report.html The File Activity Report. Maven automatically generates a log from your SCM listing file changes in the last 30 days.
target/docs/developer-activity-report.html The Developer Activity Report. Maven automatically generates a log from your SCM listing changes per developer in the last 30 days.
target/docs/jdepend-report.html Metric report. Maven automatically generates a report on various source code metrics. This report can provide further insight into a project.
target/docs/junit-report.html Unit test report. Maven automatically generates a report on the results of unit testing. This report provides a confidence level for users of your project.
target/docs/checkstyle-report.html Checkstyle report. Maven automatically generates a report on the results of Checkstyle. This report provides assurance that the coding conventions for your project are being followed.

Points to keep in mind

It is recommended to include a .cvsignore file in top-level directory under CVS control in order to avoid the distracting "?" message output during CVS update.