Gradle 1.12用户指南翻译——第五十二章. Maven 插件

时间:2022-11-08 09:16:57
本文由CSDN博客貌似掉线翻译,其他章节的翻译请参见:
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.5版本兼容 Android 2.3以上系统,项目地址如下:
https://github.com/msdx/gradle-doc-apk
翻译不易,转载请注明本文在CSDN博客上的出处:
http://blog.csdn.net/maosidiaoxian/article/details/53749725

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

另外,目前Gradle1.12版本的文档我电脑上已经翻译到第六十三章,所以该版本的翻译也进入校稿阶段,校稿的方式可以为到该项目https://github.com/msdx/gradledoc 提交issue或者是pull request。校稿的结果不只是在此版本更新,也会用于改善Gradle下一版本(2.0)文档的翻译。


第五十二章. Maven 插件

此章节还在完善中。

Maven 插件添加了将项目部署到 Maven 仓库的支持。

52.1. 用法

要使用 Maven 插件,请在构建脚本中包含以下语句:

示例 52.1. 使用 Maven 插件

build.gradle

apply plugin: 'maven'

52.2. 任务

Maven 插件定义了以下任务:

表 52.1. Maven 插件 - 任务

任务名称 依赖于 类型 描述
install 所有构建相关archives的任务。 Upload 将相关的构件安装到本地的 Maven 缓存,包括 Maven 元数据的生成。默认情况下 install 任务是与archives配置相关联的。该项配置在默认情况下只包含默认的 jar 文件。要了解更多关于安装到本地资源库的内容,请参阅:第 52.6.3 节,“安装到本地仓库”

52.3. 依赖管理

Maven 插件不定义任何依赖配置。

52.4. 约定属性

Maven 插件定义了下列约定属性:

表 52.2. Maven 插件 - 属性

属性名称 类型 默认值 描述
pomDirName String poms 相对于构建目录,用于写入生成的POM的文件夹路径。
pomDir File (read-only) buildDir/pomDirName 生成的POM所写入的目录。
conf2ScopeMappings Conf2ScopeMappingContainer n/a 将Gradle配置映射到Maven scopes的说明。见 52.6.4.2 节,“依赖映射”

这些属性由一个MavenPluginConvention 的约定对象提供。

52.5. 约定方法

Maven 插件提供了用于创建 POM 的工厂方法,如果你需要一个 POM 文件但是没有上传到 Maven 仓库的场景,这个工厂方法将非常有用。

示例 52.2. 创建一个单独的 pom。

build.gradle

task writeNewPom << {    pom {        project            inceptionYear '2008'            licenses {                license {                    name 'The Apache Software License, Version 2.0'                    url 'http://www.apache.org/licenses/LICENSE-2.0.txt'                    distribution 'repo'                }            }        }    }.writeTo("$buildDir/newpom.xml")}

除其他事项外,Gradle支持和polyglot Maven同样的生成器语法。如果要了解关于 Gradle Maven POM 对象的更多信息,请参阅MavenPom。请参见: MavenPluginConvention

52.6. 与 Maven 仓库的交互

52.6.1. 介绍

通过 Gradle你可以部署到远程 Maven 仓库,或者是安装到你的本地 Maven 仓库。这包括所有的 Maven 元数据操纵,并且 Maven snapshot一样可用。事实上,Gradle 的部署是 100%兼容 Maven的,因为我们在hood下使用的是本地的 Maven Ant 任务。

如果你没有一个POM文件,部署到 Maven 仓库只有一半的乐趣。幸运的是 Gradle 可以使用它的依赖信息为你生成这个 POM。

52.6.2. 部署到 Maven 仓库

让我们假设你的项目只是产生默认的 jar 文件。现在你想要将这个 jar 文件部署到远程 Maven 仓库。

示例 52.3. 上传文件到远程 Maven 仓库

build.gradle

apply plugin: 'maven'uploadArchives {    repositories {        mavenDeployer {            repository(url: "file://localhost/tmp/myRepo/")        }    }}

就这些了。调用uploadArchives任务将生成 POM,并将部署构件和 POM 到指定的仓库。

如果你需要支持文件之外的其他协议,那么你还需要再做一些事情。在这种情况下,我们必须将委派本地的Maven代码给第三方库实现。具体是哪些库,将取决于你需要的协议。表 52.3. “Maven 部署的协议jar”列出了可用的协议以及相应的库(这些库又有具有传递依赖,而这些依赖也有其自己的传递依赖)。[19] 举个例子,要使用ssh协议,你可以:

示例 52.4. 通过 SSH 上传文件

build.gradle

configurations {    deployerJars}repositories {    mavenCentral()}dependencies {    deployerJars "org.apache.maven.wagon:wagon-ssh:2.2"}uploadArchives {    repositories.mavenDeployer {        configuration = configurations.deployerJars        repository(url: "scp://repos.mycompany.com/releases") {            authentication(userName: "me", password: "myPassword")        }    }}

Maven deployer有很多配置选项。这个配置通过一个 Groovy builder 来完成。这个配置树的所有元素都是 Java beans。你可以传一个map到bean元素中,来配置简单的属性。如果要添加另一个bean元素到它的parent,你可以使用一个闭包。在上例中repositoryauthentication都是这样的 bean 元素。表 52.4,"MavenDeployer 的配置元素"列出了可用的 bean 元素,以及 javadoc 中相应类的链接。在javadoc 中你可以看到可能的属性,这些属性你可以设置为特定的元素。

在 Maven 中你可以定义仓库和snapshot仓库。如果没有定义任何snapshot 仓库,release和snapshot都将部署到repository元素中。否则,snapshots将部署到snapshotRepository元素中。

