Cargo使用文档-指定依赖项

原文连接：http://doc.crates.io/specifying-dependencies.html#platform-specific-dependencies

你的crates能够依赖于其余的库：

1.crates.io

2.git库

3.本地文件系统的子目录

也能够临时覆盖依赖项的位置-好比说，这样就可以测试你的工做内容的依赖项的BUG修复。你能够对不一样的平台有不一样的依赖项，以及只在开发期间使用的依赖项。

1、从crates.io指定依赖项

Cargo被设计为默认会从crates.io上搜寻依赖项。在这种方式下，只须要指定一个库名称和版本号，好比：

[dependencies]
time = "0.1.12"

字符串"0.1.12"要求是语义化标准版本(SemVer)，由于这种字符串没有运算符，

^符号(Caret requirements)

^符号容许以SemVer兼容方式升级到指定版本。只要新的版本号主要，次要，补丁组中最左边非零数字不被修改，这个升级就是被容许的，在这种状况下，若是咱们运行

cargo update -p time

若是这个版本可用的话，cargo将会帮咱们把time库升级到0.1.13，而毫不会升级到0.2.0，若是咱们以^1.0方式指定版本，将会升级到1.1版本可是不会升级到2.0.0.0.x。

~符号(Tilde requirements)

~指定了一个能够更新的最小版本。好比，若是你指定了一个主.次.补丁版本或者主.次版本，那么只能容许补丁级别的版本更改。若是只指定了主版本，那么能够容许次版本和补丁版本的升级。

eg:

~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)

*容许它所在位置的任意版本的升级

eg:

*            <=>    [0.0.0, ..)
1.*         <=>    [1.0.0, 2.0.0)
1.2.*      <=>    [1.2.0, 1.3.0)

>、<符号(Inequality)

2、从git仓库指定依赖

为了使用一个在git仓库上的库，你须要提供的最小信息是用git关键字指定的仓库地址

[dependencies]
rand = { git = "https://github.com/rust-lang-nursery/rand" }

Cargo将从这个位置去适配git仓库，而后到git仓库任意位置(不必定须要在git仓库的根目录下)中查找Cargo.toml文件，从中查找到全部须要的crates。

由于咱们没有指定任何其余的信息，Cargo会假定咱们使用的是master分支的最近一次提交的内容，来构建咱们的工程。咱们能够把git关键字与rev，tag，或者branch关键字结合来指定其余信息。下面是一个指定使用next分支上最近内容的例子：

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

3、指定依赖路径

随时间的推移， 咱们的hello_world工程的规模已经大大的增长，已经到了咱们该分割成一个单独的crate来提供给他人使用的时候了。Cargo容许经过指定依赖路径来作到这一点，一般是在一个库内的子crates，让咱们从在hello_world工程中建立一个新的crate开始：

$ cd hello_world/
$ cargo new hello_utils

以上将建立一个新的hello_utils目录(它的cargo.toml和src文件夹已经配置好)，为了告诉Cargo这些，打开hello_world/Cargo.toml文件，将hello_utils添加到你的依赖中:

[dependencies]
hello_utils = { path = "hello_utils" }

这将告诉Cargo咱们的hello_world工程依赖一个叫hello_utils的crate，这个crate能够在hello_utils目录下找到(依据咱们在Cargo.toml中写入的内容)。

这就是全部咱们要作的，下次执行cargo build命令的时候，将会自动构建hello_utils和它全部的依赖项，并且其余工程也能够开始使用这个crate了。然而，在crates.io中，不容许使用仅指定路径的依赖项。若是咱们想要发布咱们的hello_world crate，咱们须要先发布一个hello_utils的版本到crates.io上(或者指定一个git仓库位置)，而且也要在依赖行中指定它的版本：

[dependencies]
hello_utils = { path = "hello_utils", version = "0.1.0" }

 

覆盖依赖项(Overriding dependencies)

