Generating the Wrapper files requires an installed version of the Gradle runtime on your machine as described in
Installation
.
Thankfully, generating the initial Wrapper files is a one-time process.
Every vanilla Gradle build comes with a built-in task called
wrapper
.
The task is listed under the group "Build Setup tasks" when
listing the tasks
.
Executing the
wrapper
task generates the necessary Wrapper files in the project directory:
> Task :wrapper
BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed
|
To make the Wrapper files available to other developers and execution environments, you need to check them into version control.
Wrapper files, including the JAR file, are small.
Adding the JAR file to version control is expected.
Some organizations do not allow projects to submit binary files to version control, and there is no workaround available.
|
The generated Wrapper properties file,
gradle/wrapper/gradle-wrapper.properties
, stores the information about the Gradle distribution:
-
The
server hosting
the Gradle distribution.
-
The
type of Gradle distribution
. By default, the
-bin
distribution contains only the runtime but no sample code and documentation.
-
The
Gradle version
used for executing the build. By default, the
wrapper
task picks the same Gradle version used to generate the Wrapper files.
-
Optionally, a
timeout
in ms used when downloading the Gradle distribution.
-
Optionally, a
boolean
to set the
validation of the distribution
URL.
The following is an example of the generated distribution URL in
gradle/wrapper/gradle-wrapper.properties
:
distributionUrl=https\://services.gradle.org/distributions/gradle-8.8-bin.zip
All of those aspects are configurable at the time of generating the Wrapper files with the help of the following command line options:
--gradle-version
-
The Gradle version used for downloading and executing the Wrapper.
The resulting distribution URL is validated before it is written to the properties file.
The following labels are allowed:
--distribution-type
-
The Gradle distribution type used for the Wrapper.
Available options are
bin
and
all
.
The default value is
bin
.
--gradle-distribution-url
-
The full URL pointing to the Gradle distribution ZIP file.
This option makes
--gradle-version
and
--distribution-type
obsolete, as the URL already contains this information.
This option is valuable if you want to host the Gradle distribution inside your company’s network.
The URL is validated before it is written to the properties file.
--gradle-distribution-sha256-sum
-
The SHA256 hash sum used for
verifying the downloaded Gradle distribution
.
--network-timeout
-
The network timeout to use when downloading the Gradle distribution, in ms. The default value is
10000
.
--no-validate-url
-
Disables the validation of the configured distribution URL.
--validate-url
-
Enables the validation of the configured distribution URL. Enabled by default.
If the distribution URL is configured with
--gradle-version
or
--gradle-distribution-url
, the URL is validated by sending a HEAD request in the case of the
https
scheme or by checking the existence of the file in the case of the
file
scheme.
Let’s assume the following use-case to illustrate the use of the command line options.
You would like to generate the Wrapper with version 8.8 and use the
-all
distribution to enable your IDE to enable code-completion and being able to navigate to the Gradle source code.
The following command-line execution captures those requirements:
$ gradle wrapper --gradle-version 8.8 --distribution-type all
> Task :wrapper
BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed
As a result, you can find the desired information (the generated distribution URL) in the Wrapper properties file:
distributionUrl=https\://services.gradle.org/distributions/gradle-8.8-all.zip
Let’s have a look at the following project layout to illustrate the expected Wrapper files:
.
├── a-subproject
│ └── build.gradle.kts
├── settings.gradle.kts
├── gradle
│ └── wrapper
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
├── gradlew
└── gradlew.bat
.
├── a-subproject
│ └── build.gradle
├── settings.gradle
├── gradle
│ └── wrapper
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
├── gradlew
└── gradlew.bat
A Gradle project typically provides a
settings.gradle(.kts)
file and one
build.gradle(.kts)
file for each subproject.
The Wrapper files live alongside in the
gradle
directory and the root directory of the project.
The following list explains their purpose:
gradle-wrapper.jar
-
The Wrapper JAR file containing code for downloading the Gradle distribution.
gradle-wrapper.properties
-
A properties file responsible for configuring the Wrapper runtime behavior e.g. the Gradle version compatible with this version. Note that more generic settings, like
configuring the Wrapper to use a proxy
, need to go into a
different file
.
gradlew
,
gradlew.bat
-
A shell script and a Windows batch script for executing the build with the Wrapper.