Use standard lower-case deb

2025-10-09 21:33:23 +08:00 · 2025-06-16 16:45:32 +08:00
parent 02c3a815de
commit 975b2391cb
16 changed files with 61 additions and 61 deletions
--- a/pkg/deb/BUILD.md
+++ b/pkg/deb/BUILD.md
@@ -0,0 +1,126 @@
+<!-- -----------------------------------------------------------
+ ! SPDX-License-Identifier: GFDL-1.3-or-later
+ ! -------------------------------------------------------------
+ ! Doc Type      : Markdown
+ ! Doc Name      : BUILD.md
+ ! Doc Authors   : sanchuanhehe <wyihe5520@gmail.com>
+ ! Contributors  :  Aoran Zeng  <ccmywish@qq.com>
+ !               |
+ ! Created On    : <2025-06-14>
+ ! Last Modified : <2025-06-16>
+ ! ---------------------------------------------------------- -->
+
+# 构建 deb package
+
+## 准备
+
+安装构建所需的依赖：
+
+```bash
+sudo apt-get update
+sudo apt-get install build-essential debhelper devscripts fakeroot
+```
+
+<br>
+
+## 构建
+
+```bash
+git clone https://github.com/RubyMetric/chsrc.git
+cd chsrc
+
+# 进入 deb 目录
+cd pkg/deb
+
+# 执行构建命令
+./deb.makefile deb-make
+```
+
+### 调试构建
+
+```bash
+# 启用详细输出
+DEB_BUILD_OPTIONS="nocheck" debuild -us -uc -b
+
+# 检查构建日志
+less ../chsrc_*.build
+
+# 检查包内容
+dpkg --contents ../chsrc_*.deb
+# 或
+dpkg-deb --contents ../chsrc_*.deb
+```
+
+### 交叉编译
+
+为不同架构进行构建：
+
+```bash
+# For ARM64
+CC=aarch64-linux-gnu-gcc dpkg-buildpackage -us -uc -b -aarm64
+
+# For ARMv7 (armhf)
+CC=arm-linux-gnueabihf-gcc dpkg-buildpackage -us -uc -b -aarmhf
+```
+
+<br>
+
+### 安装
+
+```bash
+sudo dpkg -i ../chsrc_*.deb
+sudo apt-get install -f  # 修复依赖问题
+```
+
+<br>
+
+### 测试安装情况
+
+```bash
+# 运行测试
+bash ./deb-installation-test.sh
+
+# 查看文档安装情况
+man chsrc
+
+# 查看 deb 包的 copyright
+cat /usr/share/doc/chsrc/copyright
+
+# 查看 deb 包 changelog
+zless /usr/share/doc/chsrc/changelog.Debian.gz
+```
+
+<br>
+
+### 清理构建产物
+
+```bash
+./deb.makefile deb-clean
+```
+
+<br>
+
+## 卸载
+
+```bash
+sudo apt-get remove chsrc
+```
+
+包括删除配置在内的完全删除：
+
+```bash
+sudo apt-get purge chsrc
+```
+
+<br>
+
+
+## 故障排查
+
+常见问题：
+
+1. **构建失败**: 检查 debian/control 中的依赖是否正确
+2. **交叉编译失败**: 确认目标架构的工具链已正确安装
+3. **安装测试失败**: 检查 postinst 脚本是否有错误
+
+<br>
--- a/pkg/deb/CI.md
+++ b/pkg/deb/CI.md
@@ -0,0 +1,61 @@
+<!-- -----------------------------------------------------------
+ ! SPDX-License-Identifier: GFDL-1.3-or-later
+ ! -------------------------------------------------------------
+ ! Doc Type      : Markdown
+ ! Doc Name      : CI.md
+ ! Doc Authors   : sanchuanhehe <wyihe5520@gmail.com>
+ ! Contributors  :  Aoran Zeng  <ccmywish@qq.com>
+ !               |
+ ! Created On    : <2025-06-14>
+ ! Last Modified : <2025-06-16>
+ ! ---------------------------------------------------------- -->
+
+# deb package CI/CD
+
+本文档说明了 chsrc 项目的 deb 包自动构建和发布流程。
+
+## CI 文件
+
+CI 维护者 [@sanchuanhehe](https://github.com/sanchuanhehe)
+
+- [.github/workflows/pkg-deb.yml](../../.github/workflows/pkg-deb.yml)
+
+<br>
+
+## 支持的架构
+
+当前支持以下架构的 deb 包构建：
+
+- `amd64` (x86_64)
+
+<br>
+
+## CI 构建产物
+
+每次 CI 构建会生成：
+
+1. **deb 包文件**: `chsrc_<version>-1_<arch>.deb`
+2. **仓库元数据**: `Packages` 和 `Packages.gz` 文件用于创建 APT 仓库
+
+<br>
+
+
+## 自动触发
+
+deb 包构建 CI 会在以下情况下自动触发：
+
+1. **Push 事件**：当 push 到 `gh-build` 分支时自动构建，并上传 deb 包 到 `pre` 这个特定的 release 中
+2. **Release 事件**: 当创建新的 release 时自动构建，并上传 deb 包到最新的这个 release 中
+2. **手动触发**: 可以在 GitHub Actions 页面手动触发构建
+
+<br>
+
+## 手动发布流程
+
+1. 确保所有代码已合并到主分支
+2. 更新版本号和 changelog
+3. 创建并推送 git tag: `git tag v1.2.3 && git push origin v1.2.3`
+4. 在 GitHub 上创建 release
+5. CI 将自动构建并上传 deb 包
+
+<br>
--- a/pkg/deb/README.md
+++ b/pkg/deb/README.md
@@ -0,0 +1,64 @@
+<!-- -----------------------------------------------------------
+ ! SPDX-License-Identifier: GFDL-1.3-or-later
+ ! -------------------------------------------------------------
+ ! Doc Type      : Markdown
+ ! Doc Name      : README.md
+ ! Doc Authors   : sanchuanhehe <wyihe5520@gmail.com>
+ !               |  Aoran Zeng  <ccmywish@qq.com>
+ ! Contributors  :   Nil Null   <nil@null.org>
+ !               |
+ ! Created On    : <2025-06-14>
+ ! Last Modified : <2025-06-16>
+ ! ---------------------------------------------------------- -->
+
+# deb package
+
+本文档说明了 `chsrc` 项目的 deb 包的相关情况
+
+<br>
+
+## 相关文件
+
+- `.github/workflows/pkg-deb.yml` - CI 配置文件
+- `CI.md` - CI 情况说明
+
+<wbr>
+
+- `debian/` - deb 包构建配置目录
+- `BUILD.md` - 如何手动构建
+- `deb.makefile` - deb 包构建 Makefile
+- `deb-installation-test.sh` - deb 包 **已正确安装** 测试脚本
+
+<br>
+
+
+## 安装
+
+如果你是普通用户，你应该从 [GitHub Releases](https://github.com/RubyMetric/chsrc/releases) 下载合适的 deb 包，然后运行以下命令安装：
+
+```bash
+sudo dpkg -i chsrc_*.deb
+sudo apt-get install -f  # Fix any dependency issues
+```
+
+如果你是高级用户，你可以自己阅读本目录下的 [./BUILD.md](./BUILD.md) 来自己构建 deb 包并按照上述同样的方式安装。
+
+<br>
+
+
+## `debian/` 目录结构
+
+```
+debian/
+├── changelog      # 版本更新日志
+├── compat         # debhelper 兼容性版本
+├── control        # 包控制信息和依赖
+├── copyright      # 版权信息
+├── postinst       # 安装后脚本
+├── prerm          # 卸载前脚本
+└── rules          # 构建规则
+```
+
+其中，最后三个是 `+x` 的可执行文件。
+
+<br>
--- a/pkg/deb/deb-installation-test.sh
+++ b/pkg/deb/deb-installation-test.sh
@@ -0,0 +1,55 @@
+#!/bin/bash
+# --------------------------------------------------------------
+# SPDX-License-Identifier: GPL-3.0-or-later
+# --------------------------------------------------------------
+# Test File     : deb-installation-test.sh
+# File Authors  : sanchuanhehe <wyihe5520@gmail.com>
+# Contributors  :  Aoran Zeng  <ccmywish@qq.com>
+#	            |
+# Created On    : <2025-06-14>
+# Last Modified : <2025-06-16>
+#
+# Test script for deb package installation
+# --------------------------------------------------------------
+
+set -e
+
+echo "Testing installation of deb package 'chsrc' ..."
+
+# Test 1: Check if chsrc binary exists and is executable
+if [ ! -f "/usr/bin/chsrc" ]; then
+    echo "ERROR: /usr/bin/chsrc not found"
+    exit 1
+fi
+
+if [ ! -x "/usr/bin/chsrc" ]; then
+    echo "ERROR: /usr/bin/chsrc is not executable"
+    exit 1
+fi
+
+echo "✓ /usr/bin/chsrc binary exists and is executable"
+
+# Test 2: Check if man page exists
+if [ ! -f "/usr/share/man/man1/chsrc.1" ]; then
+    echo "WARNING: chsrc man page not found at /usr/share/man/man1/chsrc.1"
+else
+    echo "✓ chsrc man page exists"
+fi
+
+# Test 3: Test basic functionality
+echo "Testing basic chsrc functionality..."
+if /usr/bin/chsrc help >/dev/null 2>&1; then
+    echo "✓ command 'chsrc help' works"
+else
+    echo "ERROR: command 'chsrc help' failed"
+    exit 1
+fi
+
+if /usr/bin/chsrc list >/dev/null 2>&1; then
+    echo "✓ command 'chsrc list' works"
+else
+    echo "ERROR: command 'chsrc list' failed"
+    exit 1
+fi
+
+echo "All installation tests of deb package 'chsrc' passed!"
--- a/pkg/deb/deb.makefile
+++ b/pkg/deb/deb.makefile
@@ -0,0 +1,37 @@
+#!/usr/bin/make -f
+# --------------------------------------------------------------
+# SPDX-License-Identifier: GPL-3.0-or-later
+# --------------------------------------------------------------
+# Build File    : deb.makefile
+# File Authors  : sanchuanhehe <wyihe5520@gmail.com>
+# Contributors  :  Aoran Zeng  <ccmywish@qq.com>
+#								|
+# Created On    : <2025-06-14>
+# Last Modified : <2025-06-16>
+#
+# deb package targets
+#
+# @issue https://github.com/RubyMetric/chsrc/pull/206
+# 这些本是 debhelper 兼容性版本 (debian/compat) 为 9 时所需要定义的 targets
+# 然而现在已经为版本 13 (debian/compat已移除)，不再需要这些 targets，仅出于
+# 实用目的保留。由于以上原因，也不要修改这些 targets 的名称。
+# --------------------------------------------------------------
+
+all: deb-build
+
+deb-prepare:
+	@echo "Starting: Prepare for building deb package"
+	@echo "Finished: Prepare for building deb package"
+
+deb-build: deb-prepare
+	@echo "Starting: Build deb package"
+	@debuild -us -uc -b
+	@echo "Finished: Build deb package"
+
+deb-clean:
+	@echo "Starting: Clean deb build artifacts"
+	-@rm -rf debian/chsrc/
+	-@rm -f ../chsrc_*.deb ../chsrc-dbgsym_*.ddeb ../chsrc_*.changes ../chsrc_*.buildinfo ../chsrc_*.build
+	@echo "Finished: Clean deb build artifacts"
+
+.PHONY: deb-prepare deb-build deb-clean
--- a/pkg/deb/debian/changelog
+++ b/pkg/deb/debian/changelog
@@ -0,0 +1,11 @@
+chsrc (0.2.0-1) unstable; urgency=medium
+
+  * v0.2.0 已发布
+
+ -- Aoran Zeng <ccmywish@qq.com>  Sun, 15 Jun 2025 13:32:50 +0800
+
+chsrc (0.0.1-1) unstable; urgency=medium
+
+  * Initial deb package get packaged!
+
+ -- sanchuanhehe <wyihe5520@gmail.com>  Mon, 10 Jun 2025 00:00:00 +0000
--- a/pkg/deb/debian/control
+++ b/pkg/deb/debian/control
@@ -0,0 +1,18 @@
+Source: chsrc
+Section: utils
+Priority: optional
+Maintainer: sanchuanhehe <wyihe5520@gmail.com>
+Build-Depends: debhelper-compat (= 13), build-essential, libc6-dev
+Standards-Version: 4.6.0
+Homepage: https://chsrc.run/
+Vcs-Git: https://github.com/RubyMetric/chsrc.git
+Vcs-Browser: https://github.com/RubyMetric/chsrc
+
+Package: chsrc
+Architecture: any
+Depends: ${shlibs:Depends}, ${misc:Depends}
+Description: Change Source - A tool for changing software sources
+ chsrc is a command-line tool for changing software sources (mirrors)
+ for various package managers and programming language ecosystems.
+ It supports automatic detection and switching of sources for better
+ download speeds in different regions.
--- a/pkg/deb/debian/copyright
+++ b/pkg/deb/debian/copyright
@@ -0,0 +1,50 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: chsrc
+Upstream-Contact: Aoran Zeng <ccmywish@qq.com>
+Source: https://github.com/RubyMetric/chsrc
+
+Files: *
+Copyright: 2023-2025 Aoran Zeng <ccmywish@qq.com>
+           2023-2025  Heng Guo  <2085471348@qq.com>
+License: GPL-3+
+Comment: The authors' names are indicated in each source code file's header.
+
+Files: lib/xy.h
+Copyright: 2023-2025 Aoran Zeng <ccmywish@qq.com>
+           2023-2025  Heng Guo  <2085471348@qq.com>
+License: MIT
+
+Files: pkg/deb/debian/*
+Copyright: 2025 sanchuanhehe <wyihe5520@gmail.com>
+License: GPL-3+
+
+License: GPL-3+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+ .
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+ .
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <https://www.gnu.org/licenses/>.
+ .
+ On Debian systems, the complete text of the GNU General
+ Public License version 3 can be found in "/usr/share/common-licenses/GPL-3".
+Comment:
+ On Debian systems, the full text of the GNU General Public License
+ version 3 can be found in the file '/usr/share/common-licenses/GPL-3'.
+
+License: MIT
+ MIT License
+
+ Copyright (c) 2023-2025 曾奥然 (Aoran Zeng), 郭恒 (Heng Guo)
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
--- a/pkg/deb/debian/postinst
+++ b/pkg/deb/debian/postinst
@@ -0,0 +1,42 @@
+#!/bin/sh
+# --------------------------------------------------------------
+# SPDX-License-Identifier: GPL-3.0-or-later
+# --------------------------------------------------------------
+# deb File      : postinst
+# File Authors  : sanchuanhehe <wyihe5520@gmail.com>
+# Contributors  :   Nil Null   <nil@null.org>
+#	            |
+# Created On    : <2025-06-14>
+# Last Modified : <2025-06-16>
+#
+# postinst script for chsrc
+# --------------------------------------------------------------
+
+set -e
+
+case "$1" in
+    configure)
+        # Update man database
+        if command -v mandb >/dev/null 2>&1; then
+            mandb -q /usr/share/man/man1/chsrc.1 2>/dev/null || true
+        fi
+
+        # Make sure chsrc is executable
+        chmod +x /usr/bin/chsrc
+
+        echo "chsrc has been successfully installed!"
+        echo "Run 'chsrc help' to get started."
+        ;;
+
+    abort-upgrade|abort-remove|abort-deconfigure)
+        ;;
+
+    *)
+        echo "postinst called with unknown argument \`$1'" >&2
+        exit 1
+        ;;
+esac
+
+#DEBHELPER#
+
+exit 0
--- a/pkg/deb/debian/prerm
+++ b/pkg/deb/debian/prerm
@@ -0,0 +1,33 @@
+#!/bin/sh
+# --------------------------------------------------------------
+# SPDX-License-Identifier: GPL-3.0-or-later
+# --------------------------------------------------------------
+# deb File      : prerm
+# File Authors  : sanchuanhehe <wyihe5520@gmail.com>
+# Contributors  :   Nil Null   <nil@null.org>
+#	            |
+# Created On    : <2025-06-14>
+# Last Modified : <2025-06-16>
+#
+# prerm script for chsrc
+# --------------------------------------------------------------
+
+set -e
+
+case "$1" in
+    remove|upgrade|deconfigure)
+        # Nothing special to do during removal
+        ;;
+
+    failed-upgrade)
+        ;;
+
+    *)
+        echo "prerm called with unknown argument \`$1'" >&2
+        exit 1
+        ;;
+esac
+
+#DEBHELPER#
+
+exit 0
--- a/pkg/deb/debian/rules
+++ b/pkg/deb/debian/rules
@@ -0,0 +1,49 @@
+#!/usr/bin/make -f
+# --------------------------------------------------------------
+# SPDX-License-Identifier: GPL-3.0-or-later
+# --------------------------------------------------------------
+# Build File    : rules
+# File Authors  : sanchuanhehe <wyihe5520@gmail.com>
+#               |  Aoran Zeng  <ccmywish@qq.com>
+# Contributors  :   Nil Null   <nil@null.org>
+#								|
+# Created On    : <2025-06-14>
+# Last Modified : <2025-06-15>
+#
+# 该文件是 Makefile 格式
+# --------------------------------------------------------------
+#
+# debuild 调用 dpkg-buildpackage
+#
+# dpkg-buildpackage 通过调用 fakeroot debian/rules <target> 执行本文件
+#
+# 由于下面的 %，所有任务都将被传递给 dh
+#
+# 比如：
+#
+# 	 debian/rules <target>
+#
+# 会转换为：
+#
+#			dh <target>
+#
+# 来执行
+#
+# 简单理解，将顺序调用:
+#		1. dh clean
+#		2. dh build  (debian/rules override_dh_auto_build)
+#		3. dh binary (debian/rules override_dh_auto_install)
+# --------------------------------------------------------------
+
+# 由于 debuild 要寻找 debian/ 目录，因此当前工作目录一定在 pkg/deb 下
+Chsrc-Root-Dir = $(CURDIR)/../../
+
+%:
+	dh $@
+
+override_dh_auto_build:
+# 切换到 chsrc 根目录
+	@$(MAKE) -C $(Chsrc-Root-Dir) all
+
+override_dh_auto_install:
+	@$(MAKE) -C $(Chsrc-Root-Dir) install DESTDIR=$(CURDIR)/debian/chsrc