KMonad 安装全指南：二进制、发行版包、NixOS 模块与多平台源码编译实战

• 开发工具

KMonad 是一款跨平台的键盘管理与按键重映射守护进程（项目定位 "An advanced keyboard manager"），其按键捕获与输出机制随操作系统不同而不同：Linux 依赖 evdev/uinput，Windows 使用低级钩子与 send-event，macOS 则依赖 kext/dext 系统扩展。本指南以官方安装文档 doc/installation.md 为主线，系统梳理二进制发布、各发行版包管理器、NixOS 模块化部署以及 stack / nix / Docker / 静态编译等多条安装路径，并结合仓库源码说明每条路径背后的实现细节。读完本文，你将能够根据自身发行版与平台条件，选择最合适的安装方式并完成权限配置、服务托管与安装后验证。

安装方式总览

KMonad 的安装途径大致可分为四类，各有适用场景：

其中，编译 KMonad 有一个通用前提：无论采用哪种编译方式，git都必须位于$PATH中。这是因为项目在编译期通过 Template Haskell 把当前提交哈希写入--version输出，其实现位于 src/KMonad/Args/TH.hs（gitHash函数调用git rev-parse HEAD读取哈希）；Nix 构建时甚至用假 git 脚本（见 nix/flake.nix）来模拟这一行为。

一、直接使用官方二进制

官方在 releases 页面为 Linux（64 位）与 Windows 发布预编译二进制。Windows 的二进制并非每个版本都有，截至安装文档撰写时最新发布版本为 0.4.1；当前仓库 kmonad.cabal 中的版本号为 0.4.5.1，说明以源码方式可以获得比发布包更新的版本。

下载后即可直接运行，无需安装额外依赖。若你希望获得 Linux 上不依赖任何动态库（ldd输出not a dynamic executable）的静态二进制，官方发布页通常也会附带，或者可以按下文"静态编译"一节自行构建。

二、通过发行版包管理器安装

社区已将 KMonad 打入多个发行版的官方仓库。注意：这些包可能落后于上游版本。

Arch Linux

KMonad 位于 Arch 官方extra仓库，包名即kmonad，直接安装：

$ sudo pacman -S kmonad

GNU Guix

使用 Guix 安装后需要手动复制 udev 规则（Linux 下 KMonad 需要以 uinput 方式创建虚拟键盘，权限规则必不可少）：

$ guix install kmonad # cp <kmonad-path>/lib/udev/rules.d/70-kmonad.rules /lib/udev/rules.d/

根据 Guix 包存储机制，<kmonad-path>中会包含记录精确版本号的哈希，默认路径形如/gnu/store/<hash>-kmonad-<version>/。先用guix build kmonad确认实际路径；若返回多个路径，选最短的那个。例如：

$ guix build kmonad /gnu/store/9mx79afpjqxjiiqgh1xv3b7ckblnl4wk-kmonad-0.4.2 /gnu/store/al0bmdxvl3a8s11vxn13y2nkq4hbg4c8-kmonad-0.4.2-static

此时<kmonad-path>为/gnu/store/9mx79afpjqxjiiqgh1xv3b7ckblnl4wk-kmonad-0.4.2，复制操作为：

# cp \ /gnu/store/9mx79afpjqxjiiqgh1xv3b7ckblnl4wk-kmonad-0.4.2/lib/udev/rules.d/70-kmonad.rules \ /lib/udev/rules.d/

若使用 Guix System 整机管理，则应在config.scm中通过udev-service-type声明式地加入该规则：

(use-modules (gnu packages haskell-apps)) (operating-system ;; ... (services (modify-services %desktop-services (udev-service-type config => (udev-configuration (inherit config) (rules (cons kmonad (udev-configuration-rules config))))))))

这条 udev 规则的意义可参考 FAQ doc/faq.md：它确保/dev/uinput设备文件属于uinput组并具有0660权限，用户加入input、uinput组后即可读写键盘设备与创建虚拟键盘，规则内容为KERNEL=="uinput", MODE="0660", GROUP="uinput", OPTIONS+="static_node=uinput"，修改后需sudo systemctl restart systemd-udevd.service生效。

Void Linux

通过xbps-install安装：

# xbps-install -S kmonad

Void 用户若希望开机自启，仓库 startup/ 中提供了针对 runit 的 run 服务脚本示例（放置到/etc/sv/kmonad并软链接到/var/service），以及针对 openrc 的 kmonad 脚本（放入/etc/init.d/后rc-service kmonad start、rc-update add kmonad default）。注意这两个脚本中的/path/to/kmonad与/path/to/config.kbd需替换为实际路径。

NixOS

NixOS 用户有两种选择：直接使用 nixpkgs 中的打包版本，或使用本仓库自带的 NixOS 模块（支持更多选项与 initrd 集成）。

直接使用 nixpkgs 版本

kmonad已打包进 nixpkgs。若你只想用这个版本，无需配置 flake，直接跳到下面"configuration.nix"一节的services.kmonad配置即可。

通过 flake 引入仓库自带模块

仓库 nix/flake.nix 定义了 flake，其nixosModules.default导入 nix/nixos-module.nix，并用 overlay 提供kmonad包。安装步骤如下：

1. 将 KMonad 添加为 flake input：

   kmonad = { url = "github:kmonad/kmonad?dir=nix"; inputs.nixpkgs.follows = "nixpkgs"; };

   ?dir=nix表示使用仓库nix子目录下的 flake。从 nix/flake.nix 可以看到该 flake 的 nixpkgs input 默认跟随nixpkgs-unstable，因此建议让本地 nixpkgs input 跟随（follows）以保证兼容。

2. 在 NixOS 配置中导入该模块：

   outputs = { kmonad, … }: { nixosConfigurations.«systemName» = nixpkgs.lib.nixosSystem { modules = [ kmonad.nixosModules.default ]; }; };

3. 在configuration.nix中启用服务并声明键盘：

   services.kmonad = { enable = true; keyboards = { myKMonadOutput = { device = "/dev/input/by-id/my-keyboard-kbd"; config = builtins.readFile /path/to/my/config.kbd; }; }; };

   device指向键盘设备文件，推荐使用/dev/input/by-id下的稳定名称（如何确认对应设备可参考 doc/faq.md 的问答）；config为完整的 KMonad 键位配置文件（.kbd文件，语法见 keymap/tutorial.kbd）。

   模块实现的底层细节：查看 nix/nixos-module.nix 可知，模块会把每个键盘的config通过pkgs.writeTextFile生成独立的.kbd文件，并在checkPhase中执行${cfg.package}/bin/kmonad -d $out做语法校验（-d即 dry-run 解析检查）；同时为每个键盘生成一对 systemd 单元：mkPath（nix/nixos-module.nix）监听设备文件出现事件，mkService（nix/nixos-module.nix）以低优先级Nice=-20运行kmonad --input device-file …，实现"键盘接入即自动启动 KMonad"。模块还会自动创建uinput、kmonad组与kmonad系统用户，并开启hardware.uinput.enable = true（nix/nixos-module.nix），服务以非特权用户运行，SupplementaryGroups默认包含input与uinput。

   更完整的模块配置选项见 nix/nixos-module.nix，包括：

   • services.kmonad.package：指定 KMonad 包来源（默认pkgs.kmonad，示例pkgs.haskellPackages.kmonad）；

   • services.kmonad.extraArgs：附加命令行参数，如[ "--log-level" "debug" ]；

   • 每个键盘的extraGroups：当设备文件不属于input组时补充所需组（如[ "openrazer" ]）；

   • defcfg相关选项：enable（自动生成defcfg块）、compose.key（默认ralt）、compose.delay（默认 0）、keySeqDelay（默认 1）、fallthrough、allowCommands。启用defcfg.enable时，config中不应再包含defcfg块，模块会自动生成：

     (defcfg input (device-file "…") output (uinput-sink "kmonad-…") cmp-seq ralt cmp-seq-delay 0 key-seq-delay 1 fallthrough false allow-cmd false )

     生成后同样经过kmonad -d语法检查（nix/nixos-module.nix）。这一机制的正确性由仓库内的 NixOS 集成测试验证：测试分别以"完整配置"与"自动生成 defcfg"两种方式启动 KMonad，并在 QEMU 虚拟机中验证按键层生效（见 nix/nixos-test.nix，可运行nix flake check复现）。

