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]在本地測試過，而且提交了一個請求。讓咱們看看在它實際發佈以前，如何繼續使用並測試它。

（未完待續...）