Plugin:Building

Building the Plugin that interfaces between
LateralGM and ENIGMA is
usually done by a developer with a full arsenal of developer tools.
Fortunately, the process has been simplified and documented for
interested parties. These instructions walk you through the process of
installing the necessary tools (or even the full arsenol) and then
performing a build in ways officially recognized by the devs. Other
methods are welcome, of course, and do feel free to document them here.

This process is for the newer Git repository. For those interested, our
older SVN-based process has been archived to Plugin:Building
svn.

Prerequisites

Bare Essentials

• The Plugin source code.
• An editor. A text editor can suffice, but for more intensive
  editing, an Integrated development
  environment is
  preferred, such as Eclipse.
• Java Development Kit (JDK) 6 -
  Needed to compile The Plugin, since it's written in Java.
• Some way to JAR it - A jar is a renamed zip file preferred for
  packaging Java files into a self-contained executable. In this case,
  it doesn't even need to be executable, since LGM simply loads it in.
  Our preferred method is with an Eclipse Jardesc.

Developer's Arsenal

• Git (any version) - Used to
  checkout and update ENIGMA from the repository. Otherwise, this tool
  is optional.
• Eclipse (any version) - A Java
  IDE. The developers of LateralGM use this to develop in, and uses a
  description.jardesc file to build a jar from a project with a simple
  Right Click -> Create Jar.

Dependencies

• LateralGM - Needed so that The Plugin knows where to provide its
  hooks into the interface.
• JoshEdit - LateralGM's Code Editor, which is used in the
  Definitions Frame. JoshEdit is maintained as a separate project, so
  it may need to be hooked in in addition to LGM. On the other hand,
  JoshEdit is usually included inside the LateralGM Jar, so if you go
  the jar route, you don't need to get JoshEdit separately.
• JNA.jar - Needed to allow Java and DLLs (such
  as ENIGMA) to communicate. Although JNI (note, I
  not A) is a native way for Java to communicate with DLLs, we prefer
  JNA for reasons explained on the JNI page.

Getting Dependencies and Source Code

The dependencies (LGM and JNA) are usually included in an install from
the ENIGMA repository, as is The Plugin's source code, so chances are
you already have a copy. If not, please follow the appropriate
instructions on the Install page.

The required files will usually be located in the following locations:

• enigma-dev/lgm16b4.jar - LateralGM, which includes JoshEdit.
  Obtained with the collection of binaries
  during installation.
• enigma-dev/plugins/shared/jna.jar - Obtained with the collection of
  binaries during installation.
• enigma-dev/pluginsource/ - The Plugin's source code. Checked out
  from the repository during installation.
• enigma-dev/plugins/enigma.jar - The compiled and jar'd plugin, which
  also usually contains the source code, although generally you should
  use the pluginsource directory instead. enigma.jar is obtained with
  the collection of binaries during installation.

You can optionally import the LateralGM and JoshEdit projects into
Eclipse, if you are interested in developing either of those (LateralGM
requires JoshEdit). In this case, you will not need the lgm16b4.jar
dependency. Instructions for installing them may be found at
LateralGM:Building.

Or, you may download them from their respective websites.

• LateralGM (although these days the
  latest build is maintained on the enigma host, above, rather than
  the website)
• JNA (all you need is JNA.jar)

Linking it all up

Start up Eclipse, if you haven't already. In the briefest of terms, we
need to load up The Plugin source as a project, and then modify the
build path to add the dependencies as external jars. At first hand,
these may seem like fairly simple tasks, but Eclipse is a very powerful
program with many menu and wizard options that you won't be using, so
it's very easy to get lost in the menus and wizards. As such, this
section explains how to do this, step by step.

Load up the source

We begin by creating a New Java Project which will contain our plugin's
source.

1. Click File > New > Java Project.

If you don't see Java Project as an option, you probably don't have the
Eclipse JDT installed, so close Eclipse, install the JDT, restart
Eclipse, and try again.

