Solaar 项目安装指南：从基础到高级配置

前言

Solaar 是一个用于管理 Logitech Unifying 接收器及其配对设备的开源工具，支持设备配对、配置设置等功能。本文将详细介绍 Solaar 的多种安装方式及注意事项，帮助用户根据自身需求选择合适的安装方案。

一、通过 PyPI 安装（推荐新手）

对于大多数用户而言，通过 Python 包索引 PyPI 安装是最简单的方式：

1. 确保已安装 pip 工具
2. 执行以下命令之一：

   pip install --user solaar
   

   或

   pipx install --system-site-packages solaar
   

重要补充：安装后需要手动处理 udev 规则：

1. 将 ~/.local/lib/udev/rules.d/42-logitech-unify-permissions.rules 复制到 /etc/udev/rules.d/
2. 对于 Wayland 用户，建议使用项目中的 uinput udev 规则以获得更好的输入模拟支持

二、macOS 平台特殊说明

macOS 支持有限功能（设备配对和配置设置）：

1. 通过 pip 安装 Solaar
2. 使用 Homebrew 安装依赖：

   brew update
   brew install hidapi gtk+3 pygobject3
   

注意：规则系统和 diversion 功能在 macOS 上不可用。

三、从源码安装（适合开发者/高级用户）

3.1 获取源码

使用 git 克隆项目仓库。

3.2 使用 Makefile 简化安装

项目提供了便捷的 Makefile 命令：

1. 安装系统依赖（根据发行版选择）：

   make install_apt    # Debian/Ubuntu
   make install_dnf   # Fedora
   make install_brew  # macOS
   

2. 安装 udev 规则：

   make install_udev          # X11 环境
   make install_udev_uinput  # Wayland 环境
   

3. 安装 Solaar：

   make install_pip   # 常规安装
   make install_pipx  # 使用 pipx 隔离安装
   

3.3 直接运行

无需安装即可从源码目录运行：

bin/solaar        # 启动 GUI
bin/solaar <command> <arguments>  # 使用 CLI

四、系统要求详解

4.1 内核要求

• 需要较新内核（建议 5.2+）
• 必须加载 hid-logitech-dj 和 hid-logitech-hidpp 模块
• 启用 CONFIG_HIDRAW 选项
• 需要 udev 服务运行

4.2 Python 环境

• Python 3.7+
• 必需包：
  • pyudev
  • psutil
  • python-xlib
  • evdev
  • typing-extensions
  • dbus-python
  • PyYAML

4.3 GUI 额外需求

• Gtk3 及其 GObject 绑定
• 系统托盘支持库（推荐 ayatana-appindicator）
• 桌面通知支持（可选）

4.4 特殊说明

• 不要通过 pip 安装 hid-parser，项目已包含修改版
• 推荐安装 python-git-info 以获取更好的版本信息显示
• X11 环境下功能最完整，Wayland 支持有限

五、手动配置 udev 规则

对于高级用户或自定义安装：

1. 复制对应规则文件到 /etc/udev/rules.d/
   • X11: rules.d/42-logitech-unify-permissions.rules
   • Wayland: rules.d-uinput/42-logitech-unify-permissions.rules
2. 重载 udev 规则：

   sudo udevadm control --reload-rules
   

六、多语言支持

如需非英语界面：

1. 运行 tools/po-compile.sh 编译翻译文件
2. 设置 LANGUAGE 环境变量

七、开机自启动配置

可通过以下方式实现：

1. 系统级：安装 .desktop 文件到 /etc/xdg/autostart/
2. 用户级：在用户 autostart 目录创建启动项

结语

本文涵盖了 Solaar 从简单到高级的各种安装方式，用户可根据自身技术水平和需求选择合适的方案。对于大多数桌面用户，推荐通过 PyPI 安装；开发者或需要最新功能的用户可选择源码安装方式。安装过程中如遇问题，可参考详细的系统要求部分检查依赖是否满足。