Maven: The Complete Reference

Edition 0.7

Maven 2.2 Maven 3.0

Maven: The Complete Reference

The Complete Reference Tim O’Brien Jason van Zyl Brian Fox John Casey Juven Xu Thomas Locher Manfred Moser Contributing Authors: Dan Fabulich Eric Redmond Bruce Snyder Larry Shatzer

A Sonatype Open Book Mountain View, CA

Copyright © 2010 Sonatype, Inc. This work is licensed under a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 United States license. For more information about this license, see http://creativecommons.org/licenses/by-nc-nd/3.0/us/. You are free to share, copy, distribute, display, and perform the work under the following conditions: • You must attribute the work to Sonatype, Inc. with a link to http://www.sonatype.com. • You may not use this work for commercial purposes. • You may not alter, transform, or build upon this work. Nexus™, Nexus Professional™, and all Nexus-related logos are trademarks or registered trademarks of Sonatype, Inc., in the United States and other countries. Java™ and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries. IBM® and WebSphere® are trademarks or registered trademarks of International Business Machines, Inc., in the United States and other countries. Eclipse™ is a trademark of the Eclipse Foundation, Inc., in the United States and other countries. Apache and the Apache feather logo are trademarks of The Apache Software Foundation. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and Sonatype, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. Published by: Sonatype, Inc. 800 W. El Camino Real Suite 400 Mountain View, CA 94040.

For online information and ordering of this and other Sonatype books, please visit www.sonatype.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact: [email protected]

ISBN 978-0-9842433-4-1

Editor: Tim O’Brien

Nexus Professional Nexus Professional 1.6 is now available with features to support enterprise software development. Stage software releases and maintain strict control over proxy repositories. Download your free trial today. "We have adopted Maven for all our software development projects and have started using Nexus to better support our development processes. The support for promotion and procurement workflows in Nexus Professional now expands Nexus with a robust set of additional features which make it easier for us to maintain consistency between our development, testing and production environments." - Chris Maki, Principal Software Engineer, Overstock.com "At Intuit, we recognize that as builds grow and the teams who create them change over time, swift, accurate repository management becomes critical. Nexus provides a comprehensive, easy-to-use open source solution that lets teams and developers track, search, organize and access build components." - Kaizer Sogiawala, Software Configuration Management Engineer, Intuit.

http://www.sonatype.com/products/nexus

Maven Training by Sonatype With Sonatype training, you will learn Maven fundamentals and best practices directly from Maven and Nexus experts. If your team is using Nexus, this class is the easiest way to make sure that everyone starts from the same foundation.

MVN-101 Maven Mechanics

An online instructor-led course of two half-day sessions, ideal for programmers who work with Maven projects and need to understand how to work with an existing Maven build. This class is also appropriate for experienced Maven users who are interested in becoming more familiar with Maven fundamentals.

MVN-201 Development Infrastructure Design

An online instructor-led course of two half-day sessions, ideal for Development Infrastructure Engineers who are responsible for maintaining enterprise development infrastructure. This class includes content on advanced repository management using Nexus and continuous integration using Hudson.

http://www.sonatype.com/training

