💡
有兴趣配置构建缓存以加快构建速度吗? 在此处注册以参加我们的Build Cache培训课程,以了解顶级工程团队用来提高构建速度的一些技巧.

Gradle提供了多种机制来配置Gradle本身和特定项目的行为. 以下是使用这些机制的参考.

在配置Gradle行为时,您可以使用以下方法,以从高到低的优先级顺序列出(第一个获胜):

  • 命令行标志,例如--build-cache . 这些优先于属性和环境变量.

  • 存储在gradle.properties文件中的系统属性,例如gradle.properties systemProp.http.proxyHost=somehost.org .

  • 诸如org.gradle.caching=true类的Gradle属性通常存储在项目根目录或GRADLE_USER_HOME环境变量中的gradle.properties文件中.

  • 执行Gradle的环境GRADLE_OPTS环境变量,例如GRADLE_OPTS .

除了配置构建环境之外,您还可以使用-PreleaseType=final类的Project属性配置给定的项目构建.

Gradle properties

Gradle提供了几个选项,可以轻松配置将用于执行构建的Java流程. 尽管可以通过GRADLE_OPTSJAVA_OPTS在本地环境中配置这些设置,但将某些设置(例如JVM内存配置和Java主目录位置)存储在版本控制中很有用,这样整个团队就可以在一致的环境中工作.

为构建建立一致的环境就像将这些设置放入gradle.properties文件一样简单. 该配置是所有gradle.properties文件的组合,但是如果在多个位置配置了一个选项,则第一个将获胜

  • 系统属性,例如,在命令行上设置-Dgradle.user.home时.

  • gradle.properties in GRADLE_USER_HOME directory.

  • 工程根目录中的gradle.properties .

  • Gradle安装目录中的gradle.properties .

以下属性可用于配置Gradle构建环境:

org.gradle.caching=(true,false)

设置为true时,Gradle将在可能的情况下重用任何先前构建的任务输出,从而使构建速度更快. 了解有关使用构建缓存的更多信息.

org.gradle.caching.debug=(true,false)

设置为true时,单个输入属性哈希值和每个任务的构建缓存键都记录在控制台上. 了解有关任务输出缓存的更多信息.

org.gradle.configureondemand=(true,false)

启用按需孵化配置 ,Gradle将尝试仅配置必要的项目.

org.gradle.console=(auto,plain,rich,verbose)

自定义控制台输出的颜色或详细程度. 默认值取决于如何调用Gradle. 有关其他详细信息,请参见命令行日志记录 .

org.gradle.daemon=(true,false)

设置为true将使用Gradle Daemon运行构建. 默认值为true .

org.gradle.daemon.idletimeout=(# of idle millis)

Gradle Daemon will terminate itself after specified number of idle milliseconds. Default is 10800000 (3 hours).

org.gradle.debug=(true,false)

设置为true ,Gradle将在启用远程调试的情况下运行构建,侦听端口5005.请注意,这等效于将-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005到JVM命令行,它将挂起虚拟机,直到连接了调试器. 默认值为false .

org.gradle.java.home=(path to JDK home)

指定用于Gradle构建过程的Java主页. 可以将值设置为jdkjre位置,但是,根据您的构建方式,使用JDK更安全. 如果未指定设置,则从您的环境( JAVA_HOMEjava的路径)派生一个合理的默认值. 这不会影响用于启动Gradle客户端VM的Java版本( 请参阅环境变量 ).

org.gradle.jvmargs=(JVM arguments)

指定用于Gradle守护程序的JVM参数. 该设置对于配置JVM内存设置以提高构建性能特别有用. 这不会影响Gradle客户端VM的JVM设置.

org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)

当设置为安静,警告,生命周期,信息或调试时,Gradle将使用此日志级别. 这些值不区分大小写. lifecycle级别是默认级别. 请参阅选择日志级别 .

org.gradle.parallel=(true,false)

配置后,Gradle将派生到org.gradle.workers.max JVM,以并行执行项目. 要了解有关并行任务执行的更多信息,请参阅Gradle性能指南 .

org.gradle.warning.mode=(all,fail,summary,none)

当设置为allsummarynone ,Gradle将使用不同的警告类型显示. 有关详细信息,请参见命令行日志记录选项 .

