LibGDX Project Setup: Third-party support!
I finally took the time to add third-party library support to the LibGDX Project Setup application. This update will greatly help the creators of great add-ons for libgdx to get their work used by more people instead of getting lost little-by-little in the contributions forum :)
You can download the update directly from the libgdx website.
How it works
As a proof-of-concept, I added the Universal Tween Engine (which you may already know I hope) to the list of libraries, as you can see in the previous screenshots.
To let users know about new available libraries as soon as possible, the application fetches everything from distant URLs. It relies on a hard-coded URL to find the master configuration file, and then updates its view accordingly to what is described in this file.
This configuration file is hosted here, and looks like this:
[versions] 2.0.0 1.0.1 1.0.0 [libraries] libgdx = http://libgdx.googlecode.com/... tweenengine = http://www.aurelienribon.com/...
The “versions” tag is used to let the application warn you about a new update of its binaries, and the “libraries” tag list all the available libraries. As you can see, each library is linked to an external definition file. These files are downloaded individually, and the list of libraries can then be built once they are retrieved.
A definition file lists many parameters of the library. Just take a look at the definition of the LiBGDX framework itself (yup, it’s a library like every other). First kind of parameters consists in meta-data, like its name, its author, a description, a homepage, etc. Such information is mainly used in the description pop-up to present the library to the end user.
The other kind is information about how the library should be embedded into the generated projects. For instance, the “libs-common” tag lists the files required in the common project. This is how the application knows how to modify the projects (see screenshot on the right).
Using all this information, the application is able to know: (1) if the library is compatible with the HTML backend, and (2) how to edit the classpaths of the generated projects to include the selected libraries.
Add your own library!
Adding your library is easy: all you need to do is to provide us the URL of your definition file. We can also host the file for you, but you won’t be able to edit it and so you won’t be able to correct its mistakes easily (and sending us 20 tweets/mails per day won’t help :p). Therefore, the recommended way is to host the definition file yourself.
Build your definition file
- [name] The name of your library, in a human readable format,
- [author] The name of its author,
- [author-website] The author’s website URL,
- [description] A short description of the library. You can, and should, format it with some simple HTML tags, like <br/>, <b>, <i>…
- [homepage] The URL of the library homepage,
- [logo] The URL of a logo image (reserved size in info pop-up is 200×250),
- [stable-version] The version number of the latest stable release,
- [stable-url] The URL to download the latest stable release of the library,
- [latest-url] The URL to download a nightlies version of the library (if available),
- [gwt] The GWT module name of the library, to provide support for the HTML backend,
- [libs-common] A list of the files required for the common project, as they will appear in its “libs” folder,
- [libs-desktop] A list of the files required for the desktop project, as they will appear in its “libs” folder,
- [libs-android] A list of the files required for the android project, as they will appear in its “libs” folder,
- [libs-html] A list of the files required for the html project, as they will appear in its “libs” folder.
For reference, you can see the example of the LibGDX definition file, and of the Tween Engine definition file. No tag is mandatory, but you should fill every tag that can be suitable for the library :)
Test your definition file
You should test your definition file before releasing it to the public. I provided two ways to do that, and these two ways should be tried to ensure that everything is fine:
- $ java -jar gdx-setup-ui.jar -testlibdef “yourDefinitionFile.txt” : your definition file will be embedded into the list of the available libraries.
- $ java -jar gdx-setup-ui.jar -testliburl “http://yourUrl/yourDefinitionFile.txt“ : your definition file will be fetched from the URL like every other library.
See if the library information appears as you want in its information pop-up, and if all the generated projects are working fine when your library is selected.
Submit your definition file
Submissions in comments or by email can easily can lost, so there is one and only one way to submit your libraries: using the LibGDX contribution thread. Thanks a lot, that will make everyone life easier :)
This new update lets you easily use third-party libraries in your LibGDX projects. The selected libraries are automatically extracted and added to the classpaths of the generated projects. You don’t have to do anything: everything works out-of-the-box ! Anyone can contribute a library, you just have to follow the steps listed a few paragraphs above.
Don’t hesitate to report any bug you may encounter, or just to tell us if the application helped you :)