Apache Maven

356 Pages·2009·1.4 MB·English

......................................................................................................................................
Apache Maven
Current version
User Guide
......................................................................................................................................
The Apache Software Foundation 2009-10-16

Table of Contents i
Table of Contents
.......................................................................................................................................
1 Table of Contents ........................................................... i
2 What is Maven? ............................................................. 1
3 Features ..................................................................... 3
4 FAQ .......................................................................... 4
5 Community Overview ...................................................... 11
5.1 How to Contribute ............................................................ 13
5.2 Getting Help .................................................................. 15
5.3 Issue Tracking ................................................................ 17
5.4 Source Repository ............................................................ 18
5.5 Continuous Integration ........................................................ 20
6 Running Maven ............................................................ 21
7 Maven Plugins ............................................................. 23
8 User Centre ................................................................ 30
8.1 Maven in 5 Minutes ........................................................... 31
8.2 Getting Started Guide ......................................................... 35
8.3 POM Reference ............................................................... 57
8.4 Settings Reference ............................................................ 91
8.5 Guides ...................................................................... 100
8.5.1 The Build Lifecycle ....................................................... 103
8.5.2 The POM ............................................................... 111
8.5.3 Profiles ................................................................. 123
8.5.4 Repositories ............................................................. 133
8.5.5 Standard Directory Layout ................................................ 136
8.5.6 The Dependency Mechanism .............................................. 137
8.5.7 Plugin Development ...................................................... 153
8.5.8 Configuring Plug-ins ...................................................... 156
8.5.9 The Plugin Registry ...................................................... 169
8.5.10 Plugin Prefix Resolution .................................................. 172
8.5.11 Developing Ant Plugins ................................................... 174
8.5.12 Developing Java Plugins .................................................. 188
8.5.13 Creating a Site .......................................................... 198
8.5.14 Snippet Macro ........................................................... 203
8.5.15 What is an Archetype .................................................... 205
8.5.16 Creating Archetypes ...................................................... 207
8.5.17 From Maven 1.x to Maven 2.x ............................................. 210
8.5.18 Using Maven 1.x repositories with Maven 2.x ................................ 213
8.5.19 Relocation of Artifacts .................................................... 214
8.5.20 Installing 3rd party JARs to Local Repository ................................ 216
©2009, The Apache Software Foundation • ALL RIGHTS RESERVED.
Table of Contents ii
8.5.21 Deploying 3rd party JARs to Remote Repository ............................. 217
8.5.22 Coping with Sun JARs ................................................... 218
8.5.23 Remote repository access through authenticated HTTPS ...................... 220
8.5.24 Creating Assemblies ..................................................... 222
8.5.25 Configuring Archive Plugins ............................................... 226
8.5.26 Configuring Maven ....................................................... 227
8.5.26 Mirror Settings ........................................................... 230
8.5.26 Deployment and Security Settings ......................................... 233
8.5.26 Embedding Maven 2.x .................................................... 234
8.5.26 Generating Sources ...................................................... 237
8.5.26 Working with Manifests ................................................... 239
8.5.26 Maven Classloading ...................................................... 241
8.5.26 Using Multiple Modules in a Build .......................................... 243
8.5.26 Using Multiple Repositories ............................................... 245
8.5.26 Using Proxies ........................................................... 247
8.5.26 Using the Release Plugin ................................................. 248
8.5.26 Using Ant with Maven .................................................... 253
8.5.26 Using Modello ........................................................... 255
8.5.26 Webapps ............................................................... 258
8.5.26 Using Extensions ........................................................ 259
8.5.26 Building For Different Environments with Maven 2 ............................ 260
8.5.26 Using Toolchains ........................................................ 263
8.5.26 Encrypting passwords in settings.xml ....................................... 266
8.5.26 Reusable Test JARs ..................................................... 269
8.6 Eclipse Integration ........................................................... 271
8.7 Netbeans Integration ......................................................... 272
9 Plugin Developer Centre ................................................. 273
9.1 Testing your Plugin .......................................................... 274
9.2 Documenting your Plugin ..................................................... 283
9.3 Common Bugs and Pitfalls ................................................... 284
9.4 Mojo API .................................................................... 292
10 Maven Repository Centre ................................................ 304
10.1 Guide to Maven Evangelism .................................................. 305
10.2 Guide to uploading artifacts .................................................. 306
11 Maven Developer Centre ................................................. 312
11.1 Developing Maven 2 ......................................................... 314
11.2 Building Maven 2 ............................................................ 317
11.3 Committer Environment ...................................................... 320
11.4 Committer Settings ........................................................... 322
11.5 Maven Code Style And Conventions .......................................... 323
©2009, The Apache Software Foundation • ALL RIGHTS RESERVED.
Table of Contents iii
11.6 Maven JIRA Convention ..................................................... 328
11.7 Maven SVN Convention ...................................................... 330
11.8 Making GPG Keys ........................................................... 332
11.9 Release Process ............................................................. 335
11.10 Deploy Maven Current References ........................................... 345
12 External Resources ....................................................... 346
©2009, The Apache Software Foundation • ALL RIGHTS RESERVED.
Table of Contents iv
©2009, The Apache Software Foundation • ALL RIGHTS RESERVED.
1 What is Maven? 1
1 What is Maven?
.......................................................................................................................................
1.1 Introduction
Maven, a Yiddish word meaning accumulator of knowledge, was originally started as an attempt to
simplify the build processes in the Jakarta Turbine project. There were several projects each with their
own Ant build files that were all slightly different and JARs were checked into CVS. We wanted a
standard way to build the projects, a clear definition of what the project consisted of, an easy way to
publish project information and a way to share JARs across several projects.
The result is a tool that can now be used for building and managing any Java-based project. We hope
that we have created something that will make the day-to-day work of Java developers easier and
generally help with the comprehension of any Java-based project.
1.2 Maven's Objectives
Maven's primary goal is to allow a developer to comprehend the complete state of a development
effort in the shortest period of time. In order to attain this goal there are several areas of concern that
Maven attempts to deal with:
• Making the build process easy
• Providing a uniform build system
• Providing quality project information
• Providing guidelines for best practices development
• Allowing transparent migration to new features
1.2.1 Making the build process easy
While using Maven doesn't eliminate the need to know about the underlying mechanisms, Maven
does provide a lot of shielding from the details.
1.2.2 Providing a uniform build system
Maven allows a project to build using its project object model (POM) and a set of plugins that are
shared by all projects using Maven, providing a uniform build system. Once you familiarize yourself
with how one Maven project builds you automatically know how all Maven projects build saving you
immense amounts of time when trying to navigate many projects.
1.2.3 Providing quality project information
Maven provides plenty of useful project information that is in part taken from your POM and in part
generated from your project's sources. For example, Maven can provide:
• Change log document created directly from source control
• Cross referenced sources
• Mailing lists
• Dependency list
• Unit test reports including coverage
As Maven improves the information set provided will improve, all of which will be transparent to
users of Maven.
Other products can also provide Maven plugins to allow their set of project information alongside
some of the standard information given by Maven, all still based on the POM.
©2009, The Apache Software Foundation • ALL RIGHTS RESERVED.
1 What is Maven? 2
1.2.4 Providing guidelines for best practices development
Maven aims to gather current principles for best practices development, and make it easy to guide a
project in that direction.
For example, specification, execution, and reporting of unit tests are part of the normal build cycle
using Maven. Current unit testing best practices were used as guidelines:
• Keeping your test source code in a separate, but parallel source tree
• Using test case naming conventions to locate and execute tests
• Have test cases setup their environment and don't rely on customizing the build for test
preparation.
Maven also aims to assist in project workflow such as release management and issue tracking.
Maven also suggests some guidelines on how to layout your project's directory structure so that once
you learn the layout you can easily navigate any other project that uses Maven and the same defaults.
1.2.5 Allowing transparent migration to new features
Maven provides an easy way for Maven clients to update their installations so that they can take
advantage of any changes that been made to Maven itself.
Installation of new or updated plugins from third parties or Maven itself has been made trivial for this
reason.
1.3 What is Maven Not?
You may have heard some of the following things about Maven:
• Maven is a site and documentation tool
• Maven extends Ant to let you download dependencies
• Maven is a set of reusable Ant scriptlets
While Maven does these things, as you can read above in the "What is Maven?" section, these are not
the only features Maven has, and its objectives are quite different.
Maven does encourage best practices, but we realise that some projects may not fit with these ideals
for historical reasons. While Maven is designed to be flexible, to an extent, in these situations and to
the needs of different projects, it can not cater to every situation without making compromises to the
integrity of its objectives.
If you decide to use Maven, and have an unusual build structure that you cannot reorganise, you may
have to forgo some features or the use of Maven altogether.
©2009, The Apache Software Foundation • ALL RIGHTS RESERVED.
2 Features 3
2 Features
.......................................................................................................................................
2.1 Feature Summary
The following are the key features of Maven in a nutshell:
• Simple project setup that follows best practices - get a new project or module started in seconds
• Consistent usage across all projects means no ramp up time for new developers coming onto a
project
• Superior dependency management including automatic updating, dependency closures (also
known as transitive dependencies)
• Able to easily work with multiple projects at the same time
• A large and growing repository of libraries and metadata to use out of the box, and arrangements
in place with the largest Open Source projects for real-time availability of their latest releases
• Extensible, with the ability to easily write plugins in Java or scripting languages
• Instant access to new features with little or no extra configuration
• Ant tasks for dependency management and deployment outside of Maven
• Model based builds: Maven is able to build any number of projects into predefined output types
such as a JAR, WAR, or distribution based on metadata about the project, without the need to do
any scripting in most cases.
• Coherent site of project information: Using the same metadata as for the build process, Maven is
able to generate a web site or PDF including any documentation you care to add, and adds to that
standard reports about the state of development of the project. Examples of this information can
be seen at the bottom of the left-hand navigation of this site under the "Project Information" and
"Project Reports" submenus.
• Release management and distribution publication: Without much additional configuration,
Maven will integrate with your source control system such as CVS and manage the release of a
project based on a certain tag. It can also publish this to a distribution location for use by other
projects. Maven is able to publish individual outputs such as a JAR, an archive including other
dependencies and documentation, or as a source distribution.
• Dependency management: Maven encourages the use of a central repository of JARs and
other dependencies. Maven comes with a mechanism that your project's clients can use to
download any JARs required for building your project from a central JAR repository much
like Perl's CPAN. This allows users of Maven to reuse JARs across projects and encourages
communication between projects to ensure that backward compatibility issues are dealt with. We
are collaborating with the folks at Ibiblio who have graciously allowed the central repository to
live on their servers.
©2009, The Apache Software Foundation • ALL RIGHTS RESERVED.
3 FAQ 4
3 FAQ
.......................................................................................................................................
3.1 Frequently Asked Technical Questions
1 How do I prevent "[WARNING] Using platform encoding (Cp1252 actually) to copy filtered
resources, i.e. build is platform dependent!"
2 How do I prevent including JARs in WEB-INF/lib? I need a "compile only" scope!
3 How do I list available plugins?
4 How do I determine what version of a plugin I am using?
5 How can I use Ant tasks in Maven 2?
6 How do I set up Maven so it will compile with a target and source JVM of my choice?
7 Is it possible to create my own directory structure?
8 Where is the source code? I couldn't seem to find a link anywhere on the Maven2 site.
9 Maven can't seem to download the dependencies. Is my installation correct?
10I have a jar that I want to put into my local repository. How can I copy it in?
11How do I unsubscribe from Maven mailing lists?
12How do I skip the tests?
13How can I run a single unit test?
14Handle special characters in site
15How do I include tools.jar in my dependencies?
16Maven compiles my test classes but doesn't run them?
17Where are Maven SNAPSHOT artifacts?
18Where are the Maven XSD schemas?
19Maven doesn't work, how do I get help?
20How to produce execution debug output or error messages?
21What is a Mojo?
22How to find dependencies on public Maven repositories?
How do I prevent "[WARNING] Using platform encoding (Cp1252 actually) to copy
filtered resources, i.e. build is platform dependent!"
This or a similar warning is emitted by a plugin that processes plain text files but has not
been configured to use a specific file encoding. So eliminating the warning is simply a
matter of finding out what plugin emits it and how to configure the file encoding for it.
For plugins that follow our guideline for source file encoding, this is as easy as adding the
following property to your POM (or one of its parent POMs):
<project>
...
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
...
</project>
[top]
How do I prevent including JARs in WEB-INF/lib? I need a "compile only" scope!
©2009, The Apache Software Foundation • ALL RIGHTS RESERVED.