Saturday, January 18, 2014

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 -P from 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 named name.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 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 via System.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 variable ORG_GRADLE_PROJECT_name.last and its value would be available to the Gradle build as a project property with name name.last.

Properties can also be provided to a Gradle build via a properties file named 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 file had a property name.last=Marx and a property, 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.

task displayProperties << {

def displaySystemProperties()
   println "\n=== System Properties ==="
   println "Favorite Movie (1994): ${['movie.favorite.1994']}"
   println "Favorite Movie (1996): ${['movie.favorite.1996']}" 
   println "Favorite Movie (1997): ${['movie.favorite.1997']}"
   println "Favorite Movie (1981): ${['movie.favorite.1981']}"
   println "Favorite Movie (2012): ${['movie.favorite.2012']}"
   println "Favorite Movie (2013): ${['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 =[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 file in the same directory as the build. That file is shown next.
movie.favorite.2013=Star Trek into Darkness

With the 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"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"Shawshank Redemption"

When running the above-listed Gradle build script with the indicated 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 are, with one exception, "project properties"
  • Properties specified in 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"

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

No comments: