Cargo 清單格式

The Manifest Format

清單格式

每個(gè)包的這個(gè)Cargo.toml文件稱為清單. 每個(gè)清單文件由一個(gè)或多個(gè)部分(表格)組成.

• [package] 部分
• 依賴項(xiàng) 部分
• [profile.*] 部分
• [features] 部分
• [workspace] 部分
• 項(xiàng)目布局
• Rust 示例
• Rust 測試
• 配置一個(gè) target
• [patch] 部分
• [replace] 部分

The [package] section

[package]部分

Cargo.toml的第一部分是[package].

[package]
name = "hello_world" # the name of the package
version = "0.1.0"    # the current version, obeying semver
authors = ["Alice <a@example.com>", "Bob <b@example.com>"]

所有這三個(gè)字段都是必要性的.

The version field

version 字段

Cargo 烘烤的概念是語義版本控制，所以確保你遵循一些基本規(guī)則:

• 在您達(dá)到 1.0.0 之前，任何事情都會發(fā)生，但是如果您進(jìn)行了重大變化的更新，則增加次要(minor)版本。在 Rust 語言中，重大變化包括，向結(jié)構(gòu)添加字段，或增加變量到枚舉。
• 在 1.0.0 之后，只在增加主要(major)版本時(shí)進(jìn)行重大變化。不要破壞建筑.
• 在 1.0.0 之后，不要在補(bǔ)丁級別(patch)的版本添加任何新的公共 API(沒有任何新的pub)。如果添加pub結(jié)構(gòu)、特性、字段、類型、函數(shù)、方法或其他任何東東，則總是增加次要版本。
• 使用具有三個(gè)數(shù)字部分的版本號，如 1.0.0，而不是 1.0。

The edition field (optional)

edition 字段 (可選)

您可以在Cargo.toml中的edition字段，選擇一個(gè)特定的 Rust 版本，用于您的包。 如果沒有指定版本,它將默認(rèn)為 2015。

[package]
# ...
edition = '2018'

這個(gè)edition字段會影響到您的包編譯的版本。若是通過cargo new得來的項(xiàng)目，Cargo 將始終讓edition字段設(shè)置為最新版本。設(shè)置[package]下的edition字段將影響包中的所有目標(biāo)/箱，包括測試套件、基準(zhǔn)、二進(jìn)制文件、示例等。

The build field (optional)

build 字段 (可選)

此字段指定包根目錄中的文件，該文件是構(gòu)建腳本，用于生成本機(jī)代碼。可以在構(gòu)建腳本指導(dǎo)中找到更多信息..

[package]
# ...
build = "build.rs"

The links field (optional)

links 字段 (可選)

此字段指定，要鏈接到的本機(jī)庫名，更多信息可以在構(gòu)建腳本指南的links部分.

[package]
# ...
links = "foo"
build = "build.rs"

The documentation field (optional)

documentation 字段 (可選)

此字段指定托管箱(crate)文檔的網(wǎng)站的 URL。如果清單文件中沒有指定 URL，crates.io自動(dòng)將你的箱子連接到相應(yīng)的箱子的docs.rs頁.

來自特定主機(jī)的文檔鏈接被列入黑名單。如果已知主機(jī)不承載文檔，并且可能具有惡意意圖，例如廣告跟蹤網(wǎng)絡(luò)，則主機(jī)被添加到黑名單中。下列主機(jī)的 URL 就被列入黑名單:

• rust-ci.org

來自黑名單主機(jī)的文檔 URL 將不會出現(xiàn)在 crates.io 上，并且可能被 docs.rs 鏈接替換。

The exclude and include fields (optional)

exclude 和 include 字段 (可選)

出于打包和重建包的目的，您可以顯式地指定一組globs模式，匹配項(xiàng)應(yīng)被忽略或包含。如exclude字段標(biāo)識了在發(fā)布包時(shí)，不包括的一組文件，以及檢測何時(shí)重建包時(shí)，應(yīng)該忽略的文件，而include就是顯式指定一定包含的文件。

如果一個(gè) VCS 被用于一個(gè)包，則exclude字段將被植入 VCS 的忽略設(shè)置(例如 Git 的.gitignore)。

[package]
# ...
exclude = ["build/**/*.o", "doc/**/*.md"]

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

選項(xiàng)是相互排斥的: include設(shè)置覆蓋exclude。 注意include必須是文件的詳盡列表，否則可能不包括必要的源文件。

