Fresh off the release of Firefox 3.6.10 and 3.5.13, I was thinking about tools I could write to make releases smoother. I decided to make an update snippet viewer, as even catlee (of RelEng fame) said he would like such a tool. I would be able to stop bugging the RelEng folks for information about what snippets are live where, diff between them, look for builds that don’t get snippets offered, etc.

I decided to write it first as a web tool. I then changed my mind and decided on a command line tool in python. I thought about it yet some more and decided to make a graphical client with python and some sort of cross-platform widget toolkit. I then realized that this would be a great little project to learn the Mozilla platform and decided to base it on XUL and Gecko.

These are quick notes of my adventures.

First, I search for xulrunner on Google. I’m not sure if xulrunner is what I should be looking for, but I’ve read Planet Mozilla long enough that I figure it probably is. If not, it’s likely a good place to start.

The first link that comes up is That’s good, it’s on MDN. I read the text, which strikes me as pretty opaque for a newbie. I figure it’s ok as this is fairly technical stuff.

I click on the first tutorial. It talks about building or downloading xulrunner. I figure I’ll build as I already have all the Firefox trees checked out locally. I look at the build directions and OH MY GOD I am just going to install it.

So, I download and unzip the sdk. The sdk is a bunch of files (headers and such). WTF? I was promised an installer on the previous page! Whoops, it looks like I need the runtime, not the sdk. I download and install the runtime on my Mac via the installer easily. I (naively?) thought I was developing and would need the software development kit to, you know, develop. Hm.

Following along with, it gives me instructions for Windows. Ummm, ok, is it the same for Mac? Do I use ini files or plists? I have a Linux VM I could use instead, why are there no Linux instructions either? I start looking elsewhere for more info.

The getting started page says most info comes from an awesome tutorial at Whoops, the page content doesn’t load. Well, that’s embarrassing and not at all useful.

I go back to the main page and check out another tutorial link. That’s broken as well! I get the sinking feeling I have hit a deserted corner of the web and Mozilla platform. The dead link actually looks to be the same tutorial as above: A blog post from 2005? Yikes.

The next link in the main wiki page is It looks promising. I go to download the PDF and….parked domain link page. I check the wiki to see if some spammer changed links. Nope, it just looks like someone let the domain expire and the PDF is gone.

So I contemplate stopping at this point but decide to power through with the Windows instructions. I start creating the necessary directory structure. It’s tedious so I scroll down to see how much I have to do. Ah, there’s sample code to download! That would have been helpful at the top.

So now that I have a project, how do I run this thing on Mac OS X? The wiki is no help. I manage to dig up from the list of applications that use xulrunner and notice they have a command to use. Great success! I run the command.

Hmmmm, there’s no “Myapp” in the Application directory to launch as Crowbar’s directions implied there would be. I sort the Applications directory by mod time see there’s a new “Finkle” subdirectory.

Finkle is Einhorn?

Finkle is Einhorn?

Ummm, what? Whatever, I roll with it. I double click the “Myapp” application in the Finkle directory. I get an application with no icon and no window that quits immediately:

 "Could not find compatible GRE between version 1.8 and 1.9.0.*".

Ok…..time to look in the sample project. I crack open the ini to see if I can solve the issue. Ah, that’s where Finkle came from:


Lots of Mark Finkle stuff in there. Uhhh, I appreciate the work Mark, but I was expecting a more general “Hello World” project 😉

I read further down, O HAI!

; This field is optional.  It specifies the maximum Gecko version that this
; application requires.  It should be specified if your application uses
; unfrozen interfaces.  Specifying 1.8 matches all releases with a version
; prefixed by 1.8 (e.g., 1.8a4, 1.8b, 1.8.2).

I am versed enough in Gecko version numbers to know that these are old as dirtâ„¢. Others may not be as lucky, but I imagine they could figure it out by the error message. I know I am running (which is the most recent, I just released .10 tonight and xulrunner builds come a bit later) so this is likely my problem. I yank out MaxVersion and re-run:

/Library/Frameworks/XUL.framework/xulrunner-bin --install-app myapp

I launch the app in /Applications/Finkle and get the same issue.

Ruh Roh

Ruh Roh!

I have no clue how to fix the issue if it isn’t caused by those versions! I glance at the application’s timestamp and notice it’s 10 minutes in the past. WTF, I thought the command above writes the app? It worked the first time at least. I manually delete the Finkle directory and run the above command again.

Great Success!

Take THAT xulrunner!

That worked! Take THAT xulrunner indeed! Interestingly, the launch seemed to crash and then restart–there was a flicker of the window and icon shuffling in the dock. Well it works at least and I can’t reproduce the issue on subsequent launches.

Ok, where to next? I head back to the main xulrunner wiki page. The next 2 links don’t give any info. Uhhh, ok, I guess I’ll look at tips even though I am pretty sure I need more than tips at this point. The tips wiki page looks to have some good info (especially about branding) but I am not at the point in my app where I can use any of them.

I decide to poke around in the sample “Myapp”. Nothing really there, darn. Most files don’t even have helpful comments to guide me where to play around or add/extend. And then I come across main.js. Woahhhhhh, main.js looks super complicated for this hello world app! Oh, it looks like it’s from FF? Why is it in here? Mark, what’s going on here? 🙂

At this point I decide that I’m probably on to normal XUL now and should start looking for general platform documentation. I decide I am way too tired to work on this and put it away for later.

Tagged with:  

9 Responses to A newbie’s adventure with xulrunner

  1. Alex Vincent says:

    You’re not going to like hearing about this… but:

    Firefox supports a command line argument, -app, for launching XULRunner applications:

  2. pdp says:

    xulrunner is pain but once you have some experience with it you will realise it is a very powerful platform. I cannot point you to any good tutorials but you can definitely check the following project: for some inspiration and insights. This project is packed with patterns, tips, tricks and techniques you may need to create powerful apps in xul.

    Good luck! 🙂

  3. Colby Russell says:

    Mozilla is not a platform company. By that token, these kind of “I’m in the user’s shoes” walkthroughs that go into detail are kind of likely to go nowhere.

    There are gaps in the XULRunner documentation. XULRunner is not friendly. It’s troublesome to get up and running from scratch. These are things which are obvious. The lack of congruity between your expectations and Mozilla’s direction renders these things moot, though.

  4. This kind of thing is why I’ve limited my Firefox extension endeavours to what can be done in Greasemonkey. I’m getting pretty good at figuring out designs which give acceptable interfaces within the limits of what can be ported between all the different userscript engines out there. (eg. using CORS for cross-domain XHR)

    I’m hoping Jetpack SDK will simplify traditional Firefox extension development enough for me to experiment with something like cooking up a custom bookmarking handler (or failing that, just adding a new page action, as Chrome’s well-reasoned term calls them).

    [WORDPRESS HASHCASH] The poster sent us ‘0 which is not a hashcash value.

  5. We’re pretty bad at XULRunner getting-started experience and documentation, that’s for sure, and I’d be one of the first people to cheer for improvements there.

    That said,;a=summary might give you a better example of how-to-do a XULRunner app. This is not “Hello world” but also somewhat bigger, but not really that large, and it’s well-structured. The “mandelbrot” shell script in the main directory is hacky but should give you a good impression of how to launch the app – and as of a few moths ago, there is code in that repo to make this work as both a FF add-on and a XULRunner app…

    In any case, the experience for XULRunner isn’t really good, because all Mozilla work is focused on certain end-user apps rather than the dev platform. I hope that corner will become less dusty one time, but I’m not that sure about it any more…

  6. Mark Finkle says:

    I cried, I laughed, I cried.

    It’s been a while since I updated any of the documentation on MDC/MDN. Recent changes to the way XPCOM components are registered also requires changes to the documentation.

    Lastly, main.js looks like it should have been removed before uploading. It comes from a different example project – one that shows a simple web browser.

  7. Mark Finkle says:

    I updated, hopefully addressing most of the problems you encountered. There are more parts to the tutorial, see the “Next >>” link at the bottom of the page.

    The is info on branding, but it’s mixed in with other information on a XULRunner Tips page. We could pull it out into it’s own page.

    Look at the MDC XUL Tutorial now that you have a basic application started:

    The XUL Tutorial has tons of information on using XUL. There are also separate guides to using Popup panels and Templates:

  8. pd says:

    unfortunately this experience is all too familiar to me. So is the half-arsed response from the likes of Colby Russell.

    Mozilla has what seems to be a very useful cross-platform open source desktop application development platform. Why not make use of it? How much effort would it really take to pay a couple of people to document xulrunner completely and make themselves available for support and help? Probably not much.

    However Mozilla’s vision extends only to the web. Facilitating better desktop apps is not on their agenda.

    Mark Finkle was doing a lot of good things for XUL but it seems they stole his time and applied it to other things, perhaps Fennec.

    With the Jetpack SDK planned to offer developer the ability to code an app or an extension, there may be some hope though.

    [WORDPRESS HASHCASH] The poster sent us ‘0 which is not a hashcash value.

  9. Jason Oster says:

    I am always pointing XULRunner newbies to my wiki which contains some very relevant newbie XULRunner information, and links to various [and very helpful] resources:

    Come to think of it, maybe I should add these links to MDN?

    Good luck!