Creating XULRunner Apps with the Mozilla Build System

In most cases, developers of XULRunner applications can download an existing SDK and follow the instructions in Getting started with XULRunner. This is by far the simplest approach. In some cases, however, you may want to use the Mozilla build system to create your application. The only obvious reason for this would be if you need to implement part of your application in C++, as described in the introduction to the now classic Creating Custom Firefox Extensions with the Mozilla Build System.

For the purposes of this article I'm using Dave Townsend's McCoy as an example. It's a straightforward XULRunner app that nonetheless uses most of the features any given application is likely to need.

Building XULRunner

Do I need to build XULRunner?

If you are just creating a XULRunner app with some C++ components, you can avoid the challenge of building XULRunner itself by downloading a prebuilt SDK. Do this if at all possible and send me some of the money you save on psychiatry sessions.

If you are actively modifying XULRunner as part of your development, however, you'll have to bite the bullet. For example, you may be fixing bugs in XULRunner, applying patches from Bugzilla that aren't yet checked into the main repository or making your own changes to deploy as part of a customized XULRunner build.

So basically, almost everyone should be able to skip the next section.

Building XULRunner

Still here? Hey, it's not all bad. You'll get a warm fuzzy feeling from mastering the complex but very powerful Mozilla build system. And all that furniture you smash in the meantime makes great kindling to get you through those cold winter nights. Let's face it, it was probably time for you to get some new furniture anyway.

Everything you ever wanted to know about building Mozilla (and thus XULRunner) can be found in the Build Documentation. Follow the instructions for meeting build requirements and getting the source, then come back here since the build process itself will be slightly different.

Got source? Now you need to set up a special .mozconfig file to tell Mozilla to build both XULRunner and your application. Here's a sample .mozconfig for building XULRunner and McCoy:

# Options for client.mk.
mk_add_options MOZ_BUILD_PROJECTS="xulrunner mccoy"
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../mccoybase

# Global options
ac_add_options --enable-debug
ac_add_options --disable-optimize

# XULRunner options
ac_add_app_options xulrunner --enable-application=xulrunner

# mccoy options
ac_add_app_options mccoy --enable-application=mccoy
ac_add_app_options mccoy --with-libxul-sdk=../xulrunner/dist

The first section tells Mozilla what to build and where to put the resulting object files. In this case, we are building both XULRunner and McCoy and placing the build in the directory mccoybase, located at the same level as the current (i.e. source) directory. To build just one of the projects, remove the name of the other from MOZ_BUILD_PROJECTS. For example, you might want to set it to "xulrunner" now and run make to ensure that everything is set up correctly so far.

The second section contains general options for your build. In this case we're creating a debug build, so you'd have to change the relevant options if you want a release build instead. You can find out more about which options to use in Configuring Build Options.

The third section contains options for building XULRunner. You shouldn't have to change this. Finally, the final section contains options specific to your application. Make sure you change the application name (following ac_add_app_options to that of your app. Do the same with the name that follows --enable-application. You shouldn't have to change the value of --with-libxul-sdk if you are building your own XULRunner. You can also add other options to this section if you want them to apply to your app only.

Building Your Application

If you decided that you needed a custom-built XULRunner and read the previous section then you're way ahead of the game. You simply need to place your application's root directory directly under the mozilla root on your disk. And what's more, you can skip the following section, partially compensating you for all that extra work you put in just now. See, it all balances out in the end!

Building with a prebuilt SDK

Once you've downloaded the XULRunner SDK, you'll need a .mozconfig of your own. Here's an example for McCoy:

# Options for client.mk.
mk_add_options MOZ_CO_PROJECTS=browser
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../mccoybase

# Options for 'configure' (same as command-line options).
ac_add_options --with-libxul-sdk=/path/to/xulrunner-sdk
ac_add_options --enable-application=mccoy

You still need to get the Mozilla Source Code (CVS) and put your project in a subdirectory underneath the mozilla root. Of course, you only really need the Mozilla build system since all the other Mozilla files are in the XULRunner SDK, and there is a bug filed to make it possible to check out the build system only.

Okay, okay, can I build it now?

Sorry, no. First you're going to have to write a whole bunch of makefiles and stuff. Oh, and actually develop the application itself. The first part, at least, should be fairly straightforward since you just have to copy and adapt the files from the McCoy repository. You'll learn a lot more by looking at the project files than you will from reading this drivel, but just to be safe let's run through the files one by one:

• Makefile.in - the top-level makefile. Contains the names of the subdirectories that need to be built, which at very least will include chrome and app.
• build.mk - maybe you thought that the --enable-application option told Mozilla which directory your app is located in. Wrong! It tells Mozilla where to look for the build.mk file, which is what tells it where to start building your app. Don't think to hard about this, just copy McCoy's file and adapt accordingly.
• confvars.sh - some basic configuration options. You should be able to use the McCoy version, changing just your application name and version.
• makefiles.sh - you don't absolutely need this file since the build system will generate makefiles as need by walking the tree (based on the value of DIRS). You will need it if you want to generate a makefile but keep it out of the main build, which is what McCoy does with installer/Makefile. In addition, builds are faster when you include all makefiles in this file since they can be generated with a single shell invocation.

And that's all there is to it. Now that wasn't so bad, was it? Well, actually there are still a bunch of subdirectories you're going to need. And did I mention you'll have to write your application as well?

The app/ subdirectory

The app/ subdirectory is where you put files that are necessary for packaging your application as a XULRunner app.

• Makefile.in - didn't we already do this one? Nope. Mozilla has a separate Makefile.in for each directory that is part of the build. In this case, you'll be a happy, healthier and more well-balanced if you don't try to understand the file at all. Just copy it from McCoy. You don't even have to substitute in your application name for mccoy since it uses the APP_NAME variable.
• application.ini - used for application packaging. A complete description can be found in XUL Application Packaging. In this case you can basically copy over the file as is, since once again variables are used for things like the application name and version. But you will have to change the ID to something unique to your app.
• default-prefs.js - these are the default Mozilla preferences used by XULRunner when running your app. The important ones are described in XULRunner:Specifying Startup Chrome Window. You can add other preferences for things like debugging, as McCoy does (e.g. javascript.options.showInConsole).
• default.ico and default.xpm - Icons for your app on Windows and Linux.
• macbuild/ - When Steve Jobs said "think different", we took that to heart, and not just by rejecting useless adverbial endings. We've included a whole subdirectory just for the Mac. It's got a lot of stuff in it, but once again you can mostly ignore this and copy the whole directory over from McCoy. You will, however, need to change the name of the icon file in Info.plist.in. And, of course you'll need to replace mccoy.icns with the icon file to be used by your app on OS X.

The chrome/ subdirectory

Chrome for your application should be placed in the chrome/ subdirectory as described in XUL Tutorial:XUL Structure. Chrome will be packaged automatically by the build system, so you also need to specify which files get put into which packages by using JAR Manifests. In the case of McCoy, a separate manifest is used for content/, skin/ and locale/. This also means that you will need to put a makefile in each directory.

If you're lazy like me, you can also use one big JAR manifest in the chrome/ directory, which means you don't need to put makefiles in the chrome subdirectories either. You can make this jar.mn to rule them all just by concatenating the three files in the McCoy example and updating the path to each file (since you will need to point to the correct subdirectory):

mccoy.jar:
% content mccoy %content/
* content/mccoy.xul                    (content/mccoy.xul)
  content/mccoy.js                     (content/mccoy.js)
* content/mccoy.xml                    (content/mccoy.xml)

...etc...

Note that the locale manifest uses a variable to specify the name of the locale which has to be defined in the makefile (and you need to say #filter substitution in the manifest for the variable to be expanded).

You will also need to include a branding/ subdirectory. Follow the example in McCoy carefully since XULRunner is sensitive about having exactly the right files in exactly the right packages.

The components/ subdirectory

If you are reading this guide, you probably need to include C++ components in your application. If you've never done this before, you should consult Creating XPCOM Components or another XPCOM reference.

The public/ and src/ directories that you put in the components/ directory will look the same as for an extension that includes C++ components, so you can use the relevant sections of Creating Custom Firefox Extensions with the Mozilla Build System as a reference. The makefiles, however, will be difference since you won't be defining things like XPI_NAME (this is used only for extensions). So use the makefiles in the components/ directory of McCoy as a guide instead.

Don't forget to put components into the DIRS variable in the top-level makefile, or your components won't be built. So for most XULRunner apps that use the Mozilla build system, the top-level makefile will contain:

DIRS = components chrome app

The installer/ subdirectory

The installer/ makefile lets you create a setup program for distributing your application. This is a single file that can be used to install the app (e.g. a .dmg file on Mac).

Simply copy the makefile from the installer/ subdirectory of McCoy. You shouldn't have to change anything since MOZ_APP_NAME is automatically set to the name of your application.

Note that the installer is not build automatically when you build you application, since the installer/ directory is not included in the DIRS variable in the top-level makefile. You can add it at the end if you want to make an installer every time you build the app, but this will add significant time to each build cycle. Instead, you probably want to do like McCoy and use make package to build the installer (see below for building instructions).

Building it... finally!

To build your application, make sure you have the right .mozconfig file in your top-level source directory, then run the following from that directory:

make -f client.mk build

So if you are building XULRunner as well as your app, this will cause both to be built in sequence.

Just walking the Mozilla tree to build XULRunner can take a fair amount of time, even if it has already been built and the sources haven't changed. So you'll probably find it convenient to use two .mozconfig files, one for building both and one just for your app. Rather than renaming files all the time, you can use the MOZCONFIG environment variable to specify which one to use. So if I have files called mozconfig-both and mozconfig-mccoy, for example, and I just want to build McCoy, I could run something like:

MOZCONFIG=`pwd`/mozconfig-mccoy make -f client.mk build

Acknowledgements

Many thanks first of all to Benjamin Smedberg for maintaining the build system (by this time he probably deserves credit for writing most of it) and answering my endless stupid questions. Thanks also to Dave Townsend for the many hours of trial-and-error he doubtless put into figuring this all out when writing McCoy. He suffered so that we don't have to. Finally, Ben Turner and the Songbird folks were perhaps the first to write any documentation about building XULRunner apps with the Mozilla build system, something I know Dave took advantage of.