Gradle Kotlin DSL Primer

Both IntelliJ IDEA and Android Studio will detect when you make changes to your build logic and offer two suggestions:

We recommend disabling automatic build import while enabling automatic reloading of script dependencies. This approach provides early feedback when editing Gradle scripts while giving you control over when the entire build setup synchronizes with your IDE.

See the Troubleshooting section to learn more.

To activate the Kotlin DSL, use the .gradle.kts extension for your build scripts instead of .gradle. This also applies to the settings file (e.g., settings.gradle.kts) and initialization scripts.

You can mix Groovy DSL and Kotlin DSL scripts within the same build. For example, a Kotlin DSL build script can apply a Groovy DSL one, and different projects in a multi-project build can use either.

To improve IDE support, we recommend following these conventions:

This helps the IDE identify the object "backing" the script, whether it’s Project, Settings, or Gradle.

All Kotlin DSL build scripts come with implicit imports, including:

Using internal Kotlin DSL APIs in plugins and build scripts can break builds when either Gradle or plugins are updated.

The Kotlin DSL API extends the public Gradle API with types listed in the corresponding API docs found in the packages above (but not in their subpackages).

Gradle Kotlin DSL scripts are compiled by Gradle during the configuration phase of your build.

Deprecation warnings found by the Kotlin compiler are reported on the console when compiling the scripts:

It is possible to configure your build to fail on any warning emitted during script compilation by setting the org.gradle.kotlin.dsl.allWarningsAsErrors Gradle property to true:

The Kotlin DSL currently provides various sets of type-safe model accessors, each tailored to different scopes.

For the main project build scripts and precompiled project script plugins:

For the main project settings script and precompiled settings script plugins:

The set of type-safe model accessors available is determined right before evaluating the script body, immediately after the plugins {} block. Model elements contributed after that point, such as configurations defined in your build script, will not work with type-safe model accessors:

However, this means you can use type-safe accessors for any model elements contributed by plugins that are applied by parent projects.

The following project build script demonstrates how you can access various configurations, extensions and other elements using type-safe accessors:

Note that accessors for elements of containers such as configurations, tasks, and sourceSets leverage Gradle’s configuration avoidance APIs. For example, on tasks, accessors are of type TaskProvider<T> and provide a lazy reference and lazy configuration of the underlying task.

Here are some examples illustrating when configuration avoidance applies:

For all other containers, accessors for elements are of type NamedDomainObjectProvider<T>, providing the same behavior:

Consider the sample build script shown above, which demonstrates the use of type-safe accessors. The following sample is identical, except it uses the apply() method to apply the plugin.

In this case, the build script cannot use type-safe accessors because the apply() call occurs in the body of the build script. You must use another techniques instead, as demonstrated here:

Type-safe accessors are unavailable for model elements contributed by the following:

You cannot use type-safe accessors in binary Gradle plugins implemented in Kotlin.

If you can’t find a type-safe accessor, fall back to using the normal API for the corresponding types. To do so, you need to know the names and/or types of the configured model elements. We will now show you how these can be discovered by examining the script in detail.

Some of the Gradle core plugins expose configurability with the help of a so-called convention object. These serve a similar purpose to — and have now been superseded by — extensions. Conventions are deprecated, so please avoid using convention objects when writing new plugins.

As mentioned above, the Kotlin DSL provides accessors only for convention objects on Project. However, there are situations where you may need to interact with a Gradle plugin that uses convention objects on other types. The Kotlin DSL provides the withConvention(T::class) {} extension function for this:

This technique is primarily necessary for source sets added by language plugins that have yet to be migrated to extensions.

All containers in Gradle implement NamedDomainObjectContainer<DomainObjectType>. Some containers can hold objects of different types and implement PolymorphicDomainObjectContainer<BaseType>. The simplest way to interact with containers is through these interfaces.

The following example demonstrates how you can use the named() method to configure existing tasks, and the register() method to create new tasks:

Another way to interact with containers is via Kotlin delegated properties. These are particularly useful if you need a reference to a container element that you can use elsewhere in the build. Additionally, Kotlin delegated properties can easily be renamed via IDE refactoring.

The following example achieves the same result as the one in the previous section, but it uses delegated properties and reuses those references instead of string-literal task paths:

When configuring several elements of a container, you can group interactions in a block to avoid repeating the container’s name on each interaction.

