ScreenLockDetector/docs/DEB_PACKAGE.md

# DEB 打包说明文档

本文档说明如何将 Qt Screen Lock Demo 打包成 DEB 安装包。

## 目录

- [打包准备](#打包准备)
- [快速打包](#快速打包)
- [完整打包](#完整打包)
- [打包原理](#打包原理)
- [测试安装](#测试安装)
- [常见问题](#常见问题)

---

## 打包准备

### 1. 必需工具

确保以下工具已安装：

```bash
# 安装打包工具
sudo apt-get install dpkg-dev debhelper

# 检查 linuxdeployqt 工具
ls -lh $HOME/dev/sunvpack-py/bin/linuxdeployqt
```

### 2. 环境要求

- **Qt 5.15.2** 安装在 `$HOME/sdk/qt-5.15.2`
- **linuxdeployqt** 工具在 `$HOME/dev/sunvpack-py/bin/linuxdeployqt`
- **编译好的程序** 或可以运行 `./build.sh` 编译

### 3. 文件清单

打包相关文件：

```
qt_screan_lock/
├── build_deb.sh              # 完整打包脚本（推荐）
├── make_deb.sh               # 快速打包脚本
├── screenlockdemo.desktop    # 桌面快捷方式
├── debian/                   # Debian 打包配置
│   ├── control              # 包信息
│   ├── copyright            # 版权信息
│   ├── changelog            # 更新日志
│   ├── rules                # 构建规则
│   └── compat               # 兼容性版本
└── DEB_PACKAGE.md           # 本文档
```

---

## 快速打包

如果你想快速生成一个 DEB 包，使用 `make_deb.sh`：

### 步骤 1：赋予执行权限

```bash
chmod +x make_deb.sh
```

### 步骤 2：运行打包脚本

```bash
./make_deb.sh
```

### 步骤 3：等待完成

脚本会自动完成以下步骤：

1. ✓ 清理目录
2. ✓ 编译项目（如需要）
3. ✓ 创建 AppDir
4. ✓ 使用 linuxdeployqt 收集依赖
5. ✓ 创建 DEB 包结构
6. ✓ 构建 DEB 包

### 输出结果

打包完成后会生成：

```
deb_package/
├── screenlockdemo_1.0.0_amd64.deb    # DEB 安装包
└── AppDir/                            # 临时目录
```

DEB 包路径：`deb_package/screenlockdemo_1.0.0_amd64.deb`

---

## 完整打包

使用 `build_deb.sh` 可以获得更详细的日志和更完整的打包过程：

### 步骤 1：赋予执行权限

```bash
chmod +x build_deb.sh
```

### 步骤 2：运行打包脚本

```bash
./build_deb.sh
```

### 特点

- 彩色输出，更易读
- 详细的步骤说明
- 完整的错误检查
- 自动生成安装/卸载脚本
- 更详细的包信息

### 输出结果

```
package/
├── screenlockdemo_1.0.0_amd64.deb    # DEB 安装包
├── AppDir/                            # 临时目录
└── screenlockdemo_1.0.0_amd64/       # DEB 源目录
```

DEB 包路径：`package/screenlockdemo_1.0.0_amd64.deb`

---

## 打包原理

### linuxdeployqt 的作用

`linuxdeployqt` 是一个自动化工具，用于：

1. **扫描可执行文件** 的动态链接依赖
2. **复制所有 Qt 库** 到打包目录
3. **复制 Qt 插件** (platforms, imageformats 等)
4. **复制系统库** (如果需要)
5. **设置正确的 RPATH**

### DEB 包结构

最终的 DEB 包包含：

```
/opt/screenlockdemo/              # 应用程序安装目录
├── bin/
│   └── ScreenLockDemo           # 主程序
├── lib/                          # Qt 和依赖库
│   ├── libQt5Core.so.5
│   ├── libQt5Gui.so.5
│   ├── libQt5Widgets.so.5
│   ├── libQt5DBus.so.5
│   └── ...                       # 其他依赖库
├── plugins/                      # Qt 插件
│   ├── platforms/
│   │   └── libqxcb.so
│   └── ...
└── screenlockdemo.sh            # 启动包装脚本

/usr/bin/
└── screenlockdemo               # 系统命令链接

/usr/share/applications/
└── screenlockdemo.desktop       # 桌面快捷方式

/usr/share/icons/
└── hicolor/256x256/apps/
    └── screenlockdemo.png       # 应用图标
```

### 为什么这样打包？

1. **隔离依赖**：所有 Qt 库打包在 `/opt` 下，不影响系统库
2. **避免冲突**：不依赖系统 Qt 版本
3. **易于部署**：一个包包含所有依赖
4. **跨版本兼容**：可在不同 Ubuntu 版本上运行

### 启动包装脚本

`screenlockdemo.sh` 的作用：

```bash
#!/bin/bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
export LD_LIBRARY_PATH="${SCRIPT_DIR}/lib:$LD_LIBRARY_PATH"
export QT_PLUGIN_PATH="${SCRIPT_DIR}/plugins"
exec "${SCRIPT_DIR}/bin/ScreenLockDemo" "$@"
```

- 设置 `LD_LIBRARY_PATH` 指向打包的库
- 设置 `QT_PLUGIN_PATH` 指向打包的插件
- 确保程序使用打包的 Qt，而非系统 Qt

---

## 测试安装

### 1. 查看包信息

```bash
# 查看包的详细信息
dpkg -I deb_package/screenlockdemo_1.0.0_amd64.deb

# 查看包内文件列表
dpkg -c deb_package/screenlockdemo_1.0.0_amd64.deb
```

### 2. 安装包

```bash
sudo dpkg -i deb_package/screenlockdemo_1.0.0_amd64.deb
```

如果有依赖问题：

```bash
sudo apt-get install -f
```

### 3. 运行程序

**方法 1：命令行运行**

```bash
screenlockdemo
```

**方法 2：应用菜单**

在应用程序菜单中搜索 "Screen Lock Demo"

**方法 3：直接执行**

```bash
/opt/screenlockdemo/screenlockdemo.sh
```

### 4. 验证依赖

检查程序是否使用打包的库：

```bash
# 查看程序链接的库
ldd /opt/screenlockdemo/bin/ScreenLockDemo

# 应该看到库路径指向 /opt/screenlockdemo/lib/
```

### 5. 卸载包

```bash
sudo dpkg -r screenlockdemo
```

或完全清除（包括配置）：

```bash
sudo dpkg -P screenlockdemo
```

---

## 常见问题

### Q1: linuxdeployqt 报错 "ERROR: Desktop file missing"

**原因**：缺少 `.desktop` 文件

**解决**：确保 `screenlockdemo.desktop` 文件存在且格式正确

### Q2: 打包后的程序无法启动

**诊断**：

```bash
# 直接运行二进制文件查看错误
/opt/screenlockdemo/bin/ScreenLockDemo

# 检查库依赖
ldd /opt/screenlockdemo/bin/ScreenLockDemo
```

**常见原因**：
- 缺少某些系统库（libGL, libX11 等）
- Qt 插件未正确复制
- 权限问题

**解决**：
- 安装缺失的系统库：`sudo apt-get install libgl1 libx11-6`
- 检查 `plugins/platforms/libqxcb.so` 是否存在
- 检查文件权限：`chmod +x /opt/screenlockdemo/bin/ScreenLockDemo`

### Q3: 图标不显示

**原因**：图标文件缺失或路径错误

**解决**：
1. 检查 `/usr/share/icons/hicolor/256x256/apps/screenlockdemo.png` 是否存在
2. 更新图标缓存：`sudo gtk-update-icon-cache -f /usr/share/icons/hicolor`
3. 替换为真实图标文件

### Q4: Qt 平台插件错误

**错误信息**：
```
qt.qpa.plugin: Could not load the Qt platform plugin "xcb"
```

**解决**：

```bash
# 检查插件是否存在
ls /opt/screenlockdemo/plugins/platforms/libqxcb.so

# 检查插件依赖
ldd /opt/screenlockdemo/plugins/platforms/libqxcb.so

# 安装缺失的依赖
sudo apt-get install libxcb-xinerama0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0
```

### Q5: DBus 服务连接失败

**原因**：DBus 系统服务未运行

**解决**：

```bash
# 检查 DBus 服务
systemctl status dbus

# 启动 DBus 服务
sudo systemctl start dbus
```

### Q6: 想修改包版本号

编辑脚本中的版本号：

```bash
# 在 make_deb.sh 或 build_deb.sh 中修改
VERSION="1.0.1"  # 改为新版本号
```

### Q7: 想修改安装路径

默认安装到 `/opt/screenlockdemo`，如需修改：

1. 修改脚本中的 `PACKAGE_NAME`
2. 修改 DEB 目录结构创建部分
3. 修改 desktop 文件中的 `Exec` 路径

### Q8: 如何添加真实图标？

1. 准备一个 256x256 的 PNG 图标文件
2. 命名为 `icon.png` 放在项目根目录
3. 重新运行打包脚本

或者直接替换：

```bash
cp your_icon.png screenlockdemo.png
```

然后在打包脚本中复制此图标。

---

## 高级定制

### 自定义包信息

编辑 `debian/control` 文件：

- **Maintainer**：维护者信息
- **Description**：包描述
- **Depends**：依赖包列表
- **Section**：软件分类（utils, games, graphics 等）

### 添加安装后脚本

编辑 `DEBIAN/postinst`：

```bash
#!/bin/bash
set -e

# 在这里添加安装后要执行的命令
# 例如：创建配置文件、启动服务等

exit 0
```

### 添加卸载前脚本

创建 `DEBIAN/prerm`：

```bash
#!/bin/bash
set -e

# 在这里添加卸载前要执行的命令
# 例如：停止服务、备份数据等

exit 0
```

### 减小包体积

1. **不包含调试符号**：在打包脚本中运行 `strip` 命令
2. **排除不需要的插件**：修改 linuxdeployqt 参数
3. **使用 UPX 压缩**：压缩可执行文件（可能影响兼容性）

```bash
# 压缩可执行文件
strip "${DEB_DIR}/opt/${PACKAGE_NAME}/bin/${APP_NAME}"

# 压缩所有 .so 库
find "${DEB_DIR}/opt/${PACKAGE_NAME}/lib" -name "*.so*" -exec strip {} \;
```

---

## 发布检查清单

在发布 DEB 包之前，确保：

- [ ] 包可以正常安装
- [ ] 程序可以正常启动和运行
- [ ] 所有功能正常工作（锁屏检测、动画等）
- [ ] 桌面快捷方式可用
- [ ] 命令行启动可用
- [ ] 图标正确显示
- [ ] 可以正常卸载
- [ ] 在不同 Ubuntu 版本上测试
- [ ] 文档和帮助信息完整
- [ ] 版本号正确

---

## 参考资源

- [Debian 打包指南](https://www.debian.org/doc/manuals/maint-guide/)
- [linuxdeployqt GitHub](https://github.com/probonopd/linuxdeployqt)
- [Qt 部署指南](https://doc.qt.io/qt-5/linux-deployment.html)
- [dpkg 手册](https://man7.org/linux/man-pages/man1/dpkg.1.html)

---

## 联系与支持

如有问题或建议，欢迎反馈！

**祝打包顺利！** 🎉