Migrating to gitignore-like pattern matching

轉(zhuǎn)移成 類gitignore 模式匹配

這些配置的當(dāng)前解釋實(shí)現(xiàn)都基于 UNIX Globs，如glob箱。 若是我們想要 Cargo 的include和exclude盡可能配置為類似于gitignore。可看看這個(gè)gitignore規(guī)范，其也是基于 Globs 的，但是還有許多其他的特性，這些特性使模式編寫更容易，控制也更多。因此，我們正在遷移這些配置規(guī)則的解釋實(shí)現(xiàn)，以使用ignore箱，并認(rèn)真對待gitignore文件的每一條行規(guī)則。見跟蹤問題有關(guān)遷移的更多細(xì)節(jié)。

The publish field (optional)

publish 字段 (可選)

這個(gè)publish字段通過錯(cuò)誤，防止將包(crate)，發(fā)布到包注冊中心(如crates.io)。

[package]
# ...
publish = false

The workspace field (optional)

workspace 字段 (可選)

這個(gè)workspace字段可用于配置此包將屬于的工作區(qū)。如果沒有指定，這將被推斷為文件系統(tǒng)中第一個(gè) Cargo.toml 的[workspace]。

[package]
# ...
workspace = "path/to/workspace/root"

有關(guān)更多信息，請參見下面的工作區(qū)(workspace)表格的文檔.

Package metadata

包 元信息

[package]部分會接受許多可選的元數(shù)據(jù)字段:

[package]
# ...

# 關(guān)于包的簡短介紹. 這不會以任何格式呈現(xiàn)
# 到 crates.io (又名 這不是markdown).
description = "..."

# 這些URL指向有關(guān)包的更多信息 這些是
# 旨在成為相關(guān)數(shù)據(jù)的網(wǎng)頁入口， 不一定兼容
# VCS工具(類似的)等.
documentation = "..."
homepage = "..."
repository = "..."

# 這指向包根目錄下的文件 (與 `Cargo.toml` 相對的).
# 該文件的內(nèi)容會存儲，并在注冊表中編入索引。
# crates.io 將渲染此文件，并將結(jié)果放在包的頁面上.
readme = "..."

# 這是一個(gè)，最多五個(gè)描述此箱的關(guān)鍵字的列表. 關(guān)鍵詞
# 可以在 crates.io 上搜索, 和你可以選擇任何單詞
# 幫助別人找到這個(gè)箱子。
keywords = ["...", "..."]

# 這是此箱子最適合的(最多五個(gè))類別的列表.
# 類別是 crates.io/category_slugs 上可用的固定列表, 和
# 他們必須完全匹配.
categories = ["...", "..."]

# 這是此包的SPDX 2.1許可證表達(dá)式.  目前
# crates.io將根據(jù)白名單的已知許可證和SPDX許可證列表2.4中的異常標(biāo)識符，
# 驗(yàn)證提供的許可證。目前不支持括號。
#
# 使用AND和OR的許可證表達(dá)式
# 運(yùn)算符以獲得更明確的語義。
license = "..."

# 如果程序包使用非標(biāo)準(zhǔn)許可證, 則可以指定此 key
# 代替上述 key 和 必須指向相對于此清單的文件
# (類似于 readme key).
license-file = "..."

# 要在crates.io上顯示的徽章規(guī)范，的可選項(xiàng)。
#
#  - 與當(dāng)前可用的構(gòu)建狀態(tài)有關(guān)的徽章是
#   Appveyor, CircleCI, GitLab, 和 TravisCI.
# - 與代碼測試覆蓋有關(guān)的可用徽章是 Codecov 和
#   Coveralls.
# - 還有基于 isitmaintained.com的維護(hù)相關(guān)徽章
#   其中說明了問題解決時(shí)間，未決問題的百分比和未來
#   維護(hù)意圖。
#
# 若要求一個(gè)`repository` key, 就表示一個(gè)`user/repo` 格式的存儲庫
[badges]

# Appveyor: `repository` 是必須的. `branch` 是可選的; 默認(rèn)為 `master`
# `service` 是可選的; 有效值是 `github` (默認(rèn)), `bitbucket`, 和
# `gitlab`; `id` 是可選的; 如果你想改用，可以指定appveyor 項(xiàng)目ID.
# `project_name` 是可選的; 使用在 repository
# 名稱 與 appveyor 項(xiàng)目名稱 不同的情況.
appveyor = { repository = "...", branch = "master", service = "github" }

