Table of Contents

5.1. Executing a build with the Wrapper

5.2. Adding the Wrapper to a project

5.3. Configuration

5.4. Authenticated Gradle distribution download

5.5. Verification of downloaded Gradle distributions

5.6. Unix file permissions

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:

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.

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 withgradle ... 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:

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

You install the Wrapper into your project by running thewrapper 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 abin distribution. This is the smallest Gradle distribution. Some tools, like Android Studio and Intellij IDEA, provide additional context information when used with theall 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 thewrapper task is executed with. So if you run thewrapper task with Gradle 2.4, then the Wrapper configuration will default to version 2.4.

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

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

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

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

All of these filesshould 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 addedgradlew command. Thegradlew command can be usedexactly the same way as thegradle command.

If you want to switch to a new version of Gradle you don't need to rerun thewrapper 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.

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

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

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

If you don't want any download to happen when your project is built viagradlew, 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 ofgradle-wrapper.properties file.

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

The GradleWrapper 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 thedistributionUrl. Credentials in system properties take precedence over the ones embedded indistributionUrl.

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

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

Embedding credentials in thedistributionUrl in thegradle/wrapper/gradle-wrapper.properties file also works. Please note that this file is to be committed into your source control system. Shared credentials embedded indistributionUrl should only be used in a controlled environment.

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

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

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 (viaCygwin) with theshasum command.

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

Add the returned hash sum to thegradle-wrapper.properties using thedistributionSha256Sum property.

distributionSha256Sum=371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10

The Wrapper task adds appropriate file permissions to allow the execution of thegradlew *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”.