linker-bot · liangshaoteng · Jul 8, 2026 · Jul 8, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,186 @@
+name: Release
+
+# 触发条件：推送形如 vX.Y.Z 的 tag。手动触发也可（用于验证打包流程）。
+on:
+  push:
+    tags: [ 'v*' ]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: '发布版本号（不含 v 前缀，如 2.1.8）；仅 workflow_dispatch 时生效'
+        required: true
+        default: '0.0.0-test'
+
+env:
+  DEBIAN_FRONTEND: noninteractive
+  TZ: Asia/Shanghai
+
+jobs:
+  # 从 tag 或手动输入解析版本号，供后续 job 复用
+  meta:
+    name: Resolve version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.ver.outputs.version }}
+    steps:
+      - id: ver
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VER="${{ github.event.inputs.version }}"
+          else
+            VER="${GITHUB_REF_NAME#v}"
+          fi
+          echo "version=$VER" >> "$GITHUB_OUTPUT"
+          echo "解析出的发布版本：$VER"
+
+  # Linux x86_64：runner 原生构建，产物是 build.sh 期望布局的 staging 目录
+  package-linux-x86_64:
+    name: Package linux-x86_64
+    needs: meta
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 安装构建依赖
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends build-essential cmake
+
+      - name: CMake 配置 & 安装到 staging
+        run: |
+          mkdir -p build
+          cd build
+          cmake .. \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DBUILD_EXAMPLES=OFF \
+            -DLINKERHAND_SDK_VERSION=${{ needs.meta.outputs.version }}
+          cmake --install . --prefix "${GITHUB_WORKSPACE}/stage/linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-linux-x86_64"
+
+      - name: 打包 tar.gz
+        run: |
+          cd stage
+          PKG="linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-linux-x86_64"
+          tar -czf "${PKG}.tar.gz" "$PKG"
+          sha256sum "${PKG}.tar.gz" | tee "${PKG}.tar.gz.sha256"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: linux-x86_64
+          path: stage/*.tar.gz*
+          if-no-files-found: error
+
+  # Linux aarch64：交叉编译。SDK 内部产物已是预编译库，此处只做 install 阶段的拷贝，
+  # 不需要真正在 aarch64 上运行任何代码，因此不需要 QEMU。
+  package-linux-aarch64:
+    name: Package linux-aarch64
+    needs: meta
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 安装交叉工具链
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            build-essential cmake \
+            gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
+
+      - name: CMake 配置 & 安装到 staging
+        run: |
+          mkdir -p build
+          cd build
+          cmake .. \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DBUILD_EXAMPLES=OFF \
+            -DLINKERHAND_SDK_VERSION=${{ needs.meta.outputs.version }} \
+            -DCMAKE_SYSTEM_NAME=Linux \
+            -DCMAKE_SYSTEM_PROCESSOR=aarch64 \
+            -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
+            -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++
+          cmake --install . --prefix "${GITHUB_WORKSPACE}/stage/linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-linux-aarch64"
+
+      - name: 打包 tar.gz
+        run: |
+          cd stage
+          PKG="linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-linux-aarch64"
+          tar -czf "${PKG}.tar.gz" "$PKG"
+          sha256sum "${PKG}.tar.gz" | tee "${PKG}.tar.gz.sha256"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: linux-aarch64
+          path: stage/*.tar.gz*
+          if-no-files-found: error
+
+  # Windows x64：使用 MSVC 布局
+  package-windows-x64:
+    name: Package windows-x64
+    needs: meta
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: CMake 配置 & 安装到 staging
+        shell: pwsh
+        run: |
+          mkdir build | Out-Null
+          cd build
+          cmake .. `
+            -A x64 `
+            -DBUILD_EXAMPLES=OFF `
+            -DLINKERHAND_SDK_VERSION=${{ needs.meta.outputs.version }}
+          $stage = "$env:GITHUB_WORKSPACE\stage\linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-windows-x64"
+          cmake --install . --config Release --prefix "$stage"
+
+      - name: 打包 zip
+        shell: pwsh
+        run: |
+          $pkg = "linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-windows-x64"
+          Compress-Archive -Path "stage\$pkg" -DestinationPath "stage\$pkg.zip"
+          (Get-FileHash "stage\$pkg.zip" -Algorithm SHA256).Hash.ToLower() + "  $pkg.zip" | Out-File -Encoding ascii "stage\$pkg.zip.sha256"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: windows-x64
+          path: stage/*.zip*
+          if-no-files-found: error
+
+  # 汇总产物 → 汇总 SHA256SUMS → 发布 GitHub Release
+  release:
+    name: Publish Release
+    needs: [meta, package-linux-x86_64, package-linux-aarch64, package-windows-x64]
+    runs-on: ubuntu-22.04
+    # workflow_dispatch 只做打包烟测，不真的发 Release
+    if: github.event_name == 'push'
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: 生成汇总 SHA256SUMS
+        working-directory: dist
+        run: |
+          # 单文件的 .sha256 只是给用户单独校验用的，Release 页仍以 SHA256SUMS 为准
+          rm -f SHA256SUMS
+          for f in *.tar.gz *.zip; do
+            [ -f "$f" ] || continue
+            sha256sum "$f" >> SHA256SUMS
+          done
+          echo "=== SHA256SUMS ==="
+          cat SHA256SUMS
+
+      - name: 创建 GitHub Release 并上传产物
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: LinkerHand C++ SDK ${{ needs.meta.outputs.version }}
+          generate_release_notes: true
+          files: |
+            dist/*.tar.gz
+            dist/*.zip
+            dist/SHA256SUMS
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -5,6 +5,10 @@ set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 
+# 发布版本号。默认与 SOVERSION 主版本对齐（2.x）；发布 CI 通过
+# -DLINKERHAND_SDK_VERSION=<tag> 覆盖，保证 tag / tarball / config 三者一致。
+set(LINKERHAND_SDK_VERSION "2.0.0" CACHE STRING "LinkerHand C++ SDK release version")
+
 option(BUILD_EXAMPLES "Build example applications" ON)
 option(BUILD_HAND_TEACH_PENDANT "Build hand teach pendant application" OFF)
 
@@ -17,7 +21,7 @@ if(BUILD_HAND_TEACH_PENDANT)
 endif()
 
 message(STATUS "=== LinkerHand C++ SDK Examples ===")
-message(STATUS "Version: 2.0.0")
+message(STATUS "Version: ${LINKERHAND_SDK_VERSION}")
 message(STATUS "Build Examples: ${BUILD_EXAMPLES}")
 message(STATUS "Build Hand Teach Pendant: ${BUILD_HAND_TEACH_PENDANT}")
 message(STATUS "=====================================")
@@ -66,10 +70,15 @@ endif()
 
 # CMake config 包：让下游用 find_package(linkerhand-cpp-sdk CONFIG REQUIRED)
 # 配置文件相对路径自定位（见 cmake/linkerhand-cpp-sdk-config.cmake），
-# prefix 改了无需重新生成。
+# prefix 改了无需重新生成。版本文件由模板注入 LINKERHAND_SDK_VERSION。
+configure_file(
+    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/linkerhand-cpp-sdk-config-version.cmake.in"
+    "${CMAKE_CURRENT_BINARY_DIR}/linkerhand-cpp-sdk-config-version.cmake"
+    @ONLY
+)
 install(FILES
     "${CMAKE_CURRENT_SOURCE_DIR}/cmake/linkerhand-cpp-sdk-config.cmake"
-    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/linkerhand-cpp-sdk-config-version.cmake"
+    "${CMAKE_CURRENT_BINARY_DIR}/linkerhand-cpp-sdk-config-version.cmake"
     DESTINATION "lib/cmake/linkerhand-cpp-sdk"
 )
 

diff --git a/INSTALL.md b/INSTALL.md
@@ -0,0 +1,156 @@
+# INSTALL — LinkerHand C++ SDK 安装指南
+
+本文档面向"只想集成 SDK 到自有工程"的下游用户。若你在参与 SDK 本身的开发或需要从源码构建，请回到 [`README.md`](README.md)。
+
+---
+
+## 目录
+
+- [一条命令安装](#一条命令安装)
+- [版本锁定](#版本锁定)
+- [离线 / 手动安装](#离线--手动安装)
+- [下游 CMake 集成](#下游-cmake-集成)
+- [卸载](#卸载)
+- [常见问题](#常见问题)
+
+---
+
+## 一条命令安装
+
+### Linux（x86_64 / aarch64）
+
+```bash
+# 默认：装最新 Release 到 /usr/local，自动使用 sudo
+curl -fsSL https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.sh | bash
+```
+
+支持的参数（通过 `-s --` 传给脚本）：
+
+| 参数 | 说明 |
+|------|------|
+| `--version <TAG>` | 指定版本（`v2.1.8` 或 `2.1.8` 均可），默认 latest |
+| `--prefix <PATH>` | 安装前缀，默认 `/usr/local` |
+| `--no-sudo` | 不使用 sudo（在 root 容器或已具备写权限时） |
+| `--keep-tmp` | 保留临时目录，排查用 |
+| `-h`, `--help` | 帮助 |
+
+```bash
+# 举例：装指定版本到用户目录，无需 sudo
+curl -fsSL https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.sh \
+  | bash -s -- --version v2.1.8 --prefix $HOME/.local --no-sudo
+```
+
+### Windows x64
+
+以 **管理员** 打开 PowerShell：
+
+```powershell
+iwr https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.ps1 -UseBasicParsing | iex
+```
+
+带参调用需要显式实例化脚本块：
+
+```powershell
+& ([scriptblock]::Create(
+    (iwr https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.ps1 -UseBasicParsing).Content
+  )) -Version v2.1.8 -Prefix "C:\SDKs\LinkerHand" -AddToPath
+```
+
+参数：`-Version`、`-Prefix`、`-AddToPath`（把 `<Prefix>\bin` 加入用户 PATH）。
+
+安装脚本会将 `<Prefix>` 追加到用户环境变量 `CMAKE_PREFIX_PATH`，新终端生效。
+
+---
+
+## 版本锁定
+
+生产环境建议**锁定版本**，避免上游发新版后无感知升级：
+
+```bash
+# CI / Dockerfile 中固化版本
+curl -fsSL https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.sh \
+  | bash -s -- --version v2.1.8
+```
+
+各 Release 的 SHA256 汇总由 `SHA256SUMS` 附件承载，安装脚本会**自动校验**，任何篡改或下载损坏都会终止安装。
+
+---
+
+## 离线 / 手动安装
+
+无法访问 GitHub 的环境（内网、离线机、气隙网络）：
+
+1. 到 [Releases 页面](https://github.com/linker-bot/linkerhand-cpp-sdk/releases) 手动下载对应平台的产物：
+   - `linkerhand-cpp-sdk-<VER>-linux-x86_64.tar.gz`
+   - `linkerhand-cpp-sdk-<VER>-linux-aarch64.tar.gz`
+   - `linkerhand-cpp-sdk-<VER>-windows-x64.zip`
+   - `SHA256SUMS`（校验用）
+2. 校验：`sha256sum -c SHA256SUMS`（Linux）或 `Get-FileHash`（PowerShell）
+3. Linux：`tar -xzf ...tar.gz && sudo rsync -a linkerhand-cpp-sdk-*/ /usr/local/ && sudo ldconfig`
+4. Windows：解压 zip 后整个目录移动到目标位置，将其加入 `CMAKE_PREFIX_PATH`
+
+---
+
+## 下游 CMake 集成
+
+推荐使用 CMake config 包：
+
+```cmake
+cmake_minimum_required(VERSION 3.15)
+project(my_app LANGUAGES CXX)
+
+find_package(linkerhand-cpp-sdk CONFIG REQUIRED)
+
+add_executable(my_app main.cpp)
+target_link_libraries(my_app PRIVATE LinkerHand::linkerhand_cpp_sdk)
+```
+
+- 装到 `/usr/local` 或 `C:\Program Files\LinkerHand\cpp-sdk`：`find_package` 自动发现
+- 装到自定义前缀：`cmake -DCMAKE_PREFIX_PATH=<前缀> ...`
+- Windows 上，安装脚本已把前缀写入用户 `CMAKE_PREFIX_PATH`
+
+---
+
+## 卸载
+
+### Linux
+
+安装到 `/usr/local`（或指定前缀）后，可用以下命令清理：
+
+```bash
+sudo rm -rf /usr/local/include/linkerhand-cpp-sdk \
+            /usr/local/lib/linkerhand-cpp-sdk \
+            /usr/local/lib/cmake/linkerhand-cpp-sdk \
+            /usr/local/lib/liblinkerhand_cpp_sdk.*
+sudo ldconfig
+```
+
+如仍保留了 SDK 源码目录，也可直接用 `sudo ./build.sh -u --prefix /usr/local`。
+
+### Windows
+
+删除 `%ProgramFiles%\LinkerHand\cpp-sdk`（或自定义前缀）目录，并从用户 `CMAKE_PREFIX_PATH` / `Path` 中移除对应条目：
+
+```powershell
+Remove-Item -Recurse -Force "$env:ProgramFiles\LinkerHand\cpp-sdk"
+```
+
+---
+
+## 常见问题
+
+**Q: 一键脚本安全吗？我把陌生脚本 pipe 到 bash 心里发怵。**
+A: 脚本源码位于本仓库 [`scripts/install.sh`](scripts/install.sh) 与 [`scripts/install.ps1`](scripts/install.ps1)，可在执行前先看一遍：
+```bash
+curl -fsSL https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.sh | less
+```
+脚本只做：查询 Release → 下载 tarball 与 `SHA256SUMS` → 校验 → 解压到指定前缀。不下载任何仓库以外的资源。
+
+**Q: 我的架构不在支持列表怎么办？**
+A: 当前仅提供 Linux x86_64/aarch64 与 Windows x64 预编译产物。其他架构（如 ARMv7、RISC-V）请提 issue，或克隆仓库自行构建。
+
+**Q: 安装后 `find_package` 找不到？**
+A: 若装到非标准前缀，配置下游时加 `-DCMAKE_PREFIX_PATH=<前缀>`；Windows 需重开终端让环境变量生效。
+
+**Q: 想用 apt / conan / vcpkg 装？**
+A: 暂未支持。如有需求请提 issue，会评估纳入后续发布通道。