Getting started with XULRunner

  • Revision slug: Getting_started_with_XULRunner
  • Revision title: Getting started with XULRunner
  • Revision id: 350979
  • Created:
  • Creator: Kastor
  • Is current revision? No
  • Comment

Revision Content

{{ Next("Windows and menus in XULRunner") }}

This article explores the Mozilla platform by building a basic desktop application using XULRunner. Given that Firefox, Thunderbird, and multiple other applications are written using the platform, it's a safe bet that it can be used to build a basic application. There is an article with a slightly different approach to building XULRunner at Creating XULRunner Apps with the Mozilla Build System.

If you’re going to build a XUL-based desktop application, you’ll probably need to install XULRunner. Let's start by installing XULRunner and making sure it runs a bare-bones application.

Step 1: Download XULRunner

You can find a download link on the main XULRunner page here on MDC. Since we are not creating any binary XPCOM components, we only need to download and install the XULRunner runtime package.

The XULRunner download for Windows is a zip file, not a true install. As a developer, I like the idea that XULRunner only needs to be unzipped onto my machine. I am assuming that it doesn’t need to hook into my Windows system and that’s a good thing.

The Mac version of XULRunner is distributed as a standard Mac OS X installer.

In Ubuntu desktop and Xubuntu, XULRunner is already installed by default. For Kubuntu, run the follwing command

sudo apt-get install xulrunner

to install it. If you intend to use a pre-release version of XULRunner, you might need to download the archive and unpack it, but you can download it and install in the same way of windows, just download and unzip the file.

Step 2: Install XULRunner

On Windows, unzip the archive someplace reasonable. I unzipped it to a new C:\program files\xulrunner folder.

On the Mac, just run the installer, which installs XULRunner as XUL.Framework in the /Library/Frameworks directory.

On Linux, you only need to unpack the archive if you are using a pre-release XULRunner.

 

In all systems you have to unzip the omni.ja to create the folder structure below.

Step 3: Create the application folder structure

Time to start a simple, bare bones application shell. Call it a XUL “Hello World” if you want. All of what you see below can be found in the XULRunner documentation here on MDC,

Hint: You can download the sample application from the Files section at the bottom of this article. Please continue reading to learn the "what", "why" and "how" parts of building a XULRunner application.

On Windows, I created the root in a new c:\program files\myapp folder, but you can create it wherever you like, using whatever OS you like. The same application structure is used on Windows, Mac and Linux. The differences start to appear when we get to running the application. Here is the subfolder structure:

+ myapp/
|
+-+ chrome/
| |
| +-+ content/
| | |
| | +-- main.xul
| | |
| | +-- main.js
| |
| +-- chrome.manifest
|
+-+ defaults/
| |
| +-+ preferences/
|   |
|   +-- prefs.js
|
+-- application.ini
|
+-- chrome.manifest 

Notice that there are 5 files in the folder structure: application.ini, chrome.manifest (2), prefs.js, and main.xul. The /chrome/chrome.manifest file is optional, but might be useful for backward compatibility. See the note.

Note: In XULRunner 2.0, the chrome.manifest is now used to register XPCOM components in addition to its previous uses. Part of this change means the /chrome/chrome.manifest is no longer considered the "root" manifest. XULRunner will not check that folder location for a root-level chrome.manifest. You need to move your existing chrome.manifest to the application root folder, remembering to update the relative paths within the file. You could also just create a new application root-level manifest that includes the /chrome/chrome.manifest, which is what this tutorial will do.

Step 4: Set up application.ini

The application.ini file acts as the XULRunner entry point for your application. It specifies how your application intends to use the XULRunner platform as well as configure some information that XULRunner uses to run your application. Here is mine:

[App]
Vendor=XULTest
Name=myapp
Version=1.0
BuildID=20100901
ID=xulapp@xultest.org

[Gecko]
MinVersion=1.8
MaxVersion=2.*
Note: The MinVersion and MaxVersion fields indicate the range of Gecko versions your application is compatible with; make sure that you set them so that the version of XULRunner you're using is in that range, or your application won't work.

Step 5: Set up the chrome manifest

The chrome manifest file is used by XULRunner to define specific URIs which in turn are used to locate application resources. This will become clearer when we see how the “chrome://” URI is used. Application chrome can be in a single or a few JAR files or uncompressed as folders and files. I am using the uncompressed method for now. Here is the chrome/chrome.manifest:

 content myapp content/
Note: Make sure your application name is lowercase and longer than 3 characters

As mentioned in Step 3, the default location of the chrome.manifest has changed in XULRunner 2.0, so we also need a simple chrome.manifest in the application root which will include the the manifest in our chrome root. Here is the root chrome.manifest:

manifest chrome/chrome.manifest

Step 6: Set up preferences

The prefs.js file tells XULRunner the name of the XUL file to use as the main window. Here is mine:

 pref("toolkit.defaultChromeURI", "chrome://myapp/content/main.xul");

XULRunner preferences include:

toolkit.defaultChromeURI
Specifies the default window to open when the application is launched.
toolkit.defaultChromeFeatures
Specifies the features passed to window.open() when the main application window is opened.
toolkit.singletonWindowType
Allows configuring the application to allow only one instance at a time.

This is described in further detail in XULRunner:Specifying Startup Chrome Window.

Step 7: Create some XUL

Finally, we need to create a simple XUL window, which is described in the file main.xul. Nothing fancy here, just the minimum we need to make a window. No menus or anything.

main.xul:

<?xml version="1.0"?>

<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

<window id="main" title="My App" width="300" height="300" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

  <script type="application/javascript" src="chrome://myapp/content/main.js"/>

  <caption label="Hello World"/>
  <separator/>
  <button label="More >>" oncommand="showMore();"/>
  <separator/>
  <description id="more-text" hidden="true">This is a simple XULRunner application. XUL is simple to use and quite powerful and can even be used on mobile devices.</description>

</window>
Note: Make sure there is no extra whitespace at the beginning of the XML/XUL file

The application also has a JavaScript file. Most XUL applications will include some external JavaScript, so the sample application does too, just to show how to include it into the XUL file.

main.js:

function showMore() {
  document.getElementById("more-text").hidden = false;
}

Hint: You can download the sample application from the Files section at the bottom of this article.

Step 8: Run the application

The moment of truth. We need to get XULRunner to launch the bare-bones application.

Windows

From a Windows command prompt opened to the C:\program files\myapp folder, we should be able to execute this:

 xulrunner.exe application.ini

Of course, xulrunner.exe must be in the PATH. Because of where I unzipped XULRunner, I could also try this if xulrunner.exe is not in the PATH:

 ..\xulrunner\xulrunner.exe application.ini

Mac

On the Mac, before you can run a XULRunner application with everything intact, you must install it using the --install-app xulrunner commandline flag. Installing the application creates an OS X application bundle:

 /Library/Frameworks/XUL.framework/xulrunner-bin --install-app /<path>/<to>/myapp.zip

Once installed, you can run the application:

 /Library/Frameworks/XUL.framework/xulrunner-bin "/Applications/Finkle/TestApp.app/Contents/Resources/application.ini"

You may run it without installing (but with the menu bar and dock icon missing) in OS X by typing:

/Library/Frameworks/XUL.framework/xulrunner-bin "/<full path>/TestApp/application.ini"

Note: The full path is required or a "Error: couldn't parse application.ini."-message will be returned.

This might also be simplified using a very simple shell script (i call mine "run.sh"):

#!/bin/sh
/Library/Frameworks/XUL.framework/xulrunner-bin `pwd`/application.ini 

Linux

On Ubuntu, you can run the application from a terminal. First change into the \myapp folder, then start the application by:

 xulrunner application.ini

You should now see a window that looks something like this. This particular screenshot is from Ubuntu 10.

myapp-screenshot.png

Alternative: Use Firefox3 -app to run XUL apps

With Firefox 3, you can tell the firefox executable to run a XUL application from the command line, instead of the Firefox browser that normally starts. This is similar to starting a XUL app using XULRunner. See Using Firefox 3 to run XULRunner applications. This does not work if Firefox itself was installed as a XUL app - you need to use the installed XULRunner directly.

{{ Next("Windows and menus in XULRunner") }}

Original Document Information

  • Author: Mark Finkle
  • Last Updated Date: October 2, 2006

{{ languages( { "ja": "ja/Getting_started_with_XULRunner", "ko": "ko/Getting_started_with_XULRunner" } ) }}

Revision Source

<p>{{ Next("Windows and menus in XULRunner") }}</p>
<p>This article explores the Mozilla platform by building a basic desktop application using <a href="/en/XULRunner" title="en/XULRunner">XULRunner</a>. Given that Firefox, Thunderbird, and multiple other applications are written using the platform, it's a safe bet that it can be used to build a basic application. There is an article with a slightly different approach to building XULRunner at <a href="/en/Creating_XULRunner_Apps_with_the_Mozilla_Build_System" title="en/Creating_XULRunner_Apps_with_the_Mozilla_Build_System">Creating XULRunner Apps with the Mozilla Build System</a>.</p>
<p>If you’re going to build a XUL-based desktop application, you’ll probably need to install XULRunner. Let's start by installing XULRunner and making sure it runs a bare-bones application.</p>
<h2 id="Step_1:_Download_XULRunner" name="Step_1:_Download_XULRunner">Step 1: Download XULRunner</h2>
<p>You can find a download link on the main <a href="/en/XULRunner" title="en/XULRunner">XULRunner</a> page here on MDC. Since we are not creating any binary XPCOM components, we only need to download and install the XULRunner runtime package.</p>
<p>The XULRunner download for Windows is a zip file, not a true install. As a developer, I like the idea that XULRunner only needs to be unzipped onto my machine. I am assuming that it doesn’t need to hook into my Windows system and that’s a good thing.</p>
<p>The Mac version of XULRunner is distributed as a standard Mac OS X installer.</p>
<p>In Ubuntu desktop and Xubuntu, XULRunner is already installed by default. For Kubuntu, run the follwing command</p>
<p><code>sudo apt-get install xulrunner</code></p>
<p>to install it. If you intend to use a pre-release version of XULRunner, you might need to download the archive and unpack it, but you can download it and install in the same way of windows, just download and unzip the file.</p>
<h2 id="Step_2:__Install_XULRunner" name="Step_2:__Install_XULRunner">Step 2: Install XULRunner</h2>
<p>On Windows, unzip the archive someplace reasonable. I unzipped it to a new <code>C:\program files\xulrunner</code> folder.</p>
<p>On the Mac, just run the installer, which installs XULRunner as <code>XUL.Framework</code> in the <code>/Library/Frameworks</code> directory.</p>
<p>On Linux, you only need to unpack the archive if you are using a pre-release XULRunner.</p>
<p>&nbsp;</p>
<p>In all systems you have to unzip the omni.ja to create the folder structure below.</p>
<h2 id="Step_3:_Create_the_application_folder_structure" name="Step_3:_Create_the_application_folder_structure">Step 3: Create the application folder structure</h2>
<p>Time to start a simple, bare bones application shell. Call it a XUL “Hello World” if you want. All of what you see below can be found in the <a href="/en/XULRunner" title="en/XULRunner">XULRunner</a> documentation here on MDC,</p>
<p><strong>Hint:</strong> You can download the sample application from the Files section at the bottom of this article. Please continue reading to learn the "what", "why" and "how" parts of building a XULRunner application.</p>
<p>On Windows, I created the root in a new <code>c:\program files\myapp</code> folder, but you can create it wherever you like, using whatever OS you like. The same application structure is used on Windows, Mac and Linux. The differences start to appear when we get to running the application. Here is the subfolder structure:</p>
<pre>
+ myapp/
|
+-+ chrome/
| |
| +-+ content/
| | |
| | +-- main.xul
| | |
| | +-- main.js
| |
| +-- chrome.manifest
|
+-+ defaults/
| |
| +-+ preferences/
|   |
|   +-- prefs.js
|
+-- application.ini
|
+-- chrome.manifest 
</pre>
<p>Notice that there are 5 files in the folder structure: <code>application.ini</code>, <code>chrome.manifest (2)</code>, <code>prefs.js</code>, and <code>main.xul</code>. The <code>/chrome/chrome.manifest</code> file is optional, but might be useful for backward compatibility. See the note.</p>
<div class="note">
  <strong>Note:</strong> In XULRunner 2.0, the chrome.manifest is now used to register XPCOM components in addition to its previous uses. Part of this change means the <code>/chrome/chrome.manifest</code> is no longer considered the "root" manifest. XULRunner will not check that folder location for a root-level <code>chrome.manifest</code>. You need to move your existing chrome.manifest to the application root folder, remembering to update the relative paths within the file. You could also just create a new application root-level manifest that includes the <code>/chrome/chrome.manifest</code>, which is what this tutorial will do.</div>
<h2 id="Step_4:_Set_up_application.ini" name="Step_4:_Set_up_application.ini">Step 4: <code>Set up application.ini</code></h2>
<p>The <code><a href="/en/XUL_Application_Packaging" title="en/XUL_Application_Packaging">application.ini</a></code> file acts as the XULRunner entry point for your application. It specifies how your application intends to use the XULRunner platform as well as configure some information that XULRunner uses to run your application. Here is mine:</p>
<pre>
[App]
Vendor=XULTest
Name=myapp
Version=1.0
BuildID=20100901
ID=xulapp@xultest.org

[Gecko]
MinVersion=1.8
MaxVersion=2.*
</pre>
<div class="note">
  <strong>Note:</strong> The <code>MinVersion</code> and <code>MaxVersion</code> fields indicate the range of Gecko versions your application is compatible with; make sure that you set them so that the version of XULRunner you're using is in that range, or your application won't work.</div>
<h2 id="Step_5:_Set_up_the_chrome_manifest" name="Step_5:_Set_up_the_chrome_manifest">Step 5: Set up the chrome manifest</h2>
<p>The <a href="/en/Chrome_Registration" title="en/Chrome_Registration">chrome manifest</a> file is used by XULRunner to define specific URIs which in turn are used to locate application resources. This will become clearer when we see how the “chrome://” URI is used. Application chrome can be in a single or a few JAR files or uncompressed as folders and files. I am using the uncompressed method for now. Here is the <code>chrome/chrome.manifest</code>:</p>
<pre class="eval">
 content myapp content/
</pre>
<div class="note">
  Note: Make sure your application name is lowercase and longer than 3 characters</div>
