Cargo 更換 cargo 源

更換 cargo 源 —— 附目前可用國(guó)內(nèi) cargo 鏡像源配置

本文檔是關(guān)于更換 crate 索引(注冊(cè)表)。您可以閱讀有關(guān)重寫(xiě)依賴(lài)項(xiàng)的信息，它在本文檔的重寫(xiě)依賴(lài)關(guān)系部分。

Cargo 支持用另一個(gè)來(lái)源更換一個(gè)來(lái)源的能力，可根據(jù)鏡像或 vendoring 依賴(lài)關(guān)系來(lái)表達(dá)傾向。要配置這些，目前通過(guò).cargo/config配置機(jī)制完成，像這樣:

# `source` 表下，就是存儲(chǔ)有關(guān)要更換的來(lái)源名稱(chēng)
[source]

# 在`source` 表格之下的，可為一定數(shù)量的有關(guān)來(lái)源名稱(chēng). 示例下面就# 定義了一個(gè)新源， 叫 `my-awesome-source`， 其內(nèi)容來(lái)自本地 # `vendor`目錄 ，其相對(duì)于包含`.cargo/config`文件的目錄
[source.my-awesome-source]
directory = "vendor"

# Git sources 也指定一個(gè) branch/tag/rev
git = "https://example.com/path/to/repo"
# branch = "master"
# tag = "v1.0.1"
# rev = "313f44e8"

# The crates.io 默認(rèn)源 在"crates-io"名稱(chēng)下， 且在這里我們使用 `replace-with` 字段指明 默認(rèn)源更換成"my-awesome-source"源
[source.crates-io]
replace-with = "my-awesome-source"

使用此配置，Cargo 會(huì)嘗試在"vendor"目錄中，查找所有包，而不是 查詢(xún)?cè)诰€注冊(cè)表 crates.io 。Cargo 有兩種來(lái)源更換的表達(dá) :

• 供應(yīng)(Vendoring) - 可以定義自定義源，它們表示本地文件系統(tǒng)上的包。這些源是它們正在更換的源的子集，并在需要時(shí)可以檢入包中。

• 鏡像(Mirroring) - 可以更換為等效版本的源，行為表現(xiàn)為 crates.io 本身的緩存。

Cargo 有一個(gè)關(guān)于來(lái)源更換的核心假設(shè)，源代碼從兩個(gè)完全相同的源而來(lái)。在上面的例子中，Cargo 假設(shè)所有的箱子都來(lái)自my-awesome-source，與crates-io副本完全相同。請(qǐng)注意，這也意味著my-awesome-source，不允許有crates-io源不存在的箱。

因此，來(lái)源更換不適用于依賴(lài)項(xiàng)補(bǔ)丁(fix bug)，或私有注冊(cè)表等情況。Cargo 是通過(guò)使用[replace]字段支持依賴(lài)項(xiàng)補(bǔ)丁，計(jì)劃為未來(lái)版本的 Cargo 提供私人注冊(cè)表的支持。

配置

更換源的配置通過(guò)完成.cargo/config，下面為全套可用字段是:

# 每個(gè)源都有自己的表格，名稱(chēng)即是表名
[source.the-source-name]

# 命令 ，`the-source-name` 會(huì)被`another-source`取代
replace-with = "another-source"

# 有幾種可用的源定義(接下來(lái)有所描述)
registry = "https://example.com/path/to/index"
local-registry = "path/to/registry"
directory = "path/to/vendor"

crates-io代表 crates.io 在線注冊(cè)表(箱的默認(rèn)來(lái)源)，可以更換為:

[source.crates-io]
replace-with = 'another-source'

注冊(cè)表源

"注冊(cè)表源"與 crates.io 本身相同。也就是說(shuō)，它也有一個(gè)在 git 存儲(chǔ)庫(kù)中提供的索引，該存儲(chǔ)庫(kù)匹配crates.io index的格式。然后該存儲(chǔ)庫(kù)具有指示從哪里下載包的配置。

