DEV Community

Cover image for Weeks of Debugging Your Build can Save Hours of Learning Gradle

Weeks of Debugging Your Build can Save Hours of Learning Gradle

You don't configure Gradle, you program it.

And sure for a while you could survive with copy/paste based programming, but man, I really hate that!

πŸ€” Why Would I Learn Gradle When I Can Just Copy/Paste Groovy Snippets?

You don't HAVE TO learn Gradle, especially if you are just getting started, but I think it's worth the time investment.

As an Android dev, you have probably been educated to "configure your build" by copy/pasting Groovy snippets from and blog posts.

What should you fix an approach that works well?

That's the thing, I don't think that approach works well, it never worked well for me at least.

And I know I'm not alone:

I have seen some of you spend way too much time than necessary debugging a broken build. The time spared by not learning Gradle has been more than wasted by this debugging time.

It's 2023 and I think that a professional developer should try to pass point 2 of the Professional Developer test written by Joel Spolsky in... 2000.

Joel's step #2 to better code

better code joel

Good news, Gradle was invented to have all your build tasks executable in one step.

That's why my ideal should contain that kind of paragraph:


## Build tasks

./gradlew runUnitTests  # run fast unit tests that don't do side effects
./gradlew runAllTests   # run all tests
./gradlew runApp        # run unit tests, install and run the app
./gradlew buildProd     # build and sign production APK
./gradlew pr            # run the same checks than on GitHub Action
Enter fullscreen mode Exit fullscreen mode

Programming that isn't that hard... but it does require learning Gradle.

And my suggestion would be to learn Gradle outside of Android for a time.

πŸ‘ŽπŸ» "Configure your build"

configure your build

I have bitched in private about that section of the Android docs, and I saw people not understanding the point I was trying to make.

They told me the doc looked fine. It documented the simple things that people need to get started. You could just copy/paste what you need somewhere.

Where should I copy/paste? I don't know, maybe in build.gradle or in app/build.gradle or in settings.gradle if you feel crazy.
Maybe it was inside the android { } block, maybe outside.
Just try it out until the build doesn't crash, and you will be fine.

I had an "AHA" moment when I realized that by "simple things" we meant different things.

If you have a Gradle snippet you can copy/paste, it can be considered simple by the definition that copy/pasting is easy. Even the snippet is about a badly-designed over-complex feature like build variants and their combinatory explosion of everything.

By simple things, I mean the fundamental concepts on which Gradle is based.

Settings, Project, Plugin, Task, Action, Configuration, ...

The Configure your build section mostly does NOT teach those fundamental concepts because it is stuck in a "configuration" paradigm.

It's totally fine indeed that new Android developers start this way.

I think that's a mistake in the long run though because Gradle is not Maven.

πŸ’‘ Gradle is a Java API that you Program in Kotlin

Maven is a build system that is configuration-based with its famous pom.xml .

Gradle is different.
Gradle is much more than Android - just like Kotlin.
Gradle is something you program while Maven is something you configure.
Gradle is not inherently better than Maven or the reverse. Spring proposes both options and many projects opt for one or the other.
Gradle is a Java API for building all kind of projects and that you program in Kotlin.
Gradle is gradle/wrapper/gradle-wrapper.jar

πŸ€” Why Gradle+Kotlin?

Gradle is a Java API as we established, so by virtue of JVM interoperability, you can program Gradle in Java, Groovy, Kotlin or a mix of all of those.

You can program Gradle in Java but that would be quite verbose indeed.

We traditionally program Gradle in Groovy because Groovy innovated with DSL support and can be scripted. But Gradle and Groovy together is bad idea IMHO if you want proper IDE support. Not because Groovy alone is terrible, but because Groovy AND Gradle together are like Cola and Mentos. Too much power, too few responsibility.

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.

That's what Gradle realized 5 years ago, and together with JetBrains for IDE and compiler support, they start a hugely ambitious project to make Gradle Kotlin-first.

Meanwhile Google did... nothing for what seemed to a very long time.
My guess is that it's a combinaison of being overwhelmed with work, technical debt, and being stuck in "configuration" mindset.

That's understandable but I feel like by treating Gradle like something it's not - a better Maven - , you don't get the benefits of either. If you want to configure things with proper IDE support, it will always be faster and better supported to use a file format like pom.xml.

✍🏻 So Will I Fix the Android Docs for Free?

No, absolutely not.

First I am not sure they want to change their configuration-based approach.
And I have better things to do with my time than convincing them in their ivory tower.

Second Google/Android is a massive and lucrative monopoly - duopoly wit Apple if you prefer. So I'm sure that they have enough money to pay technical writers to do it if they decide it's important.

True, to get hired, the technical writers would have to memorize the "Grokking the coding interview" book and plant red/black trees in a Google Docs. But that's a topic for another day.

What I'm saying is this

You could open up and understand the Gradle black box for fun and profit.

You could do better than just copy/pasting.

πŸ“š My experience

It was a really interesting experience for me, I used to hate Gradle, and now I'm the co-author with LouisCAD of one the most popular Gradle plugins.

{$% embed %}

  • Oh but actually Gradle is fast!
  • Oh but actually Gradle has nice documentation!
  • Oh but actually Gradle has good IDE support!
  • Oh but it's actually sort-of like programming any Java API!
  • Oh but the basic concepts of Settings, Project, Plugin, Task, Action etc are actually quite straightforward!

β˜‘ 4 Ways to Learn Gradle Outside of Android

I think the simplest way to learn Gradle is to escape for a moment the Android world.

Here are four ways to do it:

  • Create a super-simple Kotlin CLI client with IntelliJ
  • Create a Kotlin Multiplatform (non Android) project with IntelliJ
  • Create a Spring Boot project with
    • And see how straightforward the resulting build is.
  • Create a Ktor project with IntelliJ ultimate

πŸ€” What Does a Plugin Gradle Look Like?

That's a great question, thanks you hypocrite me for asking.

If you are curious, I would recommmand to have a look

  • Not the Android Gradle Plugin because it's a massive beat.
  • Not even at my own plugin
  • But at this very neat example plugin written in Kotlin by Gradle and that explains all the concepts in a very pedagogical way

Gradle Site Plugin Build Status Build Scan Maven Central

A sample Gradle plugin demonstrating established techniques and practices for plugin development as described in the following guides:


The plugin provides a task for generating a web page that derives information about the project e.g. applied plugins and available tasks. While minimalistic in functionality it serves as a show case for demonstrating best practices for Gradle plugin development. A site generated for this project can be viewed here.

The plugin is available on the Gradle plugin portal for public consumption

Usage example

The plugin can be applied with by identifier Default values can be configured with the help of the provided extension To generate the web page run the task named generateSite e.g. gradle generateSiteHtml.

The plugin requires a Gradle version of 4.0 or higher. All features that are

πŸ’― And Then You Bring Back That Knowledge to Your Android

Please send my article to a friend that needs it.

Hi, I’m Jean-Michel Fayard.

On my website, I have Careers Resources for Developers, and if that's not enough, you can ask me a question.

Top comments (1)

tkgregory profile image
Tom Gregory

Spot on Jean-Michel!

I feel like the Gradle DSL is designed to look like a configuration file, but it's actually code. Almost everything is a Groovy closure or Kotlin lambda expression!

When you realise this, things start to make more sense.