Gradle手札之Properties配置

Gradle 很多构建属性可以通过 Properties 来设置。Properties 文件格式可由 java.util.Properties 解析，其中包含若干键值对，类似 Map<String,String> 格式数据来存储。

配置构建环境

根据官方介绍，Gradle 提供了多种方式和机制来配置 Gradle 自身或者特定项目的行为。常见的有以下几种方式，优先级分别从高到低排列：

• 命令行参数 flags：例如，我们希望在执行构建任务时开启构建缓存，只需要加上 --build-cache flag 参数即可（该配置要优先于 Properties 和环境变量生效，e.g, 我们在 gradle.properties 中配置的 org.gradle.caching=false 将会被此处的 flag 覆盖生效）。
• 系统属性：例如，存储在 gradle.properties 文件中的 systemProp.http.proxyHost=somehost.org 属性。
• Gradle 属性：例如，org.gradle.caching=true 通常存储在项目根目录的 gradle.properties 文件或用户 GRADLE_USER_HOME 下的环境变量中。
• 环境变量：例如由执行 Gradle 的环境提供的 GRADLE_OPTS。
• 项目属性：例如我们可以使用项目属性（如 -PbuildType=release 来配置指定项目的构建过程。

下面来一一介绍它们的用法和使用场景。

Gradle properties

Gradle 提供了一些相关选项用于配置执行构建任务的 Java 进程。当然，我们也可以在本地环境中通过 GRADLE_OPTS 或者 JAVA_OPTS 来配置这些选项，但显然在版本控制中存储一些诸如 JVM 内存大小和 JDK 存储位置等配置对于整个团队来说会很有帮助。为此，我们可以将这些配置放入能够接受版本控制工具管辖的 gradle.properties 文件中。比如下面这样：

gradle.properties:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
# When configured, Gradle will run in incubating parallel mode.
# This option should only be used with decoupled projects. More details, visit
# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
# org.gradle.parallel=true
# AndroidX package structure to make it clearer which packages are bundled with the
# Android operating system, and which are packaged with your app"s APK
# https://developer.android.com/topic/libraries/support-library/androidx-rn
android.useAndroidX=true
# Kotlin code style for this project: "official" or "obsolete":
kotlin.code.style=official
# Enables namespacing of each library's R class so that its R class includes only the
# resources declared in the library itself and none from the library's dependencies,
# thereby reducing the size of the R class for that library
android.nonTransitiveRClass=true

Gradle 同时支持在命令行和 gradle.properties 文件中来配置以上选项，一般来说，命令行上设置的属性优先级总是最高的，而 gradle.properties 文件因其存放位置有所差异导致其优先级也略有不同。以下是按照优先级从高到低排列的：

• 通过命令行设置环境选项，如：-P / --project-prop
• GRADLE_USER_HOME 目录下的 gradle.properties 文件
• 项目根目录下的 gradle.properties 文件
• Gradle 安装目录下的 gradle.properties 文件

值得注意的是，Gradle 用户目录的位置是可以通过命令行上传递的 -Dgradle.user.home 系统属性来预先更改的。

以下是常见可用于配置 Gradle 构建环境的相关属性：

除了以上内置的配置属性，我们当然也可以在 gradle.properties 中来自定义属性，例如：

1
2
publishType=local
releaseRepoUrl=https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/

获取自定义属性也很简单，只需要调用如下方法即可：

1
2
3
4
val repoUrl = project.properties.get("releaseRepoUrl")
val publishType = project.properties.get("publishType")
System.out.println(repoUrl)
System.out.println(publishType)

系统属性（System Properties）

使用 -D 命令行选项，您可以将系统属性传递给运行 Gradle 的 JVM。 gradle 命令的 -D 选项与 java 命令的 -D 选项作用相同。我们还可以在 gradle.properties 文件中使用前缀 systemProp 设置系统属性。

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

值得注意的是，通过命令行方式传递系统属性优先级总是高于在 gradle.properties 中设置系统属性。目前常见的系统属性主要有：

需要注意的是，在多项目构建中，如果使用 “systemProp”， 除根目录下 gradle.properties 以外的任何项目中设置的系统属性都将被忽略。 也就是说，只会检查根项目的 gradle.properties 文件中以“systemProp”开头的属性。

此外，我们也可以通过 System.setProperty('http.proxyHost', 'www.somehost.org') 来同样达到指定系统属性的效果。

Gradle Wrapper 其实是一个用于管理 Gradle 版本的脚本工具，基于此，开发人员可以快速启动并运行 Gradle 项目，而无需遵循手动安装过程。

环境变量

以下环境变量可用于 gradle 命令。 请注意，命令行选项和系统属性优先于环境变量生效。

GRADLE_OPTS

指定启动 Gradle 客户端 VM 时要使用的 JVM 参数。 客户端 VM 仅处理命令行输入/输出，因此很少需要更改其 VM 参数。 实际构建由 Gradle 守护程序进行，不受此环境变量的影响。

GRADLE_USER_HOME

指定 Gradle 用户主目录（如果未设置，则默认为 $USER_HOME/.gradle ）。

JAVA_HOME

指定用于客户端 VM 的 JDK 安装目录。 此 VM 也用于守护进程，除非在带有 org.gradle.java.home 的 Gradle 属性文件中指定了不同的 VM。

项目属性（Project Properties）

您可以通过 -P 命令行选项将属性直接添加到自己的项目对象。Gradle 还可以在看到特殊命名的系统属性或环境变量时自动设置项目属性。 如果环境变量名称看起来像 ORG_GRADLE_PROJECT_prop=somevalue，那么 Gradle 将在您的项目对象上设置一个 prop 属性，其值为 somevalue。 Gradle 也支持系统属性，但命名模式不同，类似于 org.gradle.project.prop。 以下两项都将您的 Project 对象上的 foo 属性设置为 “bar”。

通过系统属性设置项目属性

1
org.gradle.project.foo=bar

通过环境变量设置项目属性

1
ORG_GRADLE_PROJECT_foo=bar

用户主目录中的 gradle.properties 优先于项目目录中的 gradle.properties 文件生效。

当你没有持续集成服务器的管理员权限并且您需要设置不易看到的属性值时，此功能非常有用。 由于我们不能在该场景中使用 -P 选项，也不能更改系统级配置文件，因此正确的策略是更改持续集成构建作业的配置，添加与预期模式匹配的环境变量设置。 这对系统上的普通用户是不可见的。我们可以像使用变量一样使用其名称来访问构建脚本中的项目属性。

如果引用了项目属性但不存在，则会引发异常并且构建将失败。在使用 Project.hasProperty(java.lang.String) 方法访问可选项目属性之前，应该先检查它们是否存在。

配置 JVM 参数

我们可以通过以下两种方式来调整 Gradle 的 JVM 参数选项：

更改构建 VM 的 JVM 配置

org.gradle.jvmargs 这个 Gradle 属性用于控制运行构建的 VM，它的默认值是 -Xmx512m "-XX:MaxMetaspaceSize=256m"。

我们可以通过以下方式自定义构建 VM 的参数：

1
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

修改客户端 VM 的 JVM 配置

JAVA_OPTS 环境变量控制命令行客户端，仅用于显示控制台输出。 默认为 -Xmx64m。

1
JAVA_OPTS="-Xmx64m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8"

在这种情况下，客户端 VM 也可以用作构建 VM：如果我们停用 Gradle 守护程序并且客户端 VM 与构建 VM 所需的设置，则客户端 VM 将直接运行构建。 否则，客户端 VM 将派生一个新 VM 来执行实际构建，以支持不同的配置。

对于某些任务，如测试任务，也会派生额外的 JVM 进程，我们可以在配置任务时传递这些参数。 他们都默认使用-Xmx512m。

例如，我们可以给 JavaCompile 类型的 Task 设置 Java 编译参数：

1
2
3
4
5
6
7
plugins {
    java
}

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

通过 Build Scans 我们也可以直接了解到执行构建过程所基于的 JVM 配置信息，只需要执行 --scan 即可：

基于项目属性配置 Task

某些场景下，我们希望可以在任务调用时根据指定的项目属性来更改任务的行为。假设我们希望确保发布构建仅由 CI 触发，处理此问题的一种简单方法是通过设置 isCI 项目属性，然后在任务执行逻辑中获取该属性并在 isCI 为 true 的情况下执行发布逻辑：

1
2
3
4
5
6
7
8
9
tasks.register("performRelease") {
    doLast {
        if (project.hasProperty("isCI")) {
            println("Performing release actions")
        } else {
            throw InvalidUserDataException("Cannot perform release outside of CI")
        }
    }
}

此外，我们也可以通过 StartParameter 来获取项目属性或者系统属性：

1
2
3
4
5
6
if (project.gradle.startParameter.projectProperties.containsKey('isCI')) {
    println("Execute with CI config")
}
if (project.gradle.startParameter.systemPropertiesArgs.containsKey('gpgSecring')) {
    println("Get system properties.")
}

只需要在命令行参数中指定 -D 即可：

1
./gradlew performRelease -PisCI=true -DgpgSecring=/Users/dorck/demo/secring.gpg --quiet

相关参考

• https://docs.gradle.org/current/userguide/build_environment.html

许可协议: 署名-非商业性使用-禁止演绎 4.0 国际 转载请保留原文链接及作者。

• Previous
  Git用户手札
• Next
  把数组排成最小的数