Sencha Cmd 包(Packages)

Sencha Cmd 包含了 Sencha 包管理器. 包设计用于解决二个基本问题: 使用和发布. 本向导聚焦于这些主题. 同时请查看 创建 Sencha Cmd 包(Packages) 来获得关于创建和共享包的资料.

"packages" 文件夹

所有由 Sencha Cmd 生成的工作区的根目录下都有一个 "packages" 文件夹. 这个文件夹的位置可以进行配置,但没什么实际意义, "packages"文件夹的角色是服务于工作区中的应用(或者其它包)使用到的所有包的存储.

packages/       # Container folder for shared Cmd packages
    local/      # Folder for packages generated in this workspace
    remote/     # Folder for packages downloaded into the workspace

根据应用需要下载下来的包将会被添加到 "packages/remote" 文件夹. 而当一个包生成后(使用 sencha generate package), 将会生成在 "packages/local" 文件夹.

应用中要求使用的包

一个包的来源没有关系 (不管是本地生成的还是从远程库下载的 - 参见下面), 假设一个相同的包: 你在 "app.json" 中加入了一个 requires 配置 . 为演示的目的,我们增加了一个简单包用于练习:

{
    "name": "MyApp",
    "requires": [
        "cool-stuff"
    ]
}

按照上面给出的要求, sencha app build 和 sencha app refresh 命令都将执行用于集成这个包到你的应用中的步骤. 典型的处理是在修改了包的要求后,你需要运行 sencha app refresh 以便这些需要元素来支持 “dev mode” 获得更新.

不管你使用哪个命令, Sencha Cmd 都将会下载和解开这个包到你的 "packages/remote" 文件夹. 完成这个操作后你会在你工作区下的这个目录下看到这个 "packages/remote/cool-stuff" 包.

本地包

包的一个用途是简单的保留一个工作区内为多个应用使用的代码或主题.这些包不需要发布出来给你的开发提供价值(在源代码控制之外).

添加一个包到你的工作区,你只需要生成这个包:

sencha generate package common

这将在 "packages/local/common" 文件夹中生成一个新的包.这个包也在 "package.json"文件中被标识为 local: true. 这个标志用于防止 Sencha Cmd 可能从一个远程库(见下面)中去获取一个版本的包来覆盖. 如果包文件夹通过编辑"workspace.json"组合 (因为它们在以前的发布的版本中) 这个就变得非常重要.

然后在你的应用的 "app.json"文件中添加 “common” 包的引入:

{
    "name": "MyApp",
    "requires": [
        "common"
    ]
}

要获取更多资料, 尤其是关于怎么发布包给其他开发者,参考 Creating Sencha Cmd 包(Packages).

远程包

当本地包在大型应用中特别有价值, 包的一个最重要的方面就是能发布出来提供给其他开发者使用.

包通过使用包库来分享和发布. Sencha Cmd 自动创建一个 “本地库” 来缓存包也用来发布包. 包作者本地库的作用在这个向导中不做讨论.详细的信息参考 Creating Sencha Cmd 包(Packages) 主题.

本地库

许多操作显式地使用本地库. 在 "app.json"文件中配置了requires Senc语句时, Sencha Cmd 遵循下面的基本步骤:

• 先在工作区间查看是否存在这个包.
• 检查本地库来查看是否已经下载了一个对应版本的包.
• 查看设置定义的远程库查看是否有一个这样的包.
• 从远程库下载这个包和添加到本地库中.

当一个包下载完成后,随后对这个包的请求就不再需要下载了,这个包就能在本地库找到了.

本地库的位置

本地库 在一个有着各种用于缓存的版本号的文件夹“旁边”的文件夹中生成.例如在Windows上为用户 Foo 安装Sencha Cmd的默认安装目录象下面这样:

C:\Users\Foo\bin\Sencha\Cmd\n.n.n.n

给定这个安装目录, 本地库会被位于:

C:\Users\Foo\bin\Sencha\Cmd\repo

这个也可以通过编辑在Sencha Cmd 安装目录下的"sencha.cfg"文件来进行修改.

