Hacker News Reader

Comment by vbezhenar | Hacker News Reader

I don't know which documentation do you miss. Gradle has pretty extensive documentation, stackoverflow has all kinds of answers and other websites have plenty of tutorials.

I don't know Groovy and I was able to write complicated enough multi-project builds with some custom build steps by copy-pasting snippets from the Internet and applying some common sense. I guess, Groovy knowledge is required if you need to write build plugins.

View on HN

No, Gradle's documentation is really terrible. There is just no easy path to learn it - you will with time and pain learn a bit of the interface, but deep down it remains mostly unfanthonable, unnecessarily complex and filled with strange quirks. Bruce Eckel had pretty much the same experience as myself: https://www.bruceeckel.com/2021/01/02/the-problem-with-gradl...

Everone "learns" Gradle by copy-pasting snippets from the Internet and then having to fix them when they break. And what little I have learned of Gradle over the years was certainly not thanks to their documentation, but other people explaining the concepts in blog posts and tutorials. The Gradle documentation always assumes that you will want to learn the whole build system from ground up. There is no simple documentation for people who see Gradle just as a tool secondary to their actual product that is just built with it.

It is in many ways similar to git. You can't really learn git unless you learn it from the ground up. But git is actually really simple when compared to Gradle, and most people do learn git eventually through using it. But I am yet to encounter a developer who actually learned Gradle inside out just from using it and reading the documentation.

Oh, and at least git's interface and structure has remained mostly static ever since the original concept by Linus in 2005. Same can not be said of Gradle - I feel like the developer interface is like a sand castle that is washed away every second release, and I assume the internals keep shifting as well. What a nightmare to work with.

This is funny, because I have the complete opposite experience. Yes, it took me an afternoon to find my way around Gradle. But ever since I really appreciate their documentation. It is to the point, well written, contains code samples (which I believe are unit-tested, so they the code samples are always up-to-date), contains examples in both Groovy & Kotlin, and I could keep going on. A good entry point, for example, is Build Script Basics (https://docs.gradle.org/current/userguide/tutorial_using_tas...).

> But I am yet to encounter a developer who actually learned Gradle inside out just from using it and reading the documentation.

You just met him! ;)

One thing that keeps disappointing me is the utter lack of reference-style (API) documentation. Sure, the conceptual documents contain examples. But if the example isn’t clear enough, you’re completely on your own.

For example, the following document has been largely useless to me even though I’ve spent whole days trying to make the examples work for me: https://docs.gradle.org/current/userguide/cross_project_publ...

Gradle has had reference-style API documentation for as long as I can think: https://docs.gradle.org/current/dsl/index.html

You are probably doing a bit simpler stuff, if that basic tutorial suffices you. I should have maybe added that I do Android development with Gradle. There you don't as much start with an empty build file to write the tasks to compile your project, but instead have to navigate a pre-existing large build file and figure how to correctly use the Google and Gradle interfaces to integrate to the Android build tools, such as the dreaded AGP (Android Gradle Plugin). Which by the way is actually mostly undocumnented AFAIK!

I know nothing about Android development with Gradle (or Android development in general, for that matter). I feel that is where a lot of negativity in this thread comes from. But then it's not per-se Gradle who is to blame; it's this specific use case of Gradle with Android which apparently is giving people a poor experience (e.g. lacking documentation).

> You are probably doing a bit simpler stuff, if that basic tutorial suffices you.

I've written a couple Gradle plugins, one of them was to build and test programs in our custom DSL. This exposed me to all facets of Gradle, because whatever Gradle offers to compile Java, Kotlin, ... you will most likely use for another language as well. I could not have written these plugins without the Gradle documentation. But again, it's totally unrelated to Android development.

The problem is not all developers have such a nice experience. Maybe the reason is underlying assumptions - they can really help in learning or become a really big obstacle, if one isn't aware of them. That or another, my several attempts to grok Gradle from existing scripts and documentation still fail to produce understanding.

It is not possible to learn anything inside out that is bigger than 100 megabytes.

The documentation I'm missing is: what tasks, sourcesets, etc. exist by default? Where are they defined? I don't want to do some kind of runtime introspection in a build environment shell to find out what the project build does, I want a static list of all the tasks and which depends on what.

Reply on news.ycombinator.com