This document defines some conventions that Maven recommends projects adopt. This is especially important if you intend to distribute your project publicly.
This section outlines the naming conventions used in the Maven project object model (POM). This document is an attempt to try and unify the many various ways projects name the artifacts that they publish for general consumption by the Java developer community (regardless of whether they are using Maven).
The first thing you will do when creating a project is to select a group ID and an artifact ID. If you are building a project to be part of a larger product that is already using Maven, you should attempt to follow any patterns already established by other projects for consistency.
These identifiers should be comprised of lowercase letters, digits, and hyphens only.
In general you should select a group ID that describes the entire product, and artifact IDs that are the basis of filenames for each item you distribute. The artifact ID may or may not overlap the group ID.
For example:
maven : maven-core maven : wagon-api
As previously mentioned, the artifact ID should be the basis of the filename for the project, as by default Maven will use that and the version to assemble the filename. Having the version as part of the filename is strongly recommended to ensure that the version can be determined at a glance without having to check a possibly non-existant manifest, or compare file sizes with the official releases.
Following these guidelines are particularly encouraged when distributing via the Maven Repository, to ensure that it can easily fit alongside other projects and reduce the risk of conflicts and confusion.
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.
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 can't these settings can be overridden via the project descriptor.
/ +- src/ | +- main/ | | +- java/ | | | +- ... | | +- resources/ | | +- ... | +- test/ | | +- java/ | | | +- ... | | +- resources/ | | +- ... | +- site/ | +- xdoc/ | +- ... +- target/ | +- ... +- project.xml +- README.txt +- LICENSE.txt
At the top level files descriptive of the project: a project.xml file (and any properties,
maven.xml or build.xml if using Ant). In addition, there are textual documents meant
for the user to be able to read immediately on receiving the source: README.txt,
LICENSE.txt, BUILDING.txt, etc.
There are just two subdirectories of this structure: src and target. The only other
directories that would be expected here are metadata like CVS or .svn, and any
subprojects in a multiproject build (each of which would be laid out as above).
Note: currently, Maven 1.x violates this principle by defaulting the xdocs location to the
top level directory. It is proposed that in future this be moved to src/site/xdoc.
The target directory is used to house all output of the build.
The src directory contains all of the source material for building the project, its site and so on.
It contains a subdirectory for each type: main for the main build artifact, test for
the unit test code and resources, site and so on.
Within artifact producing source directories (ie. main and test), there is one
directory for the language java (under which the normal package hierarchy exists), and one for
resources (the structure which is copied to the target classpath given the default resource
definition).
If there are other contributing sources to the artifact build, they would be under other subdirectories: for
example src/main/antlr would contain Antlr grammar definition files.
PDF Documentation