This chapter describes the new incubating Maven publishing support introduced in Gradle 1.4. If you are looking for documentation on the 'traditional' Maven publishing support please see Chapter 46, Publishing artifacts.
This chapter is a work in progress, and is not comprehensive or complete. It is expected that you understand the concepts in Chapter 59, Ivy Publishing (new) before reading this chapter.
This chapter describes how to publish build artifacts to a Apache Maven Repository. A module published to a Maven repository can be consumed by Maven, Gradle (see Chapter 45, Dependency Management) and other tools that understand the Maven repository format.
It is currently only possible to publish 'java' projects using the maven-publish plugin. If the java plugin is not
applied (either directly or indirectly) then no publication will be created.
The ability to publish in the Maven format is provided by the 'maven-publish' plugin.
This plugin does the following:
publishing pluginjava plugin applied:
publishing.publications container
of type MavenPublication named “maven”
(see Section 60.2, “Publications”)
PublishToMavenRepository task for each Maven publishing repository added
(see Section 60.3, “Repositories”)
The “publishing” plugin creates an extension on the project named “publishing” of type PublishingExtension.
This extension provides a container of named publications and a container of named repositories. The “maven-publish” works with
MavenPublication publications and MavenArtifactRepository repositories.
When the “maven-publish” plugin is applied together with the “java”plugin, it creates a single publication named “maven”.
This publication will publish the artifacts of the project and the associated POM file.
The attributes of the generated POM file will contain identity values derived from the following project properties:
groupId - Project.getGroup()artifactId - Project.getName()version - Project.getVersion()
Note that you can set the value of these project properties in your build script, with the exception of name.
At times, the POM file generated from the project information will need to be tweaked before publishing. The maven-publish
plugin provides a hook to allow such modification.
Example 60.2. Modifying the POM file
build.gradle
publications {
maven {
pom.withXml {
asNode().appendNode('description', 'A demonstration of maven pom customisation')
}
}
}In this example we are adding a 'description' element for the generated POM. With this hook, you can modify any aspect of the pom. For example, you could replace the version range for a dependency with the actual version used to produce the build. This allows the pom file to describe how the module should be consumed, rather than be a description of how the module was built.
See MavenPom.withXml() for the relevant API reference documentation.
Publications are published to repositories. The repositories to publish to are defined by the PublishingExtension.getRepositories()
container.
Example 60.3. Declaring repositories to publish to
build.gradle
repositories {
maven {
url "file://$buildDir/repo" // change to point to your repo, e.g. http://my.org/repo
}
}
The DSL used to declare repositories for publication is the same DSL that is used to declare repositories to consume dependencies from,
RepositoryHandler. However, in the context of Maven publication only
MavenArtifactRepository repositories can be used for publication.
The “maven-publish” plugin automatically creates a PublishToMavenRepository
task for each MavenPublication and MavenArtifactRepository
combination in the publishing.publications and publishing.repositories containers respectively.
Example 60.4. A build to publish
build.gradle
apply plugin: 'java' apply plugin: 'maven-publish' group = 'org.gradle.sample' version = '1.0' dependencies { compile 'commons-collections:commons-collections:3.0' } repositories { mavenCentral() } publishing { repositories { maven { url "file://$buildDir/repo" // change to point to your repo, e.g. http://my.org/repo } } }
Output of gradle publish
> gradle publish :compileJava :processResources UP-TO-DATE :classes :jar :publishMavenPublicationToMavenRepository :publish BUILD SUCCESSFUL Total time: 1 secs
So in this example a single PublishToMavenRepository task is be added, named 'publishMavenPublicationToMavenRepository'.
This task is wired into the publish lifecycle task.
Executing gradle publish builds the POM file and all of the artifacts to be published, and transfers them to the repository.
For integration with a local Maven installation, it is sometimes useful to publish the module into the local .m2 repository. In Maven parlance, this is
referred to as 'installing' the module. The maven-publish plugin makes this easy to do by automatically creating a
PublishToMavenLocal task for each MavenPublication
in the publishing.publications container. Each of these tasks is wired into the publishToMavenLocal lifecycle task.
You do not need to have `mavenLocal` in your `publishing.repositories` section.
Example 60.5. Publish a project to the Maven local repository
build.gradle
apply plugin: 'java' apply plugin: 'maven-publish' group = 'org.gradle.sample' version = '1.0' dependencies { compile 'commons-collections:commons-collections:3.0' } repositories { mavenCentral() } publishing { repositories { maven { url "file://$buildDir/repo" // change to point to your repo, e.g. http://my.org/repo } } }
Output of gradle publishToMavenLocal
> gradle publishToMavenLocal :compileJava :processResources UP-TO-DATE :classes :jar :publishMavenPublicationToMavenLocal :publishToMavenLocal BUILD SUCCESSFUL Total time: 1 secs
So in this example a single PublishToMavenLocal task is be added, named 'publishMavenPublicationToMavenLocal'.
This task is wired into the publish lifecycle task.
Executing gradle publishToMavenLocal builds the POM file and all of the artifacts to be published, and 'installs' them into the local Maven repository.