Repackaging Firefox

Notice: The article is about repackaging Firefox 2.0 and is obsolete when working on 3.x repackaging.

Firefox can be customized for the needs of a particular group of users (for example, your organization's employees or clients). Because Firefox is designed from the ground up for extensibility and customization, this process is simple and easy to maintain.

Important legal considerations

Before you get started, it is very important to know and abide by the legal requirements for distributing Firefox. You must have written authorization from Mozilla to distribute a modified version of Firefox. To do this, please contact [email protected].

Getting started

Now, on to the technical details. The following diagram represents an overview of the process and the pieces involved:

Image:Repackaging overview graph-1.jpg

You will need the following to get started:

A Macintosh computer (even for repackaging Windows or Linux only); it may be either PowerPC or Intel based.
The repackager tool. Currently that page mentions only Firefox 1.5.x, but it supports Firefox 2.
The pristine Firefox 2 installer files (Windows .exe, Mac .dmg, or Linux .tar.gz) for each of the locales you need. At the time of writing this document, the latest builds are here.
A "distro" extension that makes the changes you desire.

Once you have all the ingredients, the customization process is quite easy:

Download the Firefox installer.
Install the repackager tool like you would any Mac application. Make sure it starts up and launches the GUI.
Put together your extension that customizes Firefox.

The distro extension

All the changes you will want to make (for example, changing the default homepage or adding default bookmarks) can be encapsulated into a Firefox extension. We call this extension a "distro extension" (sometimes abbreviated as "DEX"), because it is used to create a new "distribution" of Firefox, with different branding, etc. Using an extension makes it far easier to keep track of your changes easily when the time comes to upgrade to new versions of Firefox, and also ensures, when set-up correctly, that users are able to safely receive Firefox updates from Mozilla. More about this below.

While the aim of this article is not to fully document how to make an extension (for that, try this section of the Mozilla Developer Center), here is a basic tutorial to get you started, and some tips specific for creating a DEX.

If you already have an extension that you want to bundle with Firefox, and don't want to bundle an extra extension solely to set a few defaults, you can do everything you need to do in your existing extension. However, it's still recommended that you look through this tutorial, as it contains tips specific for creating extensions of this type, and there are a few options that you will need to set to ensure a smooth upgrade path for users. At the very least, don't skip the "Important Extension Preferences" section below.

Sample DEX

The best way to get started is probably to look at a simple DEX and modify it for your own purposes.

Download the sample.

XPI files are specially crafted ZIP files in disguise. You can use any ZIP program (WinZIP on Windows, zip on Mac or Linux, etc) to extract it. This XPI has the following contents

chrome.manifest
components/PartnerBookmarks.js
defaults/preferences/partner.js
install.rdf
locale/ar/partner.properties
locale/cs/partner.properties
locale/da/partner.properties
locale/de/partner.properties
locale/el/partner.properties
locale/en-GB/partner.properties
locale/en-US/partner.properties
locale/es-AR/partner.properties
locale/es-ES/partner.properties
locale/fi/partner.properties
locale/fr/partner.properties
locale/he/partner.properties
locale/hu/partner.properties
locale/it/partner.properties
locale/ja/partner.properties
locale/ja-JP-mac/partner.properties
locale/ko/partner.properties
locale/nb-NO/partner.properties
locale/nl/partner.properties
locale/pl/partner.properties
locale/pt-BR/partner.properties
locale/pt-PT/partner.properties
locale/ru/partner.properties
locale/sk/partner.properties
locale/sv-SE/partner.properties
locale/tr/partner.properties
locale/zh-CN/partner.properties
locale/zh-TW/partner.properties
partner-bookmarks.xml

One by one, the files listed above are:

chrome.manifest

Contains a specialized listing of the contents of the XPI.

components/PartnerBookmarks.js

From the CCK extension, and it allows us to drop in default bookmarks at profile creation. You should not need to edit this file.

defaults/preferences/partner.js

Default preferences for this DEX.

install.rdf

Meta-information about your extension, such as the creator (your organization), a unique ID, and which versions of Firefox are supported.

locale/*/partner.properties

For preferences which need to be localized, there needs to be an entry in each of the properties files with the desired value for that locale.

If the value is the same for *all* locales, it can be set in the partner.js file itself, see the section "Preferences" for more information.

partner-bookmarks.xml

Default bookmarks are set here.

And that's all you need! Take a moment and browse through the files, and don't forget to check MDC for reference material.

Locales

There is a difference between the locales you plan to distribute installers for (and will therefore need to repack), and the locales supported by your DEX. If possible, we recommend you have your DEX support the full set of locales that Firefox supports.

The reason is that if you create and ship a DEX that supports 2 locales (for example), and later decide to ship on a 3rd locale, you will need to re-create the DEX to support it. That means that you will need to change the version of the DEX, and that will cause any users with the earlier version to get unnecessarily upgraded.

On the other hand, if you create a DEX which supports all locales, you can only ship on a few, and later expand your set without any upgrade hassles.

Of course, this strategy only works when your strings either do not need localization, or are programmatically localizable (for example, simply adding the locale to a URL, like https://<locale>.example.com/). But it's something to keep in mind when planning your locale support.

Preferences

Preferences are one of the two main things you will want to set in your extension (the other is bookmarks). There are two kinds of preferences in Firefox, both set in the partner.js file:

Localizable preferences, which have a value of a chrome:// URI pointing to the properties file where Firefox can fetch the localized value from.
Non-localizable preferences, which simply have the value in partner.js directly.

It is possible to set a value for localizable preferences directly in the partner.js file, like this:

pref("localizable.preference.name", "data:text/plain,localizable.preference.name=Some value.");

Then, a properties file is not used (or needed at all) for that preference. Therefore, if *all* of your preferences can use the same values, you do not need to include any properties files at all.

Note that you must know which preferences are localizable and which ones aren't. See the MDC documentation for more information on them.

Important Extension Preferences

There is a small set of preferences which will be given to you by Mozilla. They help Mozilla track your distribution, and plan upgrades accordingly. They allow for upgrades to be delivered by Mozilla specifically for your distribution, if need be, and because of that they are the most important preferences you need to set.

Mozilla will provide you with the values you will need here. Note that the app.partner.'name' setting uses the same value for both the name and the value of the preference.

All of these settings are non-localizable, so they are set directly in partner.js and do not need to be in the properties file.

mozilla.partner.id=<name>
app.partner.<name>=<name>
app.distributor=<name>
app.distributor.channel=<name>

Other Preferences

Some settings are commonly set in partner distributions. This is not meant to be a comprehensive list of preferences, however. If you find a preference you think is generally useful to most partner repacks, please add it below, using the same style:

Localizable preferences

browser.startup.homepage=<string>
browser.startup.homepage_reset=<string>

URL for the default homepage, and what the homepage gets reset to when the user hits "Restore to default" in the preferences. These should both be the same URL.

startup.homepage_welcome_url=<string>

URL to the first-run page. This is loaded in addition to the homepage, the very first time that Firefox is run.

browser.search.defaultenginename=<string>

Name of the default search engine. Note that this does not change the order of the search engines in the drop-down, only selects the default. Capitalization is significant.