cfx

The cfx command-line tool gives you access to the SDK documentation and development servers as well as testing, running, and building packages. 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 only applicable to a subset of the commands.

Supported Commands

cfx docs

This command displays the documentation for the SDK. The documentation is shipped with the SDK in Markdown format. The first time this command is executed, and any time after the Markdown files on disk have changed, cfx docs will generate a set of HTML pages from them and launch a web browser to display them. If the Markdown files haven't changed, cfx docs just launches a browser initialized to the set of generated pages.

To regenerate the documentation associated with a single file, you can specify the file as an argument. For example:

  cfx docs doc/dev-guide-source/addon-development/cfx-tool.md 

This command will regenerate only the HTML page you're reading. This is useful if you're iteratively editing a single file, and don't want to wait for cfx to regenerate the complete documentation tree.

cfx init

Create a new directory, 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:

  README.md
  package.json
  data/
  lib/
      main.js
  tests/
      test-main.js
  docs/
      main.md

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.

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".

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 and run its tests by loading from the tests directory any modules that start with the word test- and calling each of their exported functions, passing them a test runner object as an argument.

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
          --update-url https://example.com/addon/update_rdf

cfx will create two files:

• an XPI file which embeds https://example.com/addon/update_rdf as the value of updateURL
• an RDF file which embeds https://example.com/addon/latest 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

Experimental Commands

cfx develop

This initiates an instance of a host application in development mode, and allows you to pipe commands into it from another shell without having to constantly restart it. Aside from convenience, for SDK Platform developers this has the added benefit of making it easier to detect leaks.

For example, in shell A, type:

  cfx develop

In shell B, type:

  cfx test --use-server

This will send cfx test --use-server output to shell A. If you repeat the command in shell B, cfx test --use-server output will appear again in shell A without restarting the host application.

cfx develop doesn't take any options.

Internal Commands

cfx sdocs

Executing this command builds a static HTML version of the SDK documentation that can be hosted on a web server without the special application support required by cfx docs.

Options

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 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 --profile-dir="~/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 member of the options object passed as the first argument to your program's main function. The default value of --static-args is "{}" (an empty object), so you don't have to worry about checking whether staticArgs exists in options.

For example, if your main.js looks like this:

exports.main = function (options, callbacks) {
  console.log(options.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: 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.