Hyperfine 版本演进全解析：从 v0.2.0 到 v1.20.0 的核心功能、CLI 选项与源码实现

Hyperfine 版本演进全解析：从 v0.2.0 到 v1.20.0 的核心功能、CLI 选项与源码实现

【免费下载链接】hyperfineA command-line benchmarking tool项目地址: https://gitcode.com/gh_mirrors/hy/hyperfine

本篇技术指南以 hyperfine 官方 CHANGELOG.md 为骨架，系统梳理该命令行基准测试工具从 v0.2.0 初始发布到 v1.20.0 的完整功能演进脉络：参数化基准、运行次数控制、Shell 与输出管理、相对速度比较、多格式导出以及 Python 可视化脚本生态。读完本文，你将能对照仓库源码（src/与scripts/）理解每个关键选项的底层实现原理，并直接照抄文中命令开展实战基准测试。

一、版本演进主线：从“单命令计时”到“多命令对比”到“参数化扫描”

hyperfine 的演进可划分为三个里程碑阶段，CHANGELOG 完整记录了这条主线：

• 基础能力期（v0.2.0 ~ v0.5.0）：v0.2.0 为初始公开发布；v0.3.0 在 wall clock（真实/挂钟）时间之外引入 user 与 system 时间测量（src/timer/mod.rs中的CPUTimes结构体），并新增--prepare；v0.4.0 加入统计离群点检测（src/outlier_detection.rs）与--style输出风格控制；v0.5.0 提供完整的 Windows 支持，并新增--style auto/basic/nocolor/full细分模式。
• 功能成型期（v1.0.0 ~ v1.6.0）：v1.0.0 一次性落地 CSV/JSON/Markdown 三种导出格式、多基准汇总对比（Summary）与-P/--parameter-scan参数化扫描；此后逐步加入-S/--shell、-u/--time-unit、--show-output、-D/--parameter-step-size（含小数步长）、-c/--cleanup、AsciiDoc 导出，并让参数值与中位数进入 CSV/JSON 导出。
• 精细化与生态期（v1.7.0 ~ v1.20.0）：引入-L/--parameter-list及其多重组合、--sort、--output、--input、--conclude、--reference/--reference-name、--shell=none、--time-unit microsecond等，同时补齐 shell 补全、man page、Python 可视化脚本族与多平台打包。

二、运行次数与耗时预算控制

hyperfine 默认在每次基准中自动决定运行次数。相关约束在src/options.rs的RunBounds中定义：默认min = 10、max = None（即至少 10 次、无上限），且默认最小基准时间为 3.0 秒（min_benchmarking_time字段）。

CHANGELOG 中与运行次数直接相关的演进：

版本	能力
v1.3.0	新增指定最大/精确运行次数的选项（--max-runs/--runs，见 CLI 定义）
v1.12.0	将 shell 启动时间测量次数从 200 次降至 50 次，显著加速整体基准流程；--warmup与--*runs参数解析失败时给出明确错误（v1.11.0）
v1.15.0	新增实验性--min-benchmarking-time <secs>选项（源码中该选项被隐藏，见 cli.rs 注释）

实际用法：

# 精确运行 20 次 hyperfine --runs 20 'sleep 0.3' # 至少 5 次、至多 100 次，并预热 3 次 hyperfine --min-runs 5 --max-runs 100 --warmup 3 'sleep 0.3' # 控制最小基准时长（秒） hyperfine --min-benchmarking-time 10 'sleep 0.3'

从源码看，--runs会同时把min_runs与max_runs设为同一值（options.rs 的解析分支），而--min-runs > --max-runs会直接报错EmptyRunsRange。

三、计时精度：时间单位与 user/system 时间

-u/--time-unit（v1.4.0 引入，v1.18.0 新增microsecond）控制结果显示单位，可选microsecond、millisecond、second，不指定时自动选择；该选项同时作用于标准输出与除 CSV/JSON 之外的所有导出格式（cli.rs 中--time-unit的帮助文本明确说明）。v1.4.0 还让 Markdown 导出自动选择时间单位。

时间测量本身的演进：

• v0.3.0：除 wall clock 外新增 user/system 时间；
• v1.12.0：user 与 system 时间统一到一致的时间单位（修复 #408）；
• v1.15.0：修复 Windows 上 user/kernel 时间不准确的问题（#368）。

在src/timer/mod.rs中，TimerResult同时携带time_real、time_user、time_system与memory_usage_byte；Unix 平台使用unix_timer.rs的CPUTimer，Windows 平台则以CREATE_SUSPENDED创建挂起进程后再启动 CPU 计时，避免漏记进程创建到计时器启动之间的 CPU 时间。

