企业官网建设流程全解析

• 桌面应用

SDL（Simple DirectMedia Layer）的“奇偶版本策略”（odd/even versioning policy）决定了它的 2.x 系列中哪些版本可放心用于生产、哪些只是开发中的预发布分支。本文以仓库内 SDL 官方文档 README-versions.md 为骨架，完整继承其 2.23.0 之后与之前的版本规则，并结合 QKeyMapper 实际集成的 SDL 2.32.10 二进制发行包（SDL2-version.txt、SDL_version.h、SDL.pri 等），讲清版本号每个字段的含义、编译期/运行期如何验证版本，以及升级 SDL 时应当遵循的兼容性判断。读完本文，你可以独立判断任意一个 SDL 2.x 版本号是稳定版还是预发布版，并能在 Qt 项目中确认实际链接的 SDL 版本。

一、版本号的三段结构与奇偶规则（Since 2.23.0）

SDL 从 2.23.0 开始采用类似 GLib、GTK、Flatpak 以及早期 Linux 内核的“奇偶版本策略”。版本号MAJOR.MINOR.PATCH三段中，奇偶规则的判断对象是小版本（第二段，MINOR）：

• 主版本（MAJOR）：当向后兼容性被破坏时才递增，这种情况很少发生；
• 小版本（MINOR）可被 2 整除（例如 2.24.x、2.26.x）：表示稳定版，被认为适合生产环境使用。
  • 补丁版本（PATCH，第三段）表示 bugfix 发布；bugfix 发布不应增加或移除 ABI，因此.0发布（例如 2.24.0）应与其同一周期的所有 bugfix 发布（例如 2.24.1）保持前向兼容；
  • 小版本递增发生在新增 API 或 ABI、或发生其他重要变更时。新的小版本向后兼容、但不完全前向兼容——用 SDL 2.24.x 编译的程序可以正常运行在 2.26.x 上，反之用 2.26.x 编译的程序不一定能在 2.24.x 上运行。
• 小版本（MINOR）不可被 2 整除（例如 2.23.x、2.25.x）：表示开发预发布版（prerelease），不适合稳定的软件发行版，使用时需谨慎。
  • 补丁版本随每个预发布递增；
  • 每个预发布可能新增 API 和/或 ABI；
  • 预发布版与更旧的稳定分支保持向后兼容（例如 2.25.x 兼容 2.24.x）；
  • 预发布版之间不保证相互兼容——2.25.1 新增的 API 或 ABI 可能在 2.25.2 中被移除或修改。如果你不能接受这种不确定性，就不要使用预发布版；
  • 只有当你能保证及时跟进其后的稳定版时，才应升级到预发布版。例如：除非你能在 2.24.0 发布后立刻升级，否则不要升级到 2.23.x；
  • 有版本冻结政策的软件发行版（特别是有发布周期的 Linux 发行版，如 Debian 和 Fedora）通常只应打包稳定版，而非预发布版。

一句话速记：小版本偶数是稳定版，奇数是预发布版；补丁号只表示 bugfix 或预发布序列的推进。

二、Before 2.23.0：规则曾经作用于补丁位

2.23.0 之前的 SDL 版本遵循相似的政策，但奇偶规则的作用对象不同：它作用于**补丁位（第三段，patchlevel/micro version）**而非小版本。例如 2.0.22 是稳定版，而 2.0.21 是预发布版。理解这一历史差异很重要：如果你在旧代码或旧文档中见到“用第三段奇偶判断稳定性”的写法，那对应的是 2.23.0 之前的策略；从 2.23.0 起必须改看第二段。

三、仓库中的实际版本：SDL 2.32.10 是多处一致的证据链

QKeyMapper 通过第三方 Qt 库 QJoysticks 间接依赖 SDL2（该库负责手柄枚举与状态轮询），而 SDL2 以“预编译二进制发行包”的形式内置在仓库中，而非源码编译。可以从以下多处相互印证的工件确认当前集成版本为2.32.10：

1. 版本说明文件：SDL2-version.txt 内容为SDL2-devel-2.32.10-VC，即 Visual C++ 平台、2.32.10 的 SDL2 开发包；

2. 头文件版本宏：SDL_version.h 中定义了

   #define SDL_MAJOR_VERSION 2 #define SDL_MINOR_VERSION 32 #define SDL_PATCHLEVEL 10

   按第一节的规则：32 可被 2 整除，属于稳定分支；这与项目“面向 Win10/Win11 生产可用”的定位一致——仓库只打包偶数稳定分支，不含任何预发布分支；

3. CMake 版本校验：sdl2-config-version.cmake 会在find_package(SDL2)时读取include/SDL_version.h，用正则提取SDL_MAJOR_VERSION、SDL_MINOR_VERSION、SDL_PATCHLEVEL三个宏拼装出PACKAGE_VERSION（本包即为 2.32.10），再与调用方要求的版本做比较（小于要求版本则判定不兼容），并强制检查目标架构的 32/64 位宽度是否匹配；

