Plugin:Building_svn - hpgDesigns/hpgdesigns-dev.io GitHub Wiki

This is an archive page from when LateralGM used to reside on Svn. We have since moved to Git, and have updated our build process accordingly, which can be found on the page Plugin:Building.

Building the Plugin that interfaces between LateralGM and ENIGMA is a simple task made daunting by the fact that it doesn't have any simple methods yet, since it's always done by a developer with a full arsenal of developer tools. These instructions basically walk you through the process of installing this arsenal of tools and then performing a build in the same method that the devs do - making it the "official method". Other methods are welcome, of course, and do feel free to document them here.

Prerequisites

Bare Essentials

  • 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. For this document, we will use Eclipse and a description.jardesc file.

Dependencies

  • LateralGM.jar - Needed so that The Plugin knows where to provide its hooks into the interface. This is usually provided in a fresh checkout of ENIGMA's repository.
  • 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, I was never able to get it to work, so I upgraded to JNA. This is usually provided in a fresh checkout of ENIGMA's repository.
  • SvnKit.jar - Needed to provide SVN communication methods, such as the ones the plugin uses to Auto-Update. Regardless of whether you want Auto-Update or not, The Plugin still needs SvnKit to recognize the functions that it might call. Otherwise, you'd have to remove all the calls to SvnKit from The Plugin's source code... SvnKit is usually provided in a fresh checkout of ENIGMA's repository.

Developer's Arsenal

  • Subversion (any version) - Used to checkout and update ENIGMA from the repository, so as to get the dependencies mentioned above. If you already have all of that, you don't need subversion, but it's just a great tool to have in general.
  • 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 -> Build from Jar.

From Scratch

Obtaining the Basic Tools

Java, Subversion, and Eclipse can be obtained from the Linux repositories (you can use the Software Center) or their respective websites (e.g. for windows users)

  • Software Center: search for JDK, Subversion, and Eclipse, usually under Developer Tools.
  • apt-get: sudo apt-get install default-jdk subversion eclipse
  • yum: sudo yum install default-jdk subversion eclipse
  • Download the binaries: Oracle JDK 6 (you won't need FX, EE, or NetBeans), Subversion, and Eclipse (I'd recommend Eclipse IDE for Java Developers or Eclipse Classic).

On first run, Eclipse will ask you for a workspace, or a location for it to store projects. This does not matter; it's completely up to you. The default location is usually sufficient.

Sometimes the repository only offers the JRE or JDK 5 (usually with older distro versions), in which case you can download from the Oracle website instead. Sometimes the Software Center will not install the Eclipse JDT along with Eclipse, so you may have to install it afterwards.

Getting Dependencies

The dependencies (LGM, JNA, and SvnKit) are usually included in the ENIGMA repository, as is The Plugin's source code, so chances are you already have a copy of the repository. If not, simply check out with:

svn co https://enigma-dev.svn.sourceforge.net/svnroot/enigma-dev/trunk enigma-dev

Where enigma-dev is the name of the folder you wish for the files to go into. Obviously this will require an internet connection, and the operation may take a moment, during which time it will output every file as it fetches it.

Alternatively, you may fetch the dependencies from their respective websites.

  • LateralGM (although these days the latest build is included in the ENIGMA repository, rather than the website)
  • JNA (all you need is JNA.jar)
  • SvnKit (SvnKit.jar usually comes in a zip with other files. All you need is the SvnKit.jar)

Or you may download them from the ENIGMA repository without the use of SVN:

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. There are several ways to do this, any one of these is sufficient:

  • Click File > New > Java Project.
  • Click the New Button (first toolbar button), preferably the dropdown arrow.
    • If you click on the button but not the arrow, a wizard will ask what type of project, so select Java Project and click Next.
    • If you click the arrow, simply click Java Project from the dropdown.
  • Right click the area below the Package Explorer (this is the package tree) > 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.

Source in directory

If your plugin source is contained in a directory, we will use that directory as our project 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 enigma-dev/pluginsource directory.
  3. Working Sets should be left as-is.
  4. Proceed to #Modify the build path.

Source in enigma.jar

If you did not extract the enigma.jar, we will create a new blank project and import it later:

  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 3 external jars linked in. In order to make this process more modular among other projects, The Plugin defines a library for each of the 3 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 3 libraries are named as follows (this can be seen by configuring the build path directly), along with their usual jar locations:

  • SvnKit (enigma/Autoconf/svnkit.jar)
  • JNA (enigma/plugins/shared/jna.jar)
  • LGM16b4 (enigma/lgm16b4.jar)

To configure these libraries, take the following steps:

  1. Right click on the project > Build Path (about halfway down) > Add Libraries.
  2. In the wizard, select User Library, and click Next
  3. On the right side, click the User Libraries... button.
  4. You will now be at a Filtered Preferences window where we can configure Uesr Libraries.

For each of the 3 libraries, repeat these steps:

  1. On the right side, click the New... button.
  2. Fill in the exact 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.

... At this point I ran into something that confused me, so I'm investigating it.

Build

This is the simplest step, but a lot of setup is required before you can do this. Once you've set up everything, though, you don't need to do that again and from then on you can build with this very simple step.

Ideally

Ideally, you'd just find the file named description.jardesc in the root of the project, right click it, and click "Build Jar". Unfortunately, this particular jardesc assumes that your project is named Enigma and that you wish to export the jar as /home/ismavatar/Desktop/enigma.jar.

How to fix it

You can either edit it as a text file (xml) and replace the appropriate information, or you can use the wizard. Right click on said file, Open With, and select the desired editor. Since a text editor is fairly straightforward, the remainder of this section will cover the wizard.

The wizard is broken into 3 sections. In the first section, we handle import/export. Ensure that the whole project is checked (left half of the tree panes), as it has a tendency to become unchecked. About halfway down, you'll see the export location, so fix that. Remember to include the filename, enigma.jar. The remaining checkboxes can be left as-is. If your project is named Enigma, you may simple click "Finish" at this point. Otherwise, click Next.

The second section handles warnings and something called META-INF, which contains meta-information for the jar, like executable definitions and dependencies. The checkboxes should be ok as-is. In the part that says /Enigma/META-INF, change the Enigma to whatever you named your project. At this point you can click Finish, and it will create your jar, but you may have to repeat this steps again next time. Click Next to get to the third page, which handles saving these export settings. Ensure that Use existing manifest from the workspace is selected, and the textfield should read /Enigma/META-INF/MANIFEST.MF replacing Enigma with whatever you named your project. Click Finish.

After clicking Finish, Eclipse will attempt to build the jar file. It will probably report JAR export finished with warnings, but that's 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 Plugin. You may use it by replacing enigma/plugins/enigma.jar with your new jar (make a backup of your file, in case it then tries to update itself via SvnKit) and running ENIGMA/LateralGM in the usual way. You may submit your built jar to the repository, or to anybody who has commit access to the repository. Notice that, due to an option specified in the jardesc, the jar will contain all of its own source code as well. This is desirable to make it easy to abide by the license.

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.