[Android] Important Gradle Wrapper

1. Why do you need Gradle Wrapper

Gradle Wrapper is called Gradle wrapper, which is a layer of packaging for Gradle. Why do you need Gradle Wrapper? For example, in a development team, if every member comes in, Gradle needs to be installed on the computer. At this time, the environment and version of Gradle running will bring uncertainty to the build result. To solve this problem, Gradle provides a solution, Gradle Wrapper, which is a script that can run Gradle builds without Gradle installed on the computer, and can specify the version of Gradle, and developers can quickly start and run Gradle projects , Instead of manual installation, this standardizes the project and improves development efficiency. AS will bring its own Gradle Wrapper when creating a new project, which is why we rarely download and install Gradle separately. The workflow of Gradle Wrapper is shown in the figure below.

When using Gradle Wrapper to start Gradle, if the specified version of Gradle is not associated with the download, it will first download the version of Gradle from the Gradle official warehouse to the user's local, unpack and execute the batch file. Subsequent build runs will reuse this unpacked runtime installer.

2. Build Gradle Wrapper

First of all, make sure that the Gradle environment is configured on the computer. If not, you can refer to the Gradle core idea (2) Prelude to Gradle to configure the Gradle environment.
Gradle has built-in Wrapper Task. Executing Wrapper Task can generate Gradle Wrapper directory files in the project directory. Just execute the gradle wrapper in the project root directory.

Code

$ gradle wrapper
> Task :wrapper

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

At this time, the following files will be generated in the project root directory:

Code

├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
└── gradlew.bat

The meaning of each file is as follows:

gradle-wrapper.jar: Contains the logic code of Gradle runtime.
gradle-wrapper.properties: The properties file responsible for configuring the runtime behavior of the wrapper, used to configure which version of Gradle and other properties to use.
gradlew: A wrapper script used to execute Gralde commands under the Linux platform.
gradlew.bat: A wrapper script used to execute Gralde commands under the Windows platform.

After the above directories and files are generated, the user can push the project to the remote, and when other users are cloned, the project can be built directly, which saves the user the time to download Gradle separately, and can ensure the Gradle version Unanimous.

You can also use gradle command line options to generate a gradle wrapper.
--Gradle-version: used to download and execute the specified gradle version.
--Distribution-type: Specify the type of Gradle distribution to download. The available options are bin and all. The default value is bin. The -bin distribution only contains the runtime, but does not include the source code and documentation.
--Gradle-distribution-url: Specify the full URL address for downloading the Gradle distribution.
--Gradle-distribution-sha256-sum: Use the SHA 256 hash and verify the downloaded Gradle distribution.

For example, using the command line: gradle wrapper –gradle-version 4.2.1 –distribution-type all, you can generate a wrapper with version 4.2.1 and use the -all distribution.

3.配置Gradle Wrapper

gradle-wrapper.properties is the properties file of Gradle Wrapper, which is used to configure Gradle Wrapper. The gradle-wrapper.properties corresponding to Gradle 4.2.1 version is shown below.

Code

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-4.2.1-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

The meaning of the fields are as follows:

distributionBase: The home directory stored after Gradle is unpacked.
distributionPath: a subdirectory of the specified directory of distributionBase. distributionBase+distributionPath is the storage location after Gradle is unpacked.
distributionUrl: The download address of the Gradle distribution compressed package.
zipStoreBase: Gradle compressed package storage home directory.
zipStorePath: A subdirectory of the specified directory of zipStoreBase. zipStoreBase+zipStorePath is the storage location of the Gradle compressed package.

The most important thing we need to pay attention to here is the distributionUrl field. If the official address cannot be downloaded or is slow, you can change this address to another mirror address, or simply put the Gradle distribution compressed package on the server for download.

4. Use Gradle Wrapper

Use Gradle Wrapper not to use Gradle commands, but to use gradlew and gradlew.bat scripts. Add the following statement in build.gradle:

java

task test {
    doLast {
        println 'Hello world!'
    }
}

Taking the Windows platform as an example, we enter the root directory where the project is located and execute gradlew.bat test:

Code

f:\app>gradlew.bat test
Downloading https://services.gradle.org/distributions/gradle-4.2.1-bin.zip
...................................................................
Starting a Gradle Daemon (subsequent builds will be faster)

> Task :test
Hello world!

If there is no Gradle release on the computer, the Gradle wrapper will download the Gradle release compressed package to the local and decompress it. For example, the storage path on my computer is: C:\Users\52501.gradle\wrapper\dists\gradle -4.2.1-bin\dajvke9o8kmaxbu0kc5gcgeju\gradle-4.2.1.
If the distributionUrl property of the Gradle properties file does not change thereafter, the local Gradle release will always be used. If we execute gradlew.bat test again, it will be the same as calling the Gradle command:

Code

f:\app>gradlew.bat test
Starting a Gradle Daemon (subsequent builds will be faster)

> Task :test
Hello world!

5. Upgrade Gradle Wrapper

There are two ways to upgrade Gradle Wrapper. One is to set the distributionUrl property of the Gradle properties file. The second is to run the wrapper task. The second method is recommended. The current local Gradle version is 4.2.1, I want to upgrade to 5.1.1, just run the gradlew wrapper –gradle-version 5.1.1 command.

Code

f:\app>gradlew wrapper --gradle-version 5.1.1

BUILD SUCCESSFUL in 1s
1 actionable task: 1 executed

Run the gradlew -v command to check the version of Gradle.

Code

f:\app>gradlew -v
Downloading https://services.gradle.org/distributions/gradle-5.1.1-bin.zip
.................................................................................
Unzipping C:\Users\52501\.gradle\wrapper\dists\gradle-5.1.1-bin\90y9l8txxfw1s2o6ctiqeruwn\gradle-5.1.1-bin.zip to C:\Users\52501\.gradle\wrapper\dists\gradle-5.1.1-bin\90y9l8txxfw1s2o6ctiqeruwn

Welcome to Gradle 5.1.1!

Here are the highlights of this release:
 - Control which dependencies can be retrieved from which repositories
 - Production-ready configuration avoidance APIs

For more details see https://docs.gradle.org/5.1.1/release-notes.html

------------------------------------------------------------
Gradle 5.1.1
------------------------------------------------------------

Build time:   2019-01-10 23:05:02 UTC
Revision:     3c9abb645fb83932c44e8610642393ad62116807

Kotlin DSL:   1.1.1
Kotlin:       1.3.11
Groovy:       2.5.4
Ant:          Apache Ant(TM) version 1.9.13 compiled on July 10 2018
JVM:          1.8.0_191 (Oracle Corporation 25.191-b12)
OS: Windows 10 10.0 amd64

Since the local is not Gradle 5.1.1, the downloaded Gradle compressed package will be stored and unpacked. For details, see the print log above.

6. Custom Gradle Wrapper

Gradle has built-in Wrapper Task, so building Gradle Wrapper will generate Gradle Wrapper properties file, which can be set by customizing Wrapper Task. For example, if we want to modify the Gralde version to be downloaded to 4.2.1, we can set it like this:

java

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

You can also set the download address of the Gradle release compressed package and the local storage path after Gradle is unpacked.

java

task wrapper(type: Wrapper) {
    gradleVersion = '4.2.1'
    distributionUrl = '../../gradle-4.2.1-bin.zip'
    distributionPath=wrapper/dists

}

The distributionUrl attribute can be set to the local project directory, or you can set it to the network address.