Maven Installation, Configuration, and Basic Usage Guide

Maven is a powerful Java build tool that every Java developer should learn. This guide consolidates the basic concepts of Maven, including installation, configuration, command syntax, build lifecycle, and plugin goals.

Installation Maven

The installation steps are straightforward. Before installing, ensure that the JAVA_HOME environment variable points to the JDK directory. You can verify it with: echo $JAVA_HOME If the output is empty, JAVA_HOME is not set correctly. Set it using:

export JAVA_HOME=/path/to/java_home/

To make JAVA_HOME persistent across reboots, add the assignment to .profile or .bash_profile depending on the system.

After configuring JAVA_HOME, install Maven:

Download apache-maven-3.6.3-bin.zip.

Unzip the archive with unzip apache-maven-3.6.3-bin.zip.

Create a MAVEN_HOME environment variable pointing to the unzipped directory.

Add MAVEN_HOME/bin to the PATH variable.

Download Maven:

wget http://mirrors.tuna.tsinghua.edu.cn/apache/maven/maven-3/3.6.3/binaries/apache-maven-3.6.3-bin.zip

Unzip Maven:

unzip apache-maven-3.6.3-bin.zip

Set MAVEN_HOME :

cd apache-maven-3.6.3
pwd # view current directory
export MAVEN_HOME=/Users/yjwfn/bin/apache-maven-3.6.3

Update PATH :

export PATH=$PATH:$MAVEN_HOME/bin

These commands affect only the current shell session. To apply them automatically at startup, add the export lines to ~/.bash_profile or ~/.profile:

vi ~/.bash_profile

export MAVEN_HOME=/Users/yjwfn/bin/apache-maven-3.6.3
export PATH=$PATH:$MAVEN_HOME/bin

Verify Installation

Use which mvn to confirm the Maven executable location, and mvn -v to display the Maven version and Java details.

which mvn
/Users/yjwfn/bin/apache-maven-3.6.3/bin/mvn

mvn -v
Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
Maven home: /Users/yjwfn/bin/apache-maven-3.6.3
Java version: 1.8.0_191, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk1.8.0_191.jdk/Contents/Home/jre
Default locale: zh_CN, platform encoding: UTF-8
OS name: "mac os x", version: "10.14.6", arch: "x86_64", family: "mac"

Running Maven

The basic Maven command format consists of options, goal(s), and phase(s): mvn [options] [<goal(s)>] [<phase(s)>] All available options can be listed with mvn -h.

liuweideMacBook-Pro:bin yjwfn$ mvn -h
usage: mvn [options] [<goal(s)>] [<phase(s)>]
Options:
  -am,--also-make ...

Maven Configuration

Maven can be configured in three places: MAVEN_OPTS environment variable for JVM options (e.g., -Xms256m -Xmx512m). settings.xml located either in $MAVEN_HOME/conf/settings.xml or USER_HOME/.m2/settings.xml, providing project‑wide settings.

The hidden .mvn directory at the project root, containing extensions.xml, maven.config, and jvm.config.

MAVEN_OPTS Usage

Set MAVEN_OPTS to pass JVM arguments to Maven. For example, adding -h prints Maven usage: export MAVEN_OPTS=-h # add -h option Running mvn without goals now displays the usage information, which actually comes from the Java command java -h.

settings.xml File

The settings.xml file can be placed in two locations. Its loading can be inspected with mvn --debug:

mvn --debug
[DEBUG] Reading global settings from /Users/yjwfn/bin/apache-maven-3.6.3/conf/settings.xml
[DEBUG] Reading user settings from /Users/yjwfn/.m2/settings.xml

.mvn Directory

The .mvn directory holds project‑level configuration files: extensions.xml – declares libraries to be added to the core classloader. maven.config – defines common command‑line options automatically applied to mvn. jvm.config – contains JVM parameters.

extensions.xml Example

<extensions xmlns="http://maven.apache.org/EXTENSIONS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/EXTENSIONS/1.0.0 http://maven.apache.org/xsd/core-extensions-1.0.0.xsd">
  <extension>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>23.0</version>
  </extension>
</extensions>

maven.config Example

Adding a default -v option: -v Now running mvn will automatically include -v and display the version.

liuweideMacBook-Pro:.mvn yjwfn$ mvn
Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
Maven home: /Users/yjwfn/bin/apache-maven-3.6.3
Java version: 1.8.0_191, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk1.8.0_191.jdk/Contents/Home/jre
Default locale: zh_CN, platform encoding: UTF-8
OS name: "mac os x", version: "10.14.6", arch: "x86_64", family: "mac"

jvm.config

This file simply lists JVM arguments to be used by Maven.

Maven Build Lifecycle

Maven defines three built‑in lifecycles: clean, default, and site. The default lifecycle consists of the following phases:

validate – ensure the project is correct and all necessary information is available.

compile – compile the source code.

test – run unit tests on the compiled code.

package – bundle the compiled code into a distributable format (e.g., JAR).

verify – perform checks on integration test results.

install – install the package into the local repository.

deploy – copy the final package to a remote repository for sharing.

These phases are executed sequentially when the default lifecycle is invoked.

Plugin Goals

Each build phase is implemented by plugins. A lifecycle consists of phases, and each phase can have multiple plugin goals bound to it. For example, executing mvn install runs the install phase and the associated install:install plugin goal.

Summary

Maven is a widely used build tool, and its concepts form a solid foundation for modern build systems such as Gradle. This guide covered only a portion of Maven’s capabilities; advanced topics like dependency management, plugin management, and multi‑module projects will be explored later.