Rust语言(3):引用依赖库

crate.io是Rust社区的中心package仓库,该仓库有各种不同功能的Rust软件库。

(过年喽,年前最后一篇了,还有很多坑没填。2017,Year of Rooster,加油,fighting!)

Introduction

crate.io是Rust社区的中心package仓库,cargo用来管理package,下载、版本管理、编译、运行依赖的packages。
crate本身是木箱的意思,而cargo货运的意思,cargo承载着各种货物,其中有一些是封装好的木箱。这个比喻倒也贴切。

add package

packages from crate.io

使用Rust(当前版本1.14.0)过程中,如果需要使用一些非核心库(Rust的核心库功能有限,使用到其他的库是大概率事件),则需要在Cargo.toml文件添加依赖的package。这些package可以是来自crate.io,或者git仓库,或者本地路径。

以下是一个从 crate.io 引用 crate 的例子,两个步骤:

  1. 在 Cargo.toml 文件中增加dependencies的package名字以及版本。

    Cargo.toml
    1
    2
    [dependencies]
    webbrowser = "0.2.2"
  2. 在rust源文件中引入 crate。

    Rust import external crate
    1
    extern crate webbrowser;

packages from git repository

dependencies from git repository
1
2
[dependencies]
rand = { git = "https://github.com/rust-lang-nursery/rand", branch = "next" }

如果不加branch="next",则默认获取最新的commit,当然可以用revtagbranch来指定不同的版本。

packages from local path

dependencies from local directory
1
2
[dependencies]
my_crate_name = { path = "../my-crate-directory", version = "0.1.0" }

如果不加version="0.1.0",则不会进行版本检查。

package version

Semver

版本号0.2.2有讲究,这是符合语义化版本控制(Semantic Versioning)格式,这种格式制定了严格的版本号更新要求,严格遵守可以防止dependency hell(依赖地狱)问题。

Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Caret requirements

版本号还可以有另外一种crate格式,这种格式^x.y.z允许升级到与要求版本号兼容的最新版本上。

Crate format
1
2
3
4
5
6
7
^1.2.3 := >=1.2.3 <2.0.0
^1.2 := >=1.2.0 <2.0.0
^1 := >=1.0.0 <2.0.0
^0.2.3 := >=0.2.3 <0.3.0
^0.0.3 := >=0.0.3 <0.0.4
^0.0 := >=0.0.0 <0.1.0
^0 := >=0.0.0 <1.0.0

Tilde requirements

版本号还支持另一种Tilde格式,这种格式~x.y.z指定了最低版本号要求。

Tilde format
1
2
3
~1.2.3 := >=1.2.3 <1.3.0
~1.2 := >=1.2.0 <1.3.0
~1 := >=1.0.0 <2.0.0

Wildcard requirements

版本号支持通配符。

ver wildcard
1
2
3
* := >=0.0.0
1.* := >=1.0.0 <2.0.0
1.2.* := >=1.2.0 <1.3.0

build a project with dependencies

我做的一个例子take a break,实现了每隔一段时间打开默认浏览器播放音乐功能,其中需要用到webbrowser库。

cargo build a project with depedencies
1
2
3
4
5
6
7
>cargo build
Updating registry `https://github.com/rust-lang/crates.io-index`
Downloading webbrowser v0.2.2
Compiling webbrowser v0.2.2
Compiling take_a_break v0.1.0 (file:///Users/alta/github/Rust/04_take_a_break)
Finished debug [unoptimized + debuginfo] target(s) in 0.66 secs

update a project with dependencies

1
2
>cargo update
Updating registry `https://github.com/rust-lang/crates.io-index`

Reference:

  1. Cargo Guide
  2. Rust semver
  3. semver
  4. take a break