【Gradle Build Tool 4.1用户指南】Chapter 6.The Gradle Wrapper

Most tools require installation on your computer before you can use them. If the installation is easy, you may think that’s fine. But it can be an unnecessary burden on the users of the build. Equally importantly, will the user install the right version of the tool for the build? What if they’re building an old version of the software?

很多工具都需要安装才可以使用。如果安装很容易，你会觉得这没什么。但对构建的用户来说，这是多余的。同样重要的是，用户是否为构建安装了工具的正确版本？如果他们用旧版本来构建软件怎么办？

The Gradle Wrapper (henceforth referred to as the “Wrapper”) solves both these problems and is the preferred way of starting a Gradle build.

Gradle Wrapper （以下简称“Wrapper”）解决了这两个问题，而且它是开始Gradle构建的首选。

6.1 Executing a build with the Wrapper

6.1 使用wrapper来执行构建

If a Gradle project has set up the Wrapper (and we recommend all projects do so), you can execute the build using one of the following commands from the root of the project:

如果一个Gradle项目设置了Wrapper（并且我们要求所有的项目都这样做），您可以在项目的根目录使用下面的命令来执行构建：

• ./gradlew <task> (on Unix-like platforms such as Linux and Mac OS X)
• gradlew <task> (on Windows using the gradlew.bat batch file)

 

Each Wrapper is tied to a specific version of Gradle, so when you first run one of the commands above for a given Gradle version, it will download the corresponding Gradle distribution and use it to execute the build.

每一个wrapper都绑定一特定版本的Gradle，所以当你为一个给定的Gradle版本第一次运行上面的命令时，它会下载相应的Gradle版本来执行构建。

 

Not only does this mean that you don’t have to manually install Gradle yourself, but you are also sure to use the version of Gradle that the build is designed for. This makes your historical builds more reliable. Just use the appropriate syntax from above whenever you see a command line starting with gradle ... in the user guide, on Stack Overflow, in articles or wherever.

这不仅仅意味着你不需要手动去安装Gradle，还确保了使用到符合构建需要的Gradle版本。这会让你以往的构建更加可靠。每当你看到一个以gradle...开头的命令行，只需要使用在用户指南中的或Stack Overflow的或某个文章中的或其他任何地方中的适当的语法。

For completeness sake, and to ensure you don’t delete any important files, here are the files and directories in a Gradle project that make up the Wrapper:

为了安全起见，和确保你不会删除任何的重要文件，下面是在一个Gradle项目中组成wrapper的文件和文件夹：

• gradlew (Unix Shell script)
• gradlew.bat (Windows batch file)
• gradle/wrapper/gradle-wrapper.jar (Wrapper JAR)
• gradle/wrapper/gradle-wrapper.properties (Wrapper properties)

If you’re wondering where the Gradle distributions are stored, you’ll find them in your user home directory under $USER_HOME/.gradle/wrapper/dists.

如果你好奇Gradle分布在哪里存储，你会发现他们在你的用户目录$USER_HOME/.gradle/wrapper/dists下

 

IDEs

When importing a Gradle project via its wrapper, your IDE may ask to use the Gradle 'all' distribution. This is perfectly fine and helps the IDE provide code completion for the build files.

当通过Gradle的wrapper来导入Gradle项目，你的IDE可能要求使用Gradle所有的分布。这是非常好的，有助于IDE为生成文件完善代码。

 

6.2. Adding the Wrapper to a project

添加Wrapper到项目中

The Wrapper is something you should check into version control. By distributing the Wrapper with your project, anyone can work with it without needing to install Gradle beforehand. Even better, users of the build are guaranteed to use the version of Gradle that the build was designed to work with. Of course, this is also great for continuous integration servers (i.e. servers that regularly build your project) as it requires no configuration on the server.

Wrapper是一个你需要检查版本控制的东西。通过分配Wrapper到你的项目中，任何人都可以不事先安装Gradle就可以使用它。甚至，确保用户使用到了需要的Gradle版本。当然，这对持续集成服务器（即定期构建项目的服务器）来说也是很好的，因为它不需要服务器的配置。

 

You install the Wrapper into your project by running the wrapper task. (This task is always available, even if you don’t add it to your build). To specify a Gradle version use --gradle-version on the command-line. By default, the Wrapper will use a bin distribution. This is the smallest Gradle distribution. Some tools, like Android Studio and Intellij IDEA, provide additional context information when used with the all distribution. You may select a different Gradle distribution type by using --distribution-type. You can also set the URL to download Gradle from directly via --gradle-distribution-url. If no version or distribution URL is specified, the Wrapper will be configured to use the gradle version the wrapper task is executed with. So if you run the wrapper task with Gradle 2.4, then the Wrapper configuration will default to version 2.4.

