Chapter 7: Packaging the Toolbar
Up to this point in the tutorial, we have been relying on the dynamic development system to handle installation responsibility for our extension. The end-user doesn’t want to go to all of this trouble to install your extension, so we must package everything up into one installable file. We will actually be creating two files: an XPI (cross platform installer) and a JAR. Don’t let these file extension names fool you; both files are simply zip files in disguise.
This is where our zip tool comes in handy. For the purposes of this tutorial, I will make use of the standard UNIX zip tool, available for Windows in the Cygwin tool set.
Updating the Chrome Manifest
The first step in the packaging process involves updating the chrome manifest. Note that if you want to continue doing dynamic development, you’ll need to keep two chrome manifests around: one to package the extension with, and one for dynamic development purposes. Dealing with two files can be tricky, so we will only work with our existing chrome manifest for this tutorial. Note that after we modify our manifest, we won’t be able to do dynamic development any more (unless we revert the modifications). Let’s first take a look back at the contents of our chrome manifest:
content tuttoolbar chrome/content/ overlay chrome://browser/content/browser.xul chrome://tuttoolbar/content/tuttoolbar.xul skin tuttoolbar classic/1.0 chrome/skin/
All of the file-system paths in this file need to be updated (there are 2 total). Let’s take a look at the updated version of the first line (the changes have been highlighted):
content tuttoolbar jar:chrome/tuttoolbar.jar!/content/
You’ll note that we’ve added two items. The first is the jar: directive placed at the beginning of the path. This indicates to Firefox that it needs to look inside of a JAR file to find the content of this extension. The second item we added is the tuttoolbar.jar!/ bit of text, right between the chrome/ and content/ folder names. This bit of text tells the installer which JAR file it needs to look in. The filename of the JAR we have specified uses the exact same name as our package name (a requirement of the installer). As such, the filename must be all lowercase, just like the package name. Note that the exclamation point at the end of the name is no typo; that character is required. The other path we need to update for our chrome manifest is on the skin registration line. Here is the final version of our updated chrome manifest:
content tuttoolbar jar:chrome/tuttoolbar.jar!/content/ overlay chrome://browser/content/browser.xul chrome://tuttoolbar/content/tuttoolbar.xul skin tuttoolbar classic/1.0 jar:chrome/tuttoolbar.jar!/skin/
Creating the JAR File
The first package we need to create is our JAR file. This file will live within the chrome directory, and will contain all of our XUL, JavaScript, image, and CSS files. After we create this file, our file structure will look like the following:
+- TutToolbar/
+- install.rdf
+- chrome.manifest
+- chrome/
+- tuttoolbar.jar
+- content/
+- tuttoolbar.xul
+- tuttoolbar.js
+- skin/
+- combined.png
+- gripper.png
+- images.png
+- main.png
+- web.png
+- tuttoolbar.css
The biggest mistake that people make when packaging a JAR or XPI file is omitting the relative path names of the files. If we were to pretend that our JAR file was a folder, this is what its contents would look like when we were finished:
+- content/ +- tuttoolbar.xul +- tuttoolbar.js +- skin/ +- combined.png +- gripper.png +- images.png +- main.png +- web.png +- tuttoolbar.css
In other words, each individual file has to have an associated relative path name. Here is how I would create the JAR file for this tutorial using the UNIX zip tool:
I would first change to the chrome directory in my extension’s folder (in a command prompt window), then I would issue the following command:
zip -r tuttoolbar.jar content/* skin/*
Creating the XPI File
Now that we have a JAR file created, we need to create our XPI file. This is what you will actually distribute to the end-user. We should create this file in the top-level folder of our extension’s file structure. Once the file is created, our file structure will look like the following:
+- TutToolbar/
+- tuttoolbar.xpi
+- install.rdf
+- chrome.manifest
+- chrome/
+- tuttoolbar.jar
+- content/
+- tuttoolbar.xul
+- tuttoolbar.js
+- skin/
+- combined.png
+- gripper.png
+- images.png
+- main.png
+- web.png
+- tuttoolbar.css
Like the JAR file before it, the XPI must retain relative path information. We only need to include 3 files in our XPI file for this tutorial: the installer manifest, the chrome manifest, and the JAR file we created moments ago. Again, if we consider our XPI file to be a folder, this is what its contents would look like:
+- install.rdf +- chrome.manifest +- chrome/ +- tuttoolbar.jar
To create the XPI file using the UNIX zip tool, change to the top-level folder of your extension’s file hierarchy (the same folder where the installer and chrome manifests live), and use the following command:
zip tuttoolbar.xpi install.rdf chrome.manifest chrome/tuttoolbar.jar
Test Installing Your Extension
Now that we have an XPI file, we can test out the installation process. This is something you should always do before you release an extension to the public: make sure it installs! We must not use our development profile to do installation testing, since we already have an "installed" version of our extension in that profile. In either your normal Firefox profile, or in yet another test profile, take the following action to install your extension:
- Select the File » Open File… menu item (or press the Ctrl+O keyboard accelerator).
- In the file selection dialog, browse to the location of your XPI file, select it, and click the Open button.
If you’ve done everything correctly, the extension installer should appear. Tell it that you want to install, close Firefox when it’s finished installing, and start Firefox back up. Your toolbar should appear alongside all of the others. Congratulations on creating your first toolbar extension!
Speeding Up the Packaging Process
Packaging your extension by hand can quickly become tiresome. Why not write a script to do it? If you have a zip tool with a command line interface, you can easily automate the process. The following example shows a simple way to build our example toolbar using a DOS batch file and the UNIX zip tool.
First create two text files: one in the top level folder (named xpizip.txt), and one in the chrome folder (named jarzip.txt). Each text file is a simple listing of the items we want to include in each package: xpizip.txt lists the files to go in the XPI file, while jarzip.txt lists the files to go in the JAR file. Feel free to take a look at the following two example files: [View xpizip.txt] [View jarzip.txt]
Next, create a DOS batch file (in the extension’s top-level folder) which you can run from the command line. The code I used in the batch file is shown below:
cd chrome zip -r tuttoolbar.jar -@ < jarzip.txt cd .. zip -r tuttoolbar.xpi -@ < xpizip.txt
As you can see, this script is extremely simple. Your scripts can be much more complex than this, however. The Perl script I use to build Googlebar Lite does a number of things: it automatically updates all the version numbers for me, updates my chrome manifest, then packages the files. For the curious, I’ve provided the script for you to look at. [View the Googlebar Lite Build Script]
Ant Support
If you would rather use an Ant task to build your extension, take a look at the sample XML file sent in by Brett Clippingdale. The script should be placed in the same folder as the installer manifest, and can be run using the ant command.