Extension Manager:Bootstrapped Extensions
Note: This page contains preliminary documentation of the feature and is mainly of historical interest. The documentation is at MDC.
Bootstrapped add-ons are a special kind of add-on that developers can choose to use instead of normal add-ons in order to allow users to install and use the add-on without needing to restart the application. In order to do this, rather than the application loading chrome and components from the add-on it is up to the add-on developer to do all of this manually.
All the application will do is execute a bootstrap script that the add-on provides, telling it to startup. 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 shutdown.
Starting up and Shutting down
A key feature of bootstrapped add-ons is that they must be able to be started and shutdown on demand by the application. When told to startup it is up to the add-on's bootstrap code to do anything necessary to inject UI and behaviour into the application. When told to shutdown it is required that the add-on remove anything it has added and removing all references to its objects. Some examples of when startup and shutdown happen:
- When first installed (if the add-on is compatible and enabled) the application will tell the add-on to start up.
- When uninstalled (if the add-on is currently enabled) the application will tell the add-on to shutdown.
- When enabled or disabled while the application is running the application will tell the add-on to startup or shutdown as appropriate.
- When the application is started the application will tell any enabled add-ons to startup.
- When the user quits the application the application will tell any enabled add-ons to shutdown.
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.
Backwards Compatibility
Older versions of Firefox do not know about the em:bootstrap flag or bootstrap.js file but with care it is possible to make the same XPI usable in both cases. Older versions would just treat it as a normal add-on requiring a restart to install and uninstall and loading components and chrome from the normal places. Newer versions will ignore the components and chrome and just use the bootstrap.js.
Bootstrap Events
Bootstrapped add-ons must provide a bootstrap.js file which defines main entry functions as defined below. When the application needs to call a function the script will be executed in a privileged sandbox which is cached until the add-on is shutdown.
Startup
Whenever an add-on needs to be started the application will call a function named startup
in the bootstrap script. startup
may be called at any point during an application run. It will be passed the following arguments:
- data
- A JS object containing basic information about the add-on,
id
,version
andinstallPath
. - reason
- A number representing the reason for starting the add-on. This may be APP_STARTUP, ADDON_ENABLE, ADDON_INSTALL, ADDON_UPGRADE or ADDON_DOWNGRADE.
The add-on must at this point do anything necessary to make its functionality available, the application will not execute any other part of the add-on.
Shutdown
Whenever an add-on needs to be shutdown the application will call a function named shutdown
in the bootstrap script. shutdown
may be called at any point during an application run. It will be passed the following arguments:
- data
- A JS object containing basic information about the add-on,
id
,version
andinstallPath
. - reason
- A number representing the reason for shutting down the add-on. This may be APP_SHUTDOWN, ADDON_DISABLE, ADDON_UNINSTALL, ADDON_UPGRADE or ADDON_DOWNGRADE.
The add-on must at this point remove anything it has added to the application so its memory can be reclaimed.
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
andinstallPath
. - reason
- A number representing the reason for installing the add-on. This may be ADDON_INSTALL, ADDON_UPGRADE or ADDON_DOWNGRADE.
Note that install
will never be called if the add-on has never been started. For example if an add-on is installed but is not compatible then install
will never be called if the add-on is uninstalled before it becomes compatible. If on the other hand the add-on becomes compatible at a later point install
will be called before the call to startup
.
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. uninstall
will only ever be called if install
has been called at some point previously. It will be passed the following arguments:
- data
- A JS object containing basic information about the add-on,
id
,version
andinstallPath
. - reason
- A number representing the reason for installing the add-on. This may be ADDON_UNINSTALL, ADDON_UPGRADE or ADDON_DOWNGRADE.
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.