Rofi 调试实战指南:崩溃、卡顿与配置问题的系统化排查手册
Rofi 调试实战指南:崩溃、卡顿与配置问题的系统化排查手册
本文是 rofi 官方调试手册(rofi-debugging(5),仓库中对应 mkdocs/docs/1.7.5/rofi-debugging.5.markdown)的完整解读与源码级扩展。作为窗口切换器、应用启动器和 dmenu 替代品,rofi 崩溃或行为异常时往往难以直接定位根因。读完本文,你将掌握一套从“最小化复现环境”到“收集 issue 关键信息”,再到“时序追踪、分域调试、崩溃回溯生成”的完整排查链路,能够独立产出高质量的 bug 报告,也能自己定位启动缓慢、主题解析失败等问题。
排查的第一步:剥离个性化配置,进入 stock 模式
rofi 的行为同时受配置文件、命令行参数、主题文件(rasi)、插件和脚本模式(script mode)等多层因素影响。当 rofi 崩溃或行为异常时,首先要做的是排除“用户自定义配置”这一变量。
-no-config:跳过所有配置文件的解析,使用内置默认值运行 rofi,即官方所说的 stock 模式。在 source/rofi.c 中可以确认,该参数不仅影响配置加载,还会直接作用于-help输出——当传入-no-config时,帮助信息中的 “Configuration file” 一栏会显示Disabled。-no-plugins:禁用外部 C 插件(通过 GModule 动态加载的 mode 插件)的加载。对应实现位于 source/rofi.c:传入该参数后,rofi_collectmodes_dir(config.plugin_path)与ROFI_PLUGIN_PATH环境变量指定的插件目录都将被跳过,只保留内置的 run、ssh、drun、combi、help-keys、file-browser、recursive-browser 等模式。
建议的排查顺序:先用
rofi -no-config复现;若仍异常,再加-no-plugins复现;两者都加后问题消失,则基本可以确定问题出在你的配置文件、主题或插件上,而不是 rofi 核心逻辑。
为 issue 收集关键信息:三个必跑命令
向维护者报告问题前,请先执行以下三个命令并粘贴输出:
rofi -help
rofi -dump-config
rofi -dump-theme
rofi -help 的价值:它输出的不仅是参数列表,还包含一组环境快照。从 source/rofi.c 可以看到,它会打印精确的版本号(含 git 版本)、bug 报告地址、当前解析到的配置文件路径、已解析的主题文件、XDG 数据目录(XDG_DATA_HOME、XDG_CONFIG_HOME、XDG_CACHE_HOME、Desktop、pictures 等用户目录以及系统级 XDG_DATA_DIRS)、显示器/后端布局(xcb / wayland 当前选中状态)以及可用模式列表(内置模式与 (external) 插件模式会分别标注)。这些信息对复现环境还原至关重要。
rofi -dump-config 的价值:它把 rofi 当前生效的完整配置以 rasi 格式输出到 stdout。这给出的是 rofi 对配置的“最终解释”——不是配置文件的原文,而是解析合并后的结果,便于确认某个选项是否真的按预期生效。实现入口在 source/rofi.c,实际由 source/xrmoptions.c 的 config_parse_dump_config_rasi_format 完成输出。
rofi -dump-theme 的价值:同理,它把当前合并后的主题树以 rasi 格式完整打印(见 source/theme.c 的 rofi_theme_print,输出头部会注明 “rofi -dump-theme output.” 与 rofi 版本号)。当主题渲染异常(颜色、边框、间距不对)时,这份输出能直接暴露是哪个 widget 的属性被覆盖或写错。
注意隐私:上述输出可能包含用户名、home 路径、环境变量等可识别信息,粘贴到 issue 前请先检查并脱敏。
时序追踪(Timing Traces):定位启动慢的根因
如果 rofi 启动缓慢,可以利用内置的 Timings 调试域拿到一份带耗时统计的执行轨迹:
G_MESSAGES_DEBUG=Timings rofi -show drun
每条轨迹包含两类时间信息:累计时间(自 rofi 启动以来的总耗时)和本段增量时间(距上一条记录的时间差),并标注了 文件:函数:行号 与阶段说明。例如从文档中的示例可以读出:启动第 0.000126s 进入 main,0.001235s 完成 MODI(模式)收集,0.015349s 完成线程池初始化(source/view.c 的 rofi_view_workers_initialize),0.082884s 完成桌面应用(drun 模式)的系统目录扫描,0.085992s 完成首轮过滤(rofi_view_refilter)。若某个阶段的增量时间异常偏大,瓶颈就在那里。
底层实现见 source/timings.c:rofi_timings_init 创建 GTimer 并输出 Started 标记,rofi_timings_tick 记录当前累计值与相对上一 tick 的差值,rofi_timings_quit 输出 Stopped 标记。它依赖 glib 的 g_debug 宏,因此日志域名为 Timings,日志前缀格式为 (进程号): Timings-DEBUG: 时刻: 累计(增量): 文件:函数:行号 说明。
分域调试:G_MESSAGES_DEBUG 与调试域清单
rofi 的各功能模块通过 glib 调试框架(G_MESSAGES_DEBUG 环境变量)提供细粒度的调试输出。启用方式:
# 只输出 Desktop 文件启动器(drun 模式)的调试信息
G_MESSAGES_DEBUG=Modes.DRun rofi -show drun
# 输出所有域
G_MESSAGES_DEBUG=all rofi -show drun
# 同时开启多个域(冒号分隔)
G_MESSAGES_DEBUG=Modes.DRun:Theme rofi -show drun
文档编写时存在的调试域(与源码中 各文件的 #define G_LOG_DOMAIN 一一对应)如下:
| 调试域 | 覆盖范围 |
|---|---|
all |
所有域的调试信息 |
X11Helper |
X11 辅助函数 |
View |
主窗口视图函数 |
Rofi |
主应用逻辑(定义于 source/rofi.c) |
Timings |
时序追踪输出(定义于 source/timings.c) |
Theme |
主题引擎调试输出(警告:输出量非常大) |
Modes.DMenu |
dmenu 模式 |
Modes.Run |
run 模式 |
Modes.DRun |
桌面文件(.desktop)运行模式 |
Modes.Window |
窗口模式(wayland 与 xcb 后端共用) |
Modes.Script |
脚本模式 |
Modes.Combi |
combi(组合)模式 |
Modes.Ssh |
ssh 模式 |
Modes.RecursiveBrowser |
递归文件浏览模式 |
Widgets.Box |
Box 部件 |
Widgets.Icon |
Icon 部件 |
Widgets.Container |
Container 部件 |
Widgets.Window |
Window 部件 |
Helpers.IconFetcher |
图标查找信息 |
将日志重定向到文件:当 rofi 由窗口管理器或合成器拉起、stdout 不可见时,可用 -log 参数把全部日志写入文件:
rofi -show drun -log ~/rofi.log
指定日志文件会自动启用所有日志域。该选项在 source/rofi.c 中实现:以 O_CLOEXEC | O_APPEND | O_CREAT | O_WRONLY 方式打开指定文件,若打开失败会以 g_error 直接报错退出。
生成崩溃回溯(Backtrace):绕过键盘抓取困境
rofi 在运行时会抓取键盘和鼠标(源码中可见 Grab keyboard 阶段)。这意味着如果在 GDB 中直接运行 rofi 并使其崩溃/卡死,你会被困在 GDB 里无法操作,因此不推荐直接在 GDB 内运行 rofi。
推荐路径是启用 core dump,崩溃后用 GDB 分析 core 文件:
-
编译带调试符号的 rofi(确保符号信息完整、优化关闭):
make CFLAGS="-O0 -g3" clean rofi -
允许生成 core 文件并复现崩溃:
ulimit -c unlimited rofi -show drun # 触发崩溃,生成 core 文件 -
在 GDB 中加载 core 并打印所有线程的调用栈:
gdb rofi corethread apply all btthread apply all bt会打印所有线程的完整回溯,配合调试符号可以看到具体的函数调用链与行号,这是报告崩溃问题最核心的材料。 -
使用 systemd-coredump 的发行版:可以更方便地通过
coredumpctl获取回溯,无需手工管理 core 文件路径。
一个可复制的完整排查流程
综合以上工具,一套标准化的 rofi 问题排查流程如下:
rofi -no-config -no-plugins复现,判断问题是否来自自定义配置/插件;- 收集
rofi -help、rofi -dump-config、rofi -dump-theme三份输出,脱敏后随 issue 提交; - 若为启动慢/卡顿类问题,用
G_MESSAGES_DEBUG=Timings rofi -show drun定位耗时瓶颈阶段; - 若为特定模式行为异常,按表选择对应域(如
Modes.DRun、Modes.Combi),必要时加-log ~/rofi.log持久化输出; - 若为崩溃问题,用带调试符号的构建 + core dump +
gdb rofi core+thread apply all bt生成回溯。
相关手册
- rofi-theme(5):主题系统与 rasi 格式参考,配合
-dump-theme排障 - rofi-script(5):脚本模式与
-log输出中脚本相关信息的说明 - rofi-keys(5):键绑定配置,
-list-keybindings可辅助排查按键无响应 - rofi-dmenu(5):dmenu 兼容模式细节
- rofi(1):完整命令行选项与调试域总表