Gradle is a build automation tool that supports multi-language development. It is helpful to build, test, publish, and deploy software on any platform. In this article, we will learn about the Gradle Wrapper - what it is, when to use it, how to use it, etc.
What Is the Gradle Wrapper?
The Gradle Wrapper is basically a script. It will ensure that the required version of Gradle is downloaded and used for building the project. This is the recommended approach to executing Gradle builds.
When To Use the Gradle Wrapper?
The Wrapper is an effective way to make the build environment independent. No matter where the end-user is building the project, it will always download the appropriate version of Gradle and use it accordingly.
As a result, developers can get up and running with a Gradle project quickly and reliably without following manual installation processes. The standardized build process makes it easy to provision a new Gradle version to different execution environments.
How the Gradle Wrapper Works
Once the user builds the project using Gradle Wrapper, then the following steps will happen:
- The Wrapper script will download the required Gradle distribution from the server if necessary.
- Then, it will store and unpack the distribution under the Gradle user home location (default location is
.gradle/wrapper/distsunder the user home).
- We are all set to start building the project using the Wrapper script.
The Wrapper will not download the Gradle distribution if it is already cached in the system.
How To Use the Gradle Wrapper
There are mainly three scenarios for Gradle Wrapper usage. Let’s learn more about these.
Setting Up the Gradle Wrapper for a New Project
First, we need to install Gradle to invoke the Wrapper task. You can refer to the official installation guide. Once the installation is complete, we are good to go for the next step.
In this tutorial, we will use Gradle version 7.4.2.
Now, let’s open the terminal, navigate to the required folder/directory and run the command
After starting the
init command, we choose the project type, build script DSL, and project name. Let’s go ahead with the default options that will look something like this:
$ gradle init Select type of project to generate: 1: basic 2: application 3: library 4: Gradle plugin Enter selection (default: basic) [1..4] Select build script DSL: 1: Groovy 2: Kotlin Enter selection (default: Groovy) [1..2] Generate build using new APIs and behavior (some features may change in the next minor release)? (default: no) [yes, no] Project name (default: gradle-wrapper-demo): > Task :init Get more help with your project: Learn more about Gradle by exploring our samples at https://docs.gradle.org/7.4.2/samples BUILD SUCCESSFUL in 3m 25s 2 actionable tasks: 2 executed
If we now check the file structure in this directory, we will see:
. ├── build.gradle ├── gradle │ └── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradlew ├── gradlew.bat └── settings.gradle
We need to commit these files into version control so that the Wrapper script becomes accessible to other developers in the team.
We will explore the file contents in the next section.
We just tried the first way to create the Wrapper. Let’s move on to the next.
Setting Up the Gradle Wrapper for an Existing Project
You may also want to create the Wrapper for your existing Gradle projects. There is a
wrapper task available for this use case. The only pre-requisite is that you already have a
settings.gradle file in your project directory.
Now, when we run the command
gradle wrapper from that directory, it will create the Wrapper specific files:
$ gradle wrapper BUILD SUCCESSFUL in 697ms 1 actionable task: 1 executed
If you need help on the Wrapper task, then the
gradle help --task wrapper command is all you need.
Executing a Gradle Build Using the Wrapper
Once we have a project bootstrapped with the Wrapper files, running the Gradle build is straightforward.
- For Linux/macOS users, the
gradlewscript can be run from the terminal.
- For Windows users, the
gradlew.batscript can be run from the terminal/command prompt.
Here is a sample output of the script when run from Linux/macOS:
$ ./gradlew > Task :help Welcome to Gradle 7.4.2. To run a build, run gradlew <task> ... To see a list of available tasks, run gradlew tasks To see more detail about a task, run gradlew help --task <task> To see a list of command-line options, run gradlew --help For more detail on using Gradle, see https://docs.gradle.org/7.4.2/userguide/command_line_interface.html For troubleshooting, visit https://help.gradle.org BUILD SUCCESSFUL in 980ms 1 actionable task: 1 executed
As you can see, by default, when we don’t pass the task name in the command, the default
help task is run.
To build the project, we can use the
build task, i.e.,
./gradlew build or
gradlew.bat build. Using the Wrapper script, you can now execute any Gradle command without having to install Gradle separately.
We will use
./gradlew in the following examples. Please use
gradlew.bat instead of
./gradlew if you are on a Windows system.
What Does the Gradle Wrapper Contain?
In a typical Wrapper setup, you will encounter the following files:
||The Wrapper JAR file containing code to download the Gradle distribution.|
||The properties file configuring the Wrapper runtime behavior. Most importantly, this is where you can control the version of Gradle that is used for builds.|
||A shell script for executing the build.|
||A Windows batch script for running the build.|
gradle-wrapper.properties contains the following data:
distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists distributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-bin.zip zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists
How to Update the Gradle Version?
You might have to update the Gradle version in the future. We can achieve this by running the command
./gradlew wrapper --gradle-version <required_gradle_version> from a project containing Wrapper scripts.
Then, we can check if the version is duly updated by running the
./gradlew --version command.
You can also change the version number in the
distributionUrl property in the
gradle-wrapper.properties file. The next time
./gradlew is called, it will download the new version of Gradle.
How to Use a Different Gradle URL?
Sometimes we may have to download the Gradle distribution from a different source than the one mentioned in the default configuration. In such cases, we can use the
--gradle-distribution-url flag while generating the Wrapper, e.g.,
./gradlew wrapper --gradle-distribution-url <custom_gradle_download_url>.
In this article, we learned what problem the Gradle Wrapper solves, how to use it, and how it works. You can read a similar article on this blog on Maven Wrapper.