Gradle Variables and Properties
External
Internal
Overview
System Properties
A system property in a Gradle runtime 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 property declaration 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 from a build script won't trigger a build error, it will simply return null.
gradle properties
Does not show ...
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:
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
Accessing Gradle Properties
Overview
NEEDS REFACTORING.
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.
Properties can be displayed with:
gradle properties
The command displays project properties, and the properties added by various plugins.
Gradle Properties
Also see:
System 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
Extra Properties
An extra property is a property that can be declared on most model object instances available to the closure being executed. In case of a settings script, the available model objects are Settings, Gradle, ProjectDescriptor, etc., but of those ProjectDescriptor does not allow defining extra properties, and Settings, even if allows defining extra properties, cannot be easily accessed at configuration and execution phase, so the best candidate for defining extra properties is Gradle. For build scripts, extra properties can be defined on any available object model instances. They can be declared with a special syntax described below. Once the properties have been added, they can be read and set like predefined properties. Extra properties can be accessed from anywhere their owning object can be accessed, giving them a wider scope than local variables. Extra properties on a project are visible from its sub-projects.
By requiring special syntax for adding a property, Gradle can fail fast when an attempt is made to set a predefined or extra property but the property is misspelled or does not exist.
Declaring and Using Extra Properties
The extra properties are declared using the "ext" DSL keyword, applied to the model object we intend to declare extra properties for. However, "ext" is not necessary to access the property once declared, as shown in the examples below:
Initialization Phase
The property is defined in settings.gradle:
...
gradle.ext.color = "blue"
...
The property can be accessed anywhere in a build or settings script:
println "gradle is $gradle.color"
Extra Properties and Multi-Project Builds
The extra properties are not available and throw an execution error if they are accessed before are defined. That is why a multi-project build that declares extra properties in sub-projects' build.gradle and attempts to use them in the root project build.gradle will fail at the configuration phase:
BUILD FAILED in 3s ... * Where: Build file '.../root-project/build.gradle' line: 17 * What went wrong: A problem occurred evaluating root project 'root-project'. > Could not get unknown property 'blah' for project ':sub-project-A' of type org.gradle.api.Project.
The error occurs even "blah" was declared in sub-project-A's build.gradle, because the build file was not evaluated at the time the root project file is executed. If we log build.gradle evaluation, we get something like:
exiting root project build.gradle .... entering sub-project-A build.gradle .... exiting sub-project-A build.gradle ....
which shows that the sub-project build script is executed after the root project build script is executed.
At Configuration Phase
The property can be declared in a build script as follows:
project.ext.isApi = true
The property can be accessed anywhere in a build script:
println isApi
Declaring multiple extra properties in a closure:
...
ext {
log4jVersion = "2.1.7"
emailNotification = "build@example.com"
}
...
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.
Predefined Properties
Project Coordinates
name
A String containing the name of the project directory. It automatically becomes the project's name coordinate. See Gradle Project Coordinates.
group
See Gradle Project Coordinates - Group.
version
See Gradle Project Coordinates - Version.
parent
Other Properties
project
The Project instance.
projectDir
The File instance corresponding to the directory containing the build script.
path
A String containing the absolute path of the project. The path of the root project is ":"
description
A String containing the description for the project.
displayName
buildDir
A File representing <projectDir>/build.
buildFile
rootDir
rootProject
rootProject.name
state
status
Plugin Properties
Plugins add specific properties. For a list of properties added by various plugins, consult the plugin pages.