# Chapter 37. The Maven Plugin

This chapter is a work in progress

The Maven plugin adds support for deploying artifacts to Maven repositories.

## 37.1. Usage

To use the Maven plugin, include in your build script:

Example 37.1. Using the Maven plugin

`build.gradle`

    apply plugin: 'maven'

## 37.2. Tasks

The Maven plugin defines the following tasks:

Table 37.1. Maven plugin - tasks

Task name | Depends on | Type | Description
`install` | All tasks that build the associated archives. | `Upload` | Installs the associated artifacts to the local Maven cache, including Maven metadata generation. By default the install task is associated with the `archives` configuration. This configuration has by default only the default jar as an element. To learn more about installing to the local repository, see: Section 37.6.3, “Installing to the local repository”

## 37.3. Dependency management

The Maven plugin does not define any dependency configurations.

## 37.4. Convention properties

The Maven plugin defines the following convention properties:

Table 37.2. Maven plugin - properties

Property name | Type | Default value | Description
`pomDirName` | `String` | `poms` | The path of the directory to write the generated POMs, relative to the build directory.
`pomDir` | `File (read-only)` | ``buildDir`/`pomDirName`` | The directory where the generated POMs are written to.
`conf2ScopeMappings` | ``Conf2ScopeMappingContainer`` | `n/a` | Instructions for mapping Gradle configurations to Maven scopes. See Section 37.6.4.2, “Dependency mapping”.

These properties are provided by a `MavenPluginConvention` convention object.

## 37.5. Convention methods

The maven plugin provides a factory method for creating a POM. This is useful if you need a POM without the context of uploading to a Maven repo.

Example 37.2. Creating a stand alone pom.

`build.gradle`

    task writeNewPom << {
        pom {
            project {
                inceptionYear '2008'
                licenses {
                    license {
                        name 'The Apache Software License, Version 2.0'
                        url 'http://www.apache.org/licenses/LICENSE-2.0.txt'
                        distribution 'repo'
                    }
                }
            }
        }.writeTo("$buildDir/newpom.xml")
    }

Amongst other things, Gradle supports the same builder syntax as polyglot Maven. To learn more about the Gradle Maven POM object, see `MavenPom`. See also: `MavenPluginConvention`

## 37.6. Interacting with Maven repositories

### 37.6.1. Introduction

With Gradle you can deploy to remote Maven repositories or install to your local Maven repository. This includes all Maven metadata manipulation and works also for Maven snapshots. In fact, Gradle's deployment is 100 percent Maven compatible as we use the native Maven Ant tasks under the hood.

Deploying to a Maven repository is only half the fun if you don't have a POM. Fortunately Gradle can generate this POM for you using the dependency information it has.

### 37.6.2. Deploying to a Maven repository

Let's assume your project produces just the default jar file. Now you want to deploy this jar file to a remote Maven repository.

Example 37.3. Upload of file to remote Maven repository

`build.gradle`

    apply plugin: 'maven'

    uploadArchives {
        repositories {
            mavenDeployer {
                repository(url: "file://localhost/tmp/myRepo/")
            }
        }
    }

That is all. Calling the `uploadArchives` task will generate the POM and deploys the artifact and the pom to the specified repository.

There is some more work to do if you need support for other protocols than `file`. In this case the native Maven code we delegate to needs additional libraries. Which libraries depend on the protocol you need. The available protocols and the corresponding libraries are listed in Table 37.3, “Protocol jars for Maven deployment” (those libraries have again transitive dependencies which have transitive dependencies). [17] For example to use the ssh protocol you can do:

Example 37.4. Upload of file via SSH

`build.gradle`

    configurations {
        deployerJars
    }

    repositories {
        mavenCentral()
    }

    dependencies {
        deployerJars "org.apache.maven.wagon:wagon-ssh:1.0-beta-2"
    }

    uploadArchives {
        repositories.mavenDeployer {
            name = 'sshDeployer' // optional
            configuration = configurations.deployerJars
            repository(url: "scp://repos.mycompany.com/releases") {
                authentication(userName: "me", password: "myPassword")
            }
        }
    }

There are many configuration options for the Maven deployer. The configuration is done via a Groovy builder. All the elements of this tree are Java beans. To configure the simple attributes you pass a map to the bean elements. To add another bean elements to its parent, you use a closure. In the example above repository and authentication are such bean elements. Table 37.4, “Configuration elements of the MavenDeployer” lists the available bean elements and a link to the javadoc of the corresponding class. In the javadoc you can see the possible attributes you can set for a particular element.

In Maven you can define repositories and optionally snapshot repositories. If no snapshot repository is defined, releases and snapshots are both deployed to the `repository` element. Otherwise snapshots are deployed to the `snapshotRepository` element.

Table 37.3. Protocol jars for Maven deployment

Protocol | Library
http | org.apache.maven.wagon:wagon-http:1.0-beta-2
ssh | org.apache.maven.wagon:wagon-ssh:1.0-beta-2
ssh-external | org.apache.maven.wagon:wagon-ssh-external:1.0-beta-2
scp | org.apache.maven.wagon:wagon-scp:1.0-beta-2
ftp | org.apache.maven.wagon:wagon-ftp:1.0-beta-2
webdav | org.apache.maven.wagon:wagon-webdav-jackrabbit:1.0-beta-6
file | -

