Build Environment & Properties

tasks.register("pitfalls") {
    val label = providers.gradleProperty("label").orElse("<not set>")
    val verbose = providers.gradleProperty("verbose").map { it.toBoolean() }.orElse(false)
    doLast {
        println("label   = ${label.get()}")
        println("verbose = ${verbose.get()}")
    }
}

tasks.register('pitfalls') {
    def label = providers.gradleProperty('label').orElse('<not set>')
    def verbose = providers.gradleProperty('verbose').map { it.toBoolean() }.orElse(false)
    doLast {
        println "label   = ${label.get()}"
        println "verbose = ${verbose.get()}"
    }
}

$ cat gradle.properties
flag=false
label=Café São
verbose=false

$ ./gradlew pitfalls -q
label   = Café São
verbose = false

$ cat gradle.properties
flag=false
label=Caf\u00e9 S\u00e3o
verbose=false

$ ./gradlew pitfalls -q
label   = Café São
verbose = false

$ cat gradle.properties
label=C:\temp\new

$ ./gradlew pitfalls -q | od -c | head -3
0000000    l   a   b   e   l               =       C   :  \t   e   m   p
0000020   \n   e   w  \n   v   e   r   b   o   s   e       =       f   a
0000040    l   s   e  \n

$ cat gradle.properties
label=C:\\temp\\new

$ ./gradlew pitfalls -q
label   = C:\temp\new
verbose = false

// Project property, read lazily: the recommended way
val viaProvider = providers.gradleProperty("myProperty").orElse("<not set>")
// Project property, read through the dynamic Project lookup while configuring
val viaFind = findProperty("myProperty")?.toString() ?: "<not set>"

tasks.register("showProperty") {
    val provider = viaProvider
    val found = viaFind
    doLast {
        println("providers.gradleProperty(\"myProperty\") = ${provider.get()}")
        println("project.findProperty(\"myProperty\")    = $found")
    }
}

// Project property, read lazily: the recommended way
def viaProvider = providers.gradleProperty('myProperty').orElse('<not set>')
// Project property, read through the dynamic Project lookup while configuring
def viaFind = findProperty('myProperty')?.toString() ?: '<not set>'

tasks.register('showProperty') {
    def provider = viaProvider
    def found = viaFind
    doLast {
        println "providers.gradleProperty(\"myProperty\") = ${provider.get()}"
        println "project.findProperty(\"myProperty\")    = ${found}"
    }
}

$ ./gradlew showProperty --configuration-cache -q
providers.gradleProperty("myProperty") = <not set>
project.findProperty("myProperty")    = <not set>

$ cat <installation>/gradle.properties
myProperty=installation

$ ./gradlew showProperty --configuration-cache -q
providers.gradleProperty("myProperty") = installation
project.findProperty("myProperty")    = installation

$ cat gradle.properties
myProperty=project

$ ./gradlew showProperty --configuration-cache -q
providers.gradleProperty("myProperty") = project
project.findProperty("myProperty")    = project

$ cat $GRADLE_USER_HOME/gradle.properties
myProperty=user-home

$ ./gradlew showProperty --configuration-cache -q
providers.gradleProperty("myProperty") = user-home
project.findProperty("myProperty")    = user-home

$ ORG_GRADLE_PROJECT_myProperty=env ./gradlew showProperty --configuration-cache -q
providers.gradleProperty("myProperty") = env
project.findProperty("myProperty")    = env

$ ORG_GRADLE_PROJECT_myProperty=env ./gradlew showProperty --configuration-cache -q -Dorg.gradle.project.myProperty=sysprop
providers.gradleProperty("myProperty") = sysprop
project.findProperty("myProperty")    = sysprop

$ ORG_GRADLE_PROJECT_myProperty=env ./gradlew showProperty --configuration-cache -q -Dorg.gradle.project.myProperty=sysprop -PmyProperty=cli
providers.gradleProperty("myProperty") = cli
project.findProperty("myProperty")    = cli

tasks.register("pitfalls") {
    val label = providers.gradleProperty("label").orElse("<not set>")
    val verbose = providers.gradleProperty("verbose").map { it.toBoolean() }.orElse(false)
    doLast {
        println("label   = ${label.get()}")
        println("verbose = ${verbose.get()}")
    }
}

tasks.register('pitfalls') {
    def label = providers.gradleProperty('label').orElse('<not set>')
    def verbose = providers.gradleProperty('verbose').map { it.toBoolean() }.orElse(false)
    doLast {
        println "label   = ${label.get()}"
        println "verbose = ${verbose.get()}"
    }
}

