【译】Understanding the Gradle Wrap

翻译自：原文。

大多数的开发者在使用Gralde时都选择使用Gradle Wrapper。这非常好，因为使用Gradle Wrapper意味着开发者可以将自己的精力集中到工程开发中，而非在维护Gradle安装相关。由于wrapper的使用非常广泛，去准确理解哪些是wrapper可以做的，哪些是不能做的，就显得非常的有必要。

如果你不使用Wrapper

如果你还没有使用wrapper，那么你真应该现在就使用！ 使用wrapper可以保证你团队中的每个开发者使用同一版本的Gradle，并且使用它进行各种build(即使他们已经安装了Gradle在自己的电脑上)

开始非常简单，首先安装Gradle到你的电脑上，然后通过命令行打开你的工程所在目录。Run gradlw wrapper，然后就可以了！ 当然，你可以添加 --gradle-version X.Y 参数去明确你要使用的Gradle的版本。

现在你可以在你的工程根目录，使用 gradlew shell script 或者bat file 去run任何Gralde task。

什么是Gradle Wrapper

Gradle Wrapper由项目目录下的一系列文件组成：

• gradlew：Unix/Linux用户可用来执行Gradle tasks的shell script
• gradlew.bat：Windows用户可用来执行Gradle tasks的bat script
• gradle/wrapper/gradle-wrapper.jar：wrapper的可执行JAR；wrapper代码的存放处
• gradle/wrapper/gradle-wrapper.properties：是一个属性文件，用于配置wrapper

你需要确保如上内容全部包含在版本控制系统中。它们都是文本体积小的，系统独立的并且是你想要使用Gralde Wrapper时所必需的一些文件。

Gradle Wrapper能做什么

当你run Gradle Wrapper时，它会执行如下动作：

1. 解析传给gradlew的参数
2. 安装正确版本的Gradle
3. 调用Gradle去执行相应的 tasks

需要注意的是wrapper只接受两个可选参数：

• -q或者--quiet 用于控制输出

• -g或者--gradle-user-home 用于为Gralde另外指定一个home directory

Gradle的安装步骤可能是唯一值得特别关注的地方了吧。首先，wrapper会去检查GRADLE_USER_HOME路径下是否有我们想要的Gradle distribution。如果已经存在，wrapper就会继续去调用Gradle。如果distribution不存在，wrapper就会去下载它。

同样值得的注意的是，wrapper会完全无视你电脑中任何其他的Gradle distribution。Wrapper只会下载并解压Gradle distribution到自己单独的目录中，并且只会使用它们去build。Wrapper可以使用任何全局的Gradle配置文件（will use any global Gradle configuration）比如gradle.properties去定义你的Gradle home directory，当你执行tasks时。

Gradle Wrapper不做什么

Gradle Wrapper本身不会去执行你的tasks。它所做的只是确保你可以得到你想到的Gradle distribution，然后去调用它。Wrapper可以理解为一个薄层，过滤掉了开发者们需要自己去维护distributions的这个需求。

这意味着wrapper非常有效率地与Gradle本身解耦了。一个2014年的wrapper可以build一个使用Gralde 4.0的工程；同样地，一个今天安装的wrapper也可以build一个使用Gradle 2.0的工程。

如果你在build时遇到问题，这几乎不大可能是wrapper的问题，因为它只是纯粹地调用相应的Gradle。

Wrapper的配置

我之前已经提到过工程里的一个wrapper文件，即配置文件radle/wrapper/gradle-wrapper.properties

文件的内容类似如下：

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明确了wrapper存放Gradle distributions的目标路径。默认 GRADLE_USER_HOME 指向的是 ~/.gradle (Unix/Linux) 或者 C:\Users\<username>\.gradle (Windows)。所以wrapper会将Gradle distributions存储在 ~/.gradle/wrapper/dists (Linux/Unix)或者 C:\Users\<username>\.gradle\wrapper\dists (Windows)目录下。

zipStoreBase和zipStorePath同上非常相似。它们明确了wrapper所下载的压缩的distributions存放的路径。

distributionUrl应该是你最应该关心的。这是用于声明你想用哪个版本的Gradle并且从哪里去下载它。

更新

正因为wrapper是独立于具体的用于编译你的工程的Gradle distribution，你应该怎样或者何时更新它？

正如wrapper官方文档所言：

如果你想切换到一个新版本的Gradle，你无须重新执行Wrapper这个task，只需更改gradle-wrapper.properties文件下的相应条目。

但是如果你想使用Gradle Wrapper中最新的功能，那么你需要重新生成wrapper文件。

你需要保证你的Gradle distribution尽可能地最新，只需简单的修改gradle-wrapper.properties文件中的distributionUrl的值即可。

一般情况下你不需要更新Gradle Wrapper，但是你可以在Gradle更新过后re-running gradle wrapper这个task来实现。你也可以使用wrapper的gradlew wrapper这个task，which has the benefit of using the wrapper’s Gradle distribution.（一段废话。。）。Wrapper更新后没有什么坏处，但别指望会有什么 crazy new features 添加进来，因为自2014年以来并没有什么实际意义上的重要更新（除非你乐忠于seeing fewer dots(不知道什么意思)）

Android开发者 需要意识到：Gradle的版本（大多数情况下）是独立于Android plugin的版本和你所使用的Android Studio的版本。新版本的plugin或者AS也许会要求更新Gradle版本，但是对于老版本的plugin和AS使用新版本的Gradle并不会有什么问题。

Further reading

GitHub上的Gradle Wrapper源码