Maven Build Lifecycle

Maven Build Lifecycle

Master Maven's build lifecycle including phases, goals, profiles, and build customization for efficient Java project builds.

Overview

Maven's build lifecycle is a well-defined sequence of phases that execute in order. Understanding the lifecycle is essential for effective build configuration and optimization.

Default Lifecycle Phases

Complete Phase Order

1.  validate      - Validate project structure
2.  initialize    - Initialize build state
3.  generate-sources
4.  process-sources
5.  generate-resources
6.  process-resources - Copy resources to output
7.  compile       - Compile source code
8.  process-classes
9.  generate-test-sources
10. process-test-sources
11. generate-test-resources
12. process-test-resources
13. test-compile  - Compile test sources
14. process-test-classes
15. test          - Run unit tests
16. prepare-package
17. package       - Create JAR/​WAR
18. pre-integration-test
19. integration-test - Run integration tests
20. post-integration-test
21. verify        - Run verification checks
22. install       - Install to local repo
23. deploy        - Deploy to remote repo

Common Phase Commands

# Compile only
mvn compile

# Compile and run tests
mvn test

# Create package
mvn package

# Install to local repository
mvn install

# Deploy to remote repository
mvn deploy

# Clean and build
mvn clean install

# Skip tests
mvn install -DskipTests

# Skip test compilation and execution
mvn install -Dmaven.test.skip=true

Clean Lifecycle

1. pre-clean
2. clean         - Delete target directory
3. post-clean

# Clean build artifacts
mvn clean

# Clean specific directory
mvn clean -DbuildDirectory=out

Site Lifecycle

1. pre-site
2. site          - Generate documentation
3. post-site
4. site-deploy   - Deploy documentation

# Generate site
mvn site

# Generate and deploy site
mvn site-deploy

Goals vs Phases

Executing Phases

# Execute phase (runs all previous phases)
mvn package

Executing Goals

# Execute specific goal
mvn compiler:compile
mvn surefire:test
mvn jar:jar

# Multiple goals
mvn dependency:tree compiler:compile

Phase-to-Goal Bindings

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</​groupId>
            <artifactId>maven-compiler-plugin</​artifactId>
            <version>3.12.1</​version>
            <executions>
                <execution>
                    <id>compile-sources</​id>
                    <phase>compile</​phase>
                    <goals>
                        <goal>compile</​goal>
                    </​goals>
                </​execution>
            </​executions>
        </​plugin>
    </​plugins>
</​build>

Build Profiles

Profile Definition

<profiles>
    <profile>
        <id>development</​id>
        <activation>
            <activeByDefault>true</​activeByDefault>
        </​activation>
        <properties>
            <env>dev</​env>
            <skip.integration.tests>true</​skip.integration.tests>
        </​properties>
    </​profile>

    <profile>
        <id>production</​id>
        <properties>
            <env>prod</​env>
            <skip.integration.tests>false</​skip.integration.tests>
        </​properties>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</​groupId>
                    <artifactId>maven-compiler-plugin</​artifactId>
                    <configuration>
                        <debug>false</​debug>
                        <optimize>true</​optimize>
                    </​configuration>
                </​plugin>
            </​plugins>
        </​build>
    </​profile>
</​profiles>

Profile Activation

# Activate by name
mvn install -Pproduction

# Multiple profiles
mvn install -Pproduction,ci

# Deactivate profile
mvn install -P!development

Activation Triggers

<profile>
    <id>jdk17</​id>
    <activation>
        <!-- Activate by JDK version -->
        <jdk>17</​jdk>
    </​activation>
</​profile>

<profile>
    <id>windows</​id>
    <activation>
        <!-- Activate by OS -->
        <os>
            <family>windows</​family>
        </​os>
    </​activation>
</​profile>

<profile>
    <id>ci</​id>
    <activation>
        <!-- Activate by environment variable -->
        <property>
            <name>env.CI</​name>
            <value>true</​value>
        </​property>
    </​activation>
</​profile>

<profile>
    <id>with-config</​id>
    <activation>
        <!-- Activate by file existence -->
        <file>
            <exists>src/​main/​config/​app.properties</​exists>
        </​file>
    </​activation>
</​profile>

Resource Filtering

Enable Filtering

<build>
    <resources>
        <resource>
            <directory>src/​main/​resources</​directory>
            <filtering>true</​filtering>
            <includes>
                <include>**/​*.properties</​include>
                <include>**/​*.xml</​include>
            </​includes>
        </​resource>
        <resource>
            <directory>src/​main/​resources</​directory>
            <filtering>false</​filtering>
            <excludes>
                <exclude>**/​*.properties</​exclude>
                <exclude>**/​*.xml</​exclude>
            </​excludes>
        </​resource>
    </​resources>
</​build>

Property Substitution

# application.properties
app.name=${project.name}
app.version=${project.version}
app.environment=${env}
build.timestamp=${maven.build.timestamp}

Build Customization

Source and Target Configuration

<properties>
    <maven.compiler.source>17</​maven.compiler.source>
    <maven.compiler.target>17</​maven.compiler.target>
    <maven.compiler.release>17</​maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</​project.build.sourceEncoding>
</​properties>

Custom Source Directories

