What you need

To build and develop Piggy Bank you need:

  • Firefox (version 1.5 or later)
  • A Java Developer Kit (version 1.4 or later) NOTE: if you are on a Mac it comes with it, so you don't need to worry about this
  • Ant (version 1.6.2 or later)
  • Maven (version 2.0 or later)
  • Subversion Client (version 1.2 or later)
  • Appalachian, installed as a Firefox add-on for its OpenID API; this is not a strict requirement if you don't intend to work on publishing

Things that are not required but help:

  • FireBug - a great Firefox extension to help you debug, inspect and profile Firefox extensions.
  • Leak Monitor - another great Firefox extension that pops up warning if it spots any memory leaking in your extension code. NOTE: this spots leaks only on the javascript side of things, but it's a help.
  • Eclipse or any other Java IDE.
  • Subclipse (subversion plugin for Eclipse)

NOTE: not all subversion clients react on the "svn:externals" property (the ability to download different part of the repository in one shot). Piggy Bank won't work correctly if your Subversion client doesn't support externals (for example, Subversive doesn't). If in doubt, download the command line version and use that.

How to start Piggy Bank Development

  1. Open your favorite shell/terminal on Unix/MacOSX or DOS Prompt on Windows
  2. Make sure that Ant and Maven are installed and that ant, mvn, and svn are available in your path (if you don't know how to do this, stop here and download an already compiled Piggy Bank and save yourself a lot of pain)
  3. Checkout Piggy Bank from the Subversion repository at http://simile.mit.edu/repository/piggy-bank/trunk/. We'll assume that the checkout created directory called piggy-bank.
  4. Type cd piggy-bank
  5. Type ant to prepare Piggy Bank. This will prepare the Piggy Bank extension at src/extension.

NOTE: sometimes, due to heavy load, Maven fails to download some of its jars and reports errors. In case this happens, repeat executing mvn package from the command line until no more errors are found. Then type ant.

Using Eclipse

  1. Add the above Piggy Bank directory to your Eclipse setup as a new project
  2. Open up the general Eclipse Preferences and browse to Java > Build Path > Classpath Variables, then click New... and add the variable M2_REPO with the path that corresponds to your Maven 2 repository (this will already be done if you've set up Eclipse to work with Longwell)

How to install Piggy Bank in Firefox for Development

  1. Locate the full path to the firefox executable. On windows is normally something like c:\Program Files\Mozilla Firefox\firefox.exe, on macosx is something like /Applications/Firefox.app/Contents/MacOS/firefox-bin, while on Linux is varies depending on your distribution (try typing firefox in your command line since it might be already in your path).
  2. In your shell/dos-prompt, type <firefox> -ProfileManager where <firefox> is the full path to the executable. This will bring up Firefox Profile Manager. (I know there are easier ways to bring up the profile manager on windows, but you need this later anyway so stay with me)
  3. Create a new profile and chose a location that you can easily remember. NOTE: keep firefox running while executing the next points!
  4. Type cd [profile]/extensions where [profile] is the directory where the profile is (of course on Windows you will be typing \ instead of /)
  5. Create a file named {e29a3ba7-2b91-4bf1-8c04-b9738c77aa3d} and write the absolute path to the extension directory (which is piggy-bank/src/extension/ where piggy-bank is the location of the Piggy Bank checkout (again, on Windows, you will be typing \ instead of /). Basically, you are installing the XPI by hand and telling Firefox where to find it. (This acts as a pseudo-symlink that works in all operating systems).
    • Make sure that your file is a single line and no whitespace or newlines at the end of the path or Firefox won't load it.
    • You can create the file by typing at the command line notepad "{e29a3ba7-2b91-4bf1-8c04-b9738c77aa3d}" but note that Notepad automatically appends a .txt extension to your file, so you need to delete that extension after quitting Notepad.
  6. Restart Firefox and Piggy Bank will ask to be configured.
  7. Once you're done configuring Piggy Bank, open Tools > Piggy Bank > Options from the Firefox menu bar.
  8. Select the Development tab.
  9. Click on Enable Debug (here, you can also select what Piggy Bank subsystems you want to debug/trace. Note: they are very verbose and make the whole program slower, so turn on only what you need, and don't worry, you don't have to restart for these settings to take effect!)

NOTE: the Pig icon wears a hard hat in debug mode ;-)

Where do the logs go?

Piggy Bank is composed of two subsystems, a javascript side and a java side. They have, unfortunately, different logs and in different place depending on the Operating System.

Windows

On windows, you have to start Firefox from the command line (using the path you discovered above to trigger the profile manager!) with the -console parameter.

 C:\Program Files\Mozilla Firefox\firefox.exe -P development -console

starts firefox with the development profile and starts up the output console (here if you have javascript tracing enabled in your debugging options, you should see a bunch of tracing events being logged).

The Java part is logged into the Java Console. You can access it by right-clicking on the Java icon that appears on the tray bar after you have started Firefox.

If you don't like to use the DOS prompt, an alternative way to start firefox is to "right-click" on the firefox shortcut that starts it (for example, the one in the task bar), then select Properties and change the Target text box to

"C:\Program Files\Mozilla Firefox\firefox.exe" -P development -console

Now you can run firefox in debug mode just by clicking on the icon as before (this is also a good way of having multiple shortcuts for different profiles, which is very handy when you want to do development with one browser and still use another one to navigate)

MacOSX

On MacOSX, you have to start Firefox from the command line as well, but there is no need for a console parameter:

 /Applications/Firefox.app/Contents/MacOS/firefox-bin -P development

The java logs are dumped onto a file. The best option is to type

 open ~/Library/Logs/'Java Console.log'

which will execute the Console program over the log.

Linux

On Linux, you have to start Firefox from the command line as well, but just like MacOXS, there is no need for a console parameter. In most Linux distributions firefox is in your path so you can just type:

 firefox -P development

the javascript tracing will be dumped on that STDOUT. If you are using Sun's JDK, the java output is written to the java console which is disabled by default. To enable it type

 ControlPanel

(assuming that your $JAVA_HOME/bin is your PATH), then select the Advanced tab, expand the Java console tree item and select Show console in the radio menu. Then click Ok and restart firefox. The Java Console will open as soon as the java subsystem is invoked from your browser.

The Development Lifecycle

Piggy Bank can be fully developed in place, meaning that you can edit directly the files under version control and that Piggy Bank reacts accordingly, without you having to repackage or reinstall the firefox extension and, even better, without having to even restart firefox!!

After you have installed Piggy Bank and turned it into "debug mode" (this is necessary for Piggy Bank to unlock the internal firefox caching facilities), you can simply close and reopen a firefox page to see things updated.

There are two exceptions: java classes and the javascript XPCOM components (found in src/extension/components).

Changing Java Classes

When you change java classes, you could run ant again and restart the browser. That is the obvious but slowest choice.

A better way is to use a 'compiling IDE' (such as Eclipse or IDEA) with Maven2 support (there are plugins for both Eclipse and IDEA). This makes the "editing and compilation" phase pretty much instantaneous.

This means that you don't have to invoke ant to recompile anything, but you have to tell Firefox where to look for the new classes that your IDE compiled. To do this, open the Tools > Piggy Bank > Options panel from the Firefox menu bar, select the Development tab and place the absolute path to the piggy bank classes:

 [path-to-piggy-bank]/target/classes/

Changing even a single java class requires the entire classloader to be reloaded. There is no automatic way for piggy bank to reload automatically, but there is a Piggy Bank Reload button that does that (the pig with a big green arrow on it). Right-click on the browser progress loading button on the top right corner of the window and select Customize..., you can then drag the reload button in your browser bar.

Clicking the Piggy Bank Reload button will force the internal web server to shutdown and discard the current Piggy Bank web application and restart a new one, this is not super-fast but it's faster than restarting the browser.

Changing XPCOM Components

If you change anything in the src/extension/components/ directory, the browser needs to be restarted and the extension directory "touched" to signal to Firefox that it should reload the XPCOM registry with the new components. This is done by typing ant.

Packaging Up an XPI

Instead of ant, type ant xpi. This will make an .xpi file in the piggy-bank directory.

Troubleshooting

Missing "replaceregexp" Ant task

The Piggy Bank build system requires the replaceregexp task to be present and ant considers it an optional task so some Linux distributions don't include it by default when you install Ant. If you are using Fedora with yum configured to use the jpackage.org repositry, this is as simple as:

 yum install ant-nodeps ant-apache-regexp 

If you are using Debian or Ubuntu, type (as root, or using sudo):

 apt-get install ant-optional

NullPointerException and Failed to start web server

If your pig icon never stops spinning, your javascript console reports

Error: uncaught exception: java.lang.NullPointerException

and your java console reports something like

   Exception in thread "Thread-4" java.lang.RuntimeException:
        Failed to start web server to serve at http://127.0.0.1:1978
	at edu.mit.simile.piggyBank.PiggyBank$1.run(PiggyBank.java:149)
   Caused by: java.lang.NullPointerException
	at edu.mit.simile.piggyBank.PiggyBankService.<init>(PiggyBankService.java:40)
	at edu.mit.simile.piggyBank.PiggyBank$1.run(PiggyBank.java:142)
   java.lang.NullPointerException
	at edu.mit.simile.piggyBank.PiggyBank.getPort(PiggyBank.java:217)

it means that your subversion client doesn't support externals and it failed to checkout files that are part of Longwell and are required for Piggy Bank to start its internal web server. Download a subversion client that supports externals (such as the original svn command line client) and checkout the project with that.

More Info

Here are some some useful links:


Back to Piggy Bank.