0.16.3

Gradle Kotlin DSL 0.16.3 Release Notes

Gradle Kotlin DSL v0.16.3 brings Kotlin 1.2.31, support for .gradle.kts scripts in Kotlin source sets, Java 10, a more consistent API, better IntelliJ IDEA integration, and further improved parity with the Groovy DSL.

v0.16.3 is included in Gradle 4.7 RC1.

To use it, upgrade your Gradle wrapper in the following fashion:

$ cd $YOUR_PROJECT_ROOT
$ gradle wrapper --gradle-version 4.7-rc-1

Updates since v0.15.6

• Kotlin 1.2.31 (#738)
  The embedded Kotlin version was upgraded from Kotlin 1.2.21 to the latest official release, Kotlin 1.2.31.

• Precompiled script plugins (#666, #667, #668, #669, #670).

  In our continued effort to make it easier to author, reuse and share Gradle build logic, this release introduces the ability to publish Kotlin scripts as binary Gradle plugins with very low ceremony, a feature we are tentatively calling precompiled script plugins.

  A precompiled script plugin is a Kotlin script compiled as part of a regular Kotlin source-set, meant to be consumed as a binary Gradle plugin whose identifier is automatically derived from its file name and optional package declaration.

  The feature is enabled via the PrecompiledScriptPlugins plugin in combination with the java-gradle-plugin and kotlin-dsl plugins:

  plugins {
      `java-gradle-plugin`
      `kotlin-dsl`
  }
  
  apply<org.gradle.kotlin.dsl.plugins.precompiled.PrecompiledScriptPlugins>()

  After which *.gradle.kts scripts under src/main/kotlin would be automatically exposed as Gradle plugins.

  For example, in the project below, the Kotlin script src/main/kotlin/my-plugin.gradle.kts is automatically exposed as the my-plugin Gradle plugin and could be applied to a Gradle build in the usual ways.

  

  And while there are several limitations which we plan to address in subsequent releases, we expect the current feature-set to be compelling enough for self-contained plugins.

  To learn more about precompiled script plugins please check out the precompiled-script-plugin sample.

• Unified DSL for Gradle/Project and extra properties (#626).

  The DSL to access Gradle/Project properties and extra properties via Kotlin delegated properties is now unified with support for typed access and optionality encoding using Kotlin nullable types across the board.

  val some: String by project
  val optional: String? by project
  val other: Int by extra
  val otherOptional: Int? by extra

  The change to delegated properties to access Gradle/Project properties is potentially breaking, please see the Breaking changes section below for more detailed information.

• Access to Gradle properties in settings scripts (#653).

  It is now possible to access Gradle properties in settings scripts just like Project properties in build scripts:

  val some: String by settings
  val optional: String? by settings

• the<T>() and configure<T> {} enhancements (#703, #319).

  Those extensions are now available on all ExtensionAware objects, not only Project. This allows to configure e.g. Task extensions:

  tasks {
      "test"(Test::class) {
          configure<JacocoTaskExtension> {
              isAppend = true
          }
      }
  }

  This is a potential breaking change, please see the Breaking changes section below for what to expect when upgrading.

  In addition to the above, the<T>() and configure<T> {} now support nested generics queries using Kotlin reified types. This allows to request extensions by type such as NamedDomainObjectContainer<Thing>.

• Support for cross-configuring buildscript {} (#374).

  In build scripts:

  project(":sub") {
      buildscript {
          // ...
      }
  }    

  In settings scripts:

  gradle.projectsLoaded {
      rootProject.buildscript {
          // ...
      }
  }

  In initialization scripts:

  projectsLoaded {
      rootProject.buildscript {
          // ...
      }
  }

Plus some other API additions, enhancements and bug fixes. For the complete list see the gradle/kotlin-dsl issues for 0.16.x.

Breaking changes

This release contains several potential breaking changes:

• Access to Gradle/Project properties via Kotlin delegated properties now requires property type declaration

  If your build was accessing Project properties in the following fashion:

  val some by Project

  you'll now get a compilation error:

  Script compilation error:
  
    Line 2: val some by project
                        ^ Property delegate must have a 'getValue(Build_gradle, KProperty<*>)' method. None of the following functions is suitable:
                            public abstract operator fun <T> getValue(receiver: Any?, property: KProperty<*>): ??? defined in org.gradle.kotlin.dsl.PropertyDelegate
  

  It is now required that you strongly type the property as follows:

  val some: String by Project

  If the property is optional you can express it using a Kotlin nullable type:

  val some: String? by Project

• Erroneous usage of the plugins {} block in a nested scope now throws, it was a no-op before

  The plugins {} block can only be used as a top-level expression, but, the API is available in nested scopes. Starting with this release, if you use the plugins {} block in a nested scope, for example:

  subprojects {
      plugins {
          // ...
      }
  }

  you'll now get a build failure as follows:

  The plugins {} block must not be used here. If you need to apply a plugin imperatively, please use apply<PluginType>() or apply(plugin = "id") instead.
  

• the<T>() and configure<T> {} are now available on all ExtensionAware types

  Before this release those two extensions were only available on the Project type. This release makes them available on all ExtensionAware types such as Task, for example. That might cause the wrong ExtensionAware object to be selected as the receiver for the operations in contexts where another ExtensionAware instance is available in a closer scope. Take the following code as an example:

  tasks {
      "foo" {
        // the<T>() and configure<T> {} mean something different here in the new release
      }
  } 

  This change can lead to two different behaviors depending on the requested type.

  If the requested extension type is not available to the now selected ExtensionAware you'll get the following error:

  Extension of type 'RequestedType' does not exists. Currently registered extensions types: [...]
  

  If the requested extension type is also available to the now selected ExtensionAware your script will configure the extension on a different object, changing your build behavior.

• It is now enforced that there's a single pluginManagement {} block in settings scripts

  If you happen to have more than one pluginsManagement {} block in your settings script you will now get the following error:

  Unexpected `pluginManagement` block found. Only one `pluginManagement` block is allowed per script.