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.
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.
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 ac_add_options --enable-logging ac_cv_visibility_pragma=no # XULRunner options ac_add_app_options xulrunner --enable-application=xulrunner ac_add_app_options xulrunner --disable-installer # 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 prebuilt 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
This assumes that you are building from the directory directly above the
mccoy directory (well, actually your own application's directory) on your disk.
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
build.mk- maybe you thought that the
--enable-applicationoption told Mozilla which directory your app is located in. Wrong! It tells Mozilla where to look for the
build.mkfile, 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
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.infor 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
mccoysince it uses the
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.
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.icnswith 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
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/<code> 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
The installer/ subdirectory
Building it... finally!