Specifying Gradle Build Properties

Properties are a valuable tool for easily customizing Gradle builds and the Gradle environment. I demonstrate some of these approaches for specifying properties used in a Gradle build in this post.

Gradle supports both project properties and system properties. The main difference between the two that is of interest in this post is how each is accessed. Project properties are more conducive to direct access by name while system properties are accessed via normal Java/Groovy system properties access methods.

Passing Project Properties From Command-Line With -P

One of the easiest approaches for passing properties to a Gradle build is to specify project properties with -Pfrom the command line. Properties passed into the build with -P are readily accessible in the build as project properties and, if their naming structure allows, can be accessed directly like variables.

Passing System Properties From Command-Line With -D

As is the case with other Java applications, one can pass system properties to Gradle builds with -D. Although these system properties provided to the Gradle build via the -D option are always available to the Gradle build via the normal Java mechanism for obtaining system properties, Gradle makes it possible to specify Project Properties as system properties. This is done by placing the prefix org.gradle.project. before the name of the property desired in the build. For example, if one wanted to specify a system property namedname.first with -D that would be available to the Gradle build as if it was provided with -P, the person could provide it to the Gradle build on the command line as org.gradle.project.name.first and the Gradle build would see it as a project property named name.first.

Passing System Properties via Environmental Variable

Any Java or Groovy application (including a Gradle build) can access environmental variables viaSystem.getenv(String). However, Gradle allows environment variables to be accessed within the build like other project properties if the environmental variable is prefixed with ORG_GRADLE_PROJECT_. For example, if one wanted a project property in the Gradle build to be called name.last and wanted to supply it to the build via environment variable, that person could declare the environment variableORG_GRADLE_PROJECT_name.last and its value would be available to the Gradle build as a project property with name name.last.

gradle.properties

Properties can also be provided to a Gradle build via a properties file named gradle.properties. Any properties specified with systemProp. at the beginning of their property name are seen as system properties in the Gradle build and other properties (without their names beginning with "systemProp.") are seen as Gradle project properties. For example, if my gradle.properties file had a property name.last=Marx and a propertysystemPropr.name.first=Dustin, the name.last property would be seen and accessed in the Gradle build like any project property while the name.first property would be seen and accessed in the Gradle build like any system property.

Demonstration/Example

Each of these types of properties-specifying mechanisms can be demonstrated with a simple example. The Gradle build shown next attempts to print out various properties that are specified in different ways.

build-properties.gradle

task displayProperties << {
   displaySystemProperties()
   displayGradleProjectProperties()
}

def displaySystemProperties()
{
   println "\n=== System Properties ==="
   println "Favorite Movie (1994): ${System.properties['movie.favorite.1994']}"
   println "Favorite Movie (1996): ${System.properties['movie.favorite.1996']}" 
   println "Favorite Movie (1997): ${System.properties['movie.favorite.1997']}"
   println "Favorite Movie (1981): ${System.properties['movie.favorite.1981']}"
   println "Favorite Movie (2012): ${System.properties['movie.favorite.2012']}"
   println "Favorite Movie (2013): ${System.properties['movie.favorite.2013']}"
}

def displayGradleProjectProperties()
{
   println "\n=== Gradle Project Properties ==="
   println "Favorite Movie (1994): ${getProjectProperty('movie.favorite.1994')}"
   println "Favorite Movie (1996): ${getProjectProperty('movie.favorite.1996')}"
   println "Favorite Movie (1997): ${getProjectProperty('movie.favorite.1997')}"
   println "Favorite Movie (1981): ${getProjectProperty('movie.favorite.1981')}"
   println "Favorite Movie (2012): ${getProjectProperty('movie.favorite.2012')}"
   println "Favorite Movie (2013): ${getProjectProperty('movie.favorite.2013')}"
}

def String getProjectProperty(String propertyName)
{
   String movieTitle = "null"
   if (hasProperty(propertyName))
   {
      movieTitle = this.properties[propertyName]
   }
   return movieTitle
}

Some of the properties to be passed to this script will be provided on the command-line with -P, some will be provided on the command line with -D, one will be provided via environment variable, and two will be provided via gradle.properties file in the same directory as the build. That gradle.properties file is shown next.

gradle.properties

movie.favorite.2013=Star Trek into Darkness
systemProp.movie.favorite.2012=Skyfall

With the gradle.properties file in place, the other two interesting parts of the example are the setting of the environment variable. The example here is in DOS, but the same thing could be done with slightly different syntax in Linux environments. The DOS/Windows command is: set ORG_GRADLE_PROJECT.movie.favorite.1981="Raiders of the Lost Ark"

For this demonstration, I'll run the Gradle build script with -D and -P parameters: gradle -b build-properties.gradle displayProperties -Pmovie.favorite.1996="Independence Day" -Dmovie.favorite.1997=Gattaca -Dorg.gradle.project.movie.favorite.1994="Shawshank Redemption"

When running the above-listed Gradle build script with the indicated gradle.properties file in place, with the indicated environment variable specified, and with the command just shown, the output looks that shown in the next screen snapshot.

The screen snapshot indicates how properties are seen/accessed in the Gradle build depending on their source and naming convention. In short, the output demonstrates the following "rules" of property availability in a Gradle build:

• Command-line -P properties are "project properties"
• Command-line -D properties are, with one exception, "system properties"
• Command-line -D properties that begin with org.gradle.project. are "project properties"
• Properties specified in gradle.properties are, with one exception, "project properties"
• Properties specified in gradle.properties that begin with systemProp. are "system properties"
• Properties specified via environment variable are, with one exception, "system properties"
• Properties specified via environment variables that begin with ORG_GRADLE_PROJECT_ are "project properties"

Conclusion

Gradle provides numerous approaches for specifying properties that can be used to customize the Gradle build.