Mach Has Landed

September 26, 2012 at 05:30 PM | categories: Mozilla, Firefox

Hacking on Firefox is hard. Compiling the source tree for the first time is a daunting experience. If you manage to do that, you still need to figure out how to submit patches, write and run tests, etc. There is no shortage of points where people can get confused, make mistakes, or just give up because the barrier is too high.

I have strong convictions about making the overall developer experience better (developers are users too, after all). The easier you make the developer experience, the greater the chances of retaining developers. And retaining developers means more contributions: more features and fewer bugs. This translates to a better state for the Mozilla Project. This makes the world a better place.

Since practically my first day working at Mozilla, I've been experimenting with ways to make contributing to Firefox easier by improving the build system or interaction with it.

With a lot of help, I've finally succeeded in landing something into the Firefox source tree that I think will ultimately lead to a much better developer experience.

It's called mach (German for do) and if you pull the latest version of mozilla-central (Firefox's main source code repository), you can run mach today.

Running Mach

You can run Mach by simply executing it from the root directory in the repository:

$ ./mach

Ideally, I shouldn't have to tell you anything else: mach's output should provide you all the instruction you need to use it. If it doesn't, that is a bug and it should be fixed.

Realistically, mach is still in early development and its user experience still leaves a lot to be desired.

Because technical usage docs belong in a medium that is easily discoverable and where the community can improve on them (not a post on a personal blog), you can find additional usage information in the mach article on MDN. The mach README holds more technical information for people wanting to poke at the inner workings.

Mach does require Python 2.7. The build system will likely soon require Python 2.7 as well. So, if you don't have Python 2.7, you should upgrade now before you lose the ability to build the tree. Conveniently, the tree now has a bootstrap script which covers the installation of Python. So, Python 2.7 should just be a simple command away.


Why would you use mach? Good question! Compared to the existing out-of-the-box experience, mach adds:

  • Ability to run xpcshell and mochitest tests from the source directory. This means you can tab-complete test filenames in your shell and it just works.
  • Parsing of compiler warnings (currently supports Clang 3.1 and MSVC formats) into a unified warnings database (actually a JSON file). After builds you can run ./mach warnings-list or ./mach warnings-summary to get a concise list without having to look at build logs.
  • A single command-line interface where you can easily discover new functionality. Just run ./mach help (try doing that with make!).

Naysayers will say this is a paltry list. They are correct. I have bigger plans. But, you have to start somewhere.

Goals and Future Ideas

The overall goal of mach is to improve the developer experience of developing Firefox and other Gecko applications. It does this by providing a convenient, central command in the root directory of the repository that acts as both an oracle to discover new commands and functionality (./mach help) as well as a proxy to execute them. You don't need to worry about environment variables, working directories, or finding some random script hidden in the bowells of the source tree. You just run a single command and the world is brought to you. No build documentation. No outdated wikis. No copying commands into your shell. No having to scour random blogs for useful tools. You just clone the repository, run a command, see what you can do, and get stuff done. Your shell-literate grandmother could do it.

Mach should be your springboard to in-tree developer tools and increased productivity. You shouldn't need anything except a copy of the source tree and mach.

Like Git and Mercurial, mach is powered by the concept of sub-commands/actions. So, one simply needs to register a new sub-command with the mach driver. This involves writing a Python class. Once you do that, people can discover and use that functionality. All batteries are included with a copy of mozilla-central.

As stated above, the current set of commands is rather small. But, the sky is the limit. Here are some of my ideas:

  • Ability to upload, download, and apply patches from Bugzilla (Burak Yiğit Kaya, Jeff Hammel, Clint Talbert and I have already talked about this -- progress tracked in bug 774141).
  • Automatically configure Mercurial with optimal settings (ensure user info is set, proper lines of diff context, enable mqext, etc). Tracked bug 794580.
  • Submit Try builds. The trychooser Mercurial extension could easily live as a mach subcommand! Tracked in bug 774137.
  • Identify Bugzilla components and/or reviewers from files touched by patch. It's all in the history of the touched files and the history of the old bugs referenced by those commits! Bug 774145.
  • Interaction with the self-serve build API. That thing on TBPL to control individual builds - we could make a CLI interface for it. (Steve Fink and/or Jeff Hammel already have code for this - it just needs to be integrated). Bug 774147.

If you have an idea for a feature, please file a bug. Please note there are many features on file already. However, some obvious ones such as integration with missing test suites have yet to be filed (at least at the time I wrote this post).

If you wrote an awesome developer tool and would like others to use it (without having to rely on people discovering it by reading a corner of the Internet), add it to mach! Use mach as a wedge to get more exposure and users. File a bug. I will happily r+ patches that add useful developer functionality to the tree.

What this Means / Longer Term Future

While there is no timetable, mach will eventually replace, like mach, is essentially a CLI driver for the build system. Having the driver implemented in Python rather than make has many compelling advantages. I could probably write a whole post on it, but I'll spare the world from my ranting.

Anyway, this all means that you may want to start re-training your muscle memory now. Stop typing make and start typing mach. If you need to type make because mach does not provide a feature, this is a missing feature from mach. File a bug and request a new mach feature!

I want to condition people to stop typing make, especially in the object directory. There are drastic changes to the build system in the works (bug 784841 is the tip of the iceburg). These changes will require the build system to be treated as a black box. So, things like invoking make from the object directory will eventually break. You'll need to go through an intelligent tool to invoke the build system. Mach will be that tool.


I would like to single out the following individuals for helping to land mach:

  • Jeff Hammel for doing the bulk of the reviewing. He shares my vision for mach and how it will make the overall developer experience much more pleasant and how this will translate to better things for The Project. In my mind, Jeff deserves as much credit for landing mach as I do.
  • Mike Hommey and Ms2ger for review help. Mike Hommey helped identify a lot of issues with build system integration. Ms2ger provided lots of general feedback on Python issues and API design.
  • Mike Connor (my manager) for allowing me to work on this. It's not related to my job description in any way so he could say I shouldn't be spending time on this. But, he realizes the positive impact this can have and has been supportive of it.

I hope you find mach useful!