Extension Manager:Bootstrapped Extensions: Difference between revisions

Revision as of 20:30, 12 April 2010

Bootstrapped add-ons exist as a means of restricting what is available to an add-on in order to allow it to be loaded and unloaded with restarting the application.

Rationale

Current XPI add-ons cannot be unloaded without restarting the application. This is because the features that we give them (XPCOM components, chrome registration and overlays etc.) cannot be removed in a managed fashion. Loading without a restart could possibly be implemented however that really only solves a small part of the problem as updates etc. would still require restarts.

The approach taken here is to simplify what it means to be an add-on. Instead of registering XPCOM components and chrome in bootstrapped add-ons we instead do nothing except execute a bootstrap script when the add-on is loaded and call some functions on it. The add-on can do whatever it likes at that point however it must undo anything it has done when we call the bootstrap script to tell it to unload.

Declaring an Add-on as Bootstrappable

Add-ons are declared as being bootstrappable using the special em:bootstrap="true" property in the install manifest. Although any type of add-on can include this, for now it only makes sense for add-ons with em:type="2" (the default extension type) to include it. They should also include a bootstrap.js file alongside the install.rdf.

Bootstrap Events

When an add-on is loaded the bootstrap.js file is executed in a privileged sandbox which is cached until the add-on is unloaded. The scripts should contain a number of functions that will be called to notify the add-on of certain events:

Startup

Whenever an add-on needs to be loaded the platform will call a function named startup in the bootstrap script. It will be passed the following arguments:

data: A JS object containing basic information about the add-on, id, version and installPath.
reason: A number representing the reason for loading the add-on. This may be APP_STARTUP or ADDON_ENABLE.

Shutdown

Whenever an add-on needs to be unloaded the platform will call a function named shutdown in the bootstrap script. It will be passed the following arguments:

data: A JS object containing basic information about the add-on, id, version and installPath.
reason: A number representing the reason for unloading the add-on. This may be APP_SHUTDOWN or ADDON_DISABLE.

Install

The bootstrap script may include an install method and if so it will be called before the first call to startup after a particular version of an add-on is installed. It will be passed the following arguments:

data: A JS object containing basic information about the add-on, id, version and installPath.
reason: A number representing the reason for installing the add-on. This may be ADDON_INSTALLED, ADDON_UPGRADED or ADDON_DOWNGRADED.

Note that install will never be called if the add-on is never loaded.

Uninstall

The bootstrap script may include an uninstall method and if so it will be called after the last call to shutdown before a particular version of an add-on is uninstalled. It will be passed the following arguments:

data: A JS object containing basic information about the add-on, id, version and installPath.
reason: A number representing the reason for installing the add-on. This may be ADDON_UNINSTALLED, ADDON_UPGRADED or ADDON_DOWNGRADED.

Note that uninstall may be called even when add-ons are disabled or incompatible with the current application. It is important that the uninstall script be carefully written to handle APIs that may no longer be present in the application.

In some cases uninstall may never be called for an add-on. This happens when a third-party application removes the add-on while Firefox is not running.

@@ Line 1: / Line 1: @@
-Bootstrapped extensions exist as a means of restricting what is available to an extension in order to allow it to be loaded and unloaded with restarting the application.
+__NOTOC__Bootstrapped add-ons exist as a means of restricting what is available to an add-on in order to allow it to be loaded and unloaded with restarting the application.
 ==Rationale==
