Simple Instantbird build

This page covers the basic steps needed to build a bleeding-edge, development version of Instantbird. For additional, more detailed information, see the build documentation. This should be kept in sync with Simple Thunderbird build, you might want to take a look at that page too.

Build prerequisites

Hardware Requirements:

  • While you can build Instantbird on older hardware it can take quite a bit of time to compile on slower machines, and having 8GB of RAM is recommended (though you can probably still get away with 4Gb).
  • Good internet connection for the initial source download.

Setup:

Depending on your Operating System you will need to carry out a different process to prepare your machine. So firstly complete the instructions for your OS and then continue following these build instructions.

TIP: After completing Setup for your OS, and before you Get the source, you can opt to add the progressExtension to your mercurial.ini (for Windows) or .hgrc (for *Nix / Mac) file. This will provide status feedback during the lengthy clone / download process. see: Configure Mercurial .hgrc file for Progress Extension.

Get the source

Note: On Windows, you won't be able to build the Instantbird source code if it's under a directory with spaces in the path (e.g., don't use "Documents and Settings"). You can pick any other location, such as a new directory C:\instantbird-src.
Note: Parts of the build process also have problems when the source code is in a directory where the path is long (nested many levels deep). On Linux, this can manifest as problems setting up the virtualenv for running tests (failure to install pip or virtualenv because of OS access denied errors, where access is denied not because of permission problems, but because the paths being accessed have been truncated, and so do not exist). Having the source deep in a filesystem hierarchy can also cause problems with pymake builds on Windows. If you run into seemingly arbitrary problems in building and the source is deeply nested, try moving it close to the root of your machine and re-building.

Get the latest source code from Mozilla's comm-central Mercurial code repository:

hg clone http://hg.mozilla.org/comm-central

Then, get all the repositories it depends on. The comm-central repository includes a script to do just that. This may take a while, it's a lot of code! First, cd into the comm-central subdirectory (created automatically by the previous command):

cd comm-central

then run:

python client.py checkout
Note: Unless you have a very good network connection, "hg clone" might fail because it gets interrupted. It is faster and more efficient to use Mercurial bundles instead the first time you fetch the complete repo. In this case, you need a bundle for comm-central, and a bundle for mozilla-central. Unbundle mozilla-central into a "mozilla" subdirectory of your comm-central repo after unbundling comm-central. Then run python client.py checkout to ensure you are up-to-date.

The source code requires 1.5GB of free space or more.

Build configuration

By default, the build system creates a release build of Instantbird roughly equivalent to the official Instantbird release builds. If that's not exactly what you want, there are many build configuration options to choose from, although it's strongly recommended that you only use options that you fully understand. The normal way to specify build options is to place them in a file called '.mozconfig' at the root of your mozilla source tree, i.e. your comm-central repo. For example, to create a debug build instead of a release build, that file would contain:

ac_add_options --enable-debug

For more on configuration options, see the page Configuring build options. Note that if you use an MOZ_OBJDIR it cannot be a sibling folder to your source directory. Use an absolute path to be sure!

Building Instantbird

What you need to do to build Instantbird rather than Firefox is:

echo 'ac_add_options --enable-application=im' >> .mozconfig

To start the build, cd into the comm-central subdirectory (created automatically by the hg clone command), and run:

./mozilla/mach build

mach is our command-line tool to streamline common developer tasks. See the mach article for more.

Building can take a significant amount of time, depending on your system, OS, and chosen build options. Linux builds on a fast box may take under 15 minutes, but Windows builds on a slow box may take several hours.

Building purplexpcom and libpurple

First download the purplexpcom code:

hg clone http://hg.mozilla.org/users/florian_queze.net/purple mozilla/extensions/purple

If you've set up your build environment as above, then all you need to do is:

echo 'ac_add_options --enable-extensions=purple' >> .mozconfig

in the comm-central directory, or just add the ac_add_options --enable-extensions=purple line to your .mozconfig with your favorite editor.

Then just re-run the mach command above (you may need to clobber (see below), or you can do the addition before running make for the first time).

Running

To run your build, you can use

./mozilla/mach run

There are various command line parameters you can add, e.g. to specify a profile.

Various temporary files, libraries, and the Instantbird executable will be found in your object directory (under comm-central/), which is prefixed with obj-. The exact name depends on your system and OS. For example, a Mac user may get an object directory name of obj-x86_64-apple-darwin10.7.3/.

The Instantbird executable in particular, and its dependencies, are located under the dist/bin folder under the object directory. To run the executable from your comm-central working directory:

  • Windows: obj-.../dist/bin/instantbird.exe
  • Linux: obj-.../dist/bin/instantbird
  • OS X: obj-.../dist/Instantbird.app/Contents/MacOS/instantbird

How to update and build again

Simply re-run the mach command above. This will only recompile files that changed.

Incremental builds

When you are working on your own patches, an incremental build is often enough, and is very fast indeed. This will only rebuild a particular folder. So, for Instantbird, you would run

mach build im

which has been configured to automatically rebuild /chat as well.

Upstream changes

To fetch the latest upstream changes, in your comm-central directory, run the same command as before:

python client.py checkout

Problems Building?

Have you:

  • Tried a clobber? This means deleting the object directory so that your next build is completely fresh. To do this you can use 
    mach clobber
  • Checked the Instantbird buildbot for known failures at the time you pulled the code?
    • If the trunk is broken, you may wish to consider building one of the branches (to pull the source code from a branch, just replace the url to the repository in the hg clone instruction).
  • Checked to make sure that the path in which you placed the source code has no spaces, and is not too long?
  • Have you searched the bug database for issues relating to your problem (e.g., platform-specific issues)?
  • Try asking in mozilla.dev.chat - don't forget to include details of what is in your mozconfig, and what the actual error is.

References

Simple Thunderbird build