GlosSI 构建指南：从 prebuild.ps1 到 CMake，完整解析 Windows 与 Linux 下的编译流程-育师

桌面应用
游戏开发

【免费下载链接】GlosSI

Tool for using Steam-Input controller rebinding at a system level alongside a global overlay

项目地址：https://gitcode.com/gh_mirrors/gl/GlosSI

GlosSI（Global systemwide Steam Input）是一套将 Steam-Input 手柄重映射提升到系统级、并附带全局 Steam Overlay 的 Windows 工具。docs/BUILDING.md是官方给出的唯一构建入口文档，本篇以该文档为主线，结合仓库中的构建脚本与项目工程文件，完整还原从克隆仓库到产出可运行程序的全部步骤，并深入剖析每个预构建脚本背后实际做了什么。读完本篇，你能够独立搭建出 GlosSI 的完整开发环境，理解其子模块依赖链、版本号自动生成机制，以及首次构建可能失败的根因。

构建体系总览：一个解决方案，六个工程

从解决方案文件 GlosSI.sln 的结构可以确认，GlosSI 由六个 MSBuild 工程组成：

工程	职责（结合仓库结构推断）
`GlosSITarget`	核心目标程序，注入游戏后负责虚拟手柄与 Overlay 窗口
`GlosSIConfig`	基于 Qt 6.X 的图形配置工具（唯一依赖 Qt 的工程）
`CEFInjectLib`	CEF 注入库，`GlosSITarget`与`GlosSIWatchdog`均声明了对它的依赖
`GlosSIWatchdog`	看门狗模块，依赖`CEFInjectLib`
`UWPOverlayEnablerDLL`	为 Windows Store 应用启用 Overlay 的 DLL
`common`	公共库，包含 HidHide、Steam 工具函数、设置头等

解决方案支持Debug/Release × x64/x86四种配置组合。GlosSIConfig在 x86 平台下会复用 x64 的 ActiveCfg（Release|x86.ActiveCfg = Release|x64），从源码结构看，该工程实际只面向 64 位构建。

同时，.gitmodules声明了 15 个 git 子模块，全部位于deps/目录下，其中包括一个自定义 fork 的 SFML（Alia5/SFML，而非官方仓库）、ViGEmClient、WinReg、spdlog、subhook、ValveFileVDF、Shortcuts_VDF、imgui/imgui-sfml、json、cpp-httplib、easywsclient、traypp、fifo_map等。这解释了构建文档中反复强调的“不要使用系统已安装的 SFML”的原因——仓库依赖的是维护者自行 fork 的 SFML 版本。

Windows 构建

环境依赖清单

官方文档列出的 Windows 侧需求如下：

git：用于管理上述 15 个子模块；
Visual Studio 2022（Community 版本即可）：提供 MSBuild 工具链；
Qt 6.X：仅GlosSIConfig工程需要；
Qt Visual Studio addin：仅GlosSIConfig工程需要，使 VS 能识别 Qt 工程的 MOC/UIC/RCC 步骤。

关于 Qt 版本有一个额外的实现细节：GlosSI.sln 的ExtensibilityGlobals段记录了Qt5Version = 6.2.2_msvc2019_64，而发布打包脚本 build.ps1 中显式引用了C:\Qt\6.3.1\msvc2019_64\bin路径并调用windeployqt.exe部署 QML。因此“Qt 6.X”的取值范围可以推断为 6.2/6.3 这一档，且必须是msvc2019_64构建。

标准构建流程

在“Developer PowerShell for VS 2022”（而非普通 PowerShell）中执行以下命令：

git submodule init git submodule update --recursive .\prebuild.ps1 # Open GlosSI.sln and hit build! Invoke-Item GlosSI.sln

前两条命令拉取全部子模块，prebuild.ps1完成依赖库预编译，最后打开解决方案手动构建即可。官方文档特别提醒：

Note: It can be the case that the first build fails as there are versioning files created when building. Just hit build again and you should be good to go!

这个现象并非玄学，原因见下一节的版本文件机制。

prebuild.ps1：预构建脚本逐项解析

prebuild.ps1 是 Windows 构建链路的核心，其执行顺序与各步骤的作用如下：

git submodule init git submodule update --recursive --force .\buildSFML.ps1 .\buildViGEmClient.ps1 cd deps/traypp git apply ../../traypp_unicode.patch cd ../../ cd .\GlosSIConfig\ ..\version_help.ps1 # 若不存在则生成 steamgrid_api_keys.h（内容取自 $env:STEAMGRIDDB_KEY） if (!(Test-Path 'steamgrid_api_keys.h')) { ... } cd ../ # 若仓库根目录没有 steamgrid.exe，则下载 steamgrid v3.4.0 并解压 if (!(Test-Path 'steamgrid.exe')) { ... }

子模块同步：与文档命令一致，但追加了--force，保证本地被污染的子模块也能对齐到记录版本。
buildSFML.ps1：进入deps/SFML，用 CMake 分别构建 Debug 与 RelWithDebInfo 两套 SFML。注意脚本通过$env:_CL_="/MDd"/$env:_CL_="/MD"显式切换运行时库链接方式，确保自编译的 SFML 与 MSVC 默认 CRT 配置兼容。另外脚本中保留了针对 AppVeyor CI 的分支（$env:APPVEYOR），本地构建会跳过 Debug 构建，只产 Release。
buildViGEmClient.ps1：先在deps/ViGEmClient上应用仓库根目录的 ViGEm_BuildConfig.patch（修改 ViGEmClient 的构建配置），再用msbuild.exe以Debug_LIB/Release_LIB配置、x64平台分别构建静态库。这一步产出的 ViGEm 静态库是common等工程链接虚拟总线驱动 API 的前提。
traypp 打补丁：对deps/traypp（系统托盘库）应用 traypp_unicode.patch，从源码结构看是为了修复其 Unicode 支持。
版本信息生成：调用GlosSIConfig\..\version_help.ps1（即 version_help.ps1），见下文详述。
SteamGridDB API Key 头文件：如果GlosSIConfig/steamgrid_api_keys.h不存在，则自动生成一个包含inline const char* steamgridb_key = ""$env:STEAMGRIDDB_KEY""的头文件。也就是说，SteamGridDB 的 Key 是通过环境变量注入编译期的，没有设置$env:STEAMGRIDDB_KEY也能通过构建（Key 为空字符串），只是相关功能不可用。
steamgrid.exe 工具下载：若仓库根目录没有steamgrid.exe，则从 steamgrid v3.4.0 的发布包下载并用7z解出steamgrid.exe——这是一个构建期即完成的外部工具拉取动作。

首次构建可能失败的原因：版本文件的“先有鸡还是先有蛋”

version_help.ps1 是理解官方那句“首次构建可能失败”的关键。它做了四件事：

通过git describe --tags --always取得版本标签；若标签不是X.Y.Z.W四段格式，则补前缀0.0.0.；
把标签中的点替换为逗号、连字符与字母替换为0，回写GlosSIConfig/Resource.rc中的FILEVERSION与PRODUCTVERSION；
若../version.hpp不存在则创建，否则覆盖更新，内容包含VERSION_STR、IS_SNAPSHOT及 major/minor/patch/revision 四个常量；
若存在Installer/Installer.nsi，则同步其中的!define VERSION "..."。

也就是说version.hpp等版本文件是构建过程自身生成的产物，首次编译时它们可能尚不存在或不完整，导致引用它们的编译单元报错；脚本跑过一遍之后再次构建即正常。这正好印证了 BUILDING 文档中“再点一次 Build 即可”的提示。

驱动与运行依赖

编译产物之外，运行 GlosSI 还需要安装两个系统级组件（官方文档原文列出）：

ViGEmBusSetup_x64.exe：ViGEm 虚拟总线驱动，GlosSI 依赖它创建系统级虚拟 Xbox360 手柄；
HidHideMSI.exe：HidHide 设备隐藏组件，用于让游戏看不到物理手柄、只看到虚拟手柄。

两者可以从 ViGEm 官网下载，也可以直接用仓库自带的 download_release_deps.ps1 一条命令拉取。该脚本的实际内容与版本号为：

Invoke-WebRequest -o ViGEmBusSetup_x64.exe https://...ViGEmBus_1.22.0_x64_x86_arm64.exe Invoke-WebRequest -o HidHideSetup.exe https://...HidHide_1.4.192_x64.exe Invoke-WebRequest -o vc_redist.x64.exe https://aka.ms/vs/16/release/vc_redist.x64.exe

可以看到脚本额外拉取了VC++ 2015-2022 运行时 Redist，这是发布包分发给终端用户时保证目标机器具备 C++ 运行时的做法；本地开发机上 VS 2022 已自带，通常无需安装。

适用前提说明：仓库 README 已声明 ViGEm 项目进入 End of Life，GlosSI 对其的依赖（ViGEm + HidHide）是其核心功能的基础，因此按本文档构建出的版本属于“停止维护前的构建”，读者应了解这一背景。