The following example demonstrates a combination of type-safe accessors, the container API, and Kotlin delegated properties:

The Kotlin DSL allows you to access project properties by binding them via Kotlin delegated properties.

The following snippet demonstrates this technique for a couple of project properties, one of which must be defined:

The same approach works in both settings and initialization scripts, except you use by settings and by gradle respectively in place of by project.

Extra properties are available on any object that implements the ExtensionAware interface.

In Kotlin DSL, you can access and create extra properties via delegated properties, using the by extra syntax as demonstrated in the following sample:

This approach works for all Gradle scripts: project build scripts, script plugins, settings scripts, and initialization scripts.

You can also access extra properties on a root project from a subproject using the following syntax:

Extra properties aren’t just limited to projects. For example, Task extends ExtensionAware, so you can attach extra properties to tasks as well.

Here’s an example that defines a new myNewTaskProperty on the test task and then uses that property to initialize another task:

If you’re happy to use eager configuration rather than the configuration avoidance APIs, you could use a single, "global" property for the report type, like this:

There is one last syntax for extra properties that treats extra as a map. We generally recommend against using this, as it bypasses Kotlin’s type checking and limits IDE support. However, it is more succinct than the delegated properties syntax and can be used if you only need to set an extra property without referencing it later.

Here is a simple example demonstrating how to set and read extra properties using the map syntax:

A property represents a value that can be set and read lazily:

A provider represents a read-only, lazily-evaluated value:

A named domain object provider represents a lazily-evaluated named object from a Gradle container (like tasks or extensions):

Lazy property assignment is supported from IntelliJ 2022.3 and from Android Studio Giraffe.

Gradle ships with kotlin-compiler-embeddable plus matching versions of kotlin-stdlib and kotlin-reflect libraries. For details, see the Kotlin section of Gradle’s compatibility matrix. The kotlin package from those modules is visible through the Gradle classpath.

The compatibility guarantees provided by Kotlin apply for both backward and forward compatibility.

The following Kotlin compiler arguments are used for compiling Kotlin DSL scripts, as well as Kotlin sources and scripts in projects with the kotlin-dsl plugin applied:

Both the Groovy and Kotlin languages support extending existing classes via Groovy Extension modules and Kotlin extensions.

To call a Kotlin extension function from Groovy, call it as a static function, passing the receiver as the first parameter:

Kotlin extension functions are package-level functions. You can learn how to locate the name of the type declaring a given Kotlin extension in the Package-Level Functions section of the Kotlin reference documentation.

To call a Groovy extension method from Kotlin, the same approach applies: call it as a static function passing the receiver as the first parameter:

Both the Groovy and Kotlin languages support named function parameters and default arguments, although they are implemented very differently. Kotlin has fully-fledged support for both, as described in the Kotlin language reference under named arguments and default arguments. Groovy implements named arguments in a non-type-safe way based on a Map<String, ?> parameter, which means they cannot be combined with default arguments. In other words, you can only use one or the other in Groovy for any given method.

You may sometimes have to call Groovy methods that take Closure arguments from Kotlin code. For example, some third-party plugins written in Groovy expect closure arguments.

In order to provide a way to construct closures while preserving Kotlin’s strong typing, two helper methods exist:

Both methods are useful in different circumstances and depend upon the method you are passing the Closure instance into.

Some plugins expect simple closures, as with the Bintray plugin:

In other cases, like with the Gretty Plugin when configuring farms, the plugin expects a delegate closure:

There sometimes isn’t a good way to tell, from looking at the source code, which version to use. Usually, if you get a NullPointerException with closureOf<T> {}, using delegateClosureOf<T> {} will resolve the problem.

These two utility functions are useful for configuration closures, but some plugins might expect Groovy closures for other purposes. The KotlinClosure0 to KotlinClosure2 types allows adapting Kotlin functions to Groovy closures with more flexibility:

If some plugin makes heavy use of Groovy metaprogramming, then using it from Kotlin or Java or any statically-compiled language can be very cumbersome.

The Kotlin DSL provides a withGroovyBuilder {} utility extension that attaches the Groovy metaprogramming semantics to objects of type Any.

The following example demonstrates several features of the method on the object target:

Another option when dealing with problematic plugins that assume a Groovy DSL build script is to configure them in a Groovy DSL build script that is applied from the main Kotlin DSL build script: