Getting started with contributing patches to the Firefox preferences

Note: This article covers a feature that is not yet scheduled for a specific future release of Firefox.

The Firefox preferences serve as a tool for users to modify and personalize Firefox to their own, well, preference. This page should serve as a guide for people looking to get started with moving the current Preferences from the Window/Sheet implementation to being viewed within the content pane of the browser.

This page assumes you have already set up a build environment and have built Firefox. If you haven't set up a build environment or compiled Firefox yet, please follow the instructions in the Working with Mozilla Source Code and the Build Instructions first.

There's a lot of background knowledge that will have to be acquired over time. Nobody is expected to jump in to the Firefox code base, or any code base of similar size, and be successful in the first couple of tries.

Getting started

The first step of every front-end developer working on a Mozilla project is to install the DOM Inspector add-on. This add-on allows developers to dig in to the XUL/HTML/CSS/layout of the Firefox user interface. After installing DOM Inspector, press Ctrl+Shift+I (letter I, pronounced as eye) on Windows and Cmd+Shift+I on Mac OS X. Then choose File -> Inspect Chrome Document and choose the tab that is in the foreground. Now click on the button all the way to the left on the toolbar (it shows a cursor on top of a rounded rectangle) to pick an element for inspecting. You can now use the various tools of DOM Inspector and play around with the Firefox front-end.

Step one: Browsing through some code

There are already a few preference pages that are rendered in-content. The best example of this is about:permissions. Take a few minutes now and visit about:permissions in Firefox, using DOM Inspector to view the markup used within the page.

Step two: Reasoning about how XUL works

If you're curious as to why a certain XUL element was used or what each XUL element does, you can take a look at the XUL documentation or walk through the XUL tutorial.

Step three: Getting to know the XUL, JS, and CSS of about:permissions

Mozilla contributors can use MXR, the Mozilla Cross-Reference, to browse and search the Mozilla code base. The files used to display about:permissions can be viewed here:

The files located in /locales/ are used for generating language-specific builds of Firefox for use across the world. Changes made to Firefox usually only contain the en-US locale (English-United States). When the code moves out of trunk and in to the Aurora channel, localizers from across the world will add their own *.dtd file with their locale-specific languages.

Changes in /winstripe/ affect the Windows theme, changes in /pinstripe/ affect the Mac OS X theme, and changes in /gnomestripe/ affect the Linux theme of Firefox.

Now that you've seen the source code on MXR, open the files on your local build and make some changes. For some simple changes, you could try tweaking some of the CSS or XUL files.

Building Firefox can take a long time, but it doesn't need to. Since you've already built Firefox, (you have, haven't you?) you can now go to the object directory (located at /mozilla-central/obj-blah-blah-blah) and type make -s -C browser/components to rebuild just the components directory. If you make changes in one of the other directories, simply replace the components word with the relevant folder name, such as locales or themes. Note that if you are using Mac OS X, you will also need to run make -s -C browser/app.

To see your changes, change the working directory to /mozilla-central/obj-blah-blah-blah:

On Windows, run dist/bin/firefox.exe
On Mac OS X, run dist/NightlyDebug.app/Contents/MacOS/firefox-bin
On Linux, run dist/bin/firefox

If you already have Firefox running, you will get an error stating that, well, Firefox is already running. This is less than great, but there is a way to run multiple versions of Firefox simultaneously. For more information, see: Running multiple versions of Firefox simultaneously.

Step four: Making your own about: page

Now that you've gotten a little comfortable tweaking an existing in-content preference page, you can try creating a simple page of your own.

Update the files located here with an entry of about:omgmyownpage or something else that you think is cool:

To get a feel for what to do, try to simply copy what is done for "permissions". If you're having trouble here, ask a question in #fx-team or #developers on Mozilla's IRC network.

Now, add your own files in /browser/components/preferences/ with your own filename. To be consistent, you can name it aboutOmgMyOwnPage.xhtml. Note, how the filename ends in .xhtml, this is on purpose. Mozilla is trying to extend and build off of (X)HTML, so we're trying to use XUL less and less, and only fall back to XUL when HTML is lacking. So for this walk-through, we're going to try to start on the right foot.

After making your files, you will also need to add them to the jar.mn file. The jar.mn file is used to package up content files that are used by the browser. It is designed to make loading of content faster. The file for this example is located at browser/components/preferences/jar.mn

If you want to see how (X)HTML pages are similar or different from XUL pages, you can compare with /browser/components/sessionstore/content/aboutSessionRestore.xhtml.

After making your changes, you can now rebuild and see your changes. Make sure that your working directory is the object directory (/mozilla-central/obj-blah-blah-blah), and type make -s -C browser/components/ and also rebuild /browser/app if you're running on Mac OS X. After building, run the browser using the same tips from step three. Visit about:omgmyownpage to see, your new page.

Closing the connection

If you have any questions, please do not hesitate to visit the channels on Mozilla's IRC server. Don't ask if you can ask a question, just ask. And if nobody replies, don't take it personally (folks are really busy!), just ask again later.