Change the Gradle DSL of generated projects from Groovy to Kotlin

[bartekpacia]

Note

Moved from libgdx/libgdx#7056

Synopsis

gdx-liftoff generates libGDX projects that use Groovy DSL for its Gradle buildscripts. It'd be better to use Kotlin instead of Groovy.

Details

Since April 2024 (almost 2 years ago), Gradle recommends using Kotlin instead of Groovy for buildscripts.

Citing Gradle docs:

(Kotlin DSL) provides an alternative syntax to the traditional Groovy DSL with an enhanced editing experience in supported IDEs, with superior content assist, refactoring, documentation, and more.

I can only agree with the above – in my experience, using Kotlin DSL for Gradle makes it more pleasant and involves much less guesswork.

I think that letting users choose between Groovy DSL or Kotlin DSL can be a non-goal of this issue: Groovy is being slowly but steadily being phased out by Gradle. Offering just Kotlin DSL would be enough.

Useful resources

• Gradle Kotlin DSL Primer
• Migrating build logic from Groovy to Kotlin

[ruska112x]

I was just about to write the same thing.

It may be worth gradually changing it first in templates and then in projects (gdx-liftoff, libgdx and so on).
I'm basically willing to help with this, but I don't know that much about templates and the framework itself.

[tommyettinger]

This would be a great idea if libGDX was a brand-new, green-field project that had just put out its 0.1.0 release. This is not the state of things. Changing the buildscript language would require changing all documentation involving Gradle, whether it is in libGDX proper or not. This is documentation in various places that can sometimes be 5 years old and still accurate today, though going back to when dependencies used compile starts to find breakage. Just getting docs updated to use Liftoff instead of the old gdx-setup, with largely compatible Gradle scripts, was a challenge in the main tutorials, like Bucket Drop. The biggest problem is where tutorials are in the form of videos; updating these is nearly impossible if they were recorded years before.

I know the Kotlin Gradle DSL offers new and good features, like code completion that isn't completely brain-dead (and Groovy really isn't meant for that). The thing is, ideally new users should only need to barely touch Gradle scripts at all, and copy-paste from existing docs should really be sufficient for users who aren't trying to run complex code at build-time. Completing this issue would make us lose that feature until either:

• Some compatibility shim is worked out so Groovy syntax was usable in things like dependency blocks...
• Or there is some automated tool to convert Groovy scripts to Kotlin ones, akin to the Python 2 to 3 scripts...
  • This would need to also be able to convert snippets of Groovy scripts, which is how most docs provide Gradle info...
• Or all existing documentation, for all first-party and third-party projects, gets the small updates needed to use only Kotlin syntax.
  • Including YouTube videos.
  • Including projects abandoned by their original authors.

All of those seem like significant undertakings, or just impossible. I would of course love to be able to always use the newest and shiniest technology, with no downsides! I would also personally prefer to use leiningen as my build system, instead of Gradle, since it is so much drastically simpler to write a build script! Neither of these are happening, though. Sometimes keeping things stable is a much better plan than improving things by breaking all of them and making users pick up the pieces.

[ruska112x]

Okay, I understand you.
In that case, maybe we could add a template to gdx-liftoff that supports the Kotlin DSL in Gradle?
It seems like it would be helpful for people who are already accustomed to kts build scripts, like me.

I could create such a template, and we could add it, but as I mentioned before, I'm just learning libGDX and couldn't immediately find where the templates for liftoff are stored.

upd: I mean the new default template that contains Kotlin and Kotlin DSL in gradle scripts both

[tommyettinger]

Liftoff pieces together Gradle scripts mostly in code, the Kotlin part of src. When users select platforms, that adds Gradle files for LWJGL3, Android, iOS via RoboVM, etc. in their own projects. When the Java version changes, that sometimes can work just by changing that variable, but sometimes needs deeper changes in some of those platform projects. When dependencies are added, usually that affects dependencies blocks only, but some libraries have special requirements, like artemis-odb doesn't supply a .gwt.xml file that is needed for it to work on GWT. So, when artemis-odb is selected, an extra file is added to the project from one of the resources folders. Templates generally affect dependencies and the generated Java or Kotlin code, but not much else in terms of Gradle changes. The Java-Kotlin mix is rather messy, but UI is all Java now and works cleanly that way, while much of the project generation code is pure Kotlin (older code, but it works!). Making Gradle scripts go from Groovy to Kotlin would vary in complexity based on how different the scripts have to be, but I think there are a lot of changes that would apply to the Kotlin code in Liftoff just to have one kts template... They'd be similar to changing all Gradle code to be kts files.

It might make more sense to have simple, small, pre-made projects using the kts scripts, that users could customize for their own game. This is the approach I do for my library template, which isn't related to Liftoff. This is also the approach I recommend when people can't run Liftoff due to having a headless machine; there's an option somewhere that makes Liftoff generate sample projects, and I usually run it via a Gradle task. I know @Quillraven has some good .kts-based projects, and Spitfire looks like an impressive amount of work (7 years! Wow!). Maybe copying and stripping one of those projects down to a bare minimum, getting it to support TeaVM, Android, and other common Kotlin platforms, and making that a base project for people to edit would be the easiest route.

[Quillraven]

I don't have that many projects anymore with Kotlin Gradle because most of my projects are created out of liftoff and I personally don't care anymore in which language those build scripts are written. The important part is that they run ;)

Anyway here is one example project with with android and desktop but it is ~5 years old. Still, could be useful as a starting point for a template.

Here is one more example but also 5 years old.

Here is a more up to date kotlin multiplatform example of Fleks ECS.

---

Besides that, there are so many ways in Gradle to solve a specific problem (which I personally don't like a lot) so someone needs to decide how a template should look like. Do we want buildsrc or not? Do we want to use gradle's catalogue feature for versions or just normal properties? etc..

Again, I personally don't really care and just use whatever liftoff throws at me. Those files are almost never touched besides maybe adding a dependency and I don't care if the string is with single or double quotes or if it uses a catalogue version or not.

But that's just my personal opinion on that topic :)

[bartekpacia]

Thanks a lot for your input to this discussion, especially @tommyettinger. It's unfortunate but it's the reality.

That said I still think there are some very low hanging fruits we can do – use simple Groovy in gdx-liftoff's templates (i.e don't use wild features).

Practical examples:

• When calling a method, use parentheses like in sane programming languages
• When assigning, don't omit the = sign (it's a Gradle-specific quirk and it's going away)
• Standarize on double-quotes over single-quotes

The above things are quite easy to contribute, and they will benefit:

• normal users who couldn't care less about it. But even they have to edit buildscripts sometimes. They will have an easier time understanding buildscripts (and IDE support will be a bit better)
• gradle masochists enthusiasts like me who want to convert their project to Kotlin DSL. They will have less mundane conversion to do.

[tommyettinger]

I can probably do all those practical examples at some point. The tricky part is mostly finding all uses of those weird-Groovy-Gradle features, since I doubt a regex can locate them.