bug 549469: add documentation explaining how to build XPIs automatica…

…lly with cfx; r=myk

static-files/md/dev-guide/programs.md

@@ -10,35 +10,65 @@ and more.
 ## Your First Program ##
 
 We're going to continue building upon our package from the [Packaging]
-section.
+section. This program will add a context-menu option to links, with the
+ability to search Google for the link text.
+
+### Using Jetpack's Built-in Libraries ###
+
+Add a `dependencies` entry to your package.json file, showing that your
+package requires modules from the jetpack-core library. It should look
+something like this now:
+
+    {
+      "description": "This package adds a Google search context-menu item.",
+      "author": "Me (http://me.org)",
+      "dependencies": ["jetpack-core"]
+    }
+
+
+### Adding Your Code ###
 
 If a module called `main` exists in your package and it exports a
 function called `main`, the function will be called as soon as your
-program is activated. By "activated", we mean that either a containing
+program is activated. By "activated", we mean that either a host
 application such as Firefox or Thunderbird has enabled your program as
 an extension, or that your program is itself a standalone application.
+The forthcoming example will demonstrate an extension.
 
 With this in mind, let's create a file at `lib/main.js` with the
 following content:
 
+    // The `main` function is called by the host application that enables
+    // this module. In this example, `options` and `callbacks` are not
+    // used.
     exports.main = function(options, callbacks) {
-      console.log("Hello World!");
-      callbacks.quit();
-    }
 
-### Quitting ###
+      var contextMenu = require("context-menu");
+
+      // Create a new context menu item.
+      var menuItem = contextMenu.Item({
+
+        label: "Search with Google",
 
-Your `main` function is passed two arguments, one of which contains
-callbacks that can be used to communicate with the embedding application.
-One of these is `quit`, which can be used at any point to inform the
-embedding application that your program is finished, and can immediately
-be unloaded.
+        // A CSS selector. Matching on this selector triggers the
+        // display of our context menu.
+        context: "a[href]",
+
+        // When the context menu item is clicked, perform a Google
+        // search for the link text.
+        onClick: function (contextObj, item) {
+          var anchor = contextObj.node;
+          console.log("searching for " + anchor.textContent);
+          var searchUrl = "http://www.google.com/search?q=" +
+                          anchor.textContent;
+          contextObj.window.location.href = searchUrl;
+        }
+      });
+
+      // Add the new menu item to the application's context menu.
+      contextMenu.add(menuItem);
+    };
 
-Some programs--usually ones intended to be extensions--are never
-actually "finished" and just permanently augment their embedding
-applications until the end-user disables them or the application shuts
-down. In these kinds of programs, you never need to call `quit`
-yourself.
 
 ### Logging ###
 
@@ -56,21 +86,54 @@ for debugging.
 
 ### Running It ###
 
-To try running your application, just navigate to the root of your
-package directory in your shell and run `cfx run`.  You should
-get something like the following:
+To run your program, navigate to the root of your package directory
+in your shell and run:
+
+    cfx run -a firefox
+
+That will load an instance of Firefox (or your default application)
+with your program installed.
+
+### Packaging It ###
+
+Your program is packaged like any other extension for a Mozilla-based
+application, as a XPI file. The Jetpack 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`. You should see a message:
+
+    Exporting extension to test.xpi.
+
+The test.xpi file can be found in the directory in which you ran the
+command.
+
+### Checking the Package ###
+
+If you'd like to test the packaged program before distributing it,
+you can run it from the shell with:
+
+    mozrunner -a test.xpi
+
+Or you can install it from the Firefox Add-ons Manager itself, as
+you would when testing a traditional add-on.
+
+Running your program as described in the `Running It` section uses
+the same process as packaging it as a .xpi, so this step is optional.
+
+### Distributing It ###
 
-    info: Hello World!
-    OK
-    Total time: 0.510817 seconds
-    Program terminated successfully.
+To distribute your program, you can upload it to
+[Addons.mozilla.org](http://addons.mozilla.org).
+Eventually, this step may be automated via the SDK, streamlining the
+distribution process further.
 
 ## To Be Continued... ##
 
-Right now, the Jetpack SDK is at an early stage of
-development. There's not too much to show. But be on the lookout for
-upcoming versions of the SDK, which will continue this tutorial and
-show you how to build a useful Jetpack-based Firefox or Thunderbird
-extension that you can distribute to your friends, foes, and family!
+Right now, the Jetpack SDK is at an early stage of development.
+There's not too much to show. Be on the lookout for upcoming versions
+of the SDK, which will expand the built-in set of libraries, continue
+this tutorial and show you how to build other types of add-ons, as well
+as standalone applications!
 
   [Packaging]: #guide/packaging