四、命令准备、结论与清理：prepare / setup / conclude / cleanup

CHANGELOG 记录了四个“生命周期钩子”的逐步完善：

• --prepare（v0.3.0 引入）：每次计时运行前执行，典型用途是清空磁盘缓存；v1.2.0 起支持在准备命令中使用参数占位符；v1.8.0 起可多次指定，为每个被测命令绑定各自的准备命令；v1.9.0 起准备命令也会在 warmup 阶段执行。
• --setup（v1.13.0，短选项-s）：每组计时运行之前执行一次（如make all），语义上与--cleanup对应；注意 v1.13.0 是破坏性变更——-s从--style改给了--setup。
• --conclude（v1.19.0）：每次计时运行之后执行，适合杀掉--prepare启动的长驻进程（如 Web 服务器）；同样可指定一次或与命令数等量的多次。
• --cleanup（v1.6.0，短选项-c）：某个命令全部计时运行结束后执行，用于清理被测程序产生的工件。

多准备命令示例（来自 CHANGELOG v1.8.0）：

hyperfine --prepare "make clean; git checkout master" "make" \ --prepare "make clean; git checkout feature" "make"

选项校验逻辑位于options.rs的validate_against_command_list：--prepare/--conclude要么只提供一次（作用于全部命令），要么恰好提供 N 次（N 为命令总数，含可能的参考命令）。

五、参数化基准：parameter-scan / parameter-list / 多参数组合

参数化是 hyperfine 最具标志性的能力，其实现集中在src/command.rs与src/parameter/目录。

5.1-P/--parameter-scan（v1.0.0）与-D/--parameter-step-size（v1.7.0）

按MIN..MAX等差数列展开，替换命令中的{VAR}占位符。v1.7.0 起支持小数参数与自定义步长：

# 执行 sleep 0.3、sleep 0.5、sleep 0.7 hyperfine --parameter-scan delay 0.3 0.7 -D 0.2 'sleep {delay}'

从源码看（command.rs 的get_parameter_scan_commands），整数参数优先按i32解析；若无法解析为整数，则尝试按rust_decimal::Decimal解析——此时必须显式给出步长（否则报StepRequired），小数展开由range_step.rs的RangeStep迭代器实现。

占位符替换还支持“非重叠”语义：replace_parameters_in逐字符扫描并优先匹配最长参数名，避免{foo}与{bar}值互相二次替换（对应测试test_get_command_line_nonoverlapping）。

5.2-L/--parameter-list（v1.9.0）与多重组合（v1.11.0）

v1.9.0 引入非数值参数列表；v1.11.0 起可多次指定-L，对所有参数取值做笛卡尔积：

hyperfine -L number 1,2 -L letter a,b,c \ "echo {number}{letter}" \ "printf '%s\n' {number}{letter}" # 共 12 组：2 条命令 × 6 种参数组合

对应的test_build_commands_cross_product测试（command.rs）验证了展开顺序：先命令列表、后各参数（按命令行出现顺序）。若参数名重复，find_duplicates会直接报Duplicate parameter names。

5.3 命令命名与未使用参数显示

• --command-name（v1.11.0 引入；v1.12.0 起可引用--parameter-*的参数名，如-n name-{val}）；
• v1.17.0 起，未在命令行模板中使用的参数会以括号形式显示（command_with_unused_parameters字段，见 command.rs 的get_name_with_unused_parameters）；
• v1.20.0 修复了参数扫描时为单个命令命名不生效的 bug（#794）。

hyperfine -L compiler "gcc,clang" "{compiler} -O2 main.cpp" \ --command-name "compile-{compiler}"

六、相对速度比较：reference / reference-name / sort

从 v1.0.0 的 Summary 汇总对比开始，相对速度比较持续增强：

• v1.3.0：计算并打印速度比值的标准差（± x.xx），依据误差传播公式（见 relative_speed.rs 源码注释，引用 Wikipedia 的 uncertainty propagation，协方差按 0 处理）；
• v1.19.0：新增--reference <cmd>，显式指定相对比较的参考命令（默认以最快命令为参考）；
• v1.20.0：新增--reference-name，为参考命令指定有意义的名字；
• v1.17.0：新增--sort {auto,command,mean-time}，控制相对速度比较的排序（默认按平均时间）以及 Markdown/AsciiDoc/org-mode 导出表格的排序（默认按命令行输入顺序）。

hyperfine --reference 'sha256sum file.img' 'md5sum file.img' \ --reference-name 'sha256' 'md5sum file.img' # 指定排序方式 hyperfine 'sleep 0.3' 'sleep 0.2' --sort mean-time