# Circle CI: `repository` 是必須的. `branch` 是可選的; 默認(rèn)為 `master`
circle-ci = { repository = "...", branch = "master" }

# GitLab: `repository` 是必須的. `branch` 是可選的; 默認(rèn)為 `master`
gitlab = { repository = "...", branch = "master" }

# Travis CI: `repository`為 "<user>/<project>"格式 是必須的.
# `branch` 是可選的; 默認(rèn)為 `master`
travis-ci = { repository = "...", branch = "master" }

# Codecov: `repository` 是必須的. `branch` 是可選的; 默認(rèn)為 `master`
# `service` 是可選的; 有效值是 `github` (默認(rèn)), `bitbucket`, 和
# `gitlab`.
codecov = { repository = "...", branch = "master", service = "github" }

# Coveralls: `repository` 是必須的. `branch` 是可選的; 默認(rèn)為 `master`
# `service` 是可選的; 有效值是 `github` (默認(rèn)) 和 `bitbucket`.
coveralls = { repository = "...", branch = "master", service = "github" }

# 是否保持解決時(shí)間: `repository` 是必須的.
is-it-maintained-issue-resolution = { repository = "..." }

# 它是否保持未解決問題的百分比: `repository` 是必須的.
is-it-maintained-open-issues = { repository = "..." }

# Maintenance: `status` 是必須的. 可用的選項(xiàng)是 `actively-developed`,
# `passively-maintained`, `as-is`, `experimental`, `looking-for-maintainer`,
# `deprecated`, 和 默認(rèn)為 `none`, 不會在 crates.io 顯示徽章.
maintenance = { status = "..." }

這個(gè)crates.io注冊中心將呈現(xiàn)描述、顯示許可證、鏈接到三個(gè) URL 并根據(jù)關(guān)鍵字進(jìn)行分類。這些字段為注冊表的用戶提供有用的信息，并且還影響箱子的搜索排名。在發(fā)布箱的'展示欄'，省略任何東西都是非常令人沮喪的。

SPDX 2.1 許可證表達(dá)式被記錄在案在這里。 許可證列表的當(dāng)前版本可用的，在這里，版本 2.4 是可用的，在這里.

The metadata table (optional)

metadata 表格 (可選)

默認(rèn)情況下，Cargo 將對Cargo.toml不使用的字段發(fā)出警告，協(xié)助檢測錯(cuò)別字等。就像這個(gè)package.metadata表格，但是，完全不寫了的話， Cargo 將不會被警告。這個(gè)表格可在Cargo.toml，用于將包配置存儲好。 例如:

[package]
name = "..."
# ...

# 當(dāng)要生成一個(gè) Android APK，這個(gè)元信息會被使用, 例如.
[package.metadata.android]
package-name = "my-awesome-android-app"
assets = "path/to/static"

Dependency sections

依賴 部分

見指定依賴-那頁有關(guān)[dependencies]，[dev-dependencies]，[build-dependencies]和特定目標(biāo)的[target.*.dependencies]部分的信息。

The [profile.*] sections

[profile.*] 部分

Cargo 支持了，可通過頂層 配置文件(profile) 調(diào)用 rustc 的自定義配置。任何清單都可以聲明一個(gè)配置文件，但是實(shí)際上只讀取頂級包的配置文件。所有依賴項(xiàng)的配置文件都將被重寫，這樣做是為了讓頂級包能夠控制，其依賴項(xiàng)如何編譯的。

目前有四個(gè)受支持的配置文件名稱，它們都具有相同的配置。下面列出了可用的配置，以及每個(gè)配置文件的默認(rèn)設(shè)置.

# 此為 開發(fā)配置文件, 給 `cargo build` 所使用.
[profile.dev]
opt-level = 0      # 控制編譯器構(gòu)建的`--opt-level`。
                   # 0-1適合調(diào)試。 2是良好優(yōu)化的。最大為 3。
                   # 's' 企圖優(yōu)化大小, 'z' 則 進(jìn)一步優(yōu)化大小.
debug = true       # (u32 or bool) 包括調(diào)試信息（調(diào)試符號）.
                   # 相當(dāng)于 `-C debuginfo=2` 編譯器 標(biāo)志.
