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.

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