Jardesc

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.