The code for our tools is split in two different locations, so if you want to work on a specific tool you will first need to locate where it is.
Before you start modifying any aspect of DevTools, you’ll want to make sure you can build them successfully first. This might require setting up your computer to obtain and compile Firefox’s source code.
Where is the code?
Most of the code is hosted in the Firefox repository (we call it
mozilla-central, often abbreviated as
m-c), in the devtools folder. Development of newer pieces of the tools is happening in GitHub, on the devtools-html organisation.
m-c takes longer to obtain and build, as it involves checking out Firefox’s repository and installing tools such as compiler to build a version of Firefox in your machine.
On the other hand, the repositories in
devtools-html are more straightforward if you’re used to the GitHub workflow: you clone them, and then run
Even if you only want to work on a tool whose code is on
devtools-html, you might still need to go through the step of getting and compiling the code from
mozilla-central in order to do integration work (such as updating a tool bundle).
From now on, this document will focus on building the full DevTools within Firefox. Please refer to individual project instructions for tools hosted in
These are the steps we’re going to look at:
- Getting the code
- Building and running locally
Getting the code
The code is officially hosted on a Mercurial repository. Despair not! There are ways of accessing this via git. We will explain this too.
Either way takes a long time, because the repository is B I G. So be prepared to be patient.
Using Mercurial (hg)
hg clone http://hg.mozilla.org/mozilla-central
There is a tool called git-cinnabar that lets you use git on top of a Mercurial repository. There’s a bit of setup involved, so we’ve written a script to automate installing
git-cinnabar and obtaining the code.
Building and running locally
Whatever method you used to obtain the code, the build step is the same. Fortunately, the Firefox team has made a very good job of automating this with bootstrap scripts and putting documentation together.
If your system needs additional dependencies installed (for example, Python, or a compiler, etc), various diagnostic messages will be printed to your screen. Follow their advice and try building again.
Building also takes a long time (specially on slow computers).
Note: if using Windows, you might need to type
mach build instead (without the
Running your own compiled version of Firefox
To run the Firefox you just compiled:
This will run using an empty temporary profile which is discarded when you close the browser. We will look more into persistent development profiles later.
Suppose you pulled the latest changes from the remote repository (or made your own changes) and want to build again.
You can ask the
mach script to build only changed files:
./mach build faster
This should be faster (a matter of seconds).
Sometimes, if you haven’t updated in a while, you’ll be told that you need to clobber, or basically delete precompiled stuff and start from scratch, because there are too many changes. The way to do it is:
./mach clobber ./mach build
Building even faster with artifact builds
If you are not going to modify any C/C++ code (which is rare when working on DevTools), you can use artifact builds. This method downloads prebuilt binary components, and then the build process becomes faster.
Create a file on the root of the repository, called
mozconfig, with the following content:
# Automatically download and use compiled C++ components: ac_add_options --enable-artifact-builds # Write build artifacts to: mk_add_options MOZ_OBJDIR=./objdir-frontend
And then you can follow the normal build process again (only faster!)
On MacOS you might want to use
MOZ_OBJDIR=./objdir-frontend.noindex instead. Using the
.noindex file extension prevents the Spotlight from indexing your
objdir, which is slow.
For more information on aspects such as technical limitations of artifact builds, read the Artifact Builds page.
Maybe you don’t even need to build
Instead, what you need to do is to save the files you modified, quit Firefox, and reopen it again to use the recently saved files.
# 1. Build ./mach build # 2. Run ./mach run # 3. you try out things in the browser that opens # 4. fully close the browser, e.g. ⌘Q in MacOS # 5. edit JS files on the `devtools` folder, save # 6. Back to step 2! ./mach run
While not as fast as the average “save file and reload the website” web development workflow, or newer workflows such as React’s reloading, this can still be quite fast.
And certainly faster than building each time, even with artifact builds.
Next up: setting up a development profile.