DevTools/Hacking

Want to hack on Firefox Developer Tools? You've come to the right place! If you want more information about contributing, check out our guide for getting involved

First Build

Follow the instructions on how to build Firefox, except that you will need to use:

hg clone http://hg.mozilla.org/integration/fx-team

Instead of:

hg clone http://hg.mozilla.org/mozilla-central

For your first build, running ./mach build should do the trick after you get the source code. If you are going to be building a lot, you may want to set up your .mozconfig file.

Incremental Builds

Once you've already built Firefox once, and you just want to incrementally update your build with your latest devtools changes, you can run:

 $ ./mach build toolkit/devtools browser

Which is much faster and should only take a few seconds.

Running your build

First Run

Once you have built Firefox, you can run it with

 $ ./mach run -p development

What is the -p development? It is a flag telling Firefox to use a different profile, named "development" (this name can be anything you want). If it does not exist the first time you run it, Firefox will open a popup and you can create a new profile with the name you passed in. This will prevent you from seeing an error message telling you that you need to close your main browser window, and it will let you make settings changes without worrying about messing up your normal profile.

Once this command runs, you should see a new Firefox window, called "Nightly". You will want to make a couple of quick changes to the profile.

Open DevTools, and click the "Toolbox Options" gear in the top left. Make sure the following two options are checked: Enable Chrome Debugging and Enable Remote Debugging. These settings allow you to use the browser debugger to set breakpoints inside of the DevTools code, and let you run the Scratchpad in the Browser environment.

Depending on what you are working on, you may want to make some more changes to your profile. If you type about:config in the URL bar, click through the warning page, and search for devtools you can see some of them.

 # This setting prints all packets sent over the remote debugging protocol to stdout:
 devtools.debugger.log = true

Restart the browser to apply any configuration changes.

Development workflow

As you make changes to the code, you can run the following commands to see your changes (you may want to store these in a script for reuse).

 $ ./mach build toolkit/devtools browser
 $ ./mach run -p development

Making and Submitting a Patch

Before you make any changes, read this section on creating a patch for someone else to check in - this will get you set up with a separate Mercurial queue for development of your patch.

If you read through the source code about something you do not know about, you may find documentation here:

• Mozilla Developer Network has a ton of info about XUL elements, HTML, JS, DOM, Gecko-specific APIs and more.
• MXR (Mozilla Cross-Reference) is a source code search engine - search for symbols you want to learn about, eg. nsIDocument.
• DXR is a smart source code search tool, similar to MXR but sometimes better.
• You should read our Coding Standards before writing a patch.
  • in general, try to be File Consistent. For new files, follow the standards.

If you still have questions, ask us on IRC or leave a comment on the Bugzilla case.

And finally, once you have a patch file you can simply add it as an attachment to the Bugzilla case you are working on. You can read more about how to submit a patch if you want more information.

Developer Tools Directories Overview

• toolkit/devtools: Code for the devtools client and server, and all code shared between the front end and client/server. If we are using any third party libraries, or importing external repositories into our tree, those libraries generally live here (eg, toolkit/devtools/acorn).
  • toolkit/devtools/server: Code for the devtools Remote Debug Protocol server.
  • toolkit/devtools/client: Code for the devtools Remote Debug Protocol client.
• browser/devtools: Front end user interfaces for the tools.

Running the Developer Tools Tests

We use three suites of tests:

• xpcshell: More unit-test style of tests. No browser window, just a JavaScript shell. Mostly testing APIs directly.
• mochitest-chrome: More unit-test style of tests, but with a browser window. Mostly testing APIs that interact with the DOM directly.
• mochitest-browser: More of an integration style of tests. Fires up a whole browser window with every test and you can test clicking on buttons, etc.

xpcshell Tests

To run all of the xpcshell tests:

 $ ./mach xpcshell-test toolkit/devtools
 $ ./mach xpcshell-test browser/devtools

To run a specific xpcshell test:

 $ ./mach xpcshell-test toolkit/devtools/path/to/the/test_you_want_to_run.js

Chrome Mochitests

To run the whole suite of chrome mochitests for devtools:

 $ ./mach mochitest-chrome toolkit/devtools
 $ ./mach mochitest-chrome browser/devtools

To run a specific chrome mochitest:

 $ ./mach mochitest-chrome toolkit/devtools/path/to/the/test_you_want_to_run.html

Browser Mochitests

To run the whole suite of browser mochitests for devtools (sit back and relax):

 $ ./mach mochitest-browser browser/devtools

To run a specific tool's suite of browser mochitests:

 $ ./mach mochitest-browser browser/devtools/<tool>

For example, run all of the debugger browser mochitests:

 $ ./mach mochitest-browser browser/devtools/debugger

To run a specific browser mochitest:

 $ ./mach mochitest-browser browser/devtools/path/to/the/test_you_want_to_run.js

Checking your code using JSHint

There are many tools that allow you to run JSHint. The most commonly used on our codebase is JSHint Gutter for Sublime Text 3. Your jshint.rc should look like this:

 {
   "moz": true,
   "browser": true,
   "maxerr": 9999,
   "trailing": true,
   "undef": true,
   "loopfunc": true,
   "devel": true,
   "unused": true,
   "globals": {
     "loader": true,
     "require": true,
     "exports": true,
     "Components": true,
     "Iterator": true,
     "is": true,
     "isnot": true,
     "ok": true,
     "info": true,
     "EventUtils": true,
     "finish": true,
     "waitForExplicitFinish": true,
     "gBrowser": true,
     "content": true,
     "Services": true
   }
 }