Linux平台wiliwili Debian软件包制作指南

需求分析：为什么需要Debian打包

在Linux系统中，Debian软件包（.deb）是软件分发的标准形式，它能解决依赖管理、文件权限控制和系统集成等关键问题。对于wiliwili这款专为手柄控制设计的跨平台B站客户端，制作Debian软件包具有以下核心价值：

• 简化安装流程：用户可通过dpkg -i或图形化包管理器一键安装
• 标准化文件布局：确保可执行文件、图标和配置文件放置在系统约定位置
• 自动依赖处理：通过控制文件声明依赖关系，避免"缺少xxx库"的运行错误
• 系统集成优化：支持桌面环境菜单显示、图标关联和卸载清理

图1：wiliwili客户端主界面展示，采用手柄友好的大图标布局设计

环境搭建：从依赖到资源

环境依赖清单

工具/库	作用	最低版本要求
dpkg-deb	Debian软件包构建工具	1.19.0
dh-make	Debian打包辅助工具	2.201903
cmake	跨平台构建系统	3.10.0
g++	C++编译器	7.4.0
libmpv-dev	媒体播放库开发文件	0.29.0
libsdl2-dev	跨平台多媒体库	2.0.9

🔧 小贴士：可通过dpkg -l <package>检查已安装版本，例如dpkg -l dpkg-deb

项目资源解析

wiliwili项目中与Linux打包相关的核心文件位于以下路径：

• 桌面集成文件：scripts/linux/cn.xfangfang.wiliwili.desktop
  定义应用在桌面环境中的显示名称、图标和启动命令

• 图标资源：scripts/linux/icons/
  包含16x16至256x256多种分辨率的应用图标

• 构建脚本参考：scripts/build_mac.sh
  虽为macOS设计，但可作为Linux构建流程的参考模板

• Debian控制模板：scripts/deb/switchroot-bionic/control
  提供软件包元数据和依赖声明的基础配置

核心流程：Debian包逆向构建法

目标目录结构

我们采用"逆向拆解法"，先明确最终Debian包的内部结构，再逐步填充内容：

wiliwili_1.5.2-1_amd64/
├── DEBIAN/                 # 包元数据目录
│   ├── control             # 包信息与依赖声明
│   ├── md5sums             # 文件校验和
│   └── postinst            # 安装后脚本
└── usr/
    ├── bin/
    │   └── wiliwili        # 主程序可执行文件
    ├── share/
    │   ├── applications/
    │   │   └── cn.xfangfang.wiliwili.desktop  # 桌面文件
    │   └── icons/
    │       └── hicolor/    # 图标文件按尺寸分类
    │           ├── 16x16/apps/
    │           ├── 24x24/apps/
    │           └── ...(其他尺寸)

构建步骤详解

1. 源代码编译 [===== ] 50%

目的：将源代码编译为可执行文件
命令：

mkdir -p build && cd build
cmake .. -DPLATFORM_DESKTOP=ON -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

预期输出：在build/wiliwili路径生成可执行文件

🔧 小贴士：若编译失败，检查是否安装所有依赖库的开发版本（通常以-dev结尾）

2. 图标资源准备 [======= ] 70%

目的：生成并整理不同尺寸的应用图标
命令：

cd scripts/linux
chmod +x gen_icons.sh
./gen_icons.sh

预期输出：在icons目录下生成16x16、24x24等8种尺寸的PNG图标

3. 控制文件创建 [========= ] 90%

创建DEBIAN/control文件，内容如下：

Section: video
Priority: optional
Maintainer: xfangfang <[e-mail]>
Version: 1.5.2-1
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 specifically for controller users

🔧 小贴士：Architecture字段需根据实际编译架构修改，常见值有amd64(x86_64)、i386(32位x86)等

4. 软件包构建 [===========] 100%

目的：使用dpkg-deb生成最终的.deb文件
命令：

dpkg-deb --build wiliwili_1.5.2-1_amd64

预期输出：当前目录生成wiliwili_1.5.2-1_amd64.deb文件

问题解决：常见故障诊断

依赖问题排查流程

┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│ 安装失败并  │────>│ 检查control  │────>│ 执行apt-get   │
│ 提示缺少依赖 │     │ 文件Depends  │     │ install -f    │
└─────────────┘     └──────────────┘     └───────────────┘
        │                                        │
        │                                        ▼
        └────────────────────────────> 重新尝试安装软件包

图标不显示问题

1. 确认图标文件安装路径正确：/usr/share/icons/hicolor/<尺寸>/apps/
2. 运行update-icon-caches /usr/share/icons/hicolor/更新图标缓存
3. 检查.desktop文件中Icon字段是否与图标文件名一致

执行权限问题

若出现"权限被拒绝"错误，检查：

• 可执行文件是否设置执行权限：chmod +x /usr/bin/wiliwili
• postinst脚本是否有执行权限：chmod 755 DEBIAN/postinst

成果验证：安装与功能测试

软件包安装

sudo dpkg -i wiliwili_1.5.2-1_amd64.deb

验证项清单

• [ ] 在应用菜单中能找到wiliwili图标
• [ ] 点击图标能正常启动应用
• [ ] 手柄控制功能正常工作
• [ ] 视频播放和弹幕显示正常
• [ ] 应用能正确访问网络资源

卸载测试

sudo dpkg -r wiliwili

验证是否完全清理：

• /usr/bin/wiliwili已删除
• 图标和桌面文件已移除
• 配置文件目录~/.config/wiliwili保留（正常行为）

总结：定制化与扩展

自定义打包参数表

参数	作用	可选值	默认值
-DCMAKE_BUILD_TYPE	构建类型	Debug/Release	Release
-DENABLE_ANALYTICS	启用统计功能	ON/OFF	ON
-DUSE_SYSTEM_MPV	使用系统MPV库	ON/OFF	OFF
-DPLATFORM_DESKTOP	桌面平台构建	ON/OFF	ON

高级打包技巧

1. 版本号自动生成：结合git commit信息生成版本号

   VERSION=$(git rev-list --count HEAD)-$(git rev-parse --short HEAD)
   

2. 多架构构建：使用dpkg-cross工具链实现交叉编译

3. CI/CD集成：配置GitHub Actions实现提交后自动打包

通过本指南，你已掌握将wiliwili客户端打包为Debian软件包的完整流程。这个过程不仅适用于wiliwili，也可作为其他Linux应用打包的参考模板。根据实际需求调整控制文件和构建参数，即可生成满足特定发行版要求的软件包。