gradlew在基于Gradle项目构建中的应用分析

众所周知，在软件开发中，我们无论使用何种工具、库和软件，首先要做的事情就是先将所需的工具下载到本地，然后可能还需要进行一些基本的配置才能够正常使用。比如说，使用Maven进行项目构建，那首先就需要到http://maven.apache.org网站上将Maven二进制包下载下来、解压缩，并配置好相应的M2_HOME、path环境变量等一些信息，接下来才可以使用Maven进行常规的项目构建工作。

对于Gradle来说，情形与Maven相似；同样需要先到https://www.gradle.org网站上先将Gradle二进制压缩包下载到本地，然后解压缩，再配置相应的环境变量，方可执行正常的项目构建工作。不过，除此之外，Gradle还提供了另外一种对于使用者更加友好的方式，使得使用者在将项目拉取到本地后，无需手工下载任何Gradle压缩包，只需通过一条简单的命令即可自动完成所需工具包的下载、配置与管理工作，同时还能够确保所下载的Gradle包的版本与项目所需的Gradle版本完全一致，规避了因软件版本的不同而导致的构建可能失败的结果。这种方式即是本文所要介绍的gradlew，即Gradle Wrapper。

Gradle Wrapper是通过一个命令来完成这一切的工作。实际上，这个命令在*nix系统上就是一个shell脚本，在Windows系统上则是一个批处理文件bat。接下来，我们就来看看gradlew是如何配置与工作的。

首先，使用IntelliJ IDEA建立一个Gradle工程（实际上，在新建Gradle工程时，IDEA就已经为我们提供了gradle wrapper的选项，不过这里我们暂时先不使用），这里我使用的Gradle版本是3.5，如下是新建项目的截图：







新建项目的build.gradle内容如下所示（增加了targetCompatibility = 1.8 一行）：



接下来，进入到项目根目录gradlew-demo，输入如下命令：

gradle wrapper



再来看看项目文件，你会发现项目中增加了一个gradlew、一个gradlew.bat，以及一个gradle目录，具体如下图所示：



实际上，到此为止，gradle wrapper的基本使用就告一段落了，这里使用的都是默认的配置。

下面来说说生成的各个文件的含义：

gradlew/gradlew.bat：这是分别针对于*nix与Windows的shell脚本与批处理命令，当我们将项目push到远程后，其他用户clone下来（这里使用了Git）后，只需在本地执行./gradlew 即可进行项目的构建与任务的执行（这里的表示任务名称），同时用户本机并不需要提前安装好Gradle分发包。

gradle-wrapper.jar：这是gradlew执行构建时所依赖的jar包。值得注意的是，一般我们在使用Maven或是Gradle进行项目构建时，项目所依赖的jar包是不需要纳入版本控制系统中的，因为在执行构建时，这些依赖会被自动下载到本地（通过中央仓库、第三方仓库或是私服）；但如果使用了gradle wrapper，那么这个gradle-wrapper.jar则是必须要纳入到版本控制系统中的，因为这是其他用户执行gradlew命令进行项目构建时所必须的。

gradle-wrapper.properties：这是gradlew在执行项目构建时的属性文件。默认情况下，该属性文件内容描述了分发包的下载位置，从什么地方下载等。用户在执行gradlew进行项目构建时，如果本机没有安装好所指定的Gradle版本，那么系统会自动从distributionUrl所指定的位置处下载，并存储在distributionPath所指定的位置处。一般来说，它会存储在本机的$USER_HOME/.gradle/wrapper/dists目录下。

实际上，当生成好了上面的这些目录与文件后，用户就可以将工程push到远程，由其他用户clone下来后即可进行项目的构建，非常方便，省却了用户单独下载Gradle的时间，并且可以确保Gradle版本的完全正确。

上面在执行gradle wrapper命令时并没有添加任何参数，所以生成的gradle-wrapper.properties文件的各个属性都是默认的，默认规则如下所示：

gradlew所指定的Gradle版本与使用gradle wrapper命令时所用的Gradle版本一致，如果想要使用其他版本，那么可以在gradle wrapper命令后添加参数：–gradle-version，比如说：

gradle wrapper –gradle-version 3.4

表示gradlew所使用的Gradle版本为3.4，而非使用gradle wrapper时所用的3.5。

–gradle-distribution-url

表示gradlew所使用的Gradle包会从该配置所指定的网络位置处下载（比如说内网地址），而非Gradle官网地址。

–distribution-type

表示下载的Gradle包的类型。默认情况下，gradlew会下载bin分发包，但Gradle还提供了一个all分发包，包含了更多的信息，比如说源代码、二进制文件与文档等。那么，我们就可以通过该配置指定下载包的类型。

除此之外，还可以通过在build.gradle配置文件中定一个task来设定gradlew的各项配置，如下所示：



接下来，再去执行gradle wrapper，执行完毕后查看gradle-wrapper.properties，如下所示：



可以看到，gradle下载包变为了gradle-3.4-all.zip，即all版本。

此外，gradle wrapper还支持通过HTTP Basic认证来配置下载，即指定好用户名与密码，大家可以参考Gradle文档了解相关信息。

最后，Gradle提供了通过SHA-256校验和来验证下载包是否完整的功能，这里描述一下。

比如说，我需要使用gradle-3.4-bin，那就再进入到子目录中，找到gradle-3.4-bin.zip文件，执行如下命令：

shasum -a 256 gradle-3.4-bin.zip

输出如下所示：

72d0cd4dcdd5e3be165eb7cd7bbd25cf8968baf400323d9ab1bba622c3f72205 gradle-3.4-bin.zip

这就表示gradle-3.4-bin.zip的sha-256校验和为72d0cd4dcdd5e3be165eb7cd7bbd25cf8968baf400323d9ab1bba622c3f72205，将其加入到gradle-wrapper.properties文件中，如下所示：

distributionSha256Sum= 72d0cd4dcdd5e3be165eb7cd7bbd25cf8968baf400323d9ab1bba622c3f72205

这样，通过gradlew下载Gradle软件包时，Gradle会自动匹配校验和，确保我们下载的是完整的文件。

总结:

gradlew是Gradle提供的一个非常有用的工具，可以让使用者在事先没有安装Gradle的情况下顺利且轻松地执行Gradle构建任务，对于团队项目构建非常有帮助。这里建议每一个Gradle项目都应加上gradlew配置并将其提交到版本库中。

当其他用户将代码从仓库拉取下来并通过gradlew构建后，后续的所有构建工作依然可以通过gradlew来完成，它的作用与直接使用gradle来构建是完全一致的，包括使用的任务，参数等，完全一致。

注：本文转自圣思园张龙老师

阅读原文