// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[publishing_maven]]
== Maven Publish Plugin

The Maven Publish Plugin provides the ability to publish build artifacts to an http://maven.apache.org/[Apache Maven] repository. A module published to a Maven repository can be consumed by Maven, Gradle (see <<declaring_dependencies>>) and other tools that understand the Maven repository format. You can learn about the fundamentals of publishing in <<publishing_overview>>.


[[publishing_maven:usage]]
=== Usage

To use the Maven Publish Plugin, include the following in your build script:

++++
<sample id="publishing_maven:apply_plugin" dir="maven-publish/quickstart" title="Applying the Maven Publish Plugin">
    <sourcefile file="build.gradle" snippet="use-plugin"/>
</sample>
++++

The Maven Publish Plugin uses an extension on the project named `publishing` of type api:org.gradle.api.publish.PublishingExtension[]. This extension provides a container of named publications and a container of named repositories. The Maven Publish Plugin works with api:org.gradle.api.publish.maven.MavenPublication[] publications and api:org.gradle.api.artifacts.repositories.MavenArtifactRepository[] repositories.

[[publishing_maven:tasks]]
=== Tasks

[[publishing_maven:generate-pom]]
`generatePomFileFor__PubName__Publication` — type: api:org.gradle.api.publish.maven.tasks.GenerateMavenPom[]::
Creates a POM file for the publication named _PubName_, populating the known metadata such as project name, project version, and the dependencies. The default location for the POM file is _build/publications/$pubName/pom-default.xml_.

`publish__PubName__PublicationTo__RepoName__Repository` — type: api:org.gradle.api.publish.maven.tasks.PublishToMavenRepository[]::
Publishes the _PubName_ publication to the repository named _RepoName_. If you have a repository definition without an explicit name, _RepoName_ will be "Maven".

`publish__PubName__PublicationToMavenLocal` — type: api:org.gradle.api.publish.maven.tasks.PublishToMavenLocal[]::
Copies the _PubName_ publication to the local Maven cache — typically _$USER_HOME/.m2/repository_ — along with the publication's POM file and other metadata.

`publish`::
_Depends on_: All `publish__PubName__PublicationTo__RepoName__Repository` tasks
+
An aggregate task that publishes all defined publications to all defined repositories. It does _not_ include copying publications to the local Maven cache.

`publishToMavenLocal`::
_Depends on_: All `publish__PubName__PublicationToMavenLocal` tasks
+
Copies all defined publications to the local Maven cache, including their metadata (POM files, etc.).


[[publishing_maven:publications]]
=== Publications

This plugin provides <<glossary:publication,publications>> of type api:org.gradle.api.publish.maven.MavenPublication[]. To learn how to define and use publications, see the section on <<sec:basic_publishing,basic publishing>>.

There are four main things you can configure in a Maven publication:

 * A <<glossary:component,component>> — via api:org.gradle.api.publish.maven.MavenPublication#from(org.gradle.api.component.SoftwareComponent)[].
 * <<sec:publishing_custom_artifacts_to_maven,Custom artifacts>> — via the api:org.gradle.api.publish.maven.MavenPublication#artifact(java.lang.Object)[] method. See api:org.gradle.api.publish.maven.MavenArtifact[] for the available configuration options for custom Maven artifacts.
 * Standard metadata like `artifactId`, `groupId` and `version`.
 * Other contents of the POM file — via api:org.gradle.api.publish.maven.MavenPublication#pom(org.gradle.api.Action)[].

You can see all of these in action in the <<publishing_maven:complete_example,complete publishing example>>. The API documentation for `MavenPublication` has additional code samples.

[[sec:identity_values_in_the_generated_pom]]
==== Identity values in the generated POM

The attributes of the generated POM file will contain identity values derived from the following project properties:

* `groupId` - api:org.gradle.api.Project#getGroup()[]
* `artifactId` - api:org.gradle.api.Project#getName()[]
* `version` - api:org.gradle.api.Project#getVersion()[]

Overriding the default identity values is easy: simply specify the `groupId`, `artifactId` or `version` attributes when configuring the api:org.gradle.api.publish.maven.MavenPublication[].

++++
<sample dir="maven-publish/multiple-publications" id="publishing_maven:publish-customize-identity" title="customizing the publication identity">
    <sourcefile file="build.gradle" snippet="customize-identity"/>
</sample>
++++

[TIP]
====
Certain repositories will not be able to handle all supported characters. For example, the `:` character cannot be used as an identifier when publishing to a filesystem-backed repository on Windows.
====

Maven restricts `groupId` and `artifactId` to a limited character set (`[A-Za-z0-9_\\-.]+`) and Gradle enforces this restriction. For `version` (as well as the artifact `extension` and `classifier` properties), Gradle will handle any valid Unicode character.

The only Unicode values that are explicitly prohibited are `\`, `/` and any ISO control character. Supplied values are validated early in publication.

[[sec:modifying_the_generated_pom]]
==== Customizing the generated POM

The generated POM file can be customized before publishing. For example, when publishing a library to Maven Central you will need to set certain metadata. The Maven Publish Plugin provides a DSL for that purpose. Please see api:org.gradle.api.publish.maven.MavenPom[] in the DSL Reference for the complete documentation of available properties and methods. The following sample shows how to use the most common ones:

++++
<sample dir="signing/maven-publish" id="publishing_maven:pom_customization" title="Customizing the POM file">
    <sourcefile file="build.gradle" snippet="pom-customization"/>
</sample>
++++

[[publishing_maven:repositories]]
=== Repositories

This plugin provides <<sub:terminology_repository,repositories>> of type api:org.gradle.api.artifacts.repositories.MavenArtifactRepository[]. To learn how to define and use repositories for publishing, see the section on <<sec:basic_publishing,basic publishing>>.

Here's a simple example of defining a publishing repository:

++++
<sample dir="maven-publish/quickstart" id="publishing_maven:example:repositories" title="Declaring repositories to publish to">
    <sourcefile file="build.gradle" snippet="repositories"/>
</sample>
++++

The two main things you will want to configure are the repository's:

 * URL (required)
 * Name (optional)
 
You can define multiple repositories as long as they have unique names within the build script. You may also declare one (and only one) repository without a name. That repository will take on an implicit name of "Maven".

You can also configure any authentication details that are required to connect to the repository. See api:org.gradle.api.artifacts.repositories.MavenArtifactRepository[] for more details.

[[publishing_maven:snapshot_and_release_repositories]]
==== Snapshot and release repositories

It is a common practice to publish snapshots and releases to different Maven repositories. A simple way to accomplish this is to configure the repository URL based on the project version. The following sample uses one URL for versions that end with "SNAPSHOT" and a different URL for the rest:

++++
<sample dir="maven-publish/javaProject" id="publishing_maven:example:repo-url-from-variable" title="Configuring repository URL based on project version">
    <sourcefile file="build.gradle" snippet="repo-url-from-variable"/>
</sample>
++++

Similarly, you can use a <<build_environment, project or system property>> to decide which repository to publish to. The following example uses the release repository if the project property `release` is set, such as when a user runs `gradle -Prelease publish`:

++++
<sample dir="maven-publish/javaProject" id="publishing_maven:example:repo-url-from-variable" title="Configuring repository URL based on project property">
    <sourcefile file="build.gradle" snippet="repo-url-from-project-property"/>
</sample>
++++

[[publishing_maven:install]]
=== Publishing to Maven Local

For integration with a local Maven installation, it is sometimes useful to publish the module into the Maven local repository (typically at _$USER_HOME/.m2/repository_), along with its POM file and other metadata. In Maven parlance, this is referred to as 'installing' the module.

The Maven Publish Plugin makes this easy to do by automatically creating a api:org.gradle.api.publish.maven.tasks.PublishToMavenLocal[] task for each api:org.gradle.api.publish.maven.MavenPublication[] in the `publishing.publications` container. The task name follows the pattern of `publish__PubName__PublicationToMavenLocal`. Each of these tasks is wired into the `publishToMavenLocal` aggregate task. You do not need to have `mavenLocal()` in your `publishing.repositories` section.

[[publishing_maven:complete_example]]
=== Complete example

The following example demonstrates how to sign and publish a Java library including sources, Javadoc, and a customized POM:

++++
<sample dir="signing/maven-publish" id="publishing_maven:complete_example:sample" title="Publishing a Java library">
    <sourcefile file="build.gradle"/>
</sample>
++++

The result is that the following artifacts will be published:

* The POM: `my-library-1.0.pom`
* The primary JAR artifact for the Java component: `my-library-1.0.jar`
* The sources JAR artifact that has been explicitly configured: `my-library-1.0-sources.jar`
* The Javadoc JAR artifact that has been explicitly configured: `my-library-1.0-javadoc.jar`

The <<signing_plugin, Signing Plugin>> is used to generate a signature file for each artifact. In addition, checksum files will be generated for all artifacts and signature files.

[[publishing_maven:deferred_configuration]]
=== Removal of deferred configuration behavior

[NOTE]
====
Gradle 5.0 will change the behavior of the publishing {} block. Read on to find out how you can make your build compatible today.
====

Prior to Gradle 4.8, the `publishing {}` block was implicitly treated as if all the logic inside it was executed after the project is evaluated.
This caused quite a bit of confusion, because it was the only block that behaved that way.
As part of the stabilization effort in Gradle 4.8, we are deprecating this behavior and asking all users to migrate their build.

The new, stable behavior can be switched on by adding the following to your settings file:

    enableFeaturePreview('STABLE_PUBLISHING')

We recommend doing a test run with a local repository to see whether all artifacts still have the expected coordinates.
In most cases everything should work as before and you are done.

If the coordinates change unexpectedly, you may have some logic inside your publishing block or in a plugin that is depending on the deferred configuration behavior.
For instance, the following logic assumes that the subprojects will be evaluated when the artifactId is set:

[source,groovy]
----
subprojects {
    publishing {
        publications {
            mavenJava {
                from components.java
                artifactId = jar.baseName
            }
        }
    }
}
----

This kind of logic must be wrapped in an `afterEvaluate {}` block to make it work going forward.


[source,groovy]
----
subprojects {
    publishing {
        publications {
            mavenJava {
                from components.java
                afterEvaluate {
                    artifactId = jar.baseName
                }
            }
        }
    }
}
----
