All Implemented Interfaces and Traits:

org.gradle.api.Plugin

class PropertiesPlugin
extends java.lang.Object

This is the main class for the properties plugin. When the properties plugin is applied to a project, it uses the values of the environmentName and gradleUserName properties to reload all the project properties in the following order:

1. gradle.properties in the parent project's directory, if the project is a module of a multi-project build.
2. gradle-${environmentName}.properties in the parent project's directory, if the project is a module of a multi-project build. If no environment name is specified, the default is "local".
3. gradle.properties in the project directory
4. gradle-${environmentName}.properties in the project directory. If no environment name is specified, the default is "local".
5. gradle.properties in the user's ${gradleUserHomeDir} directory.
6. If the ${gradleUserName} property is set, gradle-${gradleUserName}.properties in the user's ${gradleUserHomeDir} directory.
7. Environment variables starting with ORG_GRADLE_PROJECT_.
8. System properties starting with org.gradle.project..
9. properties defined on the command line with the -P option.

When the plugin is applied to a Settings object, it uses the environmentName and gradleUserName properties to reload all the settings properties in the following order:

1. gradle.properties in the directory where settings.gradle is located.
2. gradle-${environmentName}.properties in the directory where settings.gradle is located. If no environment name is specified, the default is "local".
3. gradle.properties in the user's ${gradleUserHomeDir} directory.
4. If the ${gradleUserName} property is set, gradle-${gradleUserName}.properties in the user's ${gradleUserHomeDir} directory.
5. Environment variables starting with ORG_GRADLE_PROJECT_.
6. System properties starting with org.gradle.project..
7. properties defined on the command line with the -P option.

As mentioned, this plugin looks for the gradle-${environmentName}.properties file in the project directory for projects, or the directory with settings.gradle if the plugin is applied to a Settings object. You can change this behavior by specifying a value for the environmentFileDir property. It is strongly recommended to use a subdirectory of the project or settings directory when using this option. This property only effects where the environment specific files are located, it does not change where the plugin looks for the other files, such as the user files or default gradle files.

environmentFileDir, environmentName, and gradleUserName are the properties that this plugin use by default to get the location of the environment files and the names of the environment and gradle user to use. If you don't like these names, or if there is a clash with properties you already use in your build, you can configure the properties the plugin will use. You can tell the plugin what property to use for the environment file directory by setting a value for the propertiesPluginEnvironmentFileDirProperty property. You can tell the plugin what property to use for the name of the environment by setting the propertiesPluginEnvironmentNameProperty, and you can tell the plugin what property to use to set the user name by setting a value for the propertiesPluginGradleUserNameProperty property. Those properties have to be set before this plugin is applied. That means you can put them in the standard property file locations supported by Gradle itself, in environment variables, system properties, -P options or in the build.gradle file itself before applying this plugin.

The last thing to set a property wins. All files are optional unless an environment or user is specified, in which case the file belonging to the specified environment or user must exist. If an environment file directory is specified, that directory must exist, be a directory, and be readable.

As properties are set, they are also placed in a filterTokens property. The filterTokens property is a map of tokens that can be used when doing a filtered file copy. There will be a token for each property defined by one of the listed methods. The name of each token will be the name of the property from the properties file, after converting the camel case property name to dot notation. For example, if you have a myPropertyName property in the file, the plugin will create a my.property.name filter token, whose value is the property's value. The original camel case name will also be added as token.

By default, this plugin fails the build if you specify an environment, but no file exists for that environment. You can use the propertiesPluginIgnoreMissingEnvFile property to override this behavior.

Finally, the properties plugin also adds some properties to every task in your build:

requiredProperty and requiredProperties can be used to define what properties must be present for that task to work. Required properties will be checked after configuration is complete, but before any tasks are executed.

recommendedProperty and recommendedProperties can be used to define properties that the task can work without, but it (or the deployed application) will use a default value for the property. The value of this property is that we can prompt new developers to either provide a property, or make sure default config files are set up correctly.

Special thanks to Hans Dockter at Gradleware for showing me how to attach to the right place in the Gradle build lifecycle.

Authors:

Steven C. Saliman