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


task displayProperties << {

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.


movie.favorite.2013=Star Trek into Darkness

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”


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

Related Whitepaper:

Functional Programming in Java: Harnessing the Power of Java 8 Lambda Expressions

Get ready to program in a whole new way!

Functional Programming in Java will help you quickly get on top of the new, essential Java 8 language features and the functional style that will change and improve your code. This short, targeted book will help you make the paradigm shift from the old imperative way to a less error-prone, more elegant, and concise coding style that’s also a breeze to parallelize. You’ll explore the syntax and semantics of lambda expressions, method and constructor references, and functional interfaces. You’ll design and write applications better using the new standards in Java 8 and the JDK.

Get it Now!  

Leave a Reply

× 6 = forty eight

Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

20,709 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books