rpath = false      # 控制 編譯器 是否應(yīng)該設(shè)置加載器路徑.
                   # 若為 true, 傳遞 `-C rpath` 標(biāo)志 給 編譯器.
lto = false        # 鏈接時(shí)間優(yōu)化通常會減少二進(jìn)制文件和靜態(tài)庫的大小
                   # 但會增加編譯時(shí)間.
                   # 若是 true, 傳遞 `-C lto` 標(biāo)志 給 編譯器, 和 若是一個(gè)
                   # 字符串值 像 'thin' ，那會傳遞 `-C lto=thin`
                   # 給 編譯器
debug-assertions = true # 控制是否啟用調(diào)試斷言
                   # (e.g. debug_assert!() 和 算術(shù)溢出檢查)
codegen-units = 16 # if > 1 并行代碼生成，以改善
                   # 編譯時(shí)間, 但阻止了些優(yōu)化.
                   # 傳遞 `-C codegen-units`.
panic = 'unwind'   # 恐慌策略 (`-C panic=...`), 也可以是 'abort'
incremental = true # 是否啟用增量編譯
overflow-checks = true # 使用溢出檢查進(jìn)行整數(shù)運(yùn)算。
                   # 傳遞 `-C overflow-checks=...`標(biāo)志 給 compiler.

# 發(fā)布(release)的配置文件, 用于 `cargo build --release` (和 依賴項(xiàng)的
# `cargo test --release`,  包括本地 library 或 binary).
[profile.release]
opt-level = 3
debug = false
rpath = false
lto = false
debug-assertions = false
codegen-units = 16
panic = 'unwind'
incremental = false
overflow-checks = false

# 測試的配置文件, 用于 `cargo test` (對于 `cargo test --release`，可看
# `release` 和 `bench` 配置文件).
[profile.test]
opt-level = 0
debug = 2
rpath = false
lto = false
debug-assertions = true
codegen-units = 16
panic = 'unwind'
incremental = true
overflow-checks = true

# 基準(zhǔn)的配置文件, 用于`cargo bench` (和 要測試的目標(biāo) 和
# 單元測試的 `cargo test --release`).
[profile.bench]
opt-level = 3
debug = false
rpath = false
lto = false
debug-assertions = false
codegen-units = 16
panic = 'unwind'
incremental = false
overflow-checks = false

The [features] section

[features] 部分

Cargo 支持特性，允許表達(dá):

• 條件編譯選項(xiàng)(通過cfg屬性);
• 可選的依賴項(xiàng)，增強(qiáng)了包，但不是必需的;還有
• 可選依賴項(xiàng)的簇，如postgres，其中就包括postgres包postgres-macros包，以及可能的其他包(如開發(fā)時(shí)的模擬庫、調(diào)試工具等)。

包的特性也可以是可選的依賴項(xiàng)，也可以是一組其他特性。指定特性的格式是:

[package]
name = "awesome"

[features]
# 默認(rèn)的可選包集。大多數(shù)人都想使用這些
# 包, 但它們是嚴(yán)格可選的。請注意，`session`不是包
# 而是此清單中列出的另一個(gè)功能。
default = ["jquery", "uglifier", "session"]

# 沒有依賴關(guān)系的特性，主要用于條件編譯，
# 像 `#[cfg(feature = "go-faster")]`.
go-faster = []

# `secure-password` 特性 需要 bcrypt 包. 這種別名
將允許人們以更高級別的方式討論該 特性 和 允許
# 此軟件包將在未來為該特性添加更多要求.
secure-password = ["bcrypt"]

# 特性可用于重新導(dǎo)出其他包的特性. `awesome`包的 `session`
# 特性將確保 cookie/session 也是可用的
session = ["cookie/session"]

[dependencies]
# 這些包是強(qiáng)制性的，是該軟件包發(fā)行版的核心。
cookie = "1.2.0"
oauth = "1.1.0"
route-recognizer = "=2.1.0"

# 所以可選依賴項(xiàng)的列表, 其中一些是上面的
# `features`. 它們可以通過應(yīng)用程序選擇加入。
jquery = { version = "1.0.2", optional = true }
uglifier = { version = "1.5.3", optional = true }
bcrypt = { version = "*", optional = true }
civet = { version = "*", optional = true }

使用awesome包:

[dependencies.awesome]
version = "1.3.5"
default-features = false # 不包括默認(rèn)功能，和可選,
                         # 任君選 個(gè)性化特性
features = ["secure-password", "civet"]

Rules

規(guī)則

特性的使用遵循一些規(guī)則:

• 特性名稱不能與清單中的其他包名稱沖突。這是因?yàn)樗麄儽贿x擇加入features = [...]，而它只有一個(gè)命名空間。
• 除此default特性之外，所有的特性都是可選的。若要退出默認(rèn)功能，請使用default-features = false，任君選擇個(gè)人特性.
• 特性群組不允許周期性地相互依賴.
• 開發(fā) 依賴項(xiàng)不能是可選的.
• 特性群組只能引用可選的依賴項(xiàng).
• 當(dāng)選擇一個(gè)特性時(shí)，Cargo 將調(diào)用具有--cfg feature="${feature_name}"的rustc。如果包含一個(gè)特性群組，那么它將包括所有單獨(dú)的特性。這可以通過#[cfg(feature = "foo")]在代碼中進(jìn)行測試..

主要注意的是，顯露的特性，實(shí)際上不激活任何可選的依賴項(xiàng)。這就允許包在不需要新的依賴項(xiàng)的情況下，于內(nèi)部啟用/禁用特性。

Usage in end products

生產(chǎn)終點(diǎn)的用法

該特性的一個(gè)主要用例是在最終產(chǎn)品中，指定可選特性。例如，Servo 包可能希望包含可選特性，人們可以在構(gòu)建時(shí)，啟用或禁用它。

在這種情況下，Servo 將在Cargo.toml描述特性，且用命令行標(biāo)志來啟用這些特性:

$ cargo build --release --features "shumway pdf"

可以使用--no-default-features，排除默認(rèn)特性。

Usage in packages

包(庫)的用法

在大多數(shù)情況下，在庫中可選依賴的概念，最好將其表示為頂級應(yīng)用程序所依賴的單獨(dú)包。

然而，像 Iron 或 Piston 這樣的高級軟件包會需要排布多個(gè)軟件包以便于安裝。當(dāng)前的 Cargo 系統(tǒng)允許它們將一些強(qiáng)制依賴項(xiàng)，整合到一個(gè)包中，以便于安裝。

在某些情況下，包可能希望為可選依賴項(xiàng)，提供額外的管理:

• 將多個(gè)低層可選依賴項(xiàng)，組合到一個(gè)單獨(dú)的高級特性中;
• 由包用戶指定推薦(或建議)要包括的包;
• 包括特性(類似secure-password在激勵(lì)示例中)，這只在可選的依賴項(xiàng)可用時(shí)才能工作，并且很難實(shí)現(xiàn)為單獨(dú)的包(例如，設(shè)計(jì)一個(gè)與 OpenSSL 完全解耦的 IO 包可能過于困難，那這時(shí)，就可通過包含單獨(dú)的包來選擇相關(guān)特性)。

在幾乎所有情況下，在設(shè)計(jì)牢固的高級包之外，使用這些特性都是反模式的。如果某個(gè)特性是可選的，那么它幾乎可以肯定地表示為單獨(dú)的包。

The [workspace] section

[workspace] 部分

包可以定義一個(gè)工作區(qū)，它是一組箱，所有箱將共享相同Cargo.lock和輸出目錄。這個(gè)[workspace]表格可以定義為:

[workspace]

# 可選字段，從路徑依賴推斷（如果不存在）。
# 此處必須給出，包含的其他非路徑依賴。
# 特別是, 對于 一個(gè)虛擬清單，所有成員都要列出來。
members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]

# 可選字段, 如果不存在則為空
exclude = ["path1", "path/to/dir2"]

工作區(qū)作為 Cargo 的RFC 1525一部分被添加到 Cargo 中，并具有許多屬性:

• 工作區(qū)可以包含多個(gè)箱，其中一個(gè)是根箱.
• 這個(gè)根箱的Cargo.toml包含[workspace]表格，但不要求必有其他配置.
• 每當(dāng)編譯工作區(qū)中的任何箱時(shí)，輸出被放置在工作區(qū)根。 即緊挨著根箱的Cargo.toml.
• 工作區(qū)中所有箱的那個(gè)鎖定文件駐留在工作區(qū)根.
• 在Cargo.toml的[patch]，[replace]和[profile.*]部分，只認(rèn)根箱的清單，而忽略成員箱的。