4. 仅启用服务但未指定键盘时的权限问题：若只enable = true而未在keyboards中指定键盘，你可能需要将用户加入input与uinput组：

   users.users.«userName».extraGroups = [ "input" "uinput" ];

5. 与 X 布局的交互：若设置了services.kmonad.enable = true;，不要在config.kbd中再写setxkbmap行，否则会与 KMonad 的按键注入冲突。应改为声明式配置 X server：

   services.xserver = { xkbOptions = "compose:ralt"; layout = "us"; };

6. 最后重建系统：

   $ sudo nixos-rebuild switch --flake /path/to/flake

   若希望在内核 initrd（启动早期）就启用 KMonad，还可以设置boot.initrd.services.kmonad.enable = true;（要求systemd作为 stage 1 init，且必须先启用services.kmonad.enable，模块通过 assertion 强制这一前提，见 nix/nixos-module.nix）。

三、从源码编译

使用 stack（官方推荐的跨平台方案）

stack 使用 Stackage 快照lts-22.34，编译前请确保git在$PATH（原因见本文开头）。基本命令：

stack build # 只编译二进制 stack haddock # 编译二进制并生成文档

若希望自动把二进制复制到$PATH中的目录：

stack install # 编译并复制

从 kmonad.cabal 可以看到可执行文件目标kmonad（入口为 app/Main.hs），默认启用-threaded -rtsopts -with-rtsopts=-N线程运行时。Linux 下会编译 C 源 c_src/keyio.c 并链接unix、hinotify依赖；Windows 下编译 c_src/keyio_win.c 并链接Win32。因此无论哪个平台，编译环境都需要 C 编译器（gcc）。

使用 nix

若使用 Nix 包管理器（独立安装或 NixOS），可以：

nix build nix

在 macOS 上，需要让 nix 拉取 Karabiner 子模块：

nix build "./nix?submodules=1"

若要把 KMonad 作为 flake input 配置 Darwin 系统，可能需要使用git+https://…?submodules=1&dir=nix形式的引用（dir=nix指向仓库 nix 子目录）而非常规的github:…引用。这一要求的根源在 nix/flake.nix：Darwin 构建需要检查c_src/mac/Karabiner-DriverKit-VirtualHIDDevice/include子模块是否存在，否则会报错退出。从 nix/flake.nix 可见 flake 支持的系统包括x86_64-linux、aarch64-linux、x86_64-darwin、aarch64-darwin，且提供了ghc96、ghc98、ghc910三个编译器的kmonad-<compiler>变体。

另一种 nix 用法是进入开发环境后用 stack 编译：

nix-shell nix/shell.nix

注：无论哪种方式都需要安装gcc以编译少量 C 代码。

静态编译

项目不定期发布可在任何 Linux 上运行、不依赖系统动态库的静态二进制。若你想针对 HEAD 自行编译静态版本，将 nix/static 目录内容复制到 KMonad 项目根目录，然后执行：

$(nix build --no-link -A fullBuildScript)

nix/static/default.nix 的实现基于static-haskell-nix（固定了ghc865编译器与指定 hackage 快照），通过 stack2nix 生成构建脚本后产出static_package；对应的 nix/static/stack.yaml 使用lts-14.7快照。注意 nix/static-compilation.nix 是同一构建逻辑的独立副本，两者指向的源码目录不同，使用时以你实际复制的目录为准。

使用 Docker

已安装 Docker 时，无需在本机安装任何工具链即可完成编译——构建容器内置全部构建工具与依赖。这非常适合：没有现成二进制、想尝试其他分支、不想安装构建工具或系统缺少对应工具链等场景。也可用提供的 Dockerfile 做开发测试。注意：构建出的镜像只用于编译KMonad，不用于运行KMonad。

在克隆后的仓库根目录执行：

