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 also by passing values via the command line.
The default properties we can access in a Gradle build are displayed in the following table:
Name |
Type |
Default value |
---|---|---|
|
|
The project instance. |
|
|
The name of the project directory. The name is read-only. |
|
|
The absolute path of the project. |
|
|
Description of the project. |
|
|
The directory containing the build script. The value is read-only. |
|
|
Directory with the name build in the directory containing the build script. |
|
|
Not specified. |
|
|
Not specified. |
|
|
An |
The following build file has a task to show 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 'chapter3' Name: defaultProperties Path: :defaultProperties Project directory: /Users/mrhaki/Projects/gradle-book/samples/chapter3 Build directory: /Users/mrhaki/Projects/gradle-book/samples/chapter3/build Version: 1.0 Group: Sample Description: Sample build file to show project properties AntBuilder: org.gradle.api.internal.project.DefaultAntBuilder@1ebafda6 BUILD SUCCESSFUL Total time: 2.328 secs
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 property
customProperty
with a String
value custom
. In the showProperties
task, we show the value of the property:
ext.customProperty = 'custom' // Or we can use ext{} script block. ext { anotherCustomProperty = 'custom' } task showProperties { doLast { println customProperty println ext.customProperty println project.customProperty } }
After running the script, we get the following output:
$ gradle sP :showProperties custom custom BUILD SUCCESSFUL Total time: 2.419 secs
Instead of defining the property directly in the build script, 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.
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: 2.266 secs
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
, then the name of the property we want to set, followed by the value.
We can use the same build script we created before:
task showProperties { doLast { println "Version: $version" println "Custom property: $customProperty" } }
But 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.656 secs
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 the ORG_GRADLE_PROJECT_version
and ORG_GRADLE_PROJECT_customProperty
environment variables, then we run our showProperties
task:
$ export ORG_GRADLE_PROJECT_version=3.1 $ export ORG_GRADLE_PROJECT_customProperty="Set by environment variable" $ gradle showProp :showProperties Version: 3.0 Custom property: Set by environment variable BUILD SUCCESSFUL Total time: 1.668 secs
Finally, 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 in the 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:
version = 4.0 customProperty = Property value from gradle.properties
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.623 secs
3.138.172.130