Gradle 1.12用户指南翻译——第五十三章. 签名插件

其他章节的翻译请参见：
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/54292923

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

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

第五十三章. 签名插件

签名插件添加了对构件的文件和artifacts进行数字签名的功能。这些数字签名可以用于证明使用这个签名的artifact是谁构建的，以及其他的信息，比如签名是什么时候生成的。

签名插件目前只提供了生成PGP 签名的支持（这是发布到Maven 中央库所需的签名格式）。

53.1. 用法

要使用 Signing 插件，请在构建脚本中包含以下语句：

示例 53.1. 使用Signing插件

build.gradle

apply plugin: 'signing'

53.2. 签名凭证

为了创建 PGP 签名，你将需要一个密钥对（有关使用GnuPG 工具创建密钥对的介绍可以在GnuPG Howto中找到）。您需要向签名插件提供你的关键信息，即如下三项信息：

• 公钥 ID （一个8位字符的十六进制字符串）。

• 指向包含了你的私钥的密钥环文件的绝对路径。

• 用来保护你的私钥的密码。

这些条目必须分别作为属性项目signing.keyId、 signing.password和signing.secretKeyRingFile 进行提供。鉴于这些值的个人和私人性质，一个好的做法是将它们保存在用户的gradle.properties文件（第14.2 节，“Gradle 属性和系统属性”中所述）。

signing.keyId=24875D73
signing.password=secret
signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg

如果在用户的gradle.properties文件中指定的信息不适合你的环境，你可以提供这些信息，但你需要手动设置项目的属性。

import org.gradle.plugins.signing.Sign

gradle.taskGraph.whenReady { taskGraph ->
    if (taskGraph.allTasks.any { it instanceof Sign }) {
        // Use Java 6's console to read from the console (no good for a CI environment)
        Console console = System.console()
        console.printf "\n\nWe have to sign some things in this build.\n\nPlease enter your signing details.\n\n"

        def id = console.readLine("PGP Key Id: ")
        def file = console.readLine("PGP Secret Key Ring File (absolute path): ")
        def password = console.readPassword("PGP Private Key Password: ")

        allprojects { ext."signing.keyId" = id }
        allprojects { ext."signing.secretKeyRingFile" = file }
        allprojects { ext."signing.password" = password }

        console.printf "\nThanks.\n\n"
    }
}

53.3. 指定要签名的内容

除了配置内容要如何签名（即签名配置），你还必须指定哪些文件要签名。Signing 插件提供了一个DSL，它允许你指定应签名的任务及配置。

53.3.1. 签名配置

签名一个配置的artifacts是很常见的情况。例如， Java 插件配置了构建一个jar文件，并且把 jar 文件添加到archives配置。使用Signing DSL，你可以指定这个配置的所有 artifacts 都应该被签名。

53.3.2. 签名一个配置

build.gradle

signing {
    sign configurations.archives
}

这将在你的项目中创建一个名为“signArchives”的任务（Sign类型），这个任务会构建任何archives的artifacts（如果需要），然后为它们生成签名。签名文件将和被签名的artifacts放在一起。

示例 53.3. 签署一个配置的输出

gradle signArchives的输出结果

> gradle signArchives
:compileJava
:processResources
:classes
:jar
:signArchives

BUILD SUCCESSFUL

Total time: 1 secs

53.3.2. 签名任务

在某些情况下，你需要签名的artifact 可能不是配置的一部分。在这种情况下，你可以直接签名生成了要签名的artifact 的任务。

53.4. 签名一个任务

build.gradle

task stuffZip (type: Zip) {
    baseName = "stuff"
    from "src/stuff"
}

signing {
    sign stuffZip
}

这将在您的项目创建一个名为“signStuffZip”的（Sign类型） 的任务，这个任务会构建输入任务的archive（如果需要），并进行签字。签名文件将和被签名的 artifact 放在一起。

示例 53.5. 签名一个任务的输出

gradle signStuffZip的输出结果

> gradle signStuffZip
:stuffZip
:signStuffZip

BUILD SUCCESSFUL

Total time: 1 secs

一个“可签名”的任务，必须输出某种类型的archive。这样的任务有 Tar， Zip， Jar， War 及 Ear任务。

53.3.3. 有条件的签名

常见的使用模式是只在一定条件下签名构建的artifacts。例如，你可能不想对非发布版本签名artifacts。要做到这一点，你可以指定只在一定条件下才要求签名。

53.6. 有条件的签名

build.gradle

version = '1.0-SNAPSHOT'
ext.isReleaseVersion = !version.endsWith("SNAPSHOT")

signing {
    required { isReleaseVersion && gradle.taskGraph.hasTask("uploadArchives") }
    sign configurations.archives
}

在此示例中，我们只想要在我们构建一个我们即将去发布的发布版本的时候，才进行签名。由于我们正在检查任务图，以确定是否打算发布，我们必须将signing.required属性设置为一个闭包以推迟evaluation。更多的信息，请参阅SigningExtension.setRequired()。

53.4. 发布签名

当通过 Signing DSL指定什么要被签名的时候，生成的signature会自动地加入到 signatures 和 archives 的依赖配置中。这意味着，如果你想要将你的签名以及artifacts上传到你的分布仓库中，正常来讲你只需要执行uploadArchives任务。

53.5. 签名 POM 文件

当为你的artifacts部署签名到 Maven 仓库时，你还想签名发布的 POM 文件。签名插件添加了一个signing.signPom() （请参见： SigningExtension.signPom()）方法，这个方法可以在你的上传任务配置的beforeDeployment()块中使用。

示例 53.7. 为部署签名 POM

build.gradle

uploadArchives {
    repositories {
        mavenDeployer {
            beforeDeployment { MavenDeployment deployment -> signing.signPom(deployment) }
        }
    }
}

当不需要签名，以及由于缺少配置（即没有签名证书）而不能签名 POM 的时候，signPom()方法将什么都不会做，并且不会进行任何的提示。