Plugin:Building: Difference between revisions

From ENIGMA
Jump to navigation Jump to search
 
Line 48: Line 48:
Once you have done this, you will be taken to the New Java Project wizard.
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.
At this point, you need to know whether your Plugin Source code is contained in a directory (such as wherever you forked it to, or from extracting enigma.jar) or inside enigma.jar.


==== Source in directory ====
==== Source in directory ====
Line 54: Line 54:
# Contents should be ''Create project from existing source''.
# 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.
#* Some versions do not show this section, and instead have a ''Use default location'' checkbox. Uncheck it.
# For the location/directory, browse to the directory (such as enigma-dev/pluginsource).
# For the location/directory, browse to the directory (such as the plugin source).
# Working Sets should be left as-is.
# Working Sets should be left as-is.
# Proceed to [[#Modify the build path]].
# Proceed to [[#Modify the build path]].

Latest revision as of 04:32, 6 December 2013

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, so chances are you already have a copy. If not, please follow the appropriate instructions on the Install page.

The LateralGM plugin is hosted in it's own repository on GitHub.

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

  • enigma-dev/lateralgm.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/plugins/enigma.jar - The compiled and jar'd plugin, which also usually contains the source code, although generally you should use the plugin source 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 lateralgm.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 wherever you forked it to, 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 the plugin source).
  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)
  • LateralGM (enigma/lateralgm.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 External 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.