`cargo-offline`命令

cargo-offline是標準cargo命令的包裝器。其被用來，根據·距離cargo-offline命令執行目錄最近的Cargo.toml文件是否被修改過，來給被包裝的cargo命令條件地增補--offline命令行參數（即，離線編譯）。形象地講，就是將cargo check條件地變形為cargo check --offline。

項目鏈接：https://github.com/stuartZhang/cargo-offline
包倉庫鏈接：https://crates.io/crates/cargo-offline
代碼也精彩，真不是簡單的代碼堆疊，而是有套路，和講套路的。
1. 先點個star
2. 再直接導航至：https://github1s.com/stuartZhang/cargo-offline

動機

最近一段時間，github.com訪問的穩定性實在很差。但，執行cargo命令總是要求

首先，同步crates.io-index索引清單。
然后，執行目標任務

于是，日常開發/編譯工作流就時常被阻塞于

warning: spurious network error (1 tries remaining): [35] SSL connect error (schannel: failed to receive handshake, SSL/TLS connection failed); class=Net (12) Caused by: Unable to update registry `crates-io` Caused by: failed to fetch `https://github.com/rust-lang/crates.io-index` Caused by: [35] SSL connect error (schannel: failed to receive handshake, SSL/TLS connection failed); class=Net (12)

的網絡錯誤上。這實在令人感覺挫敗！

另一方面，雖然“搬梯子”能夠緩解問題，但面對頻繁的cargo check/run指令執行（特別是，莫名其妙出現的“全量索引同步”現象），其“按流量·計費”的經濟成本著實令人肉疼。

所以，我下定決心在業余時間搞一個【條件·離線·編譯】的命令行工具，來拯救自己于迷茫。

最理想的使用模型

僅首次編譯·或·在依賴項變更時，cargo命令才【連線】編譯與同步本地的crates.io-index索引清單 —— 有限且可控的“搬梯子”還是可以經濟承受的。
在所有其它時候，cargo命令皆【離線】編譯 —— 沒事少連線github.com。

工作原理

cargo-offline命令會

透傳所有命令行參數給底層的cargo指令
尋找距離cargo-offline執行目錄最近的Cargo.toml文件，無論該配置文件
1. 是【工作區workspace】配置文件
2. 還是【工作區·成員workspace.member】配置文件。
比較被找到的Cargo.toml文件·是否·被修改過 —— 就是對比該文件的【最后·修改時間】屬性值是否發生了變化。
若Cargo.toml文件的·最后修改時間·變化了，就給被透傳的參數列表額外添加--offline參數項。
于是，cargo命令就會進入【離線模式】編譯了。

`Cargo.toml`文件修改時間的保存位置

判斷Cargo.toml文件·是否·被修改過，關鍵需要：

緩存·在上一次編譯時·讀取的Cargo.toml文件【修改時間】屬性值
再，使用【緩存·時間值】與當前【文件修改時間】比大小

就將Cargo.toml文件【修改時間】保存于何處，cargo-offline程序提供了兩套備選方案：

直接保存到Cargo.toml文件自身里，和作為***.metadata配置塊內一個鍵值對。
- 被toml crate編輯過的Cargo.toml文件，它內部
- 程序·會額外地依賴cargo_toml crate。所以，編譯輸出的二進制文件會更大那么一點點兒。
- 編譯指令·會額外地開啟【不穩定feature】file_set_times
- “配置塊”會被重新排序
- “雙引號”會被替換為“單引號”。
- 不會在工程目錄下引入新文件了。
- 也不用修改.gitignore文件添加例外規則了。
- 就【工作區】而言，保存配置塊是[workspace.metadata]
- 就【工作區·成員】和【普通工程】而言，保存配置塊是[package.metadata]
- 優點：
- 缺點：
保存于獨立的*.toml配置文件內。
- 需手工地向.gitignore文件添加cargo-offline-config.toml文件名。
- Cargo.toml文件可保持“無損”。
- 少一個程序依賴項
- 避免開啟【不穩定feature】
- 即，與Cargo.toml文件同目錄的cargo-offline-config.toml文件。目前，此文件名是在代碼內被硬編碼的。
- 優點：
- 缺點：

值得一提的是，**Cargo.toml文件【修改時間】保存位置的選擇是【編譯時·決策】，而不是【運行時·決策】。**即，

以Cargo features作為編譯條件
根據不同的決策選擇
編譯輸出不一樣的二進制行可執行文件作為結果。

安裝

此命令行工具crate已經被發布至crates.io包倉庫。所以，我就未對各主流平臺與架構準備·預編譯包（感謝偉大的包管理器！）。

選擇緩存Cargo.toml文件【修改時間】至Cargo.toml [metadata]的同學，執行這條安裝指令：
cargo install cargo-offline --features=cargo-metadata
選擇緩存Cargo.toml文件【修改時間】至cargo-offline-config.toml獨立文件的同學，執行這條安裝指令：
cargo install cargo-offline --features=toml-config

因為我沒有給Cargo Package設置default features，所以完全忽略--features=命令行參數會導致源碼編譯錯誤。惡作劇地，同時指定--features=cargo-metadata與--features=toml-config也會導致編譯失敗。

一旦被安裝成功之后，cargo-offline.exe可執行文件就會

出現在%CARGO_HOME%in目錄下
從PATH環境變量劃定的搜索范圍，可見
可從命令行直接運行

使用

cargo-offline命令的執行也有兩種方式可供選擇：

作為獨立命令，執行cargo-offline。后隨和標準cargo命令相同的命令行參數（這些參數會被透傳給cargo指令的）。比如，
cargo-offline check
作為cargo指令的子命令，執行cargo offline。比如，
cargo offline check

cargo-offline的命令行參數與cargo完全相同，因為cargo-offline僅只做了透傳處理。

源碼也精彩，歡迎來品鑒

不是語句的堆疊，而是講究了“套路”。被涉及到的【設計模式】包括但不限于：

【條件編譯】plus【策略·設計模式】 —— 解決Cargo.toml文件【修改時間】保存位置的選擇問題。
1. 【策略·模式】大約對等于OOP里的【控制反轉IoC】plus【依賴注入DI】的組合。在我的代碼，從IoC容器到DI注入項都是自寫的。
2. 欲深入了解【策略·模式】的細節理論，我推薦文章淺聊Rust【策略·設計模式】Strategy / Policy design pattern —— 歡迎點贊、發評論與轉發分享。
Builder設計模式 —— 解決struct局部初始化的問題。
1. 其大約對等于OOP里【工廠模式】。
2. 但，親手給每個struct編寫Builder，那不是傻嗎！多大的工作量呀！我的選擇是derive_builder。
Option / Result枚舉類的“拆/裝箱”配合器【Combinator模式】 —— 避免丑陋且有panic風險的.unwrap()“拆箱”操作。
1. 有那么一點兒ramda鏈式函數調用的感覺了。餒餒的【函數編程·范式】。
規則宏macro-by-example—— 避免代碼重復。
1. 這是【結構相同·但·類型不同】代碼塊復用的利器呀！
2. 以【宏】的思維來復用代碼，得花費一段時間來適應。

關于·編譯

重要，十分重要：因為【不穩定feature】file_set_times在程序中被條件地開啟，所以該Cargo Package工程依賴的rustup工具鏈被鮮明地鎖定于nightly版本。若你git clone此工程至本地，請先安裝nightly版的rustc再編譯執行之。否則，會報錯的。

另外，推薦使用VSCode編輯與編譯cargo-offline工程，因為我已經配置好了：