<build>
    <sourceDirectory>src/​main/​java</​sourceDirectory>
    <testSourceDirectory>src/​test/​java</​testSourceDirectory>
    <resources>
        <resource>
            <directory>src/​main/​resources</​directory>
        </​resource>
    </​resources>
    <testResources>
        <testResource>
            <directory>src/​test/​resources</​directory>
        </​testResource>
    </​testResources>
</​build>

Final Name and Output

<build>
    <finalName>${project.artifactId}-${project.version}</​finalName>
    <directory>target</​directory>
    <outputDirectory>target/​classes</​outputDirectory>
    <testOutputDirectory>target/​test-classes</​testOutputDirectory>
</​build>

Multi-Module Builds

Reactor Options

# Build all modules
mvn install

# Build specific module and dependencies
mvn install -pl module-name -am

# Build dependents of a module
mvn install -pl module-name -amd

# Resume from specific module
mvn install -rf :module-name

# Build in parallel
mvn install -T 4
mvn install -T 1C  # 1 thread per CPU core

Module Order Control

<!-- parent/​pom.xml -->
<modules>
    <module>common</​module>
    <module>api</​module>
    <module>service</​module>
    <module>web</​module>
</​modules>

Test Configuration

Surefire Plugin (Unit Tests)

<plugin>
    <groupId>org.apache.maven.plugins</​groupId>
    <artifactId>maven-surefire-plugin</​artifactId>
    <version>3.2.3</​version>
    <configuration>
        <includes>
            <include>**/​*Test.java</​include>
            <include>**/​*Tests.java</​include>
        </​includes>
        <excludes>
            <exclude>**/​*IntegrationTest.java</​exclude>
        </​excludes>
        <parallel>methods</​parallel>
        <threadCount>4</​threadCount>
        <forkCount>1</​forkCount>
        <reuseForks>true</​reuseForks>
    </​configuration>
</​plugin>

Failsafe Plugin (Integration Tests)

<plugin>
    <groupId>org.apache.maven.plugins</​groupId>
    <artifactId>maven-failsafe-plugin</​artifactId>
    <version>3.2.3</​version>
    <executions>
        <execution>
            <goals>
                <goal>integration-test</​goal>
                <goal>verify</​goal>
            </​goals>
        </​execution>
    </​executions>
    <configuration>
        <includes>
            <include>**/​*IT.java</​include>
            <include>**/​*IntegrationTest.java</​include>
        </​includes>
    </​configuration>
</​plugin>

Build Optimization

Incremental Builds

# Skip unchanged modules
mvn install -amd

# Use build cache (requires Maven Daemon)
mvnd install

Parallel Builds

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</​groupId>
            <artifactId>maven-compiler-plugin</​artifactId>
            <configuration>
                <fork>true</​fork>
                <compilerArgs>
                    <arg>-J-Xmx512m</​arg>
                </​compilerArgs>
            </​configuration>
        </​plugin>
    </​plugins>
</​build>

Build Cache

# Enable build cache (Maven 4+)
mvn install -Dmaven.build.cache.enabled=true

Debugging Builds

Verbose Output

# Debug mode
mvn install -X

# Error stacktrace
mvn install -e

# Quiet mode
mvn install -q

Effective POM

# View resolved POM
mvn help:effective-pom

# View effective settings
mvn help:effective-settings

# Active profiles
mvn help:active-profiles

Dependency Analysis

# Check plugin versions
mvn versions:display-plugin-updates

# Check dependency versions
mvn versions:display-dependency-updates

Best Practices

1. Use Clean Builds - Run mvn clean before releases
2. Consistent Versions - Lock plugin versions
3. Profile Isolation - Keep profiles focused
4. Fail Fast - Use -ff in CI for quick feedback
5. Parallel Builds - Use -T for multi-module projects
6. Skip Wisely - Know the difference between skip options
7. Resource Filtering - Enable only where needed
8. Test Separation - Unit tests in Surefire, integration in Failsafe
9. Reproducible Builds - Pin all plugin versions
10. Document Profiles - Comment profile purposes

Common Pitfalls

1. Skipping Tests - Don't skip tests in CI
2. SNAPSHOT in Release - Remove snapshots before release
3. Missing Clean - Stale files causing issues
4. Profile Conflicts - Overlapping profile configurations
5. Resource Filtering - Accidentally filtering binaries
6. Phase Confusion - Running wrong phase
7. Memory Issues - Insufficient heap for large builds
8. Reactor Order - Module dependency issues

CI/​CD Integration

GitHub Actions

- name: Build with Maven
  run: mvn -B clean verify -Pci

- name: Release
  run: mvn -B deploy -Prelease -DskipTests

Jenkins Pipeline

stage('Build') {
    steps {
        sh 'mvn -B clean package -DskipTests'
    }
}
stage('Test') {
    steps {
        sh 'mvn -B test'
    }
}
stage('Integration Test') {
    steps {
        sh 'mvn -B verify -DskipUnitTests'
    }
}

When to Use This Skill

• Setting up new Maven projects
• Customizing build phases
• Creating build profiles for environments
• Configuring test execution
• Optimizing build performance
• Debugging build failures
• Setting up CI/​CD pipelines
• Multi-module project configuration