Jardesc - hpgDesigns/hpgdesigns-dev.io GitHub Wiki

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.

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.

  • Generated class files are what makes the Jar able to be run, so we want those.
  • Java source files are the source code (.java). This makes it easy for other users to view the source code and contribute back to the project without needing to check out all the developer tools, but at the same time, it does add some filesize to your jar, and they are ultimately optional.
  • Compression is always nice.
  • Overwriting without warning lets us rebuild the jar without always getting a nag screen.
  • The remaining options (Output folders, refactorings, and directory entries) are usually left unchecked, and I can't honestly tell you that I know what they do.

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.

  • Export with errors - Usually unchecked, for obvious reasons.
  • Export with warnings - Although we try to keep our projects free from warnings, some do slip through. Generally, Eclipse already provides facilities that make warnings obvious, so we don't really need an additional nag screen telling us what we already know. Because of this, this option is usually checked.
  • Two options should be grayed out. They are dependent on settings from the prior screen which we left unchecked.
  • Save the description decides whether to create/save these settings to a jardesc file, as well as where to place the Jardesc file. This option is usually checked, and the file is usually stored in /Project/description.jardesc so if your project is a different name from the expected (e.g. you check out LateralGM and named it LateralGM2 or something), and you want to save any changes to your jardesc settings, make sure to update this field. If you're not interesting in saving the jardesc (e.g. this is a 1-time thing), you can uncheck this option.

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.

  • If we don't already have a manifest, or if we want to regenerate the manifest, we select Generate the manifest file. When selecting this option, most of disabled options in this section of the dialog will re-enable.
    • If you want to save the manifest in the workspace, select this option.
    • If you want the jardesc file to remember the location of this manifest, so you don't have to generate it again, select that "Use the saved manifest in the generated JAR description file". This option will logically be disabled if you're not saving the jardesc.
  • If we already have a manifest, as is the case with most of our projects(it will not be the case if you are creating a new project), you can select Use existing manifest and specify the location.

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.