Manual Home

Contributing to Magpie

Magpie is designed to be easy to modify and adapt to new problems. This part of the manual explains how to build Magpie from source and describes how to add new features.

The the latest version of the source code for Magpie is available on BitBucket.

Building Magpie

There are two methods for compiling a new version of Magpie: using an automated build script provided with Magpie and through an Integrated Development Environment (IDE). For both methods, you will need to install version 7 (or greater) the Java Development Kit (JDK).

The first method for building Magpie is using Apache ANT, which is kind of a Java-centric version of Make (if that helps). To use it, simply copy or link simple-build.xml to build.xml in the Magpie root directory. Then, call ant jar and Ant will take care of compiling the source code, linking the libraries, and storing it all in the dist directory.

The alternative (and recommended) method is to use an IDE to build Magpie. If you haven't already used one, IDEs are tools that provide a single platform for editing, debugging, and preparing software for distribution. Many (like Netbeans), have handy features like automatic code generation, error checking, and tools for automatically restructuring your code. There are a variety of IDEs available for writing Java programs, and you are probably better off reading their own guides for setting up a new project. Just keep in mind that you may need to tell the IDE to link with all of the libraries in the required-libraries directory.

Extending Magpie

Now that you have a good understanding how to compile your new changes, it is time to discuss how to write new components.

Adding New Components

Adding new functionality to Magpie will more than likely involve implementing a new version of some archetypal "Base" class. The best way to create a new implementation is to find an already existing class that is closest to what you want to do, and copy it. Make sure to place the new file in the same directory as the old implementation (very important when compiling Magpie). Once you have done that, follow this simple procedure:

  1. Document What You Want to Do: Java has a wonderful documentation generation tool. So, before you get too distracted in writing code, write out the goal of what you want this new filter or model or whatever to do in the top section of documentation above the "public class" line. Everyone will thank you, or at least feel less confused about why documentation for a totally different tool is at the top of your file.
  2. Find Out What You Will Change: Read the documentation in the base class to find out which operations you need to write. If there isn't some kind of guide on what this base class does, you have been cheated and should complain to whoever is in charge of Magpie (hopefully not you).
  3. Actually Make Changes: Hopefully, the code already in your file does something similar to what you wanted to accomplish. If so, this step could be decently easy.

Adding New Text Commands

Creating new text commands for the Magpie interface is certainly a more advanced topic. The general idea for adding a new command is to alter the runCommand(List<Object>) operation for the class in question. The source code for BaseModel and its implementations should give you a detailed set of examples for how to write new commands and how to document them. Read the JavaDoc for Commandable for more details on both.

A few pitfalls to watch out for: