gradle多版本实践

在实际的开发工作中，在搭建 gradle 的本地环境时可能需要多个版本，例如，我们需要阅读 spring 项目的源码，但是 spring 的不同项目或者同一项目的不同分支，使用的 gradle 版本都是不同的。

通常情况下，为了节省资源和统一管理，我们会在本地部署某一版本的 gradle，并且将 gradle 的执行目录配置到系统的执行变量中，以便我们在控制台中的任意路径下可以直接使用 gradle 命令执行 gradle 的相关操作。但是，由于 gradle 的（大）版本升级会废弃掉一些功能和插件，在本地如果配置的是比项目指定版本高的 gradle，那么运行 gradle build 命令，可能会导致项目无法构建成功。

官网更推荐使用 gradle wrapper 来进行项目的构建。根据操作系统，您可以运行 gradlew 或 gradlew.bat 而不是 gradle 命令。

gradle-wrapper 介绍

使用 gradle-wrapper 搭建项目的一般结构如下：

├── a-subproject
│   └── build.gradle
├── settings.gradle
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
└── gradlew.bat

gradle-wrapper 主要文件介绍：

  • gradle-wrapper.jar：包含用于下载 Gradle 发行版的 Wrapper JAR 文件。
  • gradle-wrapper.properties：负责配置 Wrapper 运行时行为的属性文件，例如与此版本兼容的 Gradle 版本。请注意，更通用的设置，例如配置 Wrapper 使用的代理，需要进入不同的文件。
  • gradlew, gradlew.bat：用于使用 Wrapper 执行构建的 shell 脚本和 Windows 批处理脚本。

gradle-wrapper.properties 介绍

以下为 spring 某项目的 gradle-wrapper.properties 内容：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-6.8.2-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionSha256Sum=8de6efc274ab52332a9c820366dd5cf5fc9d35ec7078fd70c8ec6913431ee610
  • distributionBase：gradle 压缩文件解压的基础路径。该值取的是环境变量 GRADLE_USER_HOME 的值，查找 gradle 配置的全局用户目录。
  • distributionUrl：配置要下载的 gradle 地址。
  • 远程下载：设置远程 web 服务器的下载路径，可以进行如下的配置：https\://services.gradle.org/distributions/gradle-6.8.2-bin.zip。
  • 本地下载：需要将 gradle 预先下载到本地，然后设置为本地路径，例如：file\:///D:/DevEnvironment/gradle-zip/gradle-6.9.2-all.zip。
  • distributionPath：gradle 压缩文件解压的相对路径，绝对路径为 distributionBase 和 distributionPath 的组合。
  • zipStoreBase：gradle 压缩文件下载的基础路径。该值取的是环境变量 GRADLE_USER_HOME 的值，查找 gradle 配置的全局用户目录。
  • zipStorePath：gradle 压缩文件下载的相对路径，绝对路径为 zipStoreBase 和 zipStorePath 的组合。
  • distributionSha256Sum：gradle 文件的校验码。

下载位置可以和解压位置不一样。

zipStoreBase 和 distributionBase 有两种取值：

  • GRADLE_USER_HOME：表示用户目录，请参考设置环境变量章节的描述。
  • PROJECT：表示工程的当前目录，即 gradlew 所在的目录。

gradle-wrapper 实践

1. 设置环境变量

要使用 gradle-wrapper，最好设置下环境变量 GRADLE_USER_HOME，该变量是 gradle 配置的全局用户目录，默认目录为 $USER_HOME/.gradle，build cache会使用此目录。例如我配置的为 D:\DevEnvironment\gradle-repo。

GRADLE_USER_HOME 如果没有显示设置变量，默认值如下：

  • 在 windows 下是 %USERPROFILE%/.gradle，例如 C:\Users\<user_name>\.gradle\。
  • 在 linux 下是 $HOME/.gradle，例如 ~/.gradle。

2. 下载多个大版本的 gradle

通常情况下，大版本的升级通常会发生功能和插件的废弃，小版本基本是修复bug。所以我提前下载多个不同大版本的 gradle，然后缓存到本地一个固定目录下，例如 D:\DevEnvironment\gradle-zip，列表如下：

├──gradle-4.10.3-all.zip
├──gradle-4.10.3-all.zip.sha256
├──gradle-5.6.4-all.zip
├──gradle-5.6.4-all.zip.sha256
├──gradle-6.9.2-all.zip
├──gradle-6.9.2-all.zip.sha256
├──gradle-7.4.2-all.zip
├──gradle-7.4.2-all.zip.sha256

下载多个不同大版本的目的是让 gradle-wrapper 使用本地缓存的 gradle 文件，不必再去联网下载。同时每个大版本可以保证提供某项目在该大版本下的构建任务可以成功。

3. 修改项目的 gradle-wrapper.properties 文件

在第2步已下载多个大版本的前提下，不同的项目我们需要编辑 gradle-wrapper.properties 文件，主要替换2个配置：

  • distributionUrl：首先根据当前值的大版本号，例如为 gradle-6.8.2-bin.zip，查找本地的大版本 6.x.x 的压缩文件，同时将远程下载地址替换为本地下载地址，例如 distributionUrl=file\:///D:/DevEnvironment/gradle-zip/gradle-6.9.2-all.zip。
  • distributionSha256Sum：替换为 distributionUrl 设置的版本号文件的校验码。

某项目的原始 gradle-wrapper.properties 文件：

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

替换后的文件：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=file\:///D:/DevEnvironment/gradle-zip/gradle-6.9.2-all.zip
distributionSha256Sum=8bde5c859a3ddf5d127ac77465fc24fa8a831d3d8d49e8248548f2cb87485ef1

现在如果有新的 gradle 项目，我们只需要进行第3步的操作，修改项目的 gradle-wrapper.properties 文件，设置匹配的大版本 gradle，这样即节省了网络下载的开销，也可以减少很多小版本的 gradle 的存储空间。大大提升配置和开发的效率。

4. gradle 版本介绍

gradle-7.4.2-all：

文件：gradle-7.4.2-all.zip
sha256: e6d864e3b5bc05cc62041842b306383fc1fefcec359e70cebb1d470a6094ca82

gradle-6.9.2-all：

文件：gradle-6.9.2-all.zip
sha256: 8bde5c859a3ddf5d127ac77465fc24fa8a831d3d8d49e8248548f2cb87485ef1

gradle-5.6.4-all：

文件：gradle-5.6.4-all.zip
sha256: abc10bcedb58806e8654210f96031db541bcd2d6fc3161e81cb0572d6a15e821

gradle-4.10.3-all：

文件：gradle-4.10.3-all.zip
sha256: 336b6898b491f6334502d8074a6b8c2d73ed83b92123106bd4bf837f04111043

参考