Maven directory structure

Maven is a very powerful tool. Often it is considered maven is complicated in it's use. This is true if basic concepts and standards are unclear. Maven uses Convention over Configuration, so to understand maven you have to understand its conventions. Let us get into the first convention the standard Maven directory structure.

Table of Contents

  1. Understanding Maven directory structure
    1. Maven directory structure for sources
    2. Maven directory structure for build artifacts
    3. Content of maven's root directory
    4. Content of maven's src directory
    5. Content of maven's target directory
  2. Create your project folders
  3. Conclusion

1. Understanding Maven directory structure

The first convention over configuration is maven's folder structure. With a clear directory layout every project will look very similar. Since the projects look very similar, the build will be also very similar. The benefit is also, that other developers can easily understand the build also.

Persons who come from make or ANT, will pretty well know how complex such builds can get. And how hard it is to learn the concepts of each and every build system. Maven was the first great approach in Java to cleanup the mess in build systems.

1.1. Maven directory structure for sources

maven folder structure auto created usage
project         your project directory, can have any arbitrary name
├─── src       directory containing all your sources
│    ├──── main     below this folder all sources will be used to generate the final artifacts (without testing stuff)
│    │     ├───── java  yes, default here you will add all your java sources
│    │     ├───── javascript   here you will add all your javascript sources (folder may conflict with javascript frameworks)
│    │     ├───── resources  yes, default add your resources like translation files or any other files, which do not need to be changed during build
│    │     ├───── resources-filtered   add your resources here, which need to be changed (filtered) during the build
│    │     ├───── filters   add your filter files (defines key and values) for filtering resources-filtered during the build
│    │     ├───── webapp   if you create a webapp (war) you will need this folder structure for automagically building a war file
│    │     ├───── assembly    
│    │     ├───── config    
│    │     ├───── diagram   if you have some diagrams for your team or your client, use this folder
│    │       └───── scripts    
│    ├──── test     directory containing all your test sources for testing this project
│    │     ├───── java   yes, default here you will add all your java testing sources
│    │     ├───── javascript   here you will add all your javascript testing sources (folder may conflict with javascript frameworks)
│    │     ├───── resources   add your testing resources which do not get changed during build
│    │     ├───── resources-filtered   add your testing resources which get changed during build
│    │       └───── filters   add your filter files for filtering resources-filtered during the build
│    ├──── it     folder for integration tests
│    ├──── assembly     Assembly descriptors
│    └──── site     mostly the website of the project

The above table contains beside of the basic maven directory structure, also folders which XENOVATION's developers are using in their development process.

1.2. Maven directory structure for build artifacts

maven folder structure auto created usage
project       your project directory, can have any arbitrary name
└─── target     yes, on build the build target folder. All files generated by the build get moved or created here
  ├─── classes   yes, on build the compiled classes from src/main/java
  ├─── test-classes   yes, on build the compiled test classes from src/test/java
  ├─── generated-sources   yes, on build the generated sources from src/main/ e.g. by apt (annotation processor)
  ├─── generated-test-sources   yes, on build the generated sources from src/test/ e.g. by apt (annotation processor)
  ├─── antrun   yes, on build output generated during executing ANT targets in maven build
  └─── test-output   yes, on build junit or testng output shall land here

The above table is the default maven directory structure for all output files, which are generated by the build itself.

1.3. Content of maven's root directory

As a convention in maven projects you will find in the root directory this files:

  • pom.xml
    this is maven's build file, which defines what, with, how and where the build is done
  • LICENSE.txt
    this are the licensing information of your project
  • README.txt
    here you add details, summary and all relevant information about your project
  • NOTICE.txt
    any additional information which may be third-party libraries which are used in your project

1.4. Content of maven's src directory

This folder holds typically all your files, which are the source for the artifacts, which are build with this maven project.

  • src/main
    this folder contains typically all source files, which will be used to create artifacts of this project. This artifacts here (like jar, war, ear) are typically referenced as dependencies in other maven projects.
  • src/test
    this folder contains all files, which are needed to test your project. The generated files of this folder, typically end in a separate test artifact, and are not used for dependencies in other projects.

1.5. Content of maven's target directory

This folder is used as intermediate folder during the build. This is also the location, where you will find your finally created artifacts if the build finishes successful.

2. Create your project folders

This bash script helps you to create the needed maven folder structure in your project.

mkdir -p src/main/java
mkdir -p src/main/javascript
mkdir -p src/main/resources
mkdir -p src/main/filters
mkdir -p src/main/assembly
mkdir -p src/main/config
mkdir -p src/main/diagram
mkdir -p src/main/scripts
mkdir -p src/main/webapp/WEB-INF/lib
mkdir -p src/test/java
mkdir -p src/test/javascript
mkdir -p src/test/resources
mkdir -p src/test/filters
mkdir -p src/site
# build destination,  will be created by maven automatically
mkdir -p target 
mkdir -p target/classes
mkdir -p target/test-classes
mkdir -p target/generated-sources
mkdir -p target/generated-test-sources
mkdir -p target/antrun
mkdir -p target/test-output
# create gitignore
echo "target/" >> .gitignore
for srcDir in `find . -type d|grep src`; do
   touch $srcDir/.gitignore
done

3. Conclusion

In this article you have seen how you can easily create your required folder structure. Maven's impact in java was big. You will even see in other build systems, that developers are reusing maven directory structure as a very good principle. So even if you end using basic ANT, we recommend to use maven's directory structure.

More to read about Maven in Maven properties, Maven profiles and Maven lifecycle & Maven phases