Looking Glass 客户端 Linux 安装指南：从 `make install` 到用户级部署

• 音视频
• 图形学

导读

本文是 Looking Glass（KVMFR，即 KVM FrameRelay 实现）Linux 客户端的完整安装指南。Looking Glass 客户端负责在 Linux 主机上接收 Windows 虚拟机中由 Looking Glass 服务端采集的画面并显示，同时承载输入、音频、叠加层（overlay）与可选的 SPICE 服务。读完本文，你将掌握从源码构建产物出发的两种安装方式——系统级安装与用户级安装，理解make install背后的 CMake 安装规则、.desktop启动器与调试文件（.debug）的部署位置，并能独立完成安装后的验证、启动与卸载。

说明：本文对应仓库 doc/install_client.rst 的安装章节，并补充了 doc/build.rst 的构建流程与 client/CMakeLists.txt 的安装实现细节，供读者对照查阅。

安装前的定位：客户端与服务端的分工

在进入安装步骤前，先明确客户端在整个架构中的角色（参见 doc/install_client.rst 与 doc/build_host.rst）：

• Looking Glass Client（客户端）：运行在 Linux 主机上，接收来自 Windows 虚拟机中 Looking Glass 服务端实现传输的帧，并负责显示、输入、音频、叠加层及可选的 SPICE 服务。
• Looking Glass Host（服务端，旧称 Host Application）：运行在 Windows 虚拟机内，是采集与发送端的服务程序。注意Host在这里指的是"被客户端连接的服务端应用"，不是指宿主机操作系统。常见的部署形态是：宿主机 OS 上运行虚拟机，客户端应用跑在宿主机 OS，服务端应用跑在虚拟机内；Looking Glass 也支持虚拟机对虚拟机的形态。

典型工作流为：先启动 Windows 虚拟机及其显示驱动（IDD），再启动客户端，客户端默认通过 LGMP 协议在/dev/kvmfr0设备上自动通信（详见 doc/usage.rst）。

先决条件：客户端需要先构建

截至当前仓库版本，客户端没有现成的 Linux 发行版软件包，安装必须以源码构建的产物为前提（doc/install_client.rst 明确说明 "There are currently no Linux distribution packages for the client"）。因此完整的安装路径是：

1. 按 doc/build.rst 的指引从源码构建客户端；
2. 在构建目录中执行安装命令；
3. 配置运行环境并启动验证。

构建要点（完整步骤见 doc/build.rst）：

# 在仓库根目录下创建构建目录并配置 mkdir client/build cd client/build cmake ../ make

构建产物包括：

• looking-glass-client：客户端主二进制，用于显示来自虚拟机的帧；
• looking-glass-client.debug：调试符号文件。必须与对应二进制配套保留，才能在崩溃栈回溯中获得源码位置；安装目标会自动将其放到标准的bin/.debug位置。

构建期有两个常见注意点，也与安装结果直接相关：

• GNOME on Wayland 用户可开启 libdecor 支持（cmake -DENABLE_LIBDECOR=ON ../），以获得更完整的窗口装饰支持（详见 doc/build.rst 及 FAQ）；
• 编译报错常见于 backtrace 支持，可尝试cmake -DENABLE_BACKTRACE=0 ../关闭后重新构建。

构建完成的二进制可以直接从构建目录运行：

./looking-glass-client

方式一：系统级安装（make install）

在构建目录中，以 root 权限执行：

make install

这是文档给出的标准安装方式。默认前缀由 CMake 的GNUInstallDirs模块决定（通常为/usr/local），具体行为可查看 client/CMakeLists.txt 中的安装规则。

make install实际做了什么

从源码看，安装目标（install target）共注册了四类内容（client/CMakeLists.txt）：

其中.desktop模板（resources/looking-glass-client.desktop.in）的关键字段如下：

[Desktop Entry] Type=Application Name=Looking Glass Client Comment=Clent for Looking Glass KVMFR Icon=looking-glass Exec=@CMAKE_INSTALL_PREFIX@/bin/looking-glass-client Terminal=false Keywords=KVM Categories=System; StartupWMClass=looking-glass-client SingleMainWindow=true

注意Exec行中的@CMAKE_INSTALL_PREFIX@会在 CMake 配置阶段被替换为实际安装前缀，因此系统级安装与用户级安装生成的.desktop内容会指向各自对应的可执行文件路径。