# 步骤 1：构建包含二进制的 Docker 镜像 docker build -t kmonad-builder -f ci/Dockerfile.linux . # 步骤 2：从镜像启动一个临时容器，把容器内编译出的二进制复制到宿主机当前目录挂载的 output 目录 mkdir output docker run --rm -v ${PWD}/output:/host/ kmonad-builder bash -c 'cp -vp /output/* /host/' # 步骤 3：清理不再需要的构建镜像 docker rmi kmonad-builder

编译完成后，output目录中会出现kmonad二进制。查看 ci/Dockerfile.linux 可知其流程：基于alpine-haskell:9.4.8，先修改 stack.yaml 与 kmonad.cabal（追加-split-sections、ld-options: -static以减小体积），再用stack --system-ghc构建依赖与install --local-bin-path=/output产出静态二进制。

新版 Docker 甚至可以直接从公开仓库 URL 构建镜像，无需先 clone：

docker build -t kmonad-builder -f ci/Dockerfile.linux '<kmonad 仓库地址>'

然后照常执行步骤 2、3。

Podman 注意事项

若使用 Podman，bind-mount 复制二进制时必须禁用标签（SELinux labels）：

podman run --rm -it -v ${PWD}:/host/ --security-opt label=disable kmonad-builder bash -c 'cp -vp /root/.local/bin/kmonad /host/'

与 Docker 版本的差异在于：需要加--security-opt label=disable，且容器内复制源路径不同（/root/.local/bin/kmonad）。

Windows 环境

Windows 上可用 Haskell 平台配合 mingw（提供gcc）编译，装好后stack build即可。更省事的路线是用 scoop 安装 MSYS2、Haskell 与 stack，在 PowerShell 中依次执行：

# 设置运行脚本所需权限（scoop 安装器要求） Set-ExecutionPolicy RemoteSigned -scope CurrentUser # 安装 scoop（无需管理员权限） iwr -useb get.scoop.sh | iex # 安装 stack scoop install stack # 克隆 KMonad 仓库（假设已安装 git） cd $HOME\Downloads git clone <kmonad 仓库地址> cd kmonad # 编译 KMonad（首次会下载 GHC 和 msys2，耗时较长） stack build # 编译产物位于 .\.stack-work\install\xxxxxxx\bin\ # 安装 kmonad.exe（复制到 %APPDATA%\local\bin\） stack install # 运行 kmonad.exe kmonad.exe .\path\to\config.kbd

此外，仓库还提供 Windows 交叉编译用的 ci/Dockerfile.windows：基于 Debian 12，通过 wine 运行 cabal 来构建 Windows 二进制（因为 MSYS2 在 wine 下不可用，改用 cabal + stackage），并启用executable-stripping与split-sections压缩体积。这是 Linux 主机上产出 Windows 版本的可行路径。

macOS

支持的 macOS 版本与扩展选型

KMonad 支持 macOS 10.12–10.15（Sierra、High Sierra、Mojave、Catalina）与 11.0（Big Sur）；使用 driverkit 扩展 v5.0.0 及之后版本时，还支持 macOS 13.0（Ventura）、14.0（Sonoma）与 15.0（Sequoia）。

macOS 下 KMonad 依靠两种"系统扩展"之一向系统发送按键事件：

• kext（内核扩展）：用于 Catalina 及更早版本，随 KMonad 以子模块形式捆绑在c_src/mac/Karabiner-VirtualHIDDevice；
• dext（DriverKit 扩展）：用于 Catalina 及更新版本，捆绑在c_src/mac/Karabiner-DriverKit-VirtualHIDDevice。

因此必须根据 macOS 版本安装 kext 或 dext 之一（Catalina 用户两者皆可）。这一选择直接对应 kmonad.cabal 中的两个构建 flag：kext与dext，分别编译 c_src/mac/kext.cpp 或 c_src/mac/dext.cpp（dext 使用 C++2a 标准，并链接CoreFoundation、IOKit框架）。

安装 kext

kext 由 Karabiner-Elements 项目维护，因此若你已安装 Karabiner-Elements，可能已具备兼容的 kext。用以下命令核对版本：

$ kextstat | grep Karabiner