在Cargo中有多种方式来支持覆盖依赖项，并控制依赖图。不过，这些选项一般只能在工做空间级别适用，而且不能经过依赖关系传播。换句话说，"应用程序"能够覆盖依赖项，而"库"不行。

在不少场景中，都有要覆盖依赖项，或者以其余方式改变依赖项的须要。然而，他们中的大多数都归结于在被发表到crates.io以前，有能力使用crate。例如：

• 一个你正在开发中的crate也被一个你在开发中的更大的应用程序所使用，而且你将要在那个更大的应用中测试一个在crate中的BUG。
• 一个上游crate有一个新特性，或者在其git存储库的主分支上要修复BUG，你但愿测试它。
• 你将要为你的crate发布一个新的主版本，可是你但愿在整个项目中进行集成测试，以确保新的主要版本可以工做。
• 你已经为一个上游crate中发现的BUG提交啦一个修复程序，可是你想要马上在你的应用程序中依赖这个已经修复BUG的版本，以免被已经合并的BUG给阻塞(影响)。

这些目前都是经过[patch] manifest部分解决的。要注意的是，[patch]特征目前尚未稳定并且将要在2017-08-31发布。在Rust历史里，有些应用场景已经经过[replace]部分解决了，可是咱们将在这里记录[patch]部分。

测试一个BUG修复(Testing a bugfix)

假设你正在使用[uuid] crate，可是在你使用的时候，发现了一个BUG。你是至关有进取心的，因此你决定也试着取修复这个BUG，最初你的配置中会这样写：

[package]
name = "my-library"
version = "0.1.0"
authors = ["..."]

[dependencies]
uuid = "0.1.0"

咱们首先会克隆uuid仓库到本地，经过一下命令:

$ git clone https://github.com/rust-lang-nursery/uuid

而后，咱们编辑my-library的配置文件:

[patch.crates-io]
uuid = { path = "../path/to/uuid" }

这里咱们声明咱们正在修补源crates.io的一个新的依赖项。这将为咱们的本地工程有效的将uuid的的本地检出版本添加到crates.io注册表。

而后，咱们须要确信咱们的锁文件(Cargo.lock)被更新到可使用uuid的这个新版本，这样咱们的工程会使用位于本地的检出版本，而不是一个crates.io上的版本。

[patch]的工做方式是它将加载位于../path/to/uuid的依赖项而且当crates.io？？？？。

这意味着本地检出的版本很重要，而且会影响补丁是否会被使用。咱们的配置里声明uuid = "1.0"，这意味着咱们只会使用>=1.0.0，<2.0.0版本，而且Cargo的贪心算法也意外着咱们将解析到该范围内的最大版本。一般状况下，这并不重要，由于git仓库的版本将会更大，或者匹配发布到crates.io上的最大版本，可是记住这一点很重要。

在任何状况下，一般全部你须要作的是：

$ cargo build
   Compiling uuid v1.0.0 (file://.../uuid)
   Compiling my-library v0.1.0 (file://.../my-library)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

就是这样，如今，你在使用uuid的本地版本构建工程(留意在此次构建输出下的这个file://)。若是你没有看到file://的版本正在构建，那么你可能须要运行: cargo update -p uuid --precise $version，这里$version是本地检出的uuid拷贝的版本。

一旦你修复了BUG，你会发现下一件你要作的事情极可能是将其提交给uuid crate。一旦你作完这些你就能够更新[patch]部分。[patch]列下的部分相似[dependencies]部分，所以一旦你的提交请求被合并，你能够改变你的依赖路径为：

[patch.crates-io]
uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }

处理一个未发布的小版本(Working with an unpublished minor version)

如今，让咱们从处理BUG修复到添加功能。在开发my-library的时候，你发如今uuid crate中须要一个全新的特性。你已经实现了这个特性，使用[patch]在本地测试过，而且提交了一个请求。让咱们看看在它实际发布以前，如何继续使用并测试它。

（未完待续...）