6.4. Compiling your user script into an extension [Dive Into Greasemonkey]

6.4. Compiling your user script into an extension

Has your user script “outgrown” Greasemonkey's architecture? Does your user script need access to privileged Javascript functions, local files, or other Firefox features that are only available to full-fledged browser extensions? You can turn your user script into a full-fledged XPI with just a few clicks, thanks to Adrian Holovaty's amazing Greasemonkey compiler!

Procedure: Compile Butler into a browser extension

Visit the Butler user script source code. From the menu, select Edit → Select All (Ctrl-A) to copy the user script's source code to the clipboard.
Visit the Greasemonkey compiler.
Go to the “Javascript” field. From the menu, select Edit → Paste (Ctrl-V) to paste the Butler user script source code.
In the “Creator” field, enter Mark Pilgrim.
In the “Version” field, enter the current version of the Butler user script (0.3 as of this writing, but check the script's metadata section for the actual version).
Open a new window or tab and visit GUID Generator to generate a random GUID. Copy the GUID to the clipboard, including the curly braces.
Switch back to the “Greasemonkey compiler” page. In the “GUID” field, paste the GUID you got from the GUID Generator.
In the “Homepage” field, enter http://diveintomark.org/projects/butler/.
Click Create the Firefox extension. Firefox should pop up a dialog titled “Opening butler.xpi”. Select Save to disk and select a directory.

Tada! You now have a version of Butler as a browser extension. Before you install the Butler extension, you should first disable the Butler user script and verify that it is disabled by searching for something on Google. Then install the Butler extension by selecting File → Open... and selecting the butler.xpi file you created with the Greasemonkey compiler. Be sure to restart your browser to finish the installation.

An .xpi file is really just a ZIP archive with a certain directory structure. You can use any ZIP program (such as 7-zip for Windows or Stuffit Expander for Mac OS X) to decompress the archive and look at the files that constitute the browser extension.

butler.xpi
|
+-- install.rdf
|
+-- chrome/
    |
    +-- butler/
        |
        +-- content/
            |
            +-- browser.xul
            |
            +-- contents.rdf
            |
            +-- javascript.js

There are four files involved. The two RDF files are mostly Firefox boilerplate. The other two contain the actual code.

install.rdf: Metadata about the extension itself, including name, version, description, and compatible versions of Firefox.
browser.xul: Bootstrap code that checks the current URL against the script's @include and @exclude parameters, and then injects and executes the script.
contents.rdf: More metadata, Firefox boilerplate.
javascript.js: The original user script's source code.

Basically, the Greasemonkey compiler creates a really, really stripped down version of Greasemonkey that has no user interface and automatically loads a single user script on the appropriate URLs. But now you have all the source files, and you can do anything you want: create custom dialogs, modify preference panes, register menu items outside the User Script Commands menu... go wild!

Dive Into Greasemonkey

6.4. Compiling your user script into an extension

Procedure: Compile Butler into a browser extension

Further reading