ScreenLockDetector/PACKAGING_README.md

# Qt Screen Lock Demo - DEB 打包总览

本文档提供 DEB 打包的快速入门指南。

## 📦 快速开始

### 一键打包

```bash
# 赋予执行权限（首次运行）
chmod +x make_deb.sh

# 运行打包
./make_deb.sh
```

打包完成后，DEB 文件位于：`deb_package/screenlockdemo_1.0.0_amd64.deb`

### 安装测试

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

# 运行
screenlockdemo

# 卸载
sudo dpkg -r screenlockdemo
```

---

## 📁 打包文件说明

### 核心脚本

| 文件 | 说明 | 使用场景 |
|------|------|----------|
| `make_deb.sh` | 快速打包脚本 | ⭐ 推荐日常使用 |
| `build_deb.sh` | 完整打包脚本 | 需要详细日志和调试 |
| `create_icon.sh` | 图标生成脚本 | 创建应用图标（可选） |

### 配置文件

| 文件 | 说明 |
|------|------|
| `screenlockdemo.desktop` | 桌面快捷方式配置 |
| `debian/control` | DEB 包信息 |
| `debian/copyright` | 版权信息 |
| `debian/changelog` | 更新日志 |
| `debian/rules` | 构建规则（Makefile 格式） |
| `debian/compat` | Debian 兼容性版本 |

### 文档

| 文件 | 说明 |
|------|------|
| `DEB_PACKAGE.md` | 详细打包文档（460+ 行） |
| `PACKAGING_README.md` | 本文档 - 快速参考 |

---

## 🔧 环境要求

### 必需工具

1. **linuxdeployqt** - 依赖收集工具
   - 路径：`$HOME/dev/sunvpack-py/bin/linuxdeployqt`
   - 作用：自动收集 Qt 和所有依赖库

2. **Qt 5.15.2** - Qt 框架
   - 路径：`$HOME/sdk/qt-5.15.2`
   - 提供：Qt 库、插件、工具

3. **dpkg-dev** - DEB 打包工具
   ```bash
   sudo apt-get install dpkg-dev debhelper
   ```

### 验证环境

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

# 检查 Qt
ls -d $HOME/sdk/qt-5.15.2

# 检查 dpkg
dpkg-deb --version
```

---

## 🚀 打包流程

### make_deb.sh 流程（推荐）

```
[1/6] 清理目录
   └─ 删除旧的 deb_package/ 目录

[2/6] 编译项目
   └─ 运行 ./build.sh（如需要）

[3/6] 创建 AppDir
   ├─ 复制可执行文件
   ├─ 复制 desktop 文件
   └─ 创建图标占位符

[4/6] 收集依赖 (linuxdeployqt)
   ├─ 扫描程序依赖
   ├─ 复制 Qt 库
   ├─ 复制 Qt 插件
   └─ 设置 RPATH

[5/6] 创建 DEB 包结构
   ├─ /opt/screenlockdemo/     # 程序和库
   ├─ /usr/bin/                # 命令链接
   ├─ /usr/share/applications/ # 桌面快捷方式
   └─ /DEBIAN/                 # 包控制文件

[6/6] 构建 DEB 包
   └─ 运行 dpkg-deb --build
```

### build_deb.sh 流程（详细版）

```
[1/8] 清理之前的打包目录
[2/8] 编译项目
[3/8] 创建 AppDir 结构
[4/8] 使用 linuxdeployqt 收集所有依赖
[5/8] 创建 DEB 包目录结构
[6/8] 创建控制文件
[7/8] 创建安装脚本
[8/8] 构建 DEB 包
```

---

## 📦 DEB 包内容

### 安装后的文件结构

