AwesomeWM 启动选项完全指南：命令行、Modeline 与 Shebang 的配置优先级详解-平芜编程栈

操作系统

【免费下载链接】awesome

awesome window manager

项目地址：https://gitcode.com/gh_mirrors/awes/awesome

本篇技术指南以 AwesomeWM（当前仓库为 GitHub 加速计划 / awes / awesome 镜像的 awesome window manager）的启动阶段为核心，系统讲解在rc.lua被执行之前，如何通过命令行参数、配置文件顶部 modeline 注释以及可执行脚本 shebang 三种途径控制窗口管理器的行为。读完本文，你将掌握awesome全部 10 个启动选项的用途与适用场景、三者之间"谁说了算"的优先级规则，以及如何利用api-level提前发现 API 废弃警告、用-m off手动接管屏幕创建以支持 HiDPI 等实战技巧。

启动选项的三种注入途径

AwesomeWM 允许在rc.lua执行之前对窗口管理器进行配置，配置途径共有三种，其原始定义与解析逻辑均集中在仓库根目录的 options.c 中：

命令行参数：会话管理器（如 SDDM、GDM）或.xinitrc启动awesome时直接传入；
Modeline 注释：写在rc.lua顶部的特殊 Lua 注释，让同一份配置在多台机器间保持可移植；
Shebang 头：可执行.lua脚本首行的#!前缀，相当于把脚本本身当作启动入口。

三种途径的最终归宿是同一个函数——options.c 中的options_check_args()，它通过getopt_long将各类参数统一翻译成init_flags标志位和搜索路径列表。从 options.h 可以看到这些标志位的定义，包括INIT_FLAG_ARGB（透明支持）、INIT_FLAG_REPLACE_WM（接管现有窗口管理器）、INIT_FLAG_AUTO_SCREEN（自动创建屏幕）、INIT_FLAG_FORCE_CMD_ARGS（强制命令行参数优先）等。

命令行选项一览

在终端执行awesome -h或直接查看 options.c 中的exit_help()函数，可以得到如下完整帮助文本：

Usage: awesome [OPTION] -h, --help show help -v, --version show version -c, --config FILE configuration file to use -f, --force ignore modelines and apply the command line arguments -s, --search DIR add a directory to the library search path -k, --check check configuration file syntax -a, --no-argb disable client transparency support -l --api-level LEVEL select a different API support level than the current version -m, --screen on|off enable or disable automatic screen creation (default: on) -r, --replace replace an existing window manager

这 10 个选项中，-h、-v、-c、-f、-k属于一次性动作或路径覆盖；-s、-a、-l、-m、-r则会改变全局运行状态。仓库中的 getopt 配置（options.c）还额外维护了一个内部隐藏选项--reap，它被"静默忽略"（options.c），供内部重启流程使用，用户不应依赖它。

Modeline：把选项写进配置文件的头部

为了让rc.lua在不同机器之间可移植，AwesomeWM 支持在配置文件顶部以注释形式声明启动选项。这些选项在Lua 虚拟机启动之前就会被 C 层解析。modeline 的语法要求：

必须位于rc.lua靠近顶部的位置；
以-- awesome_mode:开头；
多个选项之间用:分隔；
带值的选项用=连接键与值。

默认 modeline 正是仓库根目录 awesomerc.lua 的第一行：

-- awesome_mode: api-level=4:screen=on

通过 modeline 可设置的键共有 5 个，对应关系如下：

键名	是否有参数	是否允许重复	类型	说明
`search`	是	是	string	存放 AwesomeWM 核心库的路径
`no-argb`	否	否	N/A	禁用内置（真实）透明
`api-level`	是	否	integer	配置使用的 API 级别
`screen`	是	否	string	在`rc.lua`执行前是否创建屏幕（`on`或`off`）
`replace`	否	否	N/A	接管当前窗口管理器

