Gradle Kotlin DSL 1.0 Release Notes

Gradle Kotlin DSL 1.0 brings Kotlin 1.3.0, performance improvements, script compilation build cache, API/DSL refinements and fixes.

In order to benefit from the best user experience, please update IntelliJ IDEA to 2018.3, Android Studio to 3.2 and their Kotlin Plugin to the latest 1.3.

Thanks to a great help from the community, the Gradle User Manual now contains samples for both the Groovy and Kotlin DSLs. This is now the best place to find information on how to use the Gradle Kotlin DSL as it covers all Gradle features from using plugins to customizing the dependency resolution behavior.

A new user manual chapter dedicated to the Gradle Kotlin DSL has also been added.

The Gradle Plugin Portal now displays Kotlin DSL snippets for easy copy and paste.

This release contains potential breaking changes, see below.

v1.0.3 is included in Gradle 5.0 RC3.

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

$ cd $YOUR_PROJECT_ROOT
$ gradle wrapper --gradle-version 5.0-rc-3 --distribution-type all

Updates since v1.0.2 (Gradle 5.0 RC2)

• Let getting property delegate use getByName() instead of named() (#1247)

• Let creating property delegate use create() instead of register() (#1246)

For the complete list see the gradle/kotlin-dsl issues for 1.0.3.

Updates since v1.0-RC14 (Gradle 5.0 RC1)

• Let generated source code import default package types (#1205, #1239)

• The kotlin-dsl plugin don't pin kotlin dependencies anymore (#1241)

For the complete list see the gradle/kotlin-dsl issues for 1.0.2.

Updates since v1.0-RC12 (Gradle 5.0 M1)

• Upgrade embedded Kotlin to 1.3.0 (#1197)

  Please see the Kotlin 1.3 announcement, What’s New page, ChangeLog and Compatibility Guide for more information.

• Faster script compilation (#1168, #817, #1199)

  The biggest bottleneck in the Gradle Kotlin DSL was the compilation of the generated Kotlin type-safe accessors during script compilation. The most impacted use cases were first time use of a build, and, the feedback loop when making changes to the build logic, both from the command line or in the script editor.

  In this release we replaced the usage of the Kotlin compiler for this particular step by generating the bytecode directly instead. The generated accessors are lean and repetitive, no need for a full-blown compiler to produce their bytecode.

  The IDE experience is preserved, you can still display accessors documentation in context and navigate to their sources.

  On the gradle/kotlin-dsl build with a dozen projects and a fair amount of custom build logic, the feedback loop on API change in buildSrc went from ~10s to ~6s. That's a 40% improvement.

  

  On a small Android application, here the Android Sunflower sample application, the feedback loop on API change in buildSrc went from ~7s down to ~4.5s. That's a 40% improvement too.

  

  The effect is even more drastic on complex builds. On the gradle/gradle build that has almost a hundred projects and a fairly complex build logic, the feedback loop on API change in buildSrc went from ~1 minute down to ~25s. That's a 60% improvement.

  

  That change has about the same effect on the clean checkout use case, and, improves the first time use of a small build by ~20%. For all use cases, the larger the build, bigger is the impact.

• Fix Gradle daemon meta space leak caused by kotlin-dsl plugin (#1188)

  A permanent generation / meta space memory leak was introduced in 1.0 RC1 causing the Gradle daemon to consume spurious memory and eventually fail with OutOfMemoryError. This is now fixed. See the linked issue for the tasty details.

• IDE script resolver skip buildSrc verification tasks (#1174)

  In order to shorten the feedback loop in the .gradle.kts editor, the script dependencies resolver now skips all verification tasks from the buildSrc build if present.

• Generate compilable container elements accessors for element with type in the default package (#1158, #1162, #1164)

  Previous release introduced type-safe accessors for elements of containers (e.g. tasks.compileJava { }) but they were not compilable and caused builds to fail when the element type was from the default package. This is now fixed.

For the complete list see the gradle/kotlin-dsl issues for 1.0-RC14.

Updates since v1.0-RC6 (Gradle 4.10.2)

• Upgrade embedded Kotlin to 1.3.0-RC2 (#1149, #1005, #1112, #1125, #1132)

  Note that Gradle Kotlin DSL 1.0 will ship with Kotlin 1.3 GA.

• Script compilation build cache is now enabled alongside the Gradle Build Cache (#1152)

  If you enable the Gradle Build Cache then the Gradle Kotlin DSL will store and fetch the outputs of script compilation, avoiding the expensive work of recompiling them.

• Accessors for plugins present in buildSrc (#1156)

  You can now refer statically to plugins declared in buildSrc. Instead of:

  plugins {
      id("my.buildSrc.plugin.ID")
  }
  

  you can now write:

  plugins {
      my.buildSrc.plugin.ID
  }
  

• Accessors for elements of collections (#879, #1041)

  It is now possible to refer to elements of collections available at build script body compilation time via type-safe accessors. This is applied to configurations, tasks and all Gradle extensions that are collections such as sourceSets. For tasks, it means that instead of writing:

  plugins {
      java
  }
  
  tasks {
      named<Test>("test") {
          testLogging.showStacktraces = true
      }
  }
  

  you can now write:

  plugins {
      java
  }
  
  tasks {
      test {
          testLogging.showStacktraces = true
      }
  }
  

• Accessors for artifact configurations in configurations {} (#1118, #1129)

  Accessors for artifact configurations were missing in the configurations {} block. This has been fixed the same way as for all collections, see above. Instead of:

  plugins {
      java
  }
  
  configurations {
      named("implementation") {
          exclude(group = "org.foo")
      }
  }
  

  you can now write:

  plugins {
      java
  }
  
  configurations {
      implementation {
          exclude(group = "org.foo")
      }
  }
  

• Refine dependency constraints DSL (#710, #1091)

  Accessors for artifact configurations were missing in the dependencies { constraints {} } block. This has been fixed. Instead of:

  plugins {
      java
  }
  
  dependencies {
      constraints {
          add("implementation", "com.google.collections:google-collections") {
              version { rejectAll() }
              because("Google collections is superceded by Guava")
          }
      }
  }
  

  you can now write:

  plugins {
      java
  }
  
  dependencies {
      constraints {
          implementation("com.google.collections:google-collections") {
              version { rejectAll() }
              because("Google collections is superceded by Guava")
          }
      }
  }
  

• Refine containers API (#1042, #1104, #1108, #1116)

  During the RC phase, several discrepancies were found in the domain object collections and containers API. Special care has been taken to iron it in this release. Please see the linked issues for more information.

• Let the kotlin-dsl plugin configure precompiled script plugins support (#1135)

  Applying the kotlin-dsl plugin now also applies the kotlin-dsl-precompiled-script-plugins plugin. See the Gradle Kotlin DSL Primer chapter of the Gradle User Manual for more information.

• Refine IDE script dependencies resolver (#1133, #1124, #1139)

  The dependencies resolver backing IDE editors for .gradle.kts scripts has been refined to emit warnings only when necessary and display actionable messages. Please see the linked issues for more information.

For the complete list see the gradle/kotlin-dsl issues for 1.0-RC12.

Breaking changes

This release contains some potential breaking changes:

• Upgrade embedded Kotlin to 1.3.0

  Kotlin DSL 1.0 ships with Kotlin 1.3.0. Please see the Kotlin 1.3 announcement, What’s New page, ChangeLog and Compatibility Guide for more information.

• Artifact configuration accessors are now typed NamedDomainObjectProvider<Configuration>

  Instead of simply Configuration. This goes in line with the fact that the Kotlin DSL sugar embraces the new configuration avoidance APIs. It will cause compilation errors. The simplest way to fix compilation errors is to add an invocation to .get() to the offending code.

• Legacy support for project schema JSON snapshot is removed (#1195)

  The legacy support for generating type-safe accessors from a JSON snapshot of multi-project schema and its companion task :kotlinDslAccessorsSnapshot have been removed. If your build contains a gradle/project-schema.json file you can safely delete it, it is no longer needed.

• Rename PluginAware.apply<T>(to) to PluginAware.applyTo<T>(target) (#1161, #1184)

  The PluginAware.apply<T>(to) extension function was causing ambiguities with PluginAware.apply(plugin = "some.id") and surprising behavior.

  This release renames that extension function to PluginAware.applyTo<T>(target) removing the ambiguity. If you were using that extension then use the new name instead.

• The kotlin-dsl plugin don't pin kotlin dependencies anymore (#1241)

  This was hiding version conflicts when using failOnVersionConflict() and causing confusion when mixing Kotlin versions. As a result, your build might now fail with version conflicts if you are using failOnVersionConflict().

Avoiding Gradle Kotlin DSL internal APIs

Use of Kotlin DSL internal APIs in plugins and build scripts has the potential to break builds when either Gradle or plugins change.

The Kotlin DSL extends the Gradle public API definition with org/gradle/kotlin/dsl/* excluding any subpackages.