Cargo 在crates.io上發(fā)布

發(fā)布到 crates.io

一旦你有一個(gè)你想與世界分享的 crate，就該把它發(fā)布到crates.io! 發(fā)布是指，上載特定版本的，以讓crates.io進(jìn)行托管.

發(fā)布箱(crate)子時(shí)，要小心，因?yàn)榘l(fā)布是常駐。永遠(yuǎn)不能覆蓋同版本，并且無法刪除代碼。但是，可以發(fā)布的版本數(shù)量沒有限制。

在你開始發(fā)布前

首先，你需要一個(gè)crates.io帳戶，用來獲取 API 令牌。為此，訪問主頁，并通過 GitHub 帳戶登錄(現(xiàn)在需要)。在此之后，訪問你的帳號(hào)設(shè)定頁面，并運(yùn)行cargo login命令聯(lián)通賬號(hào)。

$ cargo login abcdefghijklmnopqrstuvwxyz012345

此命令將告訴 Cargo 關(guān)于您的 API 令牌，并將其存儲(chǔ)在您的本地~/.cargo/credentials(以前是~/.cargo/config)。請注意，此令牌是一個(gè)秘密，不應(yīng)與其他任何人分享。如果因任何原因泄漏，您應(yīng)立即重新生成。

在你創(chuàng)建新 crate 前

請記住crates.io上箱子的名字，會(huì)采取先到先得的方式分配。一旦獲得箱子名稱，它就不能用于另一個(gè)箱子.

打包一個(gè) crate

下一步是，將您的包裝箱打包成可供crates.io上傳的格式。為此，我們將使用cargo package子命令。這將把我們的整個(gè)包裝箱全部打包成一個(gè)*.crate文件，其在target/package目錄中。

$ cargo package

作為一個(gè)額外的功能，*.crate將獨(dú)立于當(dāng)前源樹進(jìn)行驗(yàn)證。在*.crate創(chuàng)建之后，會(huì)解壓到target/package目錄，然后從頭開始構(gòu)建，以確保構(gòu)建成功的所有必要文件?？梢允褂?code>--no-verify參數(shù)禁用此行為。

現(xiàn)在是時(shí)候看看*.crate文件了，為了確保您不會(huì)意外地打包 2GB 視頻資源，或用于代碼生成，集成測試或基準(zhǔn)測試的大型數(shù)據(jù)文件。目前存在 10MB 的*.crate文件上傳大小限制。所以，如果tests和benches目錄及其依賴項(xiàng)大小，最多只達(dá) 幾 MB，您仍可以將它們保存在包; 不然的話，最好排除它們。

在打包時(shí)，Cargo 會(huì)自動(dòng)忽略版本控制系統(tǒng)的忽略文件，但是如果要指定要額外的忽略文件集，則可以使用清單中的exclude字段:

[package]
# ...
exclude = [
    "public/assets/*",
    "videos/*",
]

這個(gè)數(shù)組中每個(gè)元素接受的語法是rust-lang/glob。如果您寧愿使用白名單，而不是黑名單,Cargo 也支持include字段，如果設(shè)置,則會(huì)覆蓋exclude字段:

[package]
# ...
include = [
    "**/*.rs",
    "Cargo.toml",
]

上傳該 crate

現(xiàn)在我們已經(jīng)有了*.crate文件準(zhǔn)備好了，可以上傳到crates.io，接著使用cargo publish命令就好。就是這樣，你現(xiàn)在已經(jīng)發(fā)布了你的第一個(gè)箱子!

$ cargo publish

如果你想跳過cargo package那一步，cargo publish如果找不到副本，子命令將自動(dòng)打包本地包.

一定要看看您可以指定的元數(shù)據(jù)確保您的箱子更容易被發(fā)現(xiàn)!

為已存在的 crate，發(fā)布一個(gè)新版本

要發(fā)布新版本，請?jiān)?code>Cargo.toml更改version為您指定的值。記住semver 規(guī)則。然后可選擇運(yùn)行cargo package，如果你想檢查一下*.crate發(fā)布前的新版本文件，然后運(yùn)行cargo publish上傳新版本.

管理一個(gè) 基于 crates.io 的 crate

箱的管理主要通過命令行完成cargo工具，而不是crates.io網(wǎng)絡(luò)界面。為此，有一些子命令來管理包.

cargo yank

在您發(fā)布時(shí)，實(shí)際上可能會(huì)因某種原因，而最終破壞的箱子版本(語法錯(cuò)誤，忘記包含文件等)的情況。對(duì)于諸如此類的情況，Cargo 支持一個(gè)箱子版本的"yank"。

$ cargo yank --vers 1.0.1
$ cargo yank --vers 1.0.1 --undo

一個(gè) yank 不是刪除任何代碼。例如，此功能不用于刪除意外上傳的機(jī)密。如果發(fā)生這種情況，您必須立即重置這些秘密.