Copyright ........................................................................................................................................................... xv Foreword: 0.7 .................................................................................................................................................... xvii 1. Changes in Edition 0.7 ............................................................................................................................ xvii Preface .............................................................................................................................................................. xix 1. How to Use this Book .............................................................................................................................. xix 2. Your Feedback ........................................................................................................................................ xix 3. Font Conventions .................................................................................................................................... xix 4. Maven Writing Conventions ....................................................................................................................... xx 5. Acknowledgements ................................................................................................................................... xx 1. Introducing Apache Maven .................................................................................................................................. 1 1.1. Maven... What is it? ................................................................................................................................. 1 1.2. Convention Over Configuration ................................................................................................................. 1 1.3. A Common Interface ................................................................................................................................ 2 1.4. Universal Reuse through Maven Plugins ...................................................................................................... 2 1.5. Conceptual Model of a "Project" ................................................................................................................ 3 1.6. Is Maven an alternative to XYZ? ............................................................................................................... 3 1.7. Comparing Maven with Ant ...................................................................................................................... 4 2. Installing Maven ................................................................................................................................................ 7 2.1. Verify your Java Installation ...................................................................................................................... 7 2.2. Downloading Maven ................................................................................................................................ 7 2.2.1. Downloading Maven 2 ................................................................................................................... 7 2.2.2. Downloading Maven 3 ................................................................................................................... 8 2.3. Installing Maven ..................................................................................................................................... 8 2.3.1. Installing Maven on Mac OSX ........................................................................................................ 8 2.3.2. Installing Maven on Microsoft Windows ........................................................................................... 9 2.3.3. Installing Maven on Linux .............................................................................................................. 9 2.3.4. Installing Maven on FreeBSD or OpenBSD ....................................................................................... 9 2.4. Testing a Maven Installation ...................................................................................................................... 9 2.5. Maven Installation Details ....................................................................................................................... 10 2.5.1. User-specific Configuration and Repository ...................................................................................... 10 2.5.2. Upgrading a Maven Installation ..................................................................................................... 11 2.5.3. Upgrading from Maven 1.x to Maven 2.x ........................................................................................ 11 2.6. Uninstalling Maven ................................................................................................................................ 11 2.7. Getting Help with Maven ........................................................................................................................ 12 2.8. About the Apache Software License .......................................................................................................... 12 3. The Project Object Model .................................................................................................................................. 15 3.1. Introduction .......................................................................................................................................... 15 3.2. The POM ............................................................................................................................................. 15 3.2.. The Super POM ........................................................................................................................... 16 3.2.2. The Simplest POM ...................................................................................................................... 19 3.2.3. The Effective POM ..................................................................................................................... 20 3.2.4. Real POMs ................................................................................................................................. 20 3.3. POM Syntax ......................................................................................................................................... 20 3.3.1. Project Versions .......................................................................................................................... 20 3.3.2. Property References ..................................................................................................................... 21 3.4. Project Dependencies .............................................................................................................................. 22 3.4.1. Dependency Scope ...................................................................................................................... 23 3.4.2. Optional Dependencies ................................................................................................................. 24 3.4.3. Dependency Version Ranges ......................................................................................................... 25 3.4.4. Transitive Dependencies ............................................................................................................... 26 3.4.5. Conflict Resolution ...................................................................................................................... 26 3.4.6. Dependency Management ............................................................................................................. 28 3.5. Project Relationships .............................................................................................................................. 29

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 ......................................................................................................... 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.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 ....................................................................................................

iv

29 30 31 31 33 37 37 37 39 40 41 41 41 42 42 42 43 43 44 44 46 47 47 48 48 49 51 51 51 52 52 54 54 55 56 57 57 57 58 59 61 63 63 63 63 64 64 65 65 65 65 66 66

6.1.11. Downloading and Verifying Dependencies ..................................................................................... 66 6.1.12. Controlling Plugin Updates .......................................................................................................... 67 6.1.13. Non-recursive Builds .................................................................................................................. 67 6.2. Using Advanced Reactor Options ............................................................................................................. 67 6.2.1. Advanced Reactor Options Example Project ..................................................................................... 67 6.2.2. Resuming Builds ......................................................................................................................... 69 6.2.3. Specifying a Subset of Projects ...................................................................................................... 69 6.2.4. Making a Subset of Projects .......................................................................................................... 69 6.2.5. Making Project Dependents ........................................................................................................... 70 6.2.6. Resuming a "make" build ............................................................................................................. 70 6.3. Using the Maven Help Plugin .................................................................................................................. 70 6.3.1. Describing a Maven Plugin ........................................................................................................... 71 7. Maven Configuration ........................................................................................................................................ 73 7.1. Configuring Maven Plugins ..................................................................................................................... 73 7.1.1. Plugin Configuration Parameters .................................................................................................... 73 7.1.2. Adding Plugin Dependencies ......................................................................................................... 75 7.1.3. Setting Global Plugin Parameters ................................................................................................... 76 7.1.4. Setting Execution Specific Parameters ............................................................................................. 76 7.1.5. Setting Default Command Line Execution Parameters ........................................................................ 77 7.1.6. Setting Parameters for Goals Bound to Default Lifecycle .................................................................... 77 8. Maven Assemblies ............................................................................................................................................ 79 8.1. Introduction .......................................................................................................................................... 79 8.2. Assembly Basics .................................................................................................................................... 79 8.2.1. Predefined Assembly Descriptors ................................................................................................... 80 8.2.2. Building an Assembly .................................................................................................................. 80 8.2.3. Assemblies as Dependencies ......................................................................................................... 82 8.2.4. Assembling Assemblies via Assembly Dependencies ......................................................................... 82 8.3. Overview of the Assembly Descriptor ....................................................................................................... 85 8.4. The Assembly Descriptor ........................................................................................................................ 86 8.4.1. Property References in Assembly Descriptors ................................................................................... 86 8.4.2. Required Assembly Information ..................................................................................................... 86 8.5. Controlling the Contents of an Assembly ................................................................................................... 87 8.5.1. Files Section ............................................................................................................................ 87 8.5.2. FileSets Section ....................................................................................................................... 88 8.5.3. Default Exclusion Patterns for fileSets ........................................................................................ 89 8.5.4. dependencySets Section ............................................................................................................ 90 8.5.5. moduleSets Sections .................................................................................................................. 97 8.5.6. Repositories Section ................................................................................................................... 101 8.5.7. Managing the Assembly’s Root Directory ...................................................................................... 101 8.5.8. componentDescriptors and containerDescriptorHandlers .................................................... 102 8.6. Best Practices ...................................................................................................................................... 102 8.6.1. Standard, Reusable Assembly Descriptors ...................................................................................... 103 8.6.2. Distribution (Aggregating) Assemblies .......................................................................................... 105 8.7. Summary ............................................................................................................................................ 108 9. Properties and Resource Filtering ...................................................................................................................... 109 9.1. Introduction ......................................................................................................................................... 109 9.2. Maven Properties ................................................................................................................................. 109 9.2.1. Maven Project Properties ............................................................................................................ 109 9.2.2. Maven Settings Properties ........................................................................................................... 111 9.2.3. Environment Variable Properties .................................................................................................. 111 9.2.4. Java System Properties ............................................................................................................... 111 9.2.5. User-defined Properties ............................................................................................................... 112 9.3. Resource Filtering ................................................................................................................................ 113