-Current XPI extensions cannot be unloaded without restarting the application. This is because the features that we give them (XPCOM components, chrome registration and overlays etc.) cannot be removed in a managed fashion. Loading without a restart could possibly be implemented however that really only solves a small part of the problem as updates etc. would still require restarts.
+Current XPI add-ons cannot be unloaded without restarting the application. This is because the features that we give them (XPCOM components, chrome registration and overlays etc.) cannot be removed in a managed fashion. Loading without a restart could possibly be implemented however that really only solves a small part of the problem as updates etc. would still require restarts.
-The approach taken here is to simplify what it means to be an extension. Instead of registering XPCOM components and chrome in bootstrapped extension we instead do nothing except call a bootstrap script when loading the extension. The extension can do whatever it likes at that point however it must undo anything it has done when we call the bootstrap script to tell it to unload.
+The approach taken here is to simplify what it means to be an add-on. Instead of registering XPCOM components and chrome in bootstrapped add-ons we instead do nothing except execute a bootstrap script when the add-on is loaded and call some functions on it. The add-on can do whatever it likes at that point however it must undo anything it has done when we call the bootstrap script to tell it to unload.
-==Declaring an Extension as Bootstrappable==
+==Declaring an Add-on as Bootstrappable==
-Extensions are declared as being bootstrappable using the special em:type property with a value of 64 in the install manifest. They should also include a bootstrap.js file alongside the install.rdf.
+Add-ons are declared as being bootstrappable using the special em:bootstrap="true" property in the install manifest. Although any type of add-on can include this, for now it only makes sense for add-ons with em:type="2" (the default extension type) to include it. They should also include a bootstrap.js file alongside the install.rdf.
 ==Bootstrap Events==
-When an extension is loaded the bootstrap.js file is loaded into a privileged sandbox which is cached until the extension is unloaded. One of the following functions will be called:
+When an add-on is loaded the bootstrap.js file is executed in a privileged sandbox which is cached until the add-on is unloaded. The scripts should contain a number of functions that will be called to notify the add-on of certain events:
-* <code>install</code> is called if the extension is installed while Firefox is running.
+===Startup===
-* <code>startup</code> is called when Firefox starts up and the extension is enabled (occurs during profile-after-change currently).
-* <code>enable</code> is called if the user enables the extension.
-If the <code>install</code> or <code>startup</code> functions do not exist then the <code>enable</code> function will be called in their place.
+Whenever an add-on needs to be loaded the platform will call a function named <code>startup</code> in the bootstrap script. It will be passed the following arguments:
-Each function will be passed two arguments, the ID of the extension and the nsIFile of the directory the extension is installed in.
-When an extension is unloaded one of the following functions will be called from the cached sandbox:
+;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.
+;reason :A number representing the reason for loading the add-on. This may be APP_STARTUP or ADDON_ENABLE.
-* <code>uninstall</code> is called if the extension is uninstalled while Firefox is running.
+===Shutdown===
-* <code>shutdown</code> is called if Firefox shuts down while the extension is enabled (occurs during quit-application-granted currently).
-* <code>disable</code> is called if the user disables the extension.
-If the <code>uninstall</code> or <code>shutdown</code> functions do not exist then the <code>disable</code> function will be called in their place.
+Whenever an add-on needs to be unloaded the platform will call a function named <code>shutdown</code> in the bootstrap script. It will be passed the following arguments:
-After the function has been called all references to the sandbox will be dropped allowing it to be garbage collected unless the extension has failed to unload any part of itself.
+;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.
+;reason :A number representing the reason for unloading the add-on. This may be APP_SHUTDOWN or ADDON_DISABLE.
+===Install===
+The bootstrap script may include an <code>install</code> method and if so it will be called before the first call to <code>startup</code> after a particular version of an add-on is installed. It will be passed the following arguments:
+;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.
+;reason :A number representing the reason for installing the add-on. This may be ADDON_INSTALLED, ADDON_UPGRADED or ADDON_DOWNGRADED.
+Note that <code>install</code> will never be called if the add-on is never loaded.
+===Uninstall===
+The bootstrap script may include an <code>uninstall</code> method and if so it will be called after the last call to <code>shutdown</code> before a particular version of an add-on is uninstalled. It will be passed the following arguments:
+;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.
+;reason :A number representing the reason for installing the add-on. This may be ADDON_UNINSTALLED, ADDON_UPGRADED or ADDON_DOWNGRADED.
+Note that <code>uninstall</code> may be called even when add-ons are disabled or incompatible with the current application. It is important that the <code>uninstall</code> script be carefully written to handle APIs that may no longer be present in the application.
+In some cases <code>uninstall</code> may never be called for an add-on. This happens when a third-party application removes the add-on while Firefox is not running.