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.3"
}
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.3'
}
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"
Features
-
Parameters can be supplied via
-P
on the command line, viagradle.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 addingincludeBuild("gradle/plugins")
to your settings file. -
Configure the
gradle/plugins
build to include yourbuild-parameters
subproject by addinginclude("build-parameters")
to the settings script of thegradle/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.3"
}
plugins {
id 'org.gradlex.build-parameters' version '1.3'
}
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'
}
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.3"
}
buildParameters {
pluginId("mybuild.build-params")
}
plugins {
id 'org.gradlex.build-parameters' version '1.3'
}
buildParameters {
pluginId 'mybuild.build-params'
}
And then in your build script:
plugins {
id("mybuild.build-params")
}
plugins {
id 'mybuild.build-params'
}
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, 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
}
}
Boolean parameters can only be set to 'true' or 'false'.
The empty string is also mapped to 'true' so that -Pmybool
is the same as -Pmybool=true
.
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;
}
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 |