Rust 學習之路─第十四章:Cargo和Crates.io


Cargo除了可以編譯、執行、測試程式專案之外,還可以針對程式專案進行程式建構(build)時的細節調整、將不同程式專案組合成相同的工作空間(Workspace),還能搭配Crates.io來使用,利用程式專案的相依關係快速取得Crates.io上的套件,或是反過來將我們開發完成的函式庫發佈到Crates.io上。

修改程式建構的方式

Cargo有兩種主要的程式建構模式,分別是執行「cargo build」指令的開發(dev)模式,和執行「cargo build --relese」指令用來正式發佈程式時使用的釋出(release)模式。在先前的章節中,我們知道加上「--relese」參數之後輸出的程式就會透過編譯器進行一些優化,並且移除掉開發階段時用來偵錯(debug)的功能和訊息,確保正式版本的程式能在最佳狀態下運作(高效能、小體積)。

透過在「Cargo.toml」設定檔中定義「profile.dev」或「profile.release」區塊的方式,我們可以覆寫掉開發模式或是釋出模式預設的程式建構參數。

舉例來說,影響著編譯時程式優化程度的設定項目為「opt-level」,設定值數值範圍在0~3之間(包含0和3),數值0表示不作優化,數值愈高表示優化程度愈高。0和1適合用在開發模式,2和3適合用在釋出模式。開發模式的優化程度預設值為0,釋出模式的優化程度預設值為3,如果要將開發模式的優化程度改為1,釋出模式的優化程度改為2,可以在「Cargo.toml」設定檔中添加以下內容:

發佈crate到Crates.io

將自己寫的函式庫開放原始碼Crates.io,提供給其它Rust開發者使用前,應先替函式庫準備好API文件,不然沒有人會用。Rust程式語言有提供文件註解,一般註解是以「//」開頭,而文件註解是以「///」開頭,支援Markdown語法。

舉例來說:

接著執行「cargo doc」指令,就可以替這個程式專案產生出網頁版文件了!網頁會儲存在「target」目錄的「doc」目錄下。

如果想要在網頁版文件產生出來之後直接用瀏覽器開啟,可以替「cargo doc」指令加上「--open」參數。產生出來的網頁如下:

rust-cargo

rust-cargo

「Examples」是我們透過Markdown語法的Heading 1所產生出來的區塊,區塊名稱可以自行隨便定義。而範例程式的部份使用Markdown的「`」語法,除了能在網頁中有程式碼高亮的效果之外,在使用「cargo test」指令測試程式專案的時候還可以測試文件註解內寫的範例程式。

rust-cargo

「Doc-tests」的部份就是寫在文件註解內的範例程式,如此一來就可以確認程式文件中的範例程式是否是正確的。

除了函數可以加上文件註解之外,整個crate也可以加上文件註解,但就不是使用「///」,而是「//!」。舉例來說:

如此一來,在文件的網頁中就會多出crate的說明。

rust-cargo

想要將自己製作的函式庫放到Crates.io上,必須先登入Crates.io,並且利用以下網址來產生API Token:

https://crates.io/me

假設產生出來的API Token為「txDj58akNnoIoJXqzzbW4VYOoh3vgrow」,執行以下指令,Cargo就可以藉由這組API Token來登入我們的Crates.io帳號。

cargo login txDj58akNnoIoJXqzzbW4VYOoh3vgrow

在函式庫發佈前,可以替其選擇一個適當的開放原始碼License來套用。可以參考這個網站:

https://spdx.org/licenses/

每個開放原始碼License都有其專屬的「Identifier」,選定好要用的License之後,在我們程式專案「Cargo.toml」設定檔中的「package」區塊,可以加上「license」設定項目,來指定這個專案要套用的License。舉例來說:

此外也可以加上「description」設定項目,來描述一下這個函式庫的作用。

確認目前的程式專案設定無誤,且可以通過測試之後,就可以使用以下指令來將我們的函式庫發佈或是更新到Crates.io上了!

cargo publish

工作空間

如果我們要開發的套件很龐大,可以將其分割成多個子套件,利用工作空間組合起來使用。工作空間由多個程式專案來組成,可以使這些程式專案共享同一個「Cargo.lock」檔案和輸出目錄。

建立一個工作空間的方式很簡單,只要建立出一個空目錄,並在這個空目錄中新增一個「Cargo.toml」設定檔,接著在設定檔內添加「workspace」區塊,將這個工作空間所包含的其它程式專案名稱設定至「members」項目中。

舉例來說,若我們的工作空間底下有「lib1」、「lib2」這兩個程式專案,則「Cargo.toml」設定檔的內容如下:

接著將程式專案加入至工作空間中,或是直接在工作空間中建立出新的程式專案。舉例來說,若我們的工作空間底下有「lib1」、「lib2」這兩個程式專案,則工作空間的檔案目錄結構如下:

工作空間目錄中的「target」目錄和「Cargo.lock」會在編譯整個工作空間時自動產生出來。

安裝Crates.io上的可執行程式

除了函式庫可以被發佈到Crates.io上之外,可執行的應用程式專案也是可以的。如果要直接將Crates.io上的應用程式專案安裝(下載然後編譯)到自己電腦上執行,可以使用「cargo install」指令。

舉例來說,如果要安裝「ripgrep」這個工具型的應用程式的話,指令如下:

cargo install ripgrep

rust-cargo

安裝的執行檔會放置在家目錄中的「.cargo/bin」目錄下,如果「PATH」環境變數有包含家目錄中的「.cargo/bin」目錄,就可以直接在終端機輸入執行檔名稱來執行程式。

rust-cargo

擴充Cargo的功能

使用以下指令,可以看到目前Cargo所支援的命令:

cargo --list

rust-cargo

如果要擴充Cargo能夠使用的命令,我們可以將執行檔命名成「cargo-something」,放置在家目錄中的「.cargo/bin」目錄下,「something」即為我們想要使用的命令名稱

舉例來說,我們將Hello World的執行檔命名為「cargo-hello」,並存放到家目錄中的「.cargo/bin」目錄下。之後只要輸入「cargo hello」指令就可以執行到「cargo-hello」這個檔案。

rust-cargo

由於「cargo install」指令會將Crates.io上的可執行程式專案所編譯出來的執行檔也安裝至家目錄中的「.cargo/bin」目錄下,所以在Crates.io上以「cargo-」前綴來命名的可執行程式專案都可以直接透過「cargo install」指令,在安裝之後擴充Cargo的功能。

總結

Cargo是個很方便的Rust程式專案管理工具,除了可以用來產生、編譯、執行、測試、管理程式專案,還可以幫助我們下載Crates.io上的套件到我們的程式專案中,或是直接安裝至作業系統環境。如果我們想要分享自己的程式專案至Crates.io,也可以使用Cargo來快速發佈。

下一章節,我們將會學習指標的進階用法。

關於作者

Magic Len

Magic Len

各位好,我是Magic Len,是這網站的管理員。我是台灣台中大肚山上人,畢業於台中高工資訊科和台灣科技大學資訊工程系,曾在桃機航警局服役。我熱愛自然也熱愛科學,喜歡和別人分享自己的知識與經驗。如果你有興趣認識我,可以加我的Facebook,並且請註明是從MagicLen來的。

相關文章