Table 37.4. Configuration elements of the MavenDeployer

Element | Javadoc
root | `MavenDeployer`
repository | org.apache.maven.artifact.ant.RemoteRepository
authentication | org.apache.maven.artifact.ant.Authentication
releases | org.apache.maven.artifact.ant.RepositoryPolicy
snapshots | org.apache.maven.artifact.ant.RepositoryPolicy
proxy | org.apache.maven.artifact.ant.Proxy
snapshotRepository | org.apache.maven.artifact.ant.RemoteRepository

### 37.6.3. Installing to the local repository

The Maven plugin adds an `install` task to your project. This task depends on all the archives task of the `archives` configuration. It installs those archives to your local Maven repository. If the default location for the local repository is redefined in a Maven `settings.xml`, this is considered by this task.

### 37.6.4. Maven POM generation

The Maven POMs for uploading are automatically generated by Gradle. The groupId, artifactId, version and packaging values are taken from the project object. The dependency elements are created from the Gradle dependency declarations. You can find the generated POMs in the directory `<buildDir>/poms`. You can further customize the POM via the API of the `MavenPom` object.

You might want the artifact deployed to the maven repository to have a different version or name than the artifact generated by Gradle. To customize these you can do:

Example 37.5. Customization of pom

`build.gradle`

    uploadArchives {
        repositories {
            mavenDeployer {
                repository(url: "file://localhost/tmp/myRepo/")
                pom.version = '1.0Maven'
                pom.artifactId = 'myMavenName'
            }
        }
    }

Or you want to add new elements like license information.

Example 37.6. Builder style customization of pom

`build.gradle`

    uploadArchives {
        repositories {
            mavenDeployer {
                repository(url: "file://localhost/tmp/myRepo/")
                pom.project {
                    licenses {
                        license {
                            name 'The Apache Software License, Version 2.0'
                            url 'http://www.apache.org/licenses/LICENSE-2.0.txt'
                            distribution 'repo'
                        }
                    }
                }
            }
        }
    }

We use a builder here. You could also add the artifactId and groupId via the builder.

The pom object offers a `whenConfigure` method, if you need to modify the autogenerated content.

Example 37.7. Modifying auto-generated content

`build.gradle`

    [installer, deployer]*.pom*.whenConfigured {pom ->
        pom.dependencies.find {dep -> dep.groupId == 'group3' && dep.artifactId == 'runtime' }.optional = true
    }

If you have more than one artifact to publish, things work a little bit differently. SeeSection 37.6.4.1, “Multiple artifacts per project”.

To customize the settings for the Maven installer (seeSection 37.6.3, “Installing to the local repository”), you can do:

Example 37.8. Customization of Maven installer

`build.gradle`

    configure(install.repositories.mavenInstaller) {
        pom.project {
            version '1.0Maven'
            artifactId 'myName'
        }
    }

In contrast to the example above we use the builder here for changing groupId and artifactId.

#### 37.6.4.1. Multiple artifacts per project

Maven can only deal with one artifact per project. This is reflected in the structure of the Maven POM. We think there are many situations where it makes sense to have more than one artifact per project. In such a case you need to generate multiple POMs. In such a case you have to explicitly declare each artifact you want to publish to a Maven repository. The `MavenDeployer` and the MavenInstaller both provide an API for this:

Example 37.9. Generation of multiple poms

`build.gradle`

    uploadArchives {
        repositories {
            mavenDeployer {
                repository(url: "file://localhost/tmp/myRepo/")
                addFilter('api') {artifact, file ->
                    artifact.name == 'api'
                }
                addFilter('service') {artifact, file ->
                    artifact.name == 'service'
                }
                pom('api').version = 'mySpecialMavenVersion'
            }
        }
    }

You need to declare a filter for each artifact you want to publish. This filter defines a boolean expression for which Gradle artifact it accepts. Each filter has a POM associated with it which you can configure. To learn more about this have a look at `PomFilterContainer` and its associated classes.

#### 37.6.4.2. Dependency mapping

The Maven plugin configures the default mapping between the Gradle configurations added by the Java and War plugin and the Maven scopes. Most of the time you don't need to touch this and you can safely skip this section. The mapping works like the following. You can map a configuration to one and only one scope. Different configurations can be mapped to one or different scopes. One can assign also a priority to a particular configuration-to-scope mapping. Have a look at `Conf2ScopeMappingContainer` to learn more. To access the mapping configuration you can say:

Example 37.10. Accessing a mapping configuration

`build.gradle`

    task mappings << {
        println conf2ScopeMappings.mappings
    }

Gradle exclude rules are converted to Maven excludes if possible. Such a conversion is possible if in the Gradle exclude rule the group as well as the module name is specified (as Maven needs both in contrast to Ivy). Per-configuration excludes are also included in the Maven POM, if they are convertible.

[17] It is planned for a future release to provide out-of-the-box support for this