表 52.3. Maven 部署的协议 jars

协议 Library
http org.apache.maven.wagon:wagon-http:2.2
ssh org.apache.maven.wagon:wagon-ssh:2.2
ssh-external org.apache.maven.wagon:wagon-ssh-external:2.2
ftp org.apache.maven.wagon:wagon-ftp:2.2
webdav org.apache.maven.wagon:wagon-webdav:1.0-beta-2
file -

52.6.3. 安装到本地仓库

Maven 插件将install任务添加到你的项目。这个任务依赖于archives配置的所有archives任务。它将这些archives安装到你的本地 Maven 仓库中。本地仓库的默认位置是否在 Maven settings.xml中被重新定义,这项任务也会考虑到。

52.6.4. Maven POM 生成

当部署一个artifact 到一个 Maven 库时,Gradle 会自动为它生成一个POM。下表展示了用于POM的groupIdartifactIdversionpackaging元素的默认值。这些dependency元素由project 的依赖声明所创建。

表 52.5. Maven POM 生成的默认值

Maven 元素 默认值
groupId project.group
artifactId uploadTask.repositories.mavenDeployer.pom.artifactId(如果有设置的话)或archiveTask.baseName.
version project.version
packaging archiveTask.extension

在这里, uploadTaskarchiveTask分别指向上传和分别生成archive的任务(例如uploadArchivesjar)。archiveTask.baseName默认为project.archivesBaseName,后者默认为project.name

当你将archiveTask.baseName设置为非默认值时,请确保将uploadTask.repositories.mavenDeployer.pom.artifactId设置为相同的值。否则,在相同的构建中,这个项目可能会被其他项目所生成的POMs 中错误的 artifact ID所引用到。

生成的 POMs 可以在<buildDir>/poms看到。它们可以通过MavenPom API 进一步定制化。例如,你可能希望部署到 Maven 仓库中的artifact 有不同的版本,或者是不同于 Gradle 生成的artifact 的名称。如果要自定义这些你可以这样做:

示例 52.5. pom定制

build.gradle

uploadArchives {    repositories {        mavenDeployer {            repository(url: "file://localhost/tmp/myRepo/")            pom.version = '1.0Maven'            pom.artifactId = 'myMavenName'        }    }}

如果要向 POM 添加其他的内容,可以使用pom.project 生成器。通过这个生成器,Maven POM 参考中列出的任何元素都可以被添加进来。

示例 52.6. pom 的生成器类型自定义

build.gradle

uploadArchives {    repositories {        mavenDeployer {            repository(url: "file://localhost/tmp/myRepo/")            pom.project {                licenses {                    license {                        name 'The Apache Software License, Version 2.0'                        url 'http://www.apache.org/licenses/LICENSE-2.0.txt'                        distribution 'repo'                    }                }            }        }    }}

注:groupIdartifactIdversionpackaging应该始终直接在pom对象上设置。

示例 52.7. 修改自动生成的内容

build.gradle

[installer, deployer]*.pom*.whenConfigured {pom ->    pom.dependencies.find {dep -> dep.groupId == 'group3' && dep.artifactId == 'runtime' }.optional = true}

如果你有超过一个的artifact 要发布,那么要做的事情就会有些不同。请参阅第 52.6.4.1 节,“一个项目多个构件”

要为 Maven installer(见第 52.6.3 条,“安装到本地资源库”) 自定义设置,你可以:

示例 52.8. Maven installer 的自定义

build.gradle

install {    repositories.mavenInstaller {        pom.version = '1.0Maven'        pom.artifactId = 'myName'    }}

52.6.4.1. 一个项目多个构件

Maven 只可以处理一个项目一个构件。这也反映在 Maven POM 的结构中。我们认为在很多情况下,有意义一个项目有超多一个的构件。在这种情况下,你需要生成多个 POMs。在这种情况下,你必须显式声明你想要发布到一个 Maven 仓库的每一个构件。MavenDeployer和 MavenInstaller 都为此提供了一个 API:

示例 52.9. 多个 poms 的生成

build.gradle

uploadArchives {    repositories {        mavenDeployer {            repository(url: "file://localhost/tmp/myRepo/")            addFilter('api') {artifact, file ->                artifact.name == 'api'            }            addFilter('service') {artifact, file ->                artifact.name == 'service'            }            pom('api').version = 'mySpecialMavenVersion'        }    }}

你需要为你想发布的每一个构件声明一个过滤器。这个过滤器为每一个它接受的 Gradle 构件定义了一个布尔表达式。每个过滤器都有一个你可以进行配置的POM与它关联。要了解更多关于它的信息,你可以看一下PomFilterContainer和其关联的类。

52.6.4.2. 依赖映射

Maven 插件配置了由Java插件和War插件添加的Gradle configurations 与Maven scopes之间的默认映射。大多数情况下你不需要去接触它,并且你可以安全地跳过本节。映射过程像下面所示。你可以把一个configuration映射到一个并且只能是一个scope上。不同的configurations可以映射到一个或不同的scopes。一个configuration可以指定到一个特定的 configuration-to-scope 映射的优先级。你可以参考Conf2ScopeMappingContainer来了解更多的信息。要访问映射配置,你可以:

示例 52.10. 访问映射配置

build.gradle

task mappings << {    println conf2ScopeMappings.mappings}

如果有可能,Gradle排除的规则会被转换为Maven excludes。如果 Gradle 排除规则中group和module名字被指定的话(相比于Ivy,Maven对这两个都需要),这种转换是可能的。每一个configuration的排除规则如果可以被转换的话,也会包含在Maven POM中。



[19已经计划在将来的发行版中为其提供开箱即用的支持。