0.8.0

Gradle Script Kotlin 0.8.0 Release Notes

Gradle Script Kotlin v0.8.0 is a major step forward in usability, bringing a more consistent DSL, convenient and type-safe access to contributed project extensions and conventions, much better error reporting, bug fixes and, of course, the latest and greatest Kotlin release.

v0.8.0 is expected to be included in the upcoming Gradle 3.5 RC1.

The features in this release are also available for immediate use within the latest Gradle Script Kotlin distribution snapshot. To use it, upgrade your Gradle wrapper in the following fashion:

$ cd $YOUR_PROJECT_ROOT
$ gradle wrapper --gradle-distribution-url https://repo.gradle.org/gradle/kotlin-dsl-snapshots-local/gradle-script-kotlin-3.5-20170305000422+0000-all.zip

Updates since v0.7.0

• Kotlin 1.1.0 (#289). Build scripts are now compiled against Kotlin 1.1.0! This enables, among other things, the use of coroutines in build scripts.

• Better error reporting (#177, #170, #254, #290). Gradle will now report the correct location for compilation errors occurring inside buildscript and plugins blocks, will do so in a format that's readily recognised by many tools - clicking a compilation error in a console window should open the configured text editor, for instance - and will only ever display stack traces when explicitly instructed via the --stacktrace argument.

• Consistent DSL across core and community plugins (#156, #155, #157, #224). The build script compiler will now treat Gradle's Action<T> type as an alias to the T.() -> Unit type (a function literal with receiver in Kotlin parlance) finally solving the dreaded it problem once and for all. WARNING: This is a breaking change and some scripts will fail to compile due to it no longer being defined inside lambda expressions passed as Action<T> parameters. Simply replace it by this or remove it altogether.

• Type-safe accessors for project extensions and conventions (#235, #229, #230). This long awaited feature enables the replacement of type-heavy configuration code such as:

  configure<ApplicationPluginConvention> {
      mainClassName = "my.App"
  }

  by the terser and familiar looking:

  application {
      mainClassName = "my.App"
  }

  Given the inherent flexibility in Gradle's plugin system, it's not possible to cover all the different plugin application scenarios with a single, one-size-fits-all solution so type-safe accessors can be used in three different modes: just-in-time, ahead-of-time and ad hoc.

  TL;DR: Opt-in to type-safe accessors by setting the org.gradle.script.lang.kotlin.accessors.auto project property to "true" and hack on, if you get Unresolved reference compilation errors, read on.

  • just-in-time In just-in-time mode, accessors are generated immediatelly after the evaluation of the plugins block, just before the evaluation of the build script body and, because of that, accessors for extensions and conventions registered later in the process are not available. In summary, the following example works in just-in-time mode:

    plugins {
        application
    }
    
    // type-safe accessor for `application` convention generated as:
    //
    //   `fun application(configuration: ApplicationPluginConvention.() -> Unit): ApplicationPluginConvention`
    //
    
    application {
        mainClassName = "my.App"
    }

    But the following one does not:

    apply {
        plugin("application")
    }
    
    application { // 💣 Unresolved reference
        mainClassName = "my.App"
    }

    Due to the potential for build script compilation failures resulting from unaccessible extension types or illegal extension names, just-in-time accessors must be explicitly enabled via the org.gradle.script.lang.kotlin.accessors.auto project property set to "true", check out the gradle.properties file from the hello-world sample for an example.

  • ahead-of-time In ahead-of-time mode, type-safe accessors must be explicitly requested via the gskGenerateAccessors task. The upside is that all extensions and conventions available at task execution time will be taken into account. The downside is that for the task to even execute, the build script must compile cleanly, which implies we must edit the build script in two steps: step one, apply desired plugins and run gskGenerateAccessors, step two, proceed to configure the available extensions and conventions. Additionally, the buildSrc file created by gskGenerateAccessors must be added to our VCS.

    • Step 1:

      // build.gradle.kts
      apply {
          plugin("application")
      }

      Followed by:

      $ ./gradlew gskGenerateAccessors
      :gskGenerateAccessors
      
      BUILD SUCCESSFUL
      
      Total time: 1.867 secs
      

    • Step 2:

      // build.gradle.kts
      apply {
          plugin("application")
      }
      
      // type-safe accessor for `application` convention
      application {
          mainClassName = "my.App"
      }

  • ad-hoc In this usage mode, the gskProjectAccessors task is executed whenever a new type-safe accessor is needed. gskProjectAccessors will then write the Kotlin code for all available type-safe accessors to stdout from where it can be copied into the build script or to a Kotlin file under buildSrc.

• Improved Gradle API(#239, #122, #219, #246, #245, #247, #244, #243, #242, #241, #240, #238, #206, #226). Many methods in the Gradle API previously only available to Groovy have been overloaded with versions better suited to Kotlin.

• Improved Groovy interoperability(#286). Groovy closures can now be invoked using regular function invocation syntax.

• Sub-project build scripts inherit parent project compilation classpath (#190).

• Projects can use kotlin-gradle-plugin 1.0.x again (#189). Thanks to the upgrade to Kotlin 1.1.0, compatibility with Kotlin 1.0.x has been restored.

• Custom task actions will no longer interfere with the build cache (#263, #171).

• Build scripts can contain Windows line endings (#227, #220).

0.7.0

General Notes

Gradle Script Kotlin v0.7.0 supports convenient configuration of Gradle domain object collections and it is another major milestone toward achieving feature parity with the Groovy frontend. v0.7.0 is expected to be included in a future Gradle release after Gradle 3.4.

IMPORTANT: This release requires the latest IntelliJ IDEA Kotlin Plugin from the EAP 1.1 channel (1.1-M04+).

WARNING: This release is incompatible with the Kotlin Gradle plugin 1.0.x.

The features in this release are also available for immediate use within the latest Gradle Script Kotlin distribution snapshot. To use it, upgrade your Gradle wrapper in the following fashion:

$ cd $YOUR_PROJECT_ROOT
$ gradle wrapper --gradle-distribution-url https://repo.gradle.org/gradle/kotlin-dsl-snapshots-local/gradle-script-kotlin-3.4-20170117200919+0000-all.zip

Updates since v0.6.0

• Kotlin 1.1-M04 (#211). Build scripts are now compiled against the latest and greatest Kotlin release. This release fixes a long standing issue related to overloaded method resolution that was particularly problematic for interacting with the Gradle API. WARNING: The Kotlin 1.1-M04 runtime is still incompatible with the Kotlin 1.0.x compiler (and Gradle plugin) and, because of that, it is currently not possible to use Kotlin 1.0.x together with this release.
• Convenient creation and configuration of objects within Gradle collections (#35, #200 and #34). This release provides two ways of configuring Gradle collections implementing the NamedDomainObjectContainer interface. First, a declarative approach better suited to configuring many objects at once and a second one based on delegated properties, better suited to configuring single collection elements or simply bringing them into scope.

// The bulk configuration syntax works with monomorphic containers such as _configurations_
configurations {

    "myCompile" {
        isVisible = false
    }

    "myRuntime" {
        isTransitive = true
    }
}

// And it also works with polymorphic containers such as _tasks_
tasks {

    "prepare"(Copy::class) {
        from("scripts")
        into("build")
    }

    "test" {
        dependsOn("prepare")
    }
}

// Single elements can be brought into scope via delegated properties
val clean by tasks // brings an existing task into scope by name

val jar: Jar by tasks // brings an existing task into scope by name and type

// Delegated properties can also be used to create new elements in the container via the _creating_ delegate
val deploy by tasks.creating(Copy::class) { 
    from(jar)
    into("deploy")
}

// And finally, the collection indexer provides a terse way to get an element by name
tasks["check"].dependsOn(deploy)

• Extensions can be accessed via delegated properties (#216). Extensions contributed by plugins can now be accessed via the same convenient mechanism of delegated properties. Check out the provided sample to see it in action.
• org.gradle.api.* and java.io.File are now imported by default (#214 and #218). Making for cleaner and simpler to write build scripts.
• Improved Gradle API (#127). Many methods in the Gradle API previously only available to Groovy have been overloaded with versions better suited to Kotlin.

0.6.0

General Notes

Gradle Script Kotlin v0.6.0 introduces the plugins DSL and it is a major milestone toward achieving feature parity with the Groovy frontend. v0.6.0 is expected to be included in a future Gradle release after Gradle 3.3.

IMPORTANT: This release requires the latest IntelliJ IDEA Kotlin Plugin from the EAP 1.1 channel (1.1-M03+).

WARNING: This release is incompatible with the Kotlin Gradle plugin 1.0.x.

The features in this release are also available for immediate use within the latest Gradle Script Kotlin distribution snapshot. To use it, upgrade your Gradle wrapper in the following fashion:

$ cd $YOUR_PROJECT_ROOT
$ gradle wrapper --gradle-distribution-url https://repo.gradle.org/gradle/kotlin-dsl-snapshots-local/gradle-script-kotlin-3.4-20161216120313+0000-all.zip

Updates since v0.5.1

• Plugins DSL (#186). Plugins can now be applied by string id and version within the newly introduced plugins block. The semantics are the same as for the Groovy plugins DSL.

plugins {
    id("org.gradle.hello-world") version "0.2" apply false
}

• Improved plugins DSL for builtin plugins (#168). Builtin plugins can be applied via a type-safe and tooling-friendly DSL that enables content-assist, quick documentation and code navigation.

plugins {
    java
    application
}

• Build script in sub-project of a multi-project build can be edited with the correct classpath (#130). With this update IDEA will now receive the correct classpath for build scripts from sub-projects in a multi-project build.

• Kotlin 1.1-M03 (#187). Build scripts are now compiled against the latest and greatest Kotlin release. WARNING: The Kotlin 1.1-M03 runtime is incompatible with the Kotlin 1.0.x compiler (and Gradle plugin) and because of that it's currently not possible to use Kotlin 1.0.x together with this release.

• Extra delegated properties (#195). Thanks to a contribution by @orangy it is now possible to use Kotlin delegated properties against the extra properties container.

  var kotlinVersion: String by extra
  
  kotlinVersion = "1.1-M03"

0.5.1

General Notes

Gradle Script Kotlin v0.5.1 is a minor update to v0.5.0 including a fix to an issue surfaced by the latest Gradle 3.3 API and it is expected to be included in the upcoming Gradle 3.3 RC1.

0.5.0

General Notes

Gradle Script Kotlin v0.5.0 greatly improves startup performance by caching compiled build script classes. v0.5.0 is expected to be included in the upcoming Gradle 3.3 RC1.

IMPORTANT: This release requires the latest IntelliJ IDEA Kotlin Plugin from the EAP 1.1 channel (1.1-M02+).

The features in this release are also available for immediate use within the latest Gradle Script Kotlin distribution snapshot. To use it, upgrade your Gradle wrapper in the following fashion:

$ cd $YOUR_PROJECT_ROOT
$ gradle wrapper --gradle-distribution-url https://repo.gradle.org/gradle/kotlin-dsl-snapshots-local/gradle-script-kotlin-3.3-20161123161139+0000-all.zip

Updates since v0.4.1

• Compiled build scripts are cached (#31). For a very positive, noticeable, impact on startup performance, specially on multi-project builds. We consider this to be a major milestone in the project for Kotlin build script startup performance is now on par with that of Groovy build scripts.
• Build scripts outside the imported project can be edited with the correct classpath (#181). With previous Gradle Script Kotlin releases, IntelliJ IDEA would always assume the buildscript classpath of the imported project for its content-assist features, even when editing a build script from a different project. With this release, IDEA will now assume a classpath computed from the project containing the open build script.
• Improved Gradle API (#124, #125, #126 and #162). Many methods in the Gradle API previously only available to Groovy have been overloaded with versions better suited to Kotlin.
• Better interoperability with Groovy plugins (#153). The existing closureOf helper has been improved to set the Closure's owner object and it's now compatible with a wider set of Groovy plugins. A new delegateClosureOf helper was introduced to facilitate interoperability with plugins requiring Groovy Closures that operate directly on the Closure's delegate instead of its first argument.

0.4.1

General Notes

Gradle Script Kotlin v0.4.1 is an interim release meant to bring the latest and greatest version of Kotlin.

The features in this release are available for immediate use within the latest Gradle Script Kotlin distribution snapshot. To use it, upgrade your Gradle wrapper in the following fashion:

$ cd $YOUR_PROJECT_ROOT
$ gradle wrapper --gradle-distribution-url https://repo.gradle.org/gradle/kotlin-dsl-snapshots-local/gradle-script-kotlin-3.3-20161022102727+0000-all.zip

Updates since v0.4.0

• Kotlin 1.1-M02 (#164). This release brings the recently-released Kotlin 1.1-M02.

0.4.0

General Notes

Gradle Script Kotlin v0.4.0 brings further improvements for multi-project builds and it is expected to be included in the upcoming Gradle 3.2 RC1.

The features in this release are also available for immediate use within the latest Gradle Script Kotlin distribution snapshot. To use it, upgrade your Gradle wrapper in the following fashion:

$ cd $YOUR_PROJECT_ROOT
$ gradle wrapper --gradle-distribution-url https://repo.gradle.org/gradle/kotlin-dsl-snapshots-local/gradle-script-kotlin-3.3-20161019131343+0000-all.zip

Updates since v0.3.3

• New gradleScriptKotlinApi() dependency notation (#118). To enable external and buildSrc Kotlin plugins to take advantage of the Gradle Script Kotlin extensions to the Gradle API.
• Simplified ClassLoader hierarchy (#119). Which not only fixes many issues with certain combinations of plugins but improves performance as well.
• Improved support for Kotlin based buildSrc (#139). The new sample demonstrates how to take advantage of Kotlin in buildSrc to write custom tasks and share custom build logic across projects in a multi-project build.

0.3.3

General Notes

Gradle Script Kotlin v0.3.3 improves support for multi-project builds of Kotlin based projects and it is expected to be included in the upcoming Gradle 3.2 RC1.

The features in this release are also available for immediate use within the latest Gradle Script Kotlin distribution snapshot. To use it, upgrade your Gradle wrapper in the following fashion:

$ cd $YOUR_PROJECT_ROOT
$ gradle wrapper --gradle-distribution-url https://repo.gradle.org/gradle/kotlin-dsl-snapshots-local/gradle-script-kotlin-3.3-20161005141915+0000-all.zip 

Updates since v0.3.2

• Improved support for multi-project builds (#137). Multi-project builds comprising two or more Kotlin based projects are now supported with the restriction that they must be compiled against the version of Kotlin shipped with gradle-script-kotlin. This restriction will be lifted in a future version, in the meantime please refer to the provided samples for the required settings: multi-kotlin-project and multi-kotlin-project-config-injection.
• Build script compilation on Windows (#147). v0.3.2 introduced a bug that prevented many valid build scripts from compiling on Windows. This has been fixed on v0.3.3 and building on Windows is fully supported again.

0.3.2

General Notes

Gradle Script Kotlin v0.3.2 greatly increases parity with the Groovy based DSL via runtime code generation of Kotlin extension members.

Please note that this is a breaking change as many configuration patterns that previously required a qualifying it reference no longer do.

Let's take copySpec as an example. Before v0.3.2 one would write:

copySpec {
    it.from("src/data")
    it.include("*.properties")
}

With v0.3.2 it should now read:

copySpec {
    from("src/data")
    include("*.properties")
}

This behavior is only enabled for non-generic Gradle API methods under the org.gradle.api package at this point. Subsequent releases will increasingly cover the full API.

Gradle Script Kotlin v0.3.2 is expected to be included in the upcoming Gradle 3.1 RC1.

The features in this release are also available for immediate use within the latest Gradle Script Kotlin distribution snapshot. To use it, upgrade your Gradle wrapper in the following fashion:

$ cd $YOUR_PROJECT_ROOT
$ gradle wrapper --gradle-distribution-url https://repo.gradle.org/gradle/kotlin-dsl-snapshots-local/gradle-script-kotlin-3.1-20160908214640+0000-all.zip

Updates since v0.3.1

• Increased parity with the Groovy based DSL via runtime code generation (#117). The qualifying it reference is no longer required in many commonly used configuration blocks.
• Client module dependencies DSL (#111). It is now possible to configure all aspects of client module dependencies via a type-safe and IDE friendly DSL:

    dependencies {
        runtime(
            module("org.codehaus.groovy:groovy:2.4.7") {

                // Configures the module itself
                isTransitive = false

                dependency("commons-cli:commons-cli:1.0") {
                    // Configures the external module dependency
                    isTransitive = false
                }

                module(group = "org.apache.ant", name = "ant", version = "1.9.6") {
                    // Configures the inner module dependencies
                    dependencies(
                        "org.apache.ant:ant-launcher:1.9.6@jar",
                        "org.apache.ant:ant-junit:1.9.6")
                }
            }
        )
    }

• Content assist is now available to non top-level Kotlin based build scripts (#113). IDE support is now available to Kotlin build scripts even before they are referenced from Groovy build scripts via apply from: "build.gradle.kts" statements.

0.3.1

General Notes

Gradle Script Kotlin v0.3.1 significantly improves code assistance performance in IDEA (check out samples/README.md for instructions on installing the latest development version of the Kotlin plugin).

The features in this release are also available for immediate use within the latest Gradle Script Kotlin distribution nightly. To use it, upgrade your Gradle wrapper in the following fashion:

$ cd $YOUR_PROJECT_ROOT
$ gradle wrapper --gradle-distribution-url https://repo.gradle.org/gradle/kotlin-dsl-snapshots-local/gradle-script-kotlin-3.0.0-20160805133427+0000-all.zip

Updates since v0.3.0

• Upgrade to Kotlin 1.1-dev-2053 (#108). The embedded Kotlin compiler was upgraded to a recent development version greatly improving the performance of code assistance within IDEA when used together with a recent Kotlin plugin version.
• Improved dependencies DSL (#107). It is now possible to configure all aspects of external module and project dependencies via a type-safe and IDE friendly DSL:

        dependencies {

            default(group = "org.gradle", name = "foo", version = "1.0") {
                isForce = true
            }

            compile(group = "org.gradle", name = "bar") {
                exclude(module = "foo")
            }

            runtime("org.gradle:baz:1.0-SNAPSHOT") {
                isChanging = true
                isTransitive = false
            }

            testCompile(group = "junit", name = "junit")

            testRuntime(project(path = ":core")) {
                exclude(group = "org.gradle")
            }
        }

• Navigation to sources of types defined in buildSrc (#104). It is now possible to navigate to the definitions of functions and types defined in buildSrc via the standard Goto Declaration shortcuts in IDEA.
• Android sample (#83). A complete sample demonstrating how to take advantage of gradle-script-kotlin within an Android project is now available (our thanks to @tyvsmith!).