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:publishBUILD SUCCESSFULTotal 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:publishBUILD SUCCESSFULTotal 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:generatePomFileForMavenCustomPublicationBUILD SUCCESSFULTotal time: 1 secs

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

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

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