调度器实现见scheduler.rs：有参考命令时其结果排在最前并被标记为is_reference，Summary 输出“X ran / Y times slower (faster) than Z”格式；若某些基准时间为零导致无法计算比值，会提示可能是校准阶段受后台干扰，并建议使用--shell=none/-N（对应 v1.11.0 对快速命令的更好错误提示）。

七、Shell 与执行器：--shell / --shell=none / Windows 处理

• -S/--shell（v1.4.0）：覆盖默认 shell（Unix 为sh，Windows 为cmd.exe，见 options.rs 的DEFAULT_SHELL），支持完整命令行如"bash --norc"，也支持default（显式选默认 shell）与none（禁用 shell）；
• -N/--shell=none（v1.13.0）：直接执行命令而不经中间 shell，适合毫秒级快速命令。hyperfine 默认会测量并扣除 shell 启动时间，但中间 shell 始终引入测量噪声；禁用后命令仍可带参数，但无法使用sleep 0.1; sleep 0.2这类 shell 语法；
• Windows 参数引用：v1.16.0 修复了 Windows CMD 下cmd.exe /C的参数引用问题；executor.rs 中明确：仅当为默认cmd.exe时使用/C，其余 shell 一律使用-c（对应 v1.16.0 的 #568/#582）。

执行器体系在executor.rs中分为三类：ShellExecutor（默认，calibrate()以 50 次空 shell 启动测量平均启动时间并逐次扣除，对应 v1.12.0 的 200→50 优化）、RawExecutor（--shell=none，零开销）、MockExecutor（--debug-mode，仅用于测试，从sleep <time>解析假时间）。

八、输出、输入与失败处理

8.1 输出重定向--output（v1.14.0）

--output={null,pipe,inherit,<FILE>}控制被测程序 stdout/stderr 的去向：null重定向到/dev/null（默认）、pipe先经管道再丢弃（避免grep等程序感知/dev/null后启用优化）、inherit原样显示（等价于--show-output）、<FILE>写入指定文件。v1.19.0 起该选项可为每个命令分别指定一次（如--output=null my-cmd --output=./file.log my-cmd），校验逻辑同--prepare。相关枚举CommandOutputPolicy见 options.rs。

8.2 输入来源--input（v1.16.0）

--input=null（默认，读/dev/null）或--input=<FILE>（从文件读入 stdin）。options.rs 中若指定不存在的文件会直接报StdinDataFileDoesNotExist。v1.16.1 修复了--input=null的回归问题。

8.3 失败处理--ignore-failure（v1.20.0 增强）

• v1.12.0：命令失败时打印退出码（或被信号终止），并将退出码纳入 JSON 导出；
• v1.20.0：--ignore-failure除all-non-zero（或空值）外，支持逗号分隔的退出码列表，如--ignore-failure=1,2。

解析逻辑见 options.rs 的CmdFailureAction：IgnoreSpecificFailures(Vec<i32>)仅在退出码不在列表中时才判定失败；错误消息会标注失败发生在“warmup iteration i”还是“benchmark iteration i”（v1.19.0），并提示用-i或--show-output排查。

8.4 迭代号环境变量HYPERFINE_ITERATION（v1.19.0）

每次运行的迭代号会通过环境变量注入被测命令：warmup 阶段为warmup-i，正式阶段为数字（见 executor.rs 的BenchmarkIteration::to_env_var_value），可配合 shell 重定向按迭代存档输出：

hyperfine 'my-command > output-${HYPERFINE_ITERATION}.log'

8.5 输出风格--style与 NO_COLOR

• v0.4.0 引入--style禁用彩色与交互元素；v0.5.0 细分auto/basic/nocolor/full；v1.3.0 新增--style=color（保留颜色、去掉进度条等交互元素）；v1.9.0 新增--style=none完全静默；
• v1.15.0：TERM=dumb或NO_COLOR=1时自动禁用彩色输出；v1.16.0 修复 Windows 上未设置TERM时输出无彩色的问题；v1.12.0 起 Windows 默认启用彩色输出。

自动模式判定逻辑见 options.rs：stdout 非终端或使用inherit输出时回退basic，检测到TERM为unknown/dumb或NO_COLOR非空则回退nocolor。

九、导出格式演进：CSV / JSON / Markdown / AsciiDoc / org-mode

导出体系在src/export/中实现，ExportManager（mod.rs）统一管理多个导出器。演进时间线：

• v1.0.0：CSV、JSON、Markdown 三种格式；
• v1.5.0：显示运行次数（输出中标注 runs）；
• v1.6.0：新增 AsciiDoc 导出；参数值（--parameter-scan）写入 CSV/JSON；Markdown 导出包含相对速度；CSV/JSON 增加中位数；
• v1.8.0：Markdown 相对速度精度提升并附带标准差；
• v1.11.0：JSON 中参数由单键parameter改为字典parameters（多参数组合所需）；
• v1.12.0：退出码进入 JSON 导出；导出文件在基准执行前即创建（权限问题提前失败），且每完成一个命令就增量写入结果（而非全部结束后再写），避免后续基准失败导致数据丢失（mod.rs 的write_results(intermediate=true)逻辑）；
• v1.14.0：新增 Emacs org-mode 导出；
• v1.16.0：--export-*的文件名可写-表示输出到 stdout；v1.17.0 修复使用-时中间结果误入 stdout 的问题，并修复基准结果为零时 markup 导出失败的问题。

JSON 导出的字段集合定义于 benchmark_result.rs：command、mean、stddev、median、user、system、min、max、times（逐次运行值）、memory_usage_byte、exit_codes、parameters。CSV/JSON 的时间单位恒为秒；Markdown/AsciiDoc/org-mode 受--time-unit影响。

hyperfine 'sleep 0.020' 'sleep 0.021' --export-json result.json \ --export-markdown result.md --export-orgmode result.org

十、Python 可视化与分析脚本生态

自 v1.5.0 起 hyperfine 提供了配套 Python 脚本（仓库scripts/目录），配合--export-json使用：

hyperfine 'sleep 0.020' 'sleep 0.021' 'sleep 0.022' --export-json sleep.json ./scripts/plot_whisker.py sleep.json

依赖numpy、matplotlib、scipy（支持uv run直接执行，见 scripts/README.md）。各脚本的演进：

脚本	引入/增强版本	用途
plot_whisker.py	v1.10.0 更新、v1.19.0 更美观的须状图	盒须图对比各命令的时间分布
plot_histogram.py	v1.10.0 增强、v1.17.0 新增--log-count	单命令时间分布直方图
plot_parametrized.py	v1.5.0 起；v1.11.0 自动推断参数名（--parameter-name废弃）	参数化基准结果绘图
advanced_statistics.py	v1.10.0 增强；v1.20.0 新增--time-unit	进阶统计输出
welch_ttest.py	v1.8.0	Welch t 检验，判断两组基准结果是否有显著差异
plot_progression.py	v1.13.0	排查后台干扰（绘制时间序列）
plot_benchmarks.py	v1.20.0	批量绘制多个基准结果集合（#806）
plot_benchmark_comparison.py	现存于仓库	基准对比绘图

v1.19.0 还允许调整图例参数与输出 DPI。

十一、环境与平台支持演进

• 环境变量：v1.10.0 起基准执行时会注入HYPERFINE_RANDOMIZED_ENVIRONMENT_OFFSET以随机化内存布局（实现见src/util/randomized_environment_offset.rs与 executor.rs 的注入点），v1.13.0 起 Windows 同样可用；
• Shell 补全与文档：v1.10.0 提供 Bash/Zsh/Fish/PowerShell 补全文件与基础 man page（doc/hyperfine.1），v1.17.0 大幅更新 man page，v1.19.0 修复 zsh 补全；
• Windows 演进：v0.5.0 完整支持；v1.3.0 将解释器固定为cmd.exe（避免误调同名程序）；v1.3.0/v1.12.0/v1.15.0/v1.16.0 修复颜色、计时与TERM问题；v1.18.0 修复 CMD 参数引用；v1.17.0 从winapi迁移到windows-sys；v1.19.0 提供aarch64-apple-darwin二进制；
• 打包分发：CHANGELOG 记录了 Arch/AUR、Ubuntu/Debian、Fedora、Alpine、NixOS、FreeBSD、OpenBSD、MacPorts、Snapcraft 及 Windows 二进制等渠道（v0.3.0 ~ v1.9.0 各版本）；v1.7.0 起启用 LTO 以缩减二进制体积。

十二、结语：读懂 CHANGELOG，用好 hyperfine

纵览 v0.2.0 到 v1.20.0，hyperfine 的每一次版本迭代都围绕三个核心诉求展开：更精准的测量（shell 时间扣除、CPU 时间、微秒单位、离群点检测）、更丰富的基准形态（多命令对比、参数扫描/列表/组合、参考命令、生命周期钩子）与更完善的结果消费链路（五种导出格式、退出码与参数元数据、Python 可视化与分析脚本）。当你在实际项目中遇到“结果波动如何排查”“毫秒级命令如何测准”“多版本参数矩阵如何呈现”等问题时，本文梳理的选项与源码路径（src/cli.rs、src/options.rs、src/command.rs、src/benchmark/、src/export/、scripts/）即可作为直接的技术地图。

【免费下载链接】hyperfineA command-line benchmarking tool项目地址: https://gitcode.com/gh_mirrors/hy/hyperfine