Chapter 47. The Gradle Wrapper

Gradle is a new tool. You can't expect it to be installed on machines beyond your sphere of influence. An example are continuous integration server where Gradle is not installed and where you have no admin rights for the machine. Or what if you provide an open source project and you want to make it as easy as possible for your users to build it?

There is a simple and good Wrapper task. ^[25] You can create such a task in your build script.

Example 47.1. Wrapper task

build.gradle

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

The build master usually explicitly executes this task. 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 47.2. Wrapper generated files

Build layout

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

All these files must be submitted to your version control system. The gradlew command can be used exactly the same way as the gradle command.

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 there is for example an improvement in the gradle-wrapper functionality you need to regenerate the wrapper files.

47.1. Configuration

If you run Gradle with gradlew, Gradle checks if a Gradle distribution for the wrapper is available. If not it tries to download it, otherwise it delegates to the gradle command of this distribution with all the arguments passed originally to the gradlew command.

You can specify where the wrapper files should be stored (within your project directory):

Example 47.3. Configuration of wrapper task

build.gradle

task wrapper(type: Wrapper) {
    gradleVersion = '0.9'
    jarFile = 'wrapper/wrapper.jar'
}

Build layout

customized/
  gradlew
  gradlew.bat
  wrapper/
    wrapper.jar
    wrapper.properties

You can specify the download URL of the wrapper distribution. You can also specify where the wrapper distribution should be stored and unpacked (either within the project or within the gradle user home dir). If the wrapper is run and there is local archive of the wrapper distribution Gradle tries to download it and stores it at the specified place. If there is no unpacked wrapper distribution Gradle unpacks the local archive of the wrapper distribution at the specified place. All the configuration options have defaults except the version of the wrapper distribution.

For the details on how to configure the wrapper, see Wrapper

If you don't want any download to happen when your project is build via gradlew, simply add the Gradle distribution zip to your version control at the location specified by your wrapper configuration. 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.

47.2. Unix file permissions

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

47.3. Environment variable

Some rather exotic use cases might occur when working with the Gradle Wrapper. For example the continuos integration server goes down during unzipping the Gradle distribution. As the distribution directory exists gradlew delegates to it but the distribution is corrupt. Or the zip-distribution was not properly downloaded. When you have no admin right on the continuous integration server to remove the corrupt files, Gradle offers a solution via environment variables.

Table 47.1. Gradle wrapper environment variables

Variable Name	Meaning
GRADLE_WRAPPER_ALWAYS_UNPACK	If set to `true`, the distribution directory gets always deleted when gradlew is run and the distribution zip is freshly unpacked. If the zip is not there, Gradle tries to download it.
GRADLE_WRAPPER_ALWAYS_DOWNLOAD	If set to `true`, the distribution directory and the distribution zip gets always deleted when gradlew is run and the distribution zip is freshly downloaded.

^[25]If you download the Gradle source distribution or check out Gradle from SVN, you can build Gradle via the Gradle wrapper. Gradle itself is continuously built by Bamboo and Teamcity via this wrapper. See http://www.gradle.org/ci-server.html