《gradle 用户指南》中文版第6章、Gradle包装器

2021-09-30 02:59:51

第6章、Gradle包装器

6.1、用包装器（Wrapper）执行构建6.2、将包装器添加到项目中6.3、配置6.4、经过认证的Gradle发行版下载6.5、验证已下载的Gradle发行版本6.6、Unix文件权限

大多数工具需要在计算机上安装才能使用它们。如果安装很容易，你可能会认为没关系。但是，构建用户可能会造成不必要的负担。同样重要的是，用户是否会为该版本安装正确版本的工具？如果他们正在构建旧版本的软件怎么办？Gradle 包装器（以下称为“Wrapper”）解决了这两个问题，并且是开始Gradle构建的首选方式。

6.1、用Wrapper执行构建

如果Gradle项目已经设置了Wrapper（并且我们建议所有项目都这样做），那么可以使用项目根目录中的以下命令执行构建：

./gradlew <task> (在类Unix平台上，如Linux和Mac OS X)
gradlew <task> (在Windows上使用gradlew.bat批处理文件)

每个Wrapper都绑定到一个特定版本的Gradle，所以当你为一个给定的Gradle版本首先运行上面的命令之一时，它会下载相应的Gradle分布并使用它来执行构建。集成开发环境通过其包装器导入Gradle项目时，您的IDE可能会要求使用Gradle'all'分发。这是非常好的，有助于IDE为构建文件提供代码完成。这不仅意味着您不必自己手动安装Gradle，而且您还可以使用该版本设计的Gradle版本。这使您的历史建设更可靠。只要在用户指南，堆栈溢出，文章或任何地方看到从gradle ...开始的命令行，请使用上述适当的语法。为了完整起见，为确保不删除任何重要的文件，这里是构成Wrapper的Gradle项目中的文件和目录：

gradlew (Unix Shell 脚本)
gradlew.bat (Windows 指处理文件)
gradle/wrapper/gradle-wrapper.jar (Wrapper JAR)
gradle/wrapper/gradle-wrapper.properties (Wrapper 属性)

如果您想知道Gradle发行版的存储位置，您可以在$ USER_HOME / .gradle / wrapper / dists的用户主目录中找到它们。
集成开发环境通过其包装器导入Gradle项目时，您的IDE可能会要求使用Gradle'all'分发。这是非常好的，有助于IDE为构建文件提供代码完成。

6.2、将包装器添加到项目中

Wrapper是你应该检查版本控制的东西。通过将Wrapper与您的项目分发，任何人都可以使用它，而无需事先安装Gradle。更好的是，构建的用户可以保证使用该版本设计使用的Gradle版本。当然，这对于持续集成服务器（即定期构建项目的服务器）也是非常好的，因为它不需要服务器上的配置。

您可以通过运行包装任务将Wrapper安装到项目中。（此任务始终可用，即使您不将其添加到构建中）。要指定Gradle版本，请在命令行中使用--gradle-version。默认情况下，Wrapper将使用bin分配。这是最小的Gradle分布。一些工具，如Android Studio和Intellij IDEA，在与所有发行版一起使用时提供附加的上下文信息。您可以使用--distribution-type选择不同的Gradle分发类型。您还可以通过--gradle-distribution-url直接设置下载Gradle的URL。如果没有指定版本或分发URL，Wrapper将被配置为使用包装器任务执行的gradle版本。因此，如果您使用Gradle 2.4运行包装任务，则Wrapper配置将默认为2.4版。
例6.1。运行包装器任务gradle wrapper --gradle-version 2.0 命令输出：

> gradle wrapper --gradle-version 2.0
:wrapper

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

通过在构建脚本中添加和配置Wrapper任务，然后执行Wrapper任务，可以进一步定制包装器。
例6.2。包装器任务build.gradle

task wrapper(type: Wrapper) {
    gradleVersion = '2.0'
}

执行此操作后，您可以在项目目录中找到以下新的或更新的文件（如果使用了Wrapper任务的默认配置）。
例6.3。包装器生成的文件构建布局

