Gradle 基础学习(二) 认识Gradle Wrapper_gradle-wrapper

下图是用Gradle构建项目的过程，但我们并不是直接使用Gradle，而是用Gradle Wrapper。

Gradle Wrapper顾名思义就是Gradle包装器（简称Wrapper），它是对Gradle 的一层包装，那为什么需要Gradle Wrapper呢？

比如在开发团队中，每个成员都需要在计算机上安装Gradle，如果大家都是自己去下载安装Gradle，配置Gradle环境变量，这个时候运行Gradle的环境(比如IDE、 CI、服务器等)和Gradle版本上的差异，会对构建结果带来不确定性。针对这个问题，Gradle提供了一个解决方案，那就是Gradle Wrapper，它是一个脚本，在计算机没有安装Gradle的情况下，执行构建会先下载和配置给定的Gradle发行版，任何后续构建调用会重用已存在本地的发行版，从而帮助开发人员快速启动并运行Gradle项目。

使用Gradle Wrapper，开发人员可以在给定的Gradle版本上标准化一个项目，不再需要手动安装，本地也不用配置 Gradle，提高了开发效率。

Gradle Wrapper的工作流程如下图所示：

1、 执行Gradle构建的时候，会先读取 gradle-wrapper.properties 文件的配置信息，如果给定版本的gradle未安装，自动从服务器下载；

2、下载保存并解压到指定的位置(GRADLE_USER_HOME 目录下的 wrapper/dists 目录中)；

3、下次再使用相同版本的 gradle 就不用下载了，直接用本地版本进行构建；

现在用下面这个典型的Gradle项目布局来说明Wrapper具体是什么。

上图红色框部分就是Wrapper的文件构成，分别来解释它们的目的。

gradle-wrapper.jar

       Wrapper 引导程序JAR文件，包含下载、加载Gradle发行版的代码

gradle-wrapper.properties

       负责配置Wrapper运行时行为的属性文件，比如使用的Gradle版本

gradlew, gradlew.bat 

        一个shell脚本和一个Windows批处理脚本，用于使用Wrapper执行Gradle构建，依赖gradle-wrapper.jar

可以说gradlew的就是Wrapper了，用法跟gradle一模一样，在执行构建的时候总是推荐使用gradlew而不是gradle。

我们实际build看一下

$ ./gradlew build

Downloading https://services.gradle.org/distributions/gradle-8.2-bin.zip

..................10%..................20%...................30%..................40%..................50%...................60%..................70%...................80%..................90%..................100%

BUILD SUCCESSFUL in 1m 52s

7 actionable tasks: 7 up-to-date

我本地还没有gradle-8.2-bin版本，所以先进行了下载，然后再build，下载后的gradle安装在

$GRADLE_USER_HOME/wrapper/dists/gradle-8.2-bin/bbg7u40eoinfdyxsxr3z4i7ta

    —  gradle-8.2

    —  gradle-8.2-bin.zip

    —  gradle-8.2-bin.zip.lck

    —  gradle-8.2-bin.zip.ok

我们再build一次

./gradlew build

BUILD SUCCESSFUL in 21s

7 actionable tasks: 7 up-to-date

项目中已经存在Wrapper的情况下，开发人员可以不用去关心Gradle下载和配置的问题，但是如果没有Wrapper呢？

[添加Gradle Wrapper] 

一种方式是直接从其他项目中拷贝Wrapper文件结构到项目中就可以了，另一种则是完全从无到有的标准方法，使用Gradle来生成。

我们新建一个HelloGradle项目为例来演示如何添加Gradle Wrapper。 

首先需要在计算机上安装Gradle发行版本（ 安装方法参考 Installing Gradle），Gradle是基于JVM的，依赖Java环境，所以机器上也必须安装Java Development Kit (JDK) 版本 8 或更高。

Mac上常用的包管理器安装方式： 

使用Homebrew:

       $ brew install gradle

或者使用MacPorts:

       $ sudo port install gradle

AS在新建项目时会自带Gradle Wrapper，所以我们不需要单独去下载安装Gradle。

安装好后创建项目目录

$ mkdir HelloWorld

$ cd HelloWorld

执行gradle内置的init任务，初始化会帮我们生成gradle构建需要的相关文件，其中就有Wrapper。

$ gradle init 

如果提示错误  

-bash: gradle: command not found

需要在环境变量中增加刚安装好的gradle执行命令所在路径，我用的是AS，gradle会在这个目录(gradle-wrapper.properties文件定义了保存位置)

 export PATH=$PATH:~/.gradle/wrapper/dists/gradle-8.2-bin/bbg7u40eoinfdyxsxr3z4i7ta/gradle-8.2/bin/

其中的bbg7u40eoinfdyxsxr3z4i7ta是Gradle发行版的下载地址的md5值，保证了gradle版本一致性。

或者可能的路径如下

export PATH=$PATH:/usr/local/gradle/gradle-8.2/bin

看到 BUILD SUCCESSFUL 则表示成功了，此时项目的文件结构如下

gradle目录已经存在了，Gradle Wrapper相关文件也自动生成好了，同时还生成了settings.gradle(.kts)， 模块的build.gradle(.kts)等进行gradle构建必须的文件。

以上是一个非gradle构建项目转为gradle构建最简单的方式。如果现有项目使用gradle构建，但是没有用Wrapper的方式，可以通过gradle内置任务wrapper来生成Wrapper文件。

比如我们有个子项目

 $ gradle wrapper

> Task :wrapper

BUILD SUCCESSFUL in 0s

1 actionable task: 1 executed

构建成功后

生成的Wrapper文件都很小，我们需要添加到版本管理中，确保其他成员使用相同的Wrapper来构建项目。

自动生成的gradle-wrapper.properties配置文件内容如下：

distributionBase=GRADLE_USER_HOME

distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip

distributionPath=wrapper/dists

zipStorePath=wrapper/dists

zipStoreBase=GRADLE_USER_HOME

字段的含义如下：

distributionBase：  Gradle解包后存储的主目录。

distributionPath：  distributionBase的子目录。distributionBase+distributionPath就是Gradle解包后的存放位置。

distributionUrl：     Gradle发行版压缩包的下载地址。

zipStoreBase：      Gradle压缩包存储主目录。

zipStorePath：      zipStoreBase的子目录。zipStoreBase+zipStorePath就是Gradle压缩包的存放位置。

注意下载文件可能有gradle-8.2-bin.zip和gradle-8.2-all.zip两种，区别就是前者不带源码和文档，仅包含gradle运行时。

[更新Gradle Wrapper] 

项目通常希望紧跟时代步伐，升级使用的Gradle版本，以受益于新特性和改进。

一种方式是手动修改gradle-wrapper.properties文件中的distributionUrl属性来更新Gradle版本，但最好通过运行wrapper任务来提供目标Gradle版本，wrapper任务如果需要同时会更新其他的Wrapper文件，比如gradle-wrapper.jar，gradlew 和 gradlew.bat。

$./gradlew wrapper --gradle-version 8.2 --distribution-type all

> Task :wrapper

BUILD SUCCESSFUL in 0s

1 actionable task: 1 executed

查看gradle-wrapper.properties中distributionUrl字段已经更新到指定的Gradle发行版了。 

distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-all.zip 

常用的参数如下

--gradle-version    Wrapper下载和执行的Gradle版本， 值可以是具体的版本号，也可以是latest表明用最新版

--distribution-type  Gradle发行版类型，可以是 bin 或者 all， 默认是bin

--gradle-distribution-url  指向Gradle发行版ZIP文件的完整URL。这个选项使—gradle-version和—distribution-type无效，因为URL已经包含了这些信息。

[自定义Gradle Wrapper]

大多数Gradle使用者对Wrapper的默认运行时行为很满意，但是，组织策略、安全约束或个人偏好可能要求我们更深入地定制Wrapper。

Gradle内置的wrapper任务提供了许多选项，可以根据具体需要调整运行时行为。

假设我们项目总是要使用Gradle all发行版，每次通过命令行更新Wrapper的时候都要指定all 分发类型，否则就会错误成默认的bin类型，这很令人厌倦，可以通过重新配置wrapper任务来优化这一行为。

#build.gradle.kts

tasks.wrapper {

    distributionType = Wrapper.DistributionType.ALL

}

配置好后，运行./gradlew wrapper --gradle-version 8.2 生成的gradle-wrapper.properties中就不再是默认的bin而是all分发版了: 

distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-all.zip