本地库中的内容将在 Creating Sencha Cmd 包(Packages) 进行进一步的讨论.

远程库

为了将包下载到本地库, Sencha Cmd 必须知道远程库.默认情况下, Sencha Cmd自动添加 Sencha Package 库作为远程库并命名为 “sencha”.

查看远程库的列表, 运行这个 sencha repository list 命令:

> sencha repository list
...
[INF] Remote repository connections (1):
[INF]
[INF]     sencha - http://cdn.sencha.com/cmd/packages/

你可以通过 sencha repository add 和 sencha repository remove 命令来添加和删除远程库. 你的本地库如果选择通过主机进行发布实际上对于其他开发者来说也是一个有效的远程库. 更多详细信息,参考 Creating Sencha Cmd 包(Packages).

包目录

可供使用的包的设置在 “catalog” 中列出来了.你通过这个命令可以显示全局目录中的内容:

sencha package list

当你列出这些包后,你会注意到列表中包含了名字和版本.

命名赋值

因为 Sencha Cmd 的库管理被发布了并且你可以按照需要来添加和删除远程库,这就没一个包的通用命名空间.如果你保留默认的 “sencha” 连接到 Sencha Package Repository ( Sencha 包库), 那么你能查看库中的内容来作为命名标准.

通过Sencha发布的包 (不包括 Sencha 框架里面的包) 会使用下面形式的名字:

• sencha-*
• ext-*
• touch-*
• cmd-*

所有通过Sencha以上面的前缀开始命名的包名由都保留给Sencha Package Repository来使用. 即使你从Sencha Package Repository远程库断开了也建议你避免与这些名字冲突.

版本管理

为连接包和它们的使用者 (就是应用和其它包), 重要的是要考虑包的版本. 为了帮助管理这些,所有包都有一个版本号用于在使用 requires 语句来处理版本约束.

包的版本

所有包都通过它们的名字和版本组合来描述. 对一个包的所一个版本,然而还有另外一个版本数字来描述向后兼容的程度.这个版本是包的创建者生成的一个说明,他们相信包的特殊版本向后兼容一些特定的以前版本的级别.

在 "package.json" 文件描述中有二个重要的属性: version and compatVersion. 例如:

{
    ...
    "version": "n.n.n",
    "compatVersion": "2.4.2",
    ...
}

这个数字必须是以下的格式:

\d+(\.\d+)*

版本约束

当使用上面的 requires 属性我们只是定义了包的名字来让这个例子尽可能简单.这就是说恰好用的是 “最新版本”.有些情况下这是可以接受的,但当一个包的下一个版本进行了完全重构并没有提供向后兼容的级别时会带来风险要求.

为避免你的应用产生这个情况,我们能修改 require 语句来进行非常严格的约束并且锁信我们需要的版本号:

{
    "name": "MyApp",
    "requires": [
        "ext-easy-button@1.0"
    ]
}

这种方法有它的地方,但它防止甚至维护的版本会被使用.在项目的最终阶段,这可能是理想的,但在开发时也许我们要少一些约束并且可以接受任一兼容的版本.

下面的修改可以满足这点:

{
    "name": "MyApp",
    "requires": [
        "ext-easy-button@1.0?"
    ]
}

上面请求的是f "ext-easy-button"最后有效的版本,并且自描述为可以兼容到版 1.0 .

另外一个约束版本匹配的方法是:

• -1.2 (无下被 - 向上到版本 1.2)
• 1.0- (无上限 - 版本 1.0 或更高)
• 1.0+ (同上 - 版本 1.0 或更高)
• 1.0-1.2 (版本 1.0 以上 到 1.2 包含 )
• 1.0-1.2? (与 1.0 版本兼容以上到 1.2 含 )

解决版本

鉴于所有的所需的和可用的版本, Sencha Cmd 会决定最好的一套匹配包并且确保这些在你的工作区.

如果有相互排斥的需求,那么就可能失败. 在这种情况下,你会看到一个解释哪个需求不能满足要求的信息.