這個(gè)工作區(qū)的根箱，由其清單中存在的[workspace]指定，并負(fù)責(zé)定義整個(gè)工作區(qū)。所有駐留在工作區(qū)目錄中的path依賴項(xiàng)都變成成員。您可以通過members字段將附加包添加到工作區(qū)中。請注意，顯式列出的工作區(qū)成員，也在工作區(qū)中包含了它們的路徑依賴項(xiàng)。有時(shí)候，一個(gè)包可能有很多工作區(qū)成員，并且都保持最新會很麻煩。

路徑依賴也可以使用globs匹配多個(gè)路徑。 最后，exclude字段 可以用于將工作路徑中的路徑列入黑名單。如果根本不希望某些路徑依賴項(xiàng)存在于工作區(qū)中，那么這非常有用.

這個(gè)package.workspace清單字段(如上所述)用于成員箱中，以指向工作區(qū)的根箱。如果省略此字段，則推斷它是文件系統(tǒng)(向上的父目錄)中，清單包含[workspace]的第一個(gè)箱。

箱可以指定package.workspace或指定[workspace]。 也就是說，箱不能同時(shí)作為工作區(qū)中的根箱(包含[workspace])，和另一個(gè)工作區(qū)的成員箱(包含package.workspace)

大多數(shù)時(shí)間工作區(qū)都不需要處理。因cargo new和cargo init將自動(dòng)處理工作區(qū)配置。

Virtual Manifest

虛擬清單

在工作區(qū)清單中，如果package表格存在，則工作區(qū)根箱將被視為普通包和工作區(qū)。如果package表格不存在工作區(qū)清單中，那它被稱為虛擬清單。

Package selection

Package 部分

在工作區(qū)中，與包相關(guān)的 Cargo 命令，如cargo build，會應(yīng)用-p / --package或--all命令行參數(shù)選定的包。當(dāng)未指定時(shí)，可選default-members配置被使用:

[workspace]
members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
default-members = ["path/to/member2", "path/to/member3/foo"]

default-members指定時(shí)，必會擴(kuò)展到子集的members中.

若是default-members未指定，如果它是包，則默認(rèn)為根清單，或者若是虛擬工作區(qū)，就為每個(gè)成員的清單(如同--all在命令行上).

The project layout

項(xiàng)目布局

如果包是可執(zhí)行文件，則將主源文件命名為src/main.rs。 如果它是一個(gè)庫，請命名主源文件src/lib.rs。

Cargo 也將處理位于src/bin/*.rs任何文件作為可執(zhí)行文件。如果可執(zhí)行文件包含不止一個(gè)源文件，則可以使用src/bin目錄下，又一個(gè)包含main.rs文件的目錄，而該目錄將被視為具有父目錄名稱的可執(zhí)行文件。但是，一旦添加了[[bin]]部分見下文，Cargo 將不再自動(dòng)建立src/bin/*.rs文件。 相反，你必須創(chuàng)建一個(gè)[[bin]]部分，給出你想要生成的每個(gè)文件。

您的包可以(可選地)包含命名為examples，tests和benches文件夾，Cargo 將分別將其視為包含示例、集成測試和基準(zhǔn)。類似于bin目標(biāo)，它們可以由單個(gè)文件或擁有main.rs文件的目錄組成。

? src/           # 包含源文件的目錄
  lib.rs         # 庫和包的主要入口點(diǎn)
  main.rs        # 包生成可執(zhí)行文件的主要入口點(diǎn)
  ? bin/         # （可選）包含其他可執(zhí)行文件的目錄
    *.rs
  ? */           # （可選）包含多文件可執(zhí)行文件的目錄
    main.rs
? examples/      # （可選）示例
  *.rs
  ? */           # （可選）包含多文件示例的目錄
    main.rs
? tests/         # （可選）集成測試
  *.rs
  ? */           # （可選）包含多文件測試的目錄
    main.rs
? benches/       # （可選）基準(zhǔn)
  *.rs
  ? */           # （可選）包含多文件基準(zhǔn)的目錄
    main.rs

為了在創(chuàng)建文件和文件夾之后，為包構(gòu)造代碼，應(yīng)該記住使用 Rust 的模塊系統(tǒng)，您可以在這本書找到。

(譯)：中文

Examples

示例