若输出包含org.pqrs.driver.Karabiner.VirtualHIDDevice.v061000 (6.10.0)，则已安装的 kext 与 KMonad 兼容，可直接跳到"安装 kmonad"；其他版本可能也可用（但未经过测试）。从源码自行构建并签名 kext 难度较大（macOS 要求使用 "Apple Developer ID" 签名才会加载），官方推荐直接安装维护者签名的二进制：

$ git clone --recursive <kmonad 仓库地址> $ cd c_src/mac/Karabiner-VirtualHIDDevice $ make install

安装 dext

dext 同样由 Karabiner-Elements 维护。检查是否已安装兼容版本：

$ defaults read /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/Info.plist CFBundleVersion

若显示5.0.0，则兼容并可直接进入"安装 kmonad"；其他版本可能也可用（未经过测试）。dext 自行构建签名只有持有 "Apple Developer ID" 才能完成（除非构建旧版本），因此推荐安装预构建的签名 pkg：

$ git clone --recursive <kmonad 仓库地址>

$ cd kmonad/ $ open c_src/mac/Karabiner-DriverKit-VirtualHIDDevice/dist/Karabiner-DriverKit-VirtualHIDDevice-5.0.0.pkg

$ /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate

若激活失败（例如已安装更新版本），把activate换成forceActivate重试；仍不行则需临时禁用 System Integrity Protection（SIP）后安装。

从 4.0.0 版本起，dext 安装不再自动管理守护进程，需要手动启动：

$ sudo '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Daemon'

Karabiner-DriverKit-VirtualHIDDevice 仓库提供了 Launch Agent plist 文件，可用于开机自动启动该守护进程。

编译并安装 kmonad

macOS 下目前仅支持stack编译（nix 方式未测试也未规划；Hackage 安装未测试）。步骤：

$ git clone --recursive <kmonad 仓库地址> $ brew install haskell-stack

然后针对所用扩展选择对应 flag 编译并安装到~/.local/bin/（请确保该目录在$PATH中）：

使用 kext 时：

$ cd kmonad/ $ stack install --flag kmonad:kext

使用 dext 时：

$ cd kmonad/ $ stack install --flag kmonad:dext

--recursive克隆在此处是硬性要求：kext/dext 以 git 子模块形式存在（对应 kmonad.cabal 中的include-dirs引用），缺少子模块将无法编译。

授予 kmonad 额外权限

自 macOS 10.5（Leopard）起，截获按键事件需要 root 权限，因此必须以sudo等方式以 root 运行 kmonad。项目未来可能实现权限分离，使只有 KMonad 的极小一部分需要 root 权限。

自 macOS 10.15（Catalina）起，捕获按键事件还需在系统偏好设置中显式授权：在系统偏好设置>安全性与隐私>隐私>输入监控中，启用你将用来执行 kmonad 的应用程序。

四、安装后的运行与验证

Linux 上二进制就绪后，最小运行方式为：

$ kmonad /path/to/config.kbd

• 编写配置时可先用kmonad -d config.kbd做纯解析检查（不启动守护进程），该行为在 src/KMonad/App/Main.hs 中体现为dryRun时只加载配置、不启动应用循环；
• Linux 若报设备权限错误，请按 doc/faq.md 检查：uinput组是否存在（sudo groupadd --system uinput）、用户是否在input,uinput组、udev 规则是否正确、uinput内核模块是否加载（sudo modprobe uinput）；
• 需要开机自启时，可使用仓库 startup/ 中针对 systemd（kmonad@.service，Restart=always、Nice=-20，实例名为配置文件名的模板单元）、runit（run）与 openrc（kmonad）的示例脚本；NixOS 用户则直接使用上文的服务模块即可。

结语

KMonad 的安装路径覆盖了从"开箱即用二进制"到"发行版声明式管理"再到"任意平台源码编译"的全谱系。本文所有命令与配置均以当前仓库实际内容为准：Linux 权限模型可对照 doc/faq.md，NixOS 声明式细节可深入 nix/nixos-module.nix，构建链路可查看 kmonad.cabal、stack.yaml 与 ci/ 下的两个 Dockerfile。选择适合你的路径，完成安装后即可开始编写自己的.kbd键位配置（语法见 keymap/tutorial.kbd）。

• 开发工具