Once you have done this, you will be taken to the New Java Project
wizard.

At this point, you need to know whether your Plugin Source code is
contained in a directory (such as enigma-dev/pluginsource, or from
extracting enigma.jar) or inside enigma.jar.

Source in directory

1. Contents should be Create project from existing source.
   • Some versions do not show this section, and instead have a Use
     default location checkbox. Uncheck it.
2. For the location/directory, browse to the directory (such as
   enigma-dev/pluginsource).
3. Working Sets should be left as-is.
4. Proceed to #Modify the build
   path.

Source in enigma.jar

1. Enter a Project Name that you like, such as Enigma.
2. Contents should be Create a new project in the workspace.
   • Some versions do not show this section, and instead have a Use
     default location checkbox. Ensure it is checked.
3. JRE may be left as-is.
4. Project Layout should be Use project root..., the first option.
5. Working Sets should be left as-is.
6. Click Finish.

And now we import.

1. In the project tree under Project Explorer, locate the new Enigma
   project.
2. Right Click > Import... (about halfway down the dropdown menu).
3. In the wizard, expand General, and select Archive File. Click Next.
4. For From archive file, browse to enigma.jar.
5. Ensure that the folder named / is checked in the left tree pane.
   • If it's only partially checked (e.g. a solid filled checkbox
     without a checkmark), uncheck and re-check it.
6. Leave Into folder as-is.
7. Check Overwrite existing resources without warning.
8. Click Finish.
9. Proceed to #Modify the build
   path.

Modify the build path

The Plugin needs some external jars linked in. In order to make this
process more modular among other projects, The Plugin defines a library
for each of the external jars. You still need to link in the jars, but
rather than linking them straight into the project, you can link them to
their respective library. This is useful for a developer because then
other projects which use the same jars can simply link in the library
without needing to locate the jar again. Since the libraries are already
defined, this section will only cover how to link the jars up with the
libraries.

The libraries are named as follows (this can be seen by configuring the
build path directly), along with their usual jar locations:

• JNA (enigma/plugins/shared/jna.jar)
• LGM16b4 (enigma/lgm16b4.jar) - includes JoshEdit. Note, if you
  already have LateralGM and JoshEdit imported into eclipse, you can
  link to those projects directly, instead of their Jar. In this case,
  you don't have to create a User Library for LGM.

To configure these libraries, take the following steps:

1. Click the Window menu > Preferences.
2. Navigate to Java > Build Path > User Libraries
3. For each of the libraries, repeat these steps:
   1. On the right side, click the New... button.
   2. Fill in the name of the library.
   3. Leave System Library unchecked.
   4. Click OK. Ensure that the new library is selected in the list.
   5. Click Add JARs.
   6. Locate the respective jar and click OK.
4. Now you can OK out of the Preferences dialog.

Now we need to link these libraries in to our project.

1. Right click on the project > Build Path (about halfway down) >
   Configure Build Path.
2. In the wizard, switch to the Libraries tab
3. Click "Add Library..." button on the right.
4. Select "User Library" and click next.
5. Select the libraries that you need, and click Finish

If you already have LateralGM and JoshEdit imported into Eclipse and
want to use them, do *not* select them from the Libraries list.
Instead:

1. Switch to the Projects tab
2. Click Add
3. Select LateralGM and JoshEdit, then click OK.

After that, we're done with our build path dependencies. You can OK out
of the dialog.

Build

Find the file named description.jardesc in the root of the project,
right click it, and click "Create Jar". Your jar will be created inside
the Project, named "enigma.jar", so you can simply drag it out or copy
and paste it to the desired location, like enigma-dev's installation on
your filesystem.

If you named your project something other than Enigma or want to alter
the way that the jar is exported, you will need to edit the
Jardesc.

Problems

If you run into any problems, feel free to ask around for help. Check on
the IRC because some other people may have experience
with the process. The most helpful person would probably be
User:IsmAvatar, since she is the dev who
maintains The Plugin and usually is responsible for building it.