[Jslib] JSLib Uninstaller Documentation

Neil Deakin neildeakin at sympatico.ca
Wed Dec 10 18:17:07 EST 2003


The JSLib Uninstall Wizard

The following documents the new Uninstall Wizard feature of JSLib.
This info will probably be posted at jslib.mozdev.org somewhere at
some point.

The uninstaller works in both Mozilla and Mozilla Firebird, or
other Mozilla-based applications. It can be used to uninstall
packages and extensions.

The uninstaller has been tested with a number of existing Mozilla
utilities, and generally works. There are a few bits of things that
are not uninstalled in some cases. It has been tested with Preferential,
Tab Browser Extensions, ThingsTheyLeftOut, GoogleBar and the
Amazon Browser.

It works for components installed in the profile, the application,
or elsewhere.

To add an uninstaller to your package, you will need to provide
some UI for doing so as JSLib does not provide this. You will need
to include jslib.js, using the script tag, as in:

<script src="chrome://jslib/content/jslib.js"/>

This script contains a function called 'jslibUninstall' which
can be called to invoke an Uninstall Wizard. The function takes
one argument, the package name to uninstall. For example:

jslibUninstall('chatzilla');

The call above will uninstall Chatzilla. The package name is
the one specified in contents.rdf file for your package, meaning
the first word in the chrome URL. Currently, only packages can
be uninstalled, themes and locales are not supported. However,
the skin and locale part of a package will be uninstalled along
with the package. For example, Chatzilla includes the content,
skin and locale parts with its installation. All will be removed.
However, a separate theme such as Orbit that skins multiple
packages cannot currently be uninstalled.

The wizard has two screens. The first displays some introductory
text and a Show Files button. When the button is pressed, a list of
the files that will be deleted is displayed. When the Next button
is pressed, the second screen is shown. This displays a progress bar as
the files are deleted and the package is uninstalled. The user can then
click Finish to close the wizard. For most packages, uninstallation
will take less than a second so the progress bar will fill up quickly.

Note that all Mozilla windows will be closed during the uninstallation
so that it is less likely that files that need to deleted will still be
open.

The uninstaller will do the following:
  - remove overlays that were specified in the contents.rdf files.
  - remove the chrome registration of the package.
  - delete the main JAR files used.

The package is not removed from the version registry since there
isn't a scriptable interface to it.

It is assumed that you have used the conventional resource URIs when
creating the contents.rdf file. For example, 'urn:mozilla:package:xxx'.

Sometimes applications will have additional files to uninstall. These
can be specified in the contents.rdf file used by the package. List the
files to uninstall in a Seq using the predicate
http://www.mozilla.org/rdf/chrome#uninstallInfo.

For example, using typical usage:

  <RDF:Description about="urn:mozilla:package:camilla"
                   chrome:name="camilla"
                   chrome:displayName="Camilla News Reader"
          ...
    >
    <chrome:uninstallInfo>
      <RDF:Seq>
        <RDF:li>special/dictionary.txt</RDF:li>
        <RDF:li>special</RDF:li>
        <RDF:li>ComsD:libCamilla.so</RDF:li>
        <RDF:li>ComsD:camilla.xpt</RDF:li>
      </RDF:Seq>
    </chrome:uninstallInfo>
  </RDF:Description>

The above will delete the file 'special/dictionary.txt'. This file
is a relative path that is relative to the Mozilla directory.
Directories such as 'special' can also be deleted. They will not be
deleted if they are not empty. You must specify the files in the
directory separately before the directory itself.

The last two files use the form key:file. The key is any of a number
of values used by the Mozilla directory service component to locate
directories. The keys are listed in:

http://lxr.mozilla.org/seamonkey/source/xpcom/io/nsDirectoryServiceDefs.h
http://lxr.mozilla.org/seamonkey/source/xpcom/io/nsAppDirectoryServiceDefs.h

and also in:

http://www.mozdev.org/lxr/http/source/jslib/libraries/io/dirUtils.js#L47

In the example above, the files use the key 'ComsD' which refers to the
Mozilla components directory.

You do not need to specify the JAR files to be deleted. They will
automatically be uninstalled. This means that most extensions should not
need to adjust the contents.rdf file at all.

Sometimes, you will want to do additional custom cleanup. You can supply
a callback function which will be called during uninstallation:

jslibUninstall('chatzilla', callbackFunction);

NOTE: The function will be called twice during uninstallation!

The function will be called with two arguments:

function callbackFunction(filesList, stage)
{
  ...
}

The first argument is the list of files to be uninstalled. The list is
an array of nsIFile objects. You have an opportunity to add or remove
items from the list. The second argument indicates which stage of
uninstallation is occuring. The first stage runs when the wizard first
appears. This stage is responsible for gathering the list of files to
delete to display in the window. In this case, the stage argument will
be false. The second stage occurs when the progress bar appears, and
the package is being uninstalled. If this case, the stage argument
will be true.

So, if stage is false, you should add or remove any items to the files
list. If stage is true, you should perform any additional uninstall
steps such as removing preferences. Note that once you have added
files in the first stage, you shouldn't add them again in the
second stage.

The multiple stage thing may seem weird but it seems better than using
multiple callback functions.

If any issues are found, please file bugs:
  http://jslib.mozdev.org/bugs.html

Some known issues:
  - doesn't remove skin component references for profile-installed packages.
  - crashes if uninstaller is run twice per session.
  - the wizard buttons should be labeled better.

/ Neil




More information about the Jslib mailing list