The articles below include content about downloading and building Mozilla code. In addition, you'll find helpful articles about how the code works, how to build add-ons for Mozilla applications and the like.

A bird's-eye view of the Mozilla framework
The purpose of this article is to provide a high-level technical overview of the architecture of the extensible, object-based Mozilla application framework.
Accessibility and Mozilla
Accessibility is the idea that software (among other things) should be designed to be usable and, as much as possible, convenient to use for people with disabilities. Mozilla strives to make its software accessible; the documents below cover the ways in which we do so.
Add-ons allow developers to extend and modify the functionality of Firefox.
Adding a new CSS property
This page describes how to add a new CSS property to the style system. The style system is the part of the code in Gecko that is responsible for producing a computed value for every property for every element. See the Gecko Overview for more information about the style system.
Adding a new event
This draft document covers how to add a new event to the Mozilla (Firefox) source code.
Adding a new word to the en-US dictionary
Occasionally bugs are filed pointing out situations where perfectly legitimate words are missing from the English spell check dictionary in Firefox. This article describes the process for adding a word to the dictionary.
Adding phishing protection data providers
Phishing protection technology lets Firefox help protect users by comparing the URLs the user visits to a list of known scam sites, and presenting a warning to the user when they visit a site on the list.
An introduction to hacking Mozilla
This guide introduces the Mozilla project and provides an overview for developers interested in contributing to or exploring the various parts of the codebase.
Android-specific test suites
There are several Android-specific test suites that run on the Firefox for Android codebase:
API change rules
Until further notice, the following rules govern API changes:
Application cache implementation overview
This happens in nsHttpChannel::OpenCacheEntry(). All top level document loading (navigation) channels are set ChooseApplicationCache flag, which happens in nsDocShell::DoURILoad(). Channels having that flag set are searching for nsIApplicationCache object prior inspecting normal HTTP cache. nsIApplicationCacheService::ChooseApplicationCache is given the URL the channel is about to load. It synchronously returns an nsIApplicationCache object representing the most recent cache version from the most recent cache group containing the entry under the URL or a matching namespace.
Debug builds (--enable-debug) and non-optimized builds (--disable-optimize) are much slower. Any performance metrics gathered by such builds are largely unrelated to what would be found in a release browser.
Browser chrome tests
The browser chrome test suite is an automated testing framework designed to allow testing of application chrome windows using JavaScript. It currently allows you to run JavaScript code in the same scope as the main Firefox browser window and report results using the same functions as the Mochitest test framework. As all tests, they won't work in a build with tests disabled (--disable-tests).
Browser security
An important aspect of developing code for any browser, including Firefox, as well as any Web-oriented project, is its security. These articles provide important guides and references to ensuring the code you write is secure, including both design recommendations and testing guidelines.
Bugzilla (often abbreviated b.m.o) is's bug-tracking system, a database for recording bugs and enhancement requests for Firefox, Thunderbird, SeaMonkey, Camino, and other projects.
Building Mozilla
In this article, we list documents that will guide you in building Firefox or other projects based upon Mozilla code.
Building SpiderMonkey with UBSan
1. Compile a recent version of LLVM & Clang.
C++ portability guide
This document has migrated to Using C++ in Mozilla code.
Choosing the right memory allocator
There are a lot of different memory allocators in the Mozilla source tree. This article looks over some of them and tries to sort out which should be used under what circumstances.
Chrome registration
Chrome is the set of user interface elements of the application window that are outside the window's content area. Toolbars, menu bars, progress bars, and window title bars are all examples of elements that are typically part of the chrome.
Command line options
Command line options are used to specify various startup options for Mozilla applications.This page describes the commonly used options and how to use them. You can open the command line interface by pressing shift + F2.
Continuous Integration
When you push a commit to mozilla-central or a related repository, it initiates a large chain of builds and tests across multiple types of infrastructure. This document will help you understand all the pieces that comprise Mozilla's continuous integration systems.
Cookies in Mozilla
Suggestions as to needed documentation can be directed to Mike Connor.
Cookies Preferences in Mozilla
These preferences apply to most Mozilla products (including Firefox and Seamonkey), however they are application-specific, so not all of them may apply to you. The default values given are for Firefox 3.
Creating a Firefox sidebar
Web publishers can offer visitors a Firefox sidebar to encourage their engagement. There are two ways to create a sidebar for Firefox users: the Social API and an extension. You can choose either depending on your needs and resources.
Creating a Language Pack
To create a language pack, or a localization repack, you first need to go through the initial setup process.
Creating a localized Windows installer of SeaMonkey
Preamble: not all of the programs listed below are necessary. Some of them are simply the ones I use because I like them, while others are scripts that I've created to speed up the work. You can in every case choose the program you prefer to do some operations, and you can also decide not to use any of my scripts and manually enter all of the commands by hand. It's your choice!
Creating a Login Manager storage module
The Login Manager manages and stores user passwords. Extensions can replace the built-in password storage with their own implementation. This can be useful if you want to integrate a gecko application's password management with an existing password management system, or use your own password storage format or database. So for example, on KDE is is desirable to fully employ the KDE wallet manager, rather than any secondary replacements of KDEwallet.
Creating a spell check dictionary add-on
This page describes how to package a Hunspell spell check dictionary as a Firefox add-on, or how to update your existing add-on, so that it can be installed, uninstalled and updated without a restart.
Creating JavaScript callbacks in components
XPCOM components use IDL to create interfaces. These interfaces are used to manipulate the component in C++ and JavaScript. A common pattern used with interfaces to create a bi-directional communication between two groups of code is the observer (or listener) pattern. Basically, the component defines an observer (or listener) interface which is implemented by some external code and this implementation is passed to the component. The component can then call methods on the observer interface to signal the external code when predefined events occur. Here is a very simple example of the observer pattern:
Creating MozSearch plugins
Firefox 2 uses a simplified form of the OpenSearch format for storing search plugins. A MozSearch search plugin is an XML file that describes the search engine, its URL, and the parameters that need to be passed to that URL.
Creating reftest-based unit tests
The reftest harness compares the display of two Web pages. If the bitmaps resulting from displaying the two files in an 800x1000 window are identical, the test passes. If they differ, the test fails. Or, alternatively, the conditions can be reversed (a != test rather than an == test). The power of the tool comes from the fact that there is more than one way to achieve any given visual effect in a browser. So, if the effect of complex markup is being tested, put that complex markup into a page and create another page that uses simple markup to achieve the same visual effect. Reftest will then compare them and verify whether they produce the same bitmap.
Creating Sandboxed HTTP Connections
Starting with Gecko 1.8.1 (Firefox 2), it is possible to create sandboxed HTTP connections which don't affect the user's cookies. This article will cover the basics of doing HTTP connections from XPCOM JavaScript, and should easily translate to C++ XPCOM.
Debugging a project as large as Mozilla can be a daunting task. Fortunately, over the years, Mozilla developers have come up with not just technologies and features to help you debug code, but have devised tips and techniques that can help too. Also available are assorted tools that you can use when debugging.
Developer guide
There are lots of ways to contribute to the Mozilla project: coding, testing, improving the build process and tools, or contributing to the documentation. This guide provides information that will not only help you get started as a Mozilla contributor, but that you'll find useful to refer to even if you are already an experienced contributor.
Displaying Places information using views
Views are one component of the Places model-view-controller design. Use them to display nsINavHistoryResult objects to the user. See Querying Places for information about obtaining and using nsINavHistoryResult objects, which this page assumes you are familiar with.
Error codes returned by Mozilla APIs
The following tables list errors that can occur when calling various Mozilla APIs. Each error is listed by its name and an error code in parentheses. An error will typically be displayed on the error console, but can be captured using a try-catch block in JavaScript. These constants can be accessed through Components.results. For example, by using Components.results.NS_ERROR_NOT_INITIALIZED
Here you can learn about how to contribute to the Firefox project and you will also find links to information about the construction of Firefox add-ons, using the developer tools in Firefox, and other topics.
Firefox Operational Information Database: SQLite
A large amount of operational information about websites visited and browser configuration is stored in relational databases in SQLite used by Firefox. The SQLite Manager add-on allows convenient browsing of this information. (Install the SQLite Mangager add-on, click Tools -> SQLite Manager. In the manager, select the database you want to explore in the '(Select Profile Database)' pulldown, click 'Go', select one of the tables listed in the left column and see the current contents of the database in the 'Browse & Search' tab.)
Gecko is the name of the layout engine developed by the Mozilla Project. It was originally named NGLayout. Gecko's function is to render web content, such as HTML, CSS, XUL, JavaScript, and render it on the user's screen or print it. In XUL-based applications Gecko also renders the application's user interface.
Gecko's "Almost Standards" Mode
"Almost standards" rendering mode is exactly the same as "standards" mode in all details save one, where it works like "quirks" mode: the height calculations for line boxes and some of the inline elements in them.
Geckoview-Junit Tests
The geckoview-junit tests are on-device Android junit tests written for geckoview.
Getting from Content to Layout
Gecko maintains two separate representations of a document in memory: the content tree and the frame tree. Changes to a document originate in the content tree (from DOM modification by scripting, insertion of elements from the parser, etc.) and are propogated to the layout tree through magic that primarily resides in //
Getting Started with Chat
Note that on 2nd March 2020, Mozilla moved away from IRC to Matrix for its public channels, the IRC server was shut down.
Moved here:
Hacking with Bonsai
Bonsai was originally created to solve the problem of tree instability. The original Navigator code base had large sections that were shared across multiple platforms. Many times, code checked in would compile or run on a handful of platforms. Also, with as many as 100 engineers, it was very difficult to determine what happened in the tree that caused the instability. Bonsai was created to solve these problems.
How Mozilla determines MIME Types
All data handling in Mozilla is based on the MIME type of the content. This means that every time an URI is loaded, Mozilla must find out its MIME type. The several ways how this happens are described in this document.
How test harnesses work
Mozilla test harnesses are typically composed of a python runner that invokes Firefox, utilizes the browser to run tests, and reports the results. The python harness communicates with the browser by inserting an extension in the testing profile or uses marionette's wire protocol to drive the browser.
How to add a build-time test
Writing a test is good, but it is even more helpful if that test gets executed. We have various automation tools that help make this possible. The first link, though, is the "check" target in a Makefile. If a test is added, that test or its directory needs to be mentioned in a file somewhere so that the build system knows about it.
How to get a process dump with Windows Task Manager
When tracking down the causes of process hangs, it is often helpful to obtain a process dump while the process is experiencing a hang. This article describes how to get a process dump with Task Manager on Windows. (To get a process dump for Thunderbird or some other product, substitute the product name where ever you see Firefox in these instructions.)
How to get a stacktrace for a bug report
If you file a bug report in Bugzilla about a crash you should include a stacktrace (call stack) in your report. A stacktrace will tell Mozilla developers what crashed and provide a starting point for investigating its cause. This article describes how to use the Mozilla Crash Reporter (Breakpad) to get a crash ID, which our engineers can use to get a stacktrace, and alternative ways to get a stacktrace if you can't get a crash ID.
How to get a stacktrace with WinDbg
Sometimes you need to get a stacktrace (call stack) for a crash or hang but Breakpad fails because it's a special crasher or a hang. This article describes how to get a stacktrace in those cases with WinDbg on Windows. (To get a stacktrace for Thunderbird or some other product, substitute the product name where ever you see Firefox in this instructions.)
How to implement a custom autocomplete search component
The XUL textbox element supports an autocomplete mechanism that is used to create a textbox with a popup containing a list of possible completions for what the user has started to type. There are actually two autocomplete mechanisms:
How to investigate Disconnect failures
This article will guide you on how to investigate disconnect failures. An example of such a failure
How to Report a Hung Firefox
Is your Firefox not responding? Or are you regularly seeing the "Firefox is running but is not responding..." dialog? This usually means that something in Firefox is hung. This may be because of a code error within Firefox itself, such as a deadlock or infinite loop, or it may be caused by 3rd-party software such as a Firefox extension, antivirus software, or even malware or a virus on your computer.
HTTP Cache
IME handling guide
This document explains how Gecko handles IME.
Implementing Download Resuming
This document describes how an embedder or other Gecko/Necko-using application can implement download resuming.
Implementing QueryInterface
This document describes the right way to write QueryInterface().
Infallible memory allocation
There's ongoing work to implement infallible memory allocators. These are memory allocation routines that never return null; that is, they always successfully return the requested block of memory. This is in contrast to a traditional, fallible memory allocator that can return null indicating that the request failed.
Integrated Authentication
This entails support for the the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) internet standard (RFC 2478) to negotiate either Kerberos, NTLM, or other authentication protocols supported by the operating system.
Internationalized Domain Names (IDN) Support in Mozilla Browsers
Netscape 7.1 is the first commercial browser that has built-in support for Internationalized Domain Name under the new IETF RFC's established in 2003.
Introduction to Layout in Mozilla
IPC Protocol Definition Language (IPDL)
IPDL, short for "IPC (Inter-process communication) Protocol Definition Language", is a Mozilla-specific language allowing C++ code to pass messages between processes or threads in an organized and secure way. All messages for multi-process plugins and tabs in Firefox are declared in the IPDL language.
JavaScript code modules
JavaScript code modules let multiple privileged JavaScript scopes share code. For example, a module could be used by Firefox itself as well as by extensions, in order to avoid code duplication.
JavaScript libraries from Mozilla projects
In addition to Firefox and other applications, Mozilla developers have created a number of useful JavaScript libraries you can use in your projects. Documentation for these libraries can be found here.
JavaScript Tips
JavaScript-DOM Prototypes in Mozilla
When a DOM node is accessed from JavaScript in Mozilla, the native C++ DOM node is wrapped using XPConnect and the wrapper is exposed to JavaScript as the JavaScript representation of the DOM node. When XPConnect wraps a C++ object it will create a JSObject that is unique to this C++ object. In the case where the C++ object has class info (nsIClassInfo), the JSObject is a more or less empty JSObject which is not really that special. All the methods that are supposed to show up on this JSObject are actually not properties of the object itself, but rather properties of the prototype of the JSObject for the wrapper (unless the C++ object's class info has the flag nsIXPCScriptable::DONT_SHARE_PROTOTYPE set, but lets assume that's not the case here).
js-ctypes allows application and extension code to call back and forth to native code written in C. C++ support is possible through vtable pointers see Using COM from js-ctypes. For a discussion on extended C++ support see bug 505907. Other work made possible by js-ctypes is JNI, this is elaborated on in the JNI.jsm section and not the js-ctypes section due to the JSM abstracting away all of the js-ctypes. Unlike binary XPCOM components, it allows developers to ship a single binary for use with multiple versions of Firefox.
Localization at Mozilla
Localization (L10n) is the process of translating software user interfaces from one language to another and adapting it to suit a foreign culture. These resources are for anyone with an interest in the technical aspects involved in localization.
Memory Sanitizer
Memory Sanitizer (MSan) is a fast detector used for uninitialized memory in C/C++ programs. It uses a compile-time instrumentation to ensure that all memory access at runtime uses only memory that has been initialized. Unlike most other sanitizers, MSan can easily cause false positives if not all libraries are instrumented. This happens because MSan is not able to observe memory initialization in uninstrumented libraries. More information on MSan can be found on the Memory Sanitizer wiki.
Mozilla Development Strategies
This article offers some strategies and suggestions to help developers stay productive.
Mozilla Development Tools
This page lists the various development tools that we operate and/or maintain here at Naturally, source code for all of these tools is also available. The tools needed to build Mozilla are described on the build page for your platform.
Mozilla DOM Hacking Guide
Mozilla gives you the opportunity not only to use very powerful and complete DOM support, but also to work on a world-class implementation of one of the greatest Internet technologies ever created.
Mozilla external string guide
The Mozilla codebase used to have a notion of "external" strings, which were the string classes visible to code outside of the Mozilla codebase (Extensions, XULRunner applications, and embedders). These classes were removed a long time ago. The only remaining string classes are the "internal" ones, which are documented XPCOM Guide Internal strings.
Mozilla Framework Based on Templates (MFBT)
The Mozilla Framework Based on Templates ("mfbt") is the central repository for macros, functions, and data structures used throughout Mozilla code, including in the JavaScript engine.
Mozilla MathML Project
The Mozilla MathML project is Mozilla's project to build and enhance MathML support within Firefox and other Mozilla-based applications. For a quick overview, see the slides for the innovation fairs at Mozilla Summit 2013.
Mozilla Port Blocking
On 08/15/2001, Cert issued a Vulnerability Note VU#476267 for a "Cross-Protocol" scripting attack, known as the HTML Form Protocol Attack which allowed sending arbitrary data to most TCP ports. A simple exploit of this hole allows an attacker to send forged unsigned mail through a mail server behind your firewall: A really nasty hole.
Mozilla Projects
Mozilla has a number of projects other than Firefox itself. Many of these are components of Firefox or are tools used to create Firefox, but may be used by other projects as well. Here you'll find links to documentation about these projects.
Mozilla projects on GitHub
There are a number of tools and services whose code is hosted on GitHub. This article offers a quick guide for getting started with Mozilla code on GitHub. It also lists some interesting GitHub repositories containing Mozilla project code.
Mozilla Quirks Mode Behavior
The following is a rough list of the differences that exist between Mozilla's standards mode and quirks mode behavior.
Mozilla Style System
The Style System is the module of Mozilla's code responsible for the loading and parsing of CSS style sheets, and the computation of computed values for all CSS properties. The handling of those computed values is the responsibility of other parts of the code.
Mozilla Style System Documentation
See also the style techtalk for more complete although less detailed documentation.
Mozilla SVG Project
Since you have come this far, you probably already know that SVG stands for Scalable Vector Graphics, and that it is an XML language for sophisticated 2-dimensional graphics. SVG is to graphics what XHTML is to text, MathML is to mathematical equations and CML is to the description of chemical molecules.
Mozilla technologies
Mozilla has several technologies used as components of its projects. These are documented here.
Mozilla Web Developer FAQ
This document answers questions that Web authors ask frequently specifically in connection with Firefox and other Gecko-based browsers. There are links to more general Web authoring FAQs at the end of this document.
Mozilla Web Services Security Model
(This document is being compiled from scattered documentation and source code and most of the information in it has not been verified. Please do not depend on anything in it being correct for security.)
Below, find links to articles about C++ classes Mozilla uses within various namespaces, primarily the mozilla namespace.
omni.ja (formerly omni.jar)
Firefox and Thunderbird achieve performance improvements by moving many of their internal parts from being standalone files or sets of JAR files into just one JAR file called omni.ja; this reduces the amount of I/O needed to load the application. This article covers the contents of the archive and techniques for inspecting those contents.
The articles linked to from here will help you improve performance, whether you're developing core Mozilla code or an add-on.
Phishing: a short definition
In 2014, the MSCI estimated an annual global impact of phishing, and various forms of identity theft, to be as high as $5 billion USD. The impact has not improved much since.
The preference system makes it possible to store data for Mozilla applications using a key/value pairing system. These articles provide information about how to use the preference system.
Productization guide
Productization is the choice of ''default'' search engines, content and protocol handlers, bookmarks, links to recommended sites on the in-product pages, etc. The web services that make up the productization of Mozilla software are often specific to a local market. For example, a search provider can deliver a very good quality of search results — but only in a specific country or language, and we have to take this into account when considering default search engines for a locale. Hence there is a need to customize the set of default web services on a per-locale basis in order to ensure a good user experience across all locales.
Profile Manager
Firefox and other XULRunner applications store user settings and data in special folders, called profiles. Firefox provides a built-in applet to manage these profiles, but it will eventually be going away (see bug 214675), so a new standalone Profile Manager application has been created, which works with any XULRunner application, and has many features not found in Firefox's built-in version.
Redis Tips
This document is a collection of some examples and tips for using redis, the open-source data structure server. It is intended primarily for developers, and deliberately omits some topics that will be important in any redis deployment, like security and backups.
SeaMonkey is Mozilla's all in one internet suite. These pages document SeaMonkey's MailNews component and also provide links to documentation about the MailNews backend which is also used in other projects such as Eudora/Penelope, Thunderbird, Correo, etc.
Setting up an update server
The goal of this document is to provide instructions for installing a locally-served Firefox update.
Signing Mozilla apps for Mac OS X
Mac OS X's Gatekeeper functionality prevents users from launching applications that haven't been code-signed, in order to help keep their computers secure. Firefox and Thunderbird releases are both signed before shipping; this article describes the process.
Supported build targets
Page moved to the in-tree documentation:
Task graph
After a change to the Gecko source code is pushed to version-control, jobs for that change appear on Treeherder. How does this work?
The test-info task group runs per-commit, only on mozilla-central. Each task generates one or more json-formatted data files providing detailed information on tests run in continuous integration, typically broken down by bugzilla component. Data files are typically consumed by dashboards, like
Testing Mozilla code
Testing your code is important! Before you can even get your code committed into the source tree, you have to test it, and larger patches have to have automated tests. These articles will help you master (and continue to excel at) testing Mozilla code.
The Mozilla platform
The Mozilla project encompasses several technologies that, together, comprise the Mozilla platform. These links will direct you to documentation about each of these, as well as how to use the Mozilla platform to build your own projects.
The Rust programming language
Rust is a new open-source systems programming language created by Mozilla and a community of volunteers, designed to help developers create fast, secure applications which take full advantage of the powerful features of modern multi-core processors. It prevents segmentation faults and guarantees thread safety, all with an easy-to-learn syntax.
Thunderbird is a mail/messaging application managed and developed by the Thunderbird community. These pages document Thunderbird and the MailNews backend which is also used in other projects such as Seamonkey and Postbox.
Toolkit version format
This document is a reference for the version format, as used in Firefox 1.5 (XULRunner 1.8) and later. This format is used by the Extension Manager, Software Update, and other parts of the platform. Versions in at least the following places must conform to this format:
Using C++ in Mozilla code
Documentation moved in-tree
Using JS in Mozilla code
JS language features that are implemented in the Mozilla JS engine are ordinarily safe to use in Mozilla code.
Using Mozilla code in other projects
There are several ways you can use Mozilla code in your own project.
Using popup notifications
Popup notifications, also known as "doorhanger notifications", are presented to notify the user of something that's important but may not need immediate attention. These non-modal notifications let the user make decisions when they have a moment to do so, instead of being forced to deal with them at possibly inconvenient times. For example, this popup notification is displayed when a web site requests geolocation information:
Using RAII classes in Mozilla
RAII classes are useful when two operations (e.g., Lock/Unlock, AddRef/Release, PushState/PopState) must be paired.
Using tab-modal prompts
Note: This part of the documentation is outdated. The updated prompt documentation can be found in the Firefox Source Docs.
Using the Mozilla source server
Using the Mozilla source server is now even more feature-packed. The nightly debug builds are now also Source Indexed so that by following a couple of simple steps you can also have the source code served to you for debugging without a local build
Using the Mozilla symbol server
The Mozilla project runs a symbol server for trunk Firefox nightly and release builds on Windows. Symbols are available for at least 30 previous days worth of nightly builds, and Firefox releases from This allows debugging of those builds without forcing all users to download large debugging files. The server functions like Microsoft's symbol server so the documentation there can be useful.
virtualenv is software for isolating python package environments (e.g. import paths). It is written by Mozilla's own Ian Bicking. Creating a virtualenv installs setuptools (or optionally distribute) into the virtual environment. It is recommended that you use virtualenv for installing anything other than system software that you are working on. You will obviate the need to have access to your system packages and you won't mess up your system packages with whatever code you install into the site-packages directory of the virtualenv. site-packages should mostly be for system-installed python and not python that you are installing as a user.
Web APIs: Mozilla-specific documents
In the pages listed here, we provide Mozilla-specific documents about standard Web APIs. This includes notes about any Firefox-only features, or about any experiments or other deviations from the specification that may exist in Mozilla code.
WebIDL bindings
The WebIDL bindings are generated at build time based on two things: the actual WebIDL file and a configuration file that lists some metadata about how the WebIDL should be reflected into Gecko-internal code.
Working with windows in chrome code
This article describes working with multiple windows in Mozilla chrome code (XUL applications and Extensions). It contains tips and example code on opening new windows, finding an already opened window, and passing data between different windows.
XMLHttpRequest changes for Gecko1.8
This document describes some of the changes that have been made to Gecko's XMLHttpRequest implementation since version 1.7 (i.e., the version of Gecko that shipped with Firefox 1.0). These changes only apply to XUL extensions and XUL applications. They do not apply to web applications.
Cross-Platform Installer Module (XPI) is a ZIP file used to install packages, utilizing the XPInstall technology. XPI modules (so called " Bundles") are employed to install a wide variety of software, including Plugins, Extensions, Themes, and Thunderbird dictionaries.
Zombie compartments
This page tells you how to detect and avoid zombie compartments, which are a particular kind of memory leak. They can be caused by bugs in Firefox itself, or by bugs in Firefox add-ons.