```
/opt/screenlockdemo/
├── bin/
│   └── ScreenLockDemo              # 主程序
├── lib/
│   ├── libQt5Core.so.5             # Qt 核心库
│   ├── libQt5Gui.so.5              # Qt GUI 库
│   ├── libQt5Widgets.so.5          # Qt Widgets 库
│   ├── libQt5DBus.so.5             # Qt DBus 库
│   └── ...                          # 其他依赖库
├── plugins/
│   ├── platforms/
│   │   └── libqxcb.so              # X11 平台插件
│   ├── imageformats/               # 图像格式插件
│   └── ...                          # 其他 Qt 插件
└── screenlockdemo.sh               # 启动包装脚本

/usr/bin/
└── screenlockdemo → /opt/screenlockdemo/screenlockdemo.sh

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

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

### 包大小估算

- **典型大小**：50-80 MB
- **包含**：Qt 5.15.2 的所有必需库和插件
- **优点**：无需系统安装 Qt，避免依赖冲突

---

## 🎯 使用场景

### 场景 1：快速打包测试

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

### 场景 2：发布版本

```bash
# 1. 更新版本号
vim make_deb.sh  # 修改 VERSION="1.0.1"

# 2. 创建图标（可选）
./create_icon.sh

# 3. 完整打包
./build_deb.sh

# 4. 测试安装
sudo dpkg -i package/screenlockdemo_1.0.1_amd64.deb

# 5. 验证功能
screenlockdemo
```

### 场景 3：调试打包问题

```bash
# 使用详细版脚本
./build_deb.sh

# 查看 AppDir 内容
ls -lR package/AppDir/

# 查看 DEB 包内容
dpkg -c package/screenlockdemo_1.0.0_amd64.deb

# 查看包信息
dpkg -I package/screenlockdemo_1.0.0_amd64.deb
```

---

## ⚠️ 常见问题速查

### 问题：linuxdeployqt 未找到

```bash
# 检查路径
ls $HOME/dev/sunvpack-py/bin/linuxdeployqt

# 如果路径不同，修改脚本中的 LINUXDEPLOYQT 变量
```

### 问题：Qt 未找到

```bash
# 检查 Qt 目录
ls $HOME/sdk/qt-5.15.2

# 如果路径不同，修改脚本中的 QT_DIR 变量
```

### 问题：程序无法启动

```bash
# 查看错误信息
/opt/screenlockdemo/bin/ScreenLockDemo

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

# 安装缺失的系统库
sudo apt-get install libgl1 libx11-6 libxcb-xinerama0
```

### 问题：桌面图标不显示

```bash
# 更新图标缓存
sudo gtk-update-icon-cache -f /usr/share/icons/hicolor

# 更新桌面数据库
sudo update-desktop-database
```

---

## 🔄 修改版本号

### 在 make_deb.sh 中

```bash
# 第 7 行
VERSION="1.0.0"  # 改为新版本，如 "1.0.1"
```

### 在 build_deb.sh 中

```bash
# 第 14 行
VERSION="1.0.0"  # 改为新版本，如 "1.0.1"
```

### 在 debian/changelog 中

```bash
screenlockdemo (1.0.1-1) unstable; urgency=low

  * 更新内容描述

 -- 维护者 <email@example.com>  Mon, 15 Jan 2024 12:00:00 +0800
```

---

## 📚 更多信息

- **详细文档**：查看 `DEB_PACKAGE.md` （460+ 行完整指南）
- **项目文档**：查看 `README.md`
- **架构说明**：查看 `ARCHITECTURE.md`

---

## 🎉 成功标志

打包成功后，你应该看到：

```
=========================================
✓ 打包成功！
=========================================
包文件: deb_package/screenlockdemo_1.0.0_amd64.deb
大小: 52M

安装: sudo dpkg -i deb_package/screenlockdemo_1.0.0_amd64.deb
卸载: sudo dpkg -r screenlockdemo
```

---

## 📞 下一步

1. ✅ 安装测试：`sudo dpkg -i deb_package/screenlockdemo_1.0.0_amd64.deb`
2. ✅ 功能测试：运行 `screenlockdemo`，锁屏测试（Ctrl+Alt+L）
3. ✅ 其他系统测试：在不同 Ubuntu 版本上安装测试
4. ✅ 文档完善：添加真实图标、更新维护者信息

**祝打包顺利！** 🚀