Gradle 1.12用户指南翻译——第六十五章. Maven 发布（新）

其他章节的翻译请参见：
http://blog.csdn.net/column/details/gradle-translation.html
翻译项目请关注Github上的地址：
https://github.com/msdx/gradledoc
本文翻译所在分支：
https://github.com/msdx/gradledoc/tree/1.12。
直接浏览双语版的文档请访问：
http://gradledoc.qiniudn.com/1.12/userguide/userguide.html。
另外，Android 手机用户可通过我写的一个程序浏览文档，带缓存功能的，目前0.6开发中版本兼容 Android 2.3以上系统，项目地址如下：
https://github.com/msdx/gradle-doc-apk
翻译不易，转载请注明本文在CSDN博客上的出处：
http://blog.csdn.net/maosidiaoxian/article/details/75528472

关于我对Gradle的翻译，以Github上的项目及http://gradledoc.qiniudn.com 上的文档为准。如发现翻译有误的地方，将首先在以上两个地方更新。因时间精力问题，博客中发表的译文基本不会同步修改。

另外，目前Gradle1.12版本的文档已经翻译完并进入校稿阶段，校稿的方式为到该项目https://github.com/msdx/gradledoc 提交issue或是pull request。校稿的结果不只是在此版本更新，也会用于改善Gradle下一版本（2.0）文档的翻译。

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

本章内容讲的是一个新的 孵化中的 功能，是由“maven-publish”插件提供的 Maven 发布支持。最终这个新的发布支持的发布功能将会取代Upload任务的发布功能。

如果你正在查找关于使用 Upload 任务的原始的Maven 发布支持的文档，请查阅 第五十一章， 发布构件。

这一章介绍的是如何发布构建的构件到一个 Apache Maven 仓库。一个发布到Maven 仓库的模块，可以在Gradle（参见 第五十章， 依赖管理）或其他理解Maven仓库格式的工具中使用。

65.1.  “maven-publish” 插件

使用Maven格式发布的功能，是由 “maven-publish” 插件提供的。

“publishing” 插件在project上创建了一个名为 “publishing”的 PublishingExtension类型的扩展。这个扩展提供了两个容器，一个叫publications，一个叫repositories。“maven-publish”插件适用于MavenPublication publications 和 MavenArtifactRepository 仓库。

示例 65.1. 应用“maven-publish”插件

build.gradle

apply plugin: 'maven-publish'

应用“maven-publish”插件将会执行以下操作：

• 应用“publishing”插件
• 建立一个规则来为每个添加的MavenPublication自动创建 GenerateMavenPom任务（见第 65.2 节，“发布”）。
• 建立一个规则，来为添加的每一个IvyPublication（见第 65.2 节，“发布”）及 MavenArtifactRepository (见 第 65.3 节， “仓库”）的组合自动创建 PublishToIvyRepository任务。
• 建立一个规则来为每个添加的MavenPublication自动创建 PublishToMavenLocal任务（见第 65.2 节，“发布”）。

65.2. 发布

如果你不熟悉项目构件和配置，你应该读一下第五十一章，发布，里面对这些概念进行了介绍。这一章还介绍了使用另一种不同的机制的“发布构件”。这里描述的发布功能最终将取代那一功能。

发布对象描述了要被创建的发布内容的结构和配置。publications是通过任务发布到仓库中的，并且发布对象的配置明确决定了会发布哪些内容。一个项目的所有publications会在 PublishingExtension.getPublications() 容器中定义。每一个发布

为了能让“maven-publish”插件起作用的，一个 MavenPublication 必须被添加到publications集里。这个publication决定了实际上哪些构件会被发布，以及在关联的 POM文件中所包含的详细信息。通过添加组件，自定义构件，以及直接修改生成的POM文件，可以配置一个publication。

65.2.1. 发布软件组件

向Maven仓库发布一个Gradle项目的最简单的方式是指定一个要发布的 SoftwareComponent。目前可用于publication的组件都有：

表65.1. 软件组件

名称	提供者	构件	依赖
java	第二十三章. Java 插件	生成的 jar 文件	“runtime”配置的依赖
web	第二十六章. War 插件	生成的 war 文件	没有依赖

在以下示例中，工件和运行时依赖都来自于由 Java Plugin 添加的 “java” 组件。

示例 65.2. 为一个java组件添加一个MavenPublication

build.gradle

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

65.2.2. 发布自定义构件

我们还可以显式地配置要被包含在publication的构件。这些构件通常是以原始数据文件，或者是 AbstractArchiveTask的实例（如Jar, Zip）的方式来提供。

对于每个自定义的项目，在发布时可以指定extension和classifier的值。注意，只有一个发布的构件可以有一个空的classifier，并且其他所有的构件必须有一个唯一的classifier/extension组件。

如下所示配置自定义构件︰

示例65.3. 向MavenPublication 增加额外的构件

build.gradle

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

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

            artifact sourceJar {
                classifier "sources"
            }
        }
    }
}

关于如何自定义构件的更详细的文档，请参阅MavenPublication 。

64.2.3. 生成的POM中的标识值

生成的 POM 文件的属性中，包含了从以下项目属性中导出来的标识值：

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

重写默认标识值是很容易︰ 只需配置MavenPublication时指定groupId、 artifactId或version的属性。

示例 65.4. 自定义发布标识

build.gradle

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

                from components.java
            }
        }
    }

某些存储库可能无法处理所有支持的字符。例如，当发布到 Windows 上的文件系统支持的存储库，“:”字符就不能用作标识符。

Maven 限制了“groupId”和“artifactId”为有限的字符集（[A-Za-z0-9_\\-.]+），Gradle也强制实施了该限制。对于“version”（以及artifact的“extension”和“classifer”），Gradle将处理任何有效的Unicode字符。

唯一明确禁止使用的Unicode字符是“\”，“/”以及所有的ISO控制字符。这些提供的值会在发布之前进行验证。

65.2.4. 修改生成的 POM

有时候，从项目信息生成的POM文件可能需要在发布之前进行一些调整。“maven-publish”插件提供了一个钩子以允许这一类的修改。

示例 65.5. 修改 POM 文件

build.gradle

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

在这个例子中我们添加了一个用于生成的 POM 的“描述”元素。通过这个钩子，你可以修改 POM 的任何方面的内容。例如，你可以使用生产构建的实际版本号来替换依赖的版本范围。

相关的 API 参考文档，请参阅MavenPom.withXml() 。

如果有需要的话，你也可以修改所创建的POM的几乎任何方面的内容。这意味着，用这样的方式，可能会把这个POM修改为不再是有效的Maven Pom，所以必须谨慎使用这个功能。

已发布模块的标识符（groupId，artifac，version）则是一个例外；不能使用“withXML”钩子来修改POM中的这些值。

65.2.5. 发布多个模块

有时候从你的 Gradle 构建中发布多个模块会很有用，而不是创建一个单独的 Gradle 子项目。一个例子是为您的library 分别发布一个单独的 API 和它的实现的 jar。使用 Gradle 的话很简单︰

示例 65.6. 从一个单一的项目发布多个模块

build.gradle

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
            }
        }
    }

如果一个项目定义了多个要发布的内容，Gradle 将把每一个都发布到定义的仓库。如上文所述，每个发布的内容都必须给定一个唯一的标识。

65.3. 仓库

发布的内容都会被发布到仓库中用于发布的仓库是通过PublishingExtension.getRepositories()容器来定义的。

示例 65.7. 声明用于发布的仓库

build.gradle

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

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

65.4. 执行发布

对每一个在 publishing.publications 和 publishing.repositories 容器中分别组合的MavenPublication 和 MavenArtifactRepository，“maven-publish” 插件自动为它们创建了一个 PublishToMavenRepository 任务。

这个创建的任务使用“publish«PUBLICATION 名称»PublicationTo«REPOSITORY 名称»Repository”的方式来命名。

示例 65.8. 发布项目到 Maven 仓库

build.gradle

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的输出结果

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

BUILD SUCCESSFUL

Total time: 1 secs

因此，在下面的例子中，添加了一个 PublishToMavenRepository 任务，名字叫做“publishMavenJavaPublicationToMavenRepository”。这个任务会被连接到 publish 生命周期任务。执行gradle publish会构建 POM 文件和所有用于发布的构件，并将它们传输到仓库中。

65.5. 发布到Maven本地库

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

这个创建的任务使用“publish«PUBLICATION 名称»PublicationToMavenLocal”的方式来命名。

示例 65.9. 发布项目到 Maven 本地仓库

gradle publishToMavenLocal的输出结果

-> 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仓库中。

65.6. 不发布的情况下生成POM文件

有时候，我们会需要在实际 上不发布的情况下，生成一个模块的Maven POM文件。由于POM的生成是由一个单独的任务执行的，所以这很容易实现。

用于生成POM文件的这个任务，任务类型是 GenerateMavenPom，并且它被指定了一个基于发布名称的名字：“generatePomFileFor«PUBLICATION名称»Publication”。所以在下面的例子中，当发布的名称叫“mavenCustom”，那么这个任务的名称就会是“generatePomFileForMavenCustomPublication”。

示例 65.10. 不发布的情况下生成POM文件

build.gradle

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

gradle generatePomFileForMavenCustomPublication的输出结果

> gradle generatePomFileForMavenCustomPublication
:generatePomFileForMavenCustomPublication

BUILD SUCCESSFUL

Total time: 1 secs

发布模型的所有细节仍然要在 POM 生成中考虑，包括compon'，自定义artifacts，以及通过pom.withXml所做的任何修改。

“maven-publish”插件利用了后期插件配置的一些实验性的支持，并且在配置发布扩展之前，不会构造GenerateMavenPom任务。确保当你尝试访问GenerateMavenPom任务时发布插件已经配置好的最简单的方式是，将访问的代码放在publishing代码块中，如上面的例子中所示。

这同样适用于任何发布相关的任务的访问，比如PublishToMavenRepository。这些任务应该从publishing代码块内引用。