Cargo使用文檔-指定依賴項


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

你的crates可以依賴於其他的庫:

1.crates.io

2.git庫

3.本地文件系統的子目錄

也可以臨時覆蓋依賴項的位置-比如說,這樣就能夠測試你的工作內容的依賴項的BUG修復。你可以對不同的平台有不同的依賴項,以及只在開發期間使用的依賴項。

一、從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)

二、從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" }

三、指定依賴路徑

隨時間的推移, 我們的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]在本地測試過,並且提交了一個請求。讓我們看看在它實際發布之前,如何繼續使用並測試它。

(未完待續...)


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM