Cargo 依賴指定

依賴指定

您的箱子，可以依賴多個來源的庫，如crates.io，git的存儲庫或本地文件系統(tǒng)上的子目錄。您還可以臨時覆蓋依賴項的位置 - 例如， 便于能夠測試您在本地工作的依賴項中的錯誤修復。您可以為不同的平臺，和或僅在開發(fā)期間使用不同的依賴項。我們來看看如何做到這些.

指定依賴，來自 crates.io

默認情況下，Cargo 是準備好，在crates.io上查找依賴項。在這種情況下，只需要名稱和版本字符串。在Cargo 指南，我們選擇了一個依賴項-time箱:

[dependencies]
time = "0.1.12"

字符串"0.1.12"是一個semver版本格式字符串。由于此字符串中沒有任何運算符，因此它的解釋方式與我們指定的"^0.1.12"方式相同，而^被稱為跳脫條件.

Caret requirements(跳脫條件)

跳脫條件: 允許 SemVer 兼容更新指定版本。新的版本允許更新的條件是，不修改最左邊的非零數(shù)字(無論major，minor，patch)。在這種情況下，如果我們執(zhí)行了cargo update -p time，Cargo 應該更新我們的0.1.13版本(如果是最新的0.1.z發(fā)布)，但不會更新為0.2.0。相反，我們若將版本字符串指定為^1.0，Cargo 應更新至1.1，如果是最新的1.y發(fā)布，但不是2.0版本。0.0.x并不與任何其他版本兼容.

以下是一些跳脫條件的例子以及它們允許的版本:

^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.2 := >= 0.2.0 < 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

此兼容性約定與 SemVer ，在處理 1.0.0 之前的版本方面有所不同。雖然 SemVer 說在 1.0.0 之前沒有兼容性，但 Cargo 認為0.x.y是兼容0.x.z，這里y ≥ z和x > 0.

Tilde 條件

Tilde 條件指定具有更新最小版本的一定能力。如果指定 major 版本，minor 版本和 patch 程序版本，或僅指定 major 版本和 minor 版本，則僅允許 patch 程序級別更改。如果僅指定 major 版本，則允許進行 minor 和 patch 級別更改.

~1.2.3是 Tilde 條件的一個例子.

~1.2.3 := >=1.2.3 <1.3.0
~1.2 := >=1.2.0 <1.3.0
~1 := >=1.0.0 <2.0.0

通配符要求

通配符條件允許任何通配符所在的版本.

*，1.*和1.2.*是通配符條件的示例.

* := >=0.0.0
1.* := >=1.0.0 <2.0.0
1.2.* := >=1.2.0 <1.3.0

Inequality requirements(范圍條件)

范圍條件允許手動指定要依賴的版本范圍或確切版本.

以下是范圍條件的一些示例:

>= 1.2.0
> 1
< 2
= 1.2.3

多版本條件

多個版本，要求用逗號分隔，例如>= 1.2， < 1.5.

依賴指定，來自 git 存儲庫

依賴于位于git存儲庫的庫，您需要指定的最小信息，為一個git字段，其是存儲庫的github位置:

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

Cargo 將取得git，然后在這個位置找到一個存儲庫的請求箱子的Cargo.toml。方式是對git存儲庫里面的任何地方(不一定在根目錄) - 例如，指定工作區(qū)中的成員包名稱，和設置git到包含工作區(qū)的存儲庫).

由于我們尚未指定任何其他信息，因此 Cargo 假定我們打算使用最新的提交master分支，來構建我們的包。你可以將git字段和rev，tag， 還有branch，這些用于指定其他內容的字段組合起來。這是一個指定您希望在名為next分支上，使用最新提交的示例:

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

路徑，依賴指定

隨著時間的推移，我們來自指南的hello_world示例已大幅增長! 它已經(jīng)到了我們可能想分出一個單獨的箱子供其他人使用的地步。為此，Cargo 支持路徑依賴通常是位于一個存儲庫中的子箱。讓我們開始在hello_world包的內部制作一個新的箱子:

# inside of hello_world/
$ cargo new hello_utils

這將創(chuàng)建一個新文件夾hello_utils，里面有一個Cargo.toml和src文件夾已準備好進行配置。為了告訴 Cargo，請打開hello_world/Cargo.toml，并添加你的hello_utils依賴:

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

這告訴 Cargo 我們依賴于一個叫做hello_utils的箱子，這能在hello_utils文件夾找到(相對于，寫在Cargo.toml路徑).

