这篇翻译不完整。请帮忙从英语翻译这篇文章

你能在Firefox 38或更高的版本中使用jpm。

本文为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 作为你 add-on 的开端。
jpm run 运行一个带有你的 add-on 的 Firefox 实例。
jpm test 运行你插件的单元测试
jpm xpi 将你的插件打包为 XPI 文件(火狐的插件扩展文件名)
jpm post 把你的 add-on 打包成 XPI 文件,然后发送到某一个URL。
jpm watchpost 无论是否有文件变更,把你的 add-on 打包成 XPI 文件发送到某一个URL。
jpm sign 将你的插件打包为 XPI 文件并且取回一个由Mozilla签名的新XPI文件。

jpm init

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

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

mkdir my-addon
cd my-addon
jpm init

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

大部分字段都有一个默认值,显示在那些问题的后面的括号里。如果你按了回车,那么你的 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 有以下选项:

-b --binary BINARY

指定二进制文件,使用该版本的火狐。可以用全路径,也可以用相对路径。

jpm run -b /path/to/Firefox/Nightly
参看选择浏览器版本
--binary-args CMDARGS

传递附件参数到 Firefox。

例如,为了传递 -jsconsole参数给 Firefox 并打开浏览器,试试下面命令:

jpm run --binary-args -jsconsole

要传递多个参数,或者参数中间有空格,就把他们用引号括起来:

jpm run --binary-args '-url mzl.la -jsconsole'
--debug 运行这个 add-on 的Add-on 调试器
-o --overload PATH

不再使用 Firefox 内建的 SDK 模块,使用指定 PATH 路径下的模块。如果加了 -o 但 PATH 没有指定,jpm 会寻找 JETPACK_ROOT 环境变量用作路径

参看重载内建模块以获取更多信息

-p --profile= PROFILE

在你每次调用jpm run时,jpm 默认使用一个干净的临时的 Firefox 配置文件(profile)。使用--profile 选项以使得 jpm 使用已有的配置文件来打开 Firefox。

PROFILE的值可以是一个profile的名字或路径。

参看 使用 profile 以获取更多信息。

-v --verbose (查看)详细操作
--no-copy
小心使用,因为 jpm run|test 会改变很多配置,不要和你的主配置文件一起使用。
只有使用 --profile 的时候回生效
禁止配置文件的拷贝,允许重用配置。
 

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 接受一下选项:

-b --binary BINARY

指定所用 Firefox 的版本。BINARY 可被指定为绝对路径或者基于当前路径的相对路径。

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

请查看选择一个浏览器版本

--binary-args CMDARGS

传递附件参数给 Firefox。

例如,传递 -jsconsole 参数,它会打开浏览器控制台,试试下面的命令:

jpm test --binary-args -jsconsole

传递多个参数,或者参数间有空格,请将它们用引号括起来:

jpm test --binary-args '-url mzl.la -jsconsole'
--debug 运行 add-on debugger 附件到当前 add-on 上。
-f --filter FILE[:TEST]

只运行名字和 FILE 匹配的测试文件,且名字匹配 TEST(可选)的测试函数。

jpm test --filter base64:btoa

上面的命令值会运行名字中含有"base64"的文件,在这些文件中只会运行名字中含有"btoa"的测试函数。

-o --overload PATH

不使用 Firefox 内建的模块,而使用 PATH 路径下的模块。如果 -o 指定而 PATH 被忽略,jpm会查找 JETPACK_ROOT 环境变量并将其用作路径。

查看重载内建模块以获取更多信息。

-p --profile PROFILE

你每次运行jpm call时,默认地,jpm使用一个干净的临时 Firefox 配置文件。使用--profile 选项来让 jpm 使用一个现有配置文件来打开火狐。

PROFILE 的值可以是配置文件的名称或者指向配置文件的路径。

查看使用配置文件来获取更多信息。

--stop-on-error

即使测试失败,jpm test 默认还会继续运行测试。指定 --stop-on-error 的话,会在第一次失败后停止运行测试

jpm test --stop-on-error
--tbpl Treeherder 格式打印 test 的输出
--times NUMBER

运行几遍 test:

jpm test --times 2
-v --verbose 详细操作。
--no-copy

小心使用,因为 jpm run|test 会修改许多首选项,这些首选项在你的主配置文件中从未用过。

这仅仅在使用 --profile 时生效。

禁用配置未经的拷贝,允许用户重用配置文件。

jpm xpi

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

jpm xpi

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

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

jpm xpi 接受下列选项:

-v --verbose

打印详细操作:

jpm xpi -v

jpm post

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

jpm post

查找当前目录(或 --addon-dir)下的package.json 文件,创建 XPI 文件,post 到 --post-url

jpm post 接受以下选项:

--post-url URL

创建 XPI 文件后,将扩展 post 到这个URL。

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

查看使用 Post 和 Watchpost 获取更多信息。

-v --verbose

打印详细操作:

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

jpm watchpost

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

jpm watchpost

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

jpm watchpost 接受以下选项:

--post-url URL

创建 XPI 文件后,将扩展 post 到这个URL。

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

查看 Using Post 和 Watchpost 获取更多信息。

-v --verbose

打印详细信息:

jpm watchpost --post-url http://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}

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

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

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

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

jpm sign 接收以下参数:

--api-key=API_KEY

addons.mozilla.org key管理页面生成的API访问key(字符串)。

--api-secret=API_SECRET

addons.mozilla.org key 管理页面生成的API访问密钥(字符串)。这个值应该被小心保密并且永远不要记录到版本控制中。如果你的密钥被破解,另一个开发者就能上传附加组件到你的账号上。你应该立即撤销泄露的API证书并且重新生成一份。

--api-url-prefix=http://.../api

可选的API URL前缀,如果你想使用一个试用签名的API。

例如,你可以通过https://addons-dev.allizom.org/api/v3的认证来使用addons.mozilla.org的开发者版本。

--xpi=/path/to/file.xpi

需要签名的XPI文件。如果没指定文件,一个新的XPI会在当前目录(或者--addon-dir)中生成。

一些技巧

选择浏览器版本

默认地,jpm runjpm 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 runjpm 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 http://localhost:8888/,来创建 XPI 文件并提交。

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

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

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

重载内建模块

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

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

  • 获取你想要的 SDK 模块的本地拷贝:一般来说就是从 GitHub 仓库中检出SDK。
  • 设置 JETPACK_ROOT 环境变量,指向你的本地拷贝
  • 传递 -o 选项到 jpm runjpm 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。

如果你设置了 updateURLupdateLink(如果 updateKey 不是 HTTPS 的,那也要包括 updateKey),那么 jpm xpi 会:

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

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

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

 
 

文档标签和贡献者

标签: 
 此页面的贡献者: zaobao, yangwang, feix.chow, nullest
 最后编辑者: zaobao,