jpm

cfx 的Node版本允许你测试、运行以及打包扩展。

你也可以阅读 jpm教程 开始学习。

jpm 用法:

jpm [command] [options]

jpm支持以下全局参数:

-h, --help        - 显示帮助信息并退出
-V, --version     - 打印出jpm版本号
--addon-dir       - 源代码目录，默认为当前目录

安装

jpm发布在node包管理器 npm 上。

安装npm

有两种方法来获取npm。

• 访问 nodejs.org 下载并安装Node.js。Node.js 包含npm。
• 或者，如果你的系统有像 APT 这种包管理器，就用它来安装。例如，在 Ubuntu 或者 Debian 的终端窗口里，输入sudo apt-get install nodejs nodejs-legacy npm

要测试安装是否成功，运行：

​/usr/bin/env node -v

如果出现错误提示  /usr/bin/env: node: No such file or directory 并且你的 nodejs 是通过包管理的方式安装的，那你的 nodejs 很有可能安装为其它的名字。为了保证jpm的兼容，PATH之中必须是以node为可执行文件名的。在Debian和Ubuntu系统上，你可以通过安装兼容包nodejs-legacy来解决这个问题：

sudo apt-get install nodejs-legacy

在其它的发行版中，你或许必须手动创建一共本地符号链接：​

sudo ln -s "$(which nodejs)" /usr/local/bin/node

安装jpm

在你安装好npm并且将其加入你的PATH中后，你可以像安装其他npm包一样来安装jpm。

全局安装jpm

npm install jpm --global

取决于你的安装，你可能需要管理员权限执行:

sudo npm install jpm --global

局部安装jpm

如果你不想，或者不能够全局安装jpm，你或许可以只为你安装它：

npm install jpm

在局部安装的情况下，为了在终端中运行jpm，你必须首先将目录"$HOME/node_modules/.bin/"添加到你的终端PATH中。将下行中的命令添加到$HOME/.profile的末尾来实现永久添加（.profile将在每次运行一个新终端时被执行）：

export PATH="$HOME/node_modules/.bin/:$PATH"

通过git来安装jpm

另外，你也可以通过git安装jpm的最新版本

git clone https://github.com/mozilla-jetpack/jpm.git
cd jpm
npm install
npm link

jpm安装完毕后

在全部搞定后，在命令行窗口中输入:

jpm

屏幕上显示了一系列可用的 jpm 命令。不同于 cfx，当在安装时使用了 --global 参数，你能在任何路径下启动的命令提示符中使用 jpm 命令。

还有问题？

如果你看不懂本文，要寻求帮助。SDK 用户和项目团队成员在项目邮件列表中讨论问题和建议。其他人也许会和你有一样的问题，所以试着搜索一下列表。也欢迎你发表一个新问题。你也可以在 Mozilla 的 IRC 网络 的 #jetpack 房间里和其他SDK的用户聊天。

命令参考

有六个命令：

jpm init

这个命令从头开始初始化一个新的 add-on。

新建一个目录，转到该目录下，然后运行 jpm init。

mkdir my-addon
cd my-addon
jpm init

然后你会被要求提供关于你的 add-on 的一些信息：这会用来创建 package.json 文件。

• title
• name: 默认是你运行 jpm init 的目录名。除非package.json里有 id 字段， jpm 在name前面加个"@"用作 add-on 安装清单的 id 字段.
• version
• description
• entry point (映射向package.json中的 "main")
• author
• engines (支持哪些应用程序)
• license

大部分字段都有一个默认值，显示在那些问题的后面的括号里。如果你按了回车，那么你的 add-on 就用那个默认值。

一旦你提供了一个值或者接受了默认值，你会看到"package.json"的完整内容，并被询问是否接受。

然后 jpm 创建一个基本的 add-on，作为你开发的起点，文件结构如下：

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

jpm run

此命令运行一个新的装有你的 add-on 的 Firefox实例：

jpm run

jpm run 有以下选项：

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

jpm run --binary-args -jsconsole

jpm run --binary-args '-url mzl.la -jsconsole'

jpm test

这个命令用来运行 add-on 的单元测试。命令：

• 查找在当前目录（或者 --addon-dir 目录）下的test文件夹。
• 打开所有名字以 "test-" 开头的文件。注意文件名中"test"后面的连字符号。jpm test 包含一个 "test-myCode.js" 文件，但会排除"test_myCode.js"或"test_myCode.js"。
• 调用文件中所有export的、以"test"开头的函数。

jpm test

查看 单元测试教程 和 assert 模块参考文档获取更多具体内容。

jpm test 接受一下选项：

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

jpm test --binary-args -jsconsole

jpm test --binary-args '-url mzl.la -jsconsole'

