Custom app bundles for Mac OS X

This page is not complete.

Mac OS X applications are typically packaged as application bundles which are then distributed in .dmg (disk image) files. This tutorial will show you how to package your XULRunner-based application in a way which is consistent with the expectations of Mac OS X users.

Application bundle layout

Application bundles are essentially just directory structures that conform to a standard layout and naming convention. A XUL application for Mac OS X should follow something similar to this basic directory structure:

    • Contents/
      • Info.plist   (Application bundle properties are specified in this XML file.)
      • PkgInfo   (This is a simple text file and is created along with the Info.plist file)
      • MacOS/   (The MacOS folder will contain your XULRunner executable)
      • Resources/   (This is where you place your XUL Application code and support files)
        • application.ini   (XULRunner-related application settings)
        • example.icns   (This is the icon which will be used by your application bundle)
        • chrome/
          • content/
            • example.xul   (This directory contains your application's chrome)
          • example.manifest
        • defaults/
          • preferences/
            • app-prefs.js   (This provides some default values for preferences)

Application bundle contents

In addition to the standard directory hierarchy that's required of all Mac OS X applications, as shown above in Application bundle layout, there are some specific rules for what content goes where:

  • The top-level directory is given a name that ends with .app which designates the whole package as an application bundle.
  • The first sub-directory is called Contents and within that directory you will place several files and folders that are needed by your application bundle.
  • Info.plist and PkgInfo must exist in the Contents directory. The content of these files is covered in the article Deploying XULRunner 1.8.


These example files are taken from a port of WebRunner which was created to illustrate one method of Mac OS X application packaging.

See also