Chapter 5. The Gradle Wrapper about gradle wrapper and gradlewrapper

Chapter 5. The Gradle Wrapper about gradle wrapper and gradlewrapper

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?

// Most tools need to be installed before use. If the installation is easy, but it is not good if the installation is troublesome. What is equally important is whether the user installs the correct version. If the user is using the old version of the software to build it?

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, hereinafter referred to as Wrapper, solves these two problems. This is also the preferred method for gradle construction.

5.1. Executing a build with the Wrapper

// Use wrapper to execute the build

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:

// If the gradle project has wrapper installed (we recommend that all projects do this), you can run the following command in the project root directory to build

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

• gradlew <task>(On Windows using the gradlew. bat batch file) // on 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.

// Each wrapper is bound to a specified gradle version. Therefore, when you run one of the preceding commands for a given gradle version for the first time, it downloads the corresponding gradle release package, and use it to execute the build

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. this makes your historical builds more reliable. just use the appropriate syntax from abve whenever you see a command line startinggradle ...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:

// This is an important file generated in the gradle project. These files are used to build wrapper. Do not delete them.

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

// The gradle distribution package is stored in $ USER_HOME/. gradle/wrapper/dists

5.2. Adding the Wrapper to a project

// Add wrapper to the Project

The Wrapper is something youShocouldCheck 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 when it is added to the version library and published wrapper to the project. Anyone can use wrapper without the need to install gradle

Gradle beforehand. even better, users of the build are guaranteed to use the version of Gradle that the build was designed to work. 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.

// Better, the build user can ensure that gradle is used to build the designed target version. Of course, this is great for the continuous integration server.

You install the Wrapper into your project by runningwrapperTask. (This task is always available, even if you don't add it to your build). To specify a Gradle version

// Run the wrapper task to install wrapper. This task is always available, even though it is not added to the build step.

Use--gradle-versionOn the command-line. You can also set the URL to download Gradle from directly--gradle-distribution-url. If no version or distribution

// Use -- gradle -- version to specify the gradle version. You can also use the -- gradle-distribution-url option to directly download the gradle url.

URL is specified, the Wrapper will be configured to use the gradle versionwrapperTask is executed with. So if you runwrapperTask with Gradle 2.4, then

// If the wrapper version or url is not specified, wrapper downloads the gradle version for executing the wrapper task. Therefore, if you use gradle 2.4 to run the wrapper task, the default wrapper configuration is 2.4

Wrapper configuration will default to version 2.4.

Example 5.1. Running the Wrapper task

Outputgradle wrapper --gradle-version 2.0

> gradle wrapper --gradle-version 2.0:wrapperBUILD SUCCESSFULTotal time: 1 secs

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

// Wrapper can add wrapper tasks in build scripts for in-depth customization and then execute them.

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

// 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 filesShocouldBe submitted to your version control system. This only needs to be done once. After these files have been added to the project, the project

// All these files will be submitted to the version library. Therefore, this task only needs to be executed once. After these files are added to the project,

Shoshould then be built with the addedGradlewCommand.GradlewCommand can be usedExactlyThe same way asGradleCommand.

// The project will be built using the gradlew command later. The gradlew command can be used in the same way as gradle.

If you want to switch to a new version of Gradle you don't need to rerunwrapperTask. It is good enough to change the respective entry ingradle-wrapper.propertiesFile, but if you want to take advantage of new functionality in the Gradle wrapper, then you wowould need to regenerate the wrapper files.

// If you want to switch to the new version of gradle, you only need to modifygradle-wrapper.propertiesFile

5.3. Configuration

If you run GradleGradlew, The Wrapper checks if a Gradle distribution for the Wrapper is available. If so, it delegates toGradleCommand of this distribution with all the arguments passed originally toGradlewCommand. If it didn't find a Gradle distribution, it will download it first.

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

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

If you don't want any download to happen when your project is builtGradlew, 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 locationgradle-wrapper.propertiesFile.

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

Example 5.4. Generating a SHA-256 hash

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

Add the returned hash sum togradle-wrapper.propertiesUsingdistributionSha256SumProperty.

Example 5.5. Sorting 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 ofgradlew* NIX command. Subversion preserves this file permission. We are not sure how other version control systems deal with this. What shoshould always work is to execute"sh gradlew".