注册 登录  
 加关注
   显示下一条  |  关闭
温馨提示!由于新浪微博认证机制调整,您的新浪微博帐号绑定已过期,请重新绑定!立即重新绑定新浪微博》  |  关闭

韩国恺的博客

hanguokai.com

 
 
 

日志

 
 

Dart 语言入门(七)——包管理工具 Pub  

2012-12-31 23:31:35|  分类: Dart |  标签: |举报 |字号 订阅

  下载LOFTER 我的照片书  |
更新日期:2012年12月31日

Dart 语言入门(七)——包管理工具 Pub - hanguokai - 韩国恺的博客

包(package)管理系统非常多,主要目的都是解决版本管理依赖关系的问题,如 Ruby有RubyGems、Bundler、Node.js有npm、Java有Maven、Linux有apt-get 等等。Dart 也有自己的包管理工具 Pub,已包含在SDK 中(Pub是酒馆、客栈的意思,Dart是飞镖的意思,而飞镖是酒馆中常见的一种游戏)。

Pub 主要受 bundler 模型的启发,使用一个 yaml 格式的 pubspec 描述文件。Pub 中的包就是一个目录,可以包含各种东西,如代码、资源、测试、文档等。库(library)和应用(application)都是包。库是用来被重用的代码,包含了需要被别人导入的代码。而应用只是使用其它包实现自己功能。

急速使用入门:
1. 在项目根目录新建一个名为 pubspec.yaml 的文件,需要包含如下内容项:
  a) name 项表示你的应用名或库名。
  b) dependencies 项下面添加需要依赖的包,基本格式为 name: version 。
2. 在根目录下运行 pub install 命令安装依赖,修改配置文件或需要更新时运行 pub update 命令。
3. 在需要使用的 dart 文件中,使用 import 导入包,格式为:import 'package:xxx';

下面是一个简单的 pubspec.yaml 示例文件:

name: my_app
description: A sample application

dependencies:
unittest: 0.2.9+7

这里包名是 my_app,它依赖一个单元测试库 unittest 。

pub install 会递归地安装所有包需要依赖的其它包,并在根目录下创建了一个名为 packages 的目录,其中包含了所有需要的包。这个 packages 目录不应该提交到源码版本管理中

更新时,pub update 命令会更新你依赖的所有包到可用的最新版本。如果你只想更新某个特定的包,可以使用 pub update packageName 。

pubspec.lock
在执行过 pub install 之后,根目录下会出现一个 pubspec.lock 的文件,它记录了你当前直接或间接依赖的所有包及其当前使用的版本。如果你的包是一个应用,那么应该把它提交到源码版本管理中,这样别人在使用这个应用时会使用和你完全一样的包。如果你的包是一个库,那么不要把它提交到源码版本管理中。

使用 Dart Editor 的话,以上的前两步都有自动化支持。Dart Editor 的支持包括:
  • 在新建项目时勾选“Add Pub support”,默认已选中,这会自动新建 pubspec.yaml 文件。
  • 当 pubspec 文件修改时会自动执行 pub ,也可通过 Tools 菜单下的 Pub Install 和 Pub Update 手工执行。如果不想默认自动执行,可以在 Dart Editor 的 Preferences 中取消勾选 “Automatically run Pub”。
  • 支持对 pubspec.yaml 文件的可视化编辑功能,鼠标右键点击 pubspec 文件,然后选择 "Open with Pubspec Editor"。

如果你只是为了使用第三方库,OK,学到这里就够用了。如果你想了解更多细节,那么请接着往下看。

补充说明:
Pub 会下载安装所有依赖的包,这些包其实都被下载缓存到了"system cache"目录下,而你包下的 packages 目录中出现的所有包其实只是"system cache"目录下的包的符号链接。在 Mac 和 Linux 下,这个目录默认是 ~/.pub-cache 目录,在 Windows 下是 AppData\Roaming\Pub\Cache 目录。所以,同一个包的同一个版本只会下载一次,并被所有使用它的包共用。

pubspec.yaml 文件说明
pubspec.yaml 本身采用 YAML 的语法规范编写。文件中的顶层可以包含下面这些项:
  • name: 这个应用或库的包名,所有包必须有,包括Dart应用
  • version: 版本号,发布到 pub.dartlang.org 上的包必须有
  • description: 简短描述,发布到 pub.dartlang.org 上的包必须有
  • author/authors: 作者,可选
  • homepage: 项目主页的URL,可选,如 github 上的项目网址
  • dependencies: 依赖的其它库,根据情况自行配置
例如:

name: newtify
version: 1.2.3
description: >
Have you been turned into a newt? Would you like to be? This
package can help: it has all of the newt-transmogrification
functionality you've been looking for.
author: Nathan Weizenbaum <nweiz@google.com>
homepage: http://newtify.dartlang.org
dependencies:
efts: '>=2.0.4 <3.0.0'
transmogrify: '>=0.4.0'

name 的要求:全部小写,使用下划线分词,如 just_like_this。
要求符合 Dart 标示符的规范,所以可以使用字符、数字和下划线,但不能以数字开头,也不能使用保留字。
包名应该取一个简洁清晰的名字,如果是要发布到 pub.dartlang.org 上的包还需要确保名字没有被别人使用。

version 的要求:发布到 pub.dartlang.org 上的包必须要有版本号,而本地自己使用的包可以忽略(默认是0.0.0)。
版本号的格式为用点分隔的三个数字,如 1.0.2 。版本号还可以有一个可选的后缀描述作为 build 或 pre-release 的版本,如 1.0.0-alpha、1.0.0+build.1 。
当然,版本号应该符合通常的要求,每次发布新版本时使用一个新的版本号。另外,可以参考这个版本号语义的网站。

author/authors: 如果包只有一个作者,那么使用 author 字段。如果有多个作者,那么使用 authors 字段(一个 YAML 的列表)。
author 的内容可以只是一个名字,也可以是名字加Email,如:

authors:
- Nathan Weizenbaum <nweiz@google.com>
- Bob Nystrom <rnystrom@google.com>


依赖配置
dependencies 选项列出包所依赖的其它包。只需要列出所有直接依赖包即可,间接依赖的包会被自动处理。
一般情况下,在 dependencies 列表中的每项只需要使用 name: version 的格式即可,如

dependencies:
transmogrify: '>=0.4.0 <1.0.0'

前面的 name 是依赖的包的包名,也就是它们在 pubspec.yaml 顶层配置的 name 项。

依赖中的版本约束
包名后面配置的是版本约束信息,它由一组空格分隔的版本描述组成。也可以省略,省略的话代表 any 。每个版本描述可以按下面这样定义:
 any 或 省略 任意版本都可以。
 1.2.3 只能是这个特定的版本。尽量避免这样用,因为你的包依赖了某个特定版本的包,如果别人要使用你的包并且他们本身也直接或间接也依赖那个包,就可能会遇到麻烦。
 >=1.2.3 大于等于某个版本,经常用。
 >1.2.3
 大于某个版本,但不包括这个版本。
 <=1.2.3 小于等于某个版本,不太常用。
 <1.2.3 小于某个版本,但不包括这个版本。经常用,如果你知道某个版本开始出现了不兼容的变化,而你又依赖之前的版本。
注意:因为版本描述之间是用空格分隔,所以其中(比较符号与版本号之间)就不能再有空格。另外,因为大于号本身也是 YAML 中定义的语法,所以使用的时候需要用引号括起来。

对于应用而言,一般会期望使用依赖包的最新版本,并不需要太关心版本约束。但是对于库而言,指定库所依赖的其它包的版本约束就很重要,你应该尽可能大的指定依赖的版本范围,这样别人在使用你的包的时候就会更加灵活,但也不要大到你还不确定的范围。

SDK 中的包
Dart SDK 中的 pkg 目录下有一些工具包,可以在依赖项中添加特殊的 sdk 格式使用它们,如:

dependencies:
unittest: { sdk: unittest }

// 或者

dependencies:
unittest: 

sdk: unittest

不过现在这些工具包大都已上传到 pub.dartlang.org 上了,所以只要按照标准的方式使用即可,无需使用 sdk 格式。

不同的配置源
前面描述的依赖配置默认使用的都是 pub.dartlang.org 这个数据源,如果使用其它网站的数据源需要额外的配置,如:

dependencies:
transmogrify:
hosted:
name: transmogrify
url: http://some-package-server.com
version: '>=1.0.0 <2.0.0'


直接使用 Git 上的包
有时候依赖的包还处于开发中,没有正式发布,所以可能需要直接从 git 上获取这个包。可以按如下的方式指定:

dependencies:
kittens:
git:
url: git://github.com/munificent/kittens.git
ref: some-branch

url 是要从 git 中 clone 的包,这个包应该在该 git 仓库的根目录下面。如果需要指定特定的版本或分支,可以通过 ref 项指定。

包的布局约定
包其实就是一个目录,其中可以有各种文件和目录,为了避免混乱,Dart 有一些自己的约定。下面是一个比较全面的目录结构示例,你可能不需要所有这些:

enchilada/
pubspec.yaml
pubspec.lock *
README.md
LICENSE
bin/
enchilada
packages/ **
doc/
getting_started.md
example/
lunch.dart
packages/ **
lib/
enchilada.dart
tortilla.dart
src/
beans.dart
queso.dart
packages/ **
test/
enchilada_test.dart
tortilla_test.dart
packages/ **
tool/
generate_docs.dart
web/
index.html
main.dart
style.css

开源社区一般会包含一些 README, LICENSE, AUTHORS 等文件,你可以把它们放在包的根目录下,一般至少应该包含一个 README 文件。

lib 目录
对库而言,最重要的是 lib 目录,里面放的是被使用者导入的 dart 文件。一般的库可能只需要导入一个 dart 文件,那么按照惯例这个文件名应该就是包名,如这里的 enchilada.dart 。当然,也可以定义其它文件。用户在导入时就是以 lib 目录为根的(当然前面还要有包名),如 import "package:enchilada/enchilada.dart"; 。在 lib 目录下可以有 src 子目录,放的是库的实现文件。

web 目录
web 目录下可以放各种 web 资源,如 css、images 等。任何 Dart 的 web 入口点应该放在 web 目录下。

bin 目录
如果你的包可以通过命令行直接运行,那么启动脚本(如 shell 脚本或其它脚本,也可以是dart脚本)应该放在 bin 目录下,而不是 lib 目录下。

test 目录
test 目录放包的测试代码,测试代码的文件名应该以 _test 为后缀,如这里的 enchilada_test.dart 。

doc 目录
doc 目录放包的文档,这个目录不应该只放 dartdoc 自动生成的文档,因为它们可以自动生成。相反,应该放一些向导、教程类的文档。

example 目录
example 目录放示例程序,如果多个示例程序应该分别放在独立的子目录中。注意,示例代码应该使用 package: 的方式导入自己的包,就像其他人使用时一样。

tool 目录
tool 目录可以放一些内部工具。和 bin 目录不同,bin 目录放的是外部工具。


更多参考资料:
  评论这张
 
阅读(2430)| 评论(1)
推荐 转载

历史上的今天

评论

<#--最新日志,群博日志--> <#--推荐日志--> <#--引用记录--> <#--博主推荐--> <#--随机阅读--> <#--首页推荐--> <#--历史上的今天--> <#--被推荐日志--> <#--上一篇,下一篇--> <#-- 热度 --> <#-- 网易新闻广告 --> <#--右边模块结构--> <#--评论模块结构--> <#--引用模块结构--> <#--博主发起的投票-->
 
 
 
 
 
 
 
 
 
 
 
 
 
 

页脚

网易公司版权所有 ©1997-2018