调试符号由构建阶段的POST_BUILD自定义命令生成（client/CMakeLists.txt）：objcopy --only-keep-debug提取调试信息到.debug文件，strip --strip-debug精简主二进制，最后objcopy --add-gnu-debuglink在二进制中写入指向.debug的链接。这也是安装规则把.debug放到bin/.debug的原因——GDB 等调试器会沿.gnu_debuglink在该标准位置寻找符号。

验证安装结果

系统级安装完成后可执行：

which looking-glass-client looking-glass-client --help

--help会列出当前安装构建支持的全部选项（命令行选项优先级高于配置文件，详见 doc/usage.rst）。

方式二：用户级安装（仅当前用户）

如果当前用户没有 root 权限，或者希望把客户端限制在个人账户内，可以在配置阶段指定用户级前缀：

cmake -DCMAKE_INSTALL_PREFIX="$HOME/.local" .. make install

关键点 1：前缀在配置阶段决定

CMAKE_INSTALL_PREFIX是 CMake 配置（configure）阶段的变量，必须在cmake时传入，而不是在执行make install时传入。若构建目录已经用其他前缀配置过，需要先重新配置（或换一个全新的构建目录），否则安装目标仍会使用旧前缀。

关键点 2：.desktop启动器随前缀联动

由于 resources/looking-glass-client.desktop.in 中的Exec使用了@CMAKE_INSTALL_PREFIX@，用户级构建生成的.desktop会指向$HOME/.local/bin/looking-glass-client，不会与其他用户的安装冲突。

关键点 3：PATH 必须包含用户级 bin 目录

用户级安装后，可执行文件位于$HOME/.local/bin。文档明确提示：使用用户级安装时，必须确保$HOME/.local/bin在PATH中，否则 shell 无法找到looking-glass-client命令。

可以在当前 shell 会话中临时加入：

export PATH="$HOME/.local/bin:$PATH"

持久化则写入 shell 配置文件（如~/.bashrc、~/.zshrc）：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

修改后需重新加载配置（source ~/.bashrc）或重新登录使生效。

安装后的启动与验证

安装完成后即可按 doc/usage.rst 的指引启动：

# 在 Windows 虚拟机与 IDD 运行起来之后 looking-glass-client

客户端会自动选择传输设备：/dev/kvmfr0可用时默认走 LGMP over/dev/kvmfr0，否则回退到/dev/shm/looking-glass。需要指定其他设备时：

looking-glass-client -f /dev/kvmfr1

常见验证手段：

• looking-glass-client --help查看当前构建支持的全部选项；
• 按ScrLk（默认逃逸键）进入或退出捕获模式，长按ScrLk可查看可用命令（如ScrLk+Q退出、ScrLk+F切换全屏）；
• 若键盘没有ScrLk，可通过input:escapeKey或-m修改逃逸键。

卸载客户端

客户端工程通过 cmake/UninstallTarget.cmake 注册了uninstall自定义目标（client/CMakeLists.txt第 26 行通过include(UninstallTarget)引入）。在构建目录中执行：

make uninstall

其实现（cmake/uninstall.cmake.in）读取构建目录下的install_manifest.txt，逐条删除安装时落地的文件（包括二进制、.debug调试文件、.desktop启动器与图标），并支持DESTDIR环境变量。若提示找不到install_manifest.txt，说明当前构建目录从未执行过安装，无需卸载。

常见问题与排错

• looking-glass-client: command not found：多发生在用户级安装后忘记配置PATH。检查$HOME/.local/bin是否在PATH中，或直接以绝对路径运行$HOME/.local/bin/looking-glass-client。
• 安装位置与预期不符：确认cmake配置时-DCMAKE_INSTALL_PREFIX是否按需指定，系统级默认前缀通常为/usr/local；变更前缀需要重新配置构建目录。
• 崩溃时无法定位源码：检查bin/.debug/looking-glass-client.debug是否与二进制同版本配套存在；若构建时关闭了 backtrace（-DENABLE_BACKTRACE=0），需用gdb手动获取回溯。
• GNOME on Wayland 窗口装饰异常：构建时用cmake -DENABLE_LIBDECOR=ON ../启用 libdecor 支持后重新安装。

延伸阅读

• 客户端构建完整流程：doc/build.rst
• 客户端日常使用、默认按键与配置文件：doc/usage.rst
• 旧版服务端构建（legacy Host Application）：doc/build_host.rst
• 客户端安装规则源码：client/CMakeLists.txt
• 桌面启动器模板：resources/looking-glass-client.desktop.in
• 卸载目标实现：cmake/UninstallTarget.cmake 与 cmake/uninstall.cmake.in

• 音视频
• 图形学