Build Environment
Interested in configuring your Build Cache to speed up builds? Register here for our Build Cache training session to learn some of the tips and tricks top engineering teams are using to increase build speed. |
Gradle provides multiple mechanisms for configuring behavior of Gradle itself and specific projects. The following is a reference for using these mechanisms.
When configuring Gradle behavior you can use these methods, listed in order of highest to lowest precedence (first one wins):
-
Command-line flags such as
--build-cache
. These have precedence over properties and environment variables. -
System properties such as
systemProp.http.proxyHost=somehost.org
stored in agradle.properties
file in a root project directory. -
Gradle properties such as
org.gradle.caching=true
that are typically stored in agradle.properties
file in a project directory or in theGRADLE_USER_HOME
. -
Environment variables such as
GRADLE_OPTS
sourced by the environment that executes Gradle.
Aside from configuring Gradle behavior you can configure the build using the same mechanisms and reading the environment from the build logic.
Gradle properties
Gradle provides several options that make it easy to configure the Java process that will be used to execute your build. While it’s possible to configure these in your local environment via GRADLE_OPTS
or JAVA_OPTS
, it is useful to be able to store certain settings like JVM memory configuration and Java home location in version control so that an entire team can work with a consistent environment. To do so, place these settings into a gradle.properties
file committed to your version control system.
The final configuration taken into account by Gradle is a combination of all Gradle properties set on the command line and your gradle.properties
files. If an option is configured in multiple locations, the first one found in any of these locations wins:
-
command line, as set using
-D
. -
gradle.properties
inGRADLE_USER_HOME
directory. -
gradle.properties
in the project’s directory, then its parent project’s directory up to the build’s root directory. -
gradle.properties
in Gradle installation directory.
Note that the location of the Gradle user home may have been changed beforehand via the -Dgradle.user.home
system property passed on the command line.
The following properties can be used to configure the Gradle build environment:
org.gradle.caching=(true,false)
-
When set to true, Gradle will reuse task outputs from any previous build, when possible, resulting in much faster builds. Learn more about using the build cache. By default, the build cache is not enabled.
org.gradle.caching.debug=(true,false)
-
When set to true, individual input property hashes and the build cache key for each task are logged on the console. Learn more about task output caching. Default is
false
. org.gradle.configureondemand=(true,false)
-
Enables incubating configuration on demand, where Gradle will attempt to configure only necessary projects. Default is
false
. org.gradle.console=(auto,plain,rich,verbose)
-
Customize console output coloring or verbosity. Default depends on how Gradle is invoked. See command-line logging for additional details.
org.gradle.continuous.quietperiod=(# of quiet period millis)
-
When using continuous build, Gradle will wait for the quiet period to pass before triggering another build. Any additional changes within this quiet period restart waiting for the quiet period. Default is
250
milliseconds. org.gradle.daemon=(true,false)
-
When set to
true
the Gradle Daemon is used to run the build. Default istrue
, builds will be run using the daemon. 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)
-
When set to
true
, Gradle will run the build with remote debugging enabled, listening on port 5005. Note that this is the equivalent of adding-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005
to the JVM command line and will suspend the virtual machine until a debugger is attached. Default isfalse
. org.gradle.debug.host=(host address)
-
Specifies the host address to listen on or connect to when debug is enabled. In the server mode on Java 9 and above, passing
*
for the host will make the server listen on all network interfaces. By default, no host address is passed to JDWP, so on Java 9 and above, the loopback address is used, while earlier versions listen on all interfaces. org.gradle.debug.port=(port number)
-
Specifies the port number to listen on when debug is enabled. Default is
5005
. org.gradle.debug.server=(true,false)
-
If set to
true
and debugging is enabled, Gradle will run the build with the socket-attach mode of the debugger. Otherwise, the socket-listen mode is used. Default istrue
. org.gradle.debug.suspend=(true,false)
-
When set to
true
and debugging is enabled, the JVM running Gradle will suspend until a debugger is attached. Default istrue
. org.gradle.java.home=(path to JDK home)
-
Specifies the Java home for the Gradle build process. The value can be set to either a
jdk
orjre
location, however, depending on what your build does, using a JDK is safer. This does not affect the version of Java used to launch the Gradle client VM (see Environment variables). A reasonable default is derived from your environment (JAVA_HOME
or the path tojava
) if the setting is unspecified. org.gradle.jvmargs=(JVM arguments)
-
Specifies the JVM arguments used for the Gradle Daemon. The setting is particularly useful for configuring JVM memory settings for build performance. This does not affect the JVM settings for the Gradle client VM. The default is
-Xmx512m "-XX:MaxMetaspaceSize=256m"
. org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)
-
When set to quiet, warn, lifecycle, info, or debug, Gradle will use this log level. The values are not case sensitive. See Choosing a log level. The
lifecycle
level is the default. org.gradle.logging.stacktrace=(internal,all,full)
-
Specifies whether stacktraces should be displayed as part of the build result upon an exception. See also the --stacktrace command-line option. When set to
internal
, a stacktrace is present in the output only in case of internal exceptions. When set toall
orfull
, a stacktrace is present in the output for all exceptions and build failures. Usingfull
doesn’t truncate the stacktrace, which leads to a much more verbose output. Default isinternal
. org.gradle.parallel=(true,false)
-
When configured, Gradle will fork up to
org.gradle.workers.max
JVMs to execute projects in parallel. To learn more about parallel task execution, see the section on Gradle build performance. Default isfalse
. org.gradle.priority=(low,normal)
-
Specifies the scheduling priority for the Gradle daemon and all processes launched by it. See also performance command-line options. Default is
normal
. org.gradle.vfs.verbose=(true,false)
-
Configures verbose logging when watching the file system. Default is
false
. org.gradle.vfs.watch=(true,false)
-
Toggles watching the file system. When enabled Gradle re-uses information it collects about the file system between builds. Enabled by default on operating systems where Gradle supports this feature.
org.gradle.warning.mode=(all,fail,summary,none)
-
When set to
all
,summary
ornone
, Gradle will use different warning type display. See Command-line logging options for details. Default issummary
. org.gradle.welcome=(never,once)
-
Controls whether Gradle should print a welcome message. If set to never then the welcome message will be suppressed. If set to once then the message is printed once for each new version of Gradle. Default is
once
. org.gradle.workers.max=(max # of worker processes)
-
When configured, Gradle will use a maximum of the given number of workers. See also performance command-line options. Default is number of CPU processors.
The following examples demonstrate how to use Gradle properties.
gradlePropertiesProp=gradlePropertiesValue
gradleProperties.with.dots=gradlePropertiesDottedValue
// Using the API, provides a lazy Provider<String>
println(providers.gradleProperty("gradlePropertiesProp").get())
// Using Kotlin delegated properties on `settings`
val gradlePropertiesProp: String by settings
println(gradlePropertiesProp)
// Using the API, provides a lazy Provider<String>
println(providers.gradleProperty("gradlePropertiesProp").get())
// Using Kotlin delegated properties on `project`
val gradlePropertiesProp: String by project
println(gradlePropertiesProp)
// Using the API, provides a lazy Provider<String>
println providers.gradleProperty('gradlePropertiesProp').get()
// Using Groovy dynamic names
println gradlePropertiesProp
println settings.gradlePropertiesProp
// Using Groovy dynamic array notation on `settings`
println settings['gradlePropertiesProp']
// Using the API, provides a lazy Provider<String>
println providers.gradleProperty('gradlePropertiesProp').get()
// Using Groovy dynamic names
println gradlePropertiesProp
println project.gradlePropertiesProp
// Using Groovy dynamic array notation on `project`
println project['gradlePropertiesProp']
The Kotlin delegated properties are part of the Gradle Kotlin DSL.
You need to explicitly specify the type as String
.
If you need to branch depending on the presence of the property, you can also use String?
and check for null
.
Note that if a Gradle property has a dot in its name, using the dynamic Groovy names is not possible. You have to use the API or the dynamic array notation instead.
tasks.register<PrintValue>("printProperty") {
// Using the API, provides a lazy Provider<String> wired to a task input
inputValue.set(providers.gradleProperty("gradlePropertiesProp"))
}
tasks.register('printProperty', PrintValue) {
// Using the API, provides a lazy Provider<String> wired to a task input
inputValue = providers.gradleProperty('gradlePropertiesProp')
}
$ gradle -DgradlePropertiesProp=commandLineValue
Note that initialization scripts can’t read Gradle properties directly.
The earliest Gradle properties can be read in initialization scripts is on settingsEvaluated {}
:
settingsEvaluated {
// Using the API, provides a lazy Provider<String>
println(providers.gradleProperty("gradlePropertiesProp").get())
// Using Kotlin delegated properties on `settings`
val gradlePropertiesProp: String by this
println(gradlePropertiesProp)
}
settingsEvaluated { settings ->
// Using the API, provides a lazy Provider<String>
println settings.providers.gradleProperty('gradlePropertiesProp').get()
// Using Groovy dynamic names
println settings.gradlePropertiesProp
// Using Groovy dynamic array notation on `settings`
println settings['gradlePropertiesProp']
}
Properties declared in a gradle.properties
file present in a subproject directory are only available to that project and its children.
System properties
Using the -D
command-line option, you can pass a system property to the JVM which runs Gradle. The -D
option of the gradle
command has the same effect as the -D
option of the java
command.
You can also set system properties in gradle.properties
files with the prefix systemProp.
systemProp.gradle.wrapperUser=myuser systemProp.gradle.wrapperPassword=mypassword
The following system properties are available. Note that command-line options take precedence over system properties.
gradle.wrapperUser=(myuser)
-
Specify user name to download Gradle distributions from servers using HTTP Basic Authentication. Learn more in Authenticated wrapper downloads.
gradle.wrapperPassword=(mypassword)
-
Specify password for downloading a Gradle distribution using the Gradle wrapper.
gradle.user.home=(path to directory)
-
Specify the Gradle user home directory.
https.protocols
-
Specify the supported TLS versions in a comma separated format. For example:
TLSv1.2,TLSv1.3
.
In a multi project build, “systemProp.
” properties set in any project except the root will be ignored. That is, only the root project’s gradle.properties
file will be checked for properties that begin with the “systemProp.
” prefix.
The following examples demonstrate how to use System properties.
systemProp.system=gradlePropertiesValue
// Using the Java API
println(System.getProperty("system"))
// Using the Java API
println(System.getProperty("system"))
// Using the Gradle API, provides a lazy Provider<String>
println(providers.systemProperty("system").get())
// Using the Java API
println(System.getProperty("system"))
// Using the Gradle API, provides a lazy Provider<String>
println(providers.systemProperty("system").get())
// Using the Java API
println System.getProperty('system')
// Using the Java API
println System.getProperty('system')
// Using the Gradle API, provides a lazy Provider<String>
println providers.systemProperty('system').get()
// Using the Java API
println System.getProperty('system')
// Using the Gradle API, provides a lazy Provider<String>
println providers.systemProperty('system').get()
tasks.register<PrintValue>("printProperty") {
// Using the Gradle API, provides a lazy Provider<String> wired to a task input
inputValue.set(providers.systemProperty("system"))
}
tasks.register('printProperty', PrintValue) {
// Using the Gradle API, provides a lazy Provider<String> wired to a task input
inputValue = providers.systemProperty('system')
}
$ gradle -Dsystem=commandLineValue
Environment variables
The following environment variables are available for the gradle
command. Note that command-line options and system properties take precedence over environment variables.
GRADLE_OPTS
-
Specifies JVM arguments to use when starting the Gradle client VM. The client VM only handles command line input/output, so it is rare that one would need to change its VM options. The actual build is run by the Gradle daemon, which is not affected by this environment variable.
GRADLE_USER_HOME
-
Specifies the Gradle user home directory (which defaults to
<home directory of the current user>/.gradle
if not set). JAVA_HOME
-
Specifies the JDK installation directory to use for the client VM. This VM is also used for the daemon, unless a different one is specified in a Gradle properties file with
org.gradle.java.home
.
The following examples demonstrate how to use environment variables.
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))
// Using the Gradle API, provides a lazy Provider<String>
println(providers.environmentVariable("ENVIRONMENTAL").get())
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))
// Using the Gradle API, provides a lazy Provider<String>
println(providers.environmentVariable("ENVIRONMENTAL").get())
// Using the Java API
println System.getenv('ENVIRONMENTAL')
// Using the Java API
println System.getenv('ENVIRONMENTAL')
// Using the Gradle API, provides a lazy Provider<String>
println providers.environmentVariable('ENVIRONMENTAL').get()
// Using the Java API
println System.getenv('ENVIRONMENTAL')
// Using the Gradle API, provides a lazy Provider<String>
println providers.environmentVariable('ENVIRONMENTAL').get()
tasks.register<PrintValue>("printValue") {
// Using the Gradle API, provides a lazy Provider<String> wired to a task input
inputValue.set(providers.environmentVariable("ENVIRONMENTAL"))
}
tasks.register('printValue', PrintValue) {
// Using the Gradle API, provides a lazy Provider<String> wired to a task input
inputValue = providers.environmentVariable('ENVIRONMENTAL')
}
Project properties
Project properties are available on the Project object.
They can be set from the command line using the -P
/ --project-prop
environment option.
$ gradle -PgradlePropertiesProp=commandLineValue
Gradle can also set project properties when it sees specially-named system properties or environment variables. If the environment variable name looks like ORG_GRADLE_PROJECT_prop=somevalue
, then Gradle will set a prop
property on your project object, with the value of somevalue
. Gradle also supports this for system properties, but with a different naming pattern, which looks like org.gradle.project.prop
. Both of the following will set the foo
property on your Project object to "bar"
.
org.gradle.project.foo=bar
ORG_GRADLE_PROJECT_foo=bar
This feature is useful when you don’t have admin rights to a continuous integration server, and you need to set property values that should not be easily visible. Since you cannot use the -P
option in that scenario, nor change the system-level configuration files, the correct strategy is to change the configuration of your continuous integration build job, adding an environment variable setting that matches an expected pattern. This won’t be visible to normal users on the system.
The following examples demonstrate how to use project properties.
// Querying the presence of a project property
if (hasProperty("myProjectProp")) {
// Accessing the value, throws if not present
println(property("myProjectProp"))
}
// Accessing the value of a project property, null if absent
println(findProperty("myProjectProp"))
// Accessing the Map<String, Any?> of project properties
println(properties["myProjectProp"])
// Using Kotlin delegated properties on `project`
val myProjectProp: String by project
println(myProjectProp)
// Querying the presence of a project property
if (hasProperty('myProjectProp')) {
// Accessing the value, throws if not present
println property('myProjectProp')
}
// Accessing the value of a project property, null if absent
println findProperty('myProjectProp')
// Accessing the Map<String, ?> of project properties
println properties['myProjectProp']
// Using Groovy dynamic names, throws if not present
println myProjectProp
The Kotlin delegated properties are part of the Gradle Kotlin DSL.
You need to explicitly specify the type as String
.
If you need to branch depending on the presence of the property, you can also use String?
and check for null
.
Note that if a Project property has a dot in its name, using the dynamic Groovy names is not possible. You have to use the API or the dynamic array notation instead.
tasks.register<PrintValue>("printValue") {
// Eagerly accessing the value of a project property, set as a task input
inputValue.set(project.property("myProjectProp").toString())
}
tasks.register('printValue', PrintValue) {
// Eagerly accessing the value of a project property, set as a task input
inputValue = project.property('myProjectProp')
}
If a project property is referenced but does not exist, an exception will be thrown and the build will fail. You should check for existence of optional project properties before you access them using the Project.hasProperty(java.lang.String) method. |
Configuring JVM memory
You can adjust JVM options for Gradle in the following ways:
The org.gradle.jvmargs
Gradle property controls the VM running the build. It defaults to -Xmx512m "-XX:MaxMetaspaceSize=256m"
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
The JAVA_OPTS
environment variable controls the command line client, which is only used to display console output. It defaults to -Xmx64m
JAVA_OPTS="-Xmx64m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8"
There is one case where the client VM can also serve as the build VM: If you deactivate the Gradle Daemon and the client VM has the same settings as required for the build VM, the client VM will run the build directly. Otherwise the client VM will fork a new VM to run the actual build in order to honor the different settings. |
Certain tasks, like the test
task, also fork additional JVM processes. You can configure these through the tasks themselves.
They all use -Xmx512m
by default.
plugins {
java
}
tasks.withType<JavaCompile>().configureEach {
options.compilerArgs = listOf("-Xdoclint:none", "-Xlint:none", "-nowarn")
}
plugins {
id 'java'
}
tasks.withType(JavaCompile).configureEach {
options.compilerArgs += ['-Xdoclint:none', '-Xlint:none', '-nowarn']
}
See other examples in the Test API documentation and test execution in the Java plugin reference.
Build scans will tell you information about the JVM that executed the build when you use the --scan
option.
Configuring a task using project properties
It’s possible to change the behavior of a task based on project properties specified at invocation time.
Suppose you’d like to ensure release builds are only triggered by CI. A simple way to handle this is through an isCI
project property.
tasks.register("performRelease") {
val isCI = providers.gradleProperty("isCI")
doLast {
if (isCI.isPresent) {
println("Performing release actions")
} else {
throw InvalidUserDataException("Cannot perform release outside of CI")
}
}
}
tasks.register('performRelease') {
def isCI = providers.gradleProperty("isCI")
doLast {
if (isCI.present) {
println("Performing release actions")
} else {
throw new InvalidUserDataException("Cannot perform release outside of CI")
}
}
}
$ gradle performRelease -PisCI=true --quiet Performing release actions
Accessing the web through a proxy
Configuring a proxy (for downloading dependencies, for example) is done via standard JVM system properties. These properties can be set directly in the build script; for example, setting the HTTP proxy host would be done with System.setProperty('http.proxyHost', 'www.somehost.org')
. Alternatively, the properties can be specified in gradle.properties.
systemProp.http.proxyHost=www.somehost.org systemProp.http.proxyPort=8080 systemProp.http.proxyUser=userid systemProp.http.proxyPassword=password systemProp.http.nonProxyHosts=*.nonproxyrepos.com|localhost
There are separate settings for HTTPS.
systemProp.https.proxyHost=www.somehost.org systemProp.https.proxyPort=8080 systemProp.https.proxyUser=userid systemProp.https.proxyPassword=password # NOTE: this is not a typo. systemProp.http.nonProxyHosts=*.nonproxyrepos.com|localhost
There are separate settings for SOCKS.
systemProp.socksProxyHost=www.somehost.org systemProp.socksProxyPort=1080 systemProp.java.net.socks.username=userid systemProp.java.net.socks.password=password
You may need to set other properties to access other networks. Here are 2 references that may be helpful:
NTLM Authentication
If your proxy requires NTLM authentication, you may need to provide the authentication domain as well as the username and password. There are 2 ways that you can provide the domain for authenticating to a NTLM proxy:
-
Set the
http.proxyUser
system property to a value likedomain/username
. -
Provide the authentication domain via the
http.auth.ntlm.domain
system property.