值得注意的是，这 5 个键与命令行的 10 个选项并不一一对应：-c（指定配置文件）在 modeline 中毫无意义——文件此刻正在被读取；-f（强制命令行参数）是对 modeline 机制的否定，自然不能通过 modeline 声明；-k（语法检查）与-v（版本输出）是进程级动作，同样无法在 modeline 中表达。

底层解析由 options.c 的options_init_config()完成。它用一个包含MODELINE_STATE_INIT、MODELINE_STATE_COMMENT、MODELINE_STATE_MODELINE、MODELINE_STATE_KEY、MODELINE_STATE_VALUE等十余个状态的状态机逐字符扫描配置文件头部，把 modeline 或 shebang 内容重新翻译成 argv 交给options_check_args()处理。因此无论参数来自命令行还是配置文件，最终解析路径完全一致。这个解析器还体现了一个细节：modeline 必须使用 ASCII 编码，非 ASCII 字节会被跳过并打印一次WARNING: modelines must use ASCII（options.c），这与本文稍后提到的 "shebang 暂不支持 UTF-8 路径" 的限制相互呼应。

Shebang：把配置变成可执行脚本

AwesomeWM 支持把配置文件做成可执行脚本，利用 POSIX 的#!（shebang）魔术前缀启动。仓库文档给出的典型文件头如下：

#! /usr/bin/env awesome --replace -- If LuaRocks is installed, make sure that packages installed through it -- are found (e.g. lgi). If LuaRocks is not installed, do nothing. pcall(require, "luarocks.loader") -- Standard awesome library local gears = require("gears") [... more `rc.lua` content ...]

随后执行chmod +x并直接运行该文件即可。C 层对 shebang 的探测在 options.c 的options_detect_shebang()中实现：当 argv 数量介于 2 到 3 之间且最后一个参数对应的文件存在、具有可执行权限（S_IXUSR）并且首字节为#!时，就判定为 shebang 脚本模式，把该文件路径作为配置路径返回。代码注释（options.c）明确说明：由于不同平台对 shebang 的 argv 解析方式存在差异（有的平台会把参数拼接成一个字符串），判断"是否真的是被 shebang 调用"并没有跨平台的标准方法，所以干脆直接读取文件内容来消除歧义。

需要提醒的是，当前实现暂不支持 UTF-8 路径，包含非 ASCII 字符的脚本路径可能无法被正确识别。

逐项深入：十个启动选项详解

下面按awesome -h的输出顺序逐一展开每个选项。文档用三列矩阵说明每种途径的支持情况（命令行 / Modeline / Shebang），这里汇总如下：

选项	命令行	Modeline	Shebang	说明
`-h, --help`	✅	❌	❌	显示帮助
`-v, --version`	✅	❌	❌	显示版本
`-c, --config FILE`	✅	❌	❌	指定配置文件
`-f, --force`	✅	❌	❌	忽略 modeline，强制命令行参数
`-s, --search DIR`	✅	✅	✅	追加 Lua 搜索路径
`-k, --check`	✅	❌	❌	仅检查配置语法
`-a, --no-argb`	✅	✅	✅	禁用真实透明
`-l, --api-level LEVEL`	✅	✅	✅	切换 API 级别
`-m, --screen on\\|off`	✅	✅	✅	屏幕创建时机
`-r, --replace`	✅	✅	✅	接管现有窗口管理器

version (-v)：诊断信息的第一手来源

-v输出由 common/version.c 的eprint_version()生成，典型输出形如：

awesome v4.3 (Too long) • Compiled against Lua 5.1.5 (running with Lua 5.1) • API level: 4 • D-Bus support: yes • xcb-errors support: no • execinfo support: yes • xcb-randr version: 1.6 • LGI version: 0.9.2 • Transparency enabled: yes • Custom search paths: no

对照源码可以看出每一行的真实含义：Compiled against与running with分别来自编译期 Lua 版本宏和运行时_VERSION全局变量；D-Bus、xcb-errors、execinfo对应编译期特性宏WITH_DBUS、WITH_XCB_ERRORS、HAS_EXECINFO；Transparency enabled实际反映的是globalconf.had_overriden_depth标志——一旦使用了-a/--no-argb，这里就会变为no；Custom search paths则与globalconf.have_searchpaths（即是否使用了-s）挂钩。因此，在 issues 模板或社区中报告 bug 时，官方建议直接附带-v的完整输出，它比任何口头描述都更能帮助维护者定位环境差异。

config (-c)：使用替代配置文件

-c允许传入任意 Lua 文件作为配置，取代默认的~/.config/awesome/rc.lua或/etc/xdg/awesome/rc.lua。它只支持命令行途径——在 shebang 中毫无意义（你已经在直接调用脚本了），在 modeline 中也没有意义（此刻文件已被读取）。从实现看，options.c 在解析-c时除了记录配置路径，还会把配置文件所在目录追加进搜索路径，以便"多文件配置"（配置文件中再require同目录模块）正常工作；同时--config只允许出现一次，重复指定会触发fatal("--config may only be specified once")。

force (-f)：让命令行压过 modeline

正常情况下，modeline 拥有最终决定权——这正是rc.lua可以在多台机器间免修改移植的原因：机器相关的选项写死在配置里，无需改动.xinitrc或会话文件。但某些场景下你需要临时覆盖这些参数，最常见的就是临时调高 API 级别以观察更多废弃警告。-f的语义是"忽略 modeline，直接应用命令行参数"。

实现层面，启动流程（awesome.c）只有在未设置INIT_FLAG_FORCE_CMD_ARGS时才会调用options_init_config()去解析 modeline；一旦带上了-f，modeline 解析被整体跳过，命令行参数成为唯一依据。这个标志位的定义见 options.h。

search (-s)：扩展 Lua 搜索路径

-s可以向 Lua 搜索路径追加任意目录，常见用途有三：

放置核心库的替代版本（如自制版awful），便于进行上游补丁的开发调试；
指向自定义模块所在的目录；
开发期快速试验，不必把模块安装到标准位置。

文档建议自定义模块的常规安放位置是~/.config/awesome/或/usr/share/awesome/lib，因此-s更多是开发工具而非日常配置手段。它支持命令行、modeline、shebang 三种途径（modeline 键名search允许多次出现）。源码层面，每次-s都会置位globalconf.have_searchpaths并把目录加入paths数组（options.c），而 XDG 配置目录（如$XDG_CONFIG_DIR/awesome）也会在 awesome.c 被无条件追加进搜索路径，最终统一交给luaA_init()初始化 Lua 的package.path。

check (-k)：只检查语法，不保证能运行

-k只校验配置文件是否为合法 Lua 脚本，绝不检查你的自定义逻辑是否正确。即使它输出 "OK"，也只代表文件可以被解析、解释器可以尝试执行，不代表配置能正常加载。

源码实现非常直白：在 awesome.c，-k置位INIT_FLAG_RUN_TEST后，主流程会先通过luaA_find_config()找到第一个候选配置，打印Checking config '...'...，然后创建一个独立的lua_State调用luaL_loadfile()尝试编译。编译失败则打印错误并返回EXIT_FAILURE，成功则输出OK并返回EXIT_SUCCESS。也就是说它只覆盖到loadfile（编译）这一步，连执行阶段（如pcall包裹的运行、模块 require 的解析、X11 对象的创建）都不会触碰，更别提语义层面了。把-k当成 CI 或提交前的快速冒烟检查是合适的，但不要用它替代真正的启动测试。

no-argb (-a)：规避有问题的显卡驱动

-a禁用 AwesomeWM 内置的真实透明支持。开启后，标题栏（titlebar）和 wibox 将无法再做到完全透明。需要说明的是：

透明默认开启（INIT_FLAG_ARGB是默认标志之一，见 awesome.c）；
如果你本来就不使用合成器（如compton、picom），关闭透明只会提升可靠性与可移植性，视觉上几乎无差异；
该选项只应在配置搭配某款主流显卡驱动出现异常时启用——问题通常出在驱动侧，文档明确建议遇到这类 bug 时应向驱动方反馈。

从实现看，-a会置位globalconf.had_overriden_depth并清除INIT_FLAG_ARGB（options.c）。在启动阶段，只有当标志位仍然保留时，awesome.c 才会通过draw_argb_visual()申请 ARGB visual；否则回退到默认 visual。这就是-v输出中Transparency enabled一栏由yes变为no的根源。

api-level (-l)：按需切换 API 兼容级别

这是 AwesomeWM 向后兼容策略的核心机制。当你投入大量精力维护一套配置，而新的主版本发布时，可以通过设定 API 级别推迟大规模升级——AwesomeWM 会尽量保持旧级别下的行为与内容。反过来，把api-level设得比当前版本更高，可以更快收到新增的废弃 API 警告，并提前体验实验性特性。

关键规则：

默认 API 级别等于版本号的第一段。例如 AwesomeWM v4.3 的默认 API 级别就是4（由 common/version.c 的awesome_default_api_level()从AWESOME_API_LEVEL编译期宏取得，并在 awesome.c 初始化）；
兼容范围只回溯到 AwesomeWM 4.0，更早的 3.x API 已被移除；
想看到更多废弃错误，可在 modeline 中把级别加 2，例如默认级别 4 的配置可写成：
```
-- awesome_mode: api-level=6:screen=on
```

实现层面，options.c 的set_api_level()用strtol解析数值并做了严谨的校验：纯数字（可带小数点）才合法，非法输入会打印Invalid API level；当解析结果小于 4 时会被强制回退到 4。最终数值存入globalconf.api_level，并通过 luaa.c 暴露给 Lua 侧的awesome.api_level字段，供rc.lua在运行时读取判断。模型输出前的检查（-k之外的语义检查）以及运行时对 API 级别的响应，都依赖这一全局值。

screen (-m)：控制屏幕对象的创建时机

-m接受且仅接受on或off两个值，控制屏幕对象（screen）何时被创建。源码在 options.c 对非法值直接抛出fatal()，并把off翻译成globalconf.no_auto_screen = true、清除INIT_FLAG_AUTO_SCREEN。

on（默认）：屏幕在rc.lua解析之前创建。这非常适合屏幕数量固定不变的机器：mouse.screen与awful.screen.focused()等 API 可以放心假设"始终存在一个有效屏幕"。缺点在于，一旦屏幕数量变化或需要修改 DPI，这种"全自动魔法"反而碍事。
off：屏幕在rc.lua执行过程中尽早创建。好处是会派发多个信号（如request::create、added、scanned），给 DPI、超宽屏（ultra-wide）等特性留出大量可编程空间；屏幕对象也完全由 Lua 代码掌控，动态增删屏幕更加容易。文档明确预告：未来默认值将改为off，以便默认启用 HiDPI 支持。

两种模式的启动顺序差异体现在 awesome.c：no_auto_screen为真时，先执行luaA_parserc()再调用screen_scan()；否则先screen_scan()再解析配置。无论哪种模式，最终都会在 awesome.c 发出scanned信号。

这里有一个极易踩坑的约束（awesome.c）：当-m off且执行完rc.lua后仍然没有任何屏幕对象，AwesomeWM 会直接fatal()退出——"在scanned信号之前或之中，你必须创建至少一个屏幕对象，无屏运行不受支持"。也就是说，选择off意味着你的配置里必须接管屏幕创建。仓库中的 lib/awful/screen/dpi.lua 展示了一个参考实现：它监听request::create、request::remove、request::resize等信号维护屏幕，并监听scanned信号做兜底——当screen.count() == 0时，通过_scan_quiet()重新扫描视口，找不到任何视口则用fake_add(0, 0, 640, 480)垫底，最后断言屏幕创建成功。这套兜底逻辑保证了-m off与-s调试、单机无显示器等场景下系统仍能正常启动。

replace (-r)：顶替正在运行的窗口管理器

-r会让 AwesomeWM 杀掉当前的窗口管理器（哪怕它是另一个awesome实例）并取而代之。默认关闭。对应标志位INIT_FLAG_REPLACE_WM（options.c），实际生效点在 awesome.c 的acquire_WM_Sn()：该函数先检查根窗口上的WM_Sn选择权（selection）是否已被占用，若被占用且未指定-r，直接fatal("another window manager is already running ... use --replace")；指定了-r则尝试接管选择权、等待旧拥有者退出，然后以MANAGER客户端消息广播新状态。顺带一提，之后 awesome.c 对根窗口请求SubstructureRedirect事件掩码时，如果另一个窗口管理器仍存活也会触发同样的报错——这正是 X11 协议"同一时刻只能有一个 WM"的硬性保证。日常重载配置请优先使用Mod4+Ctrl+r之类的重启绑定（对应 C 层awesome_restart()的execvp自重启，awesome.c），而不是-r。

三种途径的优先级与解析顺序

理解启动顺序是正确使用这些选项的前提。综合 awesome.c 的main()与 options.c，完整的解析链如下：

探测 shebang：options_detect_shebang()判断当前是否以#!脚本方式启动（awesome.c）；
解析命令行：若未检测到 shebang，立即用options_check_args()解析命令行（awesome.c）；
读取 modeline：只要没有-f/--force，就调用options_init_config()打开配置文件头部，把 modeline（或 shebang 剩余参数）翻译成 argv 并再次走options_check_args()（awesome.c）。由于 modeline 在命令行之后解析，后写入的 modeline 值会覆盖同名命令行参数——这就是"modeline 拥有最终决定权"的机制来源；而-f正是通过跳过这一步骤让命令行参数独占决策权；
应用选项：根据init_flags决定是否申请 ARGB visual、是否接管现有 WM、检查-k、按no_auto_screen分支安排rc.lua与screen_scan()的执行顺序。

一个实用推论：由于-c指定的是"要被读取的配置文件"，而 modeline 来自这个文件本身，所以**-c与 modeline 天然互不冲突**——modeline 只是从该文件里读到的参数集。相应地，文档也明确指出-c、-f、-k、-v四种选项只存在于命令行途径，无法（也不应该）通过 modeline 或 shebang 表达。

实战组合与排错建议

新机器部署前的语法体检：awesome -k快速确认rc.lua编译无误；发现启动异常时先跑awesome -v收集环境信息，再检查api-level是否匹配。
观察废弃 API：临时用awesome -f -l 6启动，-f强制命令行覆盖 modeline 中较低的默认级别，从而在当前版本基础上看到更激进的废弃警告；也可以在配置顶部长期保留-- awesome_mode: api-level=6:screen=on。
多屏 / HiDPI 场景：在配置中显式声明-- awesome_mode: screen=off，并像 lib/awful/screen/dpi.lua 那样监听request::create等信号接管屏幕创建与 DPI 设置，避免自动屏幕创建带来的不便；记住必须保证至少创建一个屏幕，否则会触发启动fatal。
无合成器环境：如果遇到透明导致的渲染异常，用-a或 modeline 键no-argb关闭真实透明，通常能显著提升稳定性与可移植性。
开发调试自定义库：awesome -s /path/to/custom/lib临时注入搜索路径，配合模型输出验证，不必污染~/.config/awesome目录。

小结

AwesomeWM 把"窗口管理器启动之前"的决策收敛为命令行、modeline、shebang 三条通路，并统一交由 options.c 的解析器处理：api-level提供跨版本兼容与废弃预警，screen控制屏幕创建时机并直接影响 HiDPI 与多屏体验，replace与force分别解决 WM 接管和参数覆盖问题，search、no-argb、check则是开发调试与排障的常用工具。理解 awesome.c 中"先命令行、后 modeline、-f跳过 modeline"的解析顺序，你就掌握了调整窗口管理器行为的完整钥匙——这些选项共同构成了rc.lua执行之前的那一层关键控制面。