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