#cargo-toml #cargo #offline #cargo-check #failed #error #networking

app cargo-offline

cargo-offline是标准cargo命令的包装器。其被用来,根据距离cargo-offline命令执行目录最近的Cargo.toml文件是否曾经被修改,来给被包装的cargo命令聪明地添加--offline命令行参数(即,离线编译)。

7 releases

0.1.6 Nov 20, 2022
0.1.5 Nov 20, 2022

#334 in Cargo plugins

Apache-2.0

21KB
201 lines

cargo-offline命令

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

  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。所以,编译输出的二进制文件会更大那么一点点儿。
      • 编译指令·会额外地开启【不稳定featurefile_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]的同学,执行这条安装指令:

    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%\bin目录下
  • PATH环境变量划定的搜索范围,可见
  • 可从命令行直接运行

使用

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

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

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

    cargo offline check
    

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

源码也精彩,欢迎来品鉴

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

  1. 【条件编译】plus【策略·设计模式】 —— 解决Cargo.toml文件【修改时间】保存位置的选择问题。
    1. 【策略·模式】大约对等于OOP里的【控制反转IoCplus【依赖注入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. 以【宏】的思维来复用代码,得花费一段时间来适应。

关于·编译

重要,十分重要:因为【不稳定featurefile_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图形界面】,考虑到我的win32Gnome.GTK3编程经历与背景。

Dependencies

~4MB
~76K SLoC