Extension Manager:Bootstrapped Extensions - Revision history

Asqueella: link to MDC docs

2010-11-01T21:54:18Z

link to MDC docs

← Older revision		Revision as of 21:54, 1 November 2010
Line 1:		Line 1:
			{{Note\|This page contains preliminary documentation of the feature and is mainly of historical interest. The documentation is at [https://developer.mozilla.org/en/Extensions/Bootstrapped_extensions MDC].}}

	__NOTOC__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.		__NOTOC__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.

Mossop: /* Bootstrap Events */

2010-04-20T18:38:19Z

Bootstrap Events

Mossop at 04:00, 14 April 2010

2010-04-14T04:00:13Z

Mossop: /* Startup */

2010-04-13T16:52:39Z

Startup

← Older revision		Revision as of 16:52, 13 April 2010
Line 34:		Line 34:
	;reason :A number representing the reason for starting the add-on. This may be APP_STARTUP or ADDON_ENABLE.		;reason :A number representing the reason for starting the add-on. This may be APP_STARTUP or ADDON_ENABLE.

	The add-on must at this point do anything necessary to make its functionality available, the platform not execute any other part of the add-on.		The add-on must at this point do anything necessary to make its functionality available, the platform will not execute any other part of the add-on.

	===Shutdown===		===Shutdown===

Mossop: /* Uninstall */

2010-04-13T15:11:40Z

Uninstall

← Older revision		Revision as of 15:11, 13 April 2010
Line 56:		Line 56:
	===Uninstall===		===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:		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. <code>uninstall</code> will only ever be called if <code>install</code> 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, <code>id</code>, <code>version</code> and <code>installPath</code>.		;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.

Mossop at 15:10, 13 April 2010

2010-04-13T15:10:06Z

← Older revision		Revision as of 15:10, 13 April 2010
Line 9:		Line 9:
	A key feature of bootstrapped add-ons is that they must be able to be started and shutdown on demand by the platform. 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:		A key feature of bootstrapped add-ons is that they must be able to be started and shutdown on demand by the platform. 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 platform will tell the add-on to ~~load~~.		* When first installed (if the add-on is compatible and enabled) the platform will tell the add-on to start up.
	* When uninstalled (if the add-on is currently enabled) the platform will tell the add-on to ~~unload~~.		* When uninstalled (if the add-on is currently enabled) the platform will tell the add-on to shutdown.
	* When enabled or disabled while the application is running the platform will tell the add-on to startup or shutdown as appropriate.		* When enabled or disabled while the application is running the platform will tell the add-on to startup or shutdown as appropriate.
	* When the application is started the platform will tell any enabled add-ons to startup.		* When the application is started the platform will tell any enabled add-ons to startup.
Line 21:		Line 21:
	==Backwards Compatibility==		==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 ~~load~~ the bootstrap.js.		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==		==Bootstrap Events==

	Bootstrapped add-ons must provide a bootstrap.js file which defines main entry functions as defined below. When the platform needs to call a function the script will be ~~loaded into~~ a privileged sandbox which is cached until the add-on is shutdown.		Bootstrapped add-ons must provide a bootstrap.js file which defines main entry functions as defined below. When the platform needs to call a function the script will be executed in a privileged sandbox which is cached until the add-on is shutdown.

	===Startup===		===Startup===
Line 32:		Line 32:

	;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.		;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.		;reason :A number representing the reason for starting the add-on. This may be APP_STARTUP or ADDON_ENABLE.

	The add-on must at this point do anything necessary to make its functionality available, the platform ~~will do nothing else to load~~ the add-on.		The add-on must at this point do anything necessary to make its functionality available, the platform not execute any other part of the add-on.

	===Shutdown===		===Shutdown===
Line 41:		Line 41:

	;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.		;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.		;reason :A number representing the reason for shutting down the add-on. This may be APP_SHUTDOWN or ADDON_DISABLE.

	The add-on must at this point remove anything it has added to the application so its memory can be reclaimed.		The add-on must at this point remove anything it has added to the application so its memory can be reclaimed.
Line 52:		Line 52:
	;reason :A number representing the reason for installing the add-on. This may be ADDON_INSTALLED, ADDON_UPGRADED or ADDON_DOWNGRADED.		;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~~.		Note that <code>install</code> 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 <code>install</code> 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 <code>install</code> will be called before the call to <code>startup</code>.

	===Uninstall===		===Uninstall===

Mossop at 15:05, 13 April 2010

2010-04-13T15:05:52Z

← Older revision		Revision as of 15:05, 13 April 2010
Line 1:		Line 1:
	__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~~ without 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 started up and shutdown without restarting the application.

	~~==Rationale==~~		Current XPI add-ons cannot be removed from memory 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. Adding an add-on 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 add-on. Instead of registering XPCOM components and chrome in bootstrapped add-ons we do nothing except 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.

	~~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~~.		==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 platform. 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 platform will tell the add-on to load.
			* When uninstalled (if the add-on is currently enabled) the platform will tell the add-on to unload.
			* When enabled or disabled while the application is running the platform will tell the add-on to startup or shutdown as appropriate.
			* When the application is started the platform will tell any enabled add-ons to startup.
			* When the user quits the application the platform will tell any enabled add-ons to shutdown.

	==Declaring an Add-on as Bootstrappable==		==Declaring an Add-on as Bootstrappable==
Line 17:		Line 25:
	==Bootstrap Events==		==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:~~		Bootstrapped add-ons must provide a bootstrap.js file which defines main entry functions as defined below. When the platform needs to call a function the script will be loaded into a privileged sandbox which is cached until the add-on is shutdown.

	===Startup===		===Startup===

	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:		Whenever an add-on needs to be started the platform will call a function named <code>startup</code> in the bootstrap script. 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>.		;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.		;reason :A number representing the reason for loading the add-on. This may be APP_STARTUP or ADDON_ENABLE.

			The add-on must at this point do anything necessary to make its functionality available, the platform will do nothing else to load the add-on.

	===Shutdown===		===Shutdown===

	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:		Whenever an add-on needs to be shutdown the platform will call a function named <code>shutdown</code> in the bootstrap script. 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>.		;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.		;reason :A number representing the reason for unloading the add-on. This may be APP_SHUTDOWN or ADDON_DISABLE.

			The add-on must at this point remove anything it has added to the application so its memory can be reclaimed.

	===Install===		===Install===

Hipokrit at 23:57, 12 April 2010

2010-04-12T23:57:56Z

← Older revision		Revision as of 23:57, 12 April 2010
Line 1:		Line 1:
	__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.		__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 without restarting the application.

	==Rationale==		==Rationale==

Mossop at 20:36, 12 April 2010

2010-04-12T20:36:08Z

← Older revision		Revision as of 20:36, 12 April 2010
Line 10:		Line 10:

	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.		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 load the bootstrap.js.

	==Bootstrap Events==		==Bootstrap Events==

Mossop at 20:30, 12 April 2010

2010-04-12T20:30:54Z

← Older revision		Revision as of 20:30, 12 April 2010
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==		==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==		==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.

← Older revision		Revision as of 18:38, 20 April 2010
Line 30:		Line 30:

	;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.		;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 starting the add-on. This may be APP_STARTUP or ~~ADDON_ENABLE~~.		;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.		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.
Line 39:		Line 39:

	;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.		;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 shutting down the add-on. This may be APP_SHUTDOWN or ~~ADDON_DISABLE~~.		;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.		The add-on must at this point remove anything it has added to the application so its memory can be reclaimed.
Line 48:		Line 48:

	;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.		;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~~.		;reason :A number representing the reason for installing the add-on. This may be ADDON_INSTALL, ADDON_UPGRADE or ADDON_DOWNGRADE.

	Note that <code>install</code> 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 <code>install</code> 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 <code>install</code> will be called before the call to <code>startup</code>.		Note that <code>install</code> 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 <code>install</code> 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 <code>install</code> will be called before the call to <code>startup</code>.
Line 57:		Line 57:

	;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.		;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~~.		;reason :A number representing the reason for installing the add-on. This may be ADDON_UNINSTALL, ADDON_UPGRADE or ADDON_DOWNGRADE.

	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.		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.		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.

← Older revision		Revision as of 04:00, 14 April 2010
Line 1:		Line 1:
	__NOTOC__Bootstrapped add-ons ~~exist as~~ a ~~means~~ of ~~restricting what is available~~ to an add-on in order to allow it to ~~be started up~~ and ~~shutdown~~ without ~~restarting~~ the application.		__NOTOC__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.

	~~Current XPI add-ons cannot be removed from memory 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. Adding an add-on 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.		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.

	~~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 do nothing except~~ 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==		==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 ~~platform~~. 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:		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 ~~platform~~ will tell the add-on to start up.		* 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 ~~platform~~ will tell the add-on to shutdown.		* 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 ~~platform~~ will tell the add-on to startup or shutdown as appropriate.		* 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 ~~platform~~ will tell any enabled add-ons to startup.		* When the application is started the application will tell any enabled add-ons to startup.
	* When the user quits the application the ~~platform~~ will tell any enabled add-ons to shutdown.		* When the user quits the application the application will tell any enabled add-ons to shutdown.

	==Declaring an Add-on as Bootstrappable==		==Declaring an Add-on as Bootstrappable==
Line 25:		Line 23:
	==Bootstrap Events==		==Bootstrap Events==

	Bootstrapped add-ons must provide a bootstrap.js file which defines main entry functions as defined below. When the ~~platform~~ needs to call a function the script will be executed in a privileged sandbox which is cached until the add-on is shutdown.		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===		===Startup===

	Whenever an add-on needs to be started the ~~platform~~ will call a function named <code>startup</code> in the bootstrap script. It will be passed the following arguments:		Whenever an add-on needs to be started the application will call a function named <code>startup</code> in the bootstrap script. <code>startup</code> 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, <code>id</code>, <code>version</code> and <code>installPath</code>.		;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 starting the add-on. This may be APP_STARTUP or ADDON_ENABLE.		;reason :A number representing the reason for starting the add-on. This may be APP_STARTUP or ADDON_ENABLE.

	The add-on must at this point do anything necessary to make its functionality available, the ~~platform~~ will not execute any other part of the add-on.		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===		===Shutdown===

	Whenever an add-on needs to be shutdown the ~~platform~~ will call a function named <code>shutdown</code> in the bootstrap script. It will be passed the following arguments:		Whenever an add-on needs to be shutdown the application will call a function named <code>shutdown</code> in the bootstrap script. <code>shutdown</code> 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, <code>id</code>, <code>version</code> and <code>installPath</code>.		;data :A JS object containing basic information about the add-on, <code>id</code>, <code>version</code> and <code>installPath</code>.