Gradle系列之初识Gradle

2020 年 4 月 15 日
筆記
Gradle, Gradle Wrapper, GRADLE_HOME, Gradle命令, Groovy, 躬行之

原文首发于微信公众号：躬行之(jzman-blog)

学习 Android 有一段时间了，开发中经常使用到 Gradle ，但是不知道 Gradle 构建项目的原理，计划花一点时间学习一下 Gradle 相关的知识。Gradle 是一个非常优秀的项目构建工具，其 DSL(领域特定语言)基于 Groovy 实现，大部分功能通过插件的方式来实现，也可以自定义 Gradle 插件，下面开始入门 Gradle 系列的第一篇。

配置 Gradle 环境

首先确保在环境变量中配置好 JAVA_HOME，使用如下命令查看是否配置：

java -version

执行日志如下：

准备一个 Gradle 版本，下载之后进行解压，解压之后的目录说明如下：

bin：gradle批处理文件
docs：说明文档
init.d：初始化的脚本文件
lib：相关库
media：自带的图标资源
samples：案例
src：源文件
getting-started.html：入门指导链接
LICENSE
NOTICE

然后在环境变量中配置 GRADLE_HOME ，具体指的是 Gradle 的解压目录：

然后，添加将 GRADLE_HOME\bin 配置到 Path 中，具体如下：

然后打开控制台，使用命令 gradle -v 查看 Gradle 版本信息，如果能够正确显示 Gradle 版本号、Groovy 版本号、JVM 等相关信息，说明 Gradle 环境已经配置成功，配置成功 gradle -v 执行结果参考如下：

PS E:\Gradle\study> gradle -v
------------------------------------------------------------
Gradle 4.1
------------------------------------------------------------

Build time:   2017-08-07 14:38:48 UTC
Revision:     941559e020f6c357ebb08d5c67acdb858a3defc2

Groovy:       2.4.11
Ant:          Apache Ant(TM) version 1.9.6 compiled on June 29 2015
JVM:          1.8.0_91 (Oracle Corporation 25.91-b14)
OS:           Windows 10 10.0 amd64

此时，Window 上的 Gradle 构建环境就搭建好了。

Gradle 版 Hello World

学习任何一门语言，毫无疑问当然是运行 Hello World ，这里实现一个 Hello World 的 Gradle 脚本，创建一个名为 build.gradle 的脚本，脚本内容如下：

task hello{
	doLast{
		println 'Hello world'
	}
}

使用 gradle -q hello 命令执行上述脚本，结果如下：

PS E:\Gradle\study> gradle -q hello
Hello world

build.gradle 是 Gradle 默认的构建脚本文件，执行命令时会默认加载当前目录下的 build.gradle 脚本文件，这个构建脚本定义了一个名为 hello 的任务（Task），里面的 doLast 是 Task 中的一个 Action，当这个 Task 执行完毕之后要回调 doLast 里面的代码，使用 gradle 命令时的参数 -q 是指定输出的日志级别，关于 gradle 日志输出级别将在下文中介绍。

Gradle Wrapper

Wrapper 是对 Gradle 的一层包装，方便在团队中统一管理 Gradle 的版本，项目开发中通常使用的 Wrapper 这种方式，使用 Wrapper 之后就不需要采用配置 Gradle 的构建环境的方式，使用 Wrapper 启用 Gradle 的时候，Wrapper 会检查 Gradle 有没有下载关联，如果没有下载则从配置的地址下载并进行构建，这就一定程度上方便开发人员构建项目。

生成 Wrapper

Gradle 提供了内置的 Wrapper Task 来生成 Wrapper 所需的目录文件，在相应的目录执行 gradle wrapper 命令即可生成，参考如下：

PS E:\Gradle\study> gradle wrapper

BUILD SUCCESSFUL in 3s
1 actionable task: 1 executed
PS E:\Gradle\study> cd wrapper

使用 gradle wrapper 生成的文件目录如下：

│─gradlew
│─gradlew.bat
└─gradle
    └─wrapper
            gradle-wrapper.jar
            gradle-wrapper.properties

其中 gradlew 和 gradlew.bat 分别是 Linux 和 Window 下的可执行脚本，使用方式和原生的 gradle 命令一样，gradle-wrapper.jar 是根据具体业务实现的 jar 包，gradlew 最终还是通过这个 jar 包来执行相关的 gradle 相关操作，gradle-wrapper.properties 是用来配置使用哪一个版本的 gradle 进行构建操作。

Wrapper 配置

在使用 gradle wrapper 生成相关文件的时候，可以指定 wrapper 要使用的版本号以及 gradle 的下载地址，命令如下：

//指定使用的Gradle版本
gradle wrapper --gradle-version 3.3
//指定下载Gradle的地址
gradle wrapper --gradle-distribution-url ...

Gradle 默认的版本是当前 Gradle 的版本，下载地址参考如下:

https\://services.gradle.org/distributions/gradle-4.1-all.zip

下面来看一看 Gradle 的配置文件 gradle-wrapper.properties 的几个字段含义：

distributionBase //下载的Gradle压缩包解压后存储的主目录
distributionPath //相对于distributionBase解压后压缩包的路径
zipStoreBase //相对于distributionBase存放Gradle压缩包的
zipStorePath //相对于distributionPath存放Gradle压缩包的
distributionUrl //Gradle的下载地址，一般是官网地址

下面是一个 Android 项目的 Gradle 的配置文件，参考如下：

#Mon Dec 28 10:00:20 PST 2015
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-4.1-all.zip

顺便介绍一下几个属性值：

//表示用户目录，用户目录下 .gradle 下的目录
GRADLE_USER_HOME
//表示项目目录，项目底下 gradlew 所在的目录
PROJECT

这两个值可以用来设置 distributionBase 和 zipStoreBase 的值

自定义 Wrapper Task

Gradle 的配置文件 gradle-wrapper.properties 是由 Wrapper Task 生成的，可以不通过自定义 Wrapper Task 可以用来配置 gradle-wrapper.properties 文件，下面是自定义 Wrapper Task 的一个实例，

task wrapper(type: Wrapper){
	gradleVersion = '3.3'
	distributionBase='GRADLE_USER_HOME'
	distributionPath='wrapper/dists'
	//注意不要这样写：https\://services...
	distributionUrl="//services.gradle.org/distributions/gradle-3.3-all.zip"
}

这样可以定义生成 Wrapper 的 Gradle 版本及相关存储目录。

Gradle 日志

使用 Gradle 构建项目时，可以指定日志级别来显示相关的日志信息，Gradle 的日志级别主要有六种，具体如下：

ERROR //错误消息
QUIET //重要消息
WARNING //警告消息
LIFECYCLE //进度消息
INFO //信息消息
DEBUG //调试信息

使用时可以通过命令行的方式控制日志显示级别，下面是可以使用命令控制的日志选项，具体如下：

-q 或 --quiet //表示QUIET及其更高级别
-i 或 --info //表示INFO及其更高级别
-d 或 --debug //DEBUG 及其更高级别（输出所有日志）

如果不指定，则默认输出的日志是 LIFECYCLE 及其更高级别的日志。

日志主要跟踪构建过程以及调试错误，下面介绍在项目构建过程中堆栈信息的输出以及如何使用日志信息来进行调试。

输出堆栈信息

默认情况下，堆栈信息的输出是关闭的，可以通过命令行的堆栈信息开关打开它，当构建失败后，Gradle 会将输出错误的堆栈信息，方便定位和分析问题，具体如下：

-s 或 --stacktrace //输出关键性的堆栈信息
-S 或 --full--stacktrace //输出全部堆栈信息

一般使用 -s 就可以了。

日志信息调试

最简单的日志记录当然是在合适的位置打印想要看的变量即可，可以使用 print 系列方法将日志输出到控制台，这属于 QUIET 级别的日志，也可以使用内置的 logger 来控制不同级别日志的显示，及 DEBUG 输出日志最完整、ERROR 输出日志最少，使用方式参考如下：

//日志测试
task hello{
	doLast{
		println 'Hello world'
		print 'Hi'
		logger.quiet('quiet 日志')
		logger.lifecycle('lifecycle 日志')
		logger.error('error 日志')
		logger.info('info 日志')
		logger.warn('warn 日志')
		logger.debug('debug 日志')
	}
}

Gradle 日志基本内容如上，多在实际项目中实践才是最重要的。

Gradle 命令行

使用命令行在一定程度上了解构建过程，相较在 IDE 上的便捷性，使用命令行可以知其然知其所以然，只要是可以使用命令行的，都可以通过帮助获取命令来查看可执行的命令，参考如下：

gradle -h
gradle -?
gradle -help

可以通过如上命令查看可执行的命令。

查看可执行 Tasks

这里以 Wrapple 为例，可以使用 ./gradlew tasks 查看可执行的 Tasks，执行结果以分组形式输出，一个是关于构建的(Build Setup tasks)，另一个是关于帮助的(Help tasks)，执行结果如下：

PS E:\Gradle\study\wrapper> ./gradlew tasks
:tasks

------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Build Setup tasks
-----------------
init - Initializes a new Gradle build. [incubating]
wrapper - Generates Gradle wrapper files. [incubating]

Help tasks
----------
components - Displays the components produced by root project 'wrapper'. [incubating]
dependencies - Displays all dependencies declared in root project 'wrapper'.
dependencyInsight - Displays the insight into a specific dependency in root project 'wrapper'.
help - Displays a help message.
model - Displays the configuration model of root project 'wrapper'. [incubating]
projects - Displays the sub-projects of root project 'wrapper'.
properties - Displays the properties of root project 'wrapper'.
tasks - Displays the tasks runnable from root project 'wrapper'.

To see all tasks and more detail, run gradlew tasks --all

To see more detail about a task, run gradlew help --task <task>

BUILD SUCCESSFUL

Total time: 8.4 secs

查看某个 Task 的帮助

Gradle 内置一个 help task,这个 Task 可以可以了解某一个 Task 的使用帮助，具体命令如下：

//命令格式
gradle help --task Task名称
//举例
gradle help --task projects

执行结果参考如下：

PS E:\Gradle\study\wrapper> gradle help --task projects

> Task :help
Detailed task information for projects

Path
     :projects

Type
     ProjectReportTask (org.gradle.api.tasks.diagnostics.ProjectReportTask)

Description
     Displays the sub-projects of root project 'wrapper'.

Group
     help


BUILD SUCCESSFUL in 1s
1 actionable task: 1 executed

通过 Task 的帮助信息可以看到当前 Task 的分组、类型以及额外参数。

此外，开发中常常使用第三方库，那么如何强制刷新第三方依赖呢，使用命令构建项目的时候添加参数 –refresh-dependencies，有时候需要同时运行多个任务，可将具体的任务使用空格分开，如 ./gradlew t1 t2，Gradle 提供了基于驼峰命名法的缩写调用，可以使用如下方式简写调用：

//Task
newTask
//命令
./gradlew nt

总结

这是初识 Gradle 的第一篇文章，主要对 Gradle 及相关命令有了一定的了解，也是以后学习 Gradle 构建项目的基础，关于 Gradle 的学习希望能够将这个系列写完。

如果感兴趣，可以关注公众号：躬行之(jzman-blog)，一起交流学习。

Tags: Gradle Gradle Wrapper GRADLE_HOME Gradle命令 Groovy 躬行之