2 min read

Zed包管理器

本文译自Zed Package Manager | Zed

前阵子,我们给Zed加了一个很酷的特性ZPM,不过没有大肆宣传。你可以猜到,ZPM表示”Zed Package Manager”,它最初由Andrew Stephan完成。

可以想知,ZPM在将来会大有改进,但现在,还是让我说说,它是怎么运作的:怎样安装、管理应用包,自己如何开发应用包来扩展Zed的功能。

让我们先从安装与管理说起。

安装与管理

安装Zed应用包很简单,你所需要的,是一份Zed(废话)和你要安装的应用包的URI地址(关于URI后面会聊更多)。

想看看现在都安装了哪些应用包?在编辑窗口里运行Tools:Zpm:Installed Packages命令,它会打开一个会话,列出目前安装的所有应用包,你还可以在这里卸载、更新、更新所有应用包,当然,也可以安装新应用包。列表用普通Zed文件当用户界面,你可以用键盘(移动光标到“按钮”然后按回车)或鼠标(鼠标直接点击某个“按钮”)操作。需注意的是,Zed预安装的应用包是不能卸载的(界面上确实有一个卸载选项,但其实没用)。

要安装新应用包,请点击”Install New”按钮。你也可以运行Tools:Zpm:Install(任何地方都可以,不强制一定要从已安装应用包界面)。然后,输入应用包URI。你可以试试一个简单的应用包gh:zefhemel/sample-zed-package(后面我们会说明如何开发)。安装完成后,你应该有了一个新命令My Test Command,执行后会弹出”Hello world”对话框。

Awesomeness。

Zed目前的应用包是分散的,没有Sublime或Atom那样的中心库。不过暂时可以用Zed wiki替代。

深入

本质上说,应用包不过是提供一种简单方法,帮你安装一些文件到configuration项目。你可以查看Configuration项目下的/packages(这里借助树型结构是最方便的:Command-T/Ctrl-T)文件夹,你能看到一些预安装的应用包。截至写下这篇的时候,以下模式是以Zed应用包形式分发的:

以后,会有更多的内置模式迁移到Zed应用包上,不过这个任务不轻,所以会花些时间。

如果你打开你的Configuration项目下的/default.json文件,你能看到一个packages键:

packages: [
    "gh:zedapp/javascript-mode",
    "gh:zedapp/json-mode",
    "gh:zedapp/json5-mode",
    "gh:zedapp/php-mode",
    "gh:zedapp/css-mode",
    "gh:zedapp/jsx-mode"
]

Zed会确保这里列出的应用包都已安装,并自动更新。如果你自个安装了一个应用包,则可以在你的/user.json文件里找到它。

那么,这些应用包从哪儿来?一个应用包的URI可以是一个完整的HTTP链接,指向一个目录,目录下包含一个package.json文件。当然,你也可以使用快捷方式。一个快捷URI带有gh:(github)或bb:(bitbucket)前缀(目前是这样)。它们会扩展(举gh:zedapp/javascript-mode来说)成https://raw.githubusercontent.com/zedapp/javascript-mode/master/。ZPM据此补缀package.json,找到一个类似如下的JSON文件:

{
    "name": "JavaScript mode",
    "uri": "gh:zedapp/javascript-mode",
    "version": "0.2",
    "description": "JavaScript mode for Zed",
    "files": [
        "beautify-js.js",
        "beautify.js",
        "check.js",
        "index.js",
        "jshint.js"
    ]
}

所需的键如下:

  • uri:该URI与人们用来安装你的应用包使用的URI必须一致(否则的话,你可能遭遇不对劲)
  • name:显示在UI中的应用包的名称
  • description:显示在UI中的描述内容
  • version:版本号,你一旦更新这个数字,则那些已安装你应用包的人们就能自动升级它们(ZPM每隔几小时检查一次更新)
  • files:组成应用包的文件的相对路径列表(package.jsonconfig.json会自动包含,你不必自己添加它们到列表)

每一个应用包,除了package.json文件外,至少还应该有一个config.json文件,文件中包含常见的Zed配置,比如定义新命令,模式,样式主题或任何其他你的应用包提供的东西。譬如这个JavaScript模式的配置。其余的文件多数只是些JavaScript文件,用于落实config文件中列出的命令。

开发你自己的应用包

准备

你要做的第一件事,是将你的configuration项目保存到一个本地目录(而不是SyncFS,这是Chrome版Zed默认保存的位置)。原因是你可能需要上传或推送你的应用包到诸如Github这样的地方,这样你就需要能直接访问这些文件。在Chrome版中,你可以运行Configuration:Store in Local Folder命令。如果你用的是独立版本的Zed,则Linux下,你的配置文件保存在~/.config/zed/config,Mac下则保存在~/Library/Application Support/zed/config。如果你想把配置文件保存到其他地方,则使用Configuration:Set Configuration Directory命令。我个人是把我的配置保存在我的Dropbox文件夹中。

想想在哪儿托管你的应用包

我建议你在Gihub或Bitbucket上给你的应用包创建一个公共代码库。本篇中,我们会拿我托管在我zefhemel github账户上的一个叫做sample-zed-package的Github库作例子。

创建应用包

Configuration项目里有些专为开发者设计的命令,可以让你迅速开工。运行命令Tools:Zpm:Create Package。这会弹出对话框要求你输入应用包的URI。我们且输入gh:zefhemel/sample-zed-package(可替换成你的任一库名)。

这样我们就在/packages/gh/zefhemel/sample-zed-package/目录下创建了两个文件,package.jsonconfig.json。默认会打开package.json文件。请根据你的意思修改它的默认值,比如:

