Skip to content

Commit 9d271f7

Browse files
liangshaotengliangshaoteng
committed
feat: add one-command install scripts and automated release pipeline
- .github/workflows/release.yml: triggered on git tag vX.Y.Z; builds linux-x86_64, linux-aarch64, and windows-x64 packages, generates a combined SHA256SUMS, and publishes a GitHub Release via softprops/action-gh-release. workflow_dispatch is also supported for dry-run packaging without cutting a release. - scripts/install.sh: Linux one-command installer. Detects x86_64 or aarch64, fetches the matching tarball from GitHub Releases, verifies SHA256, extracts to --prefix (default /usr/local), and finishes with ldconfig plus symlinks under /usr/local/lib. - scripts/install.ps1: Windows x64 one-command installer. Verifies SHA256, installs to %ProgramFiles%\LinkerHand\cpp-sdk (overridable), appends the prefix to the user's CMAKE_PREFIX_PATH, and offers an optional -AddToPath switch. - CMakeLists.txt: introduces the LINKERHAND_SDK_VERSION cache variable (default 2.0.0) so CI can inject the git tag via -DLINKERHAND_SDK_VERSION=<tag>, keeping tag, tarball filename, and CMake config version in sync. - cmake/linkerhand-cpp-sdk-config-version.cmake becomes a .cmake.in template; configure_file writes the versioned copy before install. - README.md: adds a one-command install section at the top of the quick-start guide (Linux and Windows). - INSTALL.md: new document covering installation, version pinning, offline install, uninstall, and FAQ for downstream users.
1 parent ccb3aa9 commit 9d271f7

7 files changed

