# Package Specification #

A *package* is a directory that, at minimum, contains a JSON file
called `package.json`. This file is also referred to as the
*package manifest*.

## The Package Manifest ##

`package.json` may contain the following keys:

* `name` - the name of the package. The package system will only load
  one package with a given name. This name cannot contain spaces or periods.
  The name defaults to the name of the parent directory. If the package is
  ever built as an XPI and the `fullName` key is not present, this is
  used as the add-on's `em:name` element in its `install.rdf`.

* `fullName` - the full name of the package. It can contain spaces. If
  the package is ever built as an XPI, this is used as the add-on's
  `em:name` element in its `install.rdf`.

* `description` - a String describing the package. If the package is
  ever built as an XPI, this is used as the add-on's
  `em:description` element in its `install.rdf`.

* `author` - the original author of the package. The author may be a
  String including an optional URL in parentheses and optional email
  address in angle brackets. If the package is ever built as an XPI,
  this is used as the add-on's `em:creator` element in its
  `install.rdf`.

* `contributors` - may be an Array of additional author Strings.

* `homepage` - the URL of the package's website.

* `icon` - the relative path from the root of the package to a
  PNG file containing the icon for the package. By default, this
  is `icon.png`. If the package is built as an XPI, this is used
  as the add-on's icon to display in the Add-on Manager's add-ons list.

* `icon64` - the relative path from the root of the package to a
  PNG file containing the icon64 for the package. By default, this
  is `icon64.png`. If the package is built as an XPI, this is used
  as the add-on's icon to display in the Addon Manager's add-on details view.

* `license` - the name of the license as a String, with an optional
  URL in parentheses.

* `id` - a globally unique identifier for the package, a String
  derived from the public half of a private/public keypair, generated
  the first time you run `cfx xpi`. When the package is built as an
  XPI, this is used as the add-on's `em:id` element in its
  `install.rdf`.

* `version` - a String representing the version of the package. If the
  package is ever built as an XPI, this is used as the add-on's
  `em:version` element in its `install.rdf`.

* `dependencies` - a String or Array of Strings representing package
  names that this package requires in order to function properly.

* `lib` - a String representing the top-level module directory provided in
  this package. Defaults to `"lib"`.

* `tests` - a String representing the top-level module directory containing
  test suites for this package. Defaults to `"tests"`.

* `packages` - a String or Array of Strings representing paths to
  directories containing additional packages, defaults to
  `"packages"`.

* `main` - a String representing the name of a program module that is
  located in one of the top-level module directories specified by
  `lib`. Defaults to `"main"`.

* `harnessClassID` - a String in the GUID format:
  `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, where `x` represents a single
  hexadecimal digit. It is used as a `classID` (CID) of the "harness service"
  XPCOM component. Defaults to a random GUID generated by `cfx`.
  

## Documentation ##

A package may optionally contain a
[Markdown](http://daringfireball.net/projects/markdown/)-formatted file
called `README.md` in its root directory. Package-browsing tools may display
this file to developers.

Additionally, Markdown files can be placed in an optional `docs`
directory. When package-browsing tools are asked to show the
documentation for a module, they will look in this directory for a
`.md` file with the module's name. Thus, for instance, if a user
browses to a module at `lib/foo/bar.js`, the package-browsing tool
will look for a file at `docs/foo/bar.js` to represent the module's
API documentation.

## Data Resources ##

Packages may optionally contain a directory called `data` into which
arbitrary files may be placed, such as images or text files. The
URL for these resources may be reached using the
[self](packages/addon-kit/docs/self.html) module.

  [Markdown]: http://daringfireball.net/projects/markdown/
  [non-bootstrapped XUL extension]: #guide/xul-extensions
