XUL:XUL Application Packaging

The following is a proposal for how to package XUL applications targeted at XUL Runner.

(Currently, there is no code in the tree that supports this, nor are there examples in the tree that demonstrates the proposal completely.)

Package Structure

At the top level, a XUL Application package is a directory with the extension 'xulapp' containing the following items:

• application.ini - file - provides startup, configuration, and meta information for the application bundle
• chrome - directory - application chrome ( see Chrome Packaging )
• defaults - directory - contains default resources, such as preferences, for the application

To add an icon in the application window you must create, in the chrome, an "icons" folder and inside it a "default" folder. In that folder you can insert your icons with the same name of the "id" value of the window tag in xul page.

application.ini

This file follows the standard format for a Windows INI file. It should be saved with a UTF-8 encoding for I18N compatibility. It is currently defined as having two sections, App and Gecko. The fields for each section are explained in the sample below.

[App]
;
; This field specifies your organization's name.  This field is recommended,
; but optional.
Vendor=MyOrganization
;
; This field specifies your application's name.  This field is required.
Name=MyApplication
;
; This field specifies your application's version.  This field is optional.
Version=0.1
;
; This field specifies your application's build ID (timestamp).  This field is
; required.
BuildID=2005041816
;
; This field specifies a compact copyright notice for your application.  This
; field is optional.
Copyright=Copyright (c) 2005 MyOrganization
;
; This ID is just an example.  Every XUL app ought to have it's own unique ID.
; You can use the microsoft "guidgen" or "uuidgen" tools, or go on
; irc.mozilla.org and /msg botbot uuid.  This field is optional.
ID={3b2b4f0c-b8e1-4b13-89a6-b5d17523a7e1}

[Gecko]
;
; This field is required.  It specifies the minimum Gecko version that this
; application requires.  Specifying 1.8 matches all releases with a version
; prefixed by 1.8 (e.g., 1.8a4, 1.8b, 1.8.2).
MinVersion=1.8
;
; 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).
MaxVersion=1.8
[Shell]
;
; This field specifies the location of your application's main icon with file
; extension excluded.  NOTE: Unix style file separators are required.  This
; field is optional.
Icon=/chrome/icons/default/myapp-window

Launching a XUL Application

A XUL application is launched simply by passing the application package to XULRunner as a parameter on startup. The specifics of how this is done depends on your operating system:

From the command line

Windows

xulrunner.exe path_to_package/myapplication.xulapp

Unix

xulrunner path_to_package/myapplication.xulapp

Mac OS X

open -a Xulrunner.app path_to_package/myapplication.xulapp

From the desktop UI

Windows

A shortcut is created by the application installation process that points to XULRunner with the application package as the command line parameter.

Unix

TBD

Mac OS X

The structure of a XUL application package is complient with Apple's specification for document bundles. Mac OS X recognizes the XUL application package as a document bundle handled by XULRunner. Double clicking on the application package launches XULRunner with the application package as a document to be opened.

Shipping Applications

How does one package and ship apps? We will use a zip file as the distributable. See XUL:Installation Story for how this works with the install strategy for Windows users. On Mac or Unix, the "install" would consist of simply expanding the zip file automatically.

Implications of this proposal on XULRunner

• take folders, not ini files as the XULRunner file argument on startup

• Macs would tend to reuse the same process to load multiple applications - not the behavior desired for XULRunner. Rather than try to repackage chromes/extensions as executable bundles using a common lib (the GRE approach), we should have xulrunner act more as a launcher to effectively fork off a new process. (similar to how firefox behaves when loading new extensions on startup?)

Background information

Mac OS X factors that affect our strategy for application packaging and loading:

• Mac users expect drag-and-drop install of applications. The shipping "app" package must be ready to run after download and decompression. Also, embedding installers in the download process (active-x/xul helpers) is rather difficult to infeasible in the mac world, and requiring installers only hinders the ease of packaging and installation of software for an already small target audience.

• Mac applications must be loaded by Launch Services. This happens by actions that evoke app loading such as double-clicking on the app in the finder, double-clicking a document related to an app, or executing "open [app]" at the command line. If we want to pass a parameter to a properly launched app, we need to use a compatible way to do that (ODOC event posted to launched app).