Chapter 5. The Gradle Wrapper 关于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 构建的优选方法

5.1. Executing a build with the Wrapper

//使用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) //mac系统上

• gradlew <task> (on Windows using the gradlew.bat batch file) //windows系统上

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发布包，并使用它执行构建

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.

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.

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 distribution包存储在$USER_HOME/.gradle/wrapper/dists

5.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

//wrapper是在添加到版本库中要检查的内容，把wrapper发布到项目中，任何人可以使用wrapper而不需要安装gradle

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 forcontinuous integration servers (i.e. servers that regularly build your project) as it requires no configuration on the server.

//更好的是，构建的用户可以保证使用到的就是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

//通过运行wrapper task来安装wrapper,这个任务总是可获得的，尽管你没有把它添加到构建步骤中。

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

//用--gradle--version来指定gradle版本，你也可以通过--gradle-distribution-url选项设置直接下载gradle的url

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的版本或者url,wrapper会下载执行wrapper任务的gradle的版本，所以，如果你使用gradle 2.4运行wrapper任务，wrapper的默认配置就是2.4

Wrapper configuration will default to version 2.4.

Example 5.1. Running the Wrapper task

Output of gradle wrapper --gradle-version 2.0

> gradle wrapper --gradle-version 2.0
:wrapper

BUILD SUCCESSFUL

Total time: 1 secs

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

//wrapper可以在build脚本中添加wrapper 任务来深度定制化，然后执行它。

Example 5.2. Wrapper task

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).

//在执行完上面的脚本，你会发现在项目中生成了下面这些新的或者修改的文件（以防使用默认配置）

Example 5.3. Wrapper generated files

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 thegradle-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的新版本，只需要修改gradle-wrapper.properties 文件

5.3. Configuration

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.

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.

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

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.

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

5.4. Verification of downloaded Gradle distributions

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.

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.

Example 5.4. Generating a SHA-256 hash

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

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

Example 5.5. Configuring SHA-256 checksum verification

gradle-wrapper.properties

distributionSha256Sum=371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10

5.5. Unix file permissions

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”.