v

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 ...............................................................................................................................

vi

117 117 117 118 119 120 121 121 122 122 123 123 124 124 124 125 128 129 130 130 130 131 131 132 132 135 135 135 135 136 136 137 137 138 139 141 141 141 142 143 145 145 147 147 147 149 150 150 151 151 152 153 155

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.2. Notable Third-Party Archetypes .................................................................................................. 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.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.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.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 ....................................................................................................................................

155 155 155 156 157 157 158 158 160 163 163 163 163 167 168 168 168 172 175 180 181 182 182 183 184 184 184 185 186 186 187 187 187 187 187 188 189 189 190 191 191 191 192 192 192 195 195 195 195 196 197 197 198

vii

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.6 ......................................................................................................................... D.2. Changes in Edition 0.5 ......................................................................................................................... D.3. Changes in Edition 0.4 ......................................................................................................................... D.4. Changes in Edition 0.2.1 ....................................................................................................................... D.5. Changes in Edition 0.2 ......................................................................................................................... D.6. Changes in Edition 0.1 ......................................................................................................................... Index ................................................................................................................................................................

viii

198 199 200 201 201 202 205 207 207 211 211 211 211 212 212 212 215

List of Figures 2.1. Downloading Maven 2 from the Apache Maven web site ....................................................................................... 7 2.2. Downloading Maven 3 from the Apache Maven web site ....................................................................................... 8 3.1. The Project Object Model ............................................................................................................................... 16 3.2. The Super POM is always the base Parent ......................................................................................................... 19 3.3. Project Inheritance for a-parent and project-a ...................................................................................................... 30 3.4. maven-book Multi-module vs. Inheritance .......................................................................................................... 33 3.5. Enterprise Multi-module vs. Inheritance ............................................................................................................. 34 6.1. Directory Structure of Sample Multi-module Project ............................................................................................ 68 6.2. Dependencies within Sample Multi-module Project .............................................................................................. 68 10.1. Simple Generated Maven Site ....................................................................................................................... 118 10.2. Customized Sample Project Web Site ............................................................................................................. 119 13.1. Adding a Proxy Repository to Sonatype Nexus ................................................................................................ 164 13.2. Configuring the Sonatype Flexmojos Proxy Repository ..................................................................................... 165 13.3. Adding the Sonatype Flexmojos Proxy to the Public Repositories Group .............................................................. 166 13.4. Flexmojo Library Archetype File Structure ..................................................................................................... 169 13.5. Directory Structure for Flex Application Archetype .......................................................................................... 173 13.6. Directory Structure for Flex Multimodule Archetype ......................................................................................... 176 13.7. The FlexMojos SWC Lifecycle ..................................................................................................................... 181 13.8. The FlexMojos SWF Lifecycle ..................................................................................................................... 182 13.9. Actionscript Documentation Generated by the FlexMojos Plugin ......................................................................... 183 13.10. Actionscript Documentation Report on Maven Site ......................................................................................... 185 13.11. Flexmojos Subversion Repository ................................................................................................................ 186 A.1. Storing Unencrypted Passwords in Maven Settings ............................................................................................ 202 A.2. Storing Encrypted Passwords in Maven Settings ............................................................................................... 202

List of Examples 1.1. A Simple Ant build.xml file .............................................................................................................................. 4 1.2. A Sample Maven pom.xml ................................................................................................................................ 5 3.1. The Super POM ............................................................................................................................................ 16 3.2. The Simplest POM ........................................................................................................................................ 19 3.3. Project Dependencies ...................................................................................................................................... 22 3.4. Declaring Optional Dependencies ..................................................................................................................... 24 3.5. Specifying a Dependency Range: JUnit 3.8 - JUnit 4.0 ......................................................................................... 25 3.6. Specifying a Dependency Range: JUnit