View source for XUL:XUL Application Packaging

<table style="float: right; border: 1px solid #999;">
<tr><td>
* [[XUL:Home Page]]
{{XUL:XUL_Runner_TOC}}
</table>

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:

* <tt>application.ini</tt> - file - provides startup, configuration, and meta information for the application bundle
* <tt>chrome</tt> - directory - application chrome ( see [http://www.mozilla.org/xpfe/ConfigChromeSpec.html Chrome Packaging] )
* <tt>defaults</tt> - 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, <tt>App</tt> and <tt>Gecko</tt>.  The fields for each section are explained in the sample below.

<div class="example" title="application.ini - xulapp package information">
<pre class="code">
[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

</pre>
</div>

== 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'''

<tt>xulrunner.exe path_to_package/myapplication.xulapp</tt>

'''Unix'''

<tt>xulrunner path_to_package/myapplication.xulapp</tt>

'''Mac OS X'''

<tt>open -a Xulrunner.app path_to_package/myapplication.xulapp</tt>

=== 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 [http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/Concepts/DocumentBundles.html 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).