Building sample npruntime plugins

Background

There is a dearth of useful documentation on how to get started with scriptable plugin development. I wanted to build a sample npruntime plugin and also some of the other sample plugins available. Most documentation assumes you are already an experienced plugin developer. Very little is aimed at new users and there are no "plugins for dummies" guides. To get started you need to read through the documentation available through the mozilla development center.

The main documentation source for developing plugins for mozilla based apps, such as firefox, is: https://developer.mozilla.org/en/Plugins

This provides a link to the Gecko plugin API reference: https://developer.mozilla.org/En/Gecko_Plugin_API_Reference

The reference includes a section on scriptable plugins using npruntime: https://developer.mozilla.org/en/Gecko_Plugin_API_Reference/Scripting_plugins Npruntime is the recommend way of writing scriptable plugins and supercedes the old xpconnect method based on the XPCOM architecture (which was itself a replacement for liveconnect).

There is a software development kit (SDK) for building scriptable plugins. It is called the Gecko SDK and some documentation on it is here: https://developer.mozilla.org/en/Gecko_SDK

Other than reading through the references, the only way to pick up plugin coding seems to be to look at existing plugins. The mozilla source includes several sample plugins but some of these are out of date and do not compile. There may only be limited value in looking at these samples as many of them are wrong. Also getting them to build is non trivial if you are not used to the mozilla build system. Some of the plugins in the source tree can be built under linux using just the Gecko plugin SDK, will others require you to build the mozilla source tree first (which takes ages).

The sample plugins can be found at the following locations in the mozilla source tree:

/mozilla/modules/plugin/samples
/mozilla/modules/plugin/tools/sdk/samples (older samples of more basic plugins)

I managed to build a selection of these under linux, using the firefox-3.0.9 source and xulrunner-1.9.0.7 for the Gecko plugin SDK. Happily this also included the sample npruntime plugin which was the only one I was really interested in. There are a few tricks to building some of the samples and others don't compile at all. Before providing a brief outline on the samples here are some general instructions on setting up a build environment. Hopefully this will help others avoid the pain I went through.

Setting up the mozilla source

Get the source for mozilla firefox and set up a .mozconfig file. Instructions on how to do this can be found on the wiki page detailing how to build http://www.cmiss.org/cmgui/zinc/Firefox. If you intend on using the Gecko plugin SDK, don't actually build firefox, just download it and set up the .mozconfig file.
Edit the mozilla/tookit/toolkit-makefiles.sh script to include any missing plugins you would like to build. This file contains a variable called MAKEFILES_plugin which lists all the paths to the plugin Makefiles to generate when the configure command is run. Several of the plugins I wanted to build were not listed here, so I added them into the list. eg I added:
```
modules/plugin/samples/npruntime/Makefile
modules/plugin/tools/sdk/samples/scriptable/unix/Makefile
modules/plugin/tools/sdk/samples/basic/unix/Makefile
```
Run the configure command to generate all the Makefiles. To do this change into the mozilla directory (you may like to set up a MOZILLA_DIR environment variable for convenience) and type './configure'.
You can now type 'make' to build the entire mozilla source OR set up to use the Gecko SDK.

Setting up the Gecko SDK

Download the appropriate Gecko SDK for your operating system and version of firefox from the link available on this page: https://developer.mozilla.org/en/Gecko_SDK
Unpack the tarball to an appropriate location. eg on my system I stuck it in my zinc directory:
```
cd $CMISS_ROOT/zinc/
tar -xvf xulrunner-1.9.0.7.en-US.linux-i686.sdk.tar.bz2
```

Configure the mozilla source tree to hook into the Gecko SDK location:

cd $MOZILLA_DIR
./configure --with-libxul-sdk=$CMISS_ROOT/zinc/xulrunner-sdk

You should now be able to build some of the plugins without having to build the mozilla source tree.

Building a plugin

Change into the plugin directory, eg: 'cd $MOZILLA_DIR/modules/plugin/samples/npruntime
Run the makefile by typing 'make'

Beaware that some plugins have problems building. Read the notes below for more details.

Notes on samples listed in /mozilla/modules/plugin/samples/

These notes are based on the samples available in the mozilla source tree for firefox-3.0.9.

default - This is the default plugin that is loaded if no plugin is found for the mime type specified. Building this required building the entire mozilla source tree first, as it depends on various files that are not available via the gecko plugin SDK.
npruntime - This is an example of an npruntime scriptable plugin. I managed to get this to compile unsing the SDK, although the makefile also tries to install the plugin and this failed. Installing the plugin requires the use of nsinstall and the makefile does not find the version available in the SDK. You can get around this by either copying the version from the SDK (under host/bin) to the required directory (mozilla/config) or making it (cd into the mozilla/config directory and type make nsinstall).
npthread - Windows only plugin, so I didn't try building it.
simple - This is an example of how to write a simple xpcom scriptable plugin. It does not build, as it depends on widget code which is no longer included in the mozilla source tree.
testevents - I could not get this to build due to autotools issues. It demonstrates how to implement a native control as a plugin.
unixprinting - This is an example that demonstrates printing from a plugin. It seems to build fine with the SDK.
SanePlugin - This is an XPCOM based plugin that enables a scanner/digital camera application to be created with javascript. It does not compile, probably just needs extra SANE libraries/headers (Scanner Access Now Easy).

Notes on samples listed in /mozilla/modules/plugin/tools/sdk/samples/