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

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

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

apply plugin: 'maven-publish'

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

Publication对象描述了要创建的发布内容的结构和配置。Publications是通过任务发布到仓库的，发布对象的配置明确地决定了要发布的内容。一个项目的所有publications都会在PublishingExtension.getPublications()容器中定义，每一个publication在项目中都具有唯一名称。
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 用语中，这称为“安装”模块。“maven-publish”插件通过为publishing.publications容器中的每个MavenPublication任务，自动创建一个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 publishToMavenLocal
:generatePomFileForMavenJavaPublication
:compileJava
:processResources UP-TO-DATE
:classes
:jar
:publishMavenJavaPublicationToMavenLocal
:publishToMavenLocal

BUILD SUCCESSFUL

Total time: 1 secs

因此，在这个示例中，你可以看到添加了一个名为“publishMavenJavaPublicationToMavenLocal”的PublisheToMavenLocal任务。这个任务连接到publishToMavenLocal生命周期任务中。执行 gradle publishToMavenLocal 会构建 POM 文件和所有要发布的工件，并将它们“安装”到本地 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 的名称»发布”。因此，在下面的示例中，如果发布名为“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.