目前還沒(méi)有一個(gè)已經(jīng)設(shè)置 crates.io 的鏡像的可用項(xiàng)目。請(qǐng)繼續(xù)關(guān)注!

以下配置由芽之家書(shū)館搜集驗(yàn)證，并持續(xù)更新——

中國(guó)大陸用戶(hù)，因?yàn)榫W(wǎng)絡(luò)原因，推薦使用國(guó)內(nèi)鏡像源。目前國(guó)內(nèi) cargo 鏡像源有：中國(guó)科學(xué)技術(shù)大學(xué)源、上海交通大學(xué)源、清華大學(xué)源，以及 rustcc 社區(qū)源。

自定義 cargo 源有兩種方法，推薦使用第一種——

• 創(chuàng)建 $HOME/.cargo/config 文件（各操作系統(tǒng)及版本均大致相同），然后在 config 文件內(nèi)寫(xiě)入下述配置內(nèi)容。其中協(xié)議推薦使用 git，但對(duì)于 https 和 git 協(xié)議，一般各鏡像源都支持，并且是可以互換的。如果你所處的環(huán)境中不允許使用 git 協(xié)議，或者配置 git 協(xié)議后不能正常獲取和編譯 crate，可以換 https 協(xié)議再試試。

[source.crates-io]
registry = "https://github.com/rust-lang/crates.io-index"
# 指定鏡像
replace-with = '鏡像源名' # 如：tuna、sjtu、ustc，或者 rustcc

# 注：以下源配置一個(gè)即可，無(wú)需全部

# 中國(guó)科學(xué)技術(shù)大學(xué)
[source.ustc]
registry = "https://mirrors.ustc.edu.cn/crates.io-index"
# >>> 或者 <<<
registry = "git://mirrors.ustc.edu.cn/crates.io-index"

# 上海交通大學(xué)
[source.sjtu]
registry = "https://mirrors.sjtug.sjtu.edu.cn/git/crates.io-index/"

# 清華大學(xué)
[source.tuna]
registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git"

# rustcc社區(qū)
[source.rustcc]
registry = "https://code.aliyun.com/rustcc/crates.io-index.git"

• 或者在項(xiàng)目工程結(jié)構(gòu)中，與 Cargo.toml 同級(jí)目錄的 .cargo 文件夾下創(chuàng)建 config 文件，config 文件配置方法和內(nèi)容與第一種相同。

本地 注冊(cè)表源

"本地注冊(cè)表源"旨在成為另一個(gè)注冊(cè)表源的子集，但可在本地文件系統(tǒng)(也稱(chēng)為 vendoring)上使用。本地注冊(cè)表是提前下載，通常與一個(gè) Cargo.lock同步，并由一組*.crate文件和像普通注冊(cè)表一樣的索引組成。

管理和創(chuàng)建本地注冊(cè)表源的主要方法是通過(guò)cargo-local-registry子命令，可在 crates.io 上找到，并用cargo install cargo-local-registry安裝。

本地注冊(cè)表包含在一個(gè)目錄，其中包含許多從 crates.io 下載的*.crate文件，以及index目錄，它與 crates.io-index 項(xiàng)目目錄具有相同格式(僅填充有存在的 crates).

目錄 源

"目錄源"類(lèi)似于本地注冊(cè)表源，其中包含本地文件系統(tǒng)上許多的可用包，適用于 vendoring 依賴(lài)項(xiàng)。與本地注冊(cè)表一樣，目錄源主要由外部子命令管理cargo-vendor，可用cargo install cargo-vendor安裝。

目錄源與本地注冊(cè)表不同，但它們包含*.crate文件的解壓縮版本，使其在某些情況下，更適合檢查所有內(nèi)容到源代碼控制工具。目錄源只是一個(gè)包含許多其他目錄的目錄，其中包含 crates 的源代碼(解壓縮版本的*.crate文件)。目前，對(duì)每個(gè)目錄的名稱(chēng)沒(méi)有限制。

目錄源中的每個(gè)包也有一個(gè)關(guān)聯(lián)的元數(shù)據(jù)文件，指示包中每個(gè)文件的校驗(yàn)和，以防止意外修改。