Home Manager 22.05 版本解读Waybar 配置扁平化、启动项翻译支持与 launchd.agents 新模块【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager本篇指南以 Home Manager 仓库中的 22.05 版本发布说明 为骨架深入解读该版本的三项核心变更Waybar 模块配置从settings.modules迁移到settings顶层、对 Bash 组件的多语言翻译支持以及新增的 macOSlaunchd.agents模块。读完本文你将掌握 22.05 状态版本stateVersion的迁移细节与断言行逻辑理解home.stateVersion如何控制破坏性变更的生效时机并能用源码与测试用例佐证这些变更的真实实现。版本背景22.05 稳定分支22.05 发布分支于 2022 年 5 月成为 Home Manager 的稳定分支见 rl-2205.md。该版本带来了三项值得关注的变更移除programs.waybar.settings.modules选项Waybar 模块改为直接在programs.waybar.settings下声明部分支持多语言翻译目前仅覆盖以 Bash 语言编写的系统部分如home-manager命令行工具与激活脚本新增launchd.agents模块用于在 macOS 上基于 LaunchAgents 启用服务。变更一Waybar 配置扁平化变更内容22.05 移除了programs.waybar.settings.modules选项。在此之前Waybar 模块需要嵌套在modules属性下声明programs.waybar.settings.modules.custom/my-module { };22.05 之后模块必须直接声明在settings顶层programs.waybar.settings.custom/my-module { };源码实现印证这一变更在 modules/programs/waybar.nix 中有完整的实现支撑。在生成最终 JSON 配置时模块配置会被“上提”到顶层。源码中的makeConfiguration函数modules/programs/waybar.nix#L289-L297会先从配置中剥离modules属性settingsWithoutModules再将其子项合并到顶层# The modules option is not valid in the JSON # as its descendants have to live at the top-level settingsWithoutModules removeAttrs configuration [ modules ]; settingsModules optionalAttrs (configuration.modules ! null) configuration.modules; in removeTopLevelNulls (settingsWithoutModules // settingsModules);换言之即使你在stateVersion低于 22.05 的配置里仍然使用settings.modules生成的waybar/config.json中模块也会被摊平到顶层与 Waybar 本身期望的 JSON 结构保持一致。同时源码通过断言assertion强制新语义modules/programs/waybar.nix#L310-L323assertion if lib.versionAtLeast config.home.stateVersion 22.05 then all (x: !hasAttr modules x || x.modules null) settings else true; message The programs.waybar.settings.[].modules option has been removed. It is now possible to declare modules in the configuration without nesting them under the modules option. ;可以看出当home.stateVersion大于等于 22.05 时配置中再出现非空的modules属性会直接触发求值错误而低于该状态版本时则保持宽松兼容旧写法。测试用例验证仓库测试对两种情形都有覆盖见 tests/modules/programs/waybar/default.nixsettings-complex.nixstateVersion 21.11仍使用settings列表形式并在每个 bar 内声明modules测试断言最终生成的home-files/.config/waybar/config与预期 JSON 完全一致——模块已被摊平到顶层settings-with-attrs.nixstateVersion 21.11演示用属性集attrs形式同时声明mainBar与secondaryBar多 bar 配置deprecated-modules-option.nixstateVersion 22.05故意使用modules声明模块测试期望触发上述断言错误同时仍校验输出 JSON 中test: {}已出现在顶层。迁移到新写法后的完整示例结合 modules/programs/waybar.nix#L191-L219 的官方示例与 settings-complex.nix 的测试配置22.05 之后的推荐写法如下programs.waybar { enable true; settings { mainBar { layer top; position top; height 30; output [ DP-1 HDMI-A-1 ]; modules-left [ sway/workspaces sway/mode custom/my-module ]; modules-center [ sway/window ]; modules-right [ idle_inhibitor pulseaudio network cpu memory backlight tray clock ]; # 模块配置直接放在 settings 顶层不再嵌套 modules sway/workspaces { disable-scroll true; all-outputs true; }; sway/window { max-length 120; }; custom/my-module { format hello from {}; exec pkgs.writeShellScript my-module echo hello ; }; clock { format-alt {:%a, %d. %b %H:%M}; }; }; }; style * { border: none; border-radius: 0; } window#waybar { background: #16191C; color: #AAB2BF; } ; };几点与源码对应的细节说明settings的类型是either (listOf waybarBarConfig) (attrsOf waybarBarConfig)modules/programs/waybar.nix#L184-L186既可以用列表bar 未命名、按顺序生效也可以用属性集每个 bar 有名字便于覆盖与继承。bar 级支持的选项包括layer、output、position、height、width、modules-left、modules-center、modules-right、margin系列、name、gtk-layer-shell等均以null为默认值序列化时顶层的null会被removeTopLevelNulls过滤掉modules/programs/waybar.nix#L285Waybar 会忽略这些空值。output支持用!前缀排除指定输出如!DP-2。配置最终经jsonFormat.generate waybar-config.json写入xdg.configFile.waybar/configmodules/programs/waybar.nix#L327-L332未启用 systemd 集成时文件变更后通过pkill -u $USER -USR2 waybar通知 Waybar 重载。若启用programs.waybar.systemd.enable则生成 systemd 用户服务waybar.serviceExecStart为waybarenableDebug时追加-l debugExecReload为kill -SIGUSR2 $MAINPID并通过X-Reload-Triggers跟踪配置与样式的变化modules/programs/waybar.nix#L346-L369。变更二对 Bash 组件的多语言翻译支持22.05 开始Home Manager 部分支持将文本翻译为不同语言。需要明确的是这一支持目前非常有限仅适用于以 Bash 语言编写的系统部分具体包括home-manager命令行工具激活脚本activation script。翻译基础设施仓库中保留了完整的翻译资产PO/POT 文件命令行工具与激活脚本的翻译模板位于 home-manager/po/home-manager.pot并提供了ar、de、es、fr、ja、ko、ru、zh_Hans、zh_Hant等数十种语言的.po翻译文件见 home-manager/po 目录模块层面的描述文本翻译模板位于 modules/po/hm-modules.pot对应 modules/po 下的各语言翻译文件根目录的 xgettext 脚本与 ci/parse.nix 负责提取与校验可翻译字符串。参与翻译的途径官方发布说明指出可以通过 Home Manager 的 Weblate 项目参与翻译工作。仓库内的 README.md 与 CONTRIBUTING.md 也提供了相关流程说明。对普通用户而言理解重点在于22.05 起home-manager命令的输出与激活流程中的部分提示信息具备了本地化的基础但覆盖范围尚窄不应期待全部界面文案都被翻译。变更三新增 launchd.agents 模块22.05 引入了全新的launchd.agents模块用于在 macOS 上基于 LaunchAgents 启用按用户运行的服务daemon/agent。基本用法launchd.agents.test-service { enable true; config { ProgramArguments [ /some/command --with-arguments foo ]; KeepAlive { Crashed true; SuccessfulExit false; }; ProcessType Background; }; };launchd.agents是一个属性集每个 key 对应一个 LaunchAgent子选项包括enable是否启用该 agentdomaingui默认或user。gui域适合需要用户 Aqua 会话的图形化工具窗口管理器、热键守护进程等user域适合无需图形登录会话的后台服务见 modules/launchd/default.nix#L21-L36waitForNixStore默认为true通过/bin/sh包装器调用/bin/wait4path /nix/store等待 Nix store 挂载后再启动 agent避免登录早期如 store 卷被加密时agent 抢先启动失败设为false时改用与 agent 同名的 launcher 脚本让 agent 在「系统设置 → 登录项与扩展」中以自身名字而非sh显示modules/launchd/default.nix#L37-L54configlaunchd 作业本体定义类型为 modules/launchd/launchd.nix 中声明的子模块。launchd 作业配置项modules/launchd/launchd.nix 移植自 nix-darwin 的 launchd 选项类型并对home.stateVersion 25.01的ProgramArguments做了自动转义处理modules/launchd/launchd.nix#L151-L170。常用配置项包括配置键类型说明Labelstr必填唯一标识该作业Home Manager 默认填充为org.nix-community.home.agent名Program/ProgramArgumentspath/listOf str二选一指定要运行的程序与参数RunAtLoadbool加载作业时立即启动一次KeepAlivebool或子模块控制是否持续运行子模块支持SuccessfulExit、Crashed、NetworkState、PathState等条件多条件之间为 OR 关系StartIntervalint每隔 N 秒启动一次系统休眠时会在唤醒后合并执行StartCalendarInterval列表类 cron 的日历调度缺失属性视为通配符空属性集等价于「每分钟」列表不能为空且不能有重复项WatchPathslistOf path任一列出的路径被修改时启动作业QueueDirectorieslistOf str类似 WatchPaths但仅在目录非空时启动StartOnMountbool每次文件系统挂载时启动EnvironmentVariablesattrsOf str设置作业环境变量WorkingDirectory/RootDirectorystr指定工作目录 / chroot 目录StandardOutPath/StandardErrorPath/StandardInPathpath重定向标准输出、错误与输入ThrottleIntervalint覆盖默认节流策略默认 10 秒内最多启动一次ExitTimeOutint等待退出后发送 SIGKILL 的秒数0 视为无限ProcessType枚举Background/Standard/Adaptive/Interactive影响系统施加的资源限制Sockets、MachServices、LaunchEvents子模块 / attrslaunch-on-demand 的 socket、Mach 服务与系统事件源SoftResourceLimits/HardResourceLimits子模块setrlimit(2)资源限制Core、CPU、Data、FileSize、NumberOfFiles、NumberOfProcesses、ResidentSetSize、Stack、MemoryLock等底层实现机制launchd.agents的实现在 modules/launchd/default.nix 中启用且enable true的 agent 会通过toPlist序列化为 plist 文件并在生成目录下暴露LaunchAgents与LaunchAgentDomains两个符号链接目录modules/launchd/default.nix#L205-L209激活脚本setupLaunchAgentsmodules/launchd/default.nix#L213-L552负责完整的生命周期管理比较新旧 plist 是否变化、通过launchctl bootout停止旧 agent、将 plist 安装到~/Library/LaunchAgents、再通过launchctl bootstrap启动新 agent并对已删除的 agent 做清理当 bootout 或 bootstrap 失败时还会尝试恢复旧版本macOS 10.6 之前/之后的-w语义、gui/$UID与user/$UID域解析等细节都在激活脚本中处理非 Darwin 平台若启用了需要 launchd 的 agent会触发断言错误「Must use Darwin for modules that require Launchd」modules/launchd/default.nix#L193-L202。测试覆盖仓库在 tests/modules/launchd 下提供了多组测试agents.nix验证 plist 生成含特殊字符转义、未识别的自由格式键透传、domain 文件内容以及激活脚本中各关键函数readAgentDomain、resolveDomain、agentIsLoaded、bootoutAgent、restoreAgent等的存在agent-domain.nix验证domain选项agent-launcher.nix验证waitForNixStore与 launcher 脚本行为。关于 stateVersion 的迁移建议22.05 的破坏性变更都由home.stateVersion控制生效时机只有把home.stateVersion设置为22.05或更高时Waybar 的settings.modules才会被严格禁止保留旧值则旧写法仍可求值但生成的 JSON 已自动摊平。升级到 22.05 及以上状态版本时请务必先搜索配置中所有programs.waybar.settings.modules出现位置将模块声明上提到settings顶层再运行home-manager switch验证。遇到断言错误时错误信息会明确指出该选项已被移除。总结22.05 版本的三项变更分别对应三条演进主线Waybar 模块配置向 Waybar 原生 JSON 结构靠拢破坏性但迁移路径清晰、i18n 基础设施从 Bash 组件起步范围有限但为后续铺路、以及 macOS 用户侧服务管理的正式化launchd.agents提供了声明式、可回滚的 LaunchAgent 管理。如果你正在维护stateVersion 22.05的配置本文给出的迁移示例、源码依据与测试路径可以直接作为核对清单使用。【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Home Manager 22.05 版本解读Waybar 配置扁平化、启动项翻译支持与 launchd.agents 新模块【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager本篇指南以 Home Manager 仓库中的 22.05 版本发布说明 为骨架深入解读该版本的三项核心变更Waybar 模块配置从settings.modules迁移到settings顶层、对 Bash 组件的多语言翻译支持以及新增的 macOSlaunchd.agents模块。读完本文你将掌握 22.05 状态版本stateVersion的迁移细节与断言行逻辑理解home.stateVersion如何控制破坏性变更的生效时机并能用源码与测试用例佐证这些变更的真实实现。版本背景22.05 稳定分支22.05 发布分支于 2022 年 5 月成为 Home Manager 的稳定分支见 rl-2205.md。该版本带来了三项值得关注的变更移除programs.waybar.settings.modules选项Waybar 模块改为直接在programs.waybar.settings下声明部分支持多语言翻译目前仅覆盖以 Bash 语言编写的系统部分如home-manager命令行工具与激活脚本新增launchd.agents模块用于在 macOS 上基于 LaunchAgents 启用服务。变更一Waybar 配置扁平化变更内容22.05 移除了programs.waybar.settings.modules选项。在此之前Waybar 模块需要嵌套在modules属性下声明programs.waybar.settings.modules.custom/my-module { };22.05 之后模块必须直接声明在settings顶层programs.waybar.settings.custom/my-module { };源码实现印证这一变更在 modules/programs/waybar.nix 中有完整的实现支撑。在生成最终 JSON 配置时模块配置会被“上提”到顶层。源码中的makeConfiguration函数modules/programs/waybar.nix#L289-L297会先从配置中剥离modules属性settingsWithoutModules再将其子项合并到顶层# The modules option is not valid in the JSON # as its descendants have to live at the top-level settingsWithoutModules removeAttrs configuration [ modules ]; settingsModules optionalAttrs (configuration.modules ! null) configuration.modules; in removeTopLevelNulls (settingsWithoutModules // settingsModules);换言之即使你在stateVersion低于 22.05 的配置里仍然使用settings.modules生成的waybar/config.json中模块也会被摊平到顶层与 Waybar 本身期望的 JSON 结构保持一致。同时源码通过断言assertion强制新语义modules/programs/waybar.nix#L310-L323assertion if lib.versionAtLeast config.home.stateVersion 22.05 then all (x: !hasAttr modules x || x.modules null) settings else true; message The programs.waybar.settings.[].modules option has been removed. It is now possible to declare modules in the configuration without nesting them under the modules option. ;可以看出当home.stateVersion大于等于 22.05 时配置中再出现非空的modules属性会直接触发求值错误而低于该状态版本时则保持宽松兼容旧写法。测试用例验证仓库测试对两种情形都有覆盖见 tests/modules/programs/waybar/default.nixsettings-complex.nixstateVersion 21.11仍使用settings列表形式并在每个 bar 内声明modules测试断言最终生成的home-files/.config/waybar/config与预期 JSON 完全一致——模块已被摊平到顶层settings-with-attrs.nixstateVersion 21.11演示用属性集attrs形式同时声明mainBar与secondaryBar多 bar 配置deprecated-modules-option.nixstateVersion 22.05故意使用modules声明模块测试期望触发上述断言错误同时仍校验输出 JSON 中test: {}已出现在顶层。迁移到新写法后的完整示例结合 modules/programs/waybar.nix#L191-L219 的官方示例与 settings-complex.nix 的测试配置22.05 之后的推荐写法如下programs.waybar { enable true; settings { mainBar { layer top; position top; height 30; output [ DP-1 HDMI-A-1 ]; modules-left [ sway/workspaces sway/mode custom/my-module ]; modules-center [ sway/window ]; modules-right [ idle_inhibitor pulseaudio network cpu memory backlight tray clock ]; # 模块配置直接放在 settings 顶层不再嵌套 modules sway/workspaces { disable-scroll true; all-outputs true; }; sway/window { max-length 120; }; custom/my-module { format hello from {}; exec pkgs.writeShellScript my-module echo hello ; }; clock { format-alt {:%a, %d. %b %H:%M}; }; }; }; style * { border: none; border-radius: 0; } window#waybar { background: #16191C; color: #AAB2BF; } ; };几点与源码对应的细节说明settings的类型是either (listOf waybarBarConfig) (attrsOf waybarBarConfig)modules/programs/waybar.nix#L184-L186既可以用列表bar 未命名、按顺序生效也可以用属性集每个 bar 有名字便于覆盖与继承。bar 级支持的选项包括layer、output、position、height、width、modules-left、modules-center、modules-right、margin系列、name、gtk-layer-shell等均以null为默认值序列化时顶层的null会被removeTopLevelNulls过滤掉modules/programs/waybar.nix#L285Waybar 会忽略这些空值。output支持用!前缀排除指定输出如!DP-2。配置最终经jsonFormat.generate waybar-config.json写入xdg.configFile.waybar/configmodules/programs/waybar.nix#L327-L332未启用 systemd 集成时文件变更后通过pkill -u $USER -USR2 waybar通知 Waybar 重载。若启用programs.waybar.systemd.enable则生成 systemd 用户服务waybar.serviceExecStart为waybarenableDebug时追加-l debugExecReload为kill -SIGUSR2 $MAINPID并通过X-Reload-Triggers跟踪配置与样式的变化modules/programs/waybar.nix#L346-L369。变更二对 Bash 组件的多语言翻译支持22.05 开始Home Manager 部分支持将文本翻译为不同语言。需要明确的是这一支持目前非常有限仅适用于以 Bash 语言编写的系统部分具体包括home-manager命令行工具激活脚本activation script。翻译基础设施仓库中保留了完整的翻译资产PO/POT 文件命令行工具与激活脚本的翻译模板位于 home-manager/po/home-manager.pot并提供了ar、de、es、fr、ja、ko、ru、zh_Hans、zh_Hant等数十种语言的.po翻译文件见 home-manager/po 目录模块层面的描述文本翻译模板位于 modules/po/hm-modules.pot对应 modules/po 下的各语言翻译文件根目录的 xgettext 脚本与 ci/parse.nix 负责提取与校验可翻译字符串。参与翻译的途径官方发布说明指出可以通过 Home Manager 的 Weblate 项目参与翻译工作。仓库内的 README.md 与 CONTRIBUTING.md 也提供了相关流程说明。对普通用户而言理解重点在于22.05 起home-manager命令的输出与激活流程中的部分提示信息具备了本地化的基础但覆盖范围尚窄不应期待全部界面文案都被翻译。变更三新增 launchd.agents 模块22.05 引入了全新的launchd.agents模块用于在 macOS 上基于 LaunchAgents 启用按用户运行的服务daemon/agent。基本用法launchd.agents.test-service { enable true; config { ProgramArguments [ /some/command --with-arguments foo ]; KeepAlive { Crashed true; SuccessfulExit false; }; ProcessType Background; }; };launchd.agents是一个属性集每个 key 对应一个 LaunchAgent子选项包括enable是否启用该 agentdomaingui默认或user。gui域适合需要用户 Aqua 会话的图形化工具窗口管理器、热键守护进程等user域适合无需图形登录会话的后台服务见 modules/launchd/default.nix#L21-L36waitForNixStore默认为true通过/bin/sh包装器调用/bin/wait4path /nix/store等待 Nix store 挂载后再启动 agent避免登录早期如 store 卷被加密时agent 抢先启动失败设为false时改用与 agent 同名的 launcher 脚本让 agent 在「系统设置 → 登录项与扩展」中以自身名字而非sh显示modules/launchd/default.nix#L37-L54configlaunchd 作业本体定义类型为 modules/launchd/launchd.nix 中声明的子模块。launchd 作业配置项modules/launchd/launchd.nix 移植自 nix-darwin 的 launchd 选项类型并对home.stateVersion 25.01的ProgramArguments做了自动转义处理modules/launchd/launchd.nix#L151-L170。常用配置项包括配置键类型说明Labelstr必填唯一标识该作业Home Manager 默认填充为org.nix-community.home.agent名Program/ProgramArgumentspath/listOf str二选一指定要运行的程序与参数RunAtLoadbool加载作业时立即启动一次KeepAlivebool或子模块控制是否持续运行子模块支持SuccessfulExit、Crashed、NetworkState、PathState等条件多条件之间为 OR 关系StartIntervalint每隔 N 秒启动一次系统休眠时会在唤醒后合并执行StartCalendarInterval列表类 cron 的日历调度缺失属性视为通配符空属性集等价于「每分钟」列表不能为空且不能有重复项WatchPathslistOf path任一列出的路径被修改时启动作业QueueDirectorieslistOf str类似 WatchPaths但仅在目录非空时启动StartOnMountbool每次文件系统挂载时启动EnvironmentVariablesattrsOf str设置作业环境变量WorkingDirectory/RootDirectorystr指定工作目录 / chroot 目录StandardOutPath/StandardErrorPath/StandardInPathpath重定向标准输出、错误与输入ThrottleIntervalint覆盖默认节流策略默认 10 秒内最多启动一次ExitTimeOutint等待退出后发送 SIGKILL 的秒数0 视为无限ProcessType枚举Background/Standard/Adaptive/Interactive影响系统施加的资源限制Sockets、MachServices、LaunchEvents子模块 / attrslaunch-on-demand 的 socket、Mach 服务与系统事件源SoftResourceLimits/HardResourceLimits子模块setrlimit(2)资源限制Core、CPU、Data、FileSize、NumberOfFiles、NumberOfProcesses、ResidentSetSize、Stack、MemoryLock等底层实现机制launchd.agents的实现在 modules/launchd/default.nix 中启用且enable true的 agent 会通过toPlist序列化为 plist 文件并在生成目录下暴露LaunchAgents与LaunchAgentDomains两个符号链接目录modules/launchd/default.nix#L205-L209激活脚本setupLaunchAgentsmodules/launchd/default.nix#L213-L552负责完整的生命周期管理比较新旧 plist 是否变化、通过launchctl bootout停止旧 agent、将 plist 安装到~/Library/LaunchAgents、再通过launchctl bootstrap启动新 agent并对已删除的 agent 做清理当 bootout 或 bootstrap 失败时还会尝试恢复旧版本macOS 10.6 之前/之后的-w语义、gui/$UID与user/$UID域解析等细节都在激活脚本中处理非 Darwin 平台若启用了需要 launchd 的 agent会触发断言错误「Must use Darwin for modules that require Launchd」modules/launchd/default.nix#L193-L202。测试覆盖仓库在 tests/modules/launchd 下提供了多组测试agents.nix验证 plist 生成含特殊字符转义、未识别的自由格式键透传、domain 文件内容以及激活脚本中各关键函数readAgentDomain、resolveDomain、agentIsLoaded、bootoutAgent、restoreAgent等的存在agent-domain.nix验证domain选项agent-launcher.nix验证waitForNixStore与 launcher 脚本行为。关于 stateVersion 的迁移建议22.05 的破坏性变更都由home.stateVersion控制生效时机只有把home.stateVersion设置为22.05或更高时Waybar 的settings.modules才会被严格禁止保留旧值则旧写法仍可求值但生成的 JSON 已自动摊平。升级到 22.05 及以上状态版本时请务必先搜索配置中所有programs.waybar.settings.modules出现位置将模块声明上提到settings顶层再运行home-manager switch验证。遇到断言错误时错误信息会明确指出该选项已被移除。总结22.05 版本的三项变更分别对应三条演进主线Waybar 模块配置向 Waybar 原生 JSON 结构靠拢破坏性但迁移路径清晰、i18n 基础设施从 Bash 组件起步范围有限但为后续铺路、以及 macOS 用户侧服务管理的正式化launchd.agents提供了声明式、可回滚的 LaunchAgent 管理。如果你正在维护stateVersion 22.05的配置本文给出的迁移示例、源码依据与测试路径可以直接作为核对清单使用。【免费下载链接】home-managerManage a user environment using Nix [maintainerkhaneliman, rycee]项目地址: https://gitcode.com/GitHub_Trending/ho/home-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
