2.3.1. Installing Maven on Mac OSX

You can download a binary release of Maven from http://maven.apache.org/download.html. Download the current release of Maven in a format that is convenient for you to work with. Pick an appropriate place for it to live, and expand the archive there. If you expanded the archive into the directory /usr/local/maven-2.0.9, you may want to create a symbolic link to make it easier to work with and to avoid the need to change any environment configuration when you upgrade to a newer version:

/usr/local % ln -s maven-2.0.9 maven
/usr/local % export M2_HOME=/usr/local/maven
/usr/local % export PATH=${M2_HOME}/bin:${PATH}

Once Maven is installed, you need to do a couple of things to make it work correctly. You need to add its bin directory in the distribution (in this example, /usr/local/maven/bin) to your command path. You also need to set the environment variable M2_HOME to the top-level directory you installed (in this example, /usr/local/maven).

You'll need to add both M2_HOME and PATH to a script that will run every time you login. To do this, add the following lines to .bash_login.

export M2_HOME=/usr/local/maven
export PATH=${M2_HOME}/bin:${PATH}

Once you've added these lines to your own environment, you will be able to run Maven from the command line.

2.3.2. Installing Maven on Microsoft Windows

Installing Maven on Windows is very similar to installing Maven on Mac OSX, the main differences being the installation location and the setting of an environment variable. This book assumes a Maven installation directory of c:\Program Files\maven-2.0.9, but it won't make a difference if you install Maven in another directory as long as you configure the proper environment variables. Once you've unpacked Maven to the installation directory, you will need to set two environment variables—PATH and M2_HOME. To set these environment variables from the command-line, type in the following commands:

C:\Users\tobrien > set M2_HOME=c:\Program Files\maven-2.0.9
C:\Users\tobrien > set PATH=%PATH%;%M2_HOME%\bin

Setting these environment variables on the command-line will allow you to run Maven in your current session, but unless you add them to the System environment variables through the control panel, you'll have to execute these two lines every time you log into your system. You should modify both of these variables through the Control Panel in Microsoft Windows.

2.3.3. Installing Maven on Linux

To install Maven on a Linux machine follow the exact procedure outlined in Section 2.3.1, “Installing Maven on Mac OSX”.

2.3.4. Installing Maven on FreeBSD or OpenBSD

To install Maven on a FreeBSD or OpenBSD machine, follow the exact procedure outlined in Section 2.3.1, “Installing Maven on Mac OSX”.

2.5.1. User-specific Configuration and Repository

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:

2.5.2. Upgrading a Maven Installation

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-2.0.9). Then switch the symbolic link /usr/local/maven from /usr/local/maven-2.0.9 to /usr/local/maven-2.future. Since, you've already set your M2_HOME variable to point to /usr/local/maven, you won't need to change any environment variables.

If you have installed Maven on a Windows machine, simply unpack Maven to c:\Program Files\maven-2.future and update your M2_HOME variable.

2.7.1. Describing a Maven Plugin

Once you start using Maven, you'll spend most of your time trying to get more information about Maven Plugins: How do plugins work? What are the configuration parameters? What are the goals? The help:describe goal is something you'll be using very frequently to retrieve this information. With the plugin parameter you can specify a plugin you wish to investigate, passing in either the plugin prefix (e.g. maven-help-plugin as help) or the groupId:artifact[:version], where version is optional. For example, the following command uses the Help plugin's describe goal to print out information about the Maven Help plugin.

$ mvn help:describe -Dplugin=help
...
Group Id:  org.apache.maven.plugins
Artifact Id: maven-help-plugin
Version:     2.0.1
Goal Prefix: help
Description:

The Maven Help plugin provides goals aimed at helping to make sense out of
    the build environment. It includes the ability to view the effective
    POM and settings files, after inheritance and active profiles
    have been applied, as well as a describe a particular plugin goal to give 
    usage information.
...

Executing the describe goal with the plugin parameter printed out the Maven coordinates for the plugin, the goal prefix, and a brief description of the plugin. While this information is helpful, you'll usually be looking for more detail than this. If you want the Help plugin to print a full list of goals with parameters, execute the help:describe goal with the parameter full as follows:

$ mvn help:describe -Dplugin=help -Dfull
...
Group Id:  org.apache.maven.plugins
Artifact Id: maven-help-plugin
Version:     2.0.1
Goal Prefix: help
Description:

The Maven Help plugin provides goals aimed at helping to make sense out of
    the build environment. It includes the ability to view the effective
    POM and settings files, after inheritance and active profiles
    have been applied, as well as a describe a particular plugin goal to 
    give usage information.

Mojos:

===============================================
Goal: 'active-profiles'
===============================================
Description:

Lists the profiles which are currently active for this build.

Implementation: org.apache.maven.plugins.help.ActiveProfilesMojo
Language: java

Parameters:
-----------------------------------------------

[0] Name: output
Type: java.io.File
Required: false
Directly editable: true
Description:

This is an optional parameter for a file destination for the output of 
this mojo...the listing of active profiles per project.

-----------------------------------------------

[1] Name: projects
Type: java.util.List
Required: true
Directly editable: false
Description:

This is the list of projects currently slated to be built by Maven.

-----------------------------------------------

This mojo doesn't have any component requirements.
===============================================

... removed the other goals ...

This option is great for discovering all of a plugin's goals as well as their parameters. But sometimes this is far more information than necessary. To get information about a single goal, set the mojo parameter as well as the plugin parameter. The following command lists all of the information about the Compiler plugin's compile goal.

$ mvn help:describe -Dplugin=compiler -Dmojo=compile -Dfull