通过运行wrapper任务将Wrapper安装到你的项目中。（这个任务总是可用的，即使你不把它添加到你的构建中）。在命令行使用--gradle-version指定Gradle版本。默认情况下，该wrapper将使用bin发布版本。这是最小的Gradle发布版本。有一些工具，像Android studio和intelliJ IDEA，当使用所有的发布版本的时候，会提供附加的上下文信息。你可以使用--distribution-type来选择不同的分布版本。你还可以直接通过--gradle-distribution-url来设置下载Gradle的URL。如果没有指定的版本或发布URL，wrapper将使用wrapper任务所使用的gradle版本。所以，如果你用Gradle2.4运行wrapper任务，wrapper配置将默认为版本2.4。

 

Example 6.1. Running the Wrapper task

例6.1：运行wrapper任务

Output of gradle wrapper --gradle-version 2.0

> gradle wrapper --gradle-version 2.0:wrapperBUILD SUCCESSFUL in 0s1 actionable task: 1 executed

The Wrapper can be further customized by adding and configuring a Wrapper task in your build script, and then executing it.

可以在你的构建脚本中添加和配置wrapper任务，来进一步定制wrapper，然后执行它。

 

Example 6.2. Wrapper task

例 6.2. wrapper任务

build.gradle

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

After such an execution you find the following new or updated files in your project directory (in case the default configuration of the Wrapper task is used).

执行此操作后，你将会在工程目录里面发现新的或者更新过的文件（如果使用wrapper任务的默认配置）。

 

Example 6.3. Wrapper generated files

例6.3 wrapper发生器文件

Build layout

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

All of these files should be submitted to your version control system. This only needs to be done once. After these files have been added to the project, the project should then be built with the added gradlew command. The gradlew command can be used exactly the same way as the gradle command.

所有这些文件都应该提交到你的版本控制系统。这仅仅需要执行一次。在这些文件被添加到项目之后，项目应使用被添加的gradlew命令来执行。Gradlew命令可以用与gradle一样的方法来使用。

If you want to switch to a new version of Gradle you don’t need to rerun the wrapper task. It is good enough to change the respective entry in the gradle-wrapper.properties file, but if you want to take advantage of new functionality in the Gradle wrapper, then you would need to regenerate the wrapper files.

如果你想切换到一个新的Gradle版本，你不需要重新执行wrapper任务。在gradle-wrapper.properties文件中可以改变各个版本的切入，但如果体验wrapper的新功能的优势，你需要重新生成wrapper文件。

 

6.3. Configuration

6.3 配置

If you run Gradle with gradlew, the Wrapper checks if a Gradle distribution for the Wrapper is available. If so, it delegates to the gradle command of this distribution with all the arguments passed originally to the gradlew command. If it didn’t find a Gradle distribution, it will download it first.

如果你使用gradlew运行gradle，wrapper会检查是否wrappe对应的gradle发布版本是可用的。如果是可用的，这意味者，这个分布版本的最初的gradle命令带着所有的参数传递到了gradlew命令。如果没有发现任何一个gradle分布版本，它会先进行下载。

When you configure the Wrapper task, you can specify the Gradle version you wish to use. The gradlew command will download the appropriate distribution from the Gradle repository. Alternatively, you can specify the download URL of the Gradle distribution. The gradlew command will use this URL to download the distribution. If you specified neither a Gradle version nor download URL, the gradlew command will download whichever version of Gradle was used to generate the Wrapper files.

在你配置wrapper任务的时候，你可以指定想要使用的Gradle版本。Gradlew命令会从gradle仓库下载最合适的发布版本。不然，你可以指定gradle发布版本的下载URL。Gradlew命令会使用这个URL去下载。如果你没有指定一个gradle版本或下载URL，gradlew命令将下载，用来生成wrapper文件的gradle版本。

For the details on how to configure the Wrapper, see the Wrapper class in the API documentation.

如何配置wrapper的详细信息，见API文档中的wrapper类。

If you don’t want any download to happen when your project is built via gradlew, simply add the Gradle distribution zip to your version control at the location specified by your Wrapper configuration. A relative URL is supported - you can specify a distribution file relative to the location of gradle-wrapper.properties file.

当你的工程通过gradlew来构建的时候，你不想有任何的下载。只需要添加Gradle发布版本压缩包到wrapper配置路径下的版本控制。支持相近URL-可以在gradle-wrapper.properties文件的相对路径下指定一个发布版本。

If you build via the Wrapper, any existing Gradle distribution installed on the machine is ignored.

