Mozilla Platform – Getting Started with XULRunner

I want to build a simple XUL-based Windows desktop application. If you’re going to build a XUL-based desktop application, you’ll probably need to install XULRunner. In this post, I try to get XULRunner installed and make sure it runs a bare-bones application.

Step 1 – Download XULRunner: The Mozilla developer page lists 1.8.0.1 as the most recent release, but I see there is also a 1.8.0.4, so that is the one I downloaded. UPDATE: 1.8.0.4 release and SDK are available from Mozilla FTP.

The XULRunner download is a ZIP file, not a true install. As a developer, I like the idea that XULRunner only needs to be unzipped onto my machine. I am assuming that it doesn’t need to hook into my Windows system and that’s a good thing.

Step 2 – Install XULRunner: I unzipped the archive to a new “c:\program files\xulrunner” folder. Pretty simple so far.

Time to start a simple, bare bones application shell. Call it a XUL “Hello World” if you want, but I need to make sure that XULRunner will work at all. Googling turned up a nice tutorial here. It is definately worth reading. Using the tutorial, I created a simple bootstrap application. All of what you see below can be found in Ryan’s tutorial and the Mozilla XULRunner documentation pages.

Step 3 – Create application folder struture: I create the root in a new “c:\program files\xulapp” folder. Here is the subfolder structure:

/xulapp
  /chrome
    /content
      main.xul
    chrome.manifest
  /defaults
    /preferences
      prefs.js
  application.ini

Notice that there are 4 files in the folder structure: application.ini, chrome.manifest, prefs.js & main.xul

Step 4 – Setup application.ini: The application.ini file acts as the XULRunner entry point for your application. It seems to be used to configure how your application intends to use the XULRunner platform as well as configure some information that XULRunner uses to run your application. Here is mine:

[App]
Vendor=Finkle
Name=Test App
Version=1.0
BuildID=20060101
Copyright=Copyright (c) 2006 Mark Finkle
ID=xulapp@starkravingfinkle.org

[Gecko]
MinVersion=1.8
MaxVersion=1.8

Step 5 – Setup Chrome Manifest: The chrome manifest file is used by XULRunner to define specific URI’s which in turn are used to locate application resources. This will become clearer when we see how the “chrome://” URI is used. Applications can be distributed compressed in a JAR file or uncompressed as folders and files. I am using the uncompressed method for now. Here is my manifest:

content myapp file:content/

Step 6 – Setup Preferences: The prefs.js files is used to tell XULRunner the name of the XUL file to use as the main window. Here is mine:

pref("toolkit.defaultChromeURI", "chrome://myapp/content/main.xul");

XULRunner preferences include:

• toolkit.defaultChromeURI
• toolkit.defaultChromeFeatures
• toolkit.singletonWindowType

Step 7 – Create some XUL: Finally, we need to create a simple XUL window. Nothing fancy here, just the minimum we need to make a window. No menus or anything:

Step 8 – Run the App: The moment of truth. We need to get XULRunner to launch the bare-bones application. From a command prompt opened to the “c:\program files\myapp” folder, we should be able to execute this:

xulrunner.exe application.ini

Of course, xulrunner.exe must be in the PATH. Because of where I unzipped XULRunner, I could also try this if xulrunner.exe is not in the PATH:

..\xulrunner\xulrunner.exe application.ini

Success! Here is a screenshot of the bare bones application running on Win2K:

My next step will be to add much more to the bare bones application. I want to explore as much of XUL as I can as fast as I can. For those that want to skip straight to the end, here is a ZIP of the My App application:

My App sample