mozilla
Your Search Results

    jpm

    The Add-on SDK includes a command-line tool that you use to initialize, run, test, and package add-ons. The current tool is written in Python and called cfx, but we're working on a replacement, based on Node.js, that we're calling jpm.

    You can use jpm from Firefox 38 onwards.

    This article is the reference for jpm.

    The Node-based replacement for cfx. Enables you to test, run, and package add-ons.

    See also jpm tutorial for getting started.

    jpm usage is:

    jpm [command] [options]
    

    jpm supports the following global options:

    -h, --help        - show a help message and exit
    -V, --version     - print the jpm version number
    

    Installation

    jpm is distributed using the node package manager npm, so to get jpm you need to have npm installed, if you haven't already. npm is included in Node.js, so to install npm, visit nodejs.org and click the Install button.

    After that you can install jpm just as you would any other npm package:

    npm install jpm -g

    Depending on your setup, you might need to run this as an administrator:

    sudo npm install jpm -g

    At the command prompt, type:

    jpm

    You should see a screen summarizing the available jpm commands. Note that unlike cfx, jpm is available in every command prompt you start, as long as you installed it with the -g flag.

    Problems?

    If you don't see this, ask for help. SDK users and project team members discuss problems and proposals on the project mailing list. Someone else may have had the same problem you do, so try searching the list. You're welcome to post a question, too. You can also chat with other SDK users in #jetpack on Mozilla's IRC network.

    Command reference

    There are four jpm commands:

    jpm init Create a skeleton add-on as a starting point for your own add-on.
    jpm run Launch an instance of Firefox with your add-on installed.
    jpm test Runs your add-on's unit tests.
    jpm xpi Package your add-on as an XPI file, which is the install file format for Firefox add-ons.
    jpm post Package your add-on as an XPI file, then post it to some url.
    jpm watchpost Package your add-on as an XPI file whenever there is a file changed, and post that to some url.

    jpm init

    This command initializes a new add-on from scratch.

    Create a new directory, change into it, and run jpm init.

    mkdir my-addon
    cd my-addon
    jpm init

    You'll then be asked to supply some information about your add-on: this will be used to create your add-on's package.json file.

    Most of these fields have a default, which is shown in brackets after the question. If you just press Enter, your add-on will get the default value.

    Once you've supplied a value or accepted the default for these properties, you'll be shown the complete contents of "package.json" and asked to accept it.

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

    • my-addon
      • index.js
      • package.json
      • test
        • test-index.js

    jpm run

    This command runs a new instance of Firefox with the add-on installed:

    jpm run

    jpm run accepts the following options:

    -b --binary BINARY

    Use the version of Firefox specified in BINARY. BINARY may be specified as a full path or as a path relative to the current directory.

    jpm run -b /path/to/Firefox/Nightly
    See Selecting a browser version.
    --binary-args CMDARGS

    Pass extra arguments to Firefox.

    For example, to pass the -jsconsole argument to Firefox, which will launch the Browser Console, try the following:

    jpm run --binary-args -jsconsole

    To pass multiple arguments, or arguments containing spaces, quote them:

    jpm run --binary-args '-url mzl.la -jsconsole'
    --debug Run the add-on debugger attached to the add-on.
    -o --overload PATH

    Rather than use the SDK modules built into Firefox, use the modules found at PATH. If -o is specified and PATH is omitted, jpm will look for the JETPACK_ROOT environment variable and use its value as the path.

    See Overloading the built-in modules for more information.

    -p --profile= PROFILE

    By default, jpm uses a clean temporary Firefox profile each time you call jpm run. Use the --profile option to instruct jpm to launch Firefox with an existing profile.

    The PROFILE value may be a profile name or the path to the profile.

    See Using profiles for more information.

    -v --verbose Verbose operation.

    jpm test

    Use this command to run an add-on's unit tests. It will:

    • look for a directory called "test" under the add-on's root
    • open every file in there whose name starts with "test-" (note the hyphen after "test" in the filename. jpm test will include a file called "test-myCode.js", but will exclude files called "test_myCode.js" or "testMyCode.js")
    • call every function exported from that file whose name starts with "test"
    jpm test
    

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

    jpm test accepts the following options:

    -b --binary BINARY

    Use the version of Firefox specified in BINARY. BINARY may be specified as a full path or as a path relative to the current directory.

    jpm test -b /path/to/Firefox/Nightly

    See Selecting a browser version.

    --binary-args CMDARGS

    Pass extra arguments to Firefox.

    For example, to pass the -jsconsole argument to Firefox, which will launch the Browser Console, try the following:

    jpm test --binary-args -jsconsole

    To pass multiple arguments, or arguments containing spaces, quote them:

    jpm test --binary-args '-url mzl.la -jsconsole'
    --debug Run the add-on debugger attached to the add-on.
    -f --filter FILE[:TEST]

    Only run tests whose filenames match FILE and optionally match TEST, both regexps.

    jpm test --filter base64:btoa

    The above command only runs tests in files whose names contain "base64", and in those files only runs tests whose names contain "btoa".

    -o --overload PATH

    Rather than use the SDK modules built into Firefox, use the modules found at PATH. If -o is specified and PATH is omitted, jpm will look for the JETPACK_ROOT environment variable and use its value as the path.

    See Overloading the built-in modules for more information.

    -p --profile PROFILE

    By default, jpm uses a clean temporary Firefox profile each time you call jpm run. Use the --profile option to instruct jpm to launch Firefox with an existing profile.

    The PROFILE value may be a profile name or the path to the profile.

    See Using profiles for more information.

    --stop-on-error

    By default jpm test keeps running tests even after tests fail. Specify --stop-on-error to stop running tests after the first failure:

    jpm test --stop-on-error
    --tbpl Print test output in Treeherder format
    --times NUMBER

    Run tests NUMBER of times:

    jpm test --times 2
    -v --verbose Verbose operation.
    --no-copy
    Use with caution because jpm run|test changes many preferences, never use with your main profile.
    This only applies when --profile is used.
    Disables the copying of the profile used, which allows one to reuse a profile.

    jpm xpi

    This command packages the add-on as an XPI file, which is the install file format for Mozilla add-ons.

    jpm xpi

    It looks for a file called package.json in the current directory and creates the corresponding XPI file. It ignores any ZIPs or XPIs in the add-on's root, and any test files.

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

    jpm xpi accepts the following option:

    -v --verbose

    Verbose operation:

    jpm xpi -v

    jpm post

    This command packages the add-on as an XPI file, the posts it to some url.

    jpm post

    It looks for a file called package.json in the current directory and creates a XPI file with which to post to the --post-url.

    jpm post accepts the following options:

    --post-url URL

    The url to post the extension to after creating a XPI.

    jpm post --post-url http://localhost:8888/

    See Using Post and Watchpost for more information.

    -v --verbose

    Verbose operation:

    jpm post --post-url http://localhost:8888/ -v

    jpm watchpost

    This command packages the add-on as an XPI file, the posts it to some url whenever a file in the current working directory changes.

    jpm watchpost

    Creates a XPI whenever a file in the current working directory changes and posts that to the --post-url.

    jpm watchpost accepts the following options:

    --post-url URL

    The url to post the extension to after creating a XPI.

    jpm watchpost --post-url http://localhost:8888/

    See Using Post and Watchpost for more information.

    -v --verbose

    Verbose operation:

    jpm watchpost --post-url http://localhost:8888/ -v

    Techniques

    Selecting a browser version

    By default, jpm run and jpm test will run the release version of Firefox. You can instruct jpm to use a different version in one of two ways:

    • you can use the -b or --binary option to instruct jpm to run a different version of Firefox. You can supply a path to a specific binary:

      jpm run -b /path/to/Firefox/Nightly

      As a shorthand for this, you can pass "nightly", "aurora", "beta", or "firefox" and jpm will look in the default location for these Firefox versions:

      jpm run -b nightly
    • you can set the JPM_FIREFOX_BINARY environment variable with the path to the version of Firefox you want to run. When you invoke jpm run or jpm test without the -b option, jpm will first check¬† JPM_FIREFOX_BINARY, and use this as the path if it is set.

    Using profiles

    By default, jpm run uses a new profile each time it is executed. This means that any profile-specific data entered from one run of jpm 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 jpm use a specific profile, pass the --profile option, specifying the name of the profile you wish to use, or the path to the profile.

    jpm run --profile boogaloo
    
    jpm run --profile path/to/boogaloo

    If you supply --profile but its argument is not the name of or path to an existing profile, jpm will open the profile manager,  enabling you to select and existing profile or create a new one:

    jpm run --profile i-dont-exist

    Developing without browser restarts

    Because jpm run restarts the browser each time you invoke it, it can be a little cumbersome if you are making very frequent changes to an add-on. An alternative development model is to use the Extension Auto-Installer add-on: this listens for new XPI files on a specified port and installs them automatically. That way you can test new changes without needing to restart the browser:

    • make a change to your add-on
    • run jpm post --post-url http://localhost:8888/, to make a xpi and post it.

    You could even automate this workflow with a simple script. For example:

    jpm watchpost --post-url http://localhost:8888/
    

    Note that the logging level defined for the console is different when you use this method, compared to the logging level used when an add-on is run using jpm run. This means that if you want to see output from console.log() messages, you'll have to tweak a setting. See the documentation on logging levels for the details on this.

    Overloading the built-in modules

    The SDK modules you use to implement your add-on are built into Firefox. When you run or package an add-on using jpm run or jpm xpi, the add-on will use the versions of the modules in the version of Firefox that hosts it.

    As an add-on developer, this is usually what you want. But if you're developing the SDK modules themselves, of course, it isn't. In this case you need to:

    • get a local copy of the SDK modules that you want: this usually means checking out the SDK from its GitHub repo
    • set the JETPACK_ROOT environment variable to your local copy
    • pass the -o option to jpm run or jpm xpi:
    jpm run -o
    

    This instructs jpm to use the local copies of the SDK modules, not the ones in Firefox. If you don't want to set the JETPACK_ROOT environment variable, you can pass the location of your copy of the SDK modules along with -o:

    jpm run -o "/path/to/SDK/"

    Document Tags and Contributors

    Tags: 
    Contributors to this page: wbamberg, edmorley, evold, maybe
    Last updated by: evold,
    Hide Sidebar