Cargo 組態(tài)

配置

本文檔將解釋 Cargo 的配置系統(tǒng)如何工作，以及可用的字段或配置。有關(guān)通過其清單，來配置程序包的信息，請參閱清單格式.

Hierarchical structure

分層策略

Cargo 允許特定包，具有本地配置以及全局配置，就像 git 一樣。Cargo 將其擴展為分層策略。例如，如果在/projects/foo/bar/baz調(diào)用 Cargo，然后將按以下順序，探測和統(tǒng)一配置文件:

• /projects/foo/bar/baz/.cargo/config
• /projects/foo/bar/.cargo/config
• /projects/foo/.cargo/config
• /projects/.cargo/config
• /.cargo/config
• $HOME/.cargo/config

使用此結(jié)構(gòu)，您可以為每個包指定配置，甚至可以將其檢入版本控制。您還可以在主目錄中，使用指定默認(rèn)值的配置文件。

Configuration format

配置格式

所有配置目前都在TOML 格式(與 Cargo.toml 清單一樣)，在字段(表格)內(nèi)部使用簡單的鍵值對，它們都被合并在一起。

Configuration keys

配置字段

以下所有字段都是可選的，除非另有說明，否則它們的默認(rèn)值將作為其值。

指定工具的鍵值可以給出，一個‘絕對路徑，相對路徑或無路徑工具名稱’。給定的絕對路徑和無路徑工具名稱直接使用。相對路徑，則解析相對于.cargo目錄的父目錄，配置文件就居住在里面。

# 路徑數(shù)組，指向本地將要覆蓋依賴項的存儲庫.
# 更多信息，請看 指定 依賴項 指南.
paths = ["/path/to/override"]

[cargo-new]
# 這是你 放 name/email 的地方， 在一個新Cargo.toml中的
#`authors` 表格就會生成。若不存在， 那 `git` 會去調(diào)查， 若還是不
# 存在，那 `$USER` 和 `$EMAIL` 會被使用.
name = "..."
email = "..."

# 默認(rèn)來說， `cargo new` 會初始化一個新的  Git repository. 該字段若設(shè)為 `hg` ，就是新建一個 Mercurial repository， 或 `none` 禁用此行為.
vcs = "none"

# 接下來的 部分， $triple 是 一些有效目標(biāo) triple的引用， 而不是一個字面量"$triple"的意思， 這個引用是無論何時都能應(yīng)用編譯的。
# 'cfg(...)' 是參考 類Rust `#[cfg]` 語法 (條件語句)
[target.$triple]
#  linker 可傳遞參數(shù)給 rustc (通過 `-C linker=`) 當(dāng) `$triple`
# 要被編譯. 默認(rèn)不傳遞東東
linker = ".."
# 一樣，但這是傳遞給 rustc 關(guān)于 庫壓縮的參數(shù) ，通過 `-C ar=`.
ar = ".."
# 若 提供了 一個 runner ， 編譯`$triple`目標(biāo) 會通過 執(zhí)行 runner 執(zhí)行文件來完成， 它會將真正的目標(biāo) 作為第一參數(shù).
# 這可運行 `cargo run`， `cargo test` 和 `cargo bench` 命令.
# 默認(rèn)，編譯目標(biāo)是 直接執(zhí)行的.
runner = ".."
# 自定義 全編譯器，目標(biāo)為 $triple
# 這些值會覆蓋 build.rustflags
rustflags = ["..", ".."]

[target.'cfg(...)']
# 與 $triple 配置類似， 但使用的是 `cfg` 語法.
# 若有幾個 `cfg` 和 $triple 目標(biāo)作為備用， 那 rustflags
# 會被串聯(lián)起來. 該 `cfg` 語法僅能應(yīng)用到 rustflags， 而不能是
# linker.
rustflags = ["..", ".."]
# 與 $triple 配置類似 ， 但使用的是 `cfg` 語法.
# 若 一個或多個 `cfg`s， 和一個 a $triple 目標(biāo)作為備用，那 該$triple將會被使用
# 若有幾個 `cfg` 和 備用的， 那構(gòu)建會 error
runner = ".."

# 關(guān)聯(lián)到 注冊表 的配置字段
[registry]
index = "..."   # 注冊表索引的URL（默認(rèn)為中央存儲庫）
token = "..."   # 訪問令牌（在中央回購網(wǎng)站上找到）
default = "..." # 要使用的默認(rèn)備用注冊表（可以使用--registry覆蓋）

[http]
proxy = "host:port" # 用于HTTP請求的HTTP代理（默認(rèn)為none）
                    # libcurl格式，例如“socks5h://host:port”
timeout = 30        # 每個HTTP請求的超時，以秒為單位
cainfo = "cert.pem" # 證書頒發(fā)機構(gòu)（CA）包的路徑（可選）
check-revoke = true # 指示是否檢查SSL證書是否已廢除
low-speed-limit = 5 # 限速 字節(jié)/秒（10 = 默認(rèn)值，0 = 禁用）
multiplexing = true # 是否在可能的情況下使用 HTTP/2多路復(fù)用

# 此設(shè)置可用于幫助調(diào)試Cargo所發(fā)生的HTTP請求
# 當(dāng)設(shè)置為“true”時，將填充Cargo的正常調(diào)試日志記錄
# 關(guān)于HTTP的信息，您可以使用
# `RUST_LOG=cargo::ops::registry=debug`提取（和`trace`可能會打印更多）。
#
# 在將這些日志發(fā)布到其他地方時要小心，因可能存在這樣的
# header中，有一個你不想泄露的身份驗證令牌的情況！務(wù)必
# 在發(fā)布之前簡要查看日志。
debug = false

[build]
jobs = 1                  # 并行作業(yè)數(shù)，默認(rèn)為CPU數(shù)
rustc = "rustc"           # rust編譯器工具
rustdoc = "rustdoc"       # doc生成器工具
target = "triple"         # build為目標(biāo) triple（被`cargo install`忽略）
target-dir = "target"     # 放置所有生成的工件的路徑
rustflags = ["..", ".."]  # 自定義 傳遞給所有編譯器調(diào)用 的參數(shù)
incremental = true        # 是否啟用增量編譯
dep-info-basedir = ".."   # depfiles中，目標(biāo)的基本目錄的完整路徑

[term]
verbose = false        # Cargo否提供詳細(xì)輸出
color = 'auto'         # Cargo否著色輸出

# 網(wǎng)絡(luò)配置
[net]
retry = 2 # 失敗 自動重試 次數(shù)
git-fetch-with-cli = false  # 若為 `true` 我們會使用 `git`命令行去 fetch git repos

# 別名 cargo 命令. 前 3 個aliases 是內(nèi)置的. 如果你的命令 要求 整行命令，請使用 list 格式.
[alias]
b = "build"
t = "test"
r = "run"
rr = "run --release"
space_example = ["run", "--release", "--", "\"command list\""]

Environment variables

環(huán)境變量

除了上面的 TOML 語法之外，還可以通過環(huán)境變量配置 Cargo。對于上方的foo.bar表格的每個配置字段，也可以用環(huán)境變量CARGO_FOO_BAR來定義值。比如說build.jobs字段，也可以通過CARGO_BUILD_JOBS定義。

環(huán)境變量將優(yōu)先于 TOML 配置，并且當(dāng)前僅支持由環(huán)境變量定義的整數(shù)，布爾和字符串字段，這意味著來源更換，能由表格表示，卻不能通過環(huán)境變量配置。

除上述系統(tǒng)外，Cargo 還認(rèn)可其他一些特定的環(huán)境變量.