如果你通过wrapper来构建，任何已经安装的发布版本会被忽略。

 

6.4. Authenticated Gradle distribution download

6.4 认证下载Gradle发布版本

The Gradle Wrapper can download Gradle distributions from servers using HTTP Basic Authentication. This enables you to host the Gradle distribution on a private protected server. You can specify a username and password in two different ways depending on your use case: as system properties or directly embedded in the distributionUrl. Credentials in system properties take precedence over the ones embedded in distributionUrl.

Gradle wrapper可以使用HTTP基本认证服务从服务器下载Gradle发布版本。这使你可以访问一个私人受保护的服务器。你可以以两种不同的方式指定一个用户名和密码，这取决于你的使用情况：系统属性或者直接嵌入到distributionUrl。系统属性的证书优先于嵌入到distributionUrl中的。

 

Using system properties can be done in the .gradle/gradle.properties file in the user’s home directory, or by other means, see Section 12.1, “Configuring the build environment via gradle.properties”.

可以在用户home目录下的.gradle/gradle.properties文件中使用系统属性，或者使用其他方法，见第12.1节，“通过gradle.properties配置构建环境”

 

Example 6.4. Specifying the HTTP Basic Authentication credentials using system properties

例6.4 使用系统属性指定HTTP基本身份验证证书

gradle.properties.

systemProp.gradle.wrapperUser=usernamesystemProp.gradle.wrapperPassword=password

Embedding credentials in the distributionUrl in the gradle/wrapper/gradle-wrapper.properties file also works. Please note that this file is to be committed into your source control system. Shared credentials embedded in distributionUrl should only be used in a controlled environment.在gradle/wrapper/gradle-wrapper.properties文件中嵌入证书到distributionUrl也是可行的。请注意这个文件是要推送到你的源码控制系统中的。被分享的嵌入到distributionUrl的证书应该只在被控制环境中被使用。

 

Example 6.5. Specifying the HTTP Basic Authentication credentials in distributionUrl

例 6.5 在distributionUrl中指定HTTP基本认证证书

gradle-wrapper.properties. 

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

This can be used in conjunction with a proxy, authenticated or not. See Section 12.3, “Accessing the web via a proxy” for more information on how to configure the Wrapper to use a proxy.

这可以和也可以不和一个代理，认证一起使用。更多关于如何配置wrapper使用代理的详情，见第12.3节，“通过代理访问网站”。

Security Warning

HTTP Basic Authentication should only be used with HTTPS URLs and not plain HTTP ones. With Basic Authentication, the user credentials are sent in clear text.

安全警告

HTTP基本认证只应使用HTTPs链接而不是普通的HTTP。使用基本认证，用户证书将以明文发送。

6.5. Verification of downloaded Gradle distributions

6.5 验证下载的Gradle发布版本

The Gradle Wrapper allows for verification of the downloaded Gradle distribution via SHA-256 hash sum comparison. This increases security against targeted attacks by preventing a man-in-the-middle attacker from tampering with the downloaded Gradle distribution.

Gradle Wrapper允许通过SHA-256哈希散列算法对下载的Gradle分布版本进行验证。这提高了安全性，防止中间人通过篡改下载的Gradle发布版本进行有针对性的攻击。

To enable this feature you’ll want to first calculate the SHA-256 hash of a known Gradle distribution. You can generate a SHA-256 hash from Linux and OSX or Windows (via Cygwin) with the shasum command.

要启用这个功能，你会首先想要计算一个已经Gradle发布版本的SHA-256散列值。可以使用shasum命令从Linux和OSX或Windows（通过Cygwin生成一个SHA-256散列值。

 

Example 6.6. Generating a SHA-256 hash

例6.6 生成一个SHA-256散列值

> shasum -a 256 gradle-2.4-all.zip371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10  gradle-2.4-all.zip

Add the returned hash sum to the gradle-wrapper.properties using the distributionSha256Sum property.

使用distributionSha256Sum属性添加返回的散列值到gradle-wrapper.properties。

 

Example 6.7. Configuring SHA-256 checksum verification

例6.7 配置SHA-256 checksum认证

gradle-wrapper.properties. 

distributionSha256Sum=371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10

6.6. Unix file permissions

6.6 Unix文件权限

The Wrapper task adds appropriate file permissions to allow the execution of the gradlew *NIX command. Subversion preserves this file permission. We are not sure how other version control systems deal with this. What should always work is to execute “sh gradlew”.

Wrapper任务添加了适当的文件权限来允许gradlew *NIX命令的执行。低版本保留了这些文件权限。我们不确定其他版本控制系统是怎么处理这些的，一致都是执行“sh gradlew”。