Android Weekly 转发的一篇关于“ Gradle Wrapper”的介绍文章，蛮新鲜的，就收藏了～
原文：https://medium.com/@bherbst/understanding-the-gradle-wrapper-a62f35662ab7

The vast majority of developers using Gradle use the Gradle Wrapper. This is great because using the Gradle Wrapper means that developers working on the project don’t need to manage their own Gradle installations. Being that the wrapper is so ubiquitous it is important to understand exactly what it does and what it does not do.

If you aren’t using the wrapper

If you aren’t already using the wrapper, you really should. Using the wrapper guarantees that every developer on your team is using the same version of Gradle and that they can run Gradle builds (even if they haven’t installed Gradle on their machine).

Getting started is easy. First install Gradle on your machine, then open up your project directory via the command line. Run gradle wrapper and you are done! You can add the --gradle-version X.Y argument to specify which version of Gradle to use.

Now you can run any Gradle task in your project using the gradlew shell script or bat file located in your project’s root directory.

What the Gradle Wrapper is

The Gradle Wrapper consists of a few files in your project directory:
gradlew: The shell script Unix users can run to execute Gradle tasks

  • gradlew.bat The bat script Windows users can run to execute Gradle tasks
  • gradle/wrapper/gradle-wrapper.jar The wrapper’s executable JAR; this is where the wrapper code resides
  • gradle/wrapper/gradle-wrapper.properties A properties file for configuring the wrapper
    You should make sure all these are committed to version control. They are all small, system-independent, and critical to using the Gradle Wrapper.

What the Gradle Wrapper does

When you run the Gradle Wrapper it performs the following actions:

  1. Parse the arguments passed to gradlew
  2. Install the correct Gradle version
  3. Invoke Gradle to run the specified tasks

Note that the wrapper only accepts two optional configuration arguments:
-q or --quiet to suppress output
-g or --gradle-user-home to specify an alternate home directory for Gradle.
The Gradle installation step is the only one that is particularly interesting. First it will check your GRADLE_USER_HOME for the desired Gradle distribution. If it already exists, the wrapper goes on to invoking Gradle. If the distribution doesn’t exist yet, the wrapper will download the distribution.

It is also important to note that the wrapper completely ignores any Gradle distribution on your system. The wrapper downloads and unzips Gradle distributions in its own separate directory and will only use those distributions for builds. The wrapper will use any global Gradle configuration such as a gradle.properties file defined in your Gradle home directory when running tasks.

What the Gradle Wrapper doesn’t do

The Gradle Wrapper itself does not execute your tasks. All it does is ensure you have the desired Gradle distribution and then invoke it. The wrapper is a very thin layer to eliminate the need for devlelopers to manage distributions themselves.

This means that the wrapper is effectively completely decoupled from Gradle itself. A wrapper from 2014 can build a project using Gradle 4.0, and a wrapper installed today can build a project using Gradle 2.0.

If you encounter an issue with your builds, it is extremely unlikely that the wrapper is at fault since it primarily just invokes Gradle proper.

Wrapper configuration

I mentioned earlier that one of the files the wrapper puts in your project is a configuration file at gradle/wrapper/gradle-wrapper.properties.

This file typically looks something like this:

1
2
3
4
5
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-4.0-all.zip

distributionBase + distributionPath specify the path at which the wrapper will store Gradle distributions. By default GRADLE_USER_HOME is ~/.gradle, so the wrapper will store Gradle distributions at ~/.gradle/wrapper/dists.
zipStoreBase and zipStorePath are very similar. These specify where the wrapper will store the zipped distributions it downloads.
distributionUrl is the one you likely care most about. This is what specifies what version of Gradle you want to use for your builds and where to download it from.

Updates

Since the wrapper is independent of the actual Gradle distribution you use to build your project, what do you update and when?

The wrapper documentation says this:

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 you want to take advantage of new functionality in the Gradle wrapper, then you would need to regenerate the wrapper files.

You should keep your Gradle distribution as up-to-date as possible. This is as easy as updating the distributionUrl in your gradle-wrapper.properties .

You typically don’t need to update the Gradle Wrapper, but you can do so by re-running the gradle wrapper task after updating Gradle. You can do this using the wrapper by running gradlew wrapper which has the benefit of using the wrapper’s Gradle distribution. Updating it won’t hurt, but don’t expect any crazy new features in the wrapper. It hasn’t meaningfully changed since 2014 (unless you get excited about seeing fewer dots).

Android developers should note that the version of Gradle is (mostly) independent from the Android plugin version and from the version of Android Studio you use. New versions of either the plugin or Studio may require an updated Gradle version, but you should be able to use newer Gradle versions with older plugins and Studio without any issues.

Further reading