Normally, if we want to run a Gradle build, we must have Gradle installed on our computer. Also, if we distribute our project to others and they want to build the project, they must have Gradle installed on their computers. The Gradle wrapper can be used to allow others to build our project even if they don't have Gradle installed on their computers.
The wrapper is a batch script on the Microsoft Windows operating systems or shell script on other operating systems that will download Gradle and run the build using the downloaded Gradle.
By using the wrapper, we can make sure the correct Gradle version for the project is used. We can define the Gradle version, and if we run the build via the wrapper script file, the version of Gradle that we defined is used.
To create the Gradle wrapper batch and shell script, we must add a task to our build. The type of task is org.gradle.api.tasks.wrapper.Wrapper. We set the gradleVersion property to the Gradle version we want to use.
The following sample build file shows how we configure a Wrapper task:
task createGradleWrapper(type: Wrapper) {
gradleVersion = '1.1'
}Next, we can execute the
createGradleWrapper task to generate the files from the command line:
$ gradle createGradleWrapper :createGradleWrapper BUILD SUCCESSFUL Total time: 5.938 secs
After the execution of the task, we have two script files: gradlew.bat and gradlew in the root of our project directory. These scripts contain all the logic needed to run Gradle. If Gradle is not downloaded yet, the Gradle distribution will be downloaded and installed locally.
In the directory gradle/wrapper relative to our project directory we find the files gradle-wrapper.jar and gradle-wrapper.properties. The gradle-wrapper.jar file contains a couple of class files necessary to download and invoke Gradle. The gradle-wrapper.properties file contains settings, such as specifying the URL to download Gradle. The gradle-wrapper.properties file also contains the Gradle version number. If a new Gradle version is released, we only have to change the version in the gradle-wrapper.properties file and the Gradle wrapper will download the new version, so we can use it to build our project.
All the generated files are now part of our project. If we use a version control system, then we must add these files to the version control. Other people that check out our project can use the gradlew scripts to execute tasks from the project. The specified Gradle version is downloaded and used to run the build file.
We can even delete the createGradleWrapper task from our build file. If we want to use another Gradle version, we can set the gradleVersion property in the gradle/wrapper/gradle-wrapper.properties file.
We can change the names of the script files that are generated with the
scriptFile property of the Wrapper task. To change the name of the generated JAR and properties files, we can change the jarFile property:
task createGradleWrapper(type: Wrapper) {
gradleVersion = '1.1'
scriptFile = 'startGradle'
jarFile = 'gradle-bin'
}To change the URL from which the Gradle version must be downloaded, we can alter the distributionUrl property. For example, we could publish a fixed Gradle version on our company intranet and use the distributionUrl property to reference a download URL on our intranet. This way we can make sure all developers in the company use the same Gradle version:
task createGradleWrapper(type: Wrapper) {
gradleVersion = '1.1 '
distributionUrl = 'http://intranet/downloads/gradle-custom-bin.zip'
}