Recently, I decided to convert my Bugzilla Tweaks jetpack to an extension based on the Jetpack SDK, which is still under development. This post is meant to be a document of my experience with the Jetpack SDK for creating a real-world and useful extension for Firefox.
As the very first step, I needed to actually get the SDK set up and running. So, I went straight to the Getting Started guide. Here is how I set it up. I cloned the hg repository (to make sure that the process of updaring my extension to future versions of the Jetpack SDK is as easy as just updating the repo and rebuilding the extension). At this point, you can make a choice. You may either want to stay on tip, or update to a release version (which may be a little more stable than tip – but remember that the Jetpack SDK is still under development). I chose to update to 0.4, which is the latest released version as of this writing.
Then, I went ahead with . bin/activate and cfx testall, to make sure that I've get a working environment up and running. I sat there and watched the command prompt waiting for the tests to be completed, but I got tired and pressed Ctrl+C to cancel the operation after about 5 minutes. Then, I decided to run cfx testall –verbose to see what's happening, but again, it just went yoohoo after running some tests. I canceled again and decided to just assume that everything is working correctly, for lack of a better way to actually verify that.
Then I proceeded to read the Packages documentation. I skimmed over it, and then proceeded to the Programs documentation. That seemed to be interesting, so I read that more thoroughly. It all seemed easy enough. The only strange part was that I seemed to have to create my packages under the Jetpack SDK directory. That seems less than ideal to me, but I decided to try to create a real directory for my extension somewhere, and just add a symlink to it under the packages directory. That worked, which was nice.
After this point, I just copied the old bugzilla-tweaks.js file as lib/main.js, and started to figure out how to make the extension do something useful. Before anything else, I'd need something equivalent to the Jetpack Prototype's pageMods facility. So, I grabbed Atul's persistent-page-mods.js module, and started looking at it (he'd pointed me to it here). Soon I figured out that I needed to have the dependencies of this package available as well. I searched for “require” in that file, and found out that it depends on timer, errors and unload-2. The only one not available in jetpack-core was the latter, so I grabbed it as well. unload-2 itself didn't have any dependencies besides unload, which ships in jetpack-core, so the dependency search was done. One thing that I wish we had was a tool to recursively extract the dependencies from any given package. Atul also told me that I needed the tab-browser package, but I noticed that it's there in 0.4.
Then I stole this code to get the pageMods functionality hooked up. This far into the process, I'm loving how easy it is to use other people's packages and code in your new Jetpacks. I think that's going to blow away how people write extensions for Firefox and other Mozilla-based applications.
For the most part, the Bugzilla Tweaks jetpack is a bunch of DOM API calls, and I expected those parts to just work. I only needed to port my Jetpack Prototype API usage over to Jetpack SDK APIs. In addition to pageMods, I used jetpack.menu to add context menu items, and jetpack.clipboard to modify the clipboard.
The context-menu API documentation was straightforward, and I ported my usage of the jetpack.menu API to context-menu very quickly. Porting jetpack.clipboard was a bit more involved, though, because jetpack-core does not include a clipboard module yet, so I had to write my own.
I decided to go with the JEP specification of the clipboard API, which has not been implemented yet. This is a relatively simple API, providing three methods: get, set and getCurrentFlavors. For this extension, I only needed the set method, so that's what I implemented for now.
I also had two direct XPCOM call sites in my original Jetpack, one for reading a preference, and the other for reading a cookie. Jetpack SDK comes with a preferences-service package, so I decided to use it. I also created a small cookiemanager package and switched to using it. The benefit of this is that if in the future, the Jetpack SDK does not allow direct usage of XPCOM components, I can just modify one package. Also, I can use the package in my other projects, and so can others!
Now was the time to try the extension for the first time! Before generating the XPI, I added a few more fields to the package.json manifest, and then I ran cfx xpi. It told me that I needed to remove the id field from the manifest, which I did. The next time I ran cfx xpi, it told me that the manifest is updated, and I need to run the cfx xpi again. This was kind of strange, and less than ideal (why didn't the tool do what's needed on its own?). Anyway, I re-ran cfx xpi, and finally I had an XPI, waiting to be tested.
But before testing, I was curious to see for myself what the generated XPI contains. So, I unzipped the package, and started looking around. The generated install.rdf contained entries for Firefox, Fennec and Thunderbird. I found that strange. I was never asked which applications this extension is compatible with. I'm pretty sure that it won't be compatible with Thunderbird, and I don't even know what will happen if I try to install the XPI on Fennec. And if the goal is for the extension to be compatible on all Mozilla-based applications, it should be a toolkit extension, right?
I also noticed that the install.rdf contains a bootstrap element, which means that the extension can be installed without Firefox being restarted if you use a trunk version. Nifty!
Then, there was the resources directory, which contained a copy of all the Jetpack packages, both in bugzillatweaks, and in jetpack-core. What I found really broken was that .main.js.swp, which is the Vim swap file which was around because I had main.js open in Vim made its way to the XPI package. Not so nice.
There was also a components directory, containing a harness.js file, which I didn't look at very carefully.
So, I went ahead and opened up a development profile that I had set up to develop and test the old version of the jetpack in Firefox 3.6. I disabled the original jetpack, dropped the XPI into Firefox, and restarted. Lo, and behold! I had my extension installed, but it didn't work! There was no error logged to the error console, and no possible way to tell what was going wrong. I felt clueless as how to proceed. I decided that having Jetpack Prototype installed might be conflicting with something, so I disabled that extension and restarted. Still no luck.
So, I went ahead and added a bunch of console.log calls in the beginning of the main function, to see if it's called, but apparently it wasn't. I decided to give things a shot with a nightly. So, I launched a nightly Firefox from the console, and boy was I lucky to have done that! I got this error on the console (that is, the OS X Terminal application):
error: An exception occurred.
Traceback (most recent call last):
File "resource://jid0-qbniplfdfa4lpdrjhac6vbqn20q-bugzillatweaks-lib/main.js", line 340, in null
});
SyntaxError: syntax error
OK, that explains a lot. But I found this out completely out of luck. The SDK really needs to expose such errors in a more discoverable way.
So, I went ahead and fixed the syntax error, re-generated the XPI, and opened it in Firefox. Because it's a rebootless add-on, it didn't require the browser to restart, and I got “info: main” on the console (again, the OS X Terminal application), which was the debugging message I had added to my main function, so the jetpack was correctly loaded! 
But apparently I have to watch the Terminal window instead of Firefox's error console, which sucks.
From there on, I spent some time debugging using console.log calls, and finally I managed to have a working Jetpack.
The entire process was rather pleasant. I hit a few bumps along the road, as I explained above, but hopefully others will read this post and know how to avoid them while the amazing guys in the Jetpack SDK team fix those issues.