第六十五章. Maven 发布（新）

使用Maven格式发布的功能，是由 “maven-publish” 插件提供的。
The ability to publish in the Maven format is provided by the “maven-publish” plugin.

“publishing” 插件在project上创建了一个名为 “publishing”的 PublishingExtension类型的扩展。这个扩展提供了两个容器，一个叫publications，一个叫repositories。“maven-publish”插件适用于MavenPublication publications 和 MavenArtifactRepository 仓库。
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” plugin works with MavenPublication publications and MavenArtifactRepository repositories.

apply plugin: 'maven-publish'

应用“maven-publish”插件将会执行以下操作：
Applying the “maven-publish” plugin does the following:

发布对象描述了要被创建的发布内容的结构和配置。publications是通过任务发布到仓库中的，并且发布对象的配置明确决定了会发布哪些内容。一个项目的所有publications会在 PublishingExtension.getPublications() 容器中定义。每一个发布
Publication objects describe the structure/configuration of a publication to be created. Publications are published to repositories via tasks, and the configuration of the publication object determines exactly what is published. All of the publications of a project are defined in the PublishingExtension.getPublications() container. Each publication has a unique name within the project.

为了能让“maven-publish”插件起作用的，一个 MavenPublication 必须被添加到publications集里。这个publication决定了实际上哪些构件会被发布，以及在关联的 POM文件中所包含的详细信息。通过添加组件，自定义构件，以及直接修改生成的POM文件，可以配置一个publication。
For the “maven-publish” plugin to have any effect, a MavenPublication must be added to the set of publications. This publication determines which artifacts are actually published as well as the details included in the associated POM file. A publication can be configured by adding components, customizing artifacts, and by modifying the generated POM file directly.

publications {
        mavenJava(MavenPublication) {
            from components.java
        }
    }

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

publishing {
    publications {
        mavenJava(MavenPublication) {
            from components.java

            artifact sourceJar {
                classifier "sources"
            }
        }
    }
}

publishing {
        publications {
            maven(MavenPublication) {
                groupId 'org.gradle.sample'
                artifactId 'project1-sample'
                version '1.1'

                from components.java
            }
        }
    }

publications {
        mavenCustom(MavenPublication) {
            pom.withXml {
                asNode().appendNode('description', 'A demonstration of maven POM customization')
            }
        }
    }

task apiJar(type: Jar) {
        baseName "publishing-api"
        from sourceSets.main.output
        exclude '**/impl/**'
    }

    publishing {
        publications {
            impl(MavenPublication) {
                groupId 'org.gradle.sample.impl'
                artifactId 'project2-impl'
                version '2.3'

                from components.java
            }
            api(MavenPublication) {
                groupId 'org.gradle.sample'
                artifactId 'project2-api'
                version '2'

                artifact apiJar
            }
        }
    }

发布的内容都会被发布到仓库中用于发布的仓库是通过PublishingExtension.getRepositories()容器来定义的。
Publications are published to repositories. The repositories to publish to are defined by the PublishingExtension.getRepositories() container.

repositories {
        maven {
            url "$buildDir/repo" // change to point to your repo, e.g. http://my.org/repo
        }
    }

定义用于发布的仓库的DSL和定义用于查找依赖的仓库的DSL一样（RepositoryHandler）。然而，在Maven 发布的场景中，只有MavenArtifactRepository()仓库才可以用于发布。
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.

对每一个在 publishing.publications 和 publishing.repositories 容器中分别组合的MavenPublication 和 MavenArtifactRepository，“maven-publish” 插件自动为它们创建了一个 PublishToMavenRepository 任务。
The “maven-publish” plugin automatically creates a PublishToMavenRepository task for each MavenPublication and MavenArtifactRepository combination in the publishing.publications and publishing.repositories containers respectively.

这个创建的任务使用“publish«PUBLICATION 名称»PublicationTo«REPOSITORY 名称»Repository”的方式来命名。
The created task is named using the pattern "publish«NAME OF PUBLICATION»PublicationTo«NAME OF REPOSITORY»Repository".

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

