cfx

Enables you to test, run, and package add-ons. cfx has been deprecated, jpm should now be used instead. cfx usage is:

  cfx [options] command [command-specific options]

"Options" are global options applicable to the tool itself or to all commands (for example --help). cfx supports the following global options:

  -h, --help        - show a help message and exit
  -v, --verbose     - enable lots of output

"Command-specific options" are documented alongside the commands.

There are four supported cfx commands:

There are also a number of internal commands, which are more likely to be useful to SDK developers than to add-on developers.

cfx init

Create a new directory called "my-addon", change into it, and run cfx init.

This command will create an skeleton add-on, as a starting point for your own add-on development, with the following file structure:

• my-addon
  • data
  • docs
    • main.md
  • lib
    • main.js
  • package.json
  • README.md
  • tests
    • test-main.js

cfx run

This command is used to run the add-on. Called with no options it looks for a file called package.json in the current directory, loads the corresponding add-on, and runs it under the version of Firefox it finds in the platform's default install path.

Supported Options

You can point cfx run at a different package.json file using the --pkgdir option, and pass arguments to your add-on using the --static-args option.

You can specify a different version of the host application using the --binary option, passing in the path to the application binary to run. The path may be specified as a full path or may be relative to the current directory. But note that the version must be 4.0b7 or later.

cfx run runs the host application with a new profile. You can specify an existing profile using the --profiledir option, and this gives you access to that profile's history, bookmarks, and other add-ons. This enables you to run your add-on alongside debuggers like Firebug. See "Using --profiledir" for more information.

cfx run --binary-args -jsconsole

cfx run --binary-args '-url "www.mozilla.org" -jsconsole'

Experimental Options

cfx run ---no-run

To launch the application, enter the following command:
 /path/to/firefox/firefox-bin -profile
 /path/to/profile/tmpJDNlP6.mozrunner -foreground -no-remote

Internal Options

cfx test

Run available tests for the specified package.

Called with no options this command will look for a file called package.json in the current directory. If package.json exists, cfx will load the corresponding add-on, load from the tests directory any modules that start with the word test- and run the unit tests they contain.

Note the hyphen after "test" in the module name. cfx test will include a module called "test-myCode.js", but will exclude modules called "test_myCode.js" or "testMyCode.js".

See the tutorial on unit testing and the reference documentation for the assert module for details.

Supported Options

As with cfx run you can use options to control which host application binary version to use, and to select a profile.

You can also control which tests are run: you can test dependent packages, filter the tests by name and run tests multiple times.

cfx run --binary-args -jsconsole

cfx run --binary-args '-url "www.mozilla.org" -jsconsole'

Experimental Options

cfx run ---no-run

To launch the application, enter the following command:
 /path/to/firefox/firefox-bin -profile
 /path/to/profile/tmpJDNlP6.mozrunner -foreground -no-remote

Internal Options

cfx xpi

This tool is used to package your add-on as an XPI file, which is the install file format for Mozilla add-ons.

Called with no options, this command looks for a file called package.json in the current directory and creates the corresponding XPI file.

Once you have built an XPI file you can distribute your add-on by submitting it to addons.mozilla.org.

updateURL and updateLink

If you choose to host the XPI yourself you should enable the host application to find new versions of your add-on.

To do this, include a URL in the XPI called the updateURL: the host application will go here to get information about updates. At the updateURL you host a file in the update RDF format: among other things, this includes another URL called updateLink which points to the updated XPI itself.

The --update-link and --update-url options simplify this process. Both options take a URL as an argument.

The --update-link option builds an update RDF alongside the XPI, and embeds the supplied URL in the update RDF as the value of updateLink.

The --update-url option embeds the supplied URL in the XPI file, as the value of updateURL.

Note that as the add-on documentation explains, you should make sure the update procedure for your add-on is secure, and this usually involves using HTTPS for the links.

So if we run the following command:

  cfx xpi --update-link https://example.com/addon/latest/pluginName.xpi --update-url https://example.com/addon/update_rdf/pluginName.update.rdf

cfx will create two files:

• an XPI file which embeds https://example.com/addon/update_rdf/pluginName.update.rdf as the value of updateURL
• an RDF file which embeds https://example.com/addon/latest/pluginName.xpi as the value of updateLink.

Supported Options

As with cfx run you can point cfx at a different package.json file using the --pkgdir option. You can also embed arguments in the XPI using the --static-args option: if you do this the arguments will be passed to your add-on whenever it is run.

Experimental Options

Internal Options

Internal Commands

cfx testcfx

This will run a number of tests on the cfx tool, including tests against the documentation. Use cfx testcfx -v for the specific list of tests.

This accepts the same options as cfx test.

cfx testaddons

This will run a number of test add-ons that are packaged with the SDK.

This accepts the same options as cfx test.

cfx testpkgs

This will test all of the available CommonJS packages. Note that the number of tests run and their success depends on what application they are run with, and which binary is used.

This accepts the same options as cfx test.

cfx testex

This will test all available example code. Note that the number of tests run and their success depends on what application they are run with, and which binary is used.

This accepts the same options as cfx test.

cfx testall

This will test everything: the cfx tool, all available CommonJS packages, and all examples.

This accepts the same options as cfx test.

Using --profiledir

By default, cfx run and cfx test use a new profile each time they are executed. This means that any profile-specific data entered from one run of cfx will not, by default, be available in the next run.

This includes, for example, any extra add-ons you installed, or your history, or any data stored using the simple-storage API.

To make cfx use a specific profile, pass the --profiledir option, specifying the path to the profile you wish to use.

If you give --profiledir a path to a nonexistent profile, cfx will create a profile there for you. So you just have to make up a path and name the first time, and keep using it:

cfx run --profiledir=~/addon-dev/profiles/boogaloo

The path must contain at least one "/" (although you may specify just "./dir").

Using Configurations

The --use-config option enables you to specify a set of options as a named configuration in a file, then pass them to cfx by referencing the named set.

You define configurations in a file called local.json which should live in the root directory of your SDK. Configurations are listed under a key called "configs".

Suppose your the following local.json is as follows:

  {
      "configs": {
          "ff40": ["-b", "/usr/bin/firefox-4.0"]
      }
  }

You can run:

  cfx test --use-config=ff40

And it would be equivalent to:

  cfx test -a firefox -b /usr/bin/firefox-4.0

This method of defining configuration options can be used for all of the run, build, and test tools. If "default" is defined in the local.json cfx will use that configuration unless otherwise specified.

Passing Static Arguments

You can use the cfx --static-args option to pass arbitrary data to your program. This may be especially useful if you run cfx from a script.

The value of --static-args must be a JSON string. The object encoded by the JSON becomes the staticArgs property of the system module.

The default value of --static-args is "{}" (an empty object), so you don't have to worry about checking whether staticArgs exists in system.

For example, if your add-on looks like this:

var system = require("sdk/system");
console.log(system.staticArgs.foo);

And you run cfx like this:

  cfx run --static-args="{ \"foo\": \"Hello from the command line\" }"

Then your console should contain this:

info: my-addon: Hello from the command line

The --static-args option is recognized by two of the package-specific commands: run and xpi. When used with the xpi command, the JSON is packaged with the XPI's harness options and will therefore be used whenever the program in the XPI is run.