Jardesc

From ENIGMA

Jump to: navigation, search

A Jardesc is an XML file intended for Eclipse to describe how to build a jar of a Java project. When using eclipse, it can be a very convenient tool for building a jar, as simple as Right click > Create Jar. Unfortunately, it is also very limited, especially with regards to portability and capability (for instance, it can't plug in a build number or date into a file. It also can't blacklist folders/files for exclusion - instead, you have to whitelist folders/files and keep the whitelist up-to-date).

Eclipse provides a Wizard for creating and modifying Jardesc files in a fairly user-friendly way, but since they are XML files, you can also edit them as text files and replace/enter the appropriate information.

To edit an existing jardesc, right click on the jardesc, Open With, and select the desired editor.

To create a new jardesc in Eclipse, right click on the project, Export, Java, Jar, and the wizard will appear.

Notice that newer versions of Eclipse will also allow you to export a "Runnable Jar". This is an extremely simplified way to create a Jar, and as a result, it can easily overlook your preferences (for example, it omits source files and generates dependency folders). We generally encourage using Jardesc over this method, especially since a well-built jardesc makes it even easier to create jars.

Contents

Wizard

The wizard is broken into 3 sections: Import/Export, Warnings/Save, and Manifest/Main. When working with an existing jardesc, most of the settings will already be set to their desired states, although you are free to tweak them to try to get something more optimal to your tastes.

Import/Export

In the first section, we handle import/export.

The top portion has the projects tree, where you select which projects and files you wish to export. We usually include most of the files and folders for our project, however there are a few exceptions that simply don't need to be included in the jar, such as the revision control repository files (.git, .svn). If there are dependency projects that you imported into eclipse (such as JoshEdit), double check to see if they are checked (if you want to include them in the jar. For example, JoshEdit is usually included with LateralGM, but not included with the Plugin since the Plugin depends on LateralGM's jar, which already includes JoshEdit). It can get tricky, so usually you shouldn't stray too far from the default options.

Export destination is usually the field that you might want to modify. Remember to include the filename, enigma.jar.

The checkboxes can usually be left as-is.

If the remaining two screens are set up the way you like, and chances are, they probably are, you can usually just click Finish at this point, and the Jar will be built to the location you specified in "Export destination".

Warnings/Save

The second section handles warnings, errors, and where to save the jardesc.

Manifest/Main

The Jar by itself is simply a zip file, so there is nothing inherently special about it that tells it how to run. Instead, this is achieved through the use of meta-information, stored as files - in particular, the Manifest file. The manifest defines information like executable definitions and dependencies. It is usually located inside a folder named META-INF and should be named MANIFEST.MF, yielding the following: /Project/META-INF/MANIFEST.MF so please confirm that this path is correct and reflects your project's name.

Sealing, as I understand it, somewhat prevents people from tampering with a Jar by adding/removing files. This is especially useful in closed-source and shareware projects. In projects like ours, we want our users to be free to modify the files to best suit their needs, so we opt to "Seal some packages", and for the "Some" we don't select anything, so the result it "Nothing sealed".

The most important part of this screen is going to be the Main class section, because it tells the Jar which class to run. Eclipse frequently leaves this field blank, so be sure to select the class containing the desired main method. Usually the Browse button conveniently finds it (along with any other Main methods you may have interspersed throughout the project).

Finish

After clicking Finish, Eclipse will attempt to build the jar file. It will sometimes report JAR export finished with warnings, but that's usually ok. If it gives an all-out error, go back and check your work. Once this has completed, you should now have a Jar in the desired location. Congratulations, you have now built the project.

You may now test your jar by placing it in the appropriate directory and running the project in the appropriate way. For example, when building the plugin, backup and replace enigma-dev/plugins/enigma.jar with your new jar and run ENIGMA/LateralGM in the usual way. LateralGM, on the other hand, can simply be run as-is, wherever it resides.

You may consider submitting your built jar to the collection of binaries. However, if you made changes to the source code for the project, you should consider submitting those changes first, and letting a developer build and maintain the binaries. This option is usually just available if the developers haven't gotten around to building a binary yet.

Personal tools
Namespaces
Variants
Actions
Navigation
ENIGMA
Other
Toolbox