就是這樣! 下一步cargo build將自動構建hello_utils，以及它自己的所有依賴項，其他人也可以開始使用它。但是，crates.io不允許僅使用 路徑指定依賴項 的包。如果我們想發(fā)布我們的hello_world箱子，我們需要發(fā)布一個版本hello_utils至crates.io，并在依賴項行中指定其版本:

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

依賴覆蓋

Cargo 中有許多方法支持，覆蓋依賴關系以及控制依賴關系圖。但是，這些選項通常僅在工作區(qū)級別可用，并且不通過依賴項傳播。換句話說，"應用程序"具有覆蓋依賴關系的能力，但"庫"卻沒有。

許多場景，會產(chǎn)生想，覆蓋依賴性或以其他方式改變某些依賴關系的愿望。然而，他們中的大多數(shù)都可以歸結為，將箱子發(fā)布到 crates.io 之前使用箱子(覆蓋依賴)的能力。例如:

• 您編寫的 crate ，也用于您編寫的更大應用程序中，并且您希望測試在更大應用程序內，crate的錯誤修復情況。
• 不是你編寫的上游包，現(xiàn)在其 git 存儲庫的主分支上，有一個新功能或錯誤修復，您要測試它。
• 您即將發(fā)布新版本的 major 版本，但您希望在整個軟件包中進行集成測試，以確保新的主要版本能夠正常運行.
• 您已經(jīng)為上游的軟件包提交了一個針對您找到的錯誤的修復程序，但是您希望立即讓您的應用程序依賴，此程序包的固定修復版本，以避免錯誤修復程序被拒絕合并.

這些場景目前都是通過[patch] 清單部分 解決的，從歷史上看，其中一些方案是該[replace]部分解決的，但我們在這里會記錄[patch]解決的部分。

測試一個錯誤修復

假設你正在使用uuid crate，但是當你正在研究它時，你會發(fā)現(xiàn)一個錯誤.但是，你很有進取心，所以你決定嘗試修復這個 bug! 最初你的清單看起來像:

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

我們要做的第一件事是克隆uuid存儲庫，到本地:

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

接下來我們將編輯my-library-Cargo.toml，為:

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

在這里，我們宣布我們是*修補(patch)*來源crates-io，其有一個新的依賴，這將有效地添加本地(簽出 checkout)版本uuid到 crates.io 注冊表，指向本地包。

接下來我們需要確保我們的鎖(lock)文件已更新為，使用此新版本uuid，所以我們的包使用本地簽出的副本，而不是 crates.io 中的副本。[patch]工作方式是它將從../path/to/uuid加載依賴，然后每當 crates.io 查詢uuid的版本時，它也會返回本地版本.

這意味著本地簽出的版本號很重要，會影響是否使用該補丁。我們的清單宣布uuid = "1.0"，這意味著我們只會解析>= 1.0.0， < 2.0.0，和 Cargo 的貪婪解析算法，也意味著我們將解析到該范圍內的最大版本。通常情況下這并不重要，因為 git 存儲庫的版本已經(jīng)更大，或與 crates.io 上發(fā)布的最大版本相匹配，但重要的是要記住這一點!

無論如何，通常您現(xiàn)在需要做的就是:

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

就是這樣! 您現(xiàn)在正在使用本地版本uuid構建(注意構建輸出中括號中的路徑)。如果您沒有看到構建本地路徑版本，那么您可能需要運行cargo update -p uuid --precise $version，這里$version是本地簽出版本的uuid副本。

一旦你修復了你最初發(fā)現(xiàn)的錯誤，你要做的下一件事就是將其作為拉取請求提交給uuid箱子本身。一旦你完成了這個，你也可以更新下[patch]部分。[patch]里面的內容列表就像是[dependencies]部分，所以一旦你的拉動請求合并，你就可以改變你的path依賴:

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

Working with an unpublished minor version

與 一個未發(fā)布的次要版本，一起工作

現(xiàn)在讓我們稍微改變一下，從錯誤修復，變成要添加功能。在努力my-library的同時，你發(fā)現(xiàn)需要uuid箱的一個全新的功能。而您已實現(xiàn)uuid此功能，并在[patch]上面進行本地測試，并提交了拉取請求。讓我們來看看在實際發(fā)布之前，你如何繼續(xù)使用和測試它。

我們也說當前版本的uuid，在 crates.io 上是1.0.0版本，但從提交那時起，git 存儲庫的主分支已更新為1.0.1。此分支包含您之前提交的新功能。要使用此存儲庫，我們將編輯我們的Cargo.toml，看起來像

[package]
name = "my-library"
version = "0.1.0"
authors = ["..."]
[dependencies]
uuid = "1.0.1"
[patch.crates-io]
uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }

注意我們對本地uuid的依賴已更新為1.0.1，因為這是我們在箱子發(fā)布后實際需要的東西。但是，這個版本在 crates.io 上不存在，所以我們提供給它清單的[patch]部分.

現(xiàn)在，當我們的庫被構建時，它將uuid從 git 存儲庫取出，并解析到存儲庫中的 1.0.1 ，而不是嘗試從 crates.io 下載版本。一旦 1.0.1 發(fā)布在 crates.io 上，那[patch]部分就可以刪除了。

值得注意的是，[patch]是連帶關系。假設您在更大的包中使用my-library，例如:

[package]
name = "my-binary"
version = "0.1.0"
authors = ["..."]
[dependencies]
my-library = { git = 'https://example.com/git/my-library' }
uuid = "1.0"
[patch.crates-io]
uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }

記住這[patch]是連帶關系，但只能在頂層，所以我們的my-library消費者不得不重寫[patch]部分(如有必要的話)。不過，在這里，新的uuid箱子會適用對uuid的依賴和my-library -> uuid的依賴，兩個依賴都指定了。該uuid箱 將被解析為整個 crate 關系圖 的 1.0.1 版本，并且它是將從 git 存儲庫中提取。

Overriding repository URL

覆蓋 注冊表 URL

如果要覆蓋的依賴項不是加載自crates.io，你將不得不改變一下你的[patch]使用方式:

[patch."https://github.com/your/repository"]
my-library = { path = "../my-library/path" }

就是這樣!

Prepublishing a breaking change

預發(fā)布一個重要變化

讓我們來看看最后一個場景。若要使用一個新的主要版本的箱子，其通常伴隨著重大變化。而要堅持使用我們以前的箱，這意味著我們將創(chuàng)建 2.0.0 版本uuid箱。在我們提交了所有上游更改后，我們可以更新我們的my-library清單，看起來像:

[dependencies]
uuid = "2.0"
[patch.crates-io]
uuid = { git = "https://github.com/rust-lang-nursery/uuid", branch = "2.0.0" }

就是這樣!與前面的示例一樣，2.0.0 版本實際上，并不存在于 crates.io 上，但我們仍然可以通過[patch]部分使用。作為一個思考練習，讓我們再看看my-binary(被使用)的再次表現(xiàn):

[package]
name = "my-binary"
version = "0.1.0"
authors = ["..."]
[dependencies]
my-library = { git = 'https://example.com/git/my-library' }
uuid = "1.0"
[patch.crates-io]
uuid = { git = 'https://github.com/rust-lang-nursery/uuid', branch = '2.0.0' }

請注意，這實際上將解析為兩個版本的uuid箱。該my-binary箱子將繼續(xù)使用 1.x.y 系列的uuid箱子，但是my-library箱 會使用 2.0.0 版本uuid。這將允許您通過依賴關系圖逐步推出對包的更改，而無需一次性更新所有內容。

Overriding with local dependencies

覆蓋 本地依賴項

有時你只是暫時在一個箱子上工作，而你不想修改Cargo.toml中像上訴的[patch]部分。對于這個用例，Cargo 提供了更為有限的覆蓋版本路徑覆蓋.

路徑覆蓋是通過.cargo/config指定，而不是Cargo.toml，你可以尋找有關此配置的更多文檔。在.cargo/config內，你要指定的是一個名為paths字段:

paths = ["/path/to/uuid"]

該數(shù)組應填充包含Cargo.toml的目錄。在這種情況下，我們只是添加uuid，所以它將是唯一一個被覆蓋的。此路徑可以是包含該路徑的絕對路徑或相對.cargo文件夾的路徑.

路徑覆蓋，比[patch]部分的限制更嚴格，但是，路徑覆蓋不能改變依賴圖的結構。而當使用路徑替換時，前一組依賴項必須完全匹配新的Cargo.toml規(guī)格。如此，就意味著路徑覆蓋不能用于向箱添加依賴項的測試，而換成[patch]在該種情況下使用。因此，路徑覆蓋的使用，通常會與快速錯誤修復分隔開來，而不是大更新分開。

注意:使用本地配置覆蓋路徑，僅適用于已發(fā)布到crates.io的包。您無法使用此功能告訴 Cargo 如何查找本地未發(fā)布的箱。

Platform specific dependencies

平臺決定依賴

特定于平臺的依賴項采用相同的格式，但在target下列出。像正常 Rust 一樣的#[cfg]語法，將用于定義這些部分:

