The "Getting Start: Project Generation" page uses a deprecated tool (gdx-setup)

djalilhebal commented 2 months ago

The Project Generation page (https://libgdx.com/wiki/start/project-generation) contains a direct download link to gdx-setup v1.12.1 (jar file), which is an old version of a deprecated project.

There is a newer continuation/fork of it: gdx-liftoff (https://github.com/libgdx/gdx-liftoff).

I scaffolded a Desktop + Web (GWT) project using gdx-setup and spent hours trying to get html:dist or html:superDev to run, only to realize later that gdx-setup is deprecated in favor of gdx-liftoff.

Suggestions:

[ ] In Project Generation, link to the gdx-setup repo (so users can download the latest version if they need to + know the project is deprecated).
[ ] Rewrite the Project Generation page for gdx-liftoff.
[ ] Update related pages, like desktop:run does not work in gdx-liftoff-generated projects but lwjgl3:run does.

I would make these changes myself, but I'm just getting started with libGDX and have no idea what I'm doing :p

crykn commented 2 months ago

I think @tommyettinger wanted to tackle this (and considering he's the sole maintainer of gdx-liftoff, he's IMO the one best suited for this).

tommyettinger commented 2 months ago

Yeah, I do want to tackle it. It does not help that I have never followed the "A Simple Game" tutorial, since it was written long after I had already learned how to do what it teaches. The actual changes mostly aren't that significant, and a lot are quick things like changing desktop:run to lwjgl3:run as mentioned. I do not have the time to go through and fix the entire wiki on my own. Some things may be possible to fix in bulk, using find+replace or the like. Others may be more subtle. I can start on the tutorial at some point soon, that should be a good starting point. If anyone else wants to contribute Liftoff-related changes to the wiki as the need for changes becomes apparent, that would be great. If you don't feel confident in a change, you can tell me about whatever is broken (communicating here or on Discord, most likely) and I can try to make it instead.

I do remember that last time I looked into this, the process for testing edits to a page was drastically more complicated than it was when we still used GitHub's wiki. That might slow things down a bit when a change is more than just a typo or something...

SonicGDX commented 3 weeks ago

Is gdx-setup actually deprecated? I know the gdx-liftoff repo has been moved into the libGDX organisation, but gdx-setup does still seem to be maintained at least with regards to dependency updates (albeit seemingly more slowly).

tommyettinger commented 3 weeks ago

Well if you're making an HTML project, gdx-setup just doesn't work. If you have Java 22 (the latest version, so clearly it must be good!) installed as your JAVA_HOME, gdx-setup doesn't work. I'm not sure if Java 21, the latest LTS, works. There's some other issues that show up often on Discord, like the gdx-setup folder structure being a challenge to use with unit tests.

So it doesn't have to be officially deprecated to have lots of people saying "don't use it."

raeleus commented 3 weeks ago

The decision to replace the old gdx setup has already been made. It's deprecated. We just need to do documentation and update links. I'm halfway through my tutorial video right now.

SonicGDX commented 3 weeks ago

Nice!

Here's a preliminary list of pages that may need changes. This probably isn't everything but this would be a good start at least.

To avoid repeating myself, most of the linked pages would need to have Desktop class names and folder names / modules / gradle tasks (like DesktopLauncher) changed to match gdx-liftoff (although, it might be worth mentioning each time that an old gdx-setup generated project would have the names as Desktop).

https://libgdx.com/wiki/start/setup - warning boxes mention gradle not supporting JDK 19, gdx-liftoff doesn't have this issue (also iirc wasn't gdx-setup updated with a newer gradle version too anyway?).

https://libgdx.com/wiki/start/project-generation

https://libgdx.com/wiki/start/import-and-running - also could mention that gdx-liftoff has a button which opens in intelliJ for you.

https://libgdx.com/wiki/start/a-simple-game - gdx-liftoff should have the macOS issue already fixed.

https://libgdx.com/wiki/audio/audio - could mention the libGDX-Oboe third party extension directly which can be added when generating a project with liftoff. Same for gdx-miniaudio

https://libgdx.com/wiki/articles/java-development-kit-selection - JDK compatibility needs to be updated

https://libgdx.com/wiki/articles/creating-a-separate-assets-project-in-eclipse - not familiar with eclipse but this page seems kind of strange and possibly outdated anyway (isn't assets folder no longer part of the android submodule)

https://libgdx.com/wiki/articles/dependency-management-with-gradle - potentially liftoff's build.gradle files are slightly different

https://libgdx.com/wiki/app/starter-classes-and-configuration

https://libgdx.com/wiki/deployment/deploying-your-application https://libgdx.com/wiki/deployment/bundling-a-jre - gdx-liftoff includes a Construo configuration which can be used to build for other desktop platforms and is worth mentioning. (https://github.com/libgdx/gdx-liftoff/releases/tag/v1.12.1.9)

https://libgdx.com/wiki/third-party/proguard-dexguard-and-libgdx - I think gdx-liftoff already includes a proguard configuration.

https://libgdx.com/wiki/app/interfacing-with-platform-specific-code - this actually might be fine left alone but I think if every other page was changed, using desktop in the leaderboard class name would be inconsistent.

https://libgdx.com/wiki/jvm-langs/using-libgdx-with-scala - gdx-liftoff has an option to enable the Scala language https://libgdx.com/wiki/jvm-langs/using-libgdx-with-kotlin - gdx-liftoff has an option to enable the Kotlin language. gdx-liftoff also has a teavm backend, so the suggestion about teavm could be replaced with a more concrete explanation.

https://libgdx.com/wiki/articles/improving-workflow-with-gradle - mentions gdx-setup.jar by name https://libgdx.com/wiki/start/project-setup-via-command-line - mentions gdx-setup.jar by name, and liftoff's CLI arguments may be different. https://libgdx.com/wiki/articles/updating-libgdx - has a link to the github changes for gdx-setup, and also a link to the gradle wrapper properties of gdx-setup

https://libgdx.com/wiki/graphics/querying-and-configuring-graphics - needs to be modified anyway because LWJGL3 is default now

raeleus commented 3 weeks ago

That is very helpful. Thanks!

libgdx / libgdx.github.io

The "Getting Start: Project Generation" page uses a deprecated tool (gdx-setup) #181