Skip to content

Commit c6bbf99

Browse files
ccmywishccmywish
committed
Update DEB doc
[GitHub #207]
1 parent 5de4f64 commit c6bbf99

File tree

4 files changed

+204
-147
lines changed

4 files changed

+204
-147
lines changed

‎pkg/DEB/BUILD.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
<!-- -----------------------------------------------------------
2+
! SPDX-License-Identifier: GFDL-1.3-or-later
3+
! -------------------------------------------------------------
4+
! Doc Type : Markdown
5+
! Doc Name : BUILD.md
6+
! Doc Authors : sanchuanhehe <wyihe5520@gmail.com>
7+
! Contributors : Aoran Zeng <ccmywish@qq.com>
8+
! |
9+
! Created On : <2025-06-14>
10+
! Last Modified : <2025-06-15>
11+
! ---------------------------------------------------------- -->
12+
13+
# 构建 DEB package
14+
15+
## 从源代码构建
16+
17+
### 准备
18+
19+
安装构建所需的依赖：
20+
21+
```bash
22+
sudo apt-get update
23+
sudo apt-get install build-essential debhelper devscripts fakeroot
24+
```
25+
26+
### 构建
27+
28+
```bash
29+
git clone https://github.com/RubyMetric/chsrc.git
30+
cd chsrc
31+
32+
# 执行构建命令
33+
./deb.makefile deb-build
34+
35+
# 安装生成的 .deb 文件
36+
sudo dpkg -i ../chsrc_*.deb
37+
```
38+
39+
<br>
40+
41+
### 交叉编译
42+
43+
为不同架构进行构建：
44+
45+
```bash
46+
# For ARM64
47+
CC=aarch64-linux-gnu-gcc dpkg-buildpackage -us -uc -b -aarm64
48+
49+
# For ARMv7 (armhf)
50+
CC=arm-linux-gnueabihf-gcc dpkg-buildpackage -us -uc -b -aarmhf
51+
```
52+
53+
<br>
54+
55+
### 安装与测试
56+
57+
```bash
58+
# 安装生成的包
59+
sudo dpkg -i ../chsrc_*.deb
60+
sudo apt-get install -f # 修复依赖问题
61+
62+
# 运行测试
63+
./deb-test.sh
64+
65+
# 卸载
66+
sudo apt-get remove chsrc
67+
```
68+
69+
### 清理构建产物
70+
71+
```bash
72+
./deb.makefile deb-clean
73+
```
74+
75+
<br>
76+
77+
## 卸载
78+
79+
```bash
80+
sudo apt-get remove chsrc
81+
```
82+
83+
包括删除配置在内的完全删除：
84+
85+
```bash
86+
sudo apt-get purge chsrc
87+
```
88+
89+
<br>
90+
91+
92+
## 故障排查
93+
94+
### 常见问题
95+
96+
1. **构建失败**: 检查 debian/control 中的依赖是否正确
97+
2. **交叉编译失败**: 确认目标架构的工具链已正确安装
98+
3. **安装测试失败**: 检查 postinst 脚本是否有错误
99+
100+
### 调试构建
101+
102+
```bash
103+
# 启用详细输出
104+
DEB_BUILD_OPTIONS="nocheck" debuild -us -uc -b
105+
106+
# 检查构建日志
107+
less ../chsrc_*.build
108+
109+
# 检查包内容
110+
dpkg --contents ../chsrc_*.deb
111+
# 或
112+
dpkg-deb --contents ../chsrc_*.deb
113+
```

‎pkg/DEB/CI.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
<!-- -----------------------------------------------------------
2+
! SPDX-License-Identifier: GFDL-1.3-or-later
3+
! -------------------------------------------------------------
4+
! Doc Type : Markdown
5+
! Doc Name : CI.md
6+
! Doc Authors : sanchuanhehe <wyihe5520@gmail.com>
7+
! Contributors : Aoran Zeng <ccmywish@qq.com>
8+
! |
9+
! Created On : <2025-06-14>
10+
! Last Modified : <2025-06-15>
11+
! ---------------------------------------------------------- -->
12+
13+
# DEB package CI/CD
14+
15+
本文档说明了 chsrc 项目的 DEB 包自动构建和发布流程。
16+
17+
## CI 文件
18+
19+
- [.github/workflows/pkg-deb.yml](.github/workflows/pkg-deb.yml)
20+
21+
<br>
22+
23+
## 支持的架构
24+
25+
当前支持以下架构的 DEB 包构建：
26+
27+
- `amd64` (x86_64)
28+
29+
<br>
30+
31+
## CI 构建产物
32+
33+
每次 CI 构建会生成：
34+
35+
1. **DEB 包文件**: `chsrc_<version>-1_<arch>.deb`
36+
2. **仓库元数据**: `Packages` 和 `Packages.gz` 文件用于创建 APT 仓库
37+
38+
<br>
39+
40+
41+
## 自动触发
42+
43+
DEB 包构建 CI 会在以下情况下自动触发：
44+
45+
1. **Release 事件**: 当创建新的 release 时自动构建并上传 DEB 包到 release assets
46+
2. **手动触发**: 可以在 GitHub Actions 页面手动触发构建
47+
48+
<br>
49+
50+
## 手动发布流程
51+
52+
1. 确保所有代码已合并到主分支
53+
2. 更新版本号和 changelog
54+
3. 创建并推送 git tag: `git tag v1.2.3 && git push origin v1.2.3`
55+
4. 在 GitHub 上创建 release
56+
5. CI 将自动构建并上传 DEB 包
57+
58+
<br>

‎pkg/DEB/INSTALL.md‎

Lines changed: 0 additions & 77 deletions
This file was deleted.

‎pkg/DEB/README.md‎

Lines changed: 33 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,52 @@
1-
# DEB Package CI/CD 构建
1+
<!-- -----------------------------------------------------------
2+
! SPDX-License-Identifier: GFDL-1.3-or-later
3+
! -------------------------------------------------------------
4+
! Doc Type : Markdown
5+
! Doc Name : README.md
6+
! Doc Authors : sanchuanhehe <wyihe5520@gmail.com>
7+
! | Aoran Zeng <ccmywish@qq.com>
8+
! Contributors : Nil Null <nil@null.org>
9+
! |
10+
! Created On : <2025-06-14>
11+
! Last Modified : <2025-06-15>
12+
! ---------------------------------------------------------- -->
213

3-
本文档说明了 chsrc 项目的 DEB 包自动构建和发布流程。
14+
# DEB package
415

5-
## 自动触发
16+
本文档说明了 `chsrc` 项目的 DEB 包的相关情况
617

7-
DEB 包构建 CI 会在以下情况下自动触发：
18+
<br>
819

9-
1. **Release 事件**: 当创建新的 release 时自动构建并上传 DEB 包到 release assets
10-
2. **手动触发**: 可以在 GitHub Actions 页面手动触发构建
11-
12-
## 支持的架构
20+
## 相关文件
1321

14-
当前支持以下架构的 DEB 包构建：
22+
- `.github/workflows/pkg-deb.yml` - CI 配置文件
23+
- `CI.md` - CI 情况说明
1524

16-
- `amd64` (x86_64)
25+
<wbr>
1726

18-
## 构建产物
27+
- `debian/` - DEB 包构建配置目录
28+
- `BUILD.md` - 如何手动构建
29+
- `deb.makefile` - DEB 包构建 Makefile
30+
- `deb-test.sh` - DEB 包 **已正确安装** 测试脚本
1931

20-
每次构建会生成：
32+
<br>
2133

22-
1. **DEB 包文件**: `chsrc_<version>-1_<arch>.deb`
23-
2. **仓库元数据**: `Packages` 和 `Packages.gz` 文件用于创建 APT 仓库
2434

25-
## 本地测试
35+
## 安装
2636

27-
### 构建 DEB 包
37+
如果你是普通用户，你应该从 [GitHub Releases](https://github.com/RubyMetric/chsrc/releases) 下载合适的 DEB package，然后运行以下命令安装：
2838

2939
```bash
30-
# 准备构建环境
31-
sudo apt-get install build-essential debhelper devscripts fakeroot
32-
33-
# 构建包
34-
make deb-build
35-
36-
# 清理构建产物
37-
make deb-clean
40+
sudo dpkg -i chsrc_*.deb
41+
sudo apt-get install -f # Fix any dependency issues
3842
```
3943

40-
### 测试安装
41-
42-
```bash
43-
# 安装生成的包
44-
sudo dpkg -i ../chsrc_*.deb
45-
sudo apt-get install -f # 修复依赖问题
44+
如果你是高级用户，你可以自己阅读本目录下的 [./BUILD.md](./BUILD.md) 来自己构建 DEB 包并按照上述同样的方式安装。
4645

47-
# 运行测试
48-
bash ./pkg/DEB/deb-test.sh
46+
<br>
4947

50-
# 卸载
51-
sudo apt-get remove chsrc
52-
```
5348

54-
## 文件结构
49+
## `debian/` 目录结构
5550

5651
```
5752
debian/
@@ -64,38 +59,6 @@ debian/
6459
└── rules # 构建规则
6560
```
6661

67-
## 手动发布流程
68-
69-
1. 确保所有代码已合并到主分支
70-
2. 更新版本号和 changelog
71-
3. 创建并推送 git tag: `git tag v1.2.3 && git push origin v1.2.3`
72-
4. 在 GitHub 上创建 release
73-
5. CI 将自动构建并上传 DEB 包
74-
75-
## 故障排查
76-
77-
### 常见问题
78-
79-
1. **构建失败**: 检查 debian/control 中的依赖是否正确
80-
2. **交叉编译失败**: 确认目标架构的工具链已正确安装
81-
3. **安装测试失败**: 检查 postinst 脚本是否有错误
82-
83-
### 调试构建
84-
85-
```bash
86-
# 启用详细输出
87-
DEB_BUILD_OPTIONS="nocheck" debuild -us -uc -b
88-
89-
# 检查构建日志
90-
less ../chsrc_*.build
91-
92-
# 检查包内容
93-
dpkg-deb --contents chsrc_*.deb
94-
```
95-
96-
## 相关文件
62+
其中，最后三个是 `+x` 的可执行文件。
9763

98-
- `.github/workflows/pkg-deb.yml` - CI 工作流配置
99-
- `debian/` - Debian 包配置目录
100-
- `pkg/DEB/deb-test.sh` - DEB 包功能测试脚本
101-
- `pkg/DEB/INSTALL.md` - 用户安装指南
64+
<br>

0 commit comments

Comments
 (0)