Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Bug 614339 - move documents for SDK developers to Internals section, …
…Bug 614340 - move documents for experimental features/processes to Experimental section
- Loading branch information
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,6 @@ | ||
|
|
||
| ## JavaScript Globals ## | ||
|
|
||
| By default, all code is executed as [JavaScript 1.8.1] and has access | ||
| to all the globals defined by it, such as `Math`, `Array`, and `JSON`. Each | ||
| module has its own set of these objects; this means that if, for | ||
|
|
@@ -9,25 +12,21 @@ For an introduction to CommonJS modules, see the | |
| [Packaging](#guide/packaging) tutorial. | ||
| </span> | ||
|
|
||
| ## CommonJS Globals ## | ||
|
|
||
| Code also has access to the `require` and `exports` globals | ||
| as specified by version 1.0 of the [CommonJS Module Specification]. | ||
|
|
||
| ## HTML5 Globals ## | ||
|
|
||
| At the time of this writing, code does *not* have access to | ||
| any globals defined by the [HTML5] specification, such as `window`, | ||
| `document`, or `localStorage`. | ||
|
|
||
This comment has been minimized.
Sorry, something went wrong. |
||
| ## SDK Globals ## | ||
|
|
||
| These globals are available regardless of the security context of the code. | ||
|
|
||
| <code>**console**</code> | ||
|
|
||
| `console` is an object with the following methods: | ||
|
|
@@ -64,88 +63,6 @@ about the exception's stack traceback if one is available. | |
|
|
||
| Inserts a stack trace into the console at the point this function is called. | ||
|
|
||
| [Components object]: https://developer.mozilla.org/en/Components_object | ||
| [Security Roadmap]: #guide/security-roadmap | ||
This comment has been minimized.
Sorry, something went wrong. 
toolness
Owner
|
||
| [HTML5]: http://dev.w3.org/html5/spec/Overview.html | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
|
|
||
| Globals in this section are subject to change in the future and/or are likely | ||
| to be of interest to SDK module developers, rather than add-on developers. | ||
|
|
||
| ## Components ## | ||
|
|
||
| To access the infamous and powerful `Components` object, see the | ||
| [Chrome Authority](#guide/chrome) documentation. | ||
|
|
||
| ## \_\_url\_\_ ## | ||
|
|
||
| The `__url__` global is a string identifying the URL from which the code has | ||
| been retrieved. If the code has no identifiable URL, this value may be `null`. | ||
|
|
||
| ## packaging ## | ||
|
|
||
| <span class="aside"> | ||
| For more information on packaging, see the [Package Specification] appendix. | ||
| </span> | ||
|
|
||
| The `packaging` global contains methods and metadata related to | ||
| the packages available in the current environment. | ||
|
|
||
| <code>packaging.**getURLForData**(*path*)</code> | ||
|
|
||
| Given a unix-style path relative to the calling package's `data` | ||
| directory, returns an absolute URL to the file or directory. | ||
|
|
||
| By "calling package", we mean the package in which the caller's source | ||
| code resides. | ||
|
|
||
| Thus, for example, if a package contains a resource at | ||
| `data/mydata.dat` and a module at `lib/foo.js`, the module at | ||
| `lib/foo.js` may make the following call to retrieve an absolute url | ||
| to `data/mydata.dat`: | ||
|
|
||
| var mydata = packaging.getURLForData("/mydata.dat"); | ||
|
|
||
| If the calling package has no `data` directory, an exception is | ||
| thrown. | ||
|
|
||
| ## memory ## | ||
|
|
||
| `memory` is an object that exposes functionality to track | ||
| objects of interest and help diagnose and prevent memory leaks. | ||
|
|
||
| <code>memory.**track**(*object*, [*bin*])</code> | ||
|
|
||
| Marks *object* for being tracked, and categorizes it with the given | ||
| bin name. If *bin* isn't specified, the memory tracker attempts to | ||
| infer a bin name by first checking the object's | ||
| `constructor.name`; if that fails or results in the generic | ||
| `Object`, the stack is inspected and the name of the current | ||
| function being executed—which is assumed to be a constructor | ||
| function—is used. If that fails, then the object is placed in a | ||
| bin named `generic`. | ||
|
|
||
| <code>memory.**getObjects**([*bin*])</code> | ||
|
|
||
| Returns an `Array` containing information about tracked objects | ||
| that have been categorized with the given bin name. If *bin* isn't | ||
| provided, information about all live tracked objects are returned. | ||
|
|
||
| Each element of the array is an object with the following keys: | ||
|
|
||
| <table> | ||
| <tr> | ||
| <td><code>weakref</code></td> | ||
| <td>A weak reference to the object being tracked. Call | ||
| <code>get()</code> on this object to retrieve its strong reference; if | ||
| a strong reference to the object no longer exists, <code>get()</code> | ||
| will return <code>null</code>.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>created</code></td> | ||
| <td>A <code>Date</code> representing the date and time that | ||
| <code>memory.track()</code> was called on the object being | ||
| tracked.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>filename</code></td> | ||
| <td>The name of the file that called <code>memory.track()</code> on | ||
| the object being tracked.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>lineNo</code></td> | ||
| <td>The line number of the file that called | ||
| <code>memory.track()</code> on the object being tracked.</td> | ||
| </tr> | ||
| </table> | ||
|
|
||
| <code>memory.**getBins**()</code> | ||
|
|
||
| Returns an `Array` containing the names of all bins that aren't | ||
| currently empty. | ||
|
|
||
| [Package Specification]: #guide/package-spec |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
|
|
||
| The Program ID is a unique identifier for your add-on and is used for a variety | ||
| of purposes. For example: [addons.mozilla.org](http://addons.mozilla.org) uses | ||
| it to distinguish between new add-ons and updates to existing add-ons, and the | ||
| [`simple-storage`](#module/addon-kit/simple-storage) module uses it to figure | ||
| out which stored data belongs to which add-on. | ||
|
|
||
| <span class="aside"> | ||
| where is it on Windows? | ||
| </span> | ||
|
|
||
This comment has been minimized.
Sorry, something went wrong.
toolness
Owner
|
||
| The program ID is the public part of a cryptographic key pair. When `cfx` | ||
| generates a program ID it actually generates a pair of related keys: one half | ||
| (the public key) is embedded in package.json as the program ID while the other | ||
| half (the private key) gets stored in a file in ~/.jetpack/keys. | ||
This comment has been minimized.
Sorry, something went wrong.
toolness
Owner
|
||
|
|
||
| When the XPI file is generated it is signed with the private key. Then the | ||
| browser, or some other tool, can use the public key to verify that the XPI file | ||
| was actually signed by the author. | ||
|
|
||
| The private key is very important! If you lose it, you will not be able to | ||
| upgrade your add-on: you'll have to create a new add-on ID, and your users will | ||
| have to manually uninstall the old one and install the new one. If somebody | ||
| else gets a copy of your private key, they will be able to write add-ons that | ||
| could impersonate and displace your own. | ||
|
|
||
| The add-on's private key needs to be available (in ~/.jetpack/keys/) on any | ||
| computer that you use to build that add-on. When you copy the add-on source | ||
| code to a new machine, you also need to copy the private key (`cfx xpi` will | ||
| remind you of this). The best idea is to just copy the whole ~/.jetpack | ||
| directory to a USB flash drive that you can carry with you. It is not stored | ||
| in your package source tree, so that you can show your code to somebody else | ||
| without also giving them the ability to create forged upgrades for your add-on. | ||
|
|
||
| If you start your add-on work by copying somebody else's source code, you'll | ||
| need to remove their Program ID from the package.json file before you can build | ||
| your own XPIs. Again, `cfx xpi` will remind you of this, and your options, when | ||
| you attempt to build an XPI from a package.json that references a private key | ||
| that you don't have in ~/.jetpack/keys/. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -116,12 +116,27 @@ This is a global accessible by any module and is very useful for debugging. | |
| ### Running It ### | ||
|
|
||
| To run your program, navigate to the root of your package directory | ||
| in your shell and type: | ||
|
|
||
| cfx run | ||
|
|
||
| The first time you do this, you'll see a message like this: | ||
|
|
||
| No 'id' in package.json: creating a new keypair for you. | ||
| package.json modified: please re-run 'cfx run' | ||
|
|
||
| Run it again, and it will run an instance of Firefox (or your default | ||
| application) with your add-on installed. | ||
|
|
||
| The ID that `cfx` generated the first time you executed `cfx run` is called the | ||
| **Program ID** and it is important. It is a unique identifier for your add-on | ||
| and is used for a variety of purposes. For example: mozilla.addons.org uses it | ||
This comment has been minimized.
Sorry, something went wrong.
toolness
Owner
|
||
| to distinguish between new add-ons and updates to existing add-ons, and the | ||
| [`simple-storage`](#module/addon-kit/simple-storage) module uses it to figure | ||
| out which stored data belongs to which add-on. | ||
|
|
||
| To learn more about the Program ID refer to the [Program ID](#guide/program-id) | ||
| document. | ||
|
|
||
| ### Trying It Out ### | ||
|
|
||
|
|
@@ -139,11 +154,6 @@ Your program is packaged like any other extension for a Mozilla-based | |
| application, as a XPI file. The Add-on SDK simplifies the packaging | ||
| process by generating this file for you. | ||
|
|
||
| To package your program as a XPI, navigate to the root of your package | ||
| directory in your shell and run `cfx xpi`. The first time you do this, | ||
| you'll see a message about generating a keypair and modifying your | ||
|
|
@@ -155,6 +165,15 @@ When you re-run it, you should see a message: | |
| The my-first-package.xpi file can be found in the directory in which you ran | ||
| the command. | ||
|
|
||
| #### The Program ID #### | ||
|
|
||
| The ID that `cfx` generated the first time you executed `cfx run` is called the | ||
| **Program ID** and it is important. It is a unique identifier for your add-on | ||
| and is used for a variety of purposes. For example: mozilla.addons.org uses it | ||
| to distinguish between new add-ons and updates to existing add-ons, and the | ||
This comment has been minimized.
Sorry, something went wrong.
toolness
Owner
|
||
| [`simple-storage`](#module/addon-kit/simple-storage) module uses it to figure | ||
| out which stored data belongs to which add-on. | ||
|
|
||
| ### Checking the Package ### | ||
|
|
||
| Test that the package installs correctly by adding it to your own Firefox | ||
|
|
||
Oops, something went wrong.
I wonder if it'd be useful to point readers to the
page-workermodule in an aside here, since they may want to know how they can get access to these HTML5 globals from an addon.