第五章. Gradle 包装器

如果 Gradle 项目已经设置好 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，因此当你首次为给定的 Gradle 版本运行上面的命令时，它将下载相应的 Gradle 发行版并使用它来执行构建。
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.

这不仅意味着你不必自己手动安装 Gradle，而且还可以确保使用构建所针对的 Gradle 版本。这使你的历史构建更加可靠。当你在用户指南、Stack Overflow、一些文章或其他任何地方看到以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 项目中构成 Wrapper 的文件和目录：
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 发行包的存储位置，你可以在用户主目录 $USER_HOME/.gradle/wrapper/dists 下找到它们。
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 的情况下使用它。更好的效果是能确保用户使用这个构建所设计的 Gradle 版本。当然，这对于 连续集成 服务器（即定期构建项目的服务器）也很重要，因为它不需要在服务器上进行配置。
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 任务，包装器将被安装到项目中（此任务始终可用，即使它没有被添加到构建中）。要指定 Gradle 版本，请在命令上使用 --gradle-version。你还可以直接通过 --gradle-distribution-url 来设置下载 Gradle 的 URL。如果没有指定版本或分发 URL，包装器将被配置为执行 wrapper 任务的 gradle 的版本。所以如果使用 Gradle 2.4 执行 wrapper 任务，则包装器配置将默认为 2.4 版本。
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. 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.

> gradle wrapper --gradle-version 2.0
:wrapper

BUILD SUCCESSFUL

Total time: 1 secs

可以通过在构建脚本中添加和配置一个 Wrapper 任务，然后执行它来进一步自定义包装器。
The Wrapper can be further customized by adding and configuring a Wrapper task in your build script, and then executing it.

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

执行这一操作之后，你会在你的项目目录中发现以下新生成或更新的文件（在使用的 Wrapper 任务为默认配置的情况下）。
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).

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

所有这些文件都 应该 提交到版本控制系统中。这只需要执行一次。在将这些文件添加到项目之后，应该使用所添加的 gradlew 命令来构建项目。gradlew 命令的使用方式与 gradle 命令完全一样。
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.

如果要切换到新版本的 Gradle，不用重新运行包装器任务，只要修改 gradle-wrapper.properties 文件中的相应属性就可以了。但是如果你想利用 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.

如果你使用 gradlew 运行 Gradle ，那么包装器会检查要使用的 Gradle 分发包是否可用。如果可用，它会将最初传给 gradlew 命令的所有参数都委托给这个分发包的 gradle 命令。如果它没有找到 Gradle 分发包，它会先下载它。
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.

配置 Wrapper 任务时，你可以指定要使用的 Gradle 版本。gradlew 命令将从 Gradle 仓库下载相应的分发包。另外，你也可以指定 Gradle 分发包的下载 URL，gradlew 命令会使用这个 URL 下载分发包。如果你没有指定 Gradle 版本或下载 URL，那么 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.

有关如何配置包装器的详细信息，请参阅 API 文档中的 Wrapper 类。
For the details on how to configure the Wrapper, see the Wrapper class in the API documentation.

如果你不想项目在通过 gradlew 构建时进行下载，那么只需将 Gradle 分发包的 zip 文件添加到版本控制中包装器配置所指定的位置上。它支持相对 URL——你可以指定一个相对于 gradle-wrapper.properties 文件的位置的分发文件。
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.

如果你通过包装器构建，这台机器上已安装的任何 Gradle 分发包都会被忽略。
If you build via the Wrapper, any existing Gradle distribution installed on the machine is ignored.

Gradle 包装器允许通过 SHA-256 哈希值比较来验证下载的 Gradle 发行版。这通过防止中间人攻击者篡改下载的 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 分发包的 SHA-256 哈希值。可以使用 Linux 和 OSX 或 Windows（通过Cygwin）的 shasum 命令生成 SHA-256 哈希值。
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.

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

将返回的哈希值使用 distributionSha256Sum属性添加到 gradle-wrapper.properties。
Add the returned hash sum to the gradle-wrapper.properties using the distributionSha256Sum property.

distributionSha256Sum=371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10

包装器任务添加了相应的文件权限，以允许 gradlew *NIX 命令的执行。Subversion 会保留此文件权限。我们不确定其他版本控制系统是如何处理这一问题的，所以能让它始终可以使用的方法是执行 “sh gradlew”。
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”.