Structure of an installable bundle

  • Revision slug: Bundles
  • Revision title: Structure of an installable bundle
  • Revision id: 72301
  • Created:
  • Creator: penguin_traveller
  • Is current revision? No
  • Comment 30 words added, 3 words removed

Revision Content

 

XULRunner applications, extensions, and themes all share a common directory structure, and in some cases the same bundle can be used as a standalone XULRunner application as well as an installable application extension.

 

Basic Structure of a Bundle

A bundle may include any of the following files:

/install.rdf                        Extension/Theme Install Manifest
/application.ini                    Application Launch Manifest
/components/*                       Component and XPT Files      (>=1.7)
/defaults/preferences/*.js          Default Preferences          (>=1.7)
/plugins/*                          NPAPI Plugins                (>=1.8)
/chrome.manifest                    Chrome Registration Manifest (>=1.8)
/chrome/icons/default/*             Window Icons                 (>=1.8)

Of course, an extension need not (and normally won't) have all of these directories. Themes are limited for security reasons, and can normally only provide a chrome.manifest which registers the theme and a JAR file.

Platform-specific Subdirectories

In some cases a single extension or application may wish to include binary component or plugins for multiple platforms, or theme authors might want to include multiple platform-specific JAR files. To facilitate the first case, the extension/app loader has special sub-directories specifically for platform-specific files (starting with Toolkit/Gecko 1.8, Firefox/Thunderbird 1.5). The platform string is defined during the toolkit build process to a value unique for the combination of operating system, processor architecture and compiler. The format of the platform string is:

{OS_TARGET}_{TARGET_XPCOM_ABI}

All of the files which are loaded from the main extension directory are loaded from the subdirectory

/platform/{platform string}

if it exists. For example, if a plugin vendor wanted to make a plugin available for consumer computers running Linux(of the form: /platform/Linux*/), Macintosh(of the form: /platform/Darwin*/), and Windows(of the form: /platform/WIN*/), it would provide the following files:

/platform/Linux_x86-gcc3/plugins/libMyPlugin.so
/platform/WINNT_x86-msvc/plugins/MyPlugin.dll
/platform/Darwin_ppc-gcc3/plugins/libMyPlugin.dylib

Because XPT files are not platform-specific, any associated XPT files would go in the generic components directory:

/components/MyPlugin.xpt

If an extension has non-binary platform-specific code (such as code which uses the windows registry from script), it can also use just the operating system identifier as a platform-subdirectory:

/platform/WINNT/components/registerDoctype.js

When platform-specific JAR files are used, each platform directory should have its own chrome.manifest file:

chrome.manifest
chrome/mytheme-base.jar
platform/Darwin/chrome.manifest
platform/Darwin/chrome/mytheme-mac.jar
platform/WINNT/chrome.manifest
platform/WINNT/chrome/mytheme-win.jar

The app/extension loader processes the base directory first, followed by the applicable platform directories (first /{OS_TARGET}/, then /{OS_TARGET}_{TARGET_XPCOM_ABI}/). When default preferences are defined in several directories, the ones loaded later overwrite the earlier ones.

Application-specific Extension Files

In addition to the extension files listed above, applications may read additional files from extensions. For example, Firefox 1.5 and greater will read Sherlock search plugins from