{
    "name": "My First Zed Package",
    "uri": "gh:zefhemel/sample-zed-package",
    "version": "1.0",
    "description": "A useful new package",
    "files": []
}

接下来,让我们打开同一目录下的config.json文件(小贴士:按Command-E/Ctrl-E调出Goto后按空格键补全当前目录完整路径,然后选择config.json)。

就我们的情况,只需定义一个命令样例:

commands: {
        "My Test Command": {
            scriptUrl: "./command.js"
        }
    }
}

接下来,让我们新建/packages/gh/zefhemel/sample-zed-package/command.js(同样使用Goto小贴士):

var ui = require("zed/ui");

module.exports = function(info) {
    return ui.prompt("Hello world!");
};

如你所见,Zed的命令是用CommonJS风格模块化的。它导出一个函数,该函数接收一个变量(info)。取决于你的配置,变量会包含一些命令执行环境的有用信息。Zed不断有增加API,允许你与编辑器互动,所有的这些API都可以通过require zed/*模块取得。你可以看看你Configuration项目里/api/zed目录下有什么。我得承认,这些API的文档还很欠缺,因此在文档完善前,建议多看些示例。比如Configuration项目:所有的已安装的应用包,模式,主题样式和各种命令的代码都在那儿,随你查阅。如果你有特定的问题,请加入Zed Google Group提问!

为测试我们新创建的项目,我们需要将它添加到/user.json里的应用包列表:

packages: [
    "gh:zefhemel/sample-zed-package"
]

你的配置会自动重载,因此新命令已经可用。你可以运行My Test Command命令验证一下。如果没有,可以使用Configuration:Reload命令强制重载你的配置。如果你改的是config.json文件,则每次都需要强制重载。另一个你会经常用到的命令是Sandbox:Reset,它会确保你的JavaScript代码在下一次它被调用时重载。

发布你的应用包

在发布你的应用包前,我们需要记住一个重要的事情:更新我们的package.json文件,引入所有其余的文件(指除开package.json与config.json外的文件)。好在Zed有提供一个便利的命令:切换到你的package.json文件,然后执行Tools:Zpm:Update Package.json File List。这个命令会自动扫描你的项目,然后更新package.json文件来引用command.js文件。

Zed方面就这些了。总之,剩下要做的,就是把我们的应用包目录变成一个git目录,commit所有文件,然后push到github。

首先,打开命令窗口,cd到你的Zed Configuration目录,然后cd到我们的应用包目录:

$ cd packages/gh/zefhemel/sample-zed-package

在目录下初始化一个git库,然后添加所有文件并commit:

$ git init
$ git add *
$ git commit -m "Initial checkin"

将我们之前创建的github库配置为远程并把代码推上去。我的情况:

$ git remote add origin git@github.com:zefhemel/sample-zed-package.git
$ git push -u origin master

就这样。

测试你的应用包

在告知我们所有的朋友前,我们还需要测试下应用包。我通常是另外备一份Zed(我或者是用独立版本做开发,Chrome版本做测试或者反过来,或者是使用安装在Chrome Canary上的Zed)。此外你也可以切换你的Zed配置到一个全新、干净的目录,随后再切换回来。目的就只是准备一个还没有安装过你的应用包的Zed。你甚至可以换一台电脑(比如你的Chromebook)。

要安装你的应用包,请在你干净版的Zed运行Tools:Zpm:Install命令,然后输入应用包URI。如果一切顺利,你的命令应该已经可用了。除了执行Tools:Zpm:Install命令外,你也可以手动更新配置中的packages列表,增加你的应用包URI。效果是一样的。

管用?恭喜,请务必将你的应用包添加到我们的维基页面

开发与调试贴士

为了开发Zed应用包,你最好把Configuration项目当成一个开发环境。我通常是先添加新模式与命令到/user.json文件里,如果没问题,再迁移到应用包里。

Logging:每个项目都有一个zed::log文件,会列出Zed给出的提示,错误与警告以及沙箱代码。如果你的应用包或脚本不能正常运行,请先检查zed::log找找头绪,看哪里可能出错了。你也可以在你的JavaScript中使用console.log等来调试,它们输出的结果也会显示在zed::log中([Sandbox]前缀)。

重载/重启:通过沙箱运行的方式,Zed严格地把所有应用包和扩展代码从编辑器本身区分开来,这样你无需重启或重开编辑器窗口就可以编辑应用包并马上测试结果。只是你需要重载你的配置文件(config.json),为此你可以运行Configuration:Reload命令。如果你修改你的JavaScript代码,运行Sandbox:Reset命令,Zed会重载这些文件,你就可以看到修改的情况。

Protip:如果你要做很多Zed应用包的开发工作,最好是把Configuration:ReloadSandbox:Reset命令绑定给键组合。譬如我在我的/user.json文件里:

keys: {
    "Sandbox:Reset": "Ctrl-Shift-S",
    "Configuration:Reload": "Ctrl-Alt-Shift-S"
}

常见问题

  • 如果在你添加你的应用包到/user.json文件中的packages键后,配置一直在重载,一个可能的原因是,package.json中定义的URI与应用包的路径不匹配。换句话说,如果你的的应用包URI是gh:abc/def,则你的package.json必须放在/packages/gh/abc/def/package.json位置。如果不是,循环的问题就会出现。
  • 如果安装或运行应用包时,你在zed::log里看到404错误,则问题很可能出在你package.json文件中的files列表。如果安装应用包时出现404,请确保package.jsonfiles键列出的文件均存在。如果404出现在安装后的测试中,则确保Zed声称找不到的文件出现在你的package.json文件里的files键下。

这就好了!让我们看看你能开发出什么!

报告问题 修订