Repackaging Firefox

  • Revision slug: Repackaging_Firefox
  • Revision title: Repackaging Firefox
  • Revision id: 140012
  • Created:
  • Creator: V thunder
  • Is current revision? No
  • Comment Add mozilla.partner.id to the list of preferences Mozilla provides for partner repacks

Revision Content

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 licensing@mozilla.com.

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:

  1. Download the Firefox installer.
  2. Install the repackager tool like you would any Mac application. Make sure it starts up and launches the GUI.
  3. 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 puposes. Download this Image:Sample.xpi (follow the link, then right-click and select 'Save Link As...'). 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:

<tt>chrome.manifest</tt>

Contains a specialized listing of the contents of the XPI.

<tt>components/PartnerBookmarks.js</tt>

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

<tt>defaults/preferences/partner.js</tt>

Default preferences for this DEX.

<tt>install.rdf</tt>

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

<tt>locale/*/partner.properties</tt>

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 <tt>partner.js</tt> file itself, see the section "Preferences" for more information.

<tt>partner-bookmarks.xml</tt>

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 http://<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 <tt>partner.js</tt> file:

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

It is possible to set a value for localizable preferences directly in the <tt>partner.js</tt> 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 <tt>app.partner.'name'</tt> 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 <tt>partner.js</tt> 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:

Non-localizable preferences
browser.EULA.2.accepted=<boolean>

Setting this preference to false causes Firefox to present the End User License Agreement upon first-launch. The default is true, so Firefox will not prompt.

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.

Repackaging Firefox

Once you have all the required pieces in place, all you need to do is launch the repackager tool and fill in the fields to set up your customized installers.

Image:Repackager.jpg

  • The "Extension" section describes your DEX. Click the "Choose" button to select the XPI file containing your extension; the ID and Name fields will be filled out automatically.
    • When repacking Firefox 2.0.0.3 or lower, be sure to download the latest version of the repackager, which has an additional checkbox in this section to disable the migration wizard at startup. Check this if the homepage needs to be different from the default to prevent the migration wizard from overwriting it.
  • The "Additional XPI" section lets you select a second extension to bundle into your customized installer. If you don't wish to install a second extension, you can leave this blank.
  • The "Repackaging" section is where you configure the actual repackaging job itself.
    • First, set the source directory by clicking its "Choose" button. The source directory is a directory that contains the Windows installer, Mac disk image (.dmg), and/or Linux tarball of the standard Firefox that you wish to customize.
    • Second, set the destination directory to the directory into which you wish to save the customized installers.
  • The "Platforms" section lets you select the platforms for which you wish to generate customized installers. Check the boxes next to each one you want to generate. Make sure you have the standard Firefox install package in the source directory for each of these. The names of the source installer packages for each platform that are included in your source directory will appear next to each checkbox.

The repackager tool will do its work, placing the customized installers into the destination directory you specified. Please remember to obtain permission as described above before distributing your new Firefox installer.

Revision Source

<p>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.
</p>
<h3 name="Important_legal_considerations"> Important legal considerations </h3>
<p>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 licensing@mozilla.com.
</p>
<h3 name="Getting_started"> Getting started </h3>
<p>Now, on to the technical details.  The following diagram represents an overview of the process and the pieces involved:
</p><p><img alt="Image:Repackaging overview graph-1.jpg" src="File:en/Media_Gallery/Repackaging_overview_graph-1.jpg">
</p><p>You will need the following to get started:
</p>
<ul><li> A Macintosh computer (even for repackaging Windows or Linux only); it may be either PowerPC or Intel based.
</li><li> The <a class="external" href="http://benjamin.smedbergs.us/release-repackager/">repackager tool</a>.  Currently that page mentions only Firefox 1.5.x, but it supports Firefox 2.
</li><li> 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 <a class="external" href="http://stage.mozilla.org/pub/mozilla.org/firefox/releases/latest/">here</a>.
</li><li> A "distro" extension that makes the changes you desire.
</li></ul>
<p>Once you have all the ingredients, the customization process is quite easy:
</p>
<ol><li> Download the Firefox installer.
</li><li> Install the repackager tool like you would any Mac application.  Make sure it starts up and launches the GUI.
</li><li> Put together your extension that customizes Firefox.
</li></ol>
<h3 name="The_distro_extension"> The distro extension </h3>
<p>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.
</p><p>While the aim of this article is not to fully document how to make an extension (for that, try <a class="external" href="http://developer.mozilla.org/en/docs/Extensions">this section</a> of the Mozilla Developer Center), here is a basic tutorial to get you started, and some tips specific for creating a DEX.
</p><p>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.
</p>
<h4 name="Sample_DEX"> Sample DEX </h4>
<p>The best way to get started is probably to look at a simple DEX and modify it for your own puposes.  Download this <img alt="Image:Sample.xpi" src="File:en/Media_Gallery/Sample.xpi"> (follow the link, then right-click and select 'Save Link As...').  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:
</p>
<pre class="eval">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
</pre>
<p>One by one, the files listed above are:
</p><p><b><tt>chrome.manifest</tt></b>
</p><p>Contains a specialized listing of the contents of the XPI.
</p><p><b><tt>components/PartnerBookmarks.js</tt></b>
</p><p>From the CCK extension, and it allows us to drop in default bookmarks at profile creation.  You should not need to edit this file.
</p><p><b><tt>defaults/preferences/partner.js</tt></b>
</p><p>Default preferences for this DEX.
</p><p><b><tt>install.rdf</tt></b>
</p><p>Meta-information about your extension, such as the creator (your organization), a unique ID, and which versions of Firefox are supported.
</p><p><b><tt>locale/*/partner.properties</tt></b>
</p><p>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.
</p><p>If the value is the same for *all* locales, it can be set in the <tt>partner.js</tt> file itself, see the section "Preferences" for more information.
</p><p><b><tt>partner-bookmarks.xml</tt></b>
</p><p>Default bookmarks are set here.
</p><p>And that's all you need!  Take a moment and browse through the files, and don't forget to check <a class="external" href="http://developer.mozilla.org/">MDC</a> for reference material.
</p>
<h4 name="Locales"> Locales </h4>
<p>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.
</p><p>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.
</p><p>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.
</p><p>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 <span class="plain">http://&lt;locale&gt;.example.com/</span>).  But it's something to keep in mind when planning your locale support.
</p>
<h4 name="Preferences"> Preferences </h4>
<p>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 <tt>partner.js</tt> file:
</p>
<ul><li> Localizable preferences, which have a value of a <tt>chrome://</tt> URI pointing to the properties file where Firefox can fetch the localized value from.
</li><li> Non-localizable preferences, which simply have the value in <tt>partner.js</tt> directly.
</li></ul>
<p>It is possible to set a value for localizable preferences directly in the <tt>partner.js</tt> file, like this:
</p>
<pre class="eval">pref("localizable.preference.name", "data:text/plain,localizable.preference.name=Some value.");
</pre>
<p>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.
</p><p>Note that you must know which preferences are localizable and which ones aren't.  See the MDC documentation for more information on them.
</p>
<h5 name="Important_Extension_Preferences"> Important Extension Preferences </h5>
<p>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.
</p><p>Mozilla will provide you with the values you will need here.  Note that the <tt>app.partner.'name'</tt> setting uses the same value for both the name and the value of the preference.
</p><p>All of these settings are non-localizable, so they are set directly in <tt>partner.js</tt> and do not need to be in the properties file.
</p>
<pre class="eval">mozilla.partner.id=&lt;name&gt;
app.partner.&lt;name&gt;=&lt;name&gt;
app.distributor=&lt;name&gt;
app.distributor.channel=&lt;name&gt;
</pre>
<h5 name="Other_Preferences"> Other Preferences </h5>
<p>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:
</p>
<h6 name="Non-localizable_preferences"> Non-localizable preferences </h6>
<pre class="eval">browser.EULA.2.accepted=&lt;boolean&gt;
</pre>
<p>Setting this preference to false causes Firefox to present the End User License Agreement upon first-launch.  The default is true, so Firefox will not prompt.
</p>
<h6 name="Localizable_preferences"> Localizable preferences </h6>
<pre class="eval">browser.startup.homepage=&lt;string&gt;
browser.startup.homepage_reset=&lt;string&gt;
</pre>
<p>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.
</p>
<pre class="eval">startup.homepage_welcome_url=&lt;string&gt;
</pre>
<p>URL to the first-run page.  This is loaded in addition to the homepage, the very first time that Firefox is run.
</p>
<pre class="eval">browser.search.defaultenginename=&lt;string&gt;
</pre>
<p>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.
</p>
<h3 name="Repackaging_Firefox"> Repackaging Firefox </h3>
<p>Once you have all the required pieces in place, all you need to do is launch the repackager tool and fill in the fields to set up your customized installers.
</p><p><img alt="Image:Repackager.jpg" src="File:en/Media_Gallery/Repackager.jpg">
</p>
<ul><li> The "Extension" section describes your DEX.  Click the "Choose" button to select the XPI file containing your extension; the ID and Name fields will be filled out automatically.
<ul><li> When repacking Firefox 2.0.0.3 or lower, be sure to download the latest version of the repackager, which has an additional checkbox in this section to disable the migration wizard at startup.  Check this if the homepage needs to be different from the default to prevent the migration wizard from overwriting it.
</li></ul>
</li><li> The "Additional XPI" section lets you select a second extension to bundle into your customized installer.  If you don't wish to install a second extension, you can leave this blank.
</li><li> The "Repackaging" section is where you configure the actual repackaging job itself.
<ul><li> First, set the source directory by clicking its "Choose" button.  The source directory is a directory that contains the Windows installer, Mac disk image (.dmg), and/or Linux tarball of the standard Firefox that you wish to customize.
</li><li> Second, set the destination directory to the directory into which you wish to save the customized installers.
</li></ul>
</li><li> The "Platforms" section lets you select the platforms for which you wish to generate customized installers.  Check the boxes next to each one you want to generate.  Make sure you have the standard Firefox install package in the source directory for each of these.  The names of the source installer packages for each platform that are included in your source directory will appear next to each checkbox.
</li></ul>
<p>The repackager tool will do its work, placing the customized installers into the destination directory you specified.  Please remember to obtain permission as described above before distributing your new Firefox installer.
</p>
Revert to this revision