Chapter 5. Publishing to a Maven Repository

In the previous chapter, you learned how to use the Upload task to publish your project artifacts. In this chapter, you will learn more about the new and still-developing feature of publishing your artifacts to a Maven repository.

You will learn about the new publishing mechanism in Gradle. This feature is currently still under development, and that means the implementation might change in the future. But for now, this way of publishing artifacts will be the default.

Defining publication

We must add the maven-publish plugin to our project to add the new publication feature of Gradle. The plugin allows us to define and deploy our project artifacts in the Maven format. This means our deployed project can be used by other developers and projects that support the Maven format. For example, other projects could use Gradle or Maven and define a dependency to our published artifacts.

The maven-publish plugin is based on a general publishing plugin. The publishing plugin adds a new publishing extension to our project. We can use a publications configuration block in our build script to configure the artifacts we want to publish and the repositories we want to deploy to. The publications extension has the PublishingExtension type in the org.gradle.api.publish package. The plugin also adds the general life cycle publish task to the project. Other tasks can be added as task dependencies to this task; thus, with a single publish task, all the publications in the...

Defining publication artifacts

Any publication we define must have a unique name in our project. We can add multiple publications with their own names inside a publications configuration block. To add an artifact, we can use the artifact method in the publication definition. We can also use the artifacts property to directly set all artifacts.

We can define artifacts with the artifact method in the following ways:

Type	Description
AbstractArchiveTask	The information for the artifact is extracted from the archive task. The artifact is an instance of PublishArtifact in the org.gradle.api.artifacts package.
File	The information for the artifact is extracted from the filename.
Map	This is another way to define artifacts. The map must contain a source key referencing a file or archive task. The other properties we can use to further configure the artifact are classifier and extension.

Using archive task artifacts

In the following example build file, we define a new publication with the name publishJar, and we define the output of the jar archive task as an artifact:

apply plugin: 'maven-publish'
apply plugin: 'java'

// Configuration block for publishing
// artifacts from the project.
publishing {

  // Define publications with what
  // needs to be published.
  publications {

    // Name of this publication
    // is publishJar.
    publishJar(MavenPublication) {

      // Use output of jar task
      // as the artifact for
      // the publication.
      artifact jar

      // Alternatively we can use
      // a Map notation:
      // artifact source: jar
    }

  }
}

Next, we will run the tasks task and, in the output, we will be able to see newly generated tasks for publishing this publication:

$ gradle tasks
...
Publishing tasks
----------------
generatePomFileForPublishJarPublication - Generates the Maven POM file for publication 'publishJar'.
publish - Publishes...

Using file artifacts

Instead of an archive task, we can also use a file as an artifact. Gradle tries to extract the extension and classifier properties from the filename. We can also configure these properties ourselves when we add the file as a publication artifact.

In the following example build file, we use the src/files/README and src/files/COPYRIGHT files as publication artifacts:

apply plugin: 'maven-publish'

publishing {
  publications {
    documentation(MavenPublication) {

      // Use file name as a publication artifact.
      artifact 'src/files/README'

      artifact('src/files/COPYRIGHT') {
        // Each file artifact must have a
        // unique classifier and extension.
        classifier = 'metaInformation'
      }

      // Alternative syntax is with
      // the Map notation:
      // artifact source: 'src/files/README'
      // artifact source: 'src/files/COPYRIGHT',
      //          extension: 'metaInformation'

    }
  }
}

Using software components

Besides the artifact method and the artifacts property, we can also use the from method inside a publications configuration block. We specify SoftwareComponent for Gradle as an argument to the from method. The java plugin adds SoftwareComponent with the name java, and it includes the jar artifact and all runtime dependencies. The war plugin adds the war artifact as SoftwareComponent. SoftwareComponent is a part of the Gradle build model that defines a piece of code that depends on other code or is a dependency for other code.

In the next example build file, we will apply the war plugin to our project, which will implicitly add the java plugin. We also define two publications, each using SoftwareComponent from both plugins. The following code shows this:

apply plugin: 'maven-publish'
apply plugin: 'war'


publishing {

  publications {

    // First publication with
    // the name javaJar, contains
    // the artifact created by the
    // jar task.
    javaJar(MavenPublication...

Generating POM files

An important part of a Maven publication is the POM file. We already saw that Gradle added a generatePom<publicationName> task to our project. Furthermore, we can define some properties of the POM file inside a publication configuration. Gradle also offers a hook to customize the generated POM file even further.

Gradle uses the project's version, group, and name properties in the generated POM file. We create a new example build file where we define the project properties so that they are included in the POM file. The following code shows this:

apply plugin: 'maven-publish'
apply plugin: 'java'

// Defined project properties, that are
// used in the generated POM file.
// The name of the project is by default
// the directory name, but we can
// change it via a settings.gradle file
// and the rootProject.name property.
version = '2.1.RELEASE'
group = 'book.gradle'

repositories {
  jcenter()
}

dependencies {
  compile 'org.springframework:spring-context:4.1.4.RELEASE...

Defining repositories

We must configure a Maven repository to publish our configured publication. We can choose a local directory or a repository manager, such as Artifactory or Nexus. Gradle also adds support installing the publication to our local Maven repository.

Publishing to the local Maven repository

Gradle already adds our local Maven repository as a destination for our publications. For each named publication, there is a publish<publicationName>ToMavenLocal task. Gradle also creates the publishToMavenLocal task, which will publish all publications to the local Maven repository.

We have the following example build file:

apply plugin: 'maven-publish'
apply plugin: 'java'

version = '2.1.DEVELOPMENT'
group = 'book.gradle'

repositories {
  jcenter()
}

dependencies {
  compile 'org.springframework:spring-context:4.1.4.RELEASE'
}

publishing {

  publications {
    publishJar(MavenPublication) {
      artifactId = 'sample'

      from components.java
    }
  }

}

From the command line...

Summary

In this chapter, you learned how to use the new and developing maven-publish plugin. You saw how you can declare your publications with the publications configuration block. Gradle will automatically create new tasks based on what you declared as publications.

You also learned how to customize the POM file that is generated by the Gradle publishing tasks.

Finally, you saw how you can configure Maven repositories so you can deploy your publications to them. We configured a local directory, which could also be a network share, and showed you how to configure an Artifactory or Nexus repository manager.

In the next chapter, you will see how you can upload to Bintray.