// The classic Groovy trap: a Gradle property is always a String
tasks.register('truthy') {
    def verbose = findProperty('verbose')
    doLast {
        println "verbose is ${verbose.getClass().simpleName} '${verbose}'"
        if (verbose) { println "if (verbose) is true even though the file says false" }
        println "'false'.toBoolean() = ${verbose.toBoolean()}"
    }
}

$ cat gradle.properties
verbose=false

$ ./gradlew truthy -q
verbose is String 'false'
if (verbose) is true even though the file says false
'false'.toBoolean() = false

$ ./gradlew pitfalls -q -Plabel
label   =
verbose = false

tasks.register("requireFlag") {
    // property(name) fails when the property does not exist anywhere
    val flag = project.property("flag").toString()
    doLast { println("flag = $flag") }
}

tasks.register('requireFlag') {
    // property(name) fails when the property does not exist anywhere
    def flag = project.property('flag').toString()
    doLast { println "flag = ${flag}" }
}

$ ./gradlew requireFlag -q 2>&1 | head -7

FAILURE: Build failed with an exception.

* What went wrong:
A problem occurred configuring root project 'pitfalls'.
> Could not create task ':requireFlag'.
   > Could not get unknown property 'flag' for root project 'pitfalls' of type org.gradle.api.Project.

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")
        }
    }
}

$ ./gradlew performRelease -q 2>&1 | head -6

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':performRelease' (registered in build file 'build.gradle.kts').
> Cannot perform release outside of CI

$ ./gradlew performRelease -q -PisCI=true
Performing release actions

$ ORG_GRADLE_PROJECT_isCI=true ./gradlew performRelease -q
Performing release actions

tasks.register("whoAmI") {
    val viaProvider = providers.gradleProperty("shared").orElse("<not set>")
    val viaFind = findProperty("shared")?.toString() ?: "<not set>"
    val onlyRoot = findProperty("onlyRoot")?.toString() ?: "<not set>"
    val fromExt = findProperty("fromRootExt")?.toString() ?: "<not set>"
    val root = providers.systemProperty("tide.root").orElse("<not set>")
    val sub = providers.systemProperty("tide.sub").orElse("<not set>")
    doLast {
        println("app: providers.gradleProperty(shared) = ${viaProvider.get()}")
        println("app: findProperty(shared)             = $viaFind")
        println("app: findProperty(onlyRoot)           = $onlyRoot")
        println("app: findProperty(fromRootExt)        = $fromExt")
        println("app: systemProp tide.root             = ${root.get()}")
        println("app: systemProp tide.sub              = ${sub.get()}")
    }
}

tasks.register('whoAmI') {
    def viaProvider = providers.gradleProperty('shared').orElse('<not set>')
    def viaFind = findProperty('shared')?.toString() ?: '<not set>'
    def onlyRoot = findProperty('onlyRoot')?.toString() ?: '<not set>'
    def fromExt = findProperty('fromRootExt')?.toString() ?: '<not set>'
    def root = providers.systemProperty('tide.root').orElse('<not set>')
    def sub = providers.systemProperty('tide.sub').orElse('<not set>')
    doLast {
        println "app: providers.gradleProperty(shared) = ${viaProvider.get()}"
        println "app: findProperty(shared)             = ${viaFind}"
        println "app: findProperty(onlyRoot)           = ${onlyRoot}"
        println "app: findProperty(fromRootExt)        = ${fromExt}"
        println "app: systemProp tide.root             = ${root.get()}"
        println "app: systemProp tide.sub              = ${sub.get()}"
    }
}

$ cat gradle.properties
shared=from-root-file
onlyRoot=root-only
systemProp.tide.root=root-system-property

$ cat app/gradle.properties
shared=from-app-file
systemProp.tide.sub=sub-system-property

$ ./gradlew :app:whoAmI :lib:whoAmI -q
app: providers.gradleProperty(shared) = from-root-file
app: findProperty(shared)             = from-app-file
app: findProperty(onlyRoot)           = root-only
app: findProperty(fromRootExt)        = root-ext-value
app: systemProp tide.root             = root-system-property
app: systemProp tide.sub              = <not set>
lib: findProperty(shared) = from-root-file

$ ./gradlew :app:whoAmI --warning-mode all --console=plain 2>&1 | grep "^Implicit"
Implicit lookup of properties in parent projects has been deprecated. This will fail with an error in Gradle 10. Property 'fromRootExt' was not declared in project ':app' and was resolved from root project 'multi'. This lookup was initiated by 'findProperty()'. Consult the upgrading guide for further information: https://docs.gradle.org/9.8.1/userguide/upgrading_version_9.html#deprecated_implicit_lookup_in_parent_projects

// Deprecated since Gradle 9.6: property delegate, and it also walks up to the parent project
val greeting: String? by project

tasks.register("greet") {
    val text = greeting
    doLast { println("greeting = $text") }
}

// A bare name is resolved dynamically, walking up to the parent project: deprecated since Gradle 9.6
tasks.register('greet') {
    def text = greeting
    doLast { println "greeting = ${text}" }
}

$ ./gradlew :child:greet -q
greeting = hello from the root

$ ./gradlew :child:greet --warning-mode all --console=plain 2>&1 | grep -E "^(The .val name|Implicit)"
The 'val name: Type? by project' property delegate syntax has been deprecated. This is scheduled to be removed in Gradle 10. Use 'val property = project.findProperty(name)' instead. Consult the upgrading guide for further information: https://docs.gradle.org/9.8.1/userguide/upgrading_version_9.html#kotlin_dsl_delegated_properties
Implicit lookup of properties in parent projects has been deprecated. This will fail with an error in Gradle 10. Property 'greeting' was not declared in project ':child' and was resolved from root project 'delegate'. This lookup was initiated by 'val ... by project'. Consult the upgrading guide for further information: https://docs.gradle.org/9.8.1/userguide/upgrading_version_9.html#deprecated_implicit_lookup_in_parent_projects

tasks.register("showJvm") {
    doLast {
        val args = java.lang.management.ManagementFactory.getRuntimeMXBean().inputArguments
        println("java.version   = ${System.getProperty("java.version")}")
        println("max heap (MiB) = ${Runtime.getRuntime().maxMemory() / 1024 / 1024}")
        println("daemon -Xmx    = ${args.filter { it.startsWith("-Xmx") }}")
    }
}

tasks.register('showJvm') {
    doLast {
        def args = java.lang.management.ManagementFactory.runtimeMXBean.inputArguments
        println "java.version   = ${System.getProperty('java.version')}"
        println "max heap (MiB) = ${Runtime.runtime.maxMemory().intdiv(1024 * 1024)}"
        println "daemon -Xmx    = ${args.findAll { it.startsWith('-Xmx') }}"
    }
}

$ JAVA_HOME=$JDK21 ./gradlew showJvm -q
java.version   = 21.0.10
max heap (MiB) = 512
daemon -Xmx    = [-Xmx512m]

$ JAVA_HOME=$JDK21 ./gradlew showJvm -q -Dorg.gradle.java.home=$JDK17
java.version   = 17.0.14
max heap (MiB) = 512
daemon -Xmx    = [-Xmx512m]

$ cat gradle.properties
org.gradle.java.home=<JDK 17 home>

$ ./gradlew showJvm -q
java.version   = 17.0.14
max heap (MiB) = 512
daemon -Xmx    = [-Xmx512m]

$ JAVA_HOME=$JDK21 ./gradlew showJvm -q
java.version   = 17.0.14
max heap (MiB) = 512
daemon -Xmx    = [-Xmx512m]

$ cat gradle.properties
org.gradle.java.home=/no/such/jdk

$ ./gradlew showJvm -q 2>&1 | head -5

FAILURE: Build failed with an exception.

* What went wrong:
Value '/no/such/jdk' given for org.gradle.java.home Gradle property is invalid (Java home supplied is invalid)

$ ./gradlew showJvm -q
java.version   = 26
max heap (MiB) = 512
daemon -Xmx    = [-Xmx512m]

$ cat gradle.properties
org.gradle.jvmargs=-Xmx700m

$ ./gradlew showJvm -q
java.version   = 26
max heap (MiB) = 704
daemon -Xmx    = [-Xmx700m]

$ ./gradlew showJvm --console=plain -Dorg.gradle.jvmargs=-Xmx800m 2>&1 | grep -E "Starting|max heap|daemon -Xmx"
Starting a Gradle Daemon, 2 incompatible and 50 stopped Daemons could not be reused, use --status for details
max heap (MiB) = 800
daemon -Xmx    = [-Xmx800m]

$ GRADLE_OPTS="-Dprobe.opts=gradle_opts -Xmx64m" ./gradlew showSystemProperty showJvm -q --configuration-cache
tide.region = <not set>
probe.opts  = gradle_opts
java.version   = 26
max heap (MiB) = 512
daemon -Xmx    = [-Xmx512m]

$ JAVA_OPTS="-Dprobe.opts=java_opts" ./gradlew showSystemProperty -q --configuration-cache
tide.region = <not set>
probe.opts  = java_opts

