JAR Packaging

  • Revision slug: JAR_Packaging
  • Revision title: JAR Packaging
  • Revision id: 38427
  • Created:
  • Creator: Mkmelin
  • Is current revision? No
  • Comment windows support chrome format "symlink" since bug 634596; 9 words added, 6 words removed

Revision Content

{{ Outdated("It was last updated in 2005.") }}

During the build process, various chrome files are collected into dist/bin/chrome. These files define the user interface of the application, and include XUL, JavaScript, DTDs (for localization), CSS, XBL, and images. The build system automates the process of building the chrome files through manifest files named jar.mn.

Chrome packaging formats

There are different formats that chrome files can take. Each has its advantages and disadvantages:

Format Advantages Disadvantages
JAR packaging (default) Most efficient. Chrome files are combined into a small number of JAR archives (also known as ZIP files). This allows easier caching and reduces the number of open filehandles on the system. Creating patches from the resulting files can be very difficult.
Flat-file chrome Good for testing purposes and experimental use, because flat chrome allows easier editing, diffing, and patching. Not as efficient as JAR packaging.
Symlinked flat chrome Similar to flat chrome, symlinked chrome allows easy editing and patching of the mozilla source tree. It also saves some disk space. Uses symlinks for platforms that support real symlinks. On windows hardlinks are used. Not as efficient as JAR packaging.

When building mozilla, you can specify the chrome packaging format using the Build Configurator or manually using the configure flag --enable-chrome-format=(jar|flat|symlink)

The jar.mn format

The build system automatically looks for files names jar.mn in the same directory as a Makefile, and parses these files to create chrome.

 Example: mozilla/browser/base/jar.mn (shortened)
 
 browser.jar:
         content/browser/contents.rdf                  (content/contents.rdf)
 # Source file content/contents.rdf is copied into jar
 # file browser.jar at path content/browser/contents.rdf
         content/browser/about.png                     (content/about.png)
 *       content/browser/aboutDialog.xul               (content/aboutDialog.xul)
 # Source file content/aboutDialog.xul is passed
 # through the XUL preprocessor before being placed in the JAR
 
 classic.jar:
         skin/classic/browser/aboutDialog.css          (skin/aboutDialog.css)
         skin/classic/browser/Bookmarks-folder.png     (skin/Bookmarks-folder.png)
 
 en-US.jar:
         locale/en-US/browser/contents.rdf             (locale/contents.rdf)
 *       locale/en-US/browser/browser.dtd              (locale/browser.dtd)

Structure of JAR files

The internal structure of jar files is consistent, to allow for easy debugging. This allows us to inspect jar files (eventually) to determine what they contain, and easily rearrange packages for different product releases. For example, one product might want to integrate the content, skin and locale for its chrome into a single package (e.g. chatzilla), whereas another product might want to include the content of the first product in its content jar file, but factor off the skins in to separate jar files for extensibility.

Internally, each jar file now has one of the following 3 forms:

  • content/package-name/<path>
  • skin/skin-name/package-name/<path>
  • locale/locale-name/package-name/<path>

Each of these correspond to the 3 forms of chrome URLs:

contents.rdf and the Chrome Registry

Merely putting XUL files into JARs does not mean that these files can be accessed from a chrome:// URI. You also need to let the chrome registry know about your files. This is done using RDF and a special file named contents.rdf. Unfortunately, the RDF schema for contents.rdf is not really documented. The best way to learn it is to copy an existing example:

 Example: mozilla/extensions/venkman/resources/content/contents.rdf
 
 <RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
          xmlns:chrome="http://www.mozilla.org/rdf/chrome#">
 
   <!-- list all the packages being supplied by this jar -->
   <RDF:Seq about="urn:mozilla:package:root">
     <RDF:li resource="urn:mozilla:package:venkman"/>
   </RDF:Seq>
 
   <!-- package information -->
   <RDF:Description about="urn:mozilla:package:venkman"
         chrome:displayName="JavaScript Debugger"
         chrome:author="mozilla.org"
         chrome:localeVersion="@MOZILLA_VERSION@"
         chrome:name="venkman">
   </RDF:Description>
 
   <!-- overlay information -->
   <RDF:Seq about="urn:mozilla:overlays">
     <RDF:li resource="chrome://communicator/content/tasksOverlay.xul"/>
   </RDF:Seq>
 
   <RDF:Seq about="chrome://communicator/content/tasksOverlay.xul">
     <RDF:li>chrome://venkman/content/venkman-overlay.xul</RDF:li>
   </RDF:Seq>
 </RDF:RDF>

Whenever the chrome build system encounters a contents.rdf file, it registers the package in the global file installed-chrome.txt.

 Example: installed-chrome.txt when flat chrome packaging is selected.
 
 locale,install,url,resource:/chrome/en-US/locale/en-US/necko/
 content,install,url,resource:/chrome/comm/content/editor/
 locale,install,url,resource:/chrome/en-US/locale/en-US/editor/
 content,install,url,resource:/chrome/comm/content/navigator/
 locale,install,url,resource:/chrome/en-US/locale/en-US/navigator/
 content,install,url,resource:/chrome/toolkit/content/global/
 locale,install,url,resource:/chrome/en-US/locale/en-US/global/
 content,install,url,resource:/chrome/comm/content/communicator/
 locale,install,url,resource:/chrome/en-US/locale/en-US/communicator/
 skin,install,url,resource:/chrome/classic/skin/classic/communicator/
 skin,install,url,resource:/chrome/classic/skin/classic/editor/
 skin,install,url,resource:/chrome/classic/skin/classic/global/
 skin,install,url,resource:/chrome/classic/skin/classic/messenger/
 skin,install,url,resource:/chrome/classic/skin/classic/navigator/
 skin,install,url,resource:/chrome/blue/skin/blue/communicator/
 skin,install,url,resource:/chrome/blue/skin/blue/editor/
 skin,install,url,resource:/chrome/blue/skin/blue/global/
 skin,install,url,resource:/chrome/blue/skin/blue/messenger/
 skin,install,url,resource:/chrome/blue/skin/blue/navigator/
 skin,install,url,resource:/chrome/modern/skin/modern/communicator/
 skin,install,url,resource:/chrome/modern/skin/modern/editor/
 skin,install,url,resource:/chrome/modern/skin/modern/global/
 skin,install,url,resource:/chrome/modern/skin/modern/messenger/
 skin,install,url,resource:/chrome/modern/skin/modern/navigator/
 skin,install,select,classic/1.0 
 locale,install,select,en-US 
 content,install,url,resource:/chrome/messenger/content/messenger/
 locale,install,url,resource:/chrome/en-US/locale/en-US/messenger/

Original Document Information

  • Author(s): Warren Harris
  • Other Contributors: Benjamin Smedberg
  • Last Updated Date: Feb 7, 2005
  • Copyright Information: Portions of this content are © 1998–2007 by individual mozilla.org contributors; content available under a Creative Commons license | Details.

{{ languages( { "ja": "ja/JAR_Packaging" } ) }}

Revision Source

