cargo-offline命令

cargo-offline是标准cargo命令的包装器。其被用来，根据·距离cargo-offline命令执行目录最近的Cargo.toml文件是否被修改过，来给被包装的cargo命令条件地增补--offline命令行参数（即，离线编译）。形象地讲，就是将cargo check条件地变形为cargo check --offline。

动机

最近一段时间，github.com访问的稳定性实在很差。但，执行cargo命令总是要求

• 首先，同步crates.io-index索引清单。
• 然后，执行目标任务

于是，日常开发/编译工作流就时常被阻塞于

shell 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命令会

1. 透传所有命令行参数给底层的cargo指令
2. 寻找距离cargo-offline执行目录最近的Cargo.toml文件，无论该配置文件
   1. 是【工作区workspace】配置文件
   2. 还是【工作区·成员workspace.member】配置文件。
3. 比较被找到的Cargo.toml文件·是否·被修改过 —— 就是对比该文件的【最后·修改时间】属性值是否发生了变化。
4. 若Cargo.toml文件的·最后修改时间·变化了，就给被透传的参数列表额外添加--offline参数项。
5. 于是，cargo命令就会进入【离线模式】编译了。

Cargo.toml文件修改时间的保存位置

判断Cargo.toml文件·是否·被修改过，关键需要：

• 缓存·在上一次编译时·读取的Cargo.toml文件【修改时间】属性值
• 再，使用【缓存·时间值】与当前【文件修改时间】比大小

就将Cargo.toml文件【修改时间】保存于何处，cargo-offline程序提供了两套备选方案：

• 直接保存到Cargo.toml文件自身里，和作为*.metadata配置块内一个键值对。
  • 就【工作区】而言，保存配置块是[workspace.metadata]
  • 就【工作区·成员】和【普通工程】而言，保存配置块是[package.metadata]
  • 优点：
  • 不会在工程目录下引入新文件了。
  • 也不用修改.gitignore文件添加例外规则了。
  • 缺点：
  • 被toml crate编辑过的Cargo.toml文件，它内部
    • “配置块”会被重新排序
    • “双引号”会被替换为“单引号”。
  • 程序·会额外地依赖cargo_toml crate。所以，编译输出的二进制文件会更大那么一点点儿。
  • 编译指令·会额外地开启【不稳定feature】file_set_times
• 保存于独立的*.toml配置文件内。
  • 即，与Cargo.toml文件同目录的cargo-offline-config.toml文件。目前，此文件名是在代码内被硬编码的。
  • 优点：
  • Cargo.toml文件可保持“无损”。
  • 少一个程序依赖项
  • 避免开启【不稳定feature】
  • 缺点：
  • 需手工地向.gitignore文件添加cargo-offline-config.toml文件名。

值得一提的是，Cargo.toml文件【修改时间】保存位置的选择是【编译时·决策】，而不是【运行时·决策】。即，

• 以Cargo features作为编译条件
• 根据不同的决策选择
• 编译输出不一样的二进制行可执行文件作为结果。

安装

此命令行工具crate已经被发布至crates.io包仓库。所以，我就未对各主流平台与架构准备·预编译包（感谢伟大的包管理器！）。

• 选择缓存Cargo.toml文件【修改时间】至Cargo.toml [metadata]的同学，执行这条安装指令：

  shell cargo install cargo-offline --features=cargo-metadata

• 选择缓存Cargo.toml文件【修改时间】至cargo-offline-config.toml独立文件的同学，执行这条安装指令：

  shell cargo install cargo-offline --features=toml-config

因为我没有给Cargo Package设置default features，所以完全忽略--features=命令行参数会导致源码编译错误。恶作剧地，同时指定--features=cargo-metadata与--features=toml-config也会导致编译失败。

一旦被安装成功之后，cargo-offline.exe可执行文件就会

• 出现在%CARGO_HOME%\bin目录下
• 从PATH环境变量划定的搜索范围，可见
• 可从命令行直接运行

使用

cargo-offline命令的执行也有两种方式可供选择：

1. 作为独立命令，执行cargo-offline。后随和标准cargo命令相同的命令行参数（这些参数会被透传给cargo指令的）。比如，

   shell cargo-offline check

2. 作为cargo指令的子命令，执行cargo offline。比如，

   shell cargo offline check

cargo-offline的命令行参数与cargo完全相同，因为cargo-offline仅只做了透传处理。

源码也精彩，欢迎来品鉴

不是语句的堆叠，而是讲究了“套路”。被涉及到的【设计模式】包括但不限于：

1. 【条件编译】plus【策略·设计模式】 —— 解决Cargo.toml文件【修改时间】保存位置的选择问题。
   1. 【策略·模式】大约对等于OOP里的【控制反转IoC】plus【依赖注入DI】的组合。在我的代码，从IoC容器到DI注入项都是自写的。
   2. 欲深入了解【策略·模式】的细节理论，我推荐文章浅聊Rust【策略·设计模式】Strategy / Policy design pattern —— 欢迎点赞、发评论与转发分享。
2. Builder设计模式 —— 解决struct局部初始化的问题。
   1. 其大约对等于OOP里【工厂模式】。
   2. 但，亲手给每个struct编写Builder，那不是傻吗！多大的工作量呀！我的选择是derive_builder。
3. Option / Result枚举类的“拆/装箱”配合器【Combinator模式】 —— 避免丑陋且有panic风险的.unwrap()“拆箱”操作。
   1. 有那么一点儿ramda链式函数调用的感觉了。馁馁的【函数编程·范式】。
4. 规则宏macro-by-example —— 避免代码重复。
   1. 这是【结构相同·但·类型不同】代码块复用的利器呀！
   2. 以【宏】的思维来复用代码，得花费一段时间来适用。

关于·编译

重要，十分重要：因为【不稳定feature】file_set_times在程序中被条件地开启，所以该Cargo Package工程依赖的rustup工具链被鲜明地锁定于nightly版本。若你git clone此工程至本地，请先安装nightly版的rustc再编译执行之。否则，会报错的。

另外，推荐使用VSCode编辑与编译cargo-offline工程，因为我已经配置好了：

1. Ctrl + Shift + B直接·编译+执行。
2. 在安装了CodeLLDB插件之后，F5就先编译，再进入断点调试模式。

无论采用上面哪种方式编译程序，VSCode都会弹出【下拉·选择器】，要求选择输入【自定义cargo feature】。所以，请注意使用【上下箭头】与【回车】键，响应VSCode的选择要求。

后续路图

若今后给该·命令行工具·添加更多功能与配置选项，我计划上【GUI图形界面】，考虑到我的win32与Gnome.GTK3编程经历与背景。