9.4 KiB

Raw Blame History

DEB 打包说明文档

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

打包准备

1. 必需工具

确保以下工具已安装：

# 安装打包工具
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：赋予执行权限

chmod +x make_deb.sh

步骤 2：运行打包脚本

./make_deb.sh

步骤 3：等待完成

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

✓ 清理目录
✓ 编译项目（如需要）
✓ 创建 AppDir
✓ 使用 linuxdeployqt 收集依赖
✓ 创建 DEB 包结构
✓ 构建 DEB 包

输出结果

打包完成后会生成：

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

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

完整打包

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

步骤 1：赋予执行权限

chmod +x build_deb.sh

步骤 2：运行打包脚本

./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 是一个自动化工具，用于：

扫描可执行文件 的动态链接依赖
复制所有 Qt 库 到打包目录
复制 Qt 插件 (platforms, imageformats 等)
复制系统库 (如果需要)
设置正确的 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       # 应用图标

为什么这样打包？

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

启动包装脚本

screenlockdemo.sh 的作用：

#!/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. 查看包信息

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

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

2. 安装包

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

如果有依赖问题：

sudo apt-get install -f

3. 运行程序

方法 1：命令行运行

screenlockdemo

方法 2：应用菜单

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

方法 3：直接执行

/opt/screenlockdemo/screenlockdemo.sh

4. 验证依赖

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

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

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

5. 卸载包

sudo dpkg -r screenlockdemo

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

sudo dpkg -P screenlockdemo

常见问题

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

原因：缺少 .desktop 文件

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

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

诊断：

# 直接运行二进制文件查看错误
/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: 图标不显示

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

解决：

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

Q4: Qt 平台插件错误

错误信息：

qt.qpa.plugin: Could not load the Qt platform plugin "xcb"

解决：

# 检查插件是否存在
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 系统服务未运行

解决：

# 检查 DBus 服务
systemctl status dbus

# 启动 DBus 服务
sudo systemctl start dbus

Q6: 想修改包版本号

编辑脚本中的版本号：

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

Q7: 想修改安装路径

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

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

Q8: 如何添加真实图标？

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

或者直接替换：

cp your_icon.png screenlockdemo.png

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

高级定制

自定义包信息

编辑 debian/control 文件：

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

添加安装后脚本

编辑 DEBIAN/postinst：

#!/bin/bash
set -e

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

exit 0

添加卸载前脚本

创建 DEBIAN/prerm：

#!/bin/bash
set -e

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

exit 0

减小包体积

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

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

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

发布检查清单

在发布 DEB 包之前，确保：

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

参考资源

联系与支持

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

祝打包顺利！ 🎉

9.4 KiB Raw Blame History Unescape Escape

DEB 打包说明文档

目录

打包准备

1. 必需工具

2. 环境要求

3. 文件清单

快速打包

步骤 1：赋予执行权限

步骤 2：运行打包脚本

步骤 3：等待完成

输出结果

完整打包

步骤 1：赋予执行权限

步骤 2：运行打包脚本

特点

输出结果

打包原理

linuxdeployqt 的作用

DEB 包结构

为什么这样打包？

启动包装脚本

测试安装

1. 查看包信息

2. 安装包

3. 运行程序

4. 验证依赖

5. 卸载包

常见问题

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

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

Q3: 图标不显示

Q4: Qt 平台插件错误

Q5: DBus 服务连接失败

Q6: 想修改包版本号

Q7: 想修改安装路径

Q8: 如何添加真实图标？

高级定制

自定义包信息

添加安装后脚本

添加卸载前脚本

减小包体积

发布检查清单

参考资源

联系与支持

9.4 KiB

Raw Blame History