封裝和發布 Rust 工具

如果您有信心讓其他人使用您的程式，那就是將它打包並發布的時候了！

有幾種方法，我們將從「設定最快」到「對使用者最方便」來看看其中的三種。

最快：cargo publish

發布您的應用程式最簡單的方法是使用 cargo。您還記得我們如何將外部依賴項新增到我們的專案嗎？Cargo 從它的預設「crate 註冊表」，crates.io，下載它們。使用 cargo publish，您也可以將 crate 發布到 crates.io。這適用於所有 crate，包括具有二進位目標的 crate。

將 crate 發布到 crates.io 非常簡單：如果您尚未擁有 crates.io 帳戶，請建立一個帳戶。目前，這是透過授權您使用 GitHub 來達成，因此您需要擁有 GitHub 帳戶（並登入）。接下來，使用 cargo 在您的本地電腦上登入。為此，請前往您的 crates.io 帳戶頁面，建立一個新的代幣，然後執行 cargo login <your-new-token>。每台電腦只需執行一次即可。您可以在 cargo 的發布指南中了解更多資訊。

在 cargo 和 crates.io 了解您之後，您已準備好發布箱子。在您匆忙繼續並發布新的箱子（版本）之前，建議您再次開啟您的 Cargo.toml 並確保已新增必要的元資料。您可以在 cargo 清單格式文件尋找可設定的所有可能的欄位。以下為一些常見條目的快速概觀

[package]
name = "grrs"
version = "0.1.0"
authors = ["Your Name <your@email.com>"]
license = "MIT OR Apache-2.0"
description = "A tool to search files"
readme = "README.md"
homepage = "https://github.com/you/grrs"
repository = "https://github.com/you/grrs"
keywords = ["cli", "search", "demo"]
categories = ["command-line-utilities"]

如何從 crates.io 安裝二進位檔

我們已了解如何發布箱子到 crates.io，您可能想知道如何安裝箱子。與函式庫相反，當您執行 cargo build（或類似命令）時，cargo 會下載並編譯函式庫，您需要告訴 cargo 明確安裝二進位檔。

這會使用 cargo install <crate-name> 完成。預設會下載箱子，編譯所有包含的二進位檔目標（在「發布」模式中，因此可能需要一段時間），並將它們複製至 ~/.cargo/bin/ 目錄中。（確保您的 shell 知道在哪裡尋找二進位檔！）

也可以從 git 儲存庫安裝箱子，僅安裝箱子的特定二進位檔，並指定安裝箱子的替代目錄。有關詳細資訊，請參閱 cargo install --help。

何時使用

cargo install 是安裝二進位檔箱子的簡單方法。Rust 開發人員使用它非常方便，但是有一些明顯的缺點：既然它會始終從頭編譯您的原始碼，則工具的使用者需要在其機器上安裝 Rust、cargo，以及您的專案要求的所有其他系統依賴項。編譯大型 Rust 程式庫代碼也可能需要一些時間。

最適合用於分配鎖定至其他 Rust 開發人員的工具。例如：許多 cargo 子命令（例如 cargo-tree 或 cargo-outdated）可以使用它安裝。

分配二進位檔

Rust 是一種編譯為原生程式碼的語言，預設是將所有相依性進行靜態連結。當你在專案中執行 `cargo build` 且專案包含一個名為 `grrs` 的二進位檔時，你最後會得到一個名為 `grrs` 的二進位檔案。試試看：使用 `cargo build`，它會是 `target/debug/grrs`，而當你執行 `cargo build --release` 時，它會是 `target/release/grrs`。除非你使用到明確需要在目標系統安裝外部函式庫的箱子（例如使用系統版本的 OpenSSL），否則此二進位檔案將只會相依於一般的系統函式庫。這表示你可以取用該檔案，傳送給和你執行相同作業系統的人，而他們將能夠執行它。

這已經非常強大了！它解決了我們剛看到 `cargo install` 的兩個缺點：使用者機器不需要安裝 Rust，而且他們可以立即執行二進位檔，而不是花費一分鐘編譯它。

因此，根據我們的觀察，`cargo build` 已經為我們建立二進位檔。唯一的問題是，並非保證這些二進位檔可以在所有平台運作。如果你在 Windows 機器上執行 `cargo build`，預設情況下你將無法取得可在 Mac 上執行的二進位檔。有沒有辦法自動為所有有趣的平台產生這些二進位檔？

在 CI 建置二進位發行版

如果你的工具是開源且託管在 GitHub，那麼設置一個免費的 CI (持續整合) 服務（例如 Travis CI）非常容易。（還有許多其他的服務也可以在其他平台運作，但 Travis 非常受歡迎。）這基本上會在你每次將變更推送到存放庫時在虛擬機器中執行設定指令。這些指令是什麼，以及它們執行於什麼類型的機器上，都是可以設定的。例如：一個好主意是在已安裝 Rust 和一些一般建置工具的機器上執行 `cargo test`。如果這樣做會失敗，代表最近的變更中存在問題。

