Gradle Kotlin DSL Primer

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

We recommend that you disable automatic build import, but enable automatic reloading of script dependencies. That way you get early feedback while editing Gradle scripts and control over when the whole build setup gets synchronized with your IDE.

The IDE support is provided by two components:

The level of support varies based on the versions of each.

If you run into trouble, the first thing you should try is running ./gradlew tasks from the command line to see whether your issue is limited to the IDE. If you encounter the same problem from the command line, then the issue is with the build rather than the IDE integration.

If you can run the build successfully from the command line but your script editor is complaining, then you should try restarting your IDE and invalidating its caches.

If the above doesn’t work and you suspect an issue with the Kotlin DSL script editor, you can:

From version 5.1 onwards, the log directory is cleaned up automatically. It is checked periodically (at most every 24 hours) and log files are deleted if they haven’t been used for 7 days.

For IDE problems outside of the Kotlin DSL script editor, please open issues in the corresponding IDE’s issue tracker:

Lastly, if you face problems with Gradle itself or with the Kotlin DSL, please open issues on the Gradle issue tracker.

To activate the Kotlin DSL, simply use the .gradle.kts extension for your build scripts in place of .gradle. That also applies to the settings file — for example settings.gradle.kts — and initialization scripts.

Note that you can mix Groovy DSL build scripts with Kotlin DSL ones, i.e. a Kotlin DSL build script can apply a Groovy DSL one and each project in a multi-project build can use either one.

We recommend that you apply the following conventions to get better IDE support:

This is so that the IDE knows what type of object "backs" the script, be it Project, Settings or Gradle.

All Kotlin DSL build scripts have implicit imports consisting of:

The Kotlin DSL currently supports type-safe model accessors for any of the following that are contributed by plugins:

The set of type-safe model accessors available is calculated right before evaluating the script body, immediately after the plugins {} block. Any model elements contributed after that point do not work with type-safe model accessors. For example, this includes any configurations you might define in your own build script. However, this approach does mean that you can use type-safe accessors for any model elements that are 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 they are of type TaskProvider<T> and provide a lazy reference and lazy configuration of the underlying task. Here are some examples that illustrate the situations in which configuration avoidance applies:

For all other containers than tasks, accessors for elements are of type NamedDomainObjectProvider<T> and provide the same behavior.

Consider the sample build script shown above that demonstrates the use of type-safe accessors. The following sample is exactly the same except that is uses the apply() method to apply the plugin. The build script can not use type-safe accessors in this case because the apply() call happens in the body of the build script. You have to use other techniques instead, as demonstrated here:

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

You also can not 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 that, you need to know the names and/or types of the configured model elements. We’ll now show you how those can be discovered by looking at the above 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. Please avoid using convention objects when writing new plugins. The long term plan is to migrate all Gradle core plugins to use extensions and remove the convention objects altogether.

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

This technique is most commonly required for source sets that are added by language plugins other than the Java Plugin, e.g. the Groovy Plugin and the Scala Plugin. You can see which plugins add which properties to source sets in the SourceSet reference documentation.

You can declare your plugins within the subprojects to which they apply, but we recommend that you also declare them within the root project build script. This makes it easier to keep plugin versions consistent across projects within a build. The approach also improves the performance of the build.

The Using Gradle plugins chapter explains how you can declare plugins in the root project build script with a version and then apply them to the appropriate subprojects' build scripts. What follows is an example of this approach using three subprojects and three plugins. Note how the root build script only declares the community plugins as the Java Library Plugin is tied to the version of Gradle you are using:

If your build requires additional plugin repositories on top of the Gradle Plugin Portal, you should declare them in the pluginManagement {} block in your settings.gradle.kts file, like so:

Plugins fetched from a source other than the Gradle Plugin Portal can only be declared via the plugins {} block if they are published with their plugin marker artifacts.

If those artifacts are missing, then you can’t use the plugins {} block. You must instead fall back to declaring your plugin dependencies using the buildscript {} block in the root project build script. Here’s an example of doing that for the Android Plugin:

This technique is not that different from what Android Studio produces when creating a new build. The main difference is that the subprojects' build scripts in the above sample declare their plugins using the plugins {} block. This means that you can use type-safe accessors for the model elements that they contribute.