$ GRADLE_OPTS="-Dorg.gradle.jvmargs=-Xmx600m" ./gradlew showJvm -q
java.version   = 26
max heap (MiB) = 600
daemon -Xmx    = [-Xmx600m]

$ cat gradle.properties
org.gradle.daemon=false

$ ./gradlew showJvm --console=plain 2>&1 | head -4
To honour the JVM settings for this build a single-use Daemon process will be forked. For more on this, please refer to https://docs.gradle.org/9.8.1/userguide/gradle_daemon.html#sec:disabling_the_daemon in the Gradle documentation.
Daemon will be stopped at the end of the build

> Task :showJvm

tasks.register("showUserHome") {
    val home = gradle.gradleUserHomeDir.name
    doLast { println("Gradle user home directory name = $home") }
}

tasks.register('showUserHome') {
    def home = gradle.gradleUserHomeDir.name
    doLast { println "Gradle user home directory name = ${home}" }
}

$ ./gradlew showUserHome -q --configuration-cache
Gradle user home directory name = guh

$ ./gradlew showUserHome -q -Dgradle.user.home=$OTHER_HOME
Gradle user home directory name = other-home

$ ./gradlew showUserHome -q -g $OTHER_HOME
Gradle user home directory name = other-home

tasks.register("env") {
    // read while configuring, so the values are inputs of the configuration cache entry
    val stage = providers.environmentVariable("DEPLOY_STAGE").orElse("dev").get()
    val label = providers.gradleProperty("label").orElse("<not set>").get()
    doLast { println("stage=$stage label=$label") }
}

tasks.register("envLazy") {
    // read while executing: the cache entry is reused and the new value still arrives
    val stage = providers.environmentVariable("DEPLOY_STAGE").orElse("dev")
    val label = providers.gradleProperty("label").orElse("<not set>")
    doLast { println("stage=${stage.get()} label=${label.get()}") }
}

tasks.register('env') {
    // read while configuring, so the values are inputs of the configuration cache entry
    def stage = providers.environmentVariable('DEPLOY_STAGE').orElse('dev').get()
    def label = providers.gradleProperty('label').orElse('<not set>').get()
    doLast { println "stage=${stage} label=${label}" }
}

tasks.register('envLazy') {
    // read while executing: the cache entry is reused and the new value still arrives
    def stage = providers.environmentVariable('DEPLOY_STAGE').orElse('dev')
    def label = providers.gradleProperty('label').orElse('<not set>')
    doLast { println "stage=${stage.get()} label=${label.get()}" }
}

$ DEPLOY_STAGE=dev ./gradlew env --configuration-cache --console=plain 2>&1 | grep -E "stage=|Calculating|Reusing|entry"
Calculating task graph as no cached configuration is available for tasks: env
stage=dev label=<not set>
Configuration cache entry stored.

$ DEPLOY_STAGE=dev ./gradlew env --configuration-cache --console=plain 2>&1 | grep -E "stage=|Calculating|Reusing|entry"
Reusing configuration cache.
stage=dev label=<not set>
Configuration cache entry reused.

$ DEPLOY_STAGE=prod ./gradlew env --configuration-cache --console=plain 2>&1 | grep -E "stage=|Calculating|Reusing|entry"
Calculating task graph as configuration cache cannot be reused because environment variable 'DEPLOY_STAGE' has changed.
stage=prod label=<not set>
Configuration cache entry stored.

$ DEPLOY_STAGE=prod ./gradlew env -Plabel=x --configuration-cache --console=plain 2>&1 | grep -E "stage=|Calculating|Reusing|entry"
Calculating task graph as configuration cache cannot be reused because Gradle property 'label' has changed.
stage=prod label=x
Configuration cache entry stored.

$ DEPLOY_STAGE=dev ./gradlew envLazy --configuration-cache --console=plain 2>&1 | grep -E "stage=|Calculating|Reusing|entry"
Calculating task graph as no cached configuration is available for tasks: envLazy
stage=dev label=<not set>
Configuration cache entry stored.

$ DEPLOY_STAGE=prod ./gradlew envLazy --configuration-cache --console=plain 2>&1 | grep -E "stage=|Calculating|Reusing|entry"
Reusing configuration cache.
stage=prod label=<not set>
Configuration cache entry reused.

$ DEPLOY_STAGE=prod ./gradlew envLazy -Plabel=y --configuration-cache --console=plain 2>&1 | grep -E "stage=|Calculating|Reusing|entry"
Reusing configuration cache.
stage=prod label=y
Configuration cache entry reused.