Setting Gradle properties to build a project [Tutorial]

10 min read

A Gradle script is a program. We use a Groovy DSL to express our build logic. Gradle has several useful built-in methods to handle files and directories as we often deal with files and directories in our build logic.

In today’s post, we will take a look at how to set Gradle properties in a project build. We will also see how to use the Gradle Wrapper task to distribute a configurable Gradle with our build scripts.

This article is an excerpt taken from, ‘Gradle Effective Implementations Guide – Second Edition’ written by Hubert Klein Ikkink.

Setting Gradle project properties

In a Gradle build file, we can access several properties that are defined by Gradle, but we can also create our own properties. We can set the value of our custom properties directly in the build script and we can also do this by passing values via the command line.

The default properties that we can access in a Gradle build are displayed in the following table:

NameTypeDefault valueprojectProjectThe project instance.nameStringThe name of the project directory. The name is read-only.pathStringThe absolute path of the project.descriptionStringThe description of the project.projectDirFileThe directory containing the build script. The value is read-only.buildDirFileThe directory with the build name in the directory, containing the build script.rootDirFileThe directory of the project at the root of a project structure.groupObjectNot specified.versionObjectNot specified.antAntBuilderAn AntBuilder instance.

The following build file has a task of showing the value of the properties:

version = '1.0' 
group = 'Sample' 
description = 'Sample build file to show project properties' 
 
task defaultProperties << { 
    println "Project: $project" 
    println "Name: $name" 
    println "Path: $path" 
    println "Project directory: $projectDir" 
    println "Build directory: $buildDir" 
    println "Version: $version" 
    println "Group: $project.group" 
    println "Description: $project.description" 
    println "AntBuilder: $ant" 
}

When we run the build, we get the following output:

$ gradle defaultProperties
:defaultProperties
Project: root project 'props'
Name: defaultProperties
Path: :defaultProperties
Project directory: /Users/mrhaki/gradle-book/Code_Files/props
Build directory: /Users/mrhaki/gradle-book/Code_Files/props/build
Version: 1.0
Group: Sample
Description: Sample build file to show project properties
AntBuilder: org.gradle.api.internal.project.DefaultAntBuilder@3c95cbbd
    
BUILD SUCCESSFUL
    
Total time: 1.458 secs

Defining custom properties in script

To add our own properties, we have to define them in an ext{} script block in a build file. Prefixing the property name with ext. is another way to set the value. To read the value of the property, we don’t have to use the ext. prefix, we can simply refer to the name of the property. The property is automatically added to the internal project property as well.

In the following script, we add a customProperty property with a String value custom. In the showProperties task, we show the value of the property:

// Define new property. 
ext.customProperty = 'custom' 
 
// Or we can use ext{} script block. 
ext { 
  anotherCustomProperty = 'custom' 
} 
 
task showProperties { 
    ext { 
        customProperty = 'override' 
    } 
    doLast { 
        // We can refer to the property 
        // in different ways: 
        println customProperty 
        println project.ext.customProperty 


        println project.customProperty 
    } 
}

After running the script, we get the following output:

$ gradle showProperties
:showProperties
override
custom
custom
    
BUILD SUCCESSFUL
    
Total time: 1.469 secs

Defining properties using an external file

We can also set the properties for our project in an external file. The file needs to be named gradle.properties, and it should be a plain text file with the name of the property and its value on separate lines. We can place the file in the project directory or Gradle user home directory. The default Gradle user home directory is $USER_HOME/.gradle. A property defined in the properties file, in the Gradle user home directory, overrides the property values defined in a properties file in the project directory.

We will now create a gradle.properties file in our project directory, with the following contents.

We use our build file to show the property values:

task showProperties { 
    doLast { 
        println "Version: $version" 
        println "Custom property: $customProperty" 
    } 
}

If we run the build file, we don’t have to pass any command-line options, Gradle will use gradle.properties to get values of the properties:

$ gradle showProperties
:showProperties
Version: 4.0
Custom property: Property value from gradle.properties
    
BUILD SUCCESSFUL
    
Total time: 1.676 secs

Passing properties via the command line

Instead of defining the property directly in the build script or external file, we can use the -P command-line option to add an extra property to a build. We can also use the -P command-line option to set a value for an existing property. If we define a property using the -P command-line option, we can override a property with the same name defined in the external gradle.properties file.

The following build script has a showProperties task that shows the value of an existing property and a new property:

task showProperties { 
    doLast { 
        println "Version: $version" 
        println "Custom property: $customProperty" 
    } 
}

Let’s run our script and pass the values for the existing version property and the non-existent customProperty:

$ gradle -Pversion=1.1 -PcustomProperty=custom showProperties
:showProperties
Version: 1.1
Custom property: custom
    
BUILD SUCCESSFUL
    
Total time: 1.412 secs

Defining properties via system properties

We can also use Java system properties to define properties for our Gradle build. We use the -D command-line option just like in a normal Java application. The name of the system property must start with org.gradle.project, followed by the name of the property we want to set, and then by the value.

We can use the same build script that we created before:

task showProperties { 
    doLast { 
        println "Version: $version" 
        println "Custom property: $customProperty" 
    } 
}

However, this time we use different command-line options to get a result:

$ gradle -Dorg.gradle.project.version=2.0 -Dorg.gradle.project.customProperty=custom showProperties
:showProperties
Version: 2.0
Custom property: custom
    
BUILD SUCCESSFUL
    
Total time: 1.218 secs

Adding properties via environment variables

Using the command-line options provides much flexibility; however, sometimes we cannot use the command-line options because of environment restrictions or because we don’t want to retype the complete command-line options each time we invoke the Gradle build. Gradle can also use environment variables set in the operating system to pass properties to a Gradle build.