位于examples下方的文件，是庫提供的功能示例用法。編譯時(shí)，它們被放置在target/examples目錄。

它們可以編譯為可執(zhí)行文件(用main()函數(shù))或，庫。和可通過使用extern crate <library-name>導(dǎo)入庫。 當(dāng)您運(yùn)行測試以保護(hù)它們免遭篡改時(shí)，它們會被編譯。

可以使用命令cargo run --example <example-name>運(yùn)行單個(gè)可執(zhí)行示例.

指定crate-type將示例編譯為庫(有關(guān)箱類型的附加信息可在Rust 參考找到):

[[example]]
name = "foo"
crate-type = ["staticlib"]

可以使用命令cargo build --example <example-name>構(gòu)建單個(gè)庫實(shí)例.

Tests

測試

當(dāng)你運(yùn)行cargo test，Cargo 會:

• 編譯并運(yùn)行庫的單元測試，這些測試位于lib.rs(當(dāng)然，任何標(biāo)記為#[cfg(test)]部分將考慮為同個(gè)階段);
• 編譯并運(yùn)行嵌入到文檔區(qū)塊內(nèi)部的庫的文檔測試;
• 編譯并運(yùn)行您庫的集成測試和
• 編譯你庫的例子.

Integration tests

集成測試

在tests/*.rs的每個(gè)文件是一個(gè)集成測試。當(dāng)你運(yùn)行cargo test，Cargo 將編譯每個(gè)文件作為一個(gè)單獨(dú)的箱子。箱可以通過使用extern crate <library-name>鏈接(導(dǎo)入)您的庫，就像其他導(dǎo)入項(xiàng)一樣。

Cargo 不會自動(dòng)編譯tests子目錄內(nèi)的文件，但是，集成測試可以像往常一樣從這些目錄導(dǎo)入模塊。例如，如果希望多個(gè)集成測試共享一些代碼，可以將共享代碼放入tests/common/mod.rs，然后為每個(gè)測試文件添加mod common;。

Configuring a target

配置為一個(gè)目標(biāo)

所有的[[bin]]，[lib]，[[bench]]，[[test]]和[[example]]部分都支持類似的配置，用于指定應(yīng)該如何構(gòu)建目標(biāo)。雙括號[[bin]]部分，是TOML格式的數(shù)組。這意味著你可以在您的箱中寫多個(gè)[[bin]]，這樣就會生成幾個(gè)可執(zhí)行文件。

下面的例子使用[lib]，但它也適用于所有其他部分。除非另有說明，下面所有列出的值都是對應(yīng)選項(xiàng)的默認(rèn)值。

[package]
# ...

[lib]
# 生成目標(biāo)與庫的名稱. 本該默認(rèn)是
# 包名, 替換所有破折號
# 為 下劃線. (Rust `extern crate` 聲明會參考該名;
# 因此，該值必須是可用的有效Rust標(biāo)識符.)
name = "foo"

# 該字段，指向 crate 的入口(位置), 路徑相對于 `Cargo.toml`.
path = "src/lib.rs"

# 一個(gè)給目標(biāo)啟用單元測試 的 標(biāo)志. 會被 `cargo test`使用.
test = true

# 一個(gè)給目標(biāo)啟用文檔測試 的 標(biāo)志. 只與庫相關(guān)
# , 不會影響其他部分。會被
# `cargo test`使用.
doctest = true

# 一個(gè)給目標(biāo)啟用基準(zhǔn) 的 標(biāo)志. 會被 `cargo bench`使用.
bench = true

# 一個(gè)給目標(biāo)啟用文檔 的 標(biāo)志. 會被 `cargo doc`使用.
doc = true

# 若該目標(biāo)為 編譯器擴(kuò)展, 那要把該字段設(shè)為 true
# ，以讓 Cargo 正確編譯和，可用于所有依賴項(xiàng).
plugin = false

# 若該目標(biāo)為 "macros 1.1" 程序宏, 那要把該字段設(shè)為 true
proc-macro = false

# 若設(shè)為 false, `cargo test` 會為 rustc 省略 `--test` 標(biāo)志, 這
# 阻止它生成測試工具 這在二進(jìn)制存在，
# 構(gòu)建管理測試運(yùn)行器本身的情況下，有用.
harness = true

# 若設(shè)置了，那 目標(biāo)會使用一個(gè)與`[package]`配置不同的版本
# , 也許是，編譯一個(gè)庫
2018年版本或，編譯單元測試的2015年版本. 默認(rèn)情況下
# 所有目標(biāo)都使用`[package]`中指定的版本進(jìn)行編譯。
edition = '2015'

這個(gè)[package]還包括可選的autobins,autoexamples,autotests和autobenches，來明確 進(jìn)入/退出 自動(dòng)發(fā)現(xiàn)特定的目標(biāo)種類。

The required-features field (optional)

required-features 字段 (可選)

這個(gè)required-features字段指定目標(biāo)需要構(gòu)建的特性。如果未選擇任何所需的特性，則將跳過目標(biāo)。這只與[[bin]]，[[bench]]，[[test]]和[[example]]部分有影響，它沒有影響[lib]。

[features]
# ...
postgres = []
sqlite = []
tools = []

[[bin]]
# ...
required-features = ["postgres", "tools"]

Building dynamic or static libraries

構(gòu)建 動(dòng)態(tài) 或 靜態(tài) 庫

如果您的包生成一個(gè)庫，則可以通過在Cargo.toml顯式地指明構(gòu)建的庫類型:

# ...

[lib]
name = "..."
crate-type = ["dylib"] # 也能是 `staticlib`

可用的選項(xiàng)是dylib，rlib，staticlib，cdylib和proc-macro。 您應(yīng)該只在包中使用一次此選項(xiàng)。Cargo 總是根據(jù)(包括的)包的要求來編譯包(依賴項(xiàng))。

您可以閱讀Rust 參考手冊中更多關(guān)于不同的箱類型

The [patch] Section

[patch] 部分

這部分可以用來重寫其他副本的依賴項(xiàng)。語法類似于[dependencies]部分:

[patch.crates-io]
foo = { git = 'https://github.com/example/foo' }
bar = { path = 'my/local/bar' }

[dependencies.baz]
git = 'https://github.com/example/baz'

[patch.'https://github.com/example/baz']
baz = { git = 'https://github.com/example/patched-baz', branch = 'my-branch' }

這個(gè)[patch]表格由，類似依賴表格的子表組成。[patch]后的每個(gè)字段是正在修補(bǔ)的源 URL，或者crates-io(如果你正在修改HTTPS://CRATESIO注冊表)。在上面的例子中，crates-io可以用 Git URL 替換，例如https://github.com/rust-lang-nursery/log；第二個(gè)示例中的[patch]部分使用此來指定一個(gè)名為baz的源。

這些表格中的每個(gè)項(xiàng)都是一個(gè)正常的依賴關(guān)系規(guī)范，與[dependencies]清單的部分一樣。[patch]部分中列出的依賴項(xiàng)，被解析并用于在指定的 URL 上對源進(jìn)行補(bǔ)丁。上面的清單片段補(bǔ)丁crates-io源(例如 crates.io 本身)的foo箱和bar箱。它也用一個(gè)來自其他地方的my-branch分支修補(bǔ)了https://github.com/example/baz源。

可以用不存在的箱版本來修補(bǔ)源，也可以用已經(jīng)存在的箱版本來修補(bǔ)源。如果用源中已經(jīng)存在的箱版本對源進(jìn)行修補(bǔ)，則會替換源的原始箱。

有關(guān)重寫依賴關(guān)系的更多信息，可閱讀本文檔的重寫依賴項(xiàng)章節(jié)和對于這一特性的RFC 1969技術(shù)規(guī)范說明。

The [replace] Section

[replace] 部分

這部分可以用來重寫其他副本的依賴項(xiàng)。語法類似于[dependencies]部分:

[replace]
"foo:0.1.0" = { git = 'https://github.com/example/foo' }
"bar:1.0.2" = { path = 'my/local/bar' }

[replace]表格的每個(gè)字段都是包標(biāo)識規(guī)范，它任意選擇依賴圖中的節(jié)點(diǎn)來重寫。每個(gè)字段值與`[dependencies]指定依賴關(guān)系的語法是一樣，除了不能指定特性。注意，當(dāng)覆蓋一個(gè)箱時(shí)，覆蓋它的副本必須具有相同的名稱和版本，但它可以來自不同的源(例如，git 或本地路徑).

有關(guān)重寫依賴關(guān)系的更多信息，可閱讀本文檔的重寫依賴項(xiàng)章節(jié)。