Labs/Jetpack/Release Notes/1.0b1: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== About the SDK ==
== About ==


The Add-on SDK is a downloadable software development kit that provides a set of tools and APIs for building, testing, and packaging Firefox add-ons.
Add-on SDK is a software development kit that provides a set of tools and APIs for building, testing, and packaging Firefox add-ons.
 
The 1.0b1 release is the first beta release of the SDK.  It includes many changes from the previous version of the software, the most notable of which are listed below.  Effective this release, the kit has also been renamed from Jetpack SDK to Add-on SDK.


== Installation ==
== Installation ==
Line 10: Line 12:
* [https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1.0b1.zip addon-sdk-1.0b1.zip]
* [https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/addon-sdk-1.0b1.zip addon-sdk-1.0b1.zip]


Once you've got that, just unpack the archive, open the <tt>addon-sdk-1.0b1/README.txt</tt> file, and follow its instructions.
Then unpack the archive, open the <tt>addon-sdk-1.0b1/README.txt</tt> file, and follow its instructions.


== Notable Changes ==
== Notable Changes ==


'''New features:'''
=== New Features ===


* <code>init</code> option in <code>cfx</code> command, let create an addon sample for the easy and fast experimentation and development expirience of addon SDK developers, all developers have to do is:  
* The <code>cfx init</code> command constructs the basic directory structure of an add-on to make it easy to start building one. ({{bug|566814}})
  <pre>