一個(gè) yank 版本的語義是，不為該版本創(chuàng)建新的依賴項(xiàng)，但所有現(xiàn)有的依賴項(xiàng)繼續(xù)有效。crates.io其中一個(gè)主要目標(biāo)是作為永久存檔的箱子庫，不會(huì)隨著時(shí)間的推移而改變，而允許刪除版本將違背這一目標(biāo)。所以基本上，一個(gè) yank 意味著所有包的Cargo.lock不會(huì)被破壞，在任何的未來，Cargo.lock生成的文件不會(huì)列出 yank 的版本。(成為了一個(gè)孤島版本)

cargo owner

箱子通常由不止一個(gè)人開發(fā)，或者主要維護(hù)者可能會(huì)隨著時(shí)間而改變!箱子的所有者是唯一允許發(fā)布新版本箱子的人，但是所有者可以指定其他所有者。

$ cargo owner --add my-buddy
$ cargo owner --remove my-buddy
$ cargo owner --add github:rust-lang:owners
$ cargo owner --remove github:rust-lang:owners

給這些命令的所有者 ID 必須是 GitHub 用戶名或 GitHub 團(tuán)隊(duì).

如果用--add了一個(gè)用戶名，那該用戶成為"命名"所有者，擁有該箱子的完全權(quán)利。除了能夠發(fā)布或 yank 箱子的版本，他們還能夠添加或刪除所有者，包含任命他們的所有者。毋庸置疑，你不應(yīng)該讓那些你不完全信任的人，作命名所有者。要成為命名所有者，用戶必須之前就已登錄crates.io。

如果用--add了一個(gè)團(tuán)隊(duì)，那該團(tuán)隊(duì)成為"團(tuán)隊(duì)"所有者，對(duì)箱的權(quán)利受到限制。雖然他們有權(quán)發(fā)布或 yank 箱子的版本，但他們不能夠添加或刪除所有者。除了更方便管理所有者群體之外，團(tuán)隊(duì)還可以更安全地防止惡意所有者。

團(tuán)隊(duì)的目前的語法是github:org:team(見上面的例子)。要將團(tuán)隊(duì)添加為所有者，必須是該團(tuán)隊(duì)的成員。刪除所有者的團(tuán)隊(duì)就沒有此類限制.

GitHub 權(quán)限

團(tuán)隊(duì)成員資格，不是 GitHub 提供的簡單公共訪問權(quán)限，并且在使用它時(shí)可能會(huì)遇到以下消息:

您似乎無權(quán)從 GitHub 查詢必要的屬性，來完成此請求。您可能需要在crates.io重新進(jìn)行身份驗(yàn)證，并申請閱讀 GitHub 組織成員資格的權(quán)限。去https://crates.io/login看看

這基本上是一個(gè)全查詢防御，當(dāng)"你試圖查詢團(tuán)隊(duì)信息，而其中的五級(jí)成員訪問控制，拒絕了它"。這并不夸張。GitHub 對(duì)團(tuán)隊(duì)訪問控制的支持是企業(yè)級(jí).

最可能的原因是您最后一次登錄是在添加此功能之前。我們最初沒有要求 GitHub 對(duì)用戶進(jìn)行身份驗(yàn)證時(shí)的權(quán)限，因?yàn)槲覀儗?shí)際上并沒有將用戶的令牌用于登錄以外的任何其他內(nèi)容。但是，為了代表您能夠查詢團(tuán)隊(duì)成員資格，我們現(xiàn)在需要read:org范圍權(quán)限。

您完全可以拒絕我們這個(gè)范圍，且在團(tuán)隊(duì)介紹之前所做的一切，都將繼續(xù)有效。但是，您永遠(yuǎn)無法將團(tuán)隊(duì)添加為所有者，或者將團(tuán)隊(duì)作為團(tuán)隊(duì)所有者發(fā)布。如果您嘗試這樣做，您將收到上述錯(cuò)誤。如果你試圖發(fā)布一個(gè)你根本不擁有的箱子，但恰好有一個(gè)團(tuán)隊(duì)，你可能也會(huì)看到這個(gè)錯(cuò)誤。

如果你改變主意，或者只是不確定是否crates.io有足夠的許可，你可以隨時(shí)去https://crates.io/login查看，crates.io會(huì)提示您，它沒有獲得它想要的所有范圍許可。

查詢 GitHub 的另一個(gè)障礙，是組織可能會(huì)主動(dòng)拒絕第三方訪問。要檢查這一點(diǎn)，您可以訪問:

https://github.com/organizations/:org/settings/oauth_application_policy

這里的:org是組織的名稱(例如 rust-lang)。你可能會(huì)看到類似的東西:

你可以選擇，從您組織的黑名單中，明確刪除crates.io，或只需按"刪除限制(Remove Restrictions)"按鈕，允許所有第三方應(yīng)用程序訪問此數(shù)據(jù)。

或者，當(dāng)crates.io請求了read:org范圍，您可以明確進(jìn)入白名單的crates.io，能查詢組織的問題，通過按其名稱旁邊的"授予訪問權(quán)限(Grant Access)"按鈕: