Copyright

Maven: The Complete Reference

Tim O'Brien

Sonatype, Inc.

John Casey

Sonatype, Inc.

Brian Fox

Sonatype, Inc.

Jason Van Zyl

Sonatype, Inc.

Manfred Moser

Eric Redmond

Larry Shatzer

Copyright © 2010 Sonatype. All Rights Reserved.

Abstract

Maven: The Complete Reference is a book about Apache Maven.

Copyright
Foreword: 0.6
1. Changes in Edition 0.6
Preface
1. How to Use this Book
2. Your Feedback
3. Font Conventions
4. Maven Writing Conventions
5. Acknowledgements
1. Introducing Apache Maven
1.1. Maven... What is it?
1.2. Convention Over Configuration
1.3. A Common Interface
1.4. Universal Reuse through Maven Plugins
1.5. Conceptual Model of a "Project"
1.6. Is Maven an alternative to XYZ?
1.. Comparing Maven with Ant
2. Installing Maven
2.1. Verify your Java Installation
2.2. Downloading Maven
2.3. Installing Maven
2.3.1. Installing Maven on Mac OSX
2.3.1.1. Installing Maven on OSX using MacPorts
2.3.2. Installing Maven on Microsoft Windows
2.3.3. Installing Maven on Linux
2.3.4. Installing Maven on FreeBSD or OpenBSD
2.4. Testing a Maven Installation
2.5. Maven Installation Details
2.5.1. User-specific Configuration and Repository
2.5.2. Upgrading a Maven Installation
2.5.3. Upgrading from Maven 1.x to Maven 2.x
2.6. Uninstalling Maven
2.7. Getting Help with Maven
2.8. About the Apache Software License
3. The Project Object Model
3.1. Introduction
3.2. The POM
3.2.. The Super POM
3.2.2. The Simplest POM
3.2.3. The Effective POM
3.2.4. Real POMs
3.3. POM Syntax
3.3.1. Project Versions
3.3.1.1. Version Build Numbers
3.3.1.2. SNAPSHOT Versions
3.3.2. Property References
3.4. Project Dependencies
3.4.1. Dependency Scope
3.4.2. Optional Dependencies
3.4.3. Dependency Version Ranges
3.4.4. Transitive Dependencies
3.4.4.1. Transitive Dependencies and Scope
3.4.5. Conflict Resolution
3.4.6. Dependency Management
3.5. Project Relationships
3.5.1. More on Coordinates
3.5.2. Project Inheritance
3.6. POM Best Practices
3.6.1. Grouping Dependencies
3.6.2. Multi-module vs. Inheritance
3.6.2.1. Simple Project
3.6.2.2. Multi-module Enterprise Project
4. The Build Lifecycle
4.1. Introduction
4.1.1. Clean Lifecycle (clean)
4.1.2. Default Lifecycle (default)
4.1.3. Site Lifecycle (site)
4.2. Package-specific Lifecycles
4.2.1. JAR
4.2.2. POM
4.2.3. Maven Plugin
4.2.4. EJB
4.2.5. WAR
4.2.6. EAR
4.2.7. Other Packaging Types
4.3. Common Lifecycle Goals
4.3.1. Process Resources
4.3.2. Compile
4.3.3. Process Test Resources
4.3.4. Test Compile
4.3.5. Test
4.3.6. Install
4.3.7. Deploy
5. Build Profiles
5.1. What Are They For?
5.1.1. What is Build Portability
5.1.1.1. Non-Portable Builds
5.1.1.2. Environment Portability
5.1.1.3. Organizational (In-House) Portability
5.1.1.4. Wide (Universal) Portability
5.1.2. Selecting an Appropriate Level of Portability
5.2. Portability through Maven Profiles
5.2.1. Overriding a Project Object Model
5.3. Profile Activation
5.3.1. Activation Configuration
5.3.2. Activation by the Absence of a Property
5.4. Listing Active Profiles
5.5. Tips and Tricks
5.5.1. Common Environments
5.5.2. Protecting Secrets
5.5.3. Platform Classifiers
5.6. Summary
6. Running Maven
6.1. Maven Command Line Options
6.1.1. Defining Properties
6.1.2. Getting Help
6.1.3. Using Build Profiles
6.1.4. Displaying Version Information
6.1.5. Running in Offline Mode
6.1.6. Using a Custom POM or Custom Settings File
6.1.7. Encrypting Passwords
6.1.8. Dealing with Failure
6.1.9. Controlling Maven's Verbosity
6.1.10. Running Maven in Batch Mode
6.1.11. Downloading and Verifying Dependencies
6.1.12. Controlling Plugin Updates
6.1.13. Non-recursive Builds
6.2. Using Advanced Reactor Options
6.2.1. Advanced Reactor Options Example Project
6.2.2. Resuming Builds
6.2.3. Specifying a Subset of Projects
6.2.4. Making a Subset of Projects
6.2.5. Making Project Dependents
6.2.6. Resuming a "make" build
6.3. Using the Maven Help Plugin
6.3.1. Describing a Maven Plugin
7. Maven Configuration
7.1. Configuring Maven Plugins
7.1.1. Plugin Configuration Parameters
7.1.2. Adding Plugin Dependencies
7.1.3. Setting Global Plugin Parameters
7.1.4. Setting Execution Specific Parameters
7.1.5. Setting Default Command Line Execution Parameters
7.1.6. Setting Parameters for Goals Bound to Default Lifecycle
8. Maven Assemblies
8.1. Introduction
8.2. Assembly Basics
8.2.1. Predefined Assembly Descriptors
8.2.2. Building an Assembly
8.2.3. Assemblies as Dependencies
8.2.4. Assembling Assemblies via Assembly Dependencies
8.3. Overview of the Assembly Descriptor
8.4. The Assembly Descriptor
8.4.1. Property References in Assembly Descriptors
8.4.2. Required Assembly Information
8.5. Controlling the Contents of an Assembly
8.5.1. Files Section
8.5.2. FileSets Section
8.5.3. Default Exclusion Patterns for fileSets
8.5.4. dependencySets Section
8.5.4.1. Customizing Dependency Output Location
8.5.4.2. Interpolation of Properties in Dependency Output Location
8.5.4.3. Including and Excluding Dependencies by Scope
8.5.4.4. Fine Tuning: Dependency Includes and Excludes
8.5.4.5. Transitive Dependencies, Project Attachments, and Project Artifacts
8.5.4.6. Advanced Unpacking Options
8.5.4.7. Summarizing Dependency Sets
8.5.5. moduleSets Sections
8.5.5.1. Module Selection
8.5.5.2. Sources Section
8.5.5.3. Interpolation of outputDirectoryMapping in moduleSets
8.5.5.4. Binaries section
8.5.5.5. moduleSets, Parent POMs and the binaries Section
8.5.6. Repositories Section
8.5.7. Managing the Assembly’s Root Directory
8.5.8. componentDescriptors and containerDescriptorHandlers
8.6. Best Practices
8.6.1. Standard, Reusable Assembly Descriptors
8.6.2. Distribution (Aggregating) Assemblies
8.7. Summary
9. Properties and Resource Filtering
9.1. Introduction
9.2. Maven Properties
9.2.1. Maven Project Properties
9.2.2. Maven Settings Properties
9.2.3. Environment Variable Properties
9.2.4. Java System Properties
9.2.5. User-defined Properties
9.3. Resource Filtering
10. Site Generation
10.1. Introduction
10.2. Building a Project Site with Maven
10.3. Customizing the Site Descriptor
10.3.1. Customizing the Header Graphics
10.3.2. Customizing the Navigation Menu
10.4. Site Directory Structure
10.5. Writing Project Documentation
10.5.1. APT Example
10.5.2. FML Example
10.6. Deploying Your Project Website
10.6.1. Configuring Server Authentication
10.6.2. Configuring File and Directory Modes
10.7. Customizing Site Appearance
10.7.1. Customizing the Site CSS
10.7.2. Create a Custom Site Template
10.7.3. Reusable Website Skins
10.7.4. Creating a Custom Theme CSS
10.8. Tips and Tricks
10.8.1. Inject XHTML into HEAD
10.8.2. Add Links under Your Site Logo
10.8.3. Add Breadcrumbs to Your Site
10.8.4. Add the Project Version
10.8.5. Modify the Publication Date Format and Location
10.8.6. Using Doxia Macros
11. Writing Plugins
11.1. Introduction
11.2. Programming Maven
11.2.1. What is Inversion of Control?
11.2.2. Introduction to Plexus
11.2.3. Why Plexus?
11.2.4. What is a Plugin?
11.3. Plugin Descriptor
11.3.1. Top-level Plugin Descriptor Elements
11.3.2. Mojo Configuration
11.3.3. Plugin Dependencies
11.4. Writing a Custom Plugin
11.4.1. Creating a Plugin Project
11.4.2. A Simple Java Mojo
11.4.3. Configuring a Plugin Prefix
11.4.4. Logging from a Plugin
11.4.5. Mojo Class Annotations
11.4.6. When a Mojo Fails
11.5. Mojo Parameters
11.5.1. Supplying Values for Mojo Parameters
11.5.2. Multi-valued Mojo Parameters
11.5.3. Depending on Plexus Components
11.5.4. Mojo Parameter Annotations
11.6. Plugins and the Maven Lifecycle
11.6.1. Executing a Parallel Lifecycle
11.6.2. Creating a Custom Lifecycle
11.6.3. Overriding the Default Lifecycle
12. Using Maven Archetypes
12.1. Introduction to Maven Archetypes
12.2. Using Archetypes
12.2.1. Using an Archetype from the Command Line
12.2.2. Using the Interactive generate Goal
12.2.3. Using an Archetype from m2eclipse
12.3. Available Archetypes
12.3.1. Common Maven Archetypes
12.3.1.1. maven-archetype-quickstart
12.3.1.2. maven-archetype-webapp
12.3.1.3. maven-archetype-mojo
12.3.2. Notable Third-Party Archetypes
12.3.2.1. AppFuse
12.3.2.2. Confluence and JIRA plugins
12.3.2.3. Wicket
12.4. Publishing Archetypes
13. Developing with Flexmojos
13.1. Introduction
13.2. Configuring Build Environment for Flexmojos
13.2.1. Referencing a Repository with the Flex Framework
13.2.1.1. Referencing Sonatype's Flexmojos Repository in a POM
13.2.1.2. Proxying Sonatype's Flexmojos Repository with Nexus
13.2.2. Configuring Environment to Support Flex Unit Tests
13.2.3. Adding FlexMojos to Your Maven Settings' Plugin Groups
13.3. Creating a Flex Mojos Project from an Archetype
13.3.1. Creating a Flex Library
13.3.2. Creating a Flex Application
13.3.3. Creating a Multi-module Project: Web Application with a Flex Dependency
13.4. The FlexMojos Lifecycle
13.4.1. The SWC Lifecycle
13.4.2. The SWF Lifecycle
13.5. FlexMojos Plugin Goals
13.5.1. Generating Actionscript Documentation
13.5.2. Compiling Flex Source
13.5.3. Generating Flex Builder Project Files
13.6. FlexMojos Plugin Reports
13.6.1. Generating Actionscript Documentation Report
13.7. Developing and Customizing Flexmojos
13.7.1. Get the Flexmojos Source Code
14. Android Application Development with Maven
14.1. Introduction
14.2. Configuring Build Environment for Android Development
14.2.1. Installing the Android SDK
14.2.2. Android artifact install into Maven repository
14.2.2.1. Installation to local repository
14.2.2.2. Installation to remote repository
14.2.2.3. Installation of a subset of all platforms
14.2.3. Configuring Maven for usage of the Maven Android Plugin
14.3. Android Application Development with the Maven Android Plugin
14.3.1. HelloFlashlight Example
14.3.2. Testing Android Application Code
14.3.2.1. Unit tests
14.3.2.2. Instrumentation tests
14.3.3. Using Add Ons like the Google Maps Extension
14.3.4. Multi Module Maven Android Projects
14.3.5. Using external dependencies
14.4. Maven Android Plugin Details
14.4.1. Maven Android Plugin Lifecycle
14.4.2. Maven Android Plugin Goals
A. Appendix: Settings Details
A.1. Quick Overview
A.2. Settings Details
A.2.1. Simple Values
A.2.2. Servers
A.2.3. Mirrors
A.2.4. Proxies
A.2.5. Profiles
A.2.6. Activation
A.2.7. Properties
A.2.8. Repositories
A.2.9. Plugin Repositories
A.2.10. Active Profiles
A.2.11. Encrypting Passwords in Maven Settings
B. Appendix: Sun Specification Alternatives
C. Creative Commons License
C.1. Creative Commons BY-NC-ND 3.0 US License
D. Book Revision History
D.1. Changes in Edition 0.5
D.2. Changes in Edition 0.4
D.3. Changes in Edition 0.2.1
D.4. Changes in Edition 0.2
D.5. Changes in Edition 0.1
Index

