Zap Build Documentation

Prerequisites

The zap code is maintained as a Mercurial repository at http://hg.mozilla.org/users/alex_croczilla.com/zap-central. Zap is basically a clone of the mozilla-central repository, with some additional patches and, of course, the zap-specific code. zap-central is frequently synchronized to mozilla-central.

Building zap has similar requirements to building Mozilla. Unfortunately the Mozilla buildsystem is not for the faint of heart, so if this is the first time you are trying to get something Mozilla-based to work, it would be a very good idea if you acquire some experience with building Firefox or XULRunner from Mercurial sources, by following the instructions on the Mozilla Developer Center site here and here.

Additional build requirements

In addition to the generic Mozilla build prerequisites, on Windows you will also need the August 2007 version of the DirectX SDK (downloadable here; other versions might work; the SDK basically needs to contain DirectMusic, which is missing in more recent versions). You will also need to add the DirectX paths to your INCLUDE and LIB environment variables, so that they will be found during the build.

Linux and OS X should have no additional requirements beyond the 'generic' ones.

Cloning the zap repository

As stated earlier, zap-central, the zap repository , is a full clone of mozilla-central. This is different to other projects like Seamonkey, which maintain their project-specific code in a separate repository and pull in the Mozilla sources through a python script. Since we still want to be able to easily extract a history of zap-specific changes, the zap-related code (including zap-specific patches to Mozilla) lives in an in-repository Mercurial branch (branch 'zap'). Whenever we synchronize to mozilla-central, we merge all the changes that have been happening on the default branch to the zap branch.

The use of in-repository branches is relatively straight-forward, but you need to exercise some care when cloning and setting up the working directory. First of all, to prevent hg clone from unnessarily updating the working directory to the 'default' branch, call it with the -U option:

$ cd ~
$ mkdir zaphg
$ cd zaphg/
$ hg clone -U http://hg.mozilla.org/users/alex_croczilla.com/zap-central/
destination directory: zap-central
requesting all changes
adding changesets
adding manifests
adding file changes
added 16234 changesets with 90012 changes to 38750 files

As zap-central contains more than 30000 files, cloning could take some time. After the operation completes you will have a clone of zap-central with an empty working directory (bar the '.hg' folder):

$ ls -a zap-central/
.     ..      .hg

Because of the large size of the repository, it is a good idea to keep a pristine copy of zap-central around locally. This will allow you to create local clones of zap-central quickly and experiment with things like Mercurial Queues.

So let's leave your zap-central's working directory untouched, and instead create a (local) clone and update its working directory to the 'zap' branch:

$ hg clone -U zap-central local
$ cd local/
$ hg update -r zap
35394 files updated, 0 files merged, 0 files removed, 0 files unresolved

You can verify that 'local' is indeed set to the zap branch:

$ hg branch
zap

To examine the history of just the zap branch you can use (requires Mercurial version 1.0 or later):

$ hg log -b zap |less

changeset:   16233:db399bda2a7c
branch:      zap
tag:         tip
parent:      16061:4c4c9f3c0819
parent:      16232:d6bbea319540
user:        Alexander Fritze <alex@croczilla.com>
date:        Sat Jul 26 17:00:11 2008 +0200
summary:     Merge from mozilla-central

changeset:   16061:4c4c9f3c0819
branch:      zap
user:        Eilon Yardeni <eyardeni@8x8.com>
date:        Fri Jul 25 21:41:44 2008 +0200
summary:     Stun server / DNS resolution fixes

...

Building Zap

You instruct the buildsystem to build zap by passing --enable-application=zap to the 'configure' script. The most convenient way of doing this is by creating a '.mozconfig' file, where you can also set the other build-related options. There are a few appropriate templates in zap/config/:

# assuming your repository is in ~/zaphg/local:
$ cd ~/zaphg/local/
$ ls zap/config/
mozconfig                     mozconfig-release-linux-amd64
mozconfig-debug-linux-amd64   mozconfig-release-linux-i686
mozconfig-debug-linux-i686    mozconfig-release-osx
mozconfig-debug-osx           mozconfig-release-win32
mozconfig-debug-win32

Pick an appropriate one for your platform and copy it to the root of the tree, e.g. on OS X:

$ cp zap/config/mozconfig-debug-osx .mozconfig

This particular mozconfig file sets up the buildsystem to create a debug build in the ../debug/ directory.

As for "normal" Mozilla builds, you might need to tweak some more variables. E.g. the buildsystem will expect to find an autoconf executable called "autoconf-2.13", which isn't the right name on Ubuntu. On such a system you need to set the AUTOCONF option:

$ echo 'mk_add_options AUTOCONF=autoconf213' >> .mozconfig

Now you can proceed with building:

$ make -f client.mk

As you know from building Mozilla, this will take a bit of time :-)

Testing the build

Assuming everything went well in the last step, you should now have a build in the ~/zaphg/debug/ directory (or where ever you instructed Mozilla to place the build). There are some zap-specific unit tests that you can run:

$ cd ~/zaphg/debug/zap/
$ make check
TEST-PASS | ...zap_netutils/unit/test_441768.js | all tests passed
TEST-PASS | ...zap_netutils/unit/test_addr.js | all tests passed
TEST-PASS | ...zap_netutils/unit/test_udpsocket.js | all tests passed
TEST-PASS | ...zap_stun/unit/test_stunclassic.js | all tests passed

Should any of these tests fail, then please let us know on IRC or on the mailing list.

You can also try running the full set of Mozilla unit tests, however note that this will take quite some time and also some of the tests are known to fail at this point in time (most notably the 'places'-related ones):

$ cd ~/zaphg/debug/
$ make check
TEST-PASS ...
...

Running the SIP client application

$ cd ~/zaphg/debug/dist/bin/
$ ./xulrunner ../xpi-stage/zap/application.ini

$ export DYLD_LIBRARY_PATH=~/zaphg/debug/dist/zap.app/Contents/Frameworks/XUL.framework/
$ cd ~/zaphg/debug/dist/
$ open zap.app

$ cd ~/zaphg/debug/dist/zap.app/Contents/MacOS/
$ ./xulrunner

Running the Zap Sandbox

Making changes and recompiling

If you edit code under ~/zaphg/local/zap/, it is usually sufficient to recompile locally:

... edited some file in ~/zaphg/local/zap/zmk/ ...
$ cd ~/zaphg/debug/zap/zmk/
$ make

To be on the safe side, you might want to rebuild everything under ~/zaphg/local/zap/:

$ cd ~/zaphg/debug/zap/
$ make

$ cd ~/zaphg/debug/xulrunner/app
$ make

$ cd ~/zaphg/debug/zap/
$ make

Mercurial cheat sheet

There's a great overview at MDC for working with Mercurial Queues.