<p>{{ Outdated("It was last updated in 2005.") }}</p>
<p>During the build process, various <em>chrome</em> files are collected into dist/bin/chrome. These files define the user interface of the application, and include <a href="/en/XUL" title="en/XUL">XUL</a>, <a href="/en/JavaScript" title="en/JavaScript">JavaScript</a>, DTDs (for <a href="/en/Localization" title="en/Localization">localization</a>), CSS, XBL, and images. The build system automates the process of building the chrome files through manifest files named <code>jar.mn</code>.</p>
<h3 name="Chrome_packaging_formats">Chrome packaging formats</h3>
<p>There are different formats that chrome files can take. Each has its advantages and disadvantages:</p>
<table class="fullwidth-table"> <tbody> <tr> <th>Format</th> <th>Advantages</th> <th>Disadvantages</th> </tr> <tr> <td>JAR packaging (default)</td> <td>Most efficient. Chrome files are combined into a small number of JAR archives (also known as ZIP files). This allows easier caching and reduces the number of open filehandles on the system.</td> <td>Creating patches from the resulting files can be very difficult.</td> </tr> <tr> <td>Flat-file chrome</td> <td>Good for testing purposes and experimental use, because flat chrome allows easier editing, diffing, and patching.</td> <td>Not as efficient as JAR packaging.</td> </tr> <tr> <td>Symlinked flat chrome</td> <td>Similar to flat chrome, symlinked chrome allows easy editing and patching of the mozilla source tree. It also saves some disk space.</td> <td>Uses symlinks for platforms that support real symlinks. On windows hardlinks are used. Not as efficient as JAR packaging.</td> </tr> </tbody>
</table>
<p>When building mozilla, you can specify the chrome packaging format using the <a class="external" href="http://webtools.mozilla.org/build/config.cgi">Build Configurator</a> or manually using the configure flag --enable-chrome-format=(jar|flat|symlink)</p>
<h3 name="The_jar.mn_format">The <em>jar.mn</em> format</h3>
<p>The build system automatically looks for files names <em>jar.mn</em> in the same directory as a Makefile, and parses these files to create chrome.</p>
<pre class="eval"> <strong>Example: mozilla/browser/base/jar.mn (shortened)</strong>
 
 browser.jar:
         content/browser/contents.rdf                  (content/contents.rdf)
 <span class="highlightgreen"># Source file content/contents.rdf is copied into jar
 # file browser.jar at path content/browser/contents.rdf</span>
         content/browser/about.png                     (content/about.png)
 *       content/browser/aboutDialog.xul               (content/aboutDialog.xul)
 <span class="highlightgreen"># Source file content/aboutDialog.xul is passed
 # through the XUL preprocessor before being placed in the JAR</span>
 
 classic.jar:
         skin/classic/browser/aboutDialog.css          (skin/aboutDialog.css)
         skin/classic/browser/Bookmarks-folder.png     (skin/Bookmarks-folder.png)
 
 en-US.jar:
         locale/en-US/browser/contents.rdf             (locale/contents.rdf)
 *       locale/en-US/browser/browser.dtd              (locale/browser.dtd)
</pre>
<h3 name="Structure_of_JAR_files">Structure of JAR files</h3>
<p>The internal structure of jar files is consistent, to allow for easy debugging. This allows us to inspect jar files (eventually) to determine what they contain, and easily rearrange packages for different product releases. For example, one product might want to integrate the content, skin and locale for its chrome into a single package (e.g. chatzilla), whereas another product might want to include the content of the first product in its content jar file, but factor off the skins in to separate jar files for extensibility.</p>
<p>Internally, each jar file now has one of the following 3 forms:</p>
<ul> <li><code>content/package-name/&lt;path&gt;</code></li> <li><code>skin/skin-name/package-name/&lt;path&gt;</code></li> <li><code>locale/locale-name/package-name/&lt;path&gt;</code></li>
</ul>
<p>Each of these correspond to the 3 forms of chrome URLs:</p>
<ul> <li><code><a class=" external" href="chrome://package-name/content/" rel="freelink">chrome://package-name/content/</a>&lt;path&gt;</code></li> <li><code><a class=" external" href="chrome://package-name/skin/" rel="freelink">chrome://package-name/skin/</a>&lt;path&gt;</code></li> <li><code><a class=" external" href="chrome://package-name/locale/" rel="freelink">chrome://package-name/locale/</a>&lt;path&gt;</code></li>
</ul>
<h3 name="contents.rdf_and_the_Chrome_Registry">contents.rdf and the Chrome Registry</h3>
<p>Merely putting XUL files into JARs does not mean that these files can be accessed from a chrome:// URI. You also need to let the chrome registry know about your files. This is done using <a href="/en/RDF" title="en/RDF">RDF</a> and a special file named <code>contents.rdf</code>. Unfortunately, the RDF schema for <code>contents.rdf</code> is not really documented. The best way to learn it is to copy an existing example:</p>
<pre class="eval"> <strong>Example: mozilla/extensions/venkman/resources/content/contents.rdf</strong>
 
 &lt;RDF:RDF xmlns:RDF="<span class="nowiki">http://www.w3.org/1999/02/22-rdf-syntax-ns#</span>"
          xmlns:chrome="<span class="nowiki">http://www.mozilla.org/rdf/chrome#</span>"&gt;
 
   <span class="highlightgreen">&lt;!-- list all the packages being supplied by this jar --&gt;</span>
   &lt;RDF:Seq about="urn:mozilla:package:root"&gt;
     &lt;RDF:li resource="urn:mozilla:package:venkman"/&gt;
   &lt;/RDF:Seq&gt;
 
   <span class="highlightgreen">&lt;!-- package information --&gt;</span>
   &lt;RDF:Description about="urn:mozilla:package:venkman"
         chrome:displayName="JavaScript Debugger"
         chrome:author="mozilla.org"
         chrome:localeVersion="@MOZILLA_VERSION@"
         chrome:name="venkman"&gt;
   &lt;/RDF:Description&gt;
 
   <span class="highlightgreen">&lt;!-- overlay information --&gt;</span>
   &lt;RDF:Seq about="urn:mozilla:overlays"&gt;
     &lt;RDF:li resource="<a class=" external" href="chrome://communicator/content/tasksOverlay.xul" rel="freelink">chrome://communicator/content/tasksOverlay.xul</a>"/&gt;
   &lt;/RDF:Seq&gt;
 
   &lt;RDF:Seq about="<a class=" external" href="chrome://communicator/content/tasksOverlay.xul" rel="freelink">chrome://communicator/content/tasksOverlay.xul</a>"&gt;
     &lt;RDF:li&gt;<a class=" external" href="chrome://venkman/content/venkman-overlay.xul" rel="freelink">chrome://venkman/content/venkman-overlay.xul</a>&lt;/RDF:li&gt;
   &lt;/RDF:Seq&gt;
 &lt;/RDF:RDF&gt;
