README.md

Mozilla CommitBuilder

The mozcommitbuilder package is a generic builder library for Mozilla Firefox.  It also features interactive regression finding over changesets using local builds. 
It is probably most useful when used in combination with custom condition scripts (see below for more information)

Summary

Downloads the mozilla-central mercurial repository to a local cache and allows operations on that trunk
including interactive regression finding over changeset ranges and building particular revisions of firefox and running them. 
In particular, this module was designed for regression hunting and to provide a flexible builder for firefox. 

Dependencies

Mercurial.  A correctly-configured mozconfig dotfile is optional.  By default, mozcommitbuilder generates its own mozconfig, but you can pass in your own through params/cli if the script fails to build correctly or if you need other configurations..

Install

mozcommitbuilder is available on pypi, so you can install it with easy_install or pip.  The recommended method is pip. 

sudo pip install mozcommitbuilder --upgrade

Usage

Command-line Interface

#This is an example of a command to do interactive bisection between#changesets (you can use the full changeset hash or short numerical id)
mozcommitbuilder -g 70168-b 70180

#This example shows that you can use dateranges to similarly bisect#on changesets. 
mozcommitbuilder --good=2012-05-29--bad=2012-05-30

#If you are on OSX or Linux, this will compile with 8 cores.  Multi-core#compiliation on windows doesn't work, the parameter will be ignored. 
mozcommitbuilder -g 70168-b 70180-j 8

#This will delete the cached trunk and download a new one, then build#revision 70168 with 8 cores
mozcommitbuilder -f --single=70168-j 8

#This will delete the cached trunk and download a new one, then build#revision 70168 with 8 cores, then start firefox on completion. 
mozcommitbuilder -f -e --single=70168-j 8

Condition Scripts

Instead of interactively building/running/prompting during bisection,
you may opt to use an automated condition script.  Here is some
information about the condition script (you can also see the example
in the examples directory)

Writing a condition script:
====================1.  It needs to contain a function called interesting(args, directory).  It takes two arguments, one which will be populated
w/ the arguments, the other which will contain the path of a temporary directory. 
2.  It needs to return a string "bad"or"good" to indicate if the revision was broken ornot. 
It can theoretically return a boolean but that is less descriptive and may be confusing. 
If you choose to use booleans, Trueis bad (contains regression), Falseis good (does not contain regression)
3.  args[0] contains the path of the object directory (useful when running tests)
4.  args[1] to args[x] contain whatever arguments were supplied

Other

For bisection: if the range of commits spans more than a day, try mozregression

Flags

Usage: builder.py --good=[changeset] --bad=[changeset] [options]
builder.py --single=[changeset] -e
Options:
--version show program's version number and exit
-h, --help show this help message and exit
Global Options:
-j [numjobs], --cores=[numjobs]
Max simultaneous make jobs (default: 8, the number of
cores on this system)
-m [mozconf path], --mozconfig=[mozconf path]
external mozconfig if so desired
-f, --freshtrunk Delete old trunk and use a fresh one
-d, --deletetrunk Cleanup Flag: deletes the temp directory / trunk
generated.  Do not use with other flags, this is just
for convenient cleanup. 
Bisector Options:
These are options for bisecting on changesets.  Dates are retrieved
from pushlog and are not as reliable as exact changeset numbers. 
-g [changeset or date], --good=[changeset or date]
Last known good revision
-b [changeset or date], --bad=[changeset or date]
Broken commit revision
-r, --remote Use remote build cache to avoid extra builds (NOT YET
WORKING)
Single Changeset Options:
These are options for building a single changeset
-s [changeset], --single=[changeset]
Build a single changeset
-e, --run run a single changeset
Binary building options:
These are options for building binaries from a single changeset
-x, --binary build binary and return path to it
-q [changeset], --revision=[changeset]
revision number for single changeset to build binary
from
Automatic Testing Options:
Options for using an automated test instead of interactive prompting
for bisection.  Please read documentation on how to write testing
functions for this script. 
-c [condtest.py -opt1 -opt2], --condition=[condtest.py -opt1 -opt2]
External condition for bisecting.  Note: THIS MUST BE
THE LAST OPTION CALLED. 
Remote Options:
If you don't have a build environment you can push to tryserver to
build.  Warning: not recommended -- very very slow.  Uses a trypusher
server (see http://github.com/samliu/moztrypusher).  Another option
here is to use mozilla's remote build cache to avoid a lot of
building.  Warning: breaks support for the automated test. 
-t, --try Build remotely with trypusher
-n [trypusher server hostname], --host=[trypusher server hostname]
Trypusher host
-p [trypusher server port], --port=[trypusher server port]
Trypusher Port
Broken and Unstable Options:
Caution: use these options at your own risk.  They aren't recommended. 
-R valid repository url, --repo=valid repository url
alternative mercurial repo to bisect NOTE: NEVER BEEN
TESTED