This chapter looks at some of the details of writing a build script.
Gradle provides a domain specific language, or DSL, for describing builds. This build language is available in Groovy and Kotlin.
A Groovy build script can contain any Groovy language element.[1] A Kotlin build script can contain any Kotlin language element. Gradle assumes that each build script is encoded using UTF-8.
Build scripts describe your build by configuring projects. A project is an abstract concept, but you typically map a Gradle project to a software component that needs to be built, like a library or an application. Each build script you have is associated with an object of type Project and as the build script executes, it configures this Project.
In fact, almost all top-level properties and blocks in a build script are part of the Project API. To demonstrate, take a look at this example build script that prints the name of its project, which is accessed via the Project.name property:
Both println statements print out the same property. The first uses the top-level reference to the name property of the Project object. The other statement uses the project property available to any build script, which returns the associated Project object. Only if you define a property or a method which has the same name as a member of the Project object, would you need to use the project property.
The Project object provides some standard properties, which are available in your build script. The following table lists a few of the commonly used ones.
| Name | Type | Default Value |
|---|---|---|
|
The |
|
|
|
The name of the project directory. |
|
|
The absolute path of the project. |
|
|
A description for the project. |
|
|
The directory containing the build script. |
|
|
|
|
|
|
|
|
|
|
An |
|
Important
|
Script with other targets
The build scripts described here target |
When Gradle executes a Groovy build script (.gradle), it compiles the script into a class which implements Script. This means that all of the properties and methods declared by the Script interface are available in your script.
When Gradle executes a Kotlin build script (.gradle.kts), it compiles the script into a subclass of KotlinBuildScript. This means that all of the visible properties and functions declared by the KotlinBuildScript type are available in your script. Also see the KotlinSettingsScript and KotlinInitScript types respectively for settings scripts and init scripts.
There are two kinds of variables that can be declared in a build script: local variables and extra properties.
Local variables are declared with the def keyword. They are only visible in the scope where they have been declared. Local variables are a feature of the underlying Groovy language.
Local variables are declared with the val keyword. They are only visible in the scope where they have been declared. Local variables are a feature of the underlying Kotlin language.
All enhanced objects in Gradle’s domain model can hold extra user-defined properties. This includes, but is not limited to, projects, tasks, and source sets.
Extra properties can be added, read and set via the owning object’s ext property. Alternatively, an ext block can be used to add multiple properties at once.
Extra properties can be added, read and set via the owning object’s extra property. Alternatively, they can be addressed via Kotlin delegated properties using by extra.
In this example, an ext block adds two extra properties to the project object. Additionally, a property named purpose is added to each source set by setting ext.purpose to null (null is a permissible value). Once the properties have been added, they can be read and set like predefined properties.
In this example, two extra properties are added to the project object using by extra. Additionally, a property named purpose is added to each source set by setting extra["purpose"] to null (null is a permissible value). Once the properties have been added, they can be read and set on extra.
By requiring special syntax for adding a property, Gradle can fail fast when an attempt is made to set a (predefined or extra) property but the property is misspelled or does not exist. Extra properties can be accessed from anywhere their owning object can be accessed, giving them a wider scope than local variables. Extra properties on a project are visible from its subprojects.
For further details on extra properties and their API, see the ExtraPropertiesExtension class in the API documentation.
You can also configure arbitrary objects using an external script.
|
Caution
|
Only supported from a Groovy script
Configuring arbitrary objects using an external script is not yet supported by the Kotlin DSL. See gradle/kotlin-dsl#659 for more information. |
gradle -q configure> gradle -q configure
link:{snippetsPath}/tutorial/configureObjectUsingScript/tests/configureObjectUsingScript.out[role=include]
|
Tip
|
Looking for some Kotlin basics, the Kotlin reference documentation and Kotlin Koans should be useful to you. |
The Groovy language provides plenty of features for creating DSLs, and the Gradle build language takes advantage of these. Understanding how the build language works will help you when you write your build script, and in particular, when you start to write custom plugins and tasks.
Groovy adds lots of useful methods to the standard Java classes. For example, Iterable gets an each method, which iterates over the elements of the Iterable:
Have a look at https://groovy-lang.org/gdk.html for more details.
Groovy automatically converts a property reference into a call to the appropriate getter or setter method.
Parentheses are optional for method calls.
Groovy provides some shortcuts for defining List and Map instances. Both kinds of literals are straightforward, but map literals have some interesting twists.
For instance, the “apply” method (where you typically apply plugins) actually takes a map parameter. However, when you have a line like “apply plugin:'java'”, you aren’t actually using a map literal, you’re actually using “named parameters”, which have almost exactly the same syntax as a map literal (without the wrapping brackets). That named parameter list gets converted to a map when the method is called, but it doesn’t start out as a map.
The Gradle DSL uses closures in many places. You can find out more about closures here. When the last parameter of a method is a closure, you can place the closure after the method call:
Each closure has a delegate object, which Groovy uses to look up variable and method references which are not local variables or parameters of the closure. Gradle uses this for configuration closures, where the delegate object is set to the object to be configured.
To make build scripts more concise, Gradle automatically adds a set of import statements to the Gradle scripts. This means that instead of using throw new org.gradle.api.tasks.StopExecutionException() you can just type throw new StopExecutionException() instead.
Listed below are the imports added to each script:
link:default-imports.txt[role=include]