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

本文由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，你可以使用一个闭包。在上例中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中。

---

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