/searchplugins/*.src

Firefox 2 and greater will additionally read MozSearch and OpenSearch plugins from

/searchplugins/*.xml

and Myspell dictionaries from

/dictionaries/*.{aff|dic}

Official References for Toolkit API

{{ :en/Toolkit_API/Official_References() }}

{{ languages( { "es": "es/Bundles", "fr": "fr/Bundles", "ja": "ja/Bundles", "ko": "ko/Bundles", "pl": "pl/Paczki" } ) }}

Revision Source

<p> </p>
<p><a href="/en/XUL_Application_Packaging" title="en/XUL_Application_Packaging">XULRunner applications</a>, <a href="/en/Extensions" title="en/Extensions">extensions</a>, and <a href="/en/Themes" title="en/Themes">themes</a> all share a common directory structure, and in some cases the same bundle can be used as a standalone XULRunner application as well as an installable application extension.</p>
<p> </p>
<h3 name="Basic_Structure_of_a_Bundle">Basic Structure of a Bundle</h3>
<p>A bundle may include any of the following files:</p>
<pre class="eval">/<a href="/en/Install_Manifests" title="en/Install_Manifests">install.rdf</a>                        <em>Extension/Theme Install Manifest</em>
/<a href="/en/XUL_Application_Packaging" title="en/XUL_Application_Packaging">application.ini</a>                    <em>Application Launch Manifest</em>
/components/*                       <em>Component and XPT Files</em>      <a href="/en/Gecko#Versions_of_Gecko" title="en/Gecko#Versions_of_Gecko">(&gt;=1.7)</a>
<a href="/en/Building_an_Extension#Defaults_Files" title="en/Building_an_Extension#Defaults_Files">/defaults/preferences/*.js</a>          <em>Default Preferences</em>          <a href="/en/Gecko#Versions_of_Gecko" title="en/Gecko#Versions_of_Gecko">(&gt;=1.7)</a>
/plugins/*                          <em>NPAPI Plugins</em>                <a href="/en/Gecko#Versions_of_Gecko" title="en/Gecko#Versions_of_Gecko">(&gt;=1.8)</a>
/<a href="/en/Chrome_Registration#The_Chrome_Registry" title="en/Chrome_Registration#The_Chrome_Registry">chrome.manifest</a>                    <em>Chrome Registration Manifest</em> <a href="/en/Gecko#Versions_of_Gecko" title="en/Gecko#Versions_of_Gecko">(&gt;=1.8)</a>
/<a href="/en/Window_icons" title="en/Window_icons">chrome/icons/default/*</a>             <em>Window Icons</em>                 <a href="/en/Gecko#Versions_of_Gecko" title="en/Gecko#Versions_of_Gecko">(&gt;=1.8)</a>
</pre>
<p>Of course, an extension need not (and normally won't) have all of these directories. Themes are limited for security reasons, and can normally only provide a <a href="/en/Chrome_Registration" title="en/Chrome_Registration">chrome.manifest</a> which registers the theme and a JAR file.</p>
<h3 name="Platform-specific_Subdirectories">Platform-specific Subdirectories</h3>
<p>In some cases a single extension or application may wish to include binary component or plugins for multiple platforms, or theme authors might want to include multiple platform-specific JAR files. To facilitate the first case, the extension/app loader has special sub-directories specifically for platform-specific files (starting with Toolkit/Gecko 1.8, Firefox/Thunderbird 1.5). The platform string is defined during the toolkit build process to a value unique for the combination of operating system, processor architecture and compiler. The format of the platform string is:</p>
<pre class="eval"><em>{<a href="/en/OS_TARGET" title="en/OS_TARGET">OS_TARGET</a>}</em>_<em>{<a href="/en/XPCOM_ABI" title="en/XPCOM_ABI">TARGET_XPCOM_ABI</a>}</em>
</pre>
<p>All of the files which are loaded from the main extension directory are loaded from the subdirectory</p>
<pre class="eval">/platform/<em>{platform string}</em>
</pre>
<p>if it exists. For example, if a plugin vendor wanted to make a plugin available for consumer computers running Linux(of the form: /platform/Linux*/), Macintosh(of the form: /platform/Darwin*/), and Windows(of the form: /platform/WIN*/), it would provide the following files:</p>
<pre class="eval">/platform/Linux_x86-gcc3/plugins/libMyPlugin.so
/platform/WINNT_x86-msvc/plugins/MyPlugin.dll
/platform/Darwin_ppc-gcc3/plugins/libMyPlugin.dylib
</pre>
<p>Because XPT files are not platform-specific, any associated XPT files would go in the generic components directory:</p>
<pre class="eval">/components/MyPlugin.xpt
</pre>
<p>If an extension has non-binary platform-specific code (such as code which uses the windows registry from script), it can also use just the operating system identifier as a platform-subdirectory:</p>
<pre class="eval">/platform/WINNT/components/registerDoctype.js
</pre>
<p>When platform-specific JAR files are used, each platform directory should have its own <code>chrome.manifest</code> file:</p>
<pre class="eval">chrome.manifest
chrome/mytheme-base.jar
platform/Darwin/chrome.manifest
platform/Darwin/chrome/mytheme-mac.jar
platform/WINNT/chrome.manifest
platform/WINNT/chrome/mytheme-win.jar
</pre>
<p>The app/extension loader processes the base directory first, followed by the applicable platform directories (first /{OS_TARGET}/, then /{<a href="/en/OS_TARGET" title="en/OS_TARGET">OS_TARGET</a>}_{<a href="/en/XPCOM_ABI" title="en/XPCOM_ABI">TARGET_XPCOM_ABI</a>}/). When default preferences are defined in several directories, the ones loaded later overwrite the earlier ones.</p>
<h3 name="Application-specific_Extension_Files">Application-specific Extension Files</h3>
<p>In addition to the extension files listed above, applications may read additional files from extensions. For example, <a href="/en/Firefox_1.5_for_developers" title="en/Firefox_1.5_for_developers">Firefox 1.5</a> and greater will read Sherlock search plugins from</p>
<pre class="eval">/searchplugins/*.src
</pre>
<p><a href="/en/Firefox_2_for_developers" title="en/Firefox_2_for_developers">Firefox 2</a> and greater will additionally read <a href="/en/Creating_MozSearch_plugins" title="en/Creating_MozSearch_plugins">MozSearch and OpenSearch plugins</a> from</p>
<pre class="eval">/searchplugins/*.xml
</pre>
<p>and Myspell dictionaries from</p>
<pre class="eval">/dictionaries/*.{aff|dic}
</pre>
<h3 name="Official_References_for_Toolkit_API">Official References for <a href="/en/Toolkit_API" title="en/Toolkit_API">Toolkit API</a></h3>
<p>{{ :en/Toolkit_API/Official_References() }}</p>
<p>{{ languages( { "es": "es/Bundles", "fr": "fr/Bundles", "ja": "ja/Bundles", "ko": "ko/Bundles", "pl": "pl/Paczki" } ) }}</p>
Revert to this revision