利用 Cargo 发布 Rust 依赖库介绍

Rust 是 Apache 基金会开的一个新坑, 简单说就是一个函数式编程的现代语言. 速度期望是和 c++ 差不多.

一个语言的实用与否, 不仅仅需要考虑语言本身(当然, 一个写起来爽的语言比一个语法糟糕的语言可能要好一千倍, 但这并不是唯一判断条件), 一些好的工具链, 社区环境等都可以让语言本身更加充满希望--或者失望.

rust 使用的是 Cargo 作为编译环境. 这是你安装好 rust 后的默认选项.

很多时候, 许多代码可以被复用, 一个好的工程组织会给人带来许多方便. 目前看来, Cargo 就是一个非常不错的工具(当然, 有些时候还是有些让人不尽如人意的)

Cargo 之于 rust, 大致相当于 cmake + make 之于 c. 我们可以在工程根目录下准备一个 Cargo.toml 文件, 里面可以写上我们想要的配置信息. 然后利用 Cargo 工具可以自动下载依赖, 编译. 此外, 我们还可以利用它发布我们的依赖等等. 总之, 这是一个包办了许多事情的一个集成工具.

本文的主旨是介绍一下库的写法, 依赖的发布和使用.

首先我们要准备一个库

里面目录结构大致如下:

$ tree
.
├── Cargo.toml
├── LICENSE
├── README.md
├── src
│   ├── lib.rs
│   └── utils
│       └── mod.rs
└── test
    └── test.rs

我们在 lib.rs 中内容为:

#![crate_name = "r"]
#![deny(warnings)]
#[allow(dead_code)]

pub mod utils;

意思很简单, 前几行是声明, 因为库文件嘛, 总可能放出方法但并没有使用, 因此用 allow(dead_code) 来除掉这个warning. 然后把 utils 这个 package 放出来.

在 utils 下有个 mod.rs, 内容是一个 hello world

pub fn it_works() {
    println!("it works! a voice comes from r::utils::it_works")
}

注意, 我 mod 和想要放出的 function it_works 都被标注了 pub, 中间有个不是 pub, 就无法找到了.

然后在根目录下写上配置. 最基本的配置为:

[package]
name = "r"
version = "0.0.1"
authors = ["Yu Jing <yu@argcv.com>"]

然后就可以

cargo build

编译通过, 一个 toy lib 就做出来了.

然后我们可以选择各种方式的调用, 包括

• 本地引用
• github 引用
• crates 公共库上引用

本地引用自不用多说, 文件存着即可. github 引用, 需要把工程 push 到 github. crates 公共库引用, 则需要在 crates 注册一个账号, 获取 token 后才能发布.

前两个不需要特别的手段,只有 crates 需要注意下. 首先,我们需要去 crates 创建一个账号--其实可以通过 github 连接即可,非常简单. 然后在 https://crates.io/me 这个 URL 下, 我们可以看到一个属于这个账号的 api-key.

本地执行

cargo login your_api_key

即可.

其实从本质上说, 就是在 ~/.cargo/config 中修改写了行 token 而已.

[registry]
token = "your_api_key"

然后模仿这个页面编辑 Cargo.toml, 然后执行命令

cargo publish

即可.

需要说明的是, crates 不支持删除和修改, 你 push 上去一个后, 那个 repo 就永久留在线上了, 你不能用同一个版本号再 push 一遍来覆盖它. 你只能用 yank 命令, 让它不再能被下载

cargo yank --vers 0.0.1
cargo yank --vers 0.0.1 --undo

因此请小心操作.

接下来, 我们需要做个工程来调用它.

这个工程是一个简单的例子.内容如下:

$ tree
.
├── Cargo.lock
├── Cargo.toml
├── LICENSE
└── src
    └── main.rs

调用非常简单

extern crate r;

use r::utils::it_works;

fn main() {
    it_works();
}

声明使用外部依赖, 声称使用依赖, 调用. 没啥啰嗦的.

配置也很简单. 除了都有的 package 外, 需要增加一个 dependencies.

.toml 是一个 .ini 和 .json 的混合体, 它在写法上给了我们很大的自由度.

我们需要依赖外部 lib r.

如果我们依赖的是本地文件.那么我们需要参数 "path"

[dependencies]
r = {path="../r"}

path 可以是相对路径,也可以是绝对路径.

我们也可以写成这样:

[dependencies.r]
path="../r"

一个意思.

若我们依赖的是 git, 那么我们至少需要一个 .git, 也可以选填一个 sha1. github 尾部的 .git 是可以选填的.

[dependencies.r]
git = "https://github.com/yuikns/r"

[dependencies]
r = { git = "https://github.com/yuikns/r.git", rev = "0dc4ef" }

上述两种写法都是可以的.

若我们发布到了 crates, 事情会变得更加简单

[dependencies]
r="0.0.1"

只要有个版本号即可.