Overview

Provide the ability to install multiple items contained in a single package. This can be accomplished with a trimmed down version of the existing install manifest format and with very minimal changes through the leveraging of the existing code and user interface for item installation.

Work is happening in bug 298498

Notes

• The acronym MiX is used for brevity and refers to a Multiple Item XPI.
• For brevity this document uses the term item for all items that would be supported by a MiX (e.g. extensions and themes).
• A MiX will only install extensions and themes that are packaged for the Extension Manager (e.g. they have a valid install.rdf manifest).
• Most of the documentation is shamelessly stolen from existing extension docs and then modified if needed.

Q: are there others besides extensions and themes that should be able to use this and if so do they have requirements that are not accounted for?

MiX File Layout

The MiX file layout is a simplified version of the extension file layout. A MiX may contain both extensions (e.g. xpi file extension) and themes (e.g. jar file extension) and the xpi file extension is used for the MiX itself in order to take advantage of the existing security available from extension installation such as the 3 second countdown before a user can start the install process. The basic structure is shown below:

  packages.xpi
    install.rdf
    extension1.xpi
    extension2.xpi
    theme1.jar
    theme2.jar
    ...

The Extension Manager will read the install.rdf manifest at the top of your MiX XPI to determine that the package is a MiX and then start the installation of the individual packages it contains automatically. No other files besides the install.rdf manifest and the packages with a jar and xpi file extension will be extracted or utilized.

install.rdf

Your install.rdf manifest will look something like this:

  <?xml version="1.0"?>

  <RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
       xmlns:NC="http://home.netscape.com/NC-rdf#"
       xmlns:em="http://www.mozilla.org/2004/em-rdf#">

    <Description about="urn:mozilla:install-manifest">
      <em:id>MyMiX@mydomain.org</em:id>
      <em:name>Name of this MiX</em:name>
      <em:version>2.1</em:version>

      <!-- nsIUpdateItem type for a MiX -->
      <em:type NC:parseType="Integer">32</em:type>

      <!-- Firefox -->
      <em:targetApplication>
        <Description>
          <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
          <em:minVersion>1.0</em:minVersion>
          <em:maxVersion>2.0.0.*</em:maxVersion>
        </Description>
      </em:targetApplication>

      <!-- Thunderbird -->
      <em:targetApplication>
        <Description>
          <em:id>{3550f703-e582-4d05-9a08-453d09bdfdc6}</em:id>
          <em:minVersion>1.0</em:minVersion>
          <em:maxVersion>2.0.0.*</em:maxVersion>
        </Description>
      </em:targetApplication>
    </Description>

  </RDF>

Compulsory install.rdf Properties

Your install.rdf file must have these properties:

em:id
The string ID of the MiX. The preferred format for an ID is packagename@vendor.tld (allowed characters: a-z A-Z 0-9 - . @ _ { } *) or as a GUID which can be created by using guidgen (Windows), uuidgen (Unix) or "botbot uuid" on IRC. e.g.

  <em:id>MyMiX@mydomain.org</em:id>

Note: em:id is required in order to check for a version compatibility update and also to ease the reuse of existing code.

em:name
The name of the MiX - intended for display in the UI during installation. e.g.

  <em:name>My MiX</em:name>

Note: em:name is used when dsplaying errors and in the xpinstall dialog when a MiX is installed during startup by placing it in the extensions directory.

em:version
A Firefox Version Format (FVF) string identifying the version that is being supplied by this MiX. e.g.

  <em:version>4.6</em:version>

Note: em:version is used when dsplaying errors and in the xpinstall dialog when a MiX is installed during startup by placing it in the extensions directory.

em:targetApplication
An object specifying an application targeted by this MiX. This means that all of the packages contained by the MiX will work with the application identified by the GUID (em:id), from the min version (em:minVersion) up to and including the max version (em:maxVersion). A MiX manifest must specify at least one of these properties, and may specify more if the MiX targets multiple apps that support this extension system (e.g. Firefox and Thunderbird). For each targetApplication the minVersion specified should be the highest minVersion and the maxVersion specified should be the lowest maxVersion from all of the items contained by the MiX. If this is not done then any items that are not compatible will not be installed unless a compatibility check discovers updated compatibility information that makes it compatible. e.g.

  <em:targetApplication>
    <Description>
      <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
      <em:minVersion>1.0+</em:minVersion>
      <em:maxVersion>1.0+</em:maxVersion>
    </Description>
  </em:targetApplication>

em:type
An integer value representing the type of item. For MiX's this value must always be 32, e.g.

  <em:type NC:parseType="Integer">32</em:type>

Note: The Extension Manager requires that em:type is specfied as an integer which was not previously a requirement and allowed specifying em:type as <em:type>32</em:type> instead.

Optional install.rdf Properties

Your install.rdf file may have these properties in addition to the ones above:

em:updateURL A link to a custom RDF file that specifies version specific compatibility updates to the MiX which will only be used duriing installation e.g.

  <em:updateURL>http://www.foo.com/update.rdf</em:updateURL>

Installation

Installation can be performed using any of the existing methods used for installing extensions. The same xpinstall user interface is used for installing a MiX (the individual packages contained in the MiX will not be listed). This also allows displaying of signing information for the MiX if applicable.

If a MiX installation displays a manager (e.g. Extension / Theme Manager) then after the download of the MiX completes the manager displays the individual items contained by the MiX in the same manner that it would if the user had chosen to install multiple items simultaneously. The manager will not display the MiX in the list of items after the download of the MiX is completed.