<p>As mentioned in Step 3, the default location of the <code>chrome.manifest</code> has changed in XULRunner 2.0, so we also need a simple <code>chrome.manifest</code> in the application root which will include the the manifest in our chrome root. Here is the root <code>chrome.manifest</code>:</p>
<pre>
manifest chrome/chrome.manifest</pre>
<h2 id="Step_6:_Set_up_preferences" name="Step_6:_Set_up_preferences">Step 6: Set up preferences</h2>
<p>The <code>prefs.js</code> file tells XULRunner the name of the XUL file to use as the main window. Here is mine:</p>
<pre class="eval">
 pref("toolkit.defaultChromeURI", "<a class="external" href="chrome://myapp/content/main.xul" rel="freelink">chrome://myapp/content/main.xul</a>");
</pre>
<p>XULRunner preferences include:</p>
<dl>
  <dt>
    <code><a href="/en/toolkit.defaultChromeURI" title="en/toolkit.defaultChromeURI">toolkit.defaultChromeURI</a></code></dt>
  <dd>
    Specifies the default window to open when the application is launched.</dd>
  <dt>
    <code><a href="/en/toolkit.defaultChromeFeatures" title="en/toolkit.defaultChromeFeatures">toolkit.defaultChromeFeatures</a></code></dt>
  <dd>
    Specifies the features passed to <code><a href="/en/DOM/window.open" title="en/DOM/window.open">window.open()</a></code> when the main application window is opened.</dd>
  <dt>
    <code><a href="/en/toolkit.singletonWindowType" title="en/toolkit.singletonWindowType">toolkit.singletonWindowType</a></code></dt>
  <dd>
    Allows configuring the application to allow only one instance at a time.</dd>
</dl>
<p>This is described in further detail in <a href="/en/XULRunner/Specifying_Startup_Chrome_Window" title="en/XULRunner/Specifying_Startup_Chrome_Window">XULRunner:Specifying Startup Chrome Window</a>.</p>
<h2 id="Step_7:_Create_some_XUL" name="Step_7:_Create_some_XUL">Step 7: Create some XUL</h2>
<p>Finally, we need to create a simple XUL window, which is described in the file <code>main.xul</code>. Nothing fancy here, just the minimum we need to make a window. No menus or anything.</p>
<p>main.xul:</p>
<pre>
&lt;?xml version="1.0"?&gt;

&lt;?xml-stylesheet href="chrome://global/skin/" type="text/css"?&gt;

&lt;window id="main" title="My App" width="300" height="300" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt;

  &lt;script type="application/javascript" src="chrome://myapp/content/main.js"/&gt;

  &lt;caption label="Hello World"/&gt;
  &lt;separator/&gt;
  &lt;button label="More &gt;&gt;" oncommand="showMore();"/&gt;
  &lt;separator/&gt;
  &lt;description id="more-text" hidden="true"&gt;This is a simple XULRunner application. XUL is simple to use and quite powerful and can even be used on mobile devices.&lt;/description&gt;

&lt;/window&gt;
</pre>
<div class="note">
  <strong>Note:</strong> Make sure there is no extra whitespace at the beginning of the XML/XUL file</div>
<p>The application also has a JavaScript file. Most XUL applications will include some external JavaScript, so the sample application does too, just to show how to include it into the XUL file.</p>
<p>main.js:</p>
<pre>
function showMore() {
  document.getElementById("more-text").hidden = false;
}
</pre>
<p><strong>Hint:</strong> You can download the sample application from the Files section at the bottom of this article.</p>
<h2 id="Step_8:_Run_the_application" name="Step_8:_Run_the_application">Step 8: Run the application</h2>
<p>The moment of truth. We need to get XULRunner to launch the bare-bones application.</p>
<h3 id="Windows">Windows</h3>
<p>From a Windows command prompt opened to the <code>C:\program files\myapp</code> folder, we should be able to execute this:</p>
<pre class="eval">
 xulrunner.exe application.ini
</pre>
<p>Of course, xulrunner.exe must be in the <code>PATH</code>. Because of where I unzipped XULRunner, I could also try this if xulrunner.exe is not in the <code>PATH</code>:</p>
<pre class="eval">
 ..\xulrunner\xulrunner.exe application.ini
</pre>
<h3 id="Mac">Mac</h3>
<p>On the Mac, before you can run a XULRunner application with everything intact, you must install it using the <code>--install-app</code> xulrunner commandline flag. Installing the application creates an OS X application bundle:</p>
<pre class="eval">
 /Library/Frameworks/XUL.framework/xulrunner-bin --install-app /&lt;path&gt;/&lt;to&gt;/myapp.zip
</pre>
<p>Once installed, you can run the application:</p>
<pre class="eval">
 /Library/Frameworks/XUL.framework/xulrunner-bin "/Applications/Finkle/TestApp.app/Contents/Resources/application.ini"
</pre>
<p>You may run it without installing (but with the menu bar and dock icon missing) in OS X by typing:</p>
<pre>
/Library/Frameworks/XUL.framework/xulrunner-bin "/&lt;full path&gt;/TestApp/application.ini"
</pre>
<p>Note: The full path is required or a "Error: couldn't parse application.ini."-message will be returned.</p>
<p>This might also be simplified using a very simple shell script (i call mine "run.sh"):</p>
<pre>
#!/bin/sh
/Library/Frameworks/XUL.framework/xulrunner-bin `pwd`/application.ini 
</pre>
<h3 id="Linux">Linux</h3>
<p>On Ubuntu, you can run the application from a terminal. First change into the <code>\myapp</code> folder, then start the application by:</p>
<pre class="eval">
 xulrunner application.ini
</pre>
<p>You should now see a window that looks something like this. This particular screenshot is from Ubuntu 10.</p>
<p><img alt="myapp-screenshot.png" class="internal default" src="/@api/deki/files/4679/=myapp-screenshot.png" /></p>
<h3 id="Alternative:_Use_Firefox3_-app_to_run_XUL_apps" name="Alternative:_Use_Firefox3_-app_to_run_XUL_apps">Alternative: Use Firefox3 -app to run XUL apps</h3>
<p>With Firefox 3, you can tell the firefox executable to run a XUL application from the command line, instead of the Firefox browser that normally starts. This is similar to starting a XUL app using XULRunner. See <a href="/en/XULRunner_tips#Using_Firefox_3_to_run_XULRunner_applications" title="en/XULRunner_tips#Using_Firefox_3_to_run_XULRunner_applications">Using Firefox 3 to run XULRunner applications</a>. This does not work if Firefox itself was installed as a XUL app - you need to use the installed XULRunner directly.</p>
<p>{{ Next("Windows and menus in XULRunner") }}</p>
<div class="originaldocinfo">
  <h2 id="Original_Document_Information" name="Original_Document_Information">Original Document Information</h2>
  <ul>
    <li>Author: Mark Finkle</li>
    <li>Last Updated Date: October 2, 2006</li>
  </ul>
</div>
<p>{{ languages( { "ja": "ja/Getting_started_with_XULRunner", "ko": "ko/Getting_started_with_XULRunner" } ) }}</p>
Revert to this revision