Cua 项目 Hyprland 插件 Arch 本地开发包从 monorepo 精确版本钉扎构建到 ABI 校验与显式加载【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua导读本文围绕 Cua 仓库中 Arch 本地开发配方 展开讲解如何从一个显式的 Cua monorepo 检出点构建可选的 Hyprland 插件并通过「精确 Hyprland 包版本 精确 pkg-config 头版本」双重钉扎来保证插件与当前运行合成器的 ABI 严格匹配。读完本文你将掌握该配方的环境变量约定、makepkg -si的完整构建流程、PKGBUILD 中prepare/build/check/package四阶段的实际校验逻辑、hyprctl的显式加载/检查/卸载操作以及 Fleet 镜像消费该配方时必须遵守的版本记录与验收基线。配方定位monorepo 本地开发包而非 AUR 包该目录下的arch/PKGBUILD是一个仅面向本地开发的打包配方。它在设计上明确不适合直接进 AUR 或二进制仓库原因有三点见 packaging/arch/README.md 的说明没有远程源码归档与校验和替换机制——源码直接来自本地CUA_SOURCE_ROOT指向的 monorepo 检出不承诺与其他机器的 ABI 兼容性——插件是针对「当前这台机器上实际运行的 Hyprland」构建的包版本号带 release 后缀且属于钉扎的一部分不能靠猜。Hyprland 插件以动态库形态加载进合成器进程跨 ABI 版本的插件必须「fail closed」而不是尝试运行。插件 README 进一步说明见 hyprland-plugin/README.md加载检查会比较 Hyprland 完整的客户端/服务端 ABI 指纹包括合成器 commit 和链接的 Hyprland 库版本然后才调用其他合成器 API由于 Hyprland 通过插件 API 传递 C 对象编译器工具链族与版本也必须与构建 Hyprland 的一致。这正是该配方坚持「在运行 Omarchy/Arch 会话的机器上本地构建」的根本原因。快速开始三个环境变量与一条命令配方要求先安装当前运行会话所用的精确 Hyprland 包与开发头文件然后按如下方式构建export CUA_SOURCE_ROOT/path/to/cua export CUA_HYPRLAND_PACKAGE_VERSION$(pacman -Q hyprland | cut -d -f2-) export CUA_HYPRLAND_HEADER_VERSION0.56.2 makepkg -si三个变量的含义与用途如下与 PKGBUILD 中的取值逻辑一一对应变量含义PKGBUILD 中的使用CUA_SOURCE_ROOTCua monorepo 根目录绝对路径prepare()中通过realpath -e解析并要求该目录下存在libs/cua-driver/hyprland-plugin/CMakeLists.txt否则报错退出CUA_HYPRLAND_PACKAGE_VERSIONpacman -Q hyprland报告的完整包版本含 release 后缀写入depends(hyprland版本)prepare()再次用pacman -Q hyprland实测比对不一致立即失败CUA_HYPRLAND_HEADER_VERSION头文件版本默认0.56.2可覆盖prepare()用pkg-config --modversion hyprland实测比对不一致立即失败同时作为-DCUA_HYPRLAND_EXPECTED_VERSION传给 CMake注意CUA_HYPRLAND_PACKAGE_VERSION通过pacman -Q hyprland | cut -d -f2-取的是第二个空格之后的部分即版本-发布号它必须与系统实际安装的包完全一致——这是配方刻意设计的「精确依赖冲突」用来防止把旧合成器 ABI 的模块带进新版本。PKGBUILD 四阶段逐段解析完整的 PKGBUILD 很短但信息密度很高四个函数分别承担不同的职责。包元数据与选项pkgnamecua-hyprland-plugin-local pkgver0.1.0 pkgrel1 pkgdescDiscovery-only Cua integration for an exact local Hyprland ABI arch(x86_64 aarch64) license(MIT) makedepends(cmake ninja pkgconf binutils) options(!strip !debug !lto) source() sha256sums()包名带-local后缀与 packaging/release 目录中的独立发布配方区分开——后者是面向生产输入候选的无 monorepo 版本source()为空再次印证「不从网络取源码」!strip/!debug/!lto与 CMakeLists.txt 中-fno-lto、ELF 校验逻辑呼应插件必须保留可被readelf/ldd检查的符号与动态段且 LTO 会在与合成器 ABI 对齐时引入不确定性。prepare()双重版本实测比对prepare() { [[ -f ${_plugin_source}/CMakeLists.txt ]] || { ... return 1; } installed_hyprland$(LC_ALLC pacman -Q hyprland 2/dev/null | cut -d -f2-) [[ $installed_hyprland $_hyprland_package_version ]] || { ... return 1; } header_version$(pkg-config --modversion hyprland 2/dev/null) [[ $header_version $_hyprland_header_version ]] || { ... return 1; } }这一阶段做三件事验证CUA_SOURCE_ROOT确实指向包含插件源码的 monorepo验证实际安装的 Hyprland 包版本与声明的钉扎一致验证pkg-config 报告的头版本与声明的头版本一致。任何一项不匹配都会带着预期值与实际值直接return 1杜绝「猜版本」导致的静默 ABI 漂移。build()CMake Ninja 版本钉扎build() { cmake \ -S $_plugin_source \ -B $srcdir/build \ -G Ninja \ -DCMAKE_BUILD_TYPERelease \ -DCUA_HYPRLAND_EXPECTED_VERSION$_hyprland_header_version cmake --build $srcdir/build }CUA_HYPRLAND_EXPECTED_VERSION是 CMake 侧的钉扎点。在 CMakeLists.txt 中当该变量非空时会执行pkg_check_modules(HYPRLAND REQUIRED IMPORTED_TARGET hyprland${CUA_HYPRLAND_EXPECTED_VERSION})头版本不符则配置直接失败CMake 还会通过cmake/DetectHyprlandAPI.cmake编译探测已安装的PluginAPI.hpp在 Hyprland0.56.2的SHyprCtlCommand旧 API 与新版 Socket1 API 之间自动选择适配层未知命令 API 同样配置失败且探测在每次重新配置时重复执行防止头文件升级后复用缓存的旧层级。check()构建期即跑 CTestcheck() { ctest --test-dir $srcdir/build --output-on-failure }配方在打包前强制运行配置好的 CTest 套件涵盖协议二进制解析零长度/边界/超限、坏 magic、不支持版本、截断、队列饱和、断开、socket 放置与0600权限、SO_PEERCRED同 UID 校验、发现型拒绝路径所有变更形态必须返回background_unavailable且不改变焦点/层级/光标等测试计划详见 tests/README.md。这意味着makepkg --nocheck之类的捷径在该配方下无法绕过测试。package()只安装两样东西package() { DESTDIR$pkgdir cmake --install $srcdir/build --prefix /usr install -Dm644 $_source_root/LICENSE.md \ $pkgdir/usr/share/licenses/$pkgname/LICENSE }最终包只包含/usr/lib/cua/hyprland/cua-hyprland-plugin.so /usr/share/licenses/cua-hyprland-plugin-local/LICENSE配方不修改任何 Hyprland 配置、不自动加载插件、不创建服务或 hook。安装即止剩下的加载动作完全交给操作者显式执行。显式加载、检查与卸载加载、检查、卸载是三个独立的显式操作配方文档给出了对应命令hyprctl plugin load /usr/lib/cua/hyprland/cua-hyprland-plugin.so hyprctl -j cua:status hyprctl plugin unload /usr/lib/cua/hyprland/cua-hyprland-plugin.sohyprctl plugin load把模块显式加载进当前 Hyprland 实例hyprctl -j cua:status是插件权威的运行时状态面见 hyprland-plugin/README.md消费者在连接前必须检查其合成器 epoch、协议版本、通告能力、socket 路径、discovery-only 状态与 ABI 身份。仅仅「模块已加载」不能证明目标发现或输入变更可用hyprctl plugin unload显式卸载对输入候选而言卸载会关闭 socket 并立即断开所有连接。在本地开发构建非打包场景下把命令中的模块路径换成 CMake 输出的实际路径即可例如hyprctl plugin load $PWD/build/cua-hyprland-plugin.so。在把plugin 配置行写进 Hyprland 配置之前务必先在一个可丢弃的会话中完成 ABI 匹配与状态检查不匹配的模块可能被 Hyprland 拒绝或在加载时失败。另外需要强调的是该插件默认构建是 discovery-only它只通告协议状态与存活negotiation、status、liveness所有输入变更请求都会以类型化结果background_unavailable拒绝。默认本地传输同样是关闭的要在可丢弃会话中演练协商需在 Omarchy 的 Lua 配置中加入hl.config({plugin {cua {enabled true}}})或对传统 Hyprland 配置使用plugin:cua:enabled true然后执行hyprctl reload——插件在配置重载时才会协调传输状态仅靠运行时hyprctl eval或keyword无法启动/停止它。Hyprland 升级后重建而非复用配方文档对此给出了一条铁律每次 Hyprland 升级后必须移除或重建该本地包再加载。这是因为depends(hyprland精确版本)会制造有意的精确依赖冲突——它存在的目的就是防止把旧合成器 ABI 模块带到新版本前。CMake 构建出的模块同样不应跨 Hyprland 升级保留或分发而应针对升级后的包重新构建hyprland-plugin/README.md 亦明确「Do not retain or redistribute the resulting module across a Hyprland upgrade」。如果加载失败发生在 Hyprland 升级之后正确做法是保持未加载状态 → 针对新的精确包重建 → 重试便携版 Cua Driver 不依赖该插件依然可用。Fleet 镜像消费与初始验收基线该配方同样服务于 Fleet 镜像生产。文档要求 Fleet 满足以下几点在CUA_SOURCE_ROOT提供已记录的候选源码并记录其 Git SHA消费同一个 monorepo 配方或派生的已评审配方钉扎镜像内精确的 Hyprland 包默认保持插件不加载使用与 Hyprland 构建一致的编译器族与版本——即使包、头文件、完整 ABI 指纹、C26 语言模式全部匹配不同 C 工具链依然不可互换。初始验收镜像的精确基线来自 packaging/arch/README.md在 hyprland-plugin/README.md 的验收表中同样列出组件要求基线Omarchy4.0.2-1Hyprland0.56.2xdg-desktop-portal-hyprland1.4.1Cua Driver0.23.2会话与显示管理器UWSM / SDDM该基线是验收目标不是「该主机已通过验证」的声明更不代表稳定版0.23.2或 nightly 中已提供隔离后台输入。插件在常规构建中始终是 discovery-only。Fleet 打包车道的完整验收要求仅安装在/usr/lib/cua/hyprland/、显式加载/状态检查/协商/重连/卸载/干净重启、模拟 Hyprland 包变更后的精确 ABI 依赖失败、双实例 socket 隔离与跨 UID 拒绝、全部发现型变更拒绝见 tests/README.md 的「Fleet packaging lane」一节之后的裸机 Omarchy 物理机终检含 GTK3/GTK4/Qt6/LibreOffice/Chromium/Electron/DPMS-off/一次性与长生命周期图形会话客户端等逐行验证是最终验收闸门虚拟机或 Fleet 成功不能替代它。与独立发布配方的区别仓库中还存在另一条打包路径packaging/release 目录生成无 monorepo 检出的独立源码包用于生产输入候选CUA_HYPRLAND_INPUTON它要求下载cua-hyprland-plugin-DRIVER_VERSION-COMMIT_SHA.tar.gz与 build-kit 两个归档、校验 SHA256、并在钉扎的 Arch 环境中以/usr/bin/g或CUA_RELEASE_CXX指定的编译器构建其USAGE.md详细描述了生命周期闸门lifecycle.py、全新会话激活、升级/回滚/卸载流程见 release/USAGE.md。而arch/PKGBUILD保持为discovery-only 的本地配方两者刻意分离本地配方面向开发调试release 配方面向按 profile 钉扎的发布示例 profile 中记录了hyprland 0.56.2-2、GCC16.2.1、libstdc.so.6.0.36以及aquamarine/hyprutils/glibc等运行时 ABI 包集合。无论哪条路径构建前都要先在目标环境排布好钉扎的依赖配方本身不会安装工具链或改动运行时搜索路径。常见误区与安全边界小结结合配方文档、hyprland-plugin/README.md 与 tests/README.md有几个容易被忽略的要点版本必须实测CUA_HYPRLAND_PACKAGE_VERSION来自pacman -Q hyprlandCUA_HYPRLAND_HEADER_VERSION来自pkg-config --modversion hyprland两者都被prepare()二次实测校验手动拼一个「看起来对的版本」必然失败。「精确依赖冲突」是特性升级后直接--force越过依赖安装旧模块正是配方要阻止的操作正确的路径是重建。加载不等于可用hyprctl -j cua:status中的协议版本、能力列表、socket 路径、epoch、ABI 身份才是消费者决定是否连接的依据。ACK 不等于投递传输层的确认只证明收到并校验通过应用层行为必须依赖独立的类型化结果与状态证据tests/README.md 第 10 条专门测试了这一点。工具链不可互换即使包、头文件、ABI 指纹与 C26 模式全部对齐不同 GCC 家族/版本仍然可能因 C 对象布局差异导致加载失败或未定义行为——配方与 CMakeLists.txt 中cmake/VerifyRuntime.cmake的 ELF 依赖检查拒绝静态 C 运行时、要求与合成器解析到同一共享运行时字节正是为此设计。掌握以上要点后你可以在自己的 Omarchy/Arch 会话中安全地构建、加载、检查与卸载cua-hyprland-plugin-local并在每次 Hyprland 升级时按照「移除旧包 → 用新的精确版本重建 → 显式重新加载并检查状态」的循环完成 ABI 安全的迭代。【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考