Build Parameters Gradle plugin

The Build Parameters Gradle plugin provides compile-safe access to parameters supplied to a Gradle build. It does so by providing a DSL to describe parameters and their types. Based on this description it generates code for a plugin that can then be applied to your build. In that sense, the Build Parameters Gradle plugin is not a conventional plugin, but a meta plugin that you use to generate a plugin for your build. See the Setup section for more information on how to configure your build to use this plugin.

Compatible with Java 8 and Gradle 7.1 or later.

Primer

Describe build parameters using a rich DSL:

plugins {
    id("org.gradlex.build-parameters") version "1.4.4"
}

buildParameters {
    group("deployment") {
        string("username") {
            description.set("The username used for deploying to the artifact repository")
            defaultValue.set("deployer")
        }
        string("password") {
            description.set("The password used for deploying to the artifact repository")
        }
    }
}

plugins {
    id 'org.gradlex.build-parameters' version '1.4.4'
}

buildParameters {
    group('deployment') {
        string('username') {
            description = 'The username used for deploying to the artifact repository'
            defaultValue = 'deployer'
        }
        string('password') {
            description = 'The password used for deploying to the artifact repository'
        }
    }
}

Use compile-safe accessor in your build scripts to access parameter values:

plugins {
    id("maven-publish")
    id("build-parameters")
}

publishing {
    repositories {
        maven {
            url = uri("https://repo.my-company.com")
            credentials {
                // username has a default and is therefore of type String
                username = buildParameters.deployment.username
                // password does not have a default and is therefore of type Provider<String>
                password = buildParameters.deployment.password.get()
            }
        }
    }
}

plugins {
    id 'maven-publish'
    id 'build-parameters'
}

publishing {
    repositories {
        maven {
            url = 'https://repo.my-company.com'
            credentials {
                // username has a default and is therefore of type String
                username = buildParameters.deployment.username
                // password does not have a default and is therefore of type Provider<String>
                password = buildParameters.deployment.password.get()
            }
        }
    }
}

Use compile-safe accessor in your settings.gradle(.kts) (since 1.1):

plugins {
    id("build-parameters")
}

dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("https://repo.my-company.com")
            credentials {
                // username has a default and is therefore of type String
                username = the<BuildParametersExtension>().deployment.username
                // password does not have a default and is therefore of type Provider<String>
                password = the<BuildParametersExtension>().deployment.password.get()
            }
        }
    }
}

plugins {
    id("build-parameters")
}

dependencyResolutionManagement {
    repositories {
        maven {
            url = 'https://repo.my-company.com'
            credentials {
                // username has a default and is therefore of type String
                username = buildParameters.deployment.username
                // password does not have a default and is therefore of type Provider<String>
                password = buildParameters.deployment.password.get()
            }
        }
    }
}

Run your build and pass the parameters to it using -P commandline parameters:

./gradlew :publish -Pdeployment.username="jane" -Pdeployment.password="super-secret"

Or explore available parameters by running the parameters task:

Features

Parameters can be supplied via -P on the command line, via gradle.properties files or via environment variables
Definition of default values
Parameters can be grouped
Support for various types:
- String
- Integer
- Boolean
- Enumerations

Setup

In order to use this plugin you need an included build that will produce the resulting plugin. A typical project layout looks like this:

my-project
 |- gradle
 |   |- plugins
 |      |- build-parameters
 |      |  |- build.gradle.kts (3)
 |      |- settings.gradle.kts (2)
 |- src
 |- build.gradle.kts (4)
 |- settings.gradle.kts (1)

Configure the build to include the gradle/plugins build by adding includeBuild("gradle/plugins") to your settings file.
Configure the gradle/plugins build to include your build-parameters subproject by adding include("build-parameters") to the settings script of the gradle/plugins build.
Use the org.gradlex.build-parameters plugin to describe your build parameters. See the Usage section for more information on this.
Finally, you can now use the generated plugin in your build scripts.

Usage

Add the plugin to your build-parameters subproject using the plugins block:

plugins {
    id("org.gradlex.build-parameters") version "1.4.4"
}

plugins {
    id 'org.gradlex.build-parameters' version '1.4.4'
}

The plugin generates a new plugin based on the description in the DSL. The generated plugin will use build-parameters as plugin ID. This plugin can then be applied to your build scripts in order to access parameters supplied to the build. For that, the generated plugin creates an extension called buildParameters.

plugins {
    id("build-parameters")
}

if (buildParameters.myParameter) {
    println("myParameter was set to true")
}

plugins {
    id 'build-parameters'
}

if (buildParameters.myParameter) {
    println 'myParameter was set to true'
}

Defining parameters

This plugin supports String, boolean, integer and enum types for modelling build parameters. Parameters can be defined with and without default value. If no default value is defined, or if the parameter is mandatory, the resulting compile-safe parameter accessor will be a org.gradle.api.provider.Provider. If a default value is defined, the resulting compile-safe parameter accessor will have the actual parameter type.

String parameters

Use the string method to define parameters of type String:

buildParameters {
    string("myString") {
        description.set("Optional description of the string parameter")
        defaultValue.set("Optional default value")
    }
}

buildParameters {
    string('myString') {
        description = 'Optional description of the string parameter'
        defaultValue = 'Optional default value'
    }
}

Int parameters

Use the integer method to define parameters of type Integer:

buildParameters {
    integer("myInt") {
        description.set("Optional description of the int parameter")
        defaultValue.set(9) // optional
    }
}

buildParameters {
    integer('myInt') {
        description = 'Optional description of the int parameter'
        defaultValue = 9 // optional
    }
}

Boolean parameters

Use the bool method to define parameters of type Boolean:

buildParameters {
    bool("mybool") {
        description.set("Optional description of the bool parameter")
        defaultValue.set(true) // optional
    }
}

buildParameters {
    bool('mybool') {
        description = 'Optional description of the bool parameter'
        defaultValue = false // optional
    }
}

String values 'true', and '1' are mapped to true. The empty string is also mapped to true so that -Pmybool is the same as -Pmybool=true. Only the string value 'false' is mapped to false. All other values will lead to an error during build configuration.

Enum parameters

Use the enumeration method to define enumeration parameters. The build-parameters plugin will generate an enum class based on the name of the parameter and the supplied value list.

buildParameters {
    enumeration("myEnum") {
        description.set("Optional description of the enum parameter")
        values.addAll("One", "Two", "Three")
        defaultValue.set("One") // optional
    }
}

buildParameters {
    enumeration('myEnum') {
        description = 'Optional description of the enum parameter'
        values = ['One', 'Two', 'Three']
        defaultValue = 'One' // optional
    }
}

Using an enum parameter you can restrict he values that can be passed to the build. The generated enum class will look like the following:

public enum MyEnum {
    One, Two, Three;
}

Mandatory parameters without default value

A parameter can be made mandatory, which means that a user will see an actionable error message when not setting the parameter:

buildParameters {
    string("mandatoryString") {
        description.set("Optional description of the mandatory parameter (shown in error message when not set)")
        mandatory.set(true)
    }
}

buildParameters {
    string('mandatoryString') {
        description = 'Optional description of the mandatory parameter (shown in error message when not set)'
        mandatory = true
    }
}

The generated accessor will be a provider and the error message will only be triggered when the provider is accessed for the first time in the build. This means that if the parameter is only used to configure a certain task, the parameter is only mandatory for build runs that include that task. Setting a parameter to mandatory has no effect if the parameter has a defaultValue.

Grouping parameters

Parameters can be namespaced using the group method:

buildParameters {
    group("myGroup") {
        description.set("Optional description of the group")
        string("myString")
        integer("myInt")
    }
}

buildParameters {
    group('myGroup') {
        description = "Optional description of the group"
        string('myString')
        integer('myInt')
    }
}

The group name will be used to namespace parameters when supplied via the command line:

./gradlew help -PmyGroup.myString=hello -PmyGroup.myInt=1

And when accessing them in build scripts:

println(buildParameters.myGroup.myString.get())
println(buildParameters.myGroup.myInt.get())

println buildParameters.myGroup.myString.get()
println buildParameters.myGroup.myInt.get()

Deriving parameter values from environment variables

Sometimes you may want to supply a build parameter using the system environment. A good example of this is the CI variable that most CI servers set. By looking at this variable the build can detect that it’s running in a CI environment.

Parameters supplied via the command line take precedence over those supplied via the environment.

In order to derive a build parameter value from the environment, use the fromEnvironment() method:

buildParameters {
    bool("ci") {
        fromEnvironment()
        defaultValue.set(false)
    }
}

buildParameters {
    bool('ci') {
        fromEnvironment()
        defaultValue = false
    }
}

The fromEnvironment() method will translate the parameters property path into SCREAMING_SNAKE_CASE and use that to look up the value in the environment. In the example above ci will be translated to CI.

The translation also works in combination with grouped paramters:

buildParameters {
    group("myGroup") {
        string("someString") {
            fromEnvironment()
        }
    }
}

buildParameters {
    group('myGroup') {
        string('someString') {
            fromEnvironment()
        }
    }
}

The mygroup.someString parameter can then be set by configuring the MYGROUP_SOMESTRING environment variable.

If you need full control over the environment variable name used to look up the parameters value, use the fromEnvironment(String) overload.

buildParameters {
    group("someGroup") {
        string("someString") {
            fromEnvironment("SOME_CUSTOM_ENV_VAR")
        }
    }
}

buildParameters {
    group('someGroup') {
        string('someString') {
            fromEnvironment('SOME_CUSTOM_ENV_VAR')
        }
    }
}

Given the configuration above, the generated plugin will look up the SOME_CUSTOM_ENV_VAR variable for setting the value of myGroup.someString.

The plugin does not verify whether the value supplied to fromEnvironment(String) is a valid environment variable name. It’s the responsibility of the user to make sure only upper case letters and underscores are used.

Controlling the generated plugin ID

By default, build-parameters is used as plugin ID for the generated plugin. The ID of the generated plugin can be configured using the pluginId method.

plugins {
    id("org.gradlex.build-parameters") version "1.4.4"
}

buildParameters {
    pluginId("mybuild.build-params")
}

plugins {
    id 'org.gradlex.build-parameters' version '1.4.4'
}

buildParameters {
    pluginId 'mybuild.build-params'
}

And then in your build script:

plugins {
    id("mybuild.build-params")
}

plugins {
    id 'mybuild.build-params'
}

Disable build parameter validation

By default, the generated plugin forbids using -P for things that are not defined as build parameter. It also fails if a user accidentally used -D to set one of the defined build parameters.

If you do not want this validation in your build, you can disable it.

buildParameters {
    enableValidation.set(false)
}

buildParameters {
    enableValidation = false
}