CloudServices/Sync/FxSync/Developer/Building

Build Requirements

• If you're on Windows, you'll want to install MozillaBuild to get a collection of useful tools needed for a working build setup.
• Only if you are rebuilding/modifying the crypto pieces
  • A C++ compiler
  • The Gecko 1.9.1 SDK (if modifying/building crypto pieces)
    • If there is no 1.9.1 SDK for your OS, instructions on building one are here.
• If you want to commit changes to Weave's source code, or easily keep up with development, you'll need a Mercurial client, available here.

Retrieving the Source

Retrieve the Weave source code from the Mozilla Mercurial source repository using the following command:

 hg clone http://hg.mozilla.org/services/fx-sync

Alternatively, you can also retrieve the latest tarball of the source from:

 http://hg.mozilla.org/services/fx-sync/index.cgi/archive/tip.tar.gz

You can also retrieve the latest zip of the source from:

 http://hg.mozilla.org/services/fx-sync/index.cgi/archive/tip.zip

Building as an Extension

Building Crypto

Sync's source repository contains prebuilt binary components for all supported platforms. You should not need to rebuild these components as the code is essentially frozen. However, if your OS is not supported, or you are working on the crypto wrapper pieces, you'll need to follow these steps:

1. Set up the Gecko SDK

export MOZSDKDIR=/path/to/SDK

2. build crypto with the rebuild_crypto argument

make crypto rebuild_crypto=1

Building the Extension For Install

To build a Firefox Sync .xpi to install, just type the following in to your shell:

make xpi

This will generate a .xpi file located at fx-sync/dist/xpi/weave-{version}.xpi. You can then open that file from Firefox to install the extension.

Building the Extension For Development

You could use the above make xpi for development and install then restart every time you make a change, but you can be more efficient with another command. It requires a little more up-front setup, but it saves a lot of time down the line.

Note, this only works for systems that support "symlinks", so this won't work on Windows.

First create an extension proxy:

1. Find your profile directory
2. Create a plain text file at <profile>/extensions/{340c2bbc-ce74-4362-90b5-7c26312808ef}
3. Edit that file with a single line referencing <path to weave>/dist/stage

Assuming you know where your weave files are and your profile directory, you can do this in a single line on OS X:

echo /Path/To/fx-sync/dist/stage > ~/Library/Application\ Support/Firefox/Profiles/xr4nd0mx.profile/extensions/{340c2bbc-ce74-4362-90b5-7c26312808ef}

Now you just need to build Weave from the weave directory:

make

That's all!

Any future changes to files under fx-sync/ will work after you restart Firefox. You don't even need to run make again. The only time you would need to re-run make is if you change a .in file or the values used in the .in file.

Setting up to run tests

1. Set XULRUNNER_BIN to the location of the XULRunner or Firefox 3.5+ executable. Here are some possible values (but your executable might be elsewhere):

  Linux:
    /usr/bin/firefox
    /usr/bin/xulrunner

    Note: I observed additional test failures using xulrunner
          on Ubuntu 10.10 when compared to /usr/bin/firefox. 
          Don't use firefox-bin; it won't work.

  Mac OS X:
    /Library/Frameworks/XUL.framework/xulrunner-bin
    /Applications/Firefox.app/Contents/MacOS/firefox-bin

  Windows:
    /c/Program\ Files/Mozilla\ Firefox/firefox.exe

2. set TOPSRCDIR to the location of the top-level fx-sync source code directory.

3. set NATIVE_TOPSRCDIR to the location of the top-level fx-sync source code directory, but expressed in the platform native format. On Unix or Mac OS X this will be identical to TOPSRCDIR, but on Windows, NATIVE_TOPSRCDIR should be a Windows-style path to the same directory, with backslashes for separators.

On Mac OS X, a sample ~/.profile looks like this, in part:

       export XULRUNNER_BIN=/Library/Frameworks/XUL.framework/xulrunner-bin
       export TOPSRCDIR=~/weave
       export NATIVE_TOPSRCDIR=~/weave

Running Tests

• To run all tests, simply run "make test" from the top-level source directory. Weave will build and run all tests.

• To run specific tests, you can use the following command:

make -C services/sync/unit <test_name>

i.e. to run test_resource.js, you would type

make -C services/sync/tests/unit test_resource

N.B. the crypto tests will fail using this approach. Use the mozilla-central approach below.

Building against mozilla-central

Firefox Sync is distributed both as an extension and as part of Firefox. While development for both the client library and the add-on UI continues in the fx-sync repository, changes to the Sync client library are periodically merged to mozilla-central. It is therefore important to be able to test code against ongoing development on mozilla-central.

Using an Updated Client Library with mozilla-central builds

To run the client library from the fx-sync repository in a Firefox nightly or custom build, simply build and install it as an extension (see above). The resource://services-*/ resource paths from the extension take precedence over the built-in ones.

Running Tests against mozilla-central builds

You need a checkout of mozilla-central and a complete build located in an object dir (e.g. obj-ff-dbg below the checkout):

export MOZILLA=/path/to/mozilla-central
export MOZ_OBJDIR=/path/to/obj-ff-dbg

Then simply type

make xpcshell-tests

or

make SOLO_FILE="test_resource.js" check-one

to run an individual test. See Writing xpcshell-based unit tests for more info.

Interesting make targets

This is basically the output of "make help":

Targets:
build
test (default; implies build)
crypto (only updates the source directory)
chrome (only updates the source directory)
test (default; implies build)
xpi (sets manifest to use jars, make build to undo)
clean

Variables:
sdkdir
release_build (set to 1 when not building a snapshot)
rebuild_crypto (set to 1 when building a new crypto binary)

Substitutions for .in files:
weave_version buildid buildid_short update_url update_url_tag unpacked jar

Older Versions

If for some reason you want to build Weave versions before 0.5, docs are now here