simple/
  gradlew
  gradlew.bat
  gradle/wrapper/
    gradle-wrapper.jar
    gradle-wrapper.properties

所有这些文件都应该提交到版本控制系统。这只需要做一次。将这些文件添加到项目之后，然后使用添加的gradlew命令构建项目。 gradlew命令可以与gradle命令完全相同的方式使用。如果要切换到新版本的Gradle，则无需重新运行包装器任务。在gradlewrwrper.properties文件中更改相应条目是非常好的，但如果要在Gradle包装器中使用新功能，则需要重新生成包装器文件。

6.3、配置

如果您使用Gradle运行Gradle，Wrapper将检查Wrapper的Gradle分布是否可用。如果是这样，它将通过原来传递给gradlew命令的所有参数委派给该分发的gradle命令。如果没有找到Gradle发行版，它将首先下载。配置Wrapper任务时，可以指定要使用的Gradle版本。 gradlew命令将从Gradle存储库下载相应的分发。或者，您可以指定Gradle发行版的下载URL。 gradlew命令将使用此URL下载分发。如果您既没指定了Gradle版本也没有指定下载URL，则gradlew命令将下载用于生成Wrapper文件的Gradle版本。
有关如何配置Wrapper的详细信息，请参阅API文档中的Wrapper类。如果您不想通过逐步构建项目进行任何下载，只需在您的Wrapper配置指定的位置将Gradle发行版zip添加到您的版本控制。支持相对URL - 您可以指定相对于gradle-wrapper.properties文件位置的分发文件。如果您通过Wrapper构建，则会忽略计算机上安装的任何现有的Gradle发行版。

6.4、经过认证的Gradle发行版下载

Gradle Wrapper可以使用HTTP基本身份验证从服务器下载Gradle发行版。这使您能够在私有受保护的服务器上托管Gradle分发。您可以根据用例以两种不同的方式指定用户名和密码：作为系统属性或直接嵌入在distributionUrl中。系统属性中的凭证优先于在distributionUrl中嵌入的凭据。使用系统属性可以在用户主目录中的.gradle / gradle.properties文件中完成，或者通过其他方法，请参见第12.1节“通过gradle.properties配置构建环境”。例6.4。使用系统属性指定HTTP基本身份验证凭据gradle.properties

systemProp.gradle.wrapperUser=username
systemProp.gradle.wrapperPassword=password

在gradle / wrapper / gradle-wrapper.properties文件中的distributionUrl中嵌入凭据也可以。请注意，该文件将被提交到您的源代码管理系统。只有在受控环境中才能使用共享凭据嵌入在distributionUrl中。例6.5。在distributionUrl中指定HTTP基本身份验证凭据gradle-wrapper.properties

distributionUrl=https://username:password@somehost/path/to/gradle-distribution.zip

这可以与代理结合使用，经过身份验证。有关如何将Wrapper配置为使用代理的详细信息，请参见第12.3节“通过代理访问Web”。

6.5、验证已下载的Gradle发行版本

Gradle Wrapper允许通过SHA-256散列和比较验证下载的Gradle分布。通过防止中间人攻击者篡改下载的Gradle发行版，从而增强了针对目标攻击的安全性。要启用此功能，您需要首先计算已知Gradle分布的SHA-256散列。您可以通过shasum命令从Linux和OSX或Windows（通过Cygwin）生成SHA-256散列。例6.6。生成SHA-256哈希

> shasum -a 256 gradle-2.4-all.zip
371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10  gradle-2.4-all.zip

使用distributionSha256Sum属性将返回的散列和添加到gradle-wrapper.properties。例6.7。配置SHA-256校验和验证
gradle-wrapper.properties

distributionSha256Sum=371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10

6.6、Unix文件权限

Wrapper任务添加适当的文件权限以允许执行gradlew * NIX命令。 Subversion保留此文件权限。我们不知道其他版本控制系统如何处理这个问题。应该总是奏效的是执行“sh gradlew”。
原文：https://docs.gradle.org/current/userguide/gradle_wrapper.html

码农公寓