kvspace: harden XValue ABI, ELF destructor cleanup, CLI formatting, and v0.3.23 tutorials

.github/workflows/ci.yml

@@ -7,3 +7,5 @@ jobs:
       - uses: actions/checkout@v4
       - name: 构建
         run: cmake -B build && cmake --build build
+      - name: Run unit tests
+        run: ctest --test-dir build --output-on-failure

.github/workflows/release.yml

@@ -13,10 +13,10 @@ jobs:
       - uses: actions/checkout@v4
       - name: 构建
         run: cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build
-      - name: 构建 CLI（cli/ 独立 Cargo 项目，走 dispatch 前端 C ABI）
+      - name: Verify CLI RUNPATH (built by cmake kvspace-cli target)
         run: |
-          # CLI 用 #[link(name = "kvspace")] 链本仓刚构建的前端 → 把 build/ 交给链接器
-          RUSTFLAGS="-L native=$PWD/build" cargo build --release --manifest-path cli/Cargo.toml
+          set -euo pipefail
+          readelf -d cli/target/release/kvspace | grep -F 'RUNPATH' | grep -F '$ORIGIN/../lib'
       - name: 打包 ABI 产物
         run: |
           set -euo pipefail

CMakeLists.txt

@@ -56,14 +56,22 @@ install(FILES ${CMAKE_CURRENT_BINARY_DIR}/kvspace.pc DESTINATION ${CMAKE_INSTALL
 # ── CLI（cli/ 独立 Cargo 项目）──────────────────────────────────────
 # 走本仓 dispatch 前端的 C ABI，故须在 kvspace 目标之后构建；
 # 安装到 <prefix>/bin（prefix 默认 /usr → /usr/bin，与 kvlang 的 CLI 一致）。
-# RUNPATH 用相对自身的 $ORIGIN/../lib：可执行在 bin/、前端在 lib/，tarball
-# 换机器后仍然解析。$ 转义成 $$ 以免被 CMake 当变量展开。
+# Embed relative RUNPATH entries:
+#   $ORIGIN/../lib                      -- release tarball (bin/ + lib/)
+#   $ORIGIN/../<libdir>/kvspace         -- cmake --install (<prefix>/<libdir>/kvspace)
+# Use @loader_path on macOS; escape $ as $$ for CMake.
+# release.yml packages this binary directly without rebuilding.
 find_program(CARGO_EXECUTABLE cargo)
 if(CARGO_EXECUTABLE)
   set(KVSPACE_CLI_BIN "${CMAKE_CURRENT_SOURCE_DIR}/cli/target/release/kvspace")
+  if(APPLE)
+    set(KVSPACE_CLI_ORIGIN "@loader_path")
+  else()
+    set(KVSPACE_CLI_ORIGIN "$$ORIGIN")
+  endif()
   add_custom_target(kvspace-cli ALL
     COMMAND ${CMAKE_COMMAND} -E env
-            "RUSTFLAGS=-L native=$<TARGET_FILE_DIR:kvspace> -C link-arg=-Wl,-rpath,'$$ORIGIN/../lib'"
+            "RUSTFLAGS=-L native=$<TARGET_FILE_DIR:kvspace> -C link-arg=-Wl,-rpath,'${KVSPACE_CLI_ORIGIN}/../lib' -C link-arg=-Wl,-rpath,'${KVSPACE_CLI_ORIGIN}/../${CMAKE_INSTALL_LIBDIR}/kvspace'"
             "${CARGO_EXECUTABLE}" build --release
             --manifest-path "${CMAKE_CURRENT_SOURCE_DIR}/cli/Cargo.toml"
     BYPRODUCTS "${KVSPACE_CLI_BIN}"

README.md

@@ -12,7 +12,8 @@ KVSpace 的 dispatch 前端。消费者只链接 `libkvspace`，运行期按 DSN
 XValue 构造（`kvspaceNew*`/`kvspaceXvalueHeadNew*`）无 handle，由前端静态实现，
 head 格式 byte-identical，两个后端与前端三者共用同一份契约。
 
-后端一律按固定目录查找（Linux `/usr/lib/kvspace`，macOS `/usr/local/lib/kvspace`）；
+Backend lookup order: frontend `.so` directory, its `kvspace/` subdirectory, `../kvspace/`,
+falling back to system paths (Linux `/usr/lib/kvspace`, macOS `/usr/local/lib/kvspace`);
 若宿主已按 SONAME 加载过后端（单二进制 `memfd` 场景），前端用
 `dlopen(soname, RTLD_NOW | RTLD_NOLOAD)` 直接复用该对象，不重复映射、不 dlclose。
 运行期没有任何目录/后端类环境变量——`KVSPACE` 是唯一的运行时变量（DSN 选后端）。