874
edits
Labs/Jetpack/JEP/31: Difference between revisions
Jump to navigation
Jump to search
reorganized things a bit, added docs for command-line tools
(→Test Modules: moved test runner object docs to jep-28 and linked to them) |
(reorganized things a bit, added docs for command-line tools) |
||
| Line 17: | Line 17: | ||
* '''Developer Ergonomics.''' cfx uses Cuddlefish's introspection capabilities to provide full stack tracebacks when errors occur; it also provides facilities for making it easy to spot memory leaks, and generally tries to make writing production-quality code as hassle-free as possible. | * '''Developer Ergonomics.''' cfx uses Cuddlefish's introspection capabilities to provide full stack tracebacks when errors occur; it also provides facilities for making it easy to spot memory leaks, and generally tries to make writing production-quality code as hassle-free as possible. | ||
= Prerequisites = | * '''No Dependency Hell For Users.''' the XPIs generated by cfx are fully self-sufficient and their only requirement is the Mozilla platform. This means that all their package-level dependencies are automatically rolled into the XPI and stored such that multiple versions of them can exist side-by-side with other cfx-generated XPIs. | ||
= Specification = | |||
== Packages == | |||
A ''package'' is simply a directory that contains a JSON file called <tt>package.json</tt>. | |||
<tt>package.json</tt> may contain the following keys: | |||
* <tt>name</tt> - the name of the package. The package system will only load one package with a given name. The name defaults to the name of the parent directory. If the package is ever built as an XPI, this is used as the extension's <tt>em:name</tt> element in its <tt>install.rdf</tt>. | |||
* <tt>description</tt> - a String describing the package. If the package is ever built as an XPI, this is used as the extension's <tt>em:description</tt> element in its <tt>install.rdf</tt>. | |||
* <tt>author</tt> - 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 extension's <tt>em:creator</tt> element in its <tt>install.rdf</tt>. | |||
* <tt>contributors</tt> - may be an Array of additional author Strings. | |||
* <tt>url</tt> - the URL of the package's website. | |||
* <tt>license</tt> - the name of the license as a String, with an optional URL in parentheses. | |||
* <tt>id</tt> - a globally unique identifier for the package, which is usually either a String in the form of a GUID or an email address. If the package is ever built as an XPI, this is used as the extension's <tt>em:id</tt> element in its <tt>install.rdf</tt>. | |||
* <tt>version</tt> - a String representing the version of the package. If the package is ever built as an XPI, this is used as the extension's <tt>em:version</tt> element in its <tt>install.rdf</tt>. | |||
* <tt>dependencies</tt> - a String or Array of Strings representing package names that this package requires in order to function properly. | |||
* <tt>lib</tt> - a String or Array of Strings representing top-level module directories provided in this package. Defaults to <tt>"lib"</tt>. | |||
* <tt>tests</tt> - a String or Array of Strings representing top-level module directories containing test suites for this package. Defaults to <tt>"tests"</tt>. | |||
* <tt>main</tt> - a String representing the name of a program module that is located in one of the top-level module directories specified by <tt>lib</tt>. | |||
== Modules == | |||
All modules in cfx packages are [http://wiki.commonjs.org/wiki/Modules/1.1 CommonJS modules], and also support the global objects provided by [[Labs/Jetpack/JEP/28|Cuddlefish]]. | |||
=== Test Modules === | |||
A test module is any module located in one of the top-level module directories specified by the <tt>"tests"</tt> key in <tt>package.json</tt> whose filename starts with the prefix <tt>test-</tt>. All its exported functions are assumed to be test cases or a suite of test cases; each is called with a single argument, <tt>test</tt>, which is a [[Labs/Jetpack/JEP/28#Test_Runner_Objects|Test Runner Object]]. | |||
=== Program Modules === | |||
A program module is a module named by the <tt>"main"</tt> key in <tt>package.json</tt> and located in one of the top-level directories specified by the <tt>"lib"</tt> key. It is expected to export a function called <tt>main()</tt> which contains a program body. | |||
= Usage = | |||
== Prerequisites == | |||
The current reference implementation of cfx is available via Mercurial: | The current reference implementation of cfx is available via Mercurial: | ||
| Line 24: | Line 72: | ||
Using this implementation requires Python 2.5 or greater. On Windows, it also requires the [http://python.net/crew/skippy/win32/Downloads.html Win32 Extensions for Python]. | Using this implementation requires Python 2.5 or greater. On Windows, it also requires the [http://python.net/crew/skippy/win32/Downloads.html Win32 Extensions for Python]. | ||
== Environments == | == Environments == | ||
| Line 43: | Line 89: | ||
At any time, <tt>deactivate</tt> can be entered to deactivate the environment and return the shell to its original state. | At any time, <tt>deactivate</tt> can be entered to deactivate the environment and return the shell to its original state. | ||
== | == Package Management == | ||
Packages are simply subdirectories of the <tt>packages</tt> directory, which is located in the root of the cfx repository. | Packages are simply subdirectories of the <tt>packages</tt> directory, which is located in the root of the cfx repository. | ||
At the moment, package ''management'' functionality is outside the scope of cfx. This means that it is currently the developer's responsibility to manually manage the installation, removal, and updating of packages on their own. | At the moment, package ''management'' functionality is outside the scope of cfx. This means that it is currently the developer's responsibility to manually manage the installation, removal, and updating of packages on their own. | ||
== | == Command-Line Tools == | ||
=== <tt>cfx</tt> === | |||
The | The <tt>cfx</tt> command-line tool, made globally available upon environment activation, offers a variety of mechanisms to aid in the development, testing, and deployment of packages. | ||
All <tt>cfx</tt> commands perform some action based, by default, on the current directory, which is expected to be the root of a package and hence contain a <tt>package.json</tt> file. | |||
Executing <tt>cfx --help</tt> from the command line yields the following output: | |||
<pre> | |||
Usage: cfx [options] [command] | |||
Commands: | |||
xpcom - build xpcom component | |||
xpi - generate an xpi | |||
test - run tests | |||
run - run program | |||
Options: | |||
-h, --help show this help message and exit | |||
-c COMPONENTS, --components=COMPONENTS | |||
extra XPCOM component dir(s), comma-separated | |||
-a APP, --app=APP app to run: xulrunner (default), firefox, or | |||
thunderbird | |||
-s MOZ_SRCDIR, --srcdir=MOZ_SRCDIR | |||
Mozilla source dir | |||
-x ITERATIONS, --times=ITERATIONS | |||
number of times to run tests | |||
-p PKGDIR, --pkgdir=PKGDIR | |||
package dir containing package.json; default is | |||
current directory | |||
-b BINARY, --binary=BINARY | |||
path to app binary | |||
-v, --verbose enable lots of output | |||
-t TEMPLATEDIR, --templatedir=TEMPLATEDIR | |||
XULRunner app/ext. template | |||
-o MOZ_OBJDIR, --objdir=MOZ_OBJDIR | |||
Mozilla objdir | |||
</pre> | |||
=== <tt>mozrunner</tt> === | |||
cfx includes Mikeal Rogers' <tt>mozrunner</tt> command-line tool, which in turn uses his [http://mikeal.github.com/mozrunner/ mozrunner Python package]. | |||
Executing <tt>mozrunner --help</tt> yields the following output: | |||
<pre> | |||
Usage: mozrunner [options] | |||
== | Options: | ||
-h, --help show this help message and exit | |||
-n, --no-new-profile Do not create new profile. | |||
-b BINARY, --binary=BINARY | |||
Binary path. | |||
-w PLUGINS, --plugins=PLUGINS | |||
Plugin paths to install. | |||
-p PROFILE, --profile=PROFILE | |||
Profile path. | |||
-d DEFAULT_PROFILE, --default-profile=DEFAULT_PROFILE | |||
Default profile path. | |||
</pre> | |||
= Examples = | |||