我們也可以透過這個建置二進位檔並將它們上傳到 GitHub！實際上，如果我們執行 `cargo build --release` 並將二進位檔上傳到某處，我們就萬無一失了，對嗎？並不完全是。我們仍然需要確保我們建置的二進位檔與盡可能多的系統相容。例如，在 Linux 上，我們可以選擇不為目前的系統編譯，而針對 `x86_64-unknown-linux-musl` 目標來進行編譯，以避免依賴於預設的系統函式庫。在 macOS 上，我們可以將 `MACOSX_DEPLOYMENT_TARGET` 設定為 `10.7`，以僅依賴於第 10.7 版及更舊版本中存在於系統中的功能。

你可以看到 這裡 有使用這種手法建置二進位檔的範例，適用於 Linux 和 macOS，以及 這裡 有 Windows 的範例（使用 AppVeyor）。

使用一種預先建置的 (Docker) 映像，其中包含我們用來建置二進位檔案的所有工具，是另一種方式。這讓我們也可以輕鬆地鎖定較特殊的平台。trust 專案包含了腳本，你可以納入專案中，這些腳本會說明如何設定。它也包含支援使用 AppVeyor 的 Windows。

如果你比較喜歡在本地端設定，並在自己的電腦上產生發行檔案，還是可以看看 trust。它在內部會使用 cross，它的運作和 cargo 類似，但會將指令轉發給 Docker 容器中的 cargo 程序。這些映像的定義，也可以在 cross 的儲存庫 中找到。

如何安裝這些二進位檔案

你讓你的使用者瀏覽你的發行頁面，這個頁面可能是 類似這樣的頁面，他們可以在其中下載我們剛剛建立的成品。我們剛剛產生的發行成品，沒有什麼特別的：最後，它們只是包含二進位檔案的歸檔檔！這表示你工具的使用者，可以用他們的瀏覽器下載它們，然後解壓縮它們（通常會自動發生），並將二進位檔案複製到他們喜歡的地方。

這需要一些手動「安裝」程式的手動操作經驗，因此你可以在自述檔案中新增一個章節，說明如何安裝這個程式。

何時使用

發行二進位檔案通常是個好主意，幾乎沒有什麼缺點。它無法解決使用者必須手動安裝和更新你的工具的問題，但使用者無需安裝 Rust，就能快速取得最新版本的版本。

除了你的二進位檔案，還要打包什麼

目前，當使用者下載我們的發行版本時，他們會取得一個僅包含二進位檔案的 .tar.gz 檔案。所以，在我們的範例專案中，他們只會取得單一的 grrs 檔案，這是他們可以執行的檔案。但在我們的儲存庫中，已經有一些其他檔案，使用者可能會想要。例如，他們如何使用這個工具的自述檔案，以及授權檔案。既然我們已經準備好了這些檔案，新增它們會很容易。

有些更有趣的檔案，對於命令列工具來說特別有意義：除了自述檔案，我們還要發布手冊頁面，以及加入可能旗標完成的組態檔案到你的 shell 嗎？你可以手動編寫這些檔案，但是 clap，我們使用的引數剖析函式庫（clap 延伸自該函式庫），有一個方法可以為我們產生所有這些檔案。如需更詳盡的資訊，請參考 這篇深入探討的章節。

將你的應用程式放進套件儲存庫

到目前為止我們看到的方法，並非您通常在機器上安裝軟體的方式。尤其在大部分作業系統中透過全域套件管理員安裝命令列工具。使用者享有顯而易見的優點：無須思考如何安裝您的程式，如果可以與其他工具安裝方式相同，這些套件管理員也可讓使用者在有新版本時更新其程式。

遺憾的是，支援不同的系統意味著您必須留意這些不同系統的運作方式。對某些系統而言，這可能就像將檔案新增至您的儲存庫一樣容易（例如，為 macOS 的 brew 新增類似 此檔案 的 Formula 檔案），但對其他系統來說，您通常需要自行傳送補丁檔，並將您的工具新增至其儲存庫。有 cargo-bundle、cargo-deb 和 cargo-aur 等實用的工具，但如何運作和如何適當地封裝您的工具以適用於這些不同系統，已超出本章節範圍。

取而代之，讓我們來看看一個以 Rust 編寫且可在許多不同的套件管理員中取得的工具。

範例：ripgrep

ripgrep 是 grep/ack/ag 的替代方案，並以 Rust 編寫。它相當成功，並且已封裝許多作業系統：只要仔細閱讀其 README 中的 「Installation」區段 即可！

請注意，它會列出安裝其套件的幾個不同選項：它從指向 GitHub 釋出的連結開始，其中包含二進位檔程式，因此您可以直接下載它們；然後它會列出如何使用許多不同的套件管理員安裝其套件；最後，您也可以使用 cargo install 安裝其套件。

這似乎是一個非常好的想法：不要挑選或選擇此處提出的其中一種方法，而是從 cargo install 開始，加入二進位檔釋出，最後開始使用系統套件管理員配送您的工具。