How to debug Gradle Plugins with IntelliJ

Where is the bug 🧐

The last few days I wrote a couple of Gradle plugins which should simplify our publish process to different repositories. During developing, I ran into issues without knowing their origin. Is the issue part my plugin? Is it a bug inside a plugin which I depend on?

Some default logging parameter by Gradle like --info or --debug are very useful here. But sometimes you need to dig into the real source code to find out what happens.

Thanks to my colleague passsy I found a way to debug Gradle Plugins — and Gradle build scripts if they are written in the Kotlin DSL — with IntelliJ 🎉.

The first thing you have to do is to create a new “Remote Configuration” in IntelliJ. Simply click on the small arrow and choose “Edit configurations…”.
In the opened popup click “Add New Configuration” (the plus symbol at the top left corner) and choose “Remote”.
Give it a name and… you are basically done and are able to debug.

Now you can run your Gradle task of your choice with some additional parameters:

./gradlew tasks -Dorg.gradle.debug=true --no-daemon

This will execute the tasks task (well) and set Gradle in a kind of “debug mode”. If you run it like that you will notice that Gradle doesn’t run until you attach the previous created Remote Configuration debugger.

Now it is a good time to set your breakpoints in your — or any other — code you have access to! Yep, the debugger even works for dependency files if they provide a XYZ-source.jar

To attach the debugger simply click on the nice little 🐛 icon:

Immediately after you have set the breakpoint Gradle will execute the given task and your breakpoints — if set and reachable of course — will be called.

Troubleshooting

Sometimes I ran into the problem that the Remote Configuration debugger can not be attached.

This happed because the port (in this example 5005) was already in use by another Gradle daemon which is still running.
To solve the issue you can simply stop all running Gradle daemons:

./gradlew --stop

Fun fact: After some unsuccessfully Googling and trying out how Gradle debugging works I found this Gradle documentation which — well — basically describes everything which I have blogged here 🙃