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 a
gradle.properties
file and commit it to your version control system.
gradle.properties
org.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
-D
.
|
2
|
gradle.properties
file
|
GRADLE_USER_HOME
|
Stored in a
gradle.properties
file in the
GRADLE_USER_HOME
.
|
3
|
gradle.properties
file
|
Project Root Dir
|
Stored in a
gradle.properties
file in a project directory, then its parent project’s directory up to the project’s root directory.
|
4
|
gradle.properties
file
|
GRADLE_HOME
|
Stored in a
gradle.properties
file in the
GRADLE_HOME
, the optional Gradle installation directory.
|
|
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
.
org.gradle.configuration-cache=(true,false)
-
Enables
configuration caching
. Gradle will try to reuse the build configuration from previous builds.
org.gradle.configureondemand=(true,false)
-
Enables incubating configuration-on-demand, where Gradle will attempt to configure only necessary projects.
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.
org.gradle.daemon=(true,false)
-
When set to
true
the
Gradle Daemon
is used to run the build.
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.
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
or
jre
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 to
java
) 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
.
org.gradle.priority=(low,normal)
-
Specifies the
scheduling priority
for the Gradle daemon and all processes launched by it.
org.gradle.projectcachedir=(directory)
-
Specify the project-specific cache directory. Defaults to
.gradle
in the root project directory."
org.gradle.unsafe.isolated-projects=(true,false)
-
Enables project isolation, which enables configuration caching.
org.gradle.vfs.verbose=(true,false)
-
Configures verbose logging when
watching the file system
.
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
, or
none
, Gradle will use
different warning type display
.
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:
gradle.properties
gradlePropertiesProp=gradlePropertiesValue
gradleProperties.with.dots=gradlePropertiesDottedValue
Example 2:
Reading Gradle properties at configuration time:
settings.gradle.kts
// 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)
build.gradle.kts
// 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)
settings.gradle
// 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']
build.gradle
// 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:
build.gradle.kts
tasks.register<PrintValue>("printProperty") {
// Using the API, provides a lazy Provider<String> wired to a task input
inputValue = providers.gradleProperty("gradlePropertiesProp")
}
build.gradle
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:
init.gradle.kts
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)
}
init.gradle
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.