Linux系统下wiliwili应用的Debian软件包构建指南

一、需求分析

1.1 功能定位

wiliwili作为专为手柄控制设计的第三方B站客户端，支持多平台运行。在Linux环境中通过Debian软件包形式分发，可简化安装流程并确保系统集成度。本指南旨在提供从源码到可安装包的完整构建路径。

1.2 应用场景

• 为Debian/Ubuntu系列发行版用户提供标准化安装方式
• 满足离线环境下的应用部署需求
• 便于软件仓库维护和版本管理
• 支持系统级别的权限控制和资源管理

二、环境配置

2.1 环境依赖清单

核心工具链

• 构建工具：cmake (3.10+)、make、gcc/g++ (8.0+)
• 打包工具：dpkg-dev (1.19+)、fakeroot
• 依赖库：libmpv-dev、libcurl4-openssl-dev、libssl-dev、libass-dev

安装命令

sudo apt update && sudo apt install -y cmake make g++ dpkg-dev fakeroot \
libmpv-dev libcurl4-openssl-dev libssl-dev libass-dev libwebp-dev

2.2 项目资源定位

关键文件路径说明：

• 构建配置：CMakeLists.txt（项目根目录）
• 桌面集成：scripts/linux/cn.xfangfang.wiliwili.desktop
• 图标资源：scripts/linux/icons/（多分辨率图标集）
• Debian模板：scripts/deb/switchroot-bionic/（控制文件参考）

三、核心流程

3.1 源码编译

原理阐述：采用CMake构建系统生成平台相关的Makefile，通过Release模式优化编译产物。

实操演示：

# 创建并进入构建目录
mkdir -p build/linux && cd build/linux

# 生成Makefile (启用桌面平台支持)
cmake ../.. -DPLATFORM_DESKTOP=ON -DCMAKE_BUILD_TYPE=Release

# 多线程编译
make -j$(nproc)

注意事项：

• 编译失败时检查依赖库版本，特别是libmpv需至少2.0.0版本
• 可添加-DCMAKE_INSTALL_PREFIX=/usr指定安装路径
• 如需调试，可将CMAKE_BUILD_TYPE设为Debug

3.2 打包资源准备

原理阐述：遵循FHS标准组织文件结构，确保软件包符合Debian政策要求。

实操演示：

# 创建打包工作目录
mkdir -p wiliwili-deb/usr/{bin,share/applications,share/icons/hicolor}

# 复制可执行文件
cp build/linux/wiliwili wiliwili-deb/usr/bin/

# 处理桌面文件
sed "s|Exec=wiliwili|Exec=/usr/bin/wiliwili|" \
scripts/linux/cn.xfangfang.wiliwili.desktop > \
wiliwili-deb/usr/share/applications/cn.xfangfang.wiliwili.desktop

# 安装图标
for size in 16x16 24x24 32x32 48x48 64x64 128x128 256x256; do
  mkdir -p wiliwili-deb/usr/share/icons/hicolor/$size/apps/
  cp scripts/linux/icons/$size/cn.xfangfang.wiliwili.png \
  wiliwili-deb/usr/share/icons/hicolor/$size/apps/
done

注意事项：

• 桌面文件必须包含绝对路径，否则系统无法定位可执行文件
• 图标文件名需与.desktop文件中的Icon字段保持一致
• 所有文件需设置正确权限（一般为644）

3.3 Debian包构建

原理阐述：通过DEBIAN目录中的控制文件定义包信息，使用dpkg-deb工具构建二进制包。

实操演示：

# 创建DEBIAN控制目录
mkdir -p wiliwili-deb/DEBIAN

# 生成控制文件
cat > wiliwili-deb/DEBIAN/control << EOF
Section: video
Priority: optional
Maintainer: Your Name <[e-mail]>
Version: 1.5.2-1
Homepage: https://example.com/wiliwili
Package: wiliwili
Architecture: amd64
Depends: libass9, libdbus-1-3, libx11-6, libv4l-0, libpulse0, libuchardet0, libwebp6, libssl1.1
Description: A third-party Bilibili client designed for controller users
EOF

# 构建deb包
dpkg-deb --build wiliwili-deb

注意事项：

• Architecture字段需与实际编译架构匹配（amd64/i386/arm64等）
• Depends字段需根据目标系统调整依赖版本
• 控制文件必须使用Unix换行符，否则会导致构建失败

四、问题排查

4.1 常见构建错误

依赖缺失

• 症状：编译时提示"undefined reference to"
• 解决：使用dpkg -S查找缺失库对应的开发包，如：dpkg -S libmpv.so

权限问题

• 症状：安装时提示"permission denied"
• 解决：确保DEBIAN目录权限为755，文件权限为644

架构不匹配

• 症状：运行时提示"wrong ELF class"
• 解决：检查编译架构与目标系统是否一致，可使用file wiliwili确认

4.2 安装验证方法

# 安装测试
sudo dpkg -i wiliwili-deb.deb

# 验证文件安装
dpkg -L wiliwili

# 检查依赖关系
ldd /usr/bin/wiliwili

# 启动应用
wiliwili

五、扩展建议

5.1 跨架构适配方案

多架构构建策略：

1. 本地交叉编译

# 示例：为arm64架构交叉编译
cmake .. -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
-DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \
-DPLATFORM_DESKTOP=ON

2. Docker多阶段构建 利用项目中scripts/deb/switchroot-bionic/Dockerfile修改为多架构构建环境，结合QEMU实现跨平台编译。

3. Launchpad PPA构建 注册Ubuntu Launchpad账号，配置多架构构建环境，实现自动构建多种架构的Debian包。

5.2 自动化打包建议

CI/CD集成：

1. GitHub Actions工作流

name: Build Debian Package
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: sudo apt install -y cmake make g++ dpkg-dev fakeroot libmpv-dev
      - name: Build package
        run: bash scripts/build_deb.sh

2. 本地打包脚本 创建scripts/build_deb.sh整合编译、资源处理和打包步骤，添加版本自动递增逻辑。

3. 签名与分发 使用debsign工具对软件包进行GPG签名，通过PPA或自建仓库分发，确保软件完整性。

前置知识提示

• 熟悉Debian软件包结构（DEBIAN目录、文件系统布局）
• 了解CMake构建系统基本原理
• 掌握Linux命令行操作和权限管理

最佳实践

1. 版本控制：使用语义化版本号，确保每次构建可追溯
2. 依赖最小化：仅包含运行必需的依赖项，减少包体积
3. 测试覆盖：在多种Debian/Ubuntu版本上验证兼容性
4. 文档完善：为软件包添加详细的README和 changelog
5. 安全审计：定期更新依赖库以修复安全漏洞

通过本指南，开发者可以系统地构建符合Debian标准的wiliwili软件包，为Linux用户提供便捷的安装体验。该流程既适用于个人使用，也可扩展为社区维护的正式软件源。