`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工程，因为我已经配置好了：