org.gradle.workers.max=(max # of worker processes)

配置后,Gradle将使用最多给定数量的工人. 默认值为CPU处理器数. 另请参阅性能命令行选项 .

org.gradle.priority=(low,normal)

指定Gradle守护程序及其启动的所有进程的调度优先级. 默认为normal . 另请参阅性能命令行选项 .

下面的示例演示各种属性的用法.

示例1.使用gradle.properties文件设置属性
gradle.properties
gradlePropertiesProp=gradlePropertiesValue
sysProp=shouldBeOverWrittenBySysProp
systemProp.system=systemValue
build.gradle
task printProps {
    doLast {
        println commandLineProjectProp
        println gradlePropertiesProp
        println systemProjectProp
        println System.properties['system']
    }
}
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命令行选项,可以将系统属性传递给运行Gradle的JVM. 所述-D所述的选项gradle命令与相同的效果-D所述的选项java命令.

您还可以在gradle.properties文件中使用前缀gradle.properties设置系统属性systemProp.

gradle.properties指定系统属性
systemProp.gradle.wrapperUser=myuser
systemProp.gradle.wrapperPassword=mypassword

以下系统属性可用. 请注意,命令行选项优先于系统属性.

gradle.wrapperUser=(myuser)

指定用户名以使用HTTP基本认证从服务器下载Gradle发行版. 在身份验证的包装下载中了解更多信息.

gradle.wrapperPassword=(mypassword)

指定使用Gradle包装器下载Gradle发行版的密码.

gradle.user.home=(path to directory)

Specify the Gradle user home directory.

在多项目构建中," systemProp. 在除根目录以外的任何项目中设置的属性都将被忽略. 也就是说,将仅检查根项目的gradle.properties文件中以" gradle.properties "开头的属性systemProp. " 字首.

Environment variables

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

GRADLE_OPTS

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

GRADLE_USER_HOME

指定Gradle用户的主目录(如果未设置,则默认为$USER_HOME/.gradle ).

JAVA_HOME

指定要用于客户端VM的JDK安装目录. 该VM也用于守护程序,除非在Gradle属性文件中使用org.gradle.java.home指定了不同的org.gradle.java.home .

Project properties

您可以通过-P命令行选项将属性直接添加到Project对象.

当Gradle看到特别命名的系统属性或环境变量时,它也可以设置项目属性. 如果环境变量名称看起来像ORG_GRADLE_PROJECT _prop =somevalue ,那么Gradle将在项目对象上设置prop属性,其值为somevalue . Gradle也为系统属性支持此功能,但是具有不同的命名模式,类似于org.gradle.project. prop org.gradle.project. prop . 以下两项都将Project对象上的foo属性设置为"bar" .

通过系统属性设置项目属性
org.gradle.project.foo=bar
通过环境变量设置项目属性
ORG_GRADLE_PROJECT_foo=bar

用户主目录中的属性文件优先于项目目录中的属性文件.

当您对连续集成服务器没有管理员权限并且需要设置不容易看到的属性值时,此功能非常有用. 由于您不能在那种情况下使用-P选项,也不能更改系统级配置文件,因此正确的策略是更改连续集成构建作业的配置,并添加与预期模式匹配的环境变量设置. 这对于系统上的普通用户是不可见的.

您可以像使用变量一样使用名称来访问构建脚本中的项目属性.

如果引用了项目属性但该属性不存在,则将引发异常,并且构建将失败.

在使用Project.hasProperty(java.lang.String)方法访问可选项目属性之前,应检查其是否存在.

Configuring JVM memory

您可以通过以下方式调整Gradle的JVM选项:

org.gradle.jvmargs Gradle属性控制运行构建的VM. 默认为-Xmx512m "-XX:MaxMetaspaceSize=256m"

更改构建VM的JVM设置
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

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

更改客户端VM的JVM设置
JAVA_OPTS="-Xmx64m -XX:MaxPermSize=64m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8"

在一种情况下,客户端VM也可以用作构建VM:如果停用Gradle Daemon ,并且客户端VM具有与构建VM所需的相同设置,则客户端VM将直接运行构建. 否则,客户端虚拟机将派生一个新的虚拟机来运行实际的构建,以便采用不同的设置.

某些任务(例如test任务)也会派生其他JVM进程. 您可以通过任务本身来配置它们. 它们默认都使用-Xmx512m .

示例2.为JavaCompile任务设置Java编译选项
build.gradle
plugins {
    id 'java'
}

tasks.withType(JavaCompile) {
    options.compilerArgs += ['-Xdoclint:none', '-Xlint:none', '-nowarn']
}
build.gradle.kts
plugins {
    java
}

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

请参阅Test API文档中的其他示例,以及Java插件参考中的测试执行 .

使用--scan选项时, 构建扫描将告诉您有关执行构建的JVM的信息.

Build Environment in build scan

Configuring a task using project properties

可以根据调用时指定的项目属性来更改任务的行为.

假设您想确保发布版本仅由CI触发. 一种简单的方法是通过isCI项目属性.

例子3.防止释放到CI外
build.gradle
task performRelease {
    doLast {
        if (project.hasProperty("isCI")) {
            println("Performing release actions")
        } else {
            throw new InvalidUserDataException("Cannot perform release outside of 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

Accessing the web through a HTTP proxy

通过标准JVM系统属性来配置HTTP或HTTPS代理(例如,用于下载依赖项). 这些属性可以直接在构建脚本中设置. 例如,设置HTTP代理主机将通过System.setProperty('http.proxyHost', 'www.somehost.org') . 另外,可以在gradle.properties中指定属性.

使用gradle.properties配置HTTP代理
systemProp.http.proxyHost=www.somehost.org
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=userid
systemProp.http.proxyPassword=password
systemProp.http.nonProxyHosts=*.nonproxyrepos.com|localhost

HTTPS有单独的设置.

使用gradle.properties配置HTTPS代理
systemProp.https.proxyHost=www.somehost.org
systemProp.https.proxyPort=8080
systemProp.https.proxyUser=userid
systemProp.https.proxyPassword=password
systemProp.https.nonProxyHosts=*.nonproxyrepos.com|localhost

您可能需要设置其他属性才能访问其他网络. 这里有2个参考可能会有所帮助:

NTLM Authentication

如果您的代理服务器需要NTLM身份验证,则可能需要提供身份验证域以及用户名和密码. 您可以通过两种方式提供用于向NTLM代理进行身份验证的域:

  • http.proxyUser系统属性设置为domain / username类的值.

  • 通过http.auth.ntlm.domain系统属性提供身份验证域.