Chapter 5. The Gradle Wrapper about Gradle Wrapper

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

Most tools need to be installed before use, and if it's easy to install, it's not good to annoy users because of the hassle of installation. And just as important is whether the user installs the correct version, if the user is using the old version of the software build it?

The Gradle Wrapper (henceforth referred to as the "Wrapper") solves both these problems and is the preferred of the- ng a Gradle build.

Gradle Wrapper, hereafter referred to as Wrapper, solves these two problems, which is also the preferred method of Gradle construction.

5.1. Executing a build with the Wrapper

Using wrapper to perform builds

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

If the Gradle project already has wrapper installed (we recommend that all projects do this), you can use any one of the following commands in the root directory of the project to perform the build

• ./gradlew <task>(on Unix-like platforms such as Linux and Mac OS X)//mac system

• gradlew <task>(on Windows using the Gradlew.bat batch file)//windows system

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

Each wrapper is bound to a specified gradle version, so when you first run one of the above commands for a given gradle version, it will download the corresponding Gradle release package and use it to perform the build

Ides

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

Not only does this mean so you don ' t has to manually install Gradle yourself, but you're 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 do see a command line starting gradle ... with the user guide, On Stack Overflow, in articles or wherever.

For completeness sake, and to ensure you don't delete any important files, here is the files and directories in a Gradle Project, make up the Wrapper:

Here are some of the important files generated in the Gradle project, which are used to assemble the wrapper, do not delete

• 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 is stored, you'll find them in your user home directory under $USER_HOME/.gradle/wrapper/dists .

Gradle distribution package is stored in $user_home/.gradle/wrapper/dists

5.2. Adding the Wrapper to a project

Add wrapper to a project

The Wrapper is something your should check into version control. By distributing the Wrapper with your project, anyone can work with it without needing to install

Wrapper is the content to be checked in the repository, the wrapper is published to the project, and anyone can use wrapper without the need to install Gradle

Gradle beforehand. Even better, the users of the build is guaranteed to use the version of Gradle the build is designed to work with. Of course, this is also great forcontinuous integration servers (i.e. servers) regularly build your project) as it req Uires no configuration on the server.

Better yet, the build user can be assured that Gradle builds the targeted version of the design, which is also great for continuous integration servers.

You install the Wrapper to your project by running the wrapper task. (this task was always available, even if you don't add it to your build). To specify a Gradle version

By running wrapper task to install wrapper, this task is always available, although you did not add it to the build step.

Use on the --gradle-version command-line. You can also set the URL of the download Gradle from directly via --gradle-distribution-url . If No version or distribution

Using--gradle--version to specify the Gradle version, you can also download the Gradle URL directly via the--gradle-distribution-url option setting.

The URL is specified, the Wrapper would be configured to use the Gradle version of the wrapper task is executed with. If you run wrapper the task with Gradle 2.4 and then the

If you do not specify a version of wrapper or url,wrapper will download the Gradle version of the wrapper task, if you run Gradle task with wrapper 2.4, the default configuration for wrapper is 2.4

Wrapper configuration would default to version 2.4.

Example 5.1. Running the Wrapper task

Output ofgradle wrapper --gradle-version 2.0

> Gradle wrapper--gradle-version 2.0:wrapperbuild successfultotal time:1 secs

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

Wrapper can add a wrapper task to the build script to deeply customize it and then execute it.

Example 5.2. Wrapper Task

build.gradle

Task Wrapper (type:wrapper) {    ' 2.0 '}

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

After executing the above script, you will find that the following new or modified files are generated in the project (in case the default configuration 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 is submitted to your version control system. This is only needs to is done once. After these files has been added to the project, the project

All of these files will be submitted to the repository. So this task only needs to be executed once. When these files are added to the project,

Should then is built with the added gradlew command. The gradlew command can be used exactly the same as the gradle command.

The project is built with the Gradlew command, and the Gradlew command usage can be 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 gradle-wrapper.properties in the file, but if you want to take advantage of new functionality In the Gradle wrapper and then you would need to regenerate the wrapper files.

If you want to switch to a new version of Gradle, you only need to modify the gradle-wrapper.properties file

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 th E gradlew command. If it didn ' t find a Gradle distribution, it'll download it first.

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

For the details of the Configure the Wrapper, see the class in the Wrapper API documentation.

If you don ' t want any download to happen when your project is built via Gradlew, simply add the Gradle distri Bution zip to your version control on 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 Downlo aded 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 gradle-2.4-all.zip371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10  Gradle-2.4-all.zip

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

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 gradlew command. Subversion preserves this file permission. We is not sure how other version control systems deal with this. What should always work was to execute " sh gradlew ".

Chapter 5. The Gradle Wrapper about Gradle Wrapper