Linux 构建

官方文档对此的定位非常明确：Linux 支持目前基本没有真正实现，构建能否成功没有保证（很可能已损坏），未来计划提供“非常有限”的 Linux 支持。以下流程原样继承自文档：

GlosSITarget（CMake 路径）

git submodule init git submodule update --recursive # build custom fork of SFML # do not use SFML you might've already installed ./buildSFML.sh cd GlosSITarget cmake -S . -B build cmake --build build

两个关键点都有源码佐证：

buildSFML.sh与 Windows 的buildSFML.ps1不同，它会同时构建 Debug 和 RelWithDebInfo 两套 SFML（cmake -S . -B out/Debug/out/Release），因为 Linux 下没有_CL_之类的运行时切换手段，两套都产出最稳妥；
GlosSITarget/CMakeLists.txt要求 CMake ≥ 3.7.2、C++20，且只编译main.cpp、SteamTarget.cpp、TargetWindow.cpp三个源文件，头文件指向../deps/SFML/include，并按CMAKE_BUILD_TYPE链接../deps/SFML/out/Debug/lib或out/Release/lib下的sfml-system/window/graphics。从源码结构看，Linux 版 CMake 工程只覆盖了 Windows 版 GlosSITarget 的一部分源文件（不含InputRedirector.cpp、Overlay.cpp等），这与“支持非常有限”的官方表述一致。

另外值得注意的一个细节：CMakeLists 中判断分支写的是if (CMAKE_BUILD_TYPE EQUAL "DEBUG")，而buildSFML.sh配置的 Debug 构型是字面量Debug（首字母大写），两种写法能否精确匹配可以存疑——这从侧面印证了“构建不保证可用”的现状。

GlosSIConfig

文档中该部分原文为TODO，即 Qt 配置工具没有 Linux 构建路径。这与 Windows 侧“Qt 6.X 仅 GlosSIConfig 需要”的说明相互呼应。

构建之外的配套脚本

为让“构建”这件事闭环，仓库还提供了几个辅助脚本，理解它们有助于判断构建产物的去向：

build.ps1：发布级一键构建。流程为清理x64\Release→ 执行prebuild.ps1→ 以_CL_="/MD"构建解决方案 Release x64 → 进入SteamTweaks执行npm i && npm run build（该 TS 子项目用 Rollup 打包，见 SteamTweaks/package.json）→ 用windeployqt部署 QML → 拷贝 SFML 三个 Release DLL、驱动安装包与许可证文件，形成最终可分发的产物集。可以推断，本地开发只关心GlosSI.sln的构建结果，SteamTweaks 的 npm 构建只在发布打包链路中出现；
Installer/buildInstaller.ps1：把NSIS\Bin加入 PATH 后执行makensis.exe Installer.nsi，基于 Installer/Installer.nsi 生成GlosSI-Installer.exe（主程序入口为GlosSIConfig.exe）；其中的!define VERSION由前述version_help.ps1自动同步；
tail_target_logs.ps1/tail_config_logs.ps1：分别实时跟踪%appdata%\GlosSI\GlosSItarget.log等日志文件，构建后排查行为问题时直接可用。

构建核对清单

按docs/BUILDING.md完成构建后，建议逐项核对：

子模块：git submodule status中 15 个子模块（deps/下全部）均为已检出状态，SFML 指向Alia5/SFML的 fork 而非官方仓库；
预构建产物：deps/SFML/out/Release、deps/ViGEmClient的静态库已生成；traypp_unicode.patch与ViGEm_BuildConfig.patch已成功git apply；
版本文件：仓库根目录存在version.hpp，GlosSIConfig/Resource.rc中的FILEVERSION与GlosSIConfig/steamgrid_api_keys.h已生成；
驱动：ViGEmBus 1.22.0 与 HidHide 1.4.192 已安装（可用download_release_deps.ps1下载）；
构建配置：解决方案选择 Release|x64 后成功编译，若首次失败按官方提示再构建一次即可。

Windows 侧的构建链路（git 子模块 → SFML/ViGEm 预编译 → 补丁 → 版本生成 → VS 解决方案构建）在脚本层面是自洽且可重复的；Linux 侧则仅有 GlosSITarget 的 CMake 骨架路径，且官方明确不保证可用性。对于需要精确控制构建行为的读者，直接阅读prebuild.ps1、buildSFML.*、version_help.ps1这三个文件即可掌握全部构建细节。