feat(cursor): 第六个成员 libwayland-cursor——客户端自己的鼠标指针 (#2)

Wayland 没有服务端光标:客户端要指针,就得自己加载光标主题、把图像变成
wl_buffer、附到一个交给 wl_pointer.set_cursor 的 surface 上。这个库是前两步。
没有它,每个应用都得自己解析 XCursor 文件格式——而那正是这里的 xcursor.c。

不要和索引里的 compat.xcursor 搞混:那是 X11 的 libXcursor.so.1,要和 X 服务器
说话。这个不依赖 X,产出的是经 wl_shm 的 wl_buffer。

漏掉的原因和 libwayland-egl 一样:fork 建了合成器需要的四个成员就停了,而合成器
自己画光标。

## 与 egl 成员的关键差别:这个真的链 client

wayland-cursor.c 调 wl_shm_create_pool / wl_shm_pool_create_buffer /
wl_shm_pool_resize / wl_buffer_destroy,所以上游的
dependencies: [ wayland_client_dep ] 是链接边,不只是头。egl 成员对同一个包的
依赖只是头。两者在 manifest 里长得一样而实质不同,所以都写明了。

## 又一处编译期宿主路径

xcursor.c:493 写死

    "~/.icons:/usr/share/icons:/usr/share/pixmaps:~/.cursors:"
    "/usr/share/cursors/xorg-x11:" ICONDIR

重定位之后这些指的是**宿主的**主题,和 Vulkan 静默落到 llvmpipe 同一形状。

xcursor_library_path() 先读 getenv("XCURSOR_PATH") 且设置了就原样返回
(xcursor.c:515),所以这是兜底而非唯一入口——生态给光标主题时声明
XCURSOR_PATH,和给键盘布局声明 XKB_CONFIG_ROOT 完全对称。

所以 -DICONDIR="" -DXCURSORPATH="",空了之后没有 XCURSOR_PATH 的客户端找不到
主题、wl_cursor_theme_load 返回一个没有光标的主题——看得见,而不是「在开发者
机器上有指针、在别处没有」。

SONAME 是 .so.0 不是 .so.1:上游故意把这个库版本成 0.<minor>.<micro>,好让
wayland 1.x 永远不会逼出一次 cursor SONAME 升版,meson.build 里有注释和一个
wayland 到 2.x 就触发的 error()。

## CI

SONAME 循环加一行;新增一步逐个点名六个函数、断言 DT_NEEDED 有
libwayland-client.so.0、并 grep 二进制确认宿主光标路径确实没被编进去——最后
这条只能这么查,因为值错了的失败方式是**在恰好有 /usr/share/icons 的机器上
静默正常工作**。

本地实测:6/6 符号、链了 client、无宿主路径、三个 SONAME 全对。

Author: Sunrisepeak

.github/workflows/ci.yml

@@ -107,7 +107,8 @@ jobs:
           # ends in `.1` and would have been searched for by its full name.
           for pair in "client:libwayland-client.so.0" \
                       "server:libwayland-server.so.0" \
-                      "egl:libwayland-egl.so.1"; do
+                      "egl:libwayland-egl.so.1" \
+                      "cursor:libwayland-cursor.so.0"; do
             member=${pair%%:*}; want=${pair#*:}
             so=$(find . -name "${want%.*}" -type f | head -1)
             test -n "$so" || { echo "$member: no library built"; exit 1; }
@@ -169,6 +170,38 @@ jobs:
           fi
           echo "libwayland-egl exports exactly its own four functions"
 
+      - name: libwayland-cursor carries its six functions and no host paths
+        run: |
+          c=$(find . -name libwayland-cursor.so -type f | head -1)
+          test -n "$c" || { echo "::error::libwayland-cursor was not built"; exit 1; }
+
+          has() { readelf --dyn-syms -W "$1" | grep -q " $2$"; }
+          for f in wl_cursor_theme_load wl_cursor_theme_destroy \
+                   wl_cursor_theme_get_cursor wl_cursor_image_get_buffer \
+                   wl_cursor_frame wl_cursor_frame_and_duration; do
+            has "$c" "$f" || { echo "::error::libwayland-cursor lost $f"; exit 1; }
+          done
+
+          # It DOES link the client, unlike libwayland-egl: wayland-cursor.c
+          # calls wl_shm_create_pool and friends. A missing DT_NEEDED here would
+          # mean those calls were satisfied from somewhere else.
+          readelf -d "$c" | grep -q 'libwayland-client.so.0' || {
+            echo "::error::libwayland-cursor does not link libwayland-client"; exit 1; }
+
+          # And the compiled-in HOST cursor paths are gone. xcursor.c:493 bakes
+          # in "~/.icons:/usr/share/icons:/usr/share/pixmaps:..." unless
+          # XCURSORPATH is defined, and after relocation those name the host's
+          # themes. The recipe empties it so a theme comes from XCURSOR_PATH or
+          # not at all — and grepping the binary is the only way to see that it
+          # worked, because a wrong value here fails by SILENTLY WORKING on a
+          # machine that happens to have themes in /usr/share/icons.
+          if strings "$c" | grep -qE '/usr/share/icons|/usr/X11R6|xorg-x11'; then
+            echo "::error::a host cursor path was compiled into libwayland-cursor"
+            strings "$c" | grep -E '/usr/share/icons|/usr/X11R6|xorg-x11'
+            exit 1
+          fi
+          echo "libwayland-cursor: six functions, links the client, no host paths"
+
       - name: mcpp/generated/ matches what the scanner produces
         run: |
           # The generated protocol code is checked in because it is the

mcpp.toml

@@ -40,4 +40,9 @@ members = [
     # cover what a COMPOSITOR needs, and a compositor renders into GBM buffers
     # instead.
     "mcpp/egl",
+    # The pointer image. Wayland has no server-side cursor, so a client that
+    # wants one loads a theme itself — and without this member that means
+    # parsing the XCursor file format by hand. Missing for the same reason
+    # mcpp/egl was: a compositor draws its own cursor and never asks.
+    "mcpp/cursor",
 ]

mcpp/cursor/mcpp.toml

@@ -0,0 +1,97 @@
+# libwayland-cursor — the pointer image a Wayland client sets on itself.
+#
+# Wayland has no server-side cursor: a client that wants a pointer must load a
+# cursor theme, turn the image into a `wl_buffer`, and attach it to a surface it
+# passes to `wl_pointer.set_cursor`. This library is the first two steps, and
+# without it every application would have to parse the XCursor file format
+# itself — which is what this file's `xcursor.c` is.
+#
+# NOT the same thing as `compat.xcursor` in the index: that is X11's
+# `libXcursor.so.1`, which talks to an X server. This one has no X dependency
+# and produces a `wl_buffer` through `wl_shm`.
+#
+# It was missing for the same reason libwayland-egl was: the fork built the four
+# members a COMPOSITOR needs, and a compositor draws its own cursor.
+#
+# ─────────────────────────────────────────────────────────────────────────
+# THIS ONE REALLY LINKS THE CLIENT, unlike mcpp/egl
+#
+# `wayland-cursor.c` calls `wl_shm_create_pool`, `wl_shm_pool_create_buffer`,
+# `wl_shm_pool_resize` and `wl_buffer_destroy` — so upstream's
+# `dependencies: [ wayland_client_dep ]` is a link edge, not just headers. The
+# egl member's dependency on the same package is headers only; the two look
+# alike in the manifest and are not alike, which is why both say so.
+[package]
+namespace = "freedesktop"
+name      = "wayland-cursor"
+version   = "1.26.0"
+standard  = "c++23"
+description = "libwayland-cursor 1.26.0 — load an XCursor theme into a wl_buffer, for clients that set their own pointer"
+license   = "MIT"
+repo      = "https://github.com/mcpplibs/wayland"
+
+[build]
+sources = [
+    "../../upstream/cursor/wayland-cursor.c",
+    "../../upstream/cursor/os-compatibility.c",
+    "../../upstream/cursor/xcursor.c",
+    "src/wayland-cursor.cppm",
+]
+
+include_dirs = [
+    "../../upstream/cursor",
+    "../../upstream/src",
+    "../generated",
+]
+
+cflags = [
+    # os-compatibility.c needs memfd_create / mkostemp and does not define
+    # _GNU_SOURCE itself. The empty form for the same reason the client member
+    # uses it: the neighbouring files DO define it, and a valued -D would make
+    # each of them warn about a redefinition.
+    "-D_GNU_SOURCE=",
+
+    # The cursor theme search path, and it is EMPTY on purpose — the same
+    # decision as compat.libinput's LIBINPUT_QUIRKS_DIR and libgbm's backend
+    # path, reached for the same reason and with the same escape hatch.
+    #
+    # `xcursor.c:493` compiles in
+    #
+    #     "~/.icons:/usr/share/icons:/usr/share/pixmaps:~/.cursors:"
+    #     "/usr/share/cursors/xorg-x11:" ICONDIR
+    #
+    # — a list of HOST paths, baked in. After relocation those name the host's
+    # themes, so a sandboxed client would silently render the host machine's
+    # cursors, which is the same silent host edge that gave Vulkan an llvmpipe
+    # device instead of the GPU.
+    #
+    # `xcursor_library_path()` reads `getenv("XCURSOR_PATH")` FIRST and returns
+    # it verbatim when set (xcursor.c:515), so this is a fallback and not the
+    # only way in: an ecosystem that ships cursor themes declares XCURSOR_PATH,
+    # exactly as it declares XKB_CONFIG_ROOT for keyboard layouts.
+    #
+    # Emptied, a client with no XCURSOR_PATH finds no theme and
+    # `wl_cursor_theme_load` returns a theme with no cursors — visible, rather
+    # than a pointer that works on the developer's machine and nowhere else.
+    '-DICONDIR=""',
+    '-DXCURSORPATH=""',
+
+    "-fPIC",
+    "-fvisibility=hidden",
+]
+
+[lib]
+path = "src/wayland-cursor.cppm"
+
+[targets.wayland-cursor]
+kind = "shared"
+# `.so.0`, not `.so.1`: upstream versions this library `0.<minor>.<micro>` on
+# purpose so that wayland 1.x never forces a cursor SONAME bump — there is a
+# comment in upstream/cursor/meson.build explaining it, and an `error()` that
+# fires if wayland ever goes to 2.x.
+soname = "libwayland-cursor.so.0"
+
+[dependencies]
+# A LINK dependency, see the header comment. libwayland-client provides the
+# wl_shm calls this library makes.
+freedesktop.wayland = { path = "../client" }

mcpp/cursor/src/wayland-cursor.cppm

@@ -0,0 +1,42 @@
+// freedesktop.wayland.cursor — libwayland-cursor, as a C++23 module.
+//
+// A module wrapper and nothing more: every name below is upstream's, spelled
+// upstream's way, with upstream's signature. `import freedesktop.wayland.cursor;`
+// replaces the #include and changes nothing else.
+//
+// HAND-WRITTEN, like the egl wrapper and for the same reason: the public
+// surface is two structs and six functions, small enough to read in one glance
+// and checked one by one in `tests/`. `mcpp/tools/genmod.py` exists because the
+// client and server wrappers re-export roughly two hundred names each.
+//
+// Nothing here is `static inline`, so every name is a plain `using ::name;` —
+// no `export inline` forwarders, unlike the client and server modules where
+// wayland-scanner's convenience wrappers force them.
+//
+// THE TWO STRUCTS ARE EXPORTED AS TYPES, NOT AS OPAQUE HANDLES, and the
+// difference matters to a caller: `wl_cursor` and `wl_cursor_image` have their
+// fields in the public header — `image_count`, `images`, `hotspot_x` — and a
+// client reads them directly to place the pointer. `wl_cursor_theme` is opaque
+// and stays so.
+module;
+
+#include <wayland-cursor.h>
+
+export module freedesktop.wayland.cursor;
+
+export {
+
+// -- types --
+using ::wl_cursor_theme;   // opaque
+using ::wl_cursor;         // fields are public: image_count, images, name
+using ::wl_cursor_image;   // fields are public: width, height, hotspot_*, delay
+
+// -- functions --
+using ::wl_cursor_theme_load;
+using ::wl_cursor_theme_destroy;
+using ::wl_cursor_theme_get_cursor;
+using ::wl_cursor_image_get_buffer;
+using ::wl_cursor_frame;
+using ::wl_cursor_frame_and_duration;
+
+} // export