The environment variable name starts with ORG_GRADLE_PROJECT_ and is followed by the property name. We use our build file to show the properties:

task showProperties { 
    doLast { 
        println "Version: $version" 
        println "Custom property: $customProperty" 
    } 
}

Firstly, we set ORG_GRADLE_PROJECT_version and ORG_GRADLE_PROJECT_customProperty environment variables, then we run our showProperties task, as follows:

$ ORG_GRADLE_PROJECT_version=3.1 
ORG_GRADLE_PROJECT_customProperty="Set by environment variable" 
gradle showProp
:showProperties
Version: 3.1
Custom property: Set by environment variable
    
BUILD SUCCESSFUL
    
Total time: 1.373 secs

Using the Gradle Wrapper

Normally, if we want to run a Gradle build, we must have Gradle installed on our computer. Also, if we distribute our project to others and they want to build the project, they must have Gradle installed on their computers. The Gradle Wrapper can be used to allow others to build our project even if they don’t have Gradle installed on their computers.

The wrapper is a batch script on the Microsoft Windows operating systems or shell script on other operating systems that will download Gradle and run the build using the downloaded Gradle.

By using the wrapper, we can make sure that the correct Gradle version for the project is used. We can define the Gradle version, and if we run the build via the wrapper script file, the version of Gradle that we defined is used.

Creating wrapper scripts

To create the Gradle Wrapper batch and shell scripts, we can invoke the built-in wrapper task. This task is already available if we have installed Gradle on our computer. Let’s invoke the wrapper task from the command-line:

$ gradle wrapper
:wrapper
    
BUILD SUCCESSFUL
    
Total time: 0.61 secs

After the execution of the task, we have two script files—gradlew.bat and gradlew—in the root of our project directory. These scripts contain all the logic needed to run Gradle. If Gradle is not downloaded yet, the Gradle distribution will be downloaded and installed locally.

In the gradle/wrapper directory, relative to our project directory, we find the gradle-wrapper.jar and gradle-wrapper.properties files. The gradle-wrapper.jar file contains a couple of class files necessary to download and invoke Gradle. The gradle-wrapper.properties file contains settings, such as the URL, to download Gradle. The gradle-wrapper.properties file also contains the Gradle version number. If a new Gradle version is released, we only have to change the version in the gradle-wrapper.properties file and the Gradle Wrapper will download the new version so that we can use it to build our project.

All the generated files are now part of our project. If we use a version control system, then we must add these files to the version control. Other people that check out our project can use the gradlew scripts to execute tasks from the project. The specified Gradle version is downloaded and used to run the build file.

If we want to use another Gradle version, we can invoke the wrapper task with the --gradle-version option. We must specify the Gradle version that the Wrapper files are generated for. By default, the Gradle version that is used to invoke the wrapper task is the Gradle version used by the wrapper files.

To specify a different download location for the Gradle installation file, we must use the --gradle-distribution-url option of the wrapper task. For example, we could have a customized Gradle installation on our local intranet, and with this option, we can generate the Wrapper files that will use the Gradle distribution on our intranet.

In the following example, we generate the wrapper files for Gradle 2.12 explicitly:

$ gradle wrapper --gradle-version=2.12
:wrapper
    
BUILD SUCCESSFUL
    
Total time: 0.61 secs

Customizing the Gradle Wrapper

If we want to customize properties of the built-in wrapper task, we must add a new task to our Gradle build file with the org.gradle.api.tasks.wrapper.Wrapper type. We will not change the default wrapper task, but create a new task with new settings that we want to apply. We need to use our new task to generate the Gradle Wrapper shell scripts and support files.

We can change the names of the script files that are generated with the scriptFile property of the Wrapper task. To change the name and location of the generated JAR and properties files, we can change the jarFile property:

task createWrapper(type: Wrapper) { 
    // Set Gradle version for wrapper files. 
    gradleVersion = '2.12' 
 
    // Rename shell scripts name to 
    // startGradle instead of default gradlew. 
    scriptFile = 'startGradle' 
 
    // Change location and name of JAR file 
    // with wrapper bootstrap code and 
    // accompanying properties files. 
    jarFile = "${projectDir}/gradle-bin/gradle-bootstrap.jar" 
}

If we run the createWrapper task, we get a Windows batch file and shell script and the Wrapper bootstrap JAR file with the properties file is stored in the gradle-bin directory:

$ gradle createWrapper
:createWrapper
    
BUILD SUCCESSFUL
    
Total time: 0.605 secs
$ tree .
.
├── gradle-bin
│  ├── gradle-bootstrap.jar
│   └── gradle-bootstrap.properties
├── startGradle
├── startGradle.bat
└── build.gradle
    
 2 directories, 5 files

To change the URL from where the Gradle version must be downloaded, we can alter the distributionUrl property. For example, we could publish a fixed Gradle version on our company intranet and use the distributionUrl property to reference a download URL on our intranet. This way we can make sure that all developers in the company use the same Gradle version:

task createWrapper(type: Wrapper) { 
    // Set URL with custom Gradle distribution. 
    distributionUrl = 'http://intranet/gradle/dist/gradle-custom-       2.12.zip' 
}

We discussed the Gradle properties and how to use the Gradle Wrapper to allow users to build our projects even if they don’t have Gradle installed. We discussed how to customize the Wrapper to download a specific version of Gradle and use it to run our build.

If you’ve enjoyed reading this post, do check out our book ‘Gradle Effective Implementations Guide – Second Edition‘ to know more about how to use Gradle for Java Projects.