jpm test --filter base64:btoa

jpm test --stop-on-error

jpm test --times 2

jpm xpi

这个命令将 add-on 打包为一个 XPI 文件，这是 Mozilla 附加组件的安装文件的格式。

jpm xpi

它会在当前目录(或者 --addon-dir 指定的目录）查找 package.json 文件，并创建相关的 XPI 文件。它忽略任何 ZIP 或 XPI文件（译者注：OSX 上测试下来不会默认忽略这些文件，若要忽略请编辑.jpmignore文件），以及任何测试文件。它会包含其他所有文件。如果你想排除其他文件，查看 .jpmignore 文件。

一旦你构建了一个 XPI 文件，你可以通过提交到 addons.mozilla.org 来分发你的附加组件。

jpm xpi 接受下列选项：

jpm xpi -v

jpm post

这个命令把附加组件打包为 XPI 后 post 到某个URL。

jpm post

查找当前目录（或 --addon-dir）下的package.json 文件，创建 XPI 文件，post 到 --post-url。

jpm post 接受以下选项：

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

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

jpm watchpost

这个命令在打包附件组件为 XPI 文件后，无论文件是否改变都将其 post 到某个URL。

jpm watchpost

无论文件是否改变，在当前目录（或 --addon-dir）下创建一个 XPI并将其post到 --post-url。

jpm watchpost 接受以下选项：

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

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

jpm sign

此特性仅从 jpm 1.0.4 起被支持。

此命令为你的附加组件重新生成一个新的被Mozilla签名的 XPI 文件。这就允许你自己托管你的 add-on，这样用户可以在安装时避免 signed add-ons are required 错误。在用这个命令之前，你需要在 addons.mozilla.org 创建 API 证书。

你可以为你已经生成的 XPI 文件签名，就像如下，通过传递 XPI 文件给 --xpi参数：

jpm sign --api-key ${AMO_API_KEY} --api-secret ${AMO_API_SECRET} --xpi <xpi file>

或者，你可以省略 --xpi 参数，这样 jpm sign 会从当前目录（或者 --addon-dir）生成一个XPI文件。

jpm sign --api-key ${AMO_API_KEY} --api-secret ${AMO_API_SECRET}

上面提交了一个 XPI 到 addons.mozilla.org 签名g API，如果通过验证，然后下载一个签名后的 XPI 文件到工作目录。

下面是一些运行 sign 命令的结果：

• 你的 add-on 通过验证，被 Mozilla 签名，并且一个新的签名后的 XPI 文件被下载到你的工作目录。
• 你的 add-on 没有通过验证，没有签名，你获取到一个详细报告的链接。修复验证错误以后，你可以再次运行这个命令。
• 你的 add-on 公公验证，但是它不能自动签名，因为你的 add-on 是列表上的。列表上的 add-ons 需要人工复核才能被签名。
• 你的 add-on 已经存在某个版本号了，所以它没有被签名。增加 package.json 文件中的版本号并且再次运行命令。

在底层，jpm sign 在addons.mozilla.org里创建了一个不会被列出的附加组件，这就意味着你必须自己把XPI文件分发给你的用户来安装。如果你需要创建一个在列表中的附加组件，只要直接将它提交到 addons.mozilla.org，在那里它自动会被签名。如果你在安装一个已签名的附加组件时遇到困难，参看调试一节。

jpm sign 接收以下参数：

一些技巧

选择浏览器版本

默认地，jpm run 和 jpm test 运行 release 版本的 FireFox。你可以有一两种办法来告诉 jpm 使用一个不同的版本：

• 你可以使用 -b 或者 --binary 选项来告诉 jpm 去使用一个不同版本的 Firefox。你可以提供一个指定二进制文件的路径：

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

  有个简化的方法，你可以传递"nightly"、"aurora"、"beta"或者"firefox"然后jpm会在默认位置寻找这些 Firefox 的版本：

  jpm run -b nightly

• 你可以设置 JPM_FIREFOX_BINARY 环境变量为你想运行的 Firefox 版本的路径。在你调用 jpm run 或 jpm test 而不带 -b 选项时，jpm 首先检查 JPM_FIREFOX_BINARY，并且将其当做已设置的路径来用。

使用 .jpmignore 来忽略文件

使用 .jpmignore 就像使用 git 的.gitignore，Mercurial 的 .hgignore，或者 npm 的 .npmignore。通过使用这个文件，你可以在使用 jpm xpi 编译 .xpi 文件时，让 jpm 知道你想要忽略哪些文件。

这是个例子：

# Ignore .DS_Store files created by mac
.DS_Store

# Ignore any zip or xpi files
*.zip
*.xpi

有着以上内容的 .jpmignore 文件会忽略所有的 zip 文件和 .DS_Store 文件，这些文件不会包括在 jpm xpi 所生成的 xpi 文件中。

使用配置

默认地，jpm run 每次都会使用一个新的配置。这就意味着前一次运行 jpm 时的任何配置，默认都不会在下一次中使用。

这其中包括，比如你安装的任何附加组件，或者你的历史记录，或者任何使用 simple-storage API 存储的数据。

为了让 jpm 使用一个特定的配置，传递 --profile 选项，设定你想使用的配置文件的名字，或者是配置文件的路径。

jpm run --profile boogaloo

jpm run --profile path/to/boogaloo

如果你提供了 --profile 但是它的参数不是一个已有配置文件的名字或路径，jpm 会打开 配置文件管理器 让你选择一个已有的配置文件或者创建一个新的配置文件：

jpm run --profile i-dont-exist

开发时不用重启浏览器

因为每次调用 jpm run 时都会重启浏览，如果你十分频繁地修改附加组件，这就可能有点笨重了。一个替代的开发模型是使用 扩展自动安装器附加组件：它会在特定端口监听新 XPI 文件并且自动安装它们。这样，你就能测试新的改动，而不用重启浏览器：

• 修改附件组件
• 运行 jpm post --post-url https://localhost:8888/，来创建 XPI 文件并提交。

你甚至可以用一个简单的脚本来自动化这一工作流程。例如：

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

注意，比起使用 jpm run 运行附加组件时的日志级别，你在使用这个方法时控制台定义的日志级别是不一样的。这意味着，如果你想看到 console.log() 消息的输出，你必须微调一下配置。查看 logging levels 文档以获取这方面的详细信息。

重载内建模块

你用来实现你的附加组件的SDK模快是 Firefox 内建的。当你使用 jpm run 或 jpm xpi 来运行或者打包附加组件时，附加组件使用其所在的 Firefox 版本中的模块版本。

作为附件组件开发者，这一般就是你想要的。但是如果你在开发 SDK 模块本身，这就不合适了。这时你需要：

• 获取你想要的 SDK 模块的本地拷贝：一般来说就是从 GitHub 仓库中检出SDK。
• 设置 JETPACK_ROOT 环境变量，指向你的本地拷贝
• 传递 -o 选项到 jpm run 或 jpm xpi：

jpm run -o

这会通知 jpm 去使用 SDK 模块的本地拷贝，而不是 Firefox 内部的模块。如果你不想设置 JETPACK_ROOT 环境变量，你可以使用 -o 传递SDK模块本地拷贝的位置：

jpm run -o "/path/to/addon-sdk/"

路径必须是一个绝对路径并且指向 SDK 的根目录（不是 addon-sdk/sdk 或 addon-sdk/sdk/lib）。

支持自托管附加组件的更新

此特性仅被 jpm 1.0.3 及之后版本支持，

当你给你的附加组件来添加特性或者修复 bug 时，你想让之前安装好的附加组件将自己从老版本更新到新版本。

如果你在 addons.mozilla.org 上列出你的附加组件，那么你要做的只是提交一个新的版本；附加组件默认会检查它们在 addons.mozilla.org 上的新版本。好了，你不用继续往下看这一节了。

如果你没有在 addons.mozilla.org 上列出你的附加组件，你需要生成一个 Mozilla 签名的 XPI 文件并告诉 Firefox 哪里可以找到这个附加组件的新版本。方法就是：

• 每次你想要创建一个新版本时，你运行 jpm sign
• 当你需要更新时，更新由你托管的签名好的附加组件
• 你维护一个“更新清单”，包含了指向那个 XPI 的URL
• 你的附加组件告诉 Firefox 哪里可以找到更新清单

为了达到这个目的，package.json中需要包含两个额外的key ：

• updateURL：这个 URL 包含在 jpm xpi 所编译的 XPI 文件的安装清单中。他指向了你的更新清单。updateURL 值可以是HTTPS的。如果不是，那么你也可以签名的更新清单，并且使用 package.json 文件中的 updateKey 字段来包含其公钥。参看 安全地更新 以获取这方面更多信息
• updateLink：这个 URL 包含在那个更新清单文件中。它指向了 XPI，并且必须是一个 HTTPS URL。

如果你设置了 updateURL 和 updateLink（如果 updateKey 不是 HTTPS 的，那也要包括 updateKey），那么 jpm xpi 会：

• 生成 XPI 文件时将 updateURL 设置为你提供的值。
• 和 XPI 文件一起，生成更新清单，并将清单中的 updateURL 设置为你提供的值。

然后你将更新清单托管到 updateURL，并且将新版 XPI 托管到 updateLink。

获取更多这方面的详细信息，参看自动检查附件组件更新。