Source

Gradle Kotlin DSL Primer

---

p. “Gradle’s Kotlin DSL offers an alternative to the traditional Groovy DSL, delivering an enhanced editing experience in supported IDEs with features like better content assist, refactoring, and documentation.”

Prerequisites

---

p. “Using the plugins {} block to declare Gradle plugins is highly recommended as it significantly improves the editing experience.”

IDE support

---

p. “The Kotlin DSL is fully supported by IntelliJ IDEA and Android Studio.”

p. “you must import your project using the Gradle model to enable content assist and refactoring tools for Kotlin DSL scripts in IntelliJ IDEA.”

Automatic build import vs. automatic reloading of script dependencies

---

p. “We recommend disabling automatic build import while enabling automatic reloading of script dependencies.”

Kotlin DSL scripts

---

p. “Use the Kotlin DSL reference search to explore available members.”

p. “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.”

p. “You can mix Groovy DSL and Kotlin DSL scripts within the same build.”

p. “Name settings scripts (or any script backed by a Gradle Settings object) using the pattern *.settings.gradle.kts. This includes script plugins applied from settings scripts.”

p. “Name initialization scripts using the pattern *.init.gradle.kts or simply init.gradle.kts.”

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

Implicit imports

---

p. “The default Gradle API imports”

p. “The Kotlin DSL API, which includes types from the following packages:“

Avoid Using Internal Kotlin DSL APIs

---

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

p. “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).”

Compilation warnings

---

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

p. “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”

org.gradle.kotlin.dsl.allWarningsAsErrors=true in `gradle.properties

Type-safe model accessors

---

p. “Groovy DSL allows you to reference many build model elements by name, even if they are defined at runtime, such as named configurations or source sets.

For example, when the Java plugin is applied, you can access the implementation configuration via configurations.implementation.”

p. “Kotlin DSL replaces this dynamic resolution with type-safe model accessors, which work with model elements contributed by plugins.”

Understanding when type-safe model accessors are available

---

p. “Dependency and artifact configurations”

implementation and runtimeOnly (contributed by the Java Plugin)

p. “Project extensions and conventions, and extensions on them”

sourceSets

p. “Extensions on the dependencies and repositories containers, and extensions on them”

testImplementation (contributed by the Java Plugin), mavenCentral

p. “Elements in the tasks and configurations containers”

compileJava (contributed by the Java Plugin), test

p. “Elements in project-extension containers”

Source sets contributed by the Java Plugin that are added to the sourceSets container: sourceSets.main.java { setSrcDirs(listOf("src/main/java")) }

p. “Project extensions and conventions, contributed by Settings plugins, and extensions on them”

pluginManagement, dependencyResolutionManagement

p. “The set of type-safe model accessors available is determined right before evaluating the script body, immediately after the plugins {} block.”

So adding plugins { } block makes possible for IntelliJ to support type-safe model accessors.

If you declare custom configuration such as configuration.create("customConfiguration"), you can't declare dependency as customConfiguration(“com.google.guava…”). It will create ERROR because there’s no type-safe accessor for customConfiguration

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