Getting started with contributing patches to the Firefox preferences

  • Revision slug: Hacking_Firefox/Getting_started_with_contributing_patches_to_the_Firefox_preferences
  • Revision title: Getting started with contributing patches to the Firefox preferences
  • Revision id: 55472
  • Created:
  • Creator: JaredWein
  • Is current revision? No
  • Comment 116 words added

Revision Content

The Preamble

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 codebase, or any codebase of similar size, and be successful in the first couple tries.

The Body

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/ affects the Windows theme, changes in /pinstripe/ affects the Mac OS X theme, and changes in /gnomestripe/ affects 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.

Revision Source

<h3>The Preamble</h3>
<p>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.</p>
<p>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, <strong>please follow the instructions in the <a href="/En/Developer_Guide/Source_Code" title="Working with Mozilla source code">Working with Mozilla Source Code</a> and the <a href="/En/Developer_Guide/Build_Instructions" title="Build Instructions">Build Instructions</a> first</strong>.</p>
<p>There's a lot of background knowledge that will have to be acquired over time. Nobody is expected to jump in to the Firefox codebase, or any codebase of similar size, and be successful in the first couple tries.</p>
<h3>The Body</h3>
<p>The first step of every front-end developer working on a Mozilla project is to install <a class="link-https" href="https://addons.mozilla.org/en-US/firefox/addon/dom-inspector-6622/" title="https://addons.mozilla.org/en-US/firefox/addon/dom-inspector-6622/">the DOM Inspector add-on</a>. 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 -&gt; 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.</p>
<h4>Step one: Browsing through some code</h4>
<p>There are already a few preference pages that are rendered in-content. The best example of this is <strong>about:permissions</strong>. Take a few minutes now and visit about:permissions in Firefox, using DOM Inspector to view the markup used within the page.</p>
<h4>Step two: Reasoning about how XUL works</h4>
<p>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 <a href="/en/XUL" title="XUL">the XUL documentation</a> or walk through <a href="/en/XUL_Tutorial" title="XUL Tutorial">the XUL tutorial</a>.</p>
<h4>Step three: Getting to know the XUL, JS, and CSS of about:permissions</h4>
<p>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:</p>
<ul> <li><span class="s0"><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/">/</a><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/">browser</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/">components</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/preferences/">preferences</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/preferences/aboutPermissions.js">aboutPermissions.js</a></span></li> <li><span class="s0"><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/">/</a><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/">browser</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/">components</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/preferences/">preferences</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/preferences/aboutPermissions.css">aboutPermissions.css</a></span></li> <li><span class="s0"><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/">/</a><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/">browser</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/">components</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/preferences/">preferences</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/preferences/aboutPermissions.xml">aboutPermissions.xml</a></span></li> <li><span class="s0"><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/">/</a><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/">browser</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/">components</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/preferences/">preferences</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/components/preferences/aboutPermissions.xul">aboutPermissions.xul</a></span></li> <li><span class="s0"><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/">/</a><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/">browser</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/">locales</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/en-US/">en-US</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/en-US/chrome/">chrome</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/en-US/chrome/browser/">browser</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/en-US/chrome/browser/preferences/">preferences</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/en-US/chrome/browser/preferences/aboutPermissions.dtd">aboutPermissions.dtd</a></span></li> <li><span class="s0"><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/">/</a><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/">browser</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/">locales</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/en-US/">en-US</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/en-US/chrome/">chrome</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/en-US/chrome/browser/">browser</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/en-US/chrome/browser/preferences/">preferences</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/locales/en-US/chrome/browser/preferences/aboutPermissions.properties">aboutPermissions.properties</a></span></li> <li><span class="s0"><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/">/</a><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/">browser</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/">themes</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/winstripe/">winstripe</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/winstripe/preferences/">preferences</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/winstripe/preferences/aboutPermissions.css">aboutPermissions.css</a></span></li> <li><span class="s0"><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/">/</a><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/">browser</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/">themes</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/pinstripe/">pinstripe</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/pinstripe/preferences/">preferences</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/pinstripe/preferences/aboutPermissions.css">aboutPermissions.css</a></span></li> <li><span class="s0"><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/">/</a><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/">browser</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/">themes</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/gnomestripe/">gnomestripe</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/gnomestripe/preferences/">preferences</a>/<a class="external" href="http://mxr.mozilla.org/mozilla-central/source/browser/themes/gnomestripe/preferences/aboutPermissions.css">aboutPermissions.css</a></span></li>
</ul>
<p>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.</p>
<p>Changes in /winstripe/ affects the Windows theme, changes in /pinstripe/ affects the Mac OS X theme, and changes in /gnomestripe/ affects the Linux theme of Firefox.</p>
<p>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.</p>
<p>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 <strong>make -s -C browser/components</strong> to rebuild just the <strong>components</strong> directory. If you make changes in one of the other directories, simply replace the <strong>components</strong> word with the relevant folder name, such as <strong>locales</strong> or <strong>themes</strong>. Note that if you are using Mac OS X, you will also need to run <strong>make -s -C browser/app</strong>.</p>
<p>To see your changes, change the working directory to <strong>/mozilla-central/obj-blah-blah-blah</strong>:</p>
<ul> <li>On Windows, run <strong>dist/bin/firefox.exe</strong></li> <li>On Mac OS X, run <strong>dist/NightlyDebug.app/Contents/MacOS/firefox-bin</strong></li> <li>On Linux, run <strong>dist/bin/firefox</strong></li>
</ul>
<p>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: <a class=" external" href="http://msujaws.wordpress.com/2011/06/29/running-multiple-versions-of-firefox-simultaneously/" title="http://msujaws.wordpress.com/2011/06/29/running-multiple-versions-of-firefox-simultaneously/">Running multiple versions of Firefox simultaneously</a>.</p>
Revert to this revision