Rust Cargo 使用總結

文檔列表見：Rust 移動端跨平臺複雜圖形渲染項目開發系列總結（目錄）

2019.4.24 更新：多條件(feature)編譯

Cargo用於組織Rust項目，比直接用rustc編譯多個源文件更方便。本文檔介紹咱們開發過程當中用到的Cargo功能與小技巧，更多信息可參考 The Cargo Book。

使用依賴項目的指定git commit

rev表示要用的git commit id，可簡寫成前7個字符，由於git commit id前7個字符可算出完整的41個SHA字符值。

[dependencies]
gfx-hal = { version = "0.1.0", git = "https://github.com/gfx-rs/gfx", rev = "bd7f058" }
# 或者寫成多行
[dependencies.gfx-hal]
git = "https://github.com/gfx-rs/gfx"
version = "0.1.0" 
rev = "bd7f058"
複製代碼

git倉庫地址須要支持https訪問，若是是http須要額外配置，比較麻煩。

引用本地Rust項目

[dependencies]
hello_utils = { path = "hello_utils", version = "0.1.0" }
複製代碼

path是相對於本項目Cargo.toml文件的被依賴項目的Cargo.toml的位置，填錯將找不到文件，且編譯報錯。詳細信息參考The Cargo Book/specifying-dependencies

workspace feature 條件編譯的執行路徑問題

當cargo workspace中存在多個project時，若是對某一project進行feature條件編譯或單元測試，必定要在此項目的Cargo.toml或src路徑中執行，不然Cargo會忽悠cargo test或cargo build --features=your_feature所指定的feature，這是個容易遇的坑。

default feature 條件編譯

[features]
default = ["gfx-backend-metal"]
複製代碼

寫在Cargo.toml的default = ["a", "b", "c"]對cargo build是默認啓用的，即不用加上--features條件。

多條件(feature)編譯

語法：--features "條件1 條件2 條件3"，每一個feature（條件）中間留出空格，示例：

cargo build --features "metal gl" --bin quad 表示啓用metal、gl兩個條件編譯去編譯quad可執行程序。

cargo c 減小編譯耗時

• 使用cargo check，命令可縮寫爲cargo c。若是隻是想驗證語法、類型檢查等，那麼能夠直接使用這個命令，它只會調用編譯器前端。比cargo build快2倍，比cargo build -—release快6倍。
• 使用sccache，該工具是Mozilla出品的Rust兼容的編譯緩存服務，通常能夠得到2倍速度提高。使用cargo install sccache安裝sccache，而且在.bashrc中添加環境變量export RUSTC_WRAPPER=sccache
• 避免LTO。 LTO是連接時優化的縮寫。LTO將付出更高的編譯時間代價。
• 控制crate依賴。

如何緩解Rust編譯時間長的痛苦

編譯優化級別說明

opt level 3和z，哪一個性能優化更高？答案：3。 z無論性能，z和s差很少，O2的優化，減小size。

另外一種說法：在不一樣平臺上會獲得不一樣結果，-z爲size優化，對於cpu code cache小的機器優點比較大，大概就是優化等級開高了代碼尺寸變大會致使在某些cache小的機器上性能降低的很厲害。z在inline的優化確定要少一些。優化這東西是個神坑，不要跳。建議在你的手機上進行profiling。

opt level 參數完整說明見 Properly document and explain opt-levels s and z

[profile.release] debug=true 的討論

這樣改會影響release的性能嗎？ 好像只是留下符號信息。編譯出來大點吧。性能應該不會有啥影響。你能夠試試 提及來release帶符號 會不會致使行號不許啊

To get the best data from a profiler, you need both optimizations (usually enabled only in release builds) and debug symbols (usually enabled only in debug builds). To enable both, add this to your Cargo.toml: Programming Rust

嘗試：

debug = false --release image-20190225103810132

debug = true --release image-20190225104833677

hal api基本沒改善，多是由於多數被inline或zero cost abstraction？

workspace 與其子 project 同時指定 [profile] 配置會引發衝突

package: /Users/michael/Documents/my_project/gles/Cargo.toml workspace: /Users/michael/Documents/my_project/Cargo.toml 同時指定

# The release profile, used for `cargo build --release`
[profile.release]
panic = "abort"
debug = true # `true` for better profiler readability with debug symbols, `false` for sdk client
lto = true
opt-level = 3
overflow-checks = false
複製代碼

warning: profiles for the non root package will be ignored, specify profiles at the workspace root:

測試Rust代碼中的Markdown代碼段

/// Open the physical device with `count` queues from some active queue family. The family is
/// the first that both provides the capability `C`, supports at least `count` queues, and for
/// which `selector` returns true.
///
/// # Examples
///
/// ```no_run
/// # extern crate gfx_backend_empty as empty;
/// # extern crate gfx_hal as hal;
/// use hal::General;
/// # fn main() {
///
/// # let mut adapter: hal::Adapter<empty::Backend> = return;
/// let (device, queues) = adapter.open_with::<_, General>(1, |_| true).unwrap();
/// # }
/// ```
///
/// # Return
///
/// Returns the same errors as `open` and `InitializationFailed` if no suitable
/// queue family could be found.
pub fn open_with<F, C>(
    &self,
    count: usize,
    selector: F,
) -> Result<(B::Device, QueueGroup<B, C>), DeviceCreationError>
where
    F: Fn(&B::QueueFamily) -> bool,
    C: Capability,
{
    // ...
}
複製代碼

註釋中的Examples代碼能夠用rust-skeptic進行測試，具體作法可閱讀rust-skeptic文檔。