Gradle（二） build 环境配置

Zoypdong
6,635 阅读3分钟

Gradle build 环境配置

Gradle 提供了多种机制来配置 Gradle build 进程和 Gradle 所构建的 Project 的行为

我们可以使用下面几种方式来配置 Gradle，优先级从高到低：

  • 命令行参数 例如：--build-cache
  • System properties 例如存储在 gradle.properties 文件中的systemProp.http.proxyHost=somehost.org 参数
  • Gradle properties 存储在项目根目录下的 gradle.properties 文件中的参数或者是 GRADLE_USER_HOME下的环境变量
  • Environment variables 例如GRADLE_OPTS是由执行 Gradle 的环境提供的。

除了可以配置 Gradle 构建环境之外，还可以给 Project 对象添加自定义属性，(例如 -PreleaseType=final)来给参与构建的项目添加 releaseType 属性,它的值为 final。

Gradle properties

因为 Gradle build 程序是运行在 Java 虚拟机上的，Gradle 提供了多种可选项来配置 Java 虚拟机的执行参数，有时候调整 Java 虚拟机的参数对 Gradle build 的构建速度提升有非常大的帮助

另外在版本控制中存储某些设置(如JVM内存配置和Java home位置)是很有用的，这样整个团队就可以在一致的环境中工作。

为Gradle 配置一致的构建环境就像将这些设置放入gradle.properties文件一样简单。该配置是所有gradle.properties文件的并集，但是如果在多个文件中配置了一个选项，则优先级高的获胜，以下优先级从高到低：

  • System properties

  • gradle.properties 在GRADLE_USER_HOME目录中。

  • gradle.properties 在项目根目录中。

  • gradle.properties 在Gradle安装目录中。

下面是一些用于配置 Gradle 构建环境的一些常用参数

  • org.gradle.caching=(true,false)
    当设置为 true 时，Gradle 将使用上一次构建的 Task outputs，这个选项通常会让构建更快。
  • org.gradle.caching.debug=(true,false)
    当设置为true时，每个 Task 的 Input 的 hash 值和与之对应的构建缓存 Key 会打印在在控制台上
  • org.gradle.console=(auto,plain,rich,verbose)
    自定义控制台输出的颜色或详细程度。默认值取决于Gradle的调用方式
  • org.gradle.daemon=(true,false) 当设置为 true 时，将会启用 Gradle 的守护进程，推荐开启，这将会大大减少多次构建的重复初始化 的资源消耗
  • org.gradle.daemon.idletimeout=(# of idle millis)
    在指定的空闲毫秒数后，Gradle守护程序将自行终止。默认值为10800000（3小时）
  • org.gradle.debug=(true,false)
    设置true为时，Gradle将在启用远程调试的情况下运行构建，侦听端口5005。
  • org.gradle.java.home=(path to JDK home)
    为 Gradle 的构建进程指定 Java Home，这里的值可以是 jdk 也可以是 jre 的位置，但最好使用 Jdk。如果此项未被设置那么将会从当前环境中获取Java_HOME的值。
  • org.gradle.jvmargs=(JVM arguments) 重要
    配置 JVM 的参数，在这里配置 JVM 的内存配置对提升 Gradle 构建的表现很有用。这里的参数不会影响 Gradle 客户端的虚拟机（这个概念之后应该会提到） 在这里可以配置 JVM 最大堆内存等等，参数之间以空格分离，以-开头，详情参考下方 配置 JVM 内存参数
  • org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)
    设置 log 的Level，默认值为 lifecycle，不区分大小写
  • org.gradle.parallel=(true,false)
    当设置为true之后，JVM 将会使用 org.gradle.workers.max 所设置的工作进程数来并行的执行构建
  • org.gradle.workers.max=(max # of worker processes)
    指定 Gradle 最多使用的工作进程数。默认值为CPU的处理器数
  • org.gradle.priority=(low,normal)
    指定 Gradle 守护进程及其启动的所有进程的调度优先级，默认为 normal
  • org.gradle.vfs.verbose=(true,false)
    配置查看文件系统的详细日志记录，默认关闭
  • org.gradle.warning.mode=(all,fail,summary,none)
    可以配置不同类型的 warining mode

下面是一个例子：
Example 1. Setting properties with a gradle.properties file

#gradle.properties

gradlePropertiesProp=gradlePropertiesValue
sysProp=shouldBeOverWrittenBySysProp
systemProp.system=systemValue

// file：build.gradle.kts
// Project properties can be accessed via delegation

val commandLineProjectProp: String by project
val gradlePropertiesProp: String by project
val systemProjectProp: String by project

tasks.register("printProps") {
    doLast {
        println(commandLineProjectProp)
        println(gradlePropertiesProp)
        println(systemProjectProp)
        println(System.getProperty("system"))
    }
}

输出为：

$ gradle -q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle.project.systemProjectProp=systemPropertyValue printProps
commandLineProjectPropValue
gradlePropertiesValue
systemPropertyValue
systemValue

System properties

我们可以使用 -D 的命令行 option 来给运行 Grade 的 JVM 传递 System properties 参数

除了使用命令行，我们也可以在 gradle.properties 文件中添加 System properties，只需要加上systemProp.前缀：

systemProp.gradle.wrapperUser=myuser
systemProp.gradle.wrapperPassword=mypassword

下面是一些有效的 System properties：

  • gradle.wrapperUser=(myuser)
    指定用户名以使用HTTP基本认证从服务器下载Gradle发行版
  • gradle.wrapperPassword=(mypassword)
    指定使用Gradle wrapper 下载Gradle发行版的密码。
  • gradle.user.home=(path to directory)
    指定Gradle用户的主目录。

注： 如果这是一个多项目的构建，也就是说在 settings.gradle 文件中 include 多个子项目。那么 “systemProp.” properties 只会读取根目录而其他子项目下的将会被忽略，也就是说如果我们想要添加 “systemProp.” properties，必须在根目录下的 gradle.properties 文件中添加。

Environment variables

下面有三个用于Gradle Command 的环境变量

  • GRADLE_OPTS
    指定启动Gradle客户端虚拟机时使用的JVM参数。客户端虚拟机只处理命令行的输入/输出，所以很少需要更改其VM选项。实际的构建是由Gradle守护进程运行的，它不受这个环境变量的影响。
  • GRADLE_USER_HOME
    指定Gradle的用户主目录
  • JAVA_HOME
    指定客户端虚拟机使用的JDK安装目录，这个 JDK 安装目录也用于 Gradle 守护进程，除非用org.gradle.java.home在Gradle属性文件中指定了不同的虚拟机。

Project perperties

对于 Project，如果没有了解过 Gradle 的同学可能有些陌生，这里就先简单介绍下：一个Gradle 构建至少生成一个 Project 对象，一个 Project 对象就对应一个参与构建的项目，那么相对应的，一个Projct 中就会有很多的 Task。

我们可以通过-P命令行选项直接向 Project 对象添加属性。

我们可以通过System properties 或者 Environment variables 添加一些自定义属性，Gradle 就可以将这些自定义属性添加到 Project 属性中。
例如当我们设置了一个环境变量：ORG_GRADLE_PROJECT_prop=somevalue，那么 Gradle 就会设置一个名为 prop 的属性，它的值为 "somevalue"，注意这里的前缀ORG_GRADLE_PROJECT。Gradle 也支持通过设置 System properties 来给 Project 对象添加属性，只是属性的前缀不同，为：org.gradle.project。就像 org.gradle.project.prop，也可以给 Project 添加一个名为 prop 的属性

  • system property
org.gradle.project.foo=bar
  • environment variable
ORG_GRADLE_PROJECT_foo=bar

我们可以直接在 build script 中来使用这些自定义属性

配置 JVM 内存参数

我们可以用下面的方式来调整 JVM 参数

Gradle properties：org.gradle.jvmargs 的默认值为：-Xmx512m "-XX:MaxMetaspaceSize=256m"

  • 配置 Gradle 的 build 虚拟机内存参数的例子
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
  • 配置 Gradle 的 客户端虚拟机内存参数的例子（通常不需要改变）
    Gradle 的客户端 仅仅用于输入和控制台的输出等，默认值为：-Xmx64m
JAVA_OPTS="-Xmx64m -XX:MaxPermSize=64m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8"

某些任务，比如 test 任务，也会fork额外的JVM进程。您可以通过任务本身来配置这些任务。默认情况下，它们都使用-Xmx512m。

//build.gradle.kts

plugins {
    java
}

tasks.withType<JavaCompile>().configureEach {
    options.compilerArgs = listOf("-Xdoclint:none", "-Xlint:none", "-nowarn")
}

使用 Project 属性来配置 Task

我们可以通过添加 Project 属性来完成某些特殊功能，比如我们现在想让 Release build 只由 CI 触发，那么可以这么写：

//build.gradle.kts

tasks.register("performRelease") {
    doLast {
        if (project.hasProperty("isCI")) {
            println("Performing release actions")
        } else {
            throw InvalidUserDataException("Cannot perform release outside of CI")
        }
    }
}

$ gradle performRelease -PisCI=true --quiet
Performing release actions
avatar
文章
阅读
粉丝