Note that you can’t use this technique if you want to apply such a plugin either to the root project build script of a multi-project build (rather than solely to its subprojects) or to a single-project build. You’ll need to use a different approach in those cases that we detail in another section.

Cross project configuration is a mechanism by which you can configure a project from another project’s build script. A common example is when you configure subprojects in the root project build script.

Taking this approach means that you won’t be able to use type-safe accessors for model elements contributed by the plugins. You will instead have to rely on string literals and the standard Gradle APIs.

As an example, let’s modify the Java/Ratpack sample build to fully configure its subprojects from the root project build script:

Note how we’re using the apply() method to apply the plugins since the plugins {} block doesn’t work in this context. We are also using standard APIs instead of type-safe accessors to configure tasks, extensions and conventions — an approach that we discussed in more detail elsewhere.

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

The following sample demonstrates how you can use the named() method to configure existing tasks and the register() method to create new ones.

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. In addition, Kotlin delegated properties can easily be renamed via IDE refactoring.

The following sample does the exact same things as the one in the previous section, but it uses delegated properties and reuses those references in place of string-literal task paths:

When configuring several elements of a container one can group interactions in a block in order to avoid repeating the container’s name on each interaction. The following example uses 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. Here’s a sample snippet that demonstrates the 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. Kotlin DSL allows you to access extra properties and create new ones via delegated properties, using any of the by extra forms 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 we should cover, one that treats extra as a map. We recommend against using this in general as you lose the benefits of Kotlin’s type checking and it prevents IDEs from providing as much support as they could. However, it is more succinct than the delegated properties syntax and can reasonably be used if you only need to set the value of an extra property without referencing it later.

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

In addition to normal Kotlin source files that go under src/main/kotlin by convention, the Kotlin DSL Plugin also allows you to provide your build logic as precompiled script plugins. You write these as *.gradle.kts files in that same src/main/kotlin directory.

Precompiled script plugins are Kotlin DSL scripts that are compiled as part of a regular Kotlin source set and then placed on the build classpath or packaged in a binary plugin, depending on what type of project they’re in. For all intents and purposes, they are binary plugins, particularly as they can be applied by plugin ID, just like a normal plugin. In fact, the Kotlin DSL Plugin generates plugin metadata for them thanks to integration with the Gradle Plugin Development Plugin.

So, to apply a precompiled script plugin, you need to know its ID. That is derived from its filename (minus the .gradle.kts extension) and its (optional) package declaration.

For example, the script src/main/kotlin/java-library-convention.gradle.kts would have a plugin ID of java-library-convention (assuming it has no package declaration). Likewise, src/main/kotlin/my/java-library-convention.gradle.kts would result in a plugin ID of my.java-library-convention as long as it has a package declaration of my.

To demonstrate how you can implement and use a precompiled script plugin, let’s walk through an example based on a buildSrc project.

First, you need a buildSrc/build.gradle.kts file that applies the Kotlin DSL Plugin:

We recommend that you also create a buildSrc/settings.gradle.kts file, which you may leave empty.

Next, create a new java-library-convention.gradle.kts file in the buildSrc/src/main/kotlin directory and set its contents to the following:

This script plugin simply applies the Java Library and Checkstyle Plugins and configures them. Note that this will actually apply the plugins to the main project, i.e. the one that applies the precompiled script plugin

Finally, apply the script plugin to the root project as follows:

Gradle ships with kotlin-compiler-embeddable plus matching versions of kotlin-stdlib and kotlin-reflect libraries. For example, Gradle 4.3 ships with the Kotlin DSL v0.12.1 that includes Kotlin 1.1.51 versions of these modules. 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.

These are the Kotlin compiler arguments used for compiling Kotlin DSL scripts and Kotlin sources and scripts in a project that has 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 and you can learn how to locate the name of the type declaring a given Kotlin extension in see 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. Here’s an example:

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.

Also see the groovy-interop sample.

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:

The maven-plugin sample demonstrates the use of the withGroovyBuilder() utility extensions for configuring the uploadArchives task to deploy to a Maven repository with a custom POM using Gradle’s core Maven Plugin. Note that the recommended Maven Publish Plugin provides a type-safe and Kotlin-friendly DSL that allows you to easily do the same and more without resorting to withGroovyBuilder().

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: