Burning Chrome

Where are the good chrome dev examples?

I spent a big part of today trying to fix a bug in xpistubs, with regard to flat chrome. I went through the XPInstall API docs for hours today, trying to figure out what the hell I was doing wrong. Hours. The code examples are sparse. It's not clear to the untrained eye which arguments refer to content inside a XPI (or JAR), and which arguments refer to the target applications. A few visual examples would have saved me a lot of trouble. Example:

Suppose this is the contents of your XPI file:

content
- foo.xul

This is the contents of your target chrome directory:

chrome
- browser.jar

To copy and register the content directory into chrome/content/foo, use the following:

Install.setPackageFolder(Install.getFolder("Chrome"));
var targetDir = Install.getFolder("Chrome", "foo");
File.dirCreate(targetDir);

addDirectory(null,        "content",      targetDir, "content/");
registerChrome(CONTENT | DELAYED_CHROME, targetDir, "content/")

Note the second argument does not have a trailing slash, but the fourth argument does.

I've never seen anything like this level of detail in any XPI guide, not even "Creating Applications With Mozilla". This sort of example is short, very self-contained (you don't need to read prior chapters), and can be inserted into the addDirectory API documentation without any trouble. (Even then, it's not entirely a good example. Which "content" argument is which?)

There's another reason I wrote the example above as I did. It's not jarred chrome, it's flat. Flat chrome is useful. Flat chrome means you can edit the files raw in your objdir, and when you're done, you just copy the files into your source dir. No dealing with jars at all.

Jar files are great for finished products. But when you're doing dev work, you want to play with flat chrome. Ideally, you want to keep all your files isolated so that things are relatively obvious. If you can build jar, you can build flat, and vice versa. Mozilla reacts happily to both.

We have a serious lack of good chrome examples, flat and jarred. Oh, I could dig through the archives of mozilla.org and eventually find a bunch of XPI packages. But it's not clear to me as a developer what's inside these things, and what makes them tick. These tests would be a lot more useful if there was a guide to them. "This is what that XPI is supposed to do. This is what each XPI has inside it. This is what the install.js file looks like. This is what each line does."

Every time I try to start a new project, I go through this hassle. Every time I start playing with XPInstall, I go through this hassle. It's insane. I know I could (and probably should, given how frustrated I am) write a nice bunch of addendums to current XPInstall docs. Is that what will solve the problem? Or can I wake someone up and say, "Have you ever tried to use these docs to actually do something?"

Posted by WeirdAl at November 26, 2005 5:43 PM