* It is now possible to use an ID in one of the two [https://developer.mozilla.org/en/install_manifests#id traditional formats used by Mozilla add-ons], which is useful when migrating a traditional XUL add-on to the SDK. ({{bug|604499}})
  mkdir addonDirectory
* Add-ons created using the SDK can now easily specify an icon to represent them in Firefox's Add-on Manager and other places. Simply drop a PNG file named <code>icon.png</code> into the root of your add-on's package directory. ({{bug|588119}})
  cd addonDirectory
  cfx init
  </pre>
  <code>init</code> will add new functionalities in future like creation of public/private keypair and the directory creation when would be needed.
  ({{bug|566814}})


* 604499 myk  Need to be able to use old addon id as the id for Jetpack SDK generated extension
=== Electrolysis ===


* Early experimental support for out-of-process Add-ons, also known as ''Electrolysis'' or ''e10s'', has been added to the Add-on SDK. An add-on can be run in a separate process if the <code>--e10s</code> option is passed to the <code>cfx</code> tool. Documentation for the feature still needs to be added to the SDK, but eager souls can view the documentation for the [http://github.com/toolness/jetpack-e10s/#readme e10s proof-of-concept], which remains largely accurate. ({{bug|567703}})
[[Electrolysis]] (E10S) is a project to load and render/execute browser UI, web content, plugins, and add-ons in separate processes. We are in the process of modifying the SDK's add-on loader to load SDK-based add-ons in separate processes.


* Add-ons created using the SDK can now easily specify an icon to represent them in Firefox's Add-on Manager and other places. Simply drop a PNG file named <code>icon.png</code> into the root of your Add-on's package directory, or read more in the SDK documentation. ({{bug|588119}})
* The Widget API has been redesigned to be E10S-compatible. ({{bug|569479}})
** Events related to web content, and direct access to Widget content, has been removed from the API.
** Support for interacting with Widget content via [https://jetpack.mozillalabs.com/sdk/latest/docs/#guide/web-content content scripts] has been added to the API.
** The <code>image</code> property of the Widget API has been renamed to <code>contentURL</code> to make its interface consistent with that of other APIs that use content scripts.
* The Tabs module has been redesigned to to be E10S-compatible. ({{bug|593908}})
* Experimental support for loading add-ons in separate processes has been added to the SDK.  An add-on will be executed in a separate process if the <code>--e10s</code> option is passed to the <code>cfx</code> tool. The feature is not yet documented in the SDK documentation, but the documentation for the [http://github.com/toolness/jetpack-e10s/#readme proof-of-concept implementation] remains largely accurate. ({{bug|567703}})


'''Compatibility changes:'''
=== Object Construction and Destruction ===


* Add-ons created with the SDK are now marked as compatible with the latest Firefox nightlies. ({{bug|613341}})
Object construction and destruction has been simplified for a number of APIs that create persistent user interface elements or data structures.  It is no longer necessary to both construct an object and add it to a registry of such objects via an <code>add()</code> method call in order for the object to persist.  Such objects now persist by default for the life of the browsing session (or until the add-on is disabled/uninstalled), and to destroy them you call their <code>destroy()</code> method instead of removing them from an object registry via a <code>remove()</code> method call.


'''Project-wide reorganization:'''
The new behavior applies to the following objects:


* 570876 myk rename the Jetpack SDK to "Add-on SDK"
* Panel
* 613348 myk  jetpack-core should be renamed to api-utils
* Page (from the Page Worker API)
* Widget
* Menu, MenuItem, MenuSeparator (from the Context Menu API)
* PageMod


'''E10s changes:'''
=== Event Handling ===


* Update the widget API for e10s ({{bug|569479}})
The way add-on code registers listeners for events generated by API objects has changed.  When constructing an object like a Panel, it remains possible to register event listeners by passing the constructor an option (like <code>onShow</code> for Panel objects).  After construction, however, and for preexisting objects like the set of tabs exported by the Tabs API, you register a listener by calling the object's <code>on</code> method, passing it the name of the event and the listener function.
** Changed the Widget API to use the content-scripts API.
** Removed events related to web content in widgets.
** Renamed the image property to contentURL, making it consistent with all content-scripts-based APIs.
* 593908 rFobic  make tabs module e10s-compatible


'''Move to construct/destroy model:'''
The value of the <code>this</code> object in event listeners has been made consistent.  It is the object that emitted the event. For example, when a Panel object emits a <code>show</code> event, the value of the <code>this</code> object in its listeners is the Panel object.


* In the <code>panel</code> module, the <code>add()</code> function is no longer necessary and has been removed: simply creating a new <code>Panel</code> instance accomplishes the same thing. The <code>remove()</code> function has also been removed in favor of a new method on the <code>Panel</code> class called <code>destroy()</code>. ({{bug|611763}})
=== <code>cfx</code> Tool ===


* 596053 adw  switch to construct/destroy model for Panel, PageWorker, Widget and other APIs that create persistent DOM elements
* The undocumented <code>xpcom</code> command has been removed, along with its associated options <code>--srcdir</code> and <code>--objdir</code>. ({{bug|614568}})
* 612016 adw  Switch to construct/destroy model for context-menu
* The <code>--dep-tests</code> option has been renamed to <code>--dependencies</code>. ({{bug|614129}})
* 612169 adw  Switch to construct/destroy model for widget
* The shortcuts for some options have been removed or changed. ({{bug|614129}})
* 612180 adw  Switch to construct/destroy model for page-worker
** Shortcuts removed:
* 612463 adw  Switch to construct/destroy model for page-mod
*** <code>-p</code> for <code>--pkgdir</code>
 
*** <code>-k</code> for <code>--extra-packages</code>
'''Event handling changes:'''
*** <code>-t</code> for <code>--templatedir</code>
*** <code>-r</code> for <code>--use-server</code>
*** <code>-u</code> for <code>--update-url</code>
*** <code>-l</code> for <code>--update-link</code>
*** <code>-d</code> for <code>--dep-tests</code>
*** <code>-x</code> for <code>--times</code>
** Shortcuts changed:
*** <code>-P</code> to <code>-p</code> for <code>--profiledir</code>
*** <code>-F</code> to <code>-f</code> for <code>--filter</code>
* The <code>sdocs</code>, <code>testcfx</code>, <code>testpkgs</code>, and <code>testex</code> commands and the <code>--logfile</code>, <code>--profile-memory</code>, <code>--e10s</code>, <code>--keydir</code>, <code>--addons</code>, and <code>--test-runner-pkg</code> options have been explicitly identified as ''internal'' (intended for use by developers working on the SDK itself) and might be changed or removed in the future. ({{bug|614128}}, {{bug|614130}})
* The <code>develop</code> command and <code>--use-server</code> option have been explicitly identified as ''experimental'' and might be changed or removed in the future. ({{bug|614130}})


* 598980 rFobic  change "windows" module to use EventEmitter event registration model
=== Miscellaneous API ===
* 598981 rFobic  change "tabs" module to use EventEmitter event registration model
* 602992 rFobic  EventEmitter should let objects set a |this| object
* 616758 adw Convert context-menu events to style described in bug 593921
* 616766 adw Convert notification events to style described in bug 593921
* 616770 adw Convert simple-storage events to style described in bug 593921
* 616785 myk PageMod throws exception when XML document element inserted
* 616866 adw Convert widget events to style described in bug 593921
* 616900 adw Convert selection events to style described in bug 593921
* 616907 adw Convert private-browsing events to style described in bug 593921
* 616912 adw Convert request events to style described in bug 593921


'''Misc API changes (renamings, removals, type changes):'''
* The <code>Tab.location</code> property has been renamed to <code>Tab.url</code>, and its data type has changed to <code>string</code>. ({{bug|612678}})
* The data type of the <code>contentURL</code> property of Page, Panel, and Widget objects has changed to <code>string</code>.
* The <code>Tab.thumbnail</code> property has been replaced by a <code>Tab.getThumbnail()</code> method. ({{bug|612681}})
* The <code>contentScriptURL</code> property of several objects has been renamed to <code>contentScriptFile</code>. ({{bug|612716}})
* The Windows API's <code>openWindow()</code> method has been renamed to <code>open()</code>, and its <code>onReady</code> option has been removed. ({{bug|612758}}, {{bug|612685}})
* Boolean properties have been prefixed with "is", including the Private Browsing API's <code>isActive</code>, the Selection API's <code>isContiguous</code>, and <code>Tab.isPinned</code>. ({{bug|612733}}, {{bug|612735}}, {{bug|615164}})
* Private Browsing activation and deactivation is now exposed via <code>activate()</code> and <code>deactivate()</code> methods.
* Tab pinning and unpinning is now exposed via <code>pin()</code> and <code>unpin()</code> methods.
* The localization (l10n) API has been removed. ({{bug|612770}})


* 612678 rFobic  Tab.location property should be a string
=== Miscellaneous ===
* 612681 rFobic  Tab.thumbnail property should be a data: URI String
* 612716 rFobic  rename contentScriptURL to contentScriptFile
* 612685 rFobic  onReady option to Windows API's openWindow() not useful, should be removed
* 612719 adw  remove "ready" event from Page Worker API doc
* 612733 adw  rename "active" property to "isActive" and add activate(), deactivate() functions to Private Browsing API
* 612735 adw  rename "contiguous" property to "isContiguous" in Selection API
* 612747 rFobic  Tab.close() should accept a callback to be called when the closing process finishes
* 612758 rFobic  browserWindows.openWindow() should be simply open()
* 612770 adw  pull l10n API for initial beta
* 615164 rFobic  rename Tab.pinned to isPinned, make read-only, and add pin()/unpin() methods
 
'''CFX changes:'''
 
* 614129 adw  change cfx options based on usage expectations
* 614130 adw  distinguish between supported/experimental/internal commands/options and tool/command options
 
* The undocumented <code>xpcom</code> command has been removed, along with its associated options <code>--srcdir</code> and <code>--objdir</code>. ({{bug|614568}})


* 614128 nobody  remove obsolete/redundant commands and options
* The <code>jetpack-core</code> package has been renamed to <code>api-utils</code>. ({{bug|613348}})
* Add-ons created with the SDK are now marked as compatible with Firefox 4.0b7 and the latest Firefox 4.0b8pre nightlies. ({{bug|613341}})


A complete list of changes is available in the [http://hg.mozilla.org/labs/jetpack-sdk/ source code repository].
A complete list of changes is available in the [http://github.com/mozilla/addon-sdk/ source code repository].


== Known Issues ==
== Known Issues ==


* A variety of tests are failing intermittently. See {{bug|606351}} for the details.
* Although the SDK is not compatible with Firefox 3.6, <code>cfx test</code> and <code>cfx run</code> may use Firefox 3.6 by default if you have it installed.  To work around the problem, specify the location of the Firefox 4.0 beta binary with the <code>--binary</code> option.
* A variety of tests are failing intermittently. ({{bug|606351}})


Also see the [https://bugzilla.mozilla.org/buglist.cgi?order=Bug%20Number&bug_status=__open__&component=Jetpack%20SDK&product=Mozilla%20Labs complete list of known issues and requests for enhancement].
Also see the [https://bugzilla.mozilla.org/buglist.cgi?order=Bug%20Number&bug_status=__open__&product=Add-on%20SDK complete list of known issues and requests for enhancement].


== Feedback and Bug Reports ==
== Feedback and Bug Reports ==


We'd love to hear any feedback you have regarding this release! You can post it to the [http://groups.google.com/group/mozilla-labs-jetpack discussion forum] or [https://bugzilla.mozilla.org/enter_bug.cgi?product=Add-on%20SDK&version=1.0b1 report a bug].
We'd love to hear any feedback you have regarding this release! You can post it to the [http://groups.google.com/group/mozilla-labs-jetpack discussion group] or [https://bugzilla.mozilla.org/enter_bug.cgi?product=Add-on%20SDK&version=1.0b1 report a bug].

Latest revision as of 08:01, 9 December 2010

About

Add-on SDK is a software development kit that provides a set of tools and APIs for building, testing, and packaging Firefox add-ons.

The 1.0b1 release is the first beta release of the SDK. It includes many changes from the previous version of the software, the most notable of which are listed below. Effective this release, the kit has also been renamed from Jetpack SDK to Add-on SDK.

Installation

Obtain the SDK in your favorite compression format:

Then unpack the archive, open the addon-sdk-1.0b1/README.txt file, and follow its instructions.

Notable Changes

New Features

  • The cfx init command constructs the basic directory structure of an add-on to make it easy to start building one. (bug 566814)
  • It is now possible to use an ID in one of the two traditional formats used by Mozilla add-ons, which is useful when migrating a traditional XUL add-on to the SDK. (bug 604499)
  • Add-ons created using the SDK can now easily specify an icon to represent them in Firefox's Add-on Manager and other places. Simply drop a PNG file named icon.png into the root of your add-on's package directory. (bug 588119)

Electrolysis

Electrolysis (E10S) is a project to load and render/execute browser UI, web content, plugins, and add-ons in separate processes. We are in the process of modifying the SDK's add-on loader to load SDK-based add-ons in separate processes.

  • The Widget API has been redesigned to be E10S-compatible. (bug 569479)
    • Events related to web content, and direct access to Widget content, has been removed from the API.
    • Support for interacting with Widget content via content scripts has been added to the API.
    • The image property of the Widget API has been renamed to contentURL to make its interface consistent with that of other APIs that use content scripts.
  • The Tabs module has been redesigned to to be E10S-compatible. (bug 593908)
  • Experimental support for loading add-ons in separate processes has been added to the SDK. An add-on will be executed in a separate process if the --e10s option is passed to the cfx tool. The feature is not yet documented in the SDK documentation, but the documentation for the proof-of-concept implementation remains largely accurate. (bug 567703)

Object Construction and Destruction

Object construction and destruction has been simplified for a number of APIs that create persistent user interface elements or data structures. It is no longer necessary to both construct an object and add it to a registry of such objects via an add() method call in order for the object to persist. Such objects now persist by default for the life of the browsing session (or until the add-on is disabled/uninstalled), and to destroy them you call their destroy() method instead of removing them from an object registry via a remove() method call.

The new behavior applies to the following objects:

  • Panel
  • Page (from the Page Worker API)
  • Widget
  • Menu, MenuItem, MenuSeparator (from the Context Menu API)
  • PageMod

Event Handling

The way add-on code registers listeners for events generated by API objects has changed. When constructing an object like a Panel, it remains possible to register event listeners by passing the constructor an option (like onShow for Panel objects). After construction, however, and for preexisting objects like the set of tabs exported by the Tabs API, you register a listener by calling the object's on method, passing it the name of the event and the listener function.

The value of the this object in event listeners has been made consistent. It is the object that emitted the event. For example, when a Panel object emits a show event, the value of the this object in its listeners is the Panel object.

cfx Tool

  • The undocumented xpcom command has been removed, along with its associated options --srcdir and --objdir. (bug 614568)
  • The --dep-tests option has been renamed to --dependencies. (bug 614129)
  • The shortcuts for some options have been removed or changed. (bug 614129)
    • Shortcuts removed:
      • -p for --pkgdir
      • -k for --extra-packages
      • -t for --templatedir
      • -r for --use-server
      • -u for --update-url
      • -l for --update-link
      • -d for --dep-tests
      • -x for --times
    • Shortcuts changed:
      • -P to -p for --profiledir
      • -F to -f for --filter
  • The sdocs, testcfx, testpkgs, and testex commands and the --logfile, --profile-memory, --e10s, --keydir, --addons, and --test-runner-pkg options have been explicitly identified as internal (intended for use by developers working on the SDK itself) and might be changed or removed in the future. (bug 614128, bug 614130)
  • The develop command and --use-server option have been explicitly identified as experimental and might be changed or removed in the future. (bug 614130)

Miscellaneous API

  • The Tab.location property has been renamed to Tab.url, and its data type has changed to string. (bug 612678)
  • The data type of the contentURL property of Page, Panel, and Widget objects has changed to string.
  • The Tab.thumbnail property has been replaced by a Tab.getThumbnail() method. (bug 612681)
  • The contentScriptURL property of several objects has been renamed to contentScriptFile. (bug 612716)
  • The Windows API's openWindow() method has been renamed to open(), and its onReady option has been removed. (bug 612758, bug 612685)
  • Boolean properties have been prefixed with "is", including the Private Browsing API's isActive, the Selection API's isContiguous, and Tab.isPinned. (bug 612733, bug 612735, bug 615164)
  • Private Browsing activation and deactivation is now exposed via activate() and deactivate() methods.
  • Tab pinning and unpinning is now exposed via pin() and unpin() methods.
  • The localization (l10n) API has been removed. (bug 612770)

Miscellaneous

  • The jetpack-core package has been renamed to api-utils. (bug 613348)
  • Add-ons created with the SDK are now marked as compatible with Firefox 4.0b7 and the latest Firefox 4.0b8pre nightlies. (bug 613341)

A complete list of changes is available in the source code repository.

Known Issues

  • Although the SDK is not compatible with Firefox 3.6, cfx test and cfx run may use Firefox 3.6 by default if you have it installed. To work around the problem, specify the location of the Firefox 4.0 beta binary with the --binary option.
  • A variety of tests are failing intermittently. (bug 606351)

Also see the complete list of known issues and requests for enhancement.

Feedback and Bug Reports

We'd love to hear any feedback you have regarding this release! You can post it to the discussion group or report a bug.

Retrieved from "https://wiki.allizom.org/index.php?title=Labs/Jetpack/Release_Notes/1.0b1&oldid=272843"