Lines changed: 651 additions & 4 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
name: Release
2+
3+
# 触发条件：推送形如 vX.Y.Z 的 tag。手动触发也可（用于验证打包流程）。
4+
on:
5+
push:
6+
tags: [ 'v*' ]
7+
workflow_dispatch:
8+
inputs:
9+
version:
10+
description: '发布版本号（不含 v 前缀，如 2.1.8）；仅 workflow_dispatch 时生效'
11+
required: true
12+
default: '0.0.0-test'
13+
14+
env:
15+
DEBIAN_FRONTEND: noninteractive
16+
TZ: Asia/Shanghai
17+
18+
jobs:
19+
# 从 tag 或手动输入解析版本号，供后续 job 复用
20+
meta:
21+
name: Resolve version
22+
runs-on: ubuntu-latest
23+
outputs:
24+
version: ${{ steps.ver.outputs.version }}
25+
steps:
26+
- id: ver
27+
run: |
28+
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
29+
VER="${{ github.event.inputs.version }}"
30+
else
31+
VER="${GITHUB_REF_NAME#v}"
32+
fi
33+
echo "version=$VER" >> "$GITHUB_OUTPUT"
34+
echo "解析出的发布版本：$VER"
35+
36+
# Linux x86_64：runner 原生构建，产物是 build.sh 期望布局的 staging 目录
37+
package-linux-x86_64:
38+
name: Package linux-x86_64
39+
needs: meta
40+
runs-on: ubuntu-22.04
41+
steps:
42+
- uses: actions/checkout@v4
43+
44+
- name: 安装构建依赖
45+
run: |
46+
sudo apt-get update
47+
sudo apt-get install -y --no-install-recommends build-essential cmake
48+
49+
- name: CMake 配置 & 安装到 staging
50+
run: |
51+
mkdir -p build
52+
cd build
53+
cmake .. \
54+
-DCMAKE_BUILD_TYPE=Release \
55+
-DBUILD_EXAMPLES=OFF \
56+
-DLINKERHAND_SDK_VERSION=${{ needs.meta.outputs.version }}
57+
cmake --install . --prefix "${GITHUB_WORKSPACE}/stage/linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-linux-x86_64"
58+
59+
- name: 打包 tar.gz
60+
run: |
61+
cd stage
62+
PKG="linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-linux-x86_64"
63+
tar -czf "${PKG}.tar.gz" "$PKG"
64+
sha256sum "${PKG}.tar.gz" | tee "${PKG}.tar.gz.sha256"
65+
66+
- uses: actions/upload-artifact@v4
67+
with:
68+
name: linux-x86_64
69+
path: stage/*.tar.gz*
70+
if-no-files-found: error
71+
72+
# Linux aarch64：交叉编译。SDK 内部产物已是预编译库，此处只做 install 阶段的拷贝，
73+
# 不需要真正在 aarch64 上运行任何代码，因此不需要 QEMU。
74+
package-linux-aarch64:
75+
name: Package linux-aarch64
76+
needs: meta
77+
runs-on: ubuntu-22.04
78+
steps:
79+
- uses: actions/checkout@v4
80+
81+
- name: 安装交叉工具链
82+
run: |
83+
sudo apt-get update
84+
sudo apt-get install -y --no-install-recommends \
85+
build-essential cmake \
86+
gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
87+
88+
- name: CMake 配置 & 安装到 staging
89+
run: |
90+
mkdir -p build
91+
cd build
92+
cmake .. \
93+
-DCMAKE_BUILD_TYPE=Release \
94+
-DBUILD_EXAMPLES=OFF \
95+
-DLINKERHAND_SDK_VERSION=${{ needs.meta.outputs.version }} \
96+
-DCMAKE_SYSTEM_NAME=Linux \
97+
-DCMAKE_SYSTEM_PROCESSOR=aarch64 \
98+
-DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
99+
-DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++
100+
cmake --install . --prefix "${GITHUB_WORKSPACE}/stage/linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-linux-aarch64"
101+
102+
- name: 打包 tar.gz
103+
run: |
104+
cd stage
105+
PKG="linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-linux-aarch64"
106+
tar -czf "${PKG}.tar.gz" "$PKG"
107+
sha256sum "${PKG}.tar.gz" | tee "${PKG}.tar.gz.sha256"
108+
109+
- uses: actions/upload-artifact@v4
110+
with:
111+
name: linux-aarch64
112+
path: stage/*.tar.gz*
113+
if-no-files-found: error
114+
115+
# Windows x64：使用 MSVC 布局
116+
package-windows-x64:
117+
name: Package windows-x64
118+
needs: meta
119+
runs-on: windows-latest
120+
steps:
121+
- uses: actions/checkout@v4
122+
123+
- name: CMake 配置 & 安装到 staging
124+
shell: pwsh
125+
run: |
126+
mkdir build | Out-Null
127+
cd build
128+
cmake .. `
129+
-A x64 `
130+
-DBUILD_EXAMPLES=OFF `
131+
-DLINKERHAND_SDK_VERSION=${{ needs.meta.outputs.version }}
132+
$stage = "$env:GITHUB_WORKSPACE\stage\linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-windows-x64"
133+
cmake --install . --config Release --prefix "$stage"
134+
135+
- name: 打包 zip
136+
shell: pwsh
137+
run: |
138+
$pkg = "linkerhand-cpp-sdk-${{ needs.meta.outputs.version }}-windows-x64"
139+
Compress-Archive -Path "stage\$pkg" -DestinationPath "stage\$pkg.zip"
140+
(Get-FileHash "stage\$pkg.zip" -Algorithm SHA256).Hash.ToLower() + " $pkg.zip" | Out-File -Encoding ascii "stage\$pkg.zip.sha256"
141+
142+
- uses: actions/upload-artifact@v4
143+
with:
144+
name: windows-x64
145+
path: stage/*.zip*
146+
if-no-files-found: error
147+
148+
# 汇总产物 → 汇总 SHA256SUMS → 发布 GitHub Release
149+
release:
150+
name: Publish Release
151+
needs: [meta, package-linux-x86_64, package-linux-aarch64, package-windows-x64]
152+
runs-on: ubuntu-22.04
153+
# workflow_dispatch 只做打包烟测，不真的发 Release
154+
if: github.event_name == 'push'
155+
permissions:
156+
contents: write
157+
steps:
158+
- uses: actions/checkout@v4
159+
160+
- uses: actions/download-artifact@v4
161+
with:
162+
path: dist
163+
merge-multiple: true
164+
165+
- name: 生成汇总 SHA256SUMS
166+
working-directory: dist
167+
run: |
168+
# 单文件的 .sha256 只是给用户单独校验用的，Release 页仍以 SHA256SUMS 为准
169+
rm -f SHA256SUMS
170+
for f in *.tar.gz *.zip; do
171+
[ -f "$f" ] || continue
172+
sha256sum "$f" >> SHA256SUMS
173+
done
174+
echo "=== SHA256SUMS ==="
175+
cat SHA256SUMS
176+
177+
- name: 创建 GitHub Release 并上传产物
178+
uses: softprops/action-gh-release@v2
179+
with:
180+
tag_name: ${{ github.ref_name }}
181+
name: LinkerHand C++ SDK ${{ needs.meta.outputs.version }}
182+
generate_release_notes: true
183+
files: |
184+
dist/*.tar.gz
185+
dist/*.zip
186+
dist/SHA256SUMS

‎CMakeLists.txt‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ set(CMAKE_CXX_STANDARD 17)
55
set(CMAKE_CXX_STANDARD_REQUIRED ON)
66
set(CMAKE_CXX_EXTENSIONS OFF)
77

8+
# 发布版本号。默认与 SOVERSION 主版本对齐（2.x）；发布 CI 通过
9+
# -DLINKERHAND_SDK_VERSION=<tag> 覆盖，保证 tag / tarball / config 三者一致。
10+
set(LINKERHAND_SDK_VERSION "2.0.0" CACHE STRING "LinkerHand C++ SDK release version")
11+
812
option(BUILD_EXAMPLES "Build example applications" ON)
913
option(BUILD_HAND_TEACH_PENDANT "Build hand teach pendant application" OFF)
1014

@@ -17,7 +21,7 @@ if(BUILD_HAND_TEACH_PENDANT)
1721
endif()
1822

1923
message(STATUS "=== LinkerHand C++ SDK Examples ===")
20-
message(STATUS "Version: 2.0.0")
24+
message(STATUS "Version: ${LINKERHAND_SDK_VERSION}")
2125
message(STATUS "Build Examples: ${BUILD_EXAMPLES}")
2226
message(STATUS "Build Hand Teach Pendant: ${BUILD_HAND_TEACH_PENDANT}")
2327
message(STATUS "=====================================")
@@ -66,10 +70,15 @@ endif()
6670

6771
# CMake config 包：让下游用 find_package(linkerhand-cpp-sdk CONFIG REQUIRED)
6872
# 配置文件相对路径自定位（见 cmake/linkerhand-cpp-sdk-config.cmake），
69-
# prefix 改了无需重新生成。
73+
# prefix 改了无需重新生成。版本文件由模板注入 LINKERHAND_SDK_VERSION。
74+
configure_file(
75+
"${CMAKE_CURRENT_SOURCE_DIR}/cmake/linkerhand-cpp-sdk-config-version.cmake.in"
76+
"${CMAKE_CURRENT_BINARY_DIR}/linkerhand-cpp-sdk-config-version.cmake"
77+
@ONLY
78+
)
7079
install(FILES
7180
"${CMAKE_CURRENT_SOURCE_DIR}/cmake/linkerhand-cpp-sdk-config.cmake"
72-
"${CMAKE_CURRENT_SOURCE_DIR}/cmake/linkerhand-cpp-sdk-config-version.cmake"
81+
"${CMAKE_CURRENT_BINARY_DIR}/linkerhand-cpp-sdk-config-version.cmake"
7382
DESTINATION "lib/cmake/linkerhand-cpp-sdk"
7483
)
7584

‎INSTALL.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# INSTALL — LinkerHand C++ SDK 安装指南
2+
3+
本文档面向"只想集成 SDK 到自有工程"的下游用户。若你在参与 SDK 本身的开发或需要从源码构建，请回到 [`README.md`](README.md)。
4+
5+
---
6+
7+
## 目录
8+
9+
- [一条命令安装](#一条命令安装)
10+
- [版本锁定](#版本锁定)
11+
- [离线 / 手动安装](#离线--手动安装)
12+
- [下游 CMake 集成](#下游-cmake-集成)
13+
- [卸载](#卸载)
14+
- [常见问题](#常见问题)
15+
16+
---
17+
18+
## 一条命令安装
19+
20+
### Linux（x86_64 / aarch64）
21+
22+
```bash
23+
# 默认：装最新 Release 到 /usr/local，自动使用 sudo
24+
curl -fsSL https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.sh | bash
25+
```
26+
27+
支持的参数（通过 `-s --` 传给脚本）：
28+
29+
| 参数 | 说明 |
30+
|------|------|
31+
| `--version <TAG>` | 指定版本（`v2.1.8` 或 `2.1.8` 均可），默认 latest |
32+
| `--prefix <PATH>` | 安装前缀，默认 `/usr/local` |
33+
| `--no-sudo` | 不使用 sudo（在 root 容器或已具备写权限时） |
34+
| `--keep-tmp` | 保留临时目录，排查用 |
35+
| `-h`, `--help` | 帮助 |
36+
37+
```bash
38+
# 举例：装指定版本到用户目录，无需 sudo
39+
curl -fsSL https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.sh \
40+
| bash -s -- --version v2.1.8 --prefix $HOME/.local --no-sudo
41+
```
42+
43+
### Windows x64
44+
45+
以 **管理员** 打开 PowerShell：
46+
47+
```powershell
48+
iwr https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.ps1 -UseBasicParsing | iex
49+
```
50+
51+
带参调用需要显式实例化脚本块：
52+
53+
```powershell
54+
& ([scriptblock]::Create(
55+
(iwr https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.ps1 -UseBasicParsing).Content
56+
)) -Version v2.1.8 -Prefix "C:\SDKs\LinkerHand" -AddToPath
57+
```
58+
59+
参数：`-Version`、`-Prefix`、`-AddToPath`（把 `<Prefix>\bin` 加入用户 PATH）。
60+
61+
安装脚本会将 `<Prefix>` 追加到用户环境变量 `CMAKE_PREFIX_PATH`，新终端生效。
62+
63+
---
64+
65+
## 版本锁定
66+
67+
生产环境建议**锁定版本**，避免上游发新版后无感知升级：
68+
69+
```bash
70+
# CI / Dockerfile 中固化版本
71+
curl -fsSL https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.sh \
72+
| bash -s -- --version v2.1.8
73+
```
74+
75+
各 Release 的 SHA256 汇总由 `SHA256SUMS` 附件承载，安装脚本会**自动校验**，任何篡改或下载损坏都会终止安装。
76+
77+
---
78+
79+
## 离线 / 手动安装
80+
81+
无法访问 GitHub 的环境（内网、离线机、气隙网络）：
82+
83+
1. 到 [Releases 页面](https://github.com/linker-bot/linkerhand-cpp-sdk/releases) 手动下载对应平台的产物：
84+
- `linkerhand-cpp-sdk-<VER>-linux-x86_64.tar.gz`
85+
- `linkerhand-cpp-sdk-<VER>-linux-aarch64.tar.gz`
86+
- `linkerhand-cpp-sdk-<VER>-windows-x64.zip`
87+
- `SHA256SUMS`（校验用）
88+
2. 校验：`sha256sum -c SHA256SUMS`（Linux）或 `Get-FileHash`（PowerShell）
89+
3. Linux：`tar -xzf ...tar.gz && sudo rsync -a linkerhand-cpp-sdk-*/ /usr/local/ && sudo ldconfig`
90+
4. Windows：解压 zip 后整个目录移动到目标位置，将其加入 `CMAKE_PREFIX_PATH`
91+
92+
---
93+
94+
## 下游 CMake 集成
95+
96+
推荐使用 CMake config 包：
97+
98+
```cmake
99+
cmake_minimum_required(VERSION 3.15)
100+
project(my_app LANGUAGES CXX)
101+
102+
find_package(linkerhand-cpp-sdk CONFIG REQUIRED)
103+
104+
add_executable(my_app main.cpp)
105+
target_link_libraries(my_app PRIVATE LinkerHand::linkerhand_cpp_sdk)
106+
```
107+
108+
- 装到 `/usr/local` 或 `C:\Program Files\LinkerHand\cpp-sdk`：`find_package` 自动发现
109+
- 装到自定义前缀：`cmake -DCMAKE_PREFIX_PATH=<前缀> ...`
110+
- Windows 上，安装脚本已把前缀写入用户 `CMAKE_PREFIX_PATH`
111+
112+
---
113+
114+
## 卸载
115+
116+
### Linux
117+
118+
安装到 `/usr/local`（或指定前缀）后，可用以下命令清理：
119+
120+
```bash
121+
sudo rm -rf /usr/local/include/linkerhand-cpp-sdk \
122+
/usr/local/lib/linkerhand-cpp-sdk \
123+
/usr/local/lib/cmake/linkerhand-cpp-sdk \
124+
/usr/local/lib/liblinkerhand_cpp_sdk.*
125+
sudo ldconfig
126+
```
127+
128+
如仍保留了 SDK 源码目录，也可直接用 `sudo ./build.sh -u --prefix /usr/local`。
129+
130+
### Windows
131+
132+
删除 `%ProgramFiles%\LinkerHand\cpp-sdk`（或自定义前缀）目录，并从用户 `CMAKE_PREFIX_PATH` / `Path` 中移除对应条目：
133+
134+
```powershell
135+
Remove-Item -Recurse -Force "$env:ProgramFiles\LinkerHand\cpp-sdk"
136+
```
137+
138+
---
139+
140+
## 常见问题
141+
142+
**Q: 一键脚本安全吗？我把陌生脚本 pipe 到 bash 心里发怵。**
143+
A: 脚本源码位于本仓库 [`scripts/install.sh`](scripts/install.sh) 与 [`scripts/install.ps1`](scripts/install.ps1)，可在执行前先看一遍：
144+
```bash
145+
curl -fsSL https://raw.githubusercontent.com/linker-bot/linkerhand-cpp-sdk/main/scripts/install.sh | less
146+
```
147+
脚本只做：查询 Release → 下载 tarball 与 `SHA256SUMS` → 校验 → 解压到指定前缀。不下载任何仓库以外的资源。
148+
149+
**Q: 我的架构不在支持列表怎么办？**
150+
A: 当前仅提供 Linux x86_64/aarch64 与 Windows x64 预编译产物。其他架构（如 ARMv7、RISC-V）请提 issue，或克隆仓库自行构建。
151+
152+
**Q: 安装后 `find_package` 找不到？**
153+
A: 若装到非标准前缀，配置下游时加 `-DCMAKE_PREFIX_PATH=<前缀>`；Windows 需重开终端让环境变量生效。
154+
155+
**Q: 想用 apt / conan / vcpkg 装？**
156+
A: 暂未支持。如有需求请提 issue，会评估纳入后续发布通道。

0 commit comments

Comments
 (0)