[target.'cfg(windows)'.dependencies]
winhttp = "0.4.0"
[target.'cfg(unix)'.dependencies]
openssl = "1.0.1"
[target.'cfg(target_arch = "x86")'.dependencies]
native = { path = "native/i686" }
[target.'cfg(target_arch = "x86_64")'.dependencies]
native = { path = "native/x86_64" }

與 Rust 一樣，這里的語法支持not，any，和all運算符組合各種 cfg 名稱/值對。請注意cfg語法僅在 Cargo 0.9.0(Rust 1.8.0)之后可用.

除了#[cfg]語法，Cargo 還支持列出依賴關系適用的完整目標:

[target.x86_64-pc-windows-gnu.dependencies]
winhttp = "0.4.0"
[target.i686-unknown-linux-gnu.dependencies]
openssl = "1.0.1"

如果您使用的是自定義目標規(guī)范，請引用完整路徑和文件名:

[target."x86_64/windows.json".dependencies]
winhttp = "0.4.0"
[target."i686/linux.json".dependencies]
openssl = "1.0.1"
native = { path = "native/i686" }
[target."x86_64/linux.json".dependencies]
openssl = "1.0.1"
native = { path = "native/x86_64" }

Development dependencies

開發(fā)(Dev)依賴項

你可以添加一個[dev-dependencies]表格到Cargo.toml，其格式相當于[dependencies]:

[dev-dependencies]
tempdir = "0.3"

編譯用于構建的包時，不會使用 Dev 依賴，但用于編譯測試，示例和基準。

這些依賴關系是不會傳播到依賴于此包的其他包.

您還可以讓dev-dependencies具有特定目標的開發(fā)依賴項，而不是dependencies標題。例如:

[target.'cfg(unix)'.dev-dependencies]
mio = "0.0.1"

Build dependencies

構建 依賴項

您可以在構建腳本中使用，依賴其他基于 Cargo 的箱。依賴關系是由清單的build-dependencies部分定義:

[build-dependencies]
cc = "1.0.3"

構建腳本并不是有權訪問中 dependencies要么dev-dependencies部分列出的依賴項。除非也在dependencies部分下面列出，否則構建依賴項同樣不可用于包本身。包本身及其構建腳本是分開構建的，因此它們的依賴關系不重合。通過將獨立依賴用于獨立目的，使 Cargo 更簡單，更清潔。

Choosing features

選擇 特性

如果您依賴的包提供條件特性，您可以指定使用哪個:

[dependencies.awesome]
version = "1.3.5"
default-features = false # 不會包括默認特性， 和 任君選
                        # 單特性
features = ["secure-password", "civet"]

有關 features 的更多信息，請參閱清單文檔.

Renaming dependencies in Cargo.toml

在Cargo.toml中的重命名依賴項

寫Cargo.toml的[dependencies]部分的時候，您為依賴項編寫的字段通常與您在代碼中導入的包的名稱相匹配。但是，對于某些項目，您可能希望在代碼中引用具有不同名稱的包，而不管它是如何在 crates.io 上發(fā)布的。例如，您可能希望:

• 避免在 Rust 代碼常用use foo as bar.
• 依賴箱子的多個版本.
• 依賴來自不同注冊表管理機構的同名箱.

為了支持這個 ，Cargo 在[dependencies]部分使用 一個package字段，決定應該依賴哪個包:

[package]
name = "mypackage"
version = "0.0.1"

[dependencies]
foo = "0.1"
bar = { git = "https://github.com/example/project", package = "foo" }
baz = { version = "0.1", registry = "custom", package = "foo" }

在此示例中，Rust 代碼中現(xiàn)在提供了三個包:

extern crate foo; // crates.io
extern crate bar; // git repository
extern crate baz; // registry `custom`

所有這三個箱的包名稱在他們自己Cargo.toml，都是foo，所以我們明確地告知 Cargo ，使用的是我們想要的package字段(如 package = "foo"包名，即我們在本地調用其他東西)。如果沒有指定package，則默認為所請求的依賴項的名稱。

請注意，如果您有一個可選的(optional)依賴項，例如:

[dependencies]
foo = { version = "0.1", package = 'bar', optional = true }

你依賴于一個bar箱子，其來自 crates.io，但你箱子有一個foo特性，取代了一個bar特性。也就是說，在重命名時，特性的名稱拿掉了依賴項的名稱，而不是包名稱。

啟用傳遞依賴項的工作方式類似，例如我們可以將以下內容，添加到上面的清單中:

[features]
log-debug = ['foo/log-debug'] # 使用 'bar/log-debug' 就會出現(xiàn)一個錯誤!