List of Figures

3.1. The Project Object Model
3.2. The Super POM is always the base Parent
3.3. Project Inheritance for a-parent and project-a
3.4. maven-book Multi-module vs. Inheritance
3.5. Enterprise Multi-module vs. Inheritance
6.1. Directory Structure of Sample Multi-module Project
6.2. Dependencies within Sample Multi-module Project
10.1. Simple Generated Maven Site
10.2. Customized Sample Project Web Site
13.1. Adding a Proxy Repository to Sonatype Nexus
13.2. Configuring the Sonatype Flexmojos Proxy Repository
13.3. Adding the Sonatype Flexmojos Proxy to the Public Repositories Group
13.4. Flexmojo Library Archetype File Structure
13.5. Directory Structure for Flex Application Archetype
13.6. Directory Structure for Flex Multimodule Archetype
13.7. The FlexMojos SWC Lifecycle
13.8. The FlexMojos SWF Lifecycle
13.9. Actionscript Documentation Generated by the FlexMojos Plugin
13.10. Actionscript Documentation Report on Maven Site
13.11. Flexmojos Subversion Repository
A.1. Storing Unencrypted Passwords in Maven Settings
A.2. Storing Encrypted Passwords in Maven Settings

List of Examples

1.1. A Simple Ant build.xml file
1.2. A Sample Maven pom.xml
3.1. The Super POM
3.2. The Simplest POM
3.3. Project Dependencies
3.4. Declaring Optional Dependencies
3.5. Specifying a Dependency Range: JUnit 3.8 - JUnit 4.0
3.6. Specifying a Dependency Range: JUnit <= 3.8.1
3.7. Excluding a Transitive Dependency
3.8. Excluding and Replacing a Transitive Dependency
3.9. Defining Dependency Versions in a Top-level POM
3.10. Project Inheritance
3.11. Consolidating Dependencies in a Single POM Project
3.12. Declaring a Dependency on a POM
4.1. Triggering a Goal on pre-clean
4.2. Customizing Behavior of the Clean Plugin
4.3. Custom Packaging Type for Adobe Flex (SWF)
4.4. Using Properties in Project Resources
4.5. default.properties in src/main/filters
4.6. Filter Resources (Replacing Properties)
4.7. Configuring Additional Resource Directories
4.8. Filtering Script Resources
4.9. Setting the Source and Target Versions for the Compiler Plugin
4.10. Overriding the Default Source Directory
4.11. Overriding the Location of Test Source and Output
4.12. Configuring Surefire to Ignore Test Failures
5.1. Using a Maven Profile to Override Production Compiler Settings
5.2. Elements Allowed in a Profile
5.3. Dynamic Inclusion of Submodules Using Profile Activation
5.4. Profile Activation Parameters: JDK Version, OS Parameters, and Properties
5.5. Activating Profiles in the Absence of a Property
5.6. Project Profile Activated by setting environment.type to 'dev'
5.7. Storing Secrets in a User-specific Settings Profile
5.8. Qualifying Artifacts with Platform Activated Project Profiles
5.9. Qualifying Artifacts with Platform Activated Project Profiles and Variable Substitution
5.10. Depending on a Qualified Artifact
6.1. Maven Version Information
6.2. Order of Project Builds in Maven Reactor
7.1. Adding Dependencies to a Plugin
Configuring a Maven Plugin
7.3. Setting Configuration Parameters in an Execution
Configuring Plugin Parameters for Command Line Execution
Setting a Parameter for a Default Goal Execution
7.6. Setting Two Default Goal Plugin Configuration Parameters
8.1. Assembly Descriptor for Executable JAR
8.2. Configuring the project assembly in top-level POM
8.3. Activating the Assembly Plugin Configuration in Child Projects
8.4. POM for the Assembly Bundling Project
8.5. Required Assembly Descriptor Elements
8.6. Including a JAR file in an Assembly using files
8.7. Including Files with fileSet
8.8. Definition of Default Exclusion Patterns from Plexus Utils
8.9. Defining Dependency Sets Using Scope
8.10. Using Dependency Excludes and Includes in dependencySets
8.11. Excluding Files from a Dependency Unpack
8.12. Includes and Excluding Modules with a moduleSet
8.13. Including JavaDoc from Modules in an Assembly
8.14. Including Module Artifacts and Dependencies in an Assembly
9.1. User-defined Properties in a POM
9.2. User-defined Properties in a Profile in a POM
9.3. Referencing Maven Properties from a Resource
9.4. Defining Variables and Activating Resource Filtering
10.1. An Initial Site Descriptor
10.2. Adding a Banner Left and Banner Right to Site Descriptor
10.3. Creating Menu Items in a Site Descriptor
10.4. Adding a Link to the Site Menu
10.5. APT Document
10.6. FAQ Markup Language Document
10.7. Configuring Site Deployment
10.8. Storing Server Authentication in User-specific Settings
10.9. Configuring File and Directory Modes on Remote Servers
10.10. Customizing the Page Template in a Project's POM
10.11. Adding a Menu Item to a Site Descriptor
10.12. Configuring a Custom Site Skin in Site Descriptor
10.13. Injecting HTML into the HEAD element
10.14. Adding Links Under Your Site Logo
10.15. Configuring the Site's Breadcrumbs
10.16. Positioning the Version Information
10.17. Positioning the Publish Date
10.18. Configuring the Publish Date Format
10.19. Output of the Snippet Macro in XHTML
11.1. Plugin Descriptor
11.2. A Plugin Project's POM
11.3. A Simple EchoMojo
11.4. Maven Metadata for the Maven Plugin Group
11.5. Customizing the Plugin Groups in Maven Settings
11.6. Configuring a Plugin Prefix
11.7. A Plugin with Multi-valued Parameters
11.8. Depending on a Plexus Component
11.9. Define a Custom Lifecycle in lifecycles.xml
11.10. Forking a Custom Lifecycle from a Mojo
11.11. Overriding the Default Lifecycle
11.12. Configuring a Plugin as an Extension
12.1. Archetype Catalog for the Apache Cocoon Project
13.1. Adding a Reference to Sonatype's FlexMojos Repository in a POM
13.2. Settings XML for Local Nexus Instance
13.3. Adding Sonatype Plugins to Maven Settings
13.4. Project Object Model for Flex Library Archetype
13.5. Flex Library Archetype's Sample App Class
13.6. Unit Test for Library Archetype's App Class
13.7. POM for Flex Application Archetype
13.8. Sample Application Main.mxml
13.9. Unit Test for Main.mxml
13.10. Top-level POM Created by Modular Web Application Archetype
13.11. swc Module POM
13.12. swf module POM
13.13. war module POM
13.14. Setting Plugin Extensions to True for Custom Flex Lifecycle
13.15. Customizing the Compiler Plugin
13.16. Configuring the Actionscript Documentation Report
13.17. Configuring the asdoc-report
14.1. Snippet for settings.xml for the repository server access credentials
14.2. Snippet for settings.xml to enable short plugin name usage
14.3. The HelloFlashlight pom.xml file
14.4. Adding the test folder to the build configuration
14.5. The dependency to the Google Maps API
A.1. Overview of top-level elements in settings.xml
A.2. Simple top-level elements in settings.xml
A.3. Server configuration in settings.xml
A.4. Mirror configuration in settings.xml
A.5. Proxy configuration in settings.xml
A.6. Defining Activation Parameters in settings.xml
A.7. Setting the ${user.install} property in settings.xml
A.8. Repository Configuration in settings.xml
A.9. Plugin Repositories in settings.xml
A.10. Setting active profiles in settings.xml
A.11. settings-security.xml with Master Password
A.12. Storing an Encrypted Password in Maven Settings (~/.m2/settings.xml)
A.13. Configuring Relocation of the Master Password
B.1. Adding JTA 1.0.1B to a Maven Project
     Next
  Sponsored by Sonatype  Copyright