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 fromxulrunner-stub.exe
in your XULRunner installation.)xulrunner/
- ... copy
xulrunner/
to this directory
- ... copy
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 (usersync -rl /Library/Frameworks/XUL.framework ...
).
- files copied from
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 fromxulrunner-stub
in your XULRunner installation.)xulrunner/
- ... copy
xulrunner/
to this directory
- ... copy