CloudServices/Sync/FxSync/Developer/Building
Contents
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:
- Find your profile directory
- Create a plain text file at <profile>/extensions/{340c2bbc-ce74-4362-90b5-7c26312808ef}
- 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