SerenityOS 移植 ProTracker 2 克隆pt2-clone 补丁深度解析【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenitySerenityOS 通过 Ports 系统将大量第三方软件移植到自有内核与用户态之上其中 pt2-cloneProTracker 2 克隆版本 1.63的移植依赖两个针对性补丁分别解决构建产物输出路径与鼠标坐标获取两个问题。本文以 Ports/pt2-clone/patches/ReadMe.md 为骨架结合补丁原文、package.sh与 Ports 构建框架源码完整解析这两个补丁的动机、实现细节与自动应用机制读完你不仅能理解 pt2-clone 移植的全部适配点还能掌握为任意第三方软件编写 SerenityOS 移植补丁的通用套路。pt2-clone 与 SerenityOS Ports 移植背景pt2-clone 是经典 Amiga 音乐制作软件 ProTracker 2 的克隆实现在 Ports/AvailablePorts.md 中被标注为 ProTracker 2 clone移植版本为 1.63。它使用 C 语言编写、基于 SDL2 渲染界面因此移植到 SerenityOS 时以 SDL2 port 为首要依赖。SerenityOS 的每个移植包都位于Ports/port/目录下由一个package.sh脚本描述全部构建信息。pt2-clone 的 package.sh 内容如下#!/usr/bin/env -S bash ../.port_include.sh portpt2-clone version1.63 files( https://github.com/8bitbubsy/pt2-clone/archive/v${version}.tar.gz#3834da77ef5d84fcf0ff2531dbb21283aa62a8bcbbf46e55c7317f3ce1adfd47 ) useconfiguretrue depends( SDL2 ) configure() { run cmake \ -DCMAKE_TOOLCHAIN_FILE${SERENITY_BUILD_DIR}/CMakeToolchain.txt } install() { run make install }其中files数组声明了上游源码包 URL 及其 SHA256 校验和下载后会被校验防止内容被篡改depends声明 SDL2 依赖installdepends阶段会自动先安装configure覆盖默认实现直接调用 CMake 并传入SERENITY_BUILD_DIR/CMakeToolchain.txt交叉编译工具链文件让 CMake 以 SerenityOS 为目标平台构建。补丁在构建流程中的自动应用机制理解补丁本身之前先要弄清 SerenityOS 的 Ports 框架如何应用这些补丁。根据 Ports/README.md 的说明./package.sh patch选项会应用该 port 的patches/*.patch文件。其底层实现在 Ports/.port_include.sh 的patch_internal函数中patch_internal() { if [ -n ${IN_SERENITY_PORT_DEV:-} ]; then return fi # patch if it was not yet patched (applying patches multiple times doesnt work!) if [ -d ${PORT_META_DIR}/patches ]; then for filepath in ${PORT_META_DIR}/patches/*.patch; do filename$(basename $filepath) if [ -f $workdir/.${filename}_applied ]; then continue fi if [ -e ${workdir}/.git ]; then run git am --keep-cr --keep-non-patch ${filepath} else run patch -p$patchlevel $filepath run touch .${filename}_applied fi done fi ... }这段框架代码揭示了几条关键规则按文件名顺序应用patches/*.patch的展开顺序即应用顺序这就是为什么补丁以0001-、0002-数字前缀编号保证依赖关系先修构建、再改运行时不会被打乱幂等保护每次成功应用后会在$workdir下创建.${filename}_applied标记文件重复运行patch步骤时会跳过已应用的补丁两种应用方式若源码目录是 git 仓库dev模式下用git am --keep-cr --keep-non-patch以提交形式应用普通模式下用patch -p$patchlevelpatchlevel默认值为 1即剥离路径中的第一级目录对应补丁 diff 中a/、b/前缀。此外./package.sh dev命令Ports/.port_include.sh会提供一个交互式开发环境在打补丁后的 git 仓库中修改代码退出时用git format-patch自动重新生成补丁并通过generate_patch_readme选项自动生成/更新patches/ReadMe.md——本文所述的这份说明文档正是由该机制生成的标准格式## \补丁文件名 加提交说明。补丁一移除 CMakeLists 中的硬编码输出路径0001-Remove-output-path-from-CMakeLists.patch 是构建系统的适配补丁完整内容如下From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 From: EWouters 6179932EWoutersusers.noreply.github.com Date: Tue, 5 Apr 2022 14:41:31 0200 Subject: [PATCH] Remove output path from CMakeLists --- CMakeLists.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 70e74b6b6a032a95720eb956115383dee949677d..c631945566dd2bb84f4f92f8dfad1a6186492489 100644 --- a/CMakeLists.txt b/CMakeLists.txt -5,7 5,6 project(pt2-clone) option(EXTERNAL_LIBFLAC use external(system) flac library OFF) find_package(SDL2 REQUIRED) -set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${pt2-clone_SOURCE_DIR}/release/other/) file(GLOB pt2-clone_SRC ${pt2-clone_SOURCE_DIR}/src/*.c上游 pt2-clone 通过set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ...)将可执行文件强制输出到源码树下的release/other/目录以与其官方发布版的目录布局保持一致。这一约定在 SerenityOS 的交叉编译环境下会带来两个问题污染宿主源码目录pt2-clone_SOURCE_DIR指向下载解压后的源码目录产物会被写到该目录而非构建目录破坏了 CMake 的 out-of-source 构建约定破坏安装流程SerenityOS 的默认install步骤会执行make install并将文件装入DESTDIR即SERENITY_INSTALL_ROOT指向的系统根目录参见 Ports/.port_include.sh产物位置不可控会导致安装脚本无法找到可执行文件。因此该补丁删除这一行让 CMake 使用默认的输出目录随后make install即可将pt2-clone可执行文件正确安装到 SerenityOS 系统中。这是一个非常典型的上游构建约定与目标系统安装约定冲突类移植适配。补丁二Hacky Mouse——禁用桌面鼠标坐标0002-Hacky-Mouse.patch 是运行时行为的适配补丁修改的是src/pt2_visuals.c中的视频初始化函数From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 From: EWouters 6179932EWoutersusers.noreply.github.com Date: Tue, 5 Apr 2022 14:55:01 0200 Subject: [PATCH] Hacky Mouse Set video.useDesktopMouseCoords to false. --- src/pt2_visuals.c | 2 - 1 file changed, 1 insertion(), 1 deletion(-) diff --git a/src/pt2_visuals.c b/src/pt2_visuals.c index 012a2d7e2b5acad85aeadff43938dc175c6772cb..dcc7bef94d884cffedd60e9f1153a72050caf017 100644 --- a/src/pt2_visuals.c b/src/pt2_visuals.c -1980,7 1980,7 bool setupVideo(void) } // Workaround: SDL_GetGlobalMouseState() doesnt work with KMSDRM/Wayland - video.useDesktopMouseCoords true; video.useDesktopMouseCoords false; const char *videoDriver SDL_GetCurrentVideoDriver(); if (videoDriver ! NULL (strcmp(KMSDRM, videoDriver) 0 || strcmp(wayland, videoDriver) 0)) video.useDesktopMouseCoords false;从补丁上下文可以还原上游逻辑setupVideo()默认把video.useDesktopMouseCoords置为true即通过SDL_GetGlobalMouseState()获取桌面全局坐标来定位鼠标代码中原有的注释指出该 API 在 KMSDRM/Wayland 这类无桌面合成器的驱动下不可靠因此上游只为这两种驱动做了兜底。SerenityOS 的 SDL2 移植见 Ports/SDL2/package.sh运行在自研窗口系统之上从移植实践可以推断其视频驱动同样无法稳定提供桌面全局鼠标坐标。因此这个简单粗暴Hacky的补丁把默认值直接改为false让 pt2-clone 始终使用 SDL 窗口内的相对鼠标坐标——这既绕开了不可靠的全局坐标 API又避免了依赖上层注释中的驱动名判断属于典型的以最小改动换取最大兼容性的运行时适配。代价是所有平台统一走窗口内坐标路径对需要精确全局坐标的场景会有所影响但作为移植补丁完全可接受。安装与验证在已构建好 SerenityOS具备SERENITY_BUILD_DIR构建环境的前提下进入 port 目录直接运行即可完成依赖安装、源码下载校验、补丁应用、CMake 配置、编译与安装全流程cd Ports/pt2-clone ./package.sh流程中对应执行的是installdepends、fetch、patch、configure、build、install六个步骤参见 Ports/README.md 的说明。若只需单独验证补丁应用情况可以分步执行./package.sh fetch # 下载并校验 v1.63 源码包 ./package.sh patch # 应用 patches/ 下两个补丁应用成功后pt2-clone-1.63源码目录中会出现.0001-Remove-output-path-from-CMakeLists.patch_applied与.0002-Hacky-Mouse.patch_applied两个标记文件对应 Ports/.port_include.sh 中的幂等逻辑并可在CMakeLists.txt中确认输出路径行已被移除、在src/pt2_visuals.c中确认video.useDesktopMouseCoords false。在 SerenityOS 系统中运行pt2-clone即可启动 ProTracker 2 克隆界面。从 pt2-clone 看第三方软件移植的通用补丁套路结合这份补丁说明与 Ports 框架源码可以总结出 SerenityOS 移植第三方软件时补丁的两大典型类别与配套工具链构建适配类如 0001处理上游构建系统与 SerenityOS 交叉编译/安装约定的冲突常见手法是删除硬编码路径、替换工具链、禁用不兼容的选项可对比 SDL2 port 中-DPULSEAUDIOOFF、-DJACKOFF等配置化禁用手段原理一致运行时适配类如 0002处理上游代码依赖的目标平台能力如全局鼠标坐标 API在 SerenityOS 上不可用的问题以最小 diff 切换到等价实现。而补丁的维护完全由 Ports 框架托管用./package.sh dev进入开发环境修改代码退出时框架自动用git format-patch重新生成patches/*.patch并通过do_generate_patch_readmePorts/.port_include.sh从补丁提交信息中提取 Subject 与正文自动生成本文所解析的ReadMe.md。这套补丁即提交、文档自动生成、应用幂等可重入的机制保证了数百个第三方移植包在 SerenityOS 上长期可维护。【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SerenityOS 移植 ProTracker 2 克隆：pt2-clone 补丁深度解析
SerenityOS 移植 ProTracker 2 克隆pt2-clone 补丁深度解析【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenitySerenityOS 通过 Ports 系统将大量第三方软件移植到自有内核与用户态之上其中 pt2-cloneProTracker 2 克隆版本 1.63的移植依赖两个针对性补丁分别解决构建产物输出路径与鼠标坐标获取两个问题。本文以 Ports/pt2-clone/patches/ReadMe.md 为骨架结合补丁原文、package.sh与 Ports 构建框架源码完整解析这两个补丁的动机、实现细节与自动应用机制读完你不仅能理解 pt2-clone 移植的全部适配点还能掌握为任意第三方软件编写 SerenityOS 移植补丁的通用套路。pt2-clone 与 SerenityOS Ports 移植背景pt2-clone 是经典 Amiga 音乐制作软件 ProTracker 2 的克隆实现在 Ports/AvailablePorts.md 中被标注为 ProTracker 2 clone移植版本为 1.63。它使用 C 语言编写、基于 SDL2 渲染界面因此移植到 SerenityOS 时以 SDL2 port 为首要依赖。SerenityOS 的每个移植包都位于Ports/port/目录下由一个package.sh脚本描述全部构建信息。pt2-clone 的 package.sh 内容如下#!/usr/bin/env -S bash ../.port_include.sh portpt2-clone version1.63 files( https://github.com/8bitbubsy/pt2-clone/archive/v${version}.tar.gz#3834da77ef5d84fcf0ff2531dbb21283aa62a8bcbbf46e55c7317f3ce1adfd47 ) useconfiguretrue depends( SDL2 ) configure() { run cmake \ -DCMAKE_TOOLCHAIN_FILE${SERENITY_BUILD_DIR}/CMakeToolchain.txt } install() { run make install }其中files数组声明了上游源码包 URL 及其 SHA256 校验和下载后会被校验防止内容被篡改depends声明 SDL2 依赖installdepends阶段会自动先安装configure覆盖默认实现直接调用 CMake 并传入SERENITY_BUILD_DIR/CMakeToolchain.txt交叉编译工具链文件让 CMake 以 SerenityOS 为目标平台构建。补丁在构建流程中的自动应用机制理解补丁本身之前先要弄清 SerenityOS 的 Ports 框架如何应用这些补丁。根据 Ports/README.md 的说明./package.sh patch选项会应用该 port 的patches/*.patch文件。其底层实现在 Ports/.port_include.sh 的patch_internal函数中patch_internal() { if [ -n ${IN_SERENITY_PORT_DEV:-} ]; then return fi # patch if it was not yet patched (applying patches multiple times doesnt work!) if [ -d ${PORT_META_DIR}/patches ]; then for filepath in ${PORT_META_DIR}/patches/*.patch; do filename$(basename $filepath) if [ -f $workdir/.${filename}_applied ]; then continue fi if [ -e ${workdir}/.git ]; then run git am --keep-cr --keep-non-patch ${filepath} else run patch -p$patchlevel $filepath run touch .${filename}_applied fi done fi ... }这段框架代码揭示了几条关键规则按文件名顺序应用patches/*.patch的展开顺序即应用顺序这就是为什么补丁以0001-、0002-数字前缀编号保证依赖关系先修构建、再改运行时不会被打乱幂等保护每次成功应用后会在$workdir下创建.${filename}_applied标记文件重复运行patch步骤时会跳过已应用的补丁两种应用方式若源码目录是 git 仓库dev模式下用git am --keep-cr --keep-non-patch以提交形式应用普通模式下用patch -p$patchlevelpatchlevel默认值为 1即剥离路径中的第一级目录对应补丁 diff 中a/、b/前缀。此外./package.sh dev命令Ports/.port_include.sh会提供一个交互式开发环境在打补丁后的 git 仓库中修改代码退出时用git format-patch自动重新生成补丁并通过generate_patch_readme选项自动生成/更新patches/ReadMe.md——本文所述的这份说明文档正是由该机制生成的标准格式## \补丁文件名 加提交说明。补丁一移除 CMakeLists 中的硬编码输出路径0001-Remove-output-path-from-CMakeLists.patch 是构建系统的适配补丁完整内容如下From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 From: EWouters 6179932EWoutersusers.noreply.github.com Date: Tue, 5 Apr 2022 14:41:31 0200 Subject: [PATCH] Remove output path from CMakeLists --- CMakeLists.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 70e74b6b6a032a95720eb956115383dee949677d..c631945566dd2bb84f4f92f8dfad1a6186492489 100644 --- a/CMakeLists.txt b/CMakeLists.txt -5,7 5,6 project(pt2-clone) option(EXTERNAL_LIBFLAC use external(system) flac library OFF) find_package(SDL2 REQUIRED) -set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${pt2-clone_SOURCE_DIR}/release/other/) file(GLOB pt2-clone_SRC ${pt2-clone_SOURCE_DIR}/src/*.c上游 pt2-clone 通过set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ...)将可执行文件强制输出到源码树下的release/other/目录以与其官方发布版的目录布局保持一致。这一约定在 SerenityOS 的交叉编译环境下会带来两个问题污染宿主源码目录pt2-clone_SOURCE_DIR指向下载解压后的源码目录产物会被写到该目录而非构建目录破坏了 CMake 的 out-of-source 构建约定破坏安装流程SerenityOS 的默认install步骤会执行make install并将文件装入DESTDIR即SERENITY_INSTALL_ROOT指向的系统根目录参见 Ports/.port_include.sh产物位置不可控会导致安装脚本无法找到可执行文件。因此该补丁删除这一行让 CMake 使用默认的输出目录随后make install即可将pt2-clone可执行文件正确安装到 SerenityOS 系统中。这是一个非常典型的上游构建约定与目标系统安装约定冲突类移植适配。补丁二Hacky Mouse——禁用桌面鼠标坐标0002-Hacky-Mouse.patch 是运行时行为的适配补丁修改的是src/pt2_visuals.c中的视频初始化函数From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 From: EWouters 6179932EWoutersusers.noreply.github.com Date: Tue, 5 Apr 2022 14:55:01 0200 Subject: [PATCH] Hacky Mouse Set video.useDesktopMouseCoords to false. --- src/pt2_visuals.c | 2 - 1 file changed, 1 insertion(), 1 deletion(-) diff --git a/src/pt2_visuals.c b/src/pt2_visuals.c index 012a2d7e2b5acad85aeadff43938dc175c6772cb..dcc7bef94d884cffedd60e9f1153a72050caf017 100644 --- a/src/pt2_visuals.c b/src/pt2_visuals.c -1980,7 1980,7 bool setupVideo(void) } // Workaround: SDL_GetGlobalMouseState() doesnt work with KMSDRM/Wayland - video.useDesktopMouseCoords true; video.useDesktopMouseCoords false; const char *videoDriver SDL_GetCurrentVideoDriver(); if (videoDriver ! NULL (strcmp(KMSDRM, videoDriver) 0 || strcmp(wayland, videoDriver) 0)) video.useDesktopMouseCoords false;从补丁上下文可以还原上游逻辑setupVideo()默认把video.useDesktopMouseCoords置为true即通过SDL_GetGlobalMouseState()获取桌面全局坐标来定位鼠标代码中原有的注释指出该 API 在 KMSDRM/Wayland 这类无桌面合成器的驱动下不可靠因此上游只为这两种驱动做了兜底。SerenityOS 的 SDL2 移植见 Ports/SDL2/package.sh运行在自研窗口系统之上从移植实践可以推断其视频驱动同样无法稳定提供桌面全局鼠标坐标。因此这个简单粗暴Hacky的补丁把默认值直接改为false让 pt2-clone 始终使用 SDL 窗口内的相对鼠标坐标——这既绕开了不可靠的全局坐标 API又避免了依赖上层注释中的驱动名判断属于典型的以最小改动换取最大兼容性的运行时适配。代价是所有平台统一走窗口内坐标路径对需要精确全局坐标的场景会有所影响但作为移植补丁完全可接受。安装与验证在已构建好 SerenityOS具备SERENITY_BUILD_DIR构建环境的前提下进入 port 目录直接运行即可完成依赖安装、源码下载校验、补丁应用、CMake 配置、编译与安装全流程cd Ports/pt2-clone ./package.sh流程中对应执行的是installdepends、fetch、patch、configure、build、install六个步骤参见 Ports/README.md 的说明。若只需单独验证补丁应用情况可以分步执行./package.sh fetch # 下载并校验 v1.63 源码包 ./package.sh patch # 应用 patches/ 下两个补丁应用成功后pt2-clone-1.63源码目录中会出现.0001-Remove-output-path-from-CMakeLists.patch_applied与.0002-Hacky-Mouse.patch_applied两个标记文件对应 Ports/.port_include.sh 中的幂等逻辑并可在CMakeLists.txt中确认输出路径行已被移除、在src/pt2_visuals.c中确认video.useDesktopMouseCoords false。在 SerenityOS 系统中运行pt2-clone即可启动 ProTracker 2 克隆界面。从 pt2-clone 看第三方软件移植的通用补丁套路结合这份补丁说明与 Ports 框架源码可以总结出 SerenityOS 移植第三方软件时补丁的两大典型类别与配套工具链构建适配类如 0001处理上游构建系统与 SerenityOS 交叉编译/安装约定的冲突常见手法是删除硬编码路径、替换工具链、禁用不兼容的选项可对比 SDL2 port 中-DPULSEAUDIOOFF、-DJACKOFF等配置化禁用手段原理一致运行时适配类如 0002处理上游代码依赖的目标平台能力如全局鼠标坐标 API在 SerenityOS 上不可用的问题以最小 diff 切换到等价实现。而补丁的维护完全由 Ports 框架托管用./package.sh dev进入开发环境修改代码退出时框架自动用git format-patch重新生成patches/*.patch并通过do_generate_patch_readmePorts/.port_include.sh从补丁提交信息中提取 Subject 与正文自动生成本文所解析的ReadMe.md。这套补丁即提交、文档自动生成、应用幂等可重入的机制保证了数百个第三方移植包在 SerenityOS 上长期可维护。【免费下载链接】serenityThe Serenity Operating System 项目地址: https://gitcode.com/GitHub_Trending/se/serenity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考