</pre>
<p>Whenever the chrome build system encounters a <code>contents.rdf</code> file, it registers the package in the global file <code>installed-chrome.txt</code>.</p>
<pre class="eval"> <strong>Example: installed-chrome.txt when flat chrome packaging is selected.</strong>
 
 locale,install,url,resource:/chrome/en-US/locale/en-US/necko/
 content,install,url,resource:/chrome/comm/content/editor/
 locale,install,url,resource:/chrome/en-US/locale/en-US/editor/
 content,install,url,resource:/chrome/comm/content/navigator/
 locale,install,url,resource:/chrome/en-US/locale/en-US/navigator/
 content,install,url,resource:/chrome/toolkit/content/global/
 locale,install,url,resource:/chrome/en-US/locale/en-US/global/
 content,install,url,resource:/chrome/comm/content/communicator/
 locale,install,url,resource:/chrome/en-US/locale/en-US/communicator/
 skin,install,url,resource:/chrome/classic/skin/classic/communicator/
 skin,install,url,resource:/chrome/classic/skin/classic/editor/
 skin,install,url,resource:/chrome/classic/skin/classic/global/
 skin,install,url,resource:/chrome/classic/skin/classic/messenger/
 skin,install,url,resource:/chrome/classic/skin/classic/navigator/
 skin,install,url,resource:/chrome/blue/skin/blue/communicator/
 skin,install,url,resource:/chrome/blue/skin/blue/editor/
 skin,install,url,resource:/chrome/blue/skin/blue/global/
 skin,install,url,resource:/chrome/blue/skin/blue/messenger/
 skin,install,url,resource:/chrome/blue/skin/blue/navigator/
 skin,install,url,resource:/chrome/modern/skin/modern/communicator/
 skin,install,url,resource:/chrome/modern/skin/modern/editor/
 skin,install,url,resource:/chrome/modern/skin/modern/global/
 skin,install,url,resource:/chrome/modern/skin/modern/messenger/
 skin,install,url,resource:/chrome/modern/skin/modern/navigator/
 skin,install,select,classic/1.0 
 locale,install,select,en-US 
 content,install,url,resource:/chrome/messenger/content/messenger/
 locale,install,url,resource:/chrome/en-US/locale/en-US/messenger/
</pre>
<div class="originaldocinfo"> <h2 name="Original_Document_Information">Original Document Information</h2> <ul> <li>Author(s): Warren Harris</li> <li>Other Contributors: <a class="link-mailto" href="mailto:benjamin@smedbergs.us">Benjamin Smedberg</a></li> <li>Last Updated Date: Feb 7, 2005</li> <li>Copyright Information: Portions of this content are © 1998–2007 by individual mozilla.org contributors; content available under a Creative Commons license | <a class="external" href="http://www.mozilla.org/foundation/licensing/website-content.html">Details</a>.</li> </ul>
</div>

<p>{{ languages( { "ja": "ja/JAR_Packaging" } ) }}</p>
Revert to this revision