View source for Labs/Jetpack/Reboot/Getting Started

This document is intended to acquaint you with the reboot, so you can start playing around with it and create nifty capabilities that new-age Jetpacks can take advantage of.

== Prerequisites ==

To develop with the new Jetpack SDK, you'll need:

* [http://mercurial.selenic.com/ Mercurial]
* [http://www.python.org/ Python 2.5 or greater]
* A working version of Firefox, Thunderbird, or the XULRunner SDK that uses Gecko 1.9.2 or later (e.g., Firefox 3.6).
* If you're on Windows, you'll also need [http://python.net/crew/skippy/win32/Downloads.html Python for Windows extensions], though we'll be removing this dependency soon (see bug [https://bugzilla.mozilla.org/show_bug.cgi?id=534371 534371]).

== Installation ==

=== Laying Foundations ===

First, bust a command prompt.

Now get the Cuddlefish/CFX HG Repository:

  hg clone http://hg.mozilla.org/users/avarma_mozilla.com/jep-28/

You should now have a directory called <tt>jep-28</tt>.  Enter it.

If you're on Linux or OS X, run:

  source bin/activate

Or if you're on Windows, run:

  bin\activate

Now you have access to some cool command-line tools from any directory you're in.

=== Sanity Check #1 ===

Run this:

  cfx testall

This should produce output that looks something like this:

<pre>
Testing all available packages: test-harness, cuddlefish.

...........................................................
...........................................................
............................................

Malloc bytes allocated (in use by application): 8872960
Malloc bytes mapped (not necessarily committed): 17653760
Malloc bytes committed (r/w) in default zone: 8882512
Malloc bytes allocated (in use) in default zone: 16605184
Tracked memory objects in testing sandbox: 2

162 of 162 tests passed.
OK
Total time: 1.511243 seconds
Program terminated successfully.
</pre>

'''Note''': If you're on Windows, you may need to add the <tt>--no-quit</tt> option to <tt>cfx</tt> to prevent the above output from disappearing instantly.

Unit and behavioral testing is something that we're trying to make as easy and fast as possible in the Jetpack reboot, because it's imperative that we know when breakages occur between the Mozilla platform and Jetpack, and we also need to make sure that creating new functionality or modifying existing code doesn't break other things.

=== What Is This? ===

The thing you have installed on your computer isn't actually Jetpack, it's Cuddlefish/CFX, which together provide a module, build, packaging, and QA system for Mozilla-based code.  You can read more about Cuddlefish at [[Labs/Jetpack/JEP/28|JEP 28]] and CFX at [[Labs/Jetpack/JEP/31|JEP 31]].

Jetpack is just a package that sits on top of Cuddlefish/CFX, so you'll set that up next.

=== Installing Jetpack ===

Go into the <tt>jep-28/packages</tt> directory.  This contains all the packages that your CFX environment has access to; each package is a directory with a file called <tt>package.json</tt> at its root.  Packages can also contain other packages.

The CFX documentation has more information about all this if you want to learn more; for now, all you need to know is that we're about to fetch an "umbrella package" that contains Jetpack.

From <tt>jep-28/packages</tt>, run:

  hg clone http://hg.mozilla.org/users/avarma_mozilla.com/atul-packages/

This should create a directory at <tt>jep-28/packages/atul-packages</tt>.

=== Updating Jetpack ===

Now that you've got two separate HG repositories, it's kind of a hassle to have to separately update each one.  To alleviate this, the following command will automatically find all HG repositories in the current working directory tree and update them:

  hgall pull -u

Note: the <code>hgall</code> command will execute any HG command, not just <code>pull -u</code>, so you can use it to check the status of the repositories, push changes to them, etc.

=== Sanity Check #2 ===

Run this again:

  cfx testall

A lot more packages should be covered this time, and hopefully all of their tests pass.

You're now ready to start playing with the Jetpack reboot.

== Your First Jetpack ==

First, go to the directory above <tt>jep-28</tt> and make a new one called <tt>my-first-jetpack</tt>.  Then enter it.

=== The Manifest ===

Create a file called <tt>manifest.json</tt> and fill it with this:

<pre>
{
  "name": "My First Jetpack",
  "author": "Me <me@me.com>",
  "capabilities": {
    "notifications": {}
  }
}
</pre>

This JSON manifest contains metadata about your Jetpack, most of which is pretty self-evident.  What's not straightforward, though, is the <tt>capabilities</tt> key.

By default, a Jetpack actually doesn't have access to ''anything''; it's just a JavaScript sandbox that can crunch numbers or munge strings but not much else.  In order to give it access to anything in the world outside its little sandbox, we need to provide it with ''capabilities'': global objects that allow it to talk to the outside world. 

The <tt>capabilities</tt> key in the manifest contains a mapping between names of capabilities and optional parameters for the capabilities.  We might imagine, for instance, that a capability which provides access to the filesystem might use such parameters to attenuate itself only to allow access to a particular directory or set of files.  Notifying the user through non-intrusive messages, which the <tt>notifications</tt> capability we want to use provides, doesn't need any such parameters though, so we'll leave its parameters object empty for now.

=== The Code ===

Next, create a file called <tt>main.js</tt> and put this in it:

<pre>
notifications.show("Hello World!");
</pre>

=== Trying It Out ===

Now we can try running the Jetpack:

  jpx run

The <tt>jpx</tt> command-line tool is similar to <tt>cfx</tt>, only it works on Jetpacks instead of CFX packages.  You should see a brand new profile of Firefox start up, and the "Hello World!" notification should show up somewhere on your screen.

To make changes to your Jetpack, edit <tt>main.js</tt>, exit your browser, and start <tt>jpx run</tt> again.  An in-browser Jetpack development environment is being created to smooth development with features such as "reload this Jetpack".

=== Sharing It ===

You can also build your Jetpack into an XPI to share it with friends:

  jpx xpi

This will create a file called <tt>my-first-jetpack.xpi</tt>.  You can manually install it into Firefox or another Mozilla application, or you can try it out quickly by using <tt>mozrunner</tt>, another command-line tool made available to you by the CFX environment:

  mozrunner -w my-first-jetpack.xpi

You should see Firefox start up, and can go to the "Tools->Add-ons" menu to see your extension listed there.

=== Unit Testing ===

As your Jetpack code becomes non-trivial, you'll want to start writing tests for it.  We've tried to make this as easy as possible.  Just add a function like this to the body of your <tt>main.js</tt>:

<pre>
function testAddition(test) {
  test.assertEqual(1 + 1, 2, "Basic addition should work.");
}
</pre>

Now at the command-line, run:

  jpx test

This will produce output that looks similar to when you ran <tt>cfx testall</tt> earlier.

You can add as many tests as you want to your Jetpack; just put them in global functions that start with the text <tt>test</tt>.  The API for the <tt>test</tt> object that's passed in is fully documented [[Labs/Jetpack/JEP/28#Test_Runner_Objects|here]].

== Writing Capabilities ==

If you know how to code for the Mozilla platform&mdash;that is, if words like XPCOM and XUL don't make you terrified&mdash;then you're welcome to create your own capabilities and contribute them to the community.

We still need to write documentation on how to do this, but to get started, take a look at the [http://hg.mozilla.org/users/avarma_mozilla.com/atul-packages/raw-file/tip/packages/sample-jetpack-capabilities/lib/jetpack-cap-factory-notifications.js source for the notifications capability] and check out [[Labs/Jetpack/JEP/37|JEP 37]].  You'll need to put the capability in a CFX package as a CommonJS module whose filename has the form <tt>jetpack-cap-factory-''name''.js</tt>, where ''name'' is the name of the capability (and the name of the global variable through which the capability is accessed from Jetpacks).

Keep in mind that Cuddlefish uses CommonJS modules, which are not to be confused with JS modules.  Unlike JS modules, CommonJS modules can be unloaded, and you don't have to have an absolute URL to import something, which makes them much easier to reuse.  They're also based on the [http://wiki.commonjs.org/wiki/Modules/1.0 CommonJS standard]; lots of modules are already available in this form and can be reused in a variety of contexts, such as in server-side JS and on the Web.

== Further Reading ==

* The Cuddlefish documentation is at [[Labs/Jetpack/JEP/28|JEP 28]].
* The CFX documentation is at [[Labs/Jetpack/JEP/31|JEP 31]].
* Preliminary Jetpack/JPX documentation is currently a work-in-progress at [[Labs/Jetpack/JEP/37|JEP 37]].