Gradle Maven Publish Plugin

External

• https://docs.gradle.org/current/userguide/publishing_maven.html

Internal

• Gradle Concepts
• Gradle Artifact Publishing Concepts

Overview

"maven-publish" is an newer alternative to publishing with Maven Plugin, using "publish" tasks instead of Maven Plugin "Upload" tasks. The plugin generates Maven metadata and publishes the generated metadata and the associated artifacts to Maven repositories. The concepts behind publishing with "maven-publish", and the plugin mechanics, are described in the Concepts and Plugin Mechanics below. A step by step procedure is available under the Procedure section.

The plugin is activated with:

apply plugin: 'maven-publish'

Concepts and Plugin Mechanics

Mechanics

The plugin creates an extension of type PublishingExtension named "publishing". The extension provides a container of named publications and a container of named repositories. The plugin does not have effect if no Maven publication is added to the publications container. If publications and repositories are present, the plugin processes those configurations and based on their content, creates POM generation tasks and publishing tasks that can be used to carry out the publishing action.

Publications

https://docs.gradle.org/current/dsl/org.gradle.api.publish.maven.MavenPublication.html

A Maven Publication is the representation of how Gradle publishes an artifact in Maven format. The Maven Publish plugin publications are defined by the MavenPublication type. They are added to the publishing.publications as follows:

publishing {
  publications {
    <publication-name>(MavenPublication) {
        from <component>
        artifact <task>
        artifact(source, configuration)
        pom(configuration)
    }
  }
}

The above syntax shows that an artifact can be specified by indicating the software component that should be published, or by defining the artifact in-line. If the artifact (or artifacts) are specified in-line, their details can be configured. The generated POM can be configured in-line as well.

Each publication must have an unique name within the project. All the artifacts associated with a publication share the groupID/artifactID/version project coordinates. A publication has a POM and at least one artifact, but it can have several artifacts (or example the class JAR and the source JAR).

Software Component Publication

publishing {
  publications {
    javacomp(MavenPublication) {
        from components.java
    }
  }
}

Custom Artifact Publication

Custom artifacts can be included. They can be raw files or archives (JAR, ZIP). For each custom artifact it is possible to specify extension and classifier values to use for publications. Only one of the published artifact can have an empty classifier, all other must have unique classifier/extension combinations.

task srcJar(type: Jar) {
    from sourceSets.main.allJava
}

publishing {
  publications {
      multiart(MavenPublication) {
         ...
         artifact srcJar {
             classifier "sources"
         }
      }
}

Maven Project Coordinates

The Maven project coordinates the publication will be generated with are inherited from the project, as follows:

• groupId from Project.getGroup()
• artifactId from Project.getName()
• version from Project.getVersion()

However, they can be overridden in the publication definition, as follows:

publishing {
  publications {
      something(MavenPublication) {
         groupId 'blah'
         artifactId 'blah'
         version '1.11.111'
         ...
      }
}

Maven restricts 'groupId' and 'artifactId' to a limited character set ( [A-Za-z0-9_\\-.]+ ) and Gradle enforces this restriction. For 'version' (as well as artifact 'extension' and 'classifier'), Gradle will handle any valid Unicode character. The only Unicode values that are explicitly prohibited are ‘ \ ’, ‘ / ’ and any ISO control character.

POM Customization

https://docs.gradle.org/current/dsl/org.gradle.api.publish.maven.MavenPom.html#org.gradle.api.publish.maven.MavenPom:withXml(org.gradle.api.Action)

Any aspect of the POM can be modified as shown below, with the exception of the project coordinates (groupId, artifactId, and version).

publishing {
  publications {
      something(MavenPublication) {
         ...
         pom.withXml {
                asNode().appendNode('description', 'Something that will be inserted as description')
         }
      }
}

Repositories

The Maven Publish plugin publications are defined by the MavenArtifactRepository type.

Relationship to pre-declared repositories, how can we use it?

Publishing Tasks

The plugin creates publishing tasks, based on declared publications and repositories, for the combination of each publication and repository, and makes them available for use. All publishing tasks are triggered by the overarching "publish" tasks, which publishes all publications produced by the project.

Procedure

Activate the plugin:

apply plugin: 'maven-publish'

Declare the publications.

publishing {
  publications {
    myPublicationName(MavenPublication) {
      // Configure the publication here
    }
  }
}

Declared the target repositories. The example below assumes we want to publish locally into the local Maven repository, and also into a remote Maven repository:

repositories {
    maven {
        url "${url}"
        authentication {
            basic(BasicAuthentication)
        }
    }
}

Publish:

gradle publish

Examples

https://github.com/NovaOrdis/playground/tree/master/gradle/java-publishing

https://github.com/NovaOrdis/playground/tree/master/gradle/java-publishing-multiprojects-multipubs