Gradle Variables and Properties

DEPLETE TO

Gradle Properties - Runtime and Project Configuration

Overview

Gradle uses system properties, Gradle properties, project properties and, being a Groovy extension, local variables. When a property with the same name is declared in multiple places, property declaration precedence rules apply.

System Properties

A system property in a Gradle runtime context is a regular JVM system property that has no special signification to Gradle. There are a few system properties that make exception from this rule: "gradle.wrapperUser", "gradle.wrapperPassword" and "gradle.user.home". System properties can be declared in command line with -D. The -D option of the gradle command has the same effect as the -D option of the java command.

-D<propName>=<propValue>

Interestingly enough, inserting an extra "=" between -D and property name also works:

-D=<propName>=<propValue>

System properties can also be declared in gradle.properties files with a special syntax:

systemProp.<propName>=<propValue>

The "systemProp." system properties set in a multi-project build gradle.properties files in any project except root will be ignored. Only the root project's gradle.properties will be checked for properties that begin with "systemProp." prefix.

When the same system property is declared in multiple places, the effective value is subject to the property declaration precedence rules.

There are no special syntactic facilities to access system properties from build scripts, unlike project properties that have a special simplified syntax for access. System properties can be accessed as follows:

task printProp {

    doLast {

        println System.properties['mySystemPropA']
        println System.getProperty('mySystemPropA')
    }
}

All other equivalent JDK API is available:

System.getProperty('myPropertyName', 'DefaultValue')

If we know that the system property has boolean semantics, we can use:

Boolean.getBoolean(...)

Note that an attempt to access a non-existent system property from a build script won't trigger a build error, it will simply return null.

gradle properties 

does not show system properties declared with -D=... on command line, but does show system properties declared with "systemProp." in gradle.properties files.

Also see:

Pass Configuration on Command Line

Gradle Properties

These are properties that can be used to configure aspects of a Gradle build run, regardless of the specific of the project being built. They can be seen as Gradle runtime configuration options, and can be used to configure the following aspects:

• Build artifact caching: org.gradle.caching, org.gradle.caching.debug.
• Configuration on demand: org.gradle.configureondemand.
• Gradle runtime configuration, such as console output coloring and verbosity, running in debug mode, JVM arguments, logging level, running in parallel mode, etc.
• Whether Gradle Daemon runs or not and its operational parameters.

The Gradle properties can be declared on command line with -D<propName>=<propValue> or in gradle.properties files. When the same Gradle property is declared in multiple places, the effective value is subject to the property declaration precedence rules.

 ... -Dorg.gradle.debug=true ...

Project Properties

A Gradle project property is a key value pair that can be accessed directly from build scripts without any qualifier.

A project property is an extra property defined on a project instance.

Project properties are a mechanism designed to allow easy access and storage of state in build scripts. A project property can be accessed without any qualifier:

task printProp {
  doLast {
    println myProjectProp
  }
}

All properties currently declared on a project instance and their values can be displayed with:

task displayProjectProperties {

    doLast() {

        for(Map.Entry p: project.getProperties()) {
            println p;
        }
    }
}

To avoid a build-time exception and build failure, the existence of a project property can be checked in the configuration scripts with:

project.hasProperty("somePropertyName")

The following example shows the pattern to initialize a project property with a default value, and thus preventing build failure if the property was not declared externally on command line or gradle.properties files. For more details on how to declare project properties in the build scripts, see Extra Properties.

if (!project.hasProperty("ciUsername")) {
  ext.ciUsername = "CI-USERNAME-SHOULD-BE-DEFINED-EXTERNALLY"
}

Project properties can be declared on command line with:

-P<projectPropName>=<value>

An equivalent effect can be achieved declaring the project property with -D, as with the system properties, but prefixing it with "org.gradle.project.". A property declared as such becomes a project property and can be accessed from the build script without any qualification:

... -Dorg.gradle.project.myProjectPropB=green ...

Project properties can also be declared in gradle.properties files:

someProperty=someValue

When the same project property is declared in multiple places, the effective value is subject to the property declaration precedence rules.

Project Property Lookup Failure

An important characteristic of project properties is that an attempt to access a project property that was not explicitly defined will trigger a build error.

FAILURE: Build failed with an exception.

* Where:
Build file '/Users/ovidiu/playground/gradle/concepts/build.gradle' line: 11

* What went wrong:
Execution failed for task ':printProps'.
> Could not get unknown property 'thisProjectPropertyWasNotDefined' for task ':printProps' of type org.gradle.api.DefaultTask.

Project Property List

For a complete list of project properties see:

Project Properties

Plugin Properties

Plugins add specific properties. For a list of properties added by various plugins, consult the plugin pages.

Declaring Variables and Properties in Configuration Files

Configuration scripts can declare variables during the initialization and configuration phases, and the values of those variables can be accessed and updated during the execution phase and used to drive build logic. There are two types of variables that can be declared: local variables and extra properties.

Local Variables

Local variables, which are a feature of the underlying Groovy language, are declared with the "def" keyword. They are only visible in the scope where they have been declared. The scope include all closures declared in scope.

def myVariable = "something"
...
println myVariable

Auto-Delegation

Properties not defined in the build script are auto-delegating to the Project instance. For example:

name

and

project.name

are equivalent. Normally, using "name" is sufficient. In case you define a property or a method which has the same name as a member of the Project object, you will need to use the project property.

If auto-delegation is used, the build script will fail if the property was not previously defined on the Project instance.

Property Declaration Precedence Rules

Properties can be declared implicitly by command line flags, explicitly on command line with -D or -P, in gradle.properties files or environment variables. These configuration methods are listed in the descending order of their precedence, with the highest precedence at the top. The first one encountered wins.

Command Line Flags

Command line flags have precedence over properties and environment variables with the same effect. For more details see Gradle Command Line.

Command Line Property Definitions

System properties can be declared with -D on command line. Project properties can be declared with -P on command line.

Environment Variables

Environment variables such as GRADLE_OPTS and JAVA_OPTS are sourced by the environment that executes Gradle. These environment variables can be used to provide properties definition, but they are only available in a specific user's environment, and do not propagate to version control.

GRADLE_USER_HOME specifies Gradle user home directory, which is $USER_HOME/.gradle by default.

Project properties can also be set as environment variables:

ORG_GRADLE_PROJECT_<propName>=<propValue>

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.

Passing Configuration to a Gradle Build via Custom Environment Variables

Passing Configuration to a Gradle Build via Custom Environment Variables