Gradle & Kotlin, the missing piece of the puzzle

Hello friends, I’m currently flying back from Amsterdam and a KotlinConf 2018 that I really enjoyed.

The talk Type-safe build logic with Gradle Kotlin-DSL in particular gave me the inspiration to write about a subject I have been playing with great delight recently, and even launch an IMHO neat little project that had been in the back of my mind: gradle-kotlin-dsl-libs.

A confession

People who know me may be surprised that I’m about to write about and praise Gradle. I have often expressed the love-hate relationship I had with Gradle.

A lot of attention has been paid to the topic of Gradle performance (actually
of the Android build tools). Lot of work has been done there as well (with some more to come soon from what I’ve heard), but I want to focus here on the second half of the problem.

Maintenance of those build.gradle files can become quickly super tedious…

The bright side of Gradle is that it brings a lot of power and flexibility to the table, with build files that are very declarative and easy to read.

But with great power comes the need for great tooling… or a very frustrating user experience.

And that was the dark side of Gradle. While the build.gradle files are easy to read, they are quite hard to write. When you need to customize them, you are mostly on your own. Usually, it doesn’t work for a while, and you don’t know why. Then at some point, you copy-paste the right solution, and it works, but you don’t really know why either.

What happened is that the dynamic nature of Groovy combined badly with all the meta-programming done in Gradle to give us poor tooling support.

Ok, so that’s the background of the kotlin-dsl project on which
Gradle and JetBrains have been quietly working on. It’s about to reach maturity, so now is a good time to pay attention to the topic.

How to migrate

Migrating build logic from Groovy to Kotlin mentions two possible strategies

1. Migrating the existing syntax of your build to Kotlin, bit by bit, while retaining the structure — what we call a mechanical migration
2. Restructuring your build logic towards Gradle best practices and switching to Kotlin DSL as part of that effort

For our existing projects, the latter will usually make much more sense. 
There is a story that a lot of C programmers got started doing C++ by taking this baby step.

In this spirit, I will focus on a practical first step you can take now with Gradle & Kotlin.

Dependencies management

Gradle allows us to declare dependencies in a very terse way

I have some problems with this code:

1. Editing magic strings is error-prone.
2. How do I centralize dependencies in a multi-modules project?
3. What is Krangl?
4. Are there newer versions of Okio and RxJava available?

With Groovy, we can fix the centralization problems with the dependencies.gradle pattern.

Doing the same with Kotlin is quite easy:

The code from the buildSrc folder is automatically available to all of yourbuild.gradle or build.gradle.kts files.

Laziness as a great virtue of the programmer

I had done that for a few projects, and I was happy at first. On my third project or so, it became obvious that extracting all those strings is tedious.

Also, we didn’t solve yet the problems 3) What is Krangl? and 4) What new versions are available?

There is a very nice plugin from Ben Manes, gradle-versions-plugin, that once applied to your Gradle project answers this. So as a lazy programmer, I wondered: could I extend it to generates exactly the kotlin code I need?

As it turns out it is possible, so let me present my new Gradle plugin!

Include the gradle-kotlin-dsl-libs plugin

If you want to jump in the code directly, git clone the sample https://github.com/jmfayard/sample-synclibs

In your top build.gradle file, add:

This new declarative plugins block is the preferred way to declare a plugin instead of the buildscript {...} syntax which provides a worse kotlin DSL user experience.

$ ./gradlew syncLibs

This is the command you run the first time, and every time you added a new dependency or just want to check what versions are available.

It first executes the task :dependencyUpdates that connects to the internet and may take a while. This task produces a JSON report with meta-data about all your dependencies, which Kotlinpoet helps to convert to the following code.

IDE integration

This generated code is all we need to experience the much better IDE integration provided by Gradle’s kotlin-dsl in IntelliJ IDEA or Android Studio ≥ 3.2

We have now solved the problems we intended to solve

1. No more magic strings, we type Libs.<TAB> and auto-completion does the rest.
2. We can use those it in all the build.gradle(.kts) files.
3. To discover what Krangl is, we press <F1> Quick documentationand click on the link to the website.
4. To know which newer versions are available, we just jump from the IDE to Libs.okio and from there to Libs.Versions.okio. 2.0.0 is currently used, and a useful comment tells us that 2.1.0 is available. (The plugin never auto-apply a dependency update, that should always be the developer’s job!!).

Give it a try

Groovy build.gradle and Kotlin build.gradle.kts files look almost similar once written. What is completely different is the writing experience of it, so I will encourage you to fire up IntelliJ IDEA or Android Studio≥3.2, either in your own projects or with https://github.com/jmfayard/sample-synclibs

I began by confessing that I hated the black magic aspect of Gradle. Opening the black box with kotlin has been super useful. I realized that Gradle is simply a good, useful, well-documented API. An API that you can work with using your developer tools and skills like any other Java API. An API whose goodness had been hidden from us. I plan to go deeper in following articles if there is enough interest.

Links

Gradle’s migration guide

The samples in gradle/kotlin-dsl are one of the best way to find out how things works.

My plugin gradle-kotlin-dsl-libs and its sample project