The Gradle Wrapper (henceforth referred to as the “wrapper) is the preferred way of starting a Gradle build. The wrapper is a batch script on Windows, and a shell script for other operating systems. When you start a Gradle build via the wrapper, Gradle will be automatically downloaded and used to run the build.
The wrapper is something you should 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 for continuous 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 adding and configuring a Wrapper
task in your build script, and then executing it.
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 61.2. Wrapper generated files
Build layout
simple/ gradlew gradlew.bat gradle/wrapper/ gradle-wrapper.jar gradle-wrapper.properties
All of these files should 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 added gradlew command. 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.
If you run Gradle with gradlew, the wrapper 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.
When you configure the Wrapper
task, you can specify the Gradle version you wish to use. The gradlew
command will download the appropriate distribution from the Gradle repository.
Alternatively, you can specify the download URL of the Gradle distribution. The gradlew command will use this URL to download
the distribution.
If you specify neither a Gradle version or download URL, the gradlew command will by default download whichever version
of Gradle was used to generate the wrapper files.
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.
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.