group = 'org.gradle.sample'
version = '1.0'

publishing {
    publications {
        mavenJava(MavenPublication) {
            from components.java
        }
    }
    repositories {
        maven {
            url "$buildDir/repo" // change to point to your repo, e.g. http://my.org/repo
        }
    }
}

> gradle publish
:generatePomFileForMavenJavaPublication
:compileJava
:processResources UP-TO-DATE
:classes
:jar
:publishMavenJavaPublicationToMavenRepository
:publish

BUILD SUCCESSFUL

Total time: 1 secs

因此，在下面的例子中，添加了一个 PublishToMavenRepository 任务，名字叫做“publishMavenJavaPublicationToMavenRepository”。这个任务会被连接到 publish 生命周期任务。执行gradle publish会构建 POM 文件和所有用于发布的构件，并将它们传输到仓库中。
So in this example a single PublishToMavenRepository task is be added, named 'publishMavenJavaPublicationToMavenRepository'. 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.

与本地的 Maven 安装集成，有时很有用，比如把模块发布到本地的.m2 存储库中。在 Maven 的说法中，这叫做“安装”模块。对每一个在 publishing.publications 容器的MavenPublication ，“maven-publish” 插件自动为它们创建了一个 PublishToMavenLocal 任务。所有这些任务都被连线到publishToMavenLocal生命周期任务。你不需要在你的“publishing.repositories”节点中声明“mavenLocal”。
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.

这个创建的任务使用“publish«PUBLICATION 名称»PublicationToMavenLocal”的方式来命名。
The created task is named using the pattern "publish«NAME OF PUBLICATION»PublicationToMavenLocal".

-> gradle publish
:generatePomFileForMavenJavaPublication
:compileJava
:processResources UP-TO-DATE
:classes
:jar
:publishMavenJavaPublicationToMavenRepository
:publish

BUILD SUCCESSFUL

Total time: 1 secs

因此在这个例子中，你可以看到添加了一个 PublishToMavenLocal 任务，任务名字叫做“publishMavenJavaPublicationToMavenLocal”。这个任务被连线到publishToMavenLocal生命周期任务。执行gradle publishToMavenLocal会构建 POM 文件和所有要发布的构件，并将它们“installs”到本地Maven仓库中。
So in this example you can see that a single PublishToMavenLocal task is be added, named 'publishMavenJavaPublicationToMavenLocal'. This task is wired into the publishToMavenLocal 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.

有时候，我们会需要在实际 上不发布的情况下，生成一个模块的Maven POM文件。由于POM的生成是由一个单独的任务执行的，所以这很容易实现。
At times it is useful to generate a Maven POM file for a module without actually publishing. Since POM generation is performed by a separate task, it is very easy to do so.

用于生成POM文件的这个任务，任务类型是 GenerateMavenPom，并且它被指定了一个基于发布名称的名字：“generatePomFileFor«PUBLICATION名称»Publication”。所以在下面的例子中，当发布的名称叫“mavenCustom”，那么这个任务的名称就会是“generatePomFileForMavenCustomPublication”。
The task for generating the POM file is of type GenerateMavenPom, and it is given a name based on the name of the publication: "generatePomFileFor«NAME OF PUBLICATION»Publication". So in the example below, where the publication is named "mavenCustom", the task will be named "generatePomFileForMavenCustomPublication".

model {
    tasks.generatePomFileForMavenCustomPublication {
        destination = file("$buildDir/generated-pom.xml")
    }
}

> gradle generatePomFileForMavenCustomPublication
:generatePomFileForMavenCustomPublication

BUILD SUCCESSFUL

Total time: 1 secs

发布模型的所有细节仍然要在 POM 生成中考虑，包括compon'，自定义artifacts，以及通过pom.withXml所做的任何修改。
All details of the publishing model are still considered in POM generation, including components`, custom artifacts, and any modifications made via pom.withXml.