Technology: Maven Basics

This is a short introduction on the basic features of Maven and how to use them.

Installing Maven

This section gives a brief overview on how to install Maven on your system.

  • As Maven depends on Java, Java must be installed and the enviroment variable JAVA_HOME must be set correctly.
  • Download Maven from the Apache Site and extract the archive to a directory of your choice (Notice that directories or paths that contain spaces can cause problems during build time).
  • To execute Maven from any location of your system add the path to the Maven binaries to the system path.
  • Test Maven by typing and running mvn --version into a console window. It should result in a message like:
Maven version: 2.2.1
Java version: 1.6.0
OS name: "Windows XP"
				
  • Windows users should also consider to move the Maven repository, which is created in C:\Dokumente und Einstellungen\User\.m2\repository, to a directory that includes no spaces in its path. Don't forget to update the path of the repository within the tag <localrepository> in installdir\conf\settings.xml.

Creating a project with Maven

This section shows how to create a project and configure the necessary files for your own needs.

Creating the structure of a project

This part shows how to create a new project with Maven Archetypes and introduces the project structure.

  • Open a console window and go to the directory that should contain your project.
  • Type and run:
mvn archetype:generate 
-DarchetypeGroupId=org.apache.maven.archetypes
-DarchetypeArtifactId=maven-archetype-quickstart 
-DgroupId=com.mycompany.app 
-DartifactId=my-app				
				

The following project structure will be created by Maven:

my-app
|- src
|  |- main
|  |  `- java
|  |     `- com
|  |        `- mycompany
|  |           `- app
|  |              `- App.java
|  `- test
|     `- java
|        `- com
|           `- mycompany
|              `- app
|                 `- AppTest.java
`- pom.xml				
				
  • The value that was used as groupId builds up the directory structure com\mycompany\app and already represents the Java package structure. So the class App belongs to the Java package com.mycompany.app.
  • If the Java project needs other files like external images or configuration files a directory resources within the branch main and/or test should be created. The files from the folder are bound to the project during build time and can be used directly in the project (see Constants.java).

Configuring the Project Object Model (POM)

This chapter covers the configuration of the POM for usage in an individual project.

The pom.xml is the main configuration file of a Maven project. In its basic form (after the creation) only few values exist within the file. The structure of the file is pictured below:

<project>
  <modelVersion>4.0.0</modelVersion> 
  <groupId>at.ac.tuwien.ifs.qse</groupId> 
  <artifactId>projekt</artifactId> 
  <packaging>jar</packaging> 
  <version>1.0-SNAPSHOT</version> 
  <name>projekt</name> 
  <url>http://maven.apache.org</url> 
  <dependencies>
    <dependency>
      <groupId>junit</groupId> 
      <artifactId>junit</artifactId> 
      <version>4.7</version> 
      <scope>test</scope> 
    </dependency>
  </dependencies>
</project>
				
  • The values name and packaging are mandatory in the POM. The project can be identifed and called from other projects by its name.
  • In the section dependencies all external libraries can be mentioned that should be available in the project (see also Reference).
  • The section reporting (not in the example above) contains all Maven plugins responsible for automatic report generation.
  • If you are new at editing POMs it is strongly recommended to take the POM from the basic example and change some sections to recognize the effects.
  • A POM for a real project can be found here.

Build Lifecycle

This section introduces the phases of the Maven build process and how to use them.

Clean Phase

To clean the target folders, use the command

mvn clean

The Clean Plugin can also be configured to clean other directories than the target folder. For further information read the Plugin documentation.

Compile Phase

To build the project, use:

mvn compile

Test Phase

To run the tests, use:

mvn test

Package Phase

To package the class files to format defined in the POM, use:

mvn package

To install the packaged project in the Maven 2 repository, use:

mvn install

Install Phase

To build and install the project, go into the root of the project and run the command:

mvn install

Maven 2 will automatically identify and download needed ressources. This is only done during the first time; the downloaded dependencies will be stored in your local Maven repository (M2_HOME). The POM is configured to use a mirror of the repository at the QSE, but even so, you might encounter timeouts during the initial download. Simply restart the build process.

The output of the build process (class files, the project site etc.) is stored in the target/subdirectory.

Site (Documentation) Phase

To build the Maven project site (the one you are just looking at right now), use:

mvn site

This creates a directory target\site where all html files can be found that represent the documentation..

IDE Preperation

You can prepare the project for some IDEs like Eclipse or Netbeans.

To prepare a project for Eclipse, use:

mvn eclipse:eclipse

This command creates all necessary files and folders used by Eclipse. The structure of your project (at root level) then looks like this:

my-app
|- .settings
|- src
|- target
|- .classpath
|- .projekt
`- pom.xml
				

The project can be imported to Eclipse directly with the dialog New - Project - Create project from existing source.

To clean the Eclipse specific files from the project, use:

mvn eclipse:clean

When using CVS/SVN it is recommended, that you only upload a clean project structure, without any IDE specific files and folders.

Further Information

You can also combine more than one goal in a single command:

mvn clean compile package

This will first clean all structures and then compile the sources to new target folders and package them.

Reference Material