Configuring the Build Environment
Gradle provides multiple mechanisms for configuring the behavior of Gradle itself and specific projects.
The following is a reference for using these mechanisms:
Mechanism | Information | Example |
---|---|---|
Flags that configure build behavior and Gradle features |
|
|
Properties specific to your Gradle project |
|
|
Properties that are passed to the Gradle runtime (JVM) |
|
|
Properties that configure Gradle settings |
|
|
Properties that configure build behavior based on the environment |
|
Priority for configurations
When configuring Gradle behavior, you can use these methods, but you must consider their priority. The following table lists these methods in order of highest to lowest precedence (the first one wins):
Priority | Method | Location | Example | Details |
---|---|---|---|---|
1 |
Command line |
|
These have precedence over properties and environment variables. |
|
2 |
Project Root Dir |
|
Stored in a |
|
3 |
|
|
Stored in a |
|
4 |
Environment |
|
Sourced by the environment that executes Gradle. |
Project properties
Project properties are specific to your Gradle project.
They are defined using blocks in your build script or directly in the project
object.
For example, the project property myProperty
is created in a build file:
ext {
myProperty = findProperty('myProperty') ?: 'Hello, world!'
}
println "My property value: ${project.ext.myProperty}"
You have two options to add project properties, listed in order of priority:
-
Command Line: You can add properties directly to your Project object via the
-P
command line option.$ ./gradlew build -PmyProperty='Hi, world'
-
System Properties or Environment Variables: You can set project properties with specially-named system properties or environment variables.
$ ./gradlew build -Dorg.gradle.project.myProperty='Hi, world'
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
.
The following examples will set the foo
property on your Project object to "bar"
.
Example 1: Setting a project property via the command line.
$ ./gradlew build -Pfoo=bar
Example 2: Setting a project property via a system property.
org.gradle.project.foo=bar
Example 3: Setting a project property via an environment variable.
$ export ORG_GRADLE_PROJECT_foo=bar
This feature is very useful when you don’t have admin rights to a continuous integration server and need to set property values that are not 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.
You can access a project property in your build script simply by using its name, as you would a variable.
Command-line flags
The command line interface and the available flags are described in its own section.
System properties
System properties are variables set at the JVM level and accessible to the Gradle build process.
System properties can be accessed using the System
class in the build script.
Common system properties are listed below.
You have two options to add system properties listed in order of priority:
-
Command Line: Using the
-D
command-line option, you can pass a system property to the JVM, which runs Gradle. The-D
option of thegradle
command has the same effect as the-D
option of thejava
command.$ ./gradlew build -Dgradle.wrapperUser=myuser
-
gradle.properties
file: You can also set system properties ingradle.properties
files with the prefixsystemProp
:gradle.propertiessystemProp.gradle.wrapperUser=myuser systemProp.gradle.wrapperPassword=mypassword
The following are common system properties:
gradle.wrapperUser=(myuser)
-
Specify username to download Gradle distributions from servers using HTTP Basic Authentication.
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. e.g.,
TLSv1.2,TLSv1.3
.
Additional Java system properties are listed here.
In a multi-project build, systemProp
properties set in any project except the root will be ignored.
Only the root project’s gradle.properties
file will be checked for properties that begin with systemProp
.
The following examples demonstrate how to use system properties:
Example 1: Setting system properties with a gradle.properties
file:
systemProp.system=gradlePropertiesValue
Example 2: Reading system properties at configuration time:
// 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()
Example 3: Reading system properties for consumption at execution time:
tasks.register<PrintValue>("printProperty") {
// Using the Gradle API, provides a lazy Provider<String> wired to a task input
inputValue = 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')
}
Example 4: Setting system properties from the command line -D gradle.wrapperUser=username
:
$ gradle -Dsystem=commandLineValue
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.
You have one option to add gradle properties:
-
gradle.properties
file: Place these settings into agradle.properties
file and commit it to your version control system.gradle.propertiesorg.gradle.caching.debug=false
The final configuration considered 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:
Priority | Method | Location | Details |
---|---|---|---|
1 |
Command line interface |
. |
In the command line using |
2 |
|
|
Stored in a |
3 |
|
Project Root Dir |
Stored in a |
4 |
|
|
Stored in a |
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 are common Gradle properties:
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.Default is
false
; 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.Default is
false
. org.gradle.configuration-cache=(true,false)
-
Enables configuration caching. Gradle will try to reuse the build configuration from previous builds.
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.
org.gradle.continue=(true,false)
-
If enabled, continue task execution after a task failure, else stop task execution after a task failure.
Default is
false
. org.gradle.daemon=(true,false)
-
When set to
true
the Gradle Daemon is used to run the build.Default is
true
. org.gradle.daemon.idletimeout=(# of idle millis)
-
Gradle Daemon will terminate itself after a 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 equivalent to 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 is
false
. 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, using a JDK is safer depending on what your build does. This does not affect the version of Java used to launch the Gradle client VM.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.
Default is
-Xmx512m "-XX:MaxMetaspaceSize=384m"
. org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)
-
When set to quiet, warn, info, or debug, Gradle will use this log level. The values are not case-sensitive.
Default is
lifecycle
level. org.gradle.parallel=(true,false)
-
When configured, Gradle will fork up to
org.gradle.workers.max
JVMs to execute projects in parallel.Default is
false
. org.gradle.priority=(low,normal)
-
Specifies the scheduling priority for the Gradle daemon and all processes launched by it.
Default is
normal
. org.gradle.projectcachedir=(directory)
-
Specify the project-specific cache directory. Defaults to
.gradle
in the root project directory."Default is
.gradle
. org.gradle.unsafe.isolated-projects=(true,false)
-
Enables project isolation, which enables configuration caching.
Default is
false
. 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 reuses information it collects about the file system between builds.
Default is
true
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.Default is
summary
. org.gradle.workers.max=(max # of worker processes)
-
When configured, Gradle will use a maximum of the given number of workers.
Default is the number of CPU processors.
The following examples demonstrate how to use Gradle properties.
Example 1: Setting Gradle properties with a gradle.properties
file:
gradlePropertiesProp=gradlePropertiesValue
gradleProperties.with.dots=gradlePropertiesDottedValue
Example 2: Reading Gradle properties at configuration time:
// 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 using the dynamic Groovy names is impossible if a Gradle property has a dot in its name. You have to use the API or the dynamic array notation instead.
Example 3: Reading Gradle properties for consumption at execution time:
tasks.register<PrintValue>("printProperty") {
// Using the API, provides a lazy Provider<String> wired to a task input
inputValue = providers.gradleProperty("gradlePropertiesProp")
}
tasks.register('printProperty', PrintValue) {
// Using the API, provides a lazy Provider<String> wired to a task input
inputValue = providers.gradleProperty('gradlePropertiesProp')
}
Example 4: Setting Gradle properties from the command line:
$ 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 {}
:
Example 5: Reading Gradle properties from initialization scripts:
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.
Environment variables
Gradle provides a number of environment variables, which are listed below.
You can access environment variables as properties in the build script using the System.getenv()
method.
The following environment variables are available for the gradle
command.
GRADLE_HOME
-
Installation directory for Gradle.
Can be used to specify a local Gradle version instead of using the wrapper.
You can add
GRADLE_HOME/bin
to yourPATH
for specific applications and use cases (such as testing an early release for Gradle). JAVA_OPTS
-
Used to pass JVM options and custom settings to the JVM.
GRADLE_OPTS
-
Specifies JVM arguments to use when starting the Gradle client VM.
The client VM only handles command line input/output, so one would rarely 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 for Gradle to store its global configuration properties, initialization scripts, caches, log files and more.Defaults to
USER_HOME/.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
. GRADLE_LIBS_REPO_OVERRIDE
-
Overrides for the default Gradle library repository.
Can be used to specify a default Gradle repository URL in
org.gradle.plugins.ide.internal.resolver
.Useful override to specify an internally hosted repository if your company uses a firewall/proxy.
The following examples demonstrate how to use environment variables.
Example 1: Reading environment variables at configuration time:
// 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()
Example 2: Reading environment variables for consumption at execution time:
tasks.register<PrintValue>("printValue") {
// Using the Gradle API, provides a lazy Provider<String> wired to a task input
inputValue = 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')
}