Maven: The Complete Reference
Maven’s download measures in at roughly 1.5 MiB, it has attained such a slim download size because the core of Maven has been designed to retrieve plugins and dependencies from a remote repository on-demand. When you start using Maven, it will start to download plugins to a local repository described in Section 2.5.1, “User-specific Configuration and Repository”. In case you are curious, let’s take a quick look at what is in Maven’s installation directory.
/usr/local/maven $ ls -p1 LICENSE.txt NOTICE.txt README.txt bin/ boot/ conf/ lib/
LICENSE.txt contains the software license for Apache Maven. This license is described in some detail later in the section Section 2.8, “About the Apache Software License”. NOTICE.txt contains some notices and attributions required by libraries that Maven depends on. README.txt contains some installation instructions. bin/ contains the mvn script that executes Maven. boot/ contains a JAR file (classwords-1.1.jar) that is responsible for creating the Class Loader in which Maven executes. conf/ contains a global settings.xml that can be used to customize the behavior of your Maven installation. If you need to customize Maven, it is customary to override any settings in a settings.xml file stored in ~/.m2. lib/ contains a single JAR file (maven-core-3.0.3-uber.jar) that contains the core of Maven.
Unless you are working in a shared Unix environment, you should avoid customizing the settings.xml in M2_HOME/conf. Altering the global settings.xml file in the Maven installation itself is usually unnecessary and it tends to complicate the upgrade procedure for Maven as you’ll have to remember to copy the customized settings.xml from the old Maven installation to the new installation. If you need to customize settings.xml, you should be editing your own settings.xml in ~/.m2/settings.xml.
Once you start using Maven extensively, you’ll notice that Maven has created some local user-specific configuration files and a local repository in your home directory. In ~/.m2 there will be:
- A file containing user-specific configuration for authentication, repositories, and other information to customize the behavior of Maven.
- This directory contains your local Maven repository. When you download a dependency from a remote Maven repository, Maven stores a copy of the dependency in your local repository.
In Unix (and OSX), your home directory will be referred to using a tilde (i.e. ~/bin refers to /home/tobrien/bin). In Windows, we will also be using ~ to refer to your home directory. In Windows XP, your home directory is C:\Documents and Settings\tobrien, and in Windows Vista, your home directory is C:\Users\tobrien. From this point forward, you should translate paths such as ~/m2 to your operating system’s equivalent.
If you’ve installed Maven on a Mac OSX or Unix machine according to
the details in Section 2.3.1, “Installing Maven on Mac OSX” and
Section 2.3.3, “Installing Maven on Linux”, it should be easy to upgrade to
newer versions of Maven when they become available. Simply install the
newer version of Maven (/usr/local/maven-2.future) next to the
existing version of Maven (/usr/local/maven-3.0.3). Then switch the
symbolic link /usr/local/maven from /usr/local/maven-3.0.3 to
/usr/local/maven-2.future. Since, you’ve already set your
variable to point to /usr/local/maven, you won’t need to change any
If you have installed Maven on a Windows machine, simply unpack Maven
to c:\Program Files\maven-2.future and update your
If you have any customizations to the global settings.xml in M2_HOME/conf, you will need to copy this settings.xml to the conf directory of the new Maven installation.
If you are upgrading from Maven 1 to Maven 2, you are going to be
using an entirely new POM and repository structure. If you have
already created a custom Maven 1 repository to hold custom artifacts,
you can use the Nexus Repository Manager to expose a Maven 1
repository in a format that can be understood by Maven 2 clients. For
more information about the Nexus Repository Manager, see
Management with Nexus. In addition to tools like Nexus, you can also
configure references to repositories to use the
format. For more information about configuring a reference to a legacy
repository, see Section 15.2.8, “Repositories”.
If you have a set of Maven 1 projects, you may want to know about the
Maven One Plugin. The Maven One Plugin was designed to help projects
migrate from Maven 1 to Maven 2. If you have a Maven 1 project, you
can convert the project’s POM by running the
one:convert goal as
$ cd my-project $ mvn one:convert
one:convert will read a project.xml and produce a pom.xml that
is compatible with Maven 2. If you’ve customized a Maven 1 build using
Jelly script in a maven.xml file, you will need to investigate other
options. While Maven 1 emphasized Jelly scripting for customizing
builds, Maven 2 favors custom plugins or customization through
scripting Plugins or the Maven Antrun Plugin.
The most important thing to know about when upgrading from Maven 1 to Maven 2 is that Maven 2 is a completely different build framework. Maven 2 introduces the concept of the Maven Lifecycle and redefines the relationships between plugins. If you upgrade from Maven 1 to Maven 2, you need to invest some time in learning about the differences between the two versions. Although it might seem straightforward to start learning about the new POM structure, you should focus on the Lifecycle first. If you understand the Maven Lifecycle, you will be able to use Maven to its fullest potential.