Deploying XULRunner

Current XULRunner is a stable developer preview release. This means that while the release is immature in some areas such as embedding, application deployment, and OS integration, it can be used by developers that are releasing standalone XUL applications. This document explains how deployment should be managed for self contained portable applications built on XULRunner.

Note: To actually install a XULRunner application, a compatible version of XULRunner must be registered on the system and the app must be deployed per the instructions at XUL Application Packaging. If your installer is capable of determining whether or not XULRunner has been registered on the system you could perform the check and register the appropriate version if necessary. After that, the app could be installed to the registered XULRunner and appear in start menus, lists of installed programs, etc. (Bonus points for checking the operating system and downloading the right XULRunner on the fly, or bundling them into your installer). Registration and app installation are performed with command line switches as outlined in the XULRunner section of article Command Line Options.

It may turn out to be easier to create a self contained portable application, as described here, and deploy it with a generic installer that would create shortcuts to scripts that launch your application in the unregistered bundled XULRunner. The responsibility still lies with the developer to provide the correct version of XULRunner per platform. In the end, most users are afraid of links that don't have a pretty icon so you may want to have a look at the Branding section of XULRunner tips.

Windows

On Windows, XULRunner does not yet have a complete built-in installation solution; app developers should use pre-existing solutions for a native Windows installer. An example of one such solution may be found in the article: Creating a Windows Inno Setup installer for XULRunner applications. The installed files should be arranged in the following directory structure:

  • installdir/
    • application.ini
    • components/
      • ... components which are part of the application
    • chrome/
      • ... chrome which is part of the application
    • ... additional application files such as icons, etc
    • myapplicationname.exe (This is the "stub executable"... you should copy and rename this file from xulrunner-stub.exe in your XULRunner installation.)
    • xulrunner/
      • ... copy xulrunner/ to this directory

When deploying with XULRunner 2.0 and above do the following:

  • Move chrome.manifest to the root directory, and adjust resource paths inside chrome.manifest accordingly

  • With XULRunner 9.0 or 10.0 you may need to copy "mozutils.dll" and/or "mozcrt19.dll" from the xulrunner directory to the root directory. This should be fixed with XULRunner 11.0

  • With XULRunner 11.0 you may need to copy "gkmedias.dll" from the xulrunner directory to the root directory

Mac OS X

On Mac OS X, the exact layout of your application bundle depends on which version of XULRunner you're using.

XULRunner 39 and later

Due to Mac OS X code signing rules and how they interact with the design of XULRunner (see bug 1105044 for the inside scoop), starting with XULRunner 39 the XULRunner library files are no longer able to reside in a XULRunner framework directory. Instead, the library files are placed directly into the MacOS directory alongside the main executable file. Here's how the entire application bundle looks:

  • MyApp.app/
    • Contents/
      • Info.plist
      • PkgInfo
      • Resources/
        • application.ini
        • app_icon.icns
        • components/
          • ... components which are part of the application
        • chrome/
          • ... chrome which is part of the application
        • ... additional application files such as icons, etc
      • MacOS/
        • xulrunner (This is the "stub executable"... you should copy this file from /Library/Frameworks/XUL.framework/Versions/1.8/xulrunner.)
        • libmozglue.dylib (the main XUL library)
        • ... other executables and libraries

The core changes to XUL and Gecko that require this new file layout were implemented in Gecko 34, except that the XULRunner application was not updated to know about the change, so it will report an error: "Unable to load XPCOM." XULRunner was fixed in Gecko 39. See this blog post for additional background about this change.

XULRunner 38 and earlier

In XULRunner 38 and earlier, XULRunner is provided in a Mac OS X Framework bundle, which is placed in your application bundle's Frameworks directory. The complete bundle structure is as follows:

  • MyApp.app/
    • Contents/
      • Info.plist
      • PkgInfo
      • Frameworks/
        • XUL.framework/
          • files copied from /Library/Frameworks/XUL.framework/Versions/1.8/... make sure you copy all symlinks correctly (use rsync -rl /Library/Frameworks/XUL.framework ...).
      • Resources/
        • application.ini
        • app_icon.icns
        • components/
          • ... components which are part of the application
        • chrome/
          • ... chrome which is part of the application
        • ... additional application files such as icons, etc
      • MacOS/
        • xulrunner (This is the "stub executable"... you should copy this file from /Library/Frameworks/XUL.framework/Versions/1.8/xulrunner.)

When deploying with XULRunner 2.0, move chrome.manifest to the root directory, and adjust resource paths inside chrome.manifest accordingly. Additionally, your Mac app will not run without a valid Info.plist file. Here's a sample one:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleDevelopmentRegion</key>
	<string>English</string>
	<key>CFBundleExecutable</key>
	<string>xulrunner</string>
	<key>CFBundleGetInfoString</key>
	<string>1.0</string>
	<key>CFBundleIconFile</key>
	<string>app_icon.icns</string>
	<key>CFBundleIdentifier</key>
	<string>net.yourcompany.yourapplication</string>
	<key>CFBundleInfoDictionaryVersion</key>
	<string>6.0</string>
	<key>CFBundleName</key>
	<string>applicationName</string>
	<key>CFBundlePackageType</key>
	<string>APPL</string>
	<key>CFBundleShortVersionString</key>
	<string>1.0</string>
	<key>CFBundleSignature</key>
	<string>????</string>
        <!--only useful if your app handle urls-->
	<key>CFBundleURLTypes</key>
	<array>
		<dict>
			<key>CFBundleURLIconFile</key>
			<string>app_icon.icns</string>
			<key>CFBundleURLName</key>
			<string>YOURAPP Entity</string>
			<key>CFBundleURLSchemes</key>
			<array>
				<string>chrome</string>
			</array>
		</dict>
	</array>
	<key>CFBundleVersion</key>
	<string>1.0</string>
</dict>
</plist>

Here's a sample of the PkgInfo file

AAPL????

Edit this as you need to, but CFBundleExecutable MUST be xulrunner, and CFBundleIconFile and CFBundleURLIconFile should be set to the filename of your application icon (app_icon.icns).

Finally :

  • You can use any paint or graphics utility to create your application's icon, which should be provided as a 512 by 512 pixel PNG file.
  • To make it all work, change the permissions of your bundle by running chmod -R 755 YourApp.app.

Linux

Most Linux applications are distributed as simple .tar.bz2 archives which can be unpacked by the user wherever they wish. The archive should be structured as follows:

  • appname/
    • application.ini
    • components/
      • ... components which are part of the application
    • chrome/
      • ... chrome which is part of the application
    • ... additional application files such as icons, etc
    • myapplicationname (This is the "stub executable"... you should copy and rename this file from xulrunner-stub in your XULRunner installation.)
    • xulrunner/
      • ... copy xulrunner/ to this directory