Add reaction
Like
Unicorn
Exploding Head
Raised Hands
Fire
Save
Boost
More...
Copy link
Copy link
Copied to Clipboard
Read the friendly documentation
Usage
Make sure the project is correctly set up (see just above).
Migrate project:
The refreshVersionsMigrate task can help you migrate your project in a few minutes, or less.
In version 0.50.0, support for Gradle's Versions Catalogs was added (see discussion thread here ), so a --mode option is now required.
Run it without it to see the complete list and the full description of...
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 (actuallyhttps://guides.gradle.org/performance/ and https://developer.android.com/studio/build/optimize-your-build .
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 Gradle's kotlin-dsl project on which
How to migrate
Migrating build logic from Groovy to Kotlin mentions two possible strategies
Migrating the existing syntax of your build to Kotlin, bit by bit, while retaining the structure β what we call a mechanical migration 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.
// before.c
int main () {
/* I was doing C programming */
printf ( "Hello, World!" );
return 0 ;
}
// after.cpp
int main () {
// Now I'm now doing c++
printf ( "Hello, World!" );
return 0 ;
}
Enter fullscreen mode
Exit fullscreen mode
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
dependencies {
implementation ( "com.squareup.okio:okio:2.0.0" )
implementation ( "io.reactivex.rxjava2:rxjava:2.2.0" )
implementation ( "de.mpicbg.scicomp:krangl:0.10.3" )
}
Enter fullscreen mode
Exit fullscreen mode
I have some problems with this code:
Editing magic strings is error-prone.
How do I centralize dependencies in a multi-module project?
What is Krangl?
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:
// buildSrc/build.gradle.kts
plugins {
`kotlin-dsl`
}
// buildSrc/src/main/kotlin/Libs.kt
object Libs {
val okio = "com.squareup.okio:okio:2.0.0"
}
// some-module/build.gradle or
// some-module/build.gradle.kts
dependencies {
implementation ( Libs . okio )
}
Enter fullscreen mode
Exit fullscreen mode
The code from the buildSrc folder is automatically available to all of your build.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
As it turns out it is possible, so let me present my new Gradle plugin!
Include the buildSrcVersions plugin
In your top build.gradle file, add:
pluginVersion
plugins {
id ( "de.fayard.buildSrcVersions" ) version "$VERSION"
}
Enter fullscreen mode
Exit fullscreen mode
You will find $VERSION at https://plugins.gradle.org/plugin/de.fayard.buildSrcVersions .
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 buildSrcVersions
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.
// Folder buildSrc/src/main/kotlin
object Libs {
/** [krangl website](https://github.com/holgerbrandl/krangl) */
const val krangl : String = "de.mpicbg.scicomp:krangl:" + Versions . krangl
/** [okio website](https://github.com/square/okio/) */
const val okio : String = "com.squareup.okio:okio:" + Versions . okio
/** [rxjava website](https://github.com/ReactiveX/RxJava) */
const val rxjava : String = "io.reactivex.rxjava2:rxjava:" + Versions . rxjava
}
object Versions {
const val krangl : String = "0.10.3" // up-to-date
const val okio : String = "2.0.0" // available: milestone=2.1.0
const val rxjava : String = "2.2.0" // available: milestone=2.2.2
}
Enter fullscreen mode
Exit fullscreen mode
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.
https://www.useloom.com/share/7edceb83fd594f319356240fcce304d5
We have now solved the problems we intended to solve
No more magic strings, we type Libs.<TAB> and auto-completion does the rest.
We can use those it in all the build.gradle and build.gradle.kts files.
To discover what Krangl is, we press Quick documentation and click on the link to the website.
To know which newer versions are available, we just jump from the IDE to Libs.okio and from there to 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.
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 with 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
My plugin
Life is too short to google for dependencies and versions
What is refreshVersions?
refreshVersions helps Gradle users with the tedious manual work usually involved in adding and updating dependencies and their versions .
Documentation
See documentation at https://splitties.github.io/refreshVersions
Setup
// settings.gradle(.kts)// See https://splitties.github.io/refreshVersions" de.fayard.refreshVersions" " 0.60.6" // Optional: configure the plugin// ...
Enter fullscreen mode
Exit fullscreen mode
Read the friendly documentation
Usage
Make sure the project is correctly set up (see just above).
Migrate project:
The refreshVersionsMigrate task can help you migrate your project in a few minutes, or less.
In version 0.50.0, support for Gradle's Versions Catalogs was added (see discussion thread here ), so a --mode option is now required.
Run it without it to see the complete list and the full description of...
The gradle/kotlin-dsl samples
Gradle Kotlin DSL Samples
Caution
This repository is now obsolete.
Up-to-date Kotlin DSL Reference docs for Gradle can be found here .
Top comments (4)
"Migrating the existing syntax of your build to Kotlin, bit by bit, while retaining the structure β what we call a mechanical migration"
Intriguing! I have a large gradle file and can't allocate the time to convert it using option 2.
Is this suggesting that I can convert one file to kotlin bit by bit? I assumed that renaming the file to .kts would stop the existing groovy from being accepted.
Usually in a large build file, there are parts that looks like code and parts that are very declarative.
What I would do is keep the file in groovy (build.gradle), but remove from it everything that looks like code. Put that part in the buildSrc folder in kotlin.
In the end you will have a very declarative groovy file, that would look almost the same in kotlin anyway.
That's almost what I do here. Well dependency strings are not exactly code, but they are easier to manage as code.
Also if you have a project with multiple modules, you can freely convert one file to kotlin (build.gradle.kts) and keep the rest in groovy. I would migrate the root build file since this the most interesting for adding new stuff.
I guess the plugin ID has changed to
"de.fayard.buildSrcVersions"Completly true, thanks a lot, I updated the article.