4. qmake 链接规则：SDL.pri 负责把发行包接入 Qt 构建：INCLUDEPATH指向include目录；在 Windows 下额外定义SDL_SUPPORTED与SDL_MAIN_HANDLED（表明WinMain由 SDL 接管，这是使用 SDL 的 Windows GUI 程序的常规要求），并按目标架构分别链接lib/x64或lib/x86下的SDL2库；

5. 运行时二进制：QKeyMapper/QJoysticks/lib/SDL/lib/x64/与x86/目录中分别存放对应架构的SDL2.dll、SDL2.lib、SDL2.pdb以及SDL2main.lib、SDL2test.lib。

四、编译期与运行期的版本验证

SDL 提供两套版本机制，用途不同：

1）编译期：SDL_VERSION()宏SDL_VERSION(x)是一个宏，用它填充SDL_version结构体记录的是“程序针对哪套头文件编译”的版本。由于它由头文件宏展开，编译后即可确定；动态链接时，运行时的实际库版本可能略新或略旧。

2）运行期：SDL_GetVersion()SDL_version.h 中声明的SDL_GetVersion()返回实际链接的 SDL 版本。在动态链接场景下，它是判断“运行时 DLL 是否满足要求”的唯一可靠手段。

结合仓库内版本 2.32.10，一段典型的运行期校验可以写成：

SDL_version compiled, linked; SDL_VERSION(&compiled); // 2.32.10（来自 SDL_version.h） SDL_GetVersion(&linked); // 实际加载的 SDL2.dll 版本 // 要求运行时库不高于编译版本（避免使用了编译期不存在的新 API 语义） if (linked.major > compiled.major || (linked.major == compiled.major && linked.minor > compiled.minor) || (linked.major == compiled.major && linked.minor == compiled.minor && linked.patch > compiled.patch)) { /* 运行时库比编译期更新，需要人工评估兼容性 */ }

3）版本比较宏：SDL_version.h 还定义了SDL_VERSION_ATLEAST(X, Y, Z)，用于在条件编译中判断“是否针对至少 X.Y.Z 的 SDL 编译”。需要注意的编码陷阱：旧式的SDL_COMPILEDVERSION（基于SDL_VERSIONNUM数值化）在 2.9.0 之后小版本会“溢出”进千位——例如 2.23.0 被编码为 4300，因此头文件注释明确建议弃用它、改用SDL_VERSION_ATLEAST或SDL_VERSION，且该旧宏在 SDL 3.x 中将被移除（#if SDL_MAJOR_VERSION < 3条件块中的 TODO 注释已注明）。这也提示：版本比较永远走结构化比较（逐段比较 major/minor/patch），不要走数值拼接。

五、对 QKeyMapper 集成的工程影响

从源码结构看，SDL 是 SDL_Joysticks.cpp 中手柄输入路径的基础：构造函数里调用SDL_Init(SDL_INIT_GAMECONTROLLER)初始化游戏控制器子系统，随后加载gamecontrollerdb.txt数据库（通过SDL_GameControllerAddMapping逐行注册映射）以及按平台选择通用回退映射，再由 100ms 的QTimer周期触发update()轮询手柄状态。这意味着：

• 版本策略直接影响输入功能可用性：控制器触摸板事件（如SDL_CONTROLLERTOUCHPADDOWN等）属于较新 API，只有较新的小版本才可用。仓库锁定在稳定分支 2.32.x，正是奇偶规则推荐的“只打包偶数小版本”做法在 Windows 侧的体现——文档中该条虽然针对 Debian/Fedora 等 Linux 发行版，但对“随发行版分发的 Windows 桌面软件”同样是合理的版本治理原则；
• 升级 SDL 的操作路径：若要升级，需同时替换lib/x64与lib/x86两套二进制、include头文件、cmake配置，并保持 SDL.pri 中INCLUDEPATH、LIBS路径与SDL_MAIN_HANDLED等定义不变；升级前按第二节的兼容方向判断——用旧版（如 2.32.x）编译的 QJoysticks 代码可运行于更新的偶数稳定版（如 2.34.x），反之不保证；
• 不要引入奇数小版本：如果手头只有 2.33.x 这类预发布分支，按 README-versions.md 的要求，仅在你能立即跟进其后的 2.34.0 稳定版时才可使用，否则维持 2.32.10 这类稳定版。

六、结论

SDL 的版本治理可以浓缩为三条可执行规则：

1. 看第二段（2.23.0 起）：偶数小版本 = 稳定可用，奇数小版本 = 预发布，谨慎使用；
2. 补丁位只做 bugfix：稳定分支内的.N升级不会改变 ABI，可以放心跟随；
3. 兼容性单向：低版本编译 → 高版本运行可行，反向不保证；预发布之间甚至互相都不保证。

QKeyMapper 仓库内置的 SDL 2.32.10 正是按这套规则选择的偶数稳定分支，其版本号在 SDL2-version.txt、SDL_version.h、sdl2-config-version.cmake 三处工件中保持一致，可作为“如何核验一个预编译 SDL 发行包版本与文档宣称是否一致”的完整示例。

• 桌面应用