本文由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) |
|
生成的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,你可以使用一个闭包。在上例中repository和authentication都是这样的 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.4. 配置 MavenDeployer 的元素
元素 | Javadoc |
root | MavenDeployer |
repository | org.apache.maven.artifact.ant.RemoteRepository |
authentication | org.apache.maven.artifact.ant.Authentication |
releases | org.apache.maven.artifact.ant.RepositoryPolicy |
snapshots | org.apache.maven.artifact.ant.RepositoryPolicy |
proxy | org.apache.maven.artifact.ant.Proxy |
snapshotRepository | org.apache.maven.artifact.ant.RemoteRepository |
52.6.3. 安装到本地仓库
Maven 插件将install
任务添加到你的项目。这个任务依赖于archives
配置的所有archives任务。它将这些archives安装到你的本地 Maven 仓库中。本地仓库的默认位置是否在 Maven settings.xml
中被重新定义,这项任务也会考虑到。
52.6.4. Maven POM 生成
当部署一个artifact 到一个 Maven 库时,Gradle 会自动为它生成一个POM。下表展示了用于POM的groupId
,artifactId
,version
和packaging
元素的默认值。这些dependency
元素由project 的依赖声明所创建。
表 52.5. Maven POM 生成的默认值
Maven 元素 | 默认值 |
groupId | project.group |
artifactId | uploadTask.repositories.mavenDeployer.pom.artifactId(如果有设置的话)或archiveTask.baseName. |
version | project.version |
packaging | archiveTask.extension |
在这里, uploadTask
和archiveTask
分别指向上传和分别生成archive的任务(例如uploadArchives
和jar
)。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' } } } } } }
注:groupId
,artifactId
,version
和packaging
应该始终直接在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中。