Gradle Variables and Properties

External

• https://docs.gradle.org/current/userguide/build_environment.html

Property Concepts

System Properties

A system property is this context is a regular JVM system property, that has no special signification to Gradle. System properties can be declared in command line with -D=..., in gradle.properties with a special syntax ("systemProp.<propName>=...) or in the build files, subject to the usual precedence rules.

There are no special facilities to access system properties from build scripts (unlike project properties, that have a special simplified syntax for access):

task printProp {

    doLast {

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

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

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=... or in gradle.properties.

Project Properties

A Gradle project property is a key value pair that can be accessed directly from build scripts without any qualifier. Project properties is a mechanism designed for easy access. It can be considered logically attached directly to the project.

A project property can be accessed without any qualifier:

task printProp {
    doLast {
        println myProjectProp
    }
}

An important characteristic of project properties is that an attempt to access a project property that was not explicitly defined using one of the means described below will trigger a build error.

task printProp {
    doLast {
       println thisProjectPropertyWasNotDefined
   }
}

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.

Declaring Properties

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. See:

Gradle Command Line

Command Line Property Definitions

Command Line System Properties

System properties can be declared on command line with "-D=", using the usual Java system property declaration syntax:

... -DsystemProp1=red ...

Command Line Project Properties

Project properties can be declared on command line with "-P="

... -PmyProjectPropA=blue ...

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 ...

gradle.properties Files

gradle.properties can be used to define properties for the build. gradle.properties files can be placed either in Gradle user home directory (~/.gradle/gradle.properties) or in the project root directory. If both files are present, their content is merged and the configuration that comes from the user home directory takes precedence over the configuration that comes from the project root directory. If a command line -Dproperty-name=... is specified, the value overrides the value read from the property files, if any.

Form a security perspective, it makes sense to use the user home directory if the project is checked into a repository and we do not want to maintain sensitive information in that file.

someUser=someuser
somePassword=somepassword

Normally, gradle.properties is used to declare project properties

System properties can be declared with this special syntax:

systemProp.mySystemPropDeclaredInGradleProperties = something

Gradle User Home gradle.properties

This location is configurable as GRADLE_USER_HOME environment variable.

Project Root gradle.properties

This property definition vehicle is important because it can be stored in source control, so the entire team working on the project can share the same configuration.

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. For definitions that propagate to version control, so an entire team can use them, use the project root gradle.properties.

Accessing Properties

The effective value of the properties can be displayed with:

gradle properties

TODO

tmp