![]()
玲珑
作为一种新型的独立包管理工具集，玲珑主要提供分层与隔离的运行环境，解决传统包管理系统强依赖导致的兼容性问题，以及权限松散导致的安全问题。当前，玲珑已支持 4 个发行版，包括 deepin、统信 UOS 以及 Debian 和 Ubuntu。玲珑的隔离技术可以将应用与系统进行完全解耦，从而彻底解决系统与应用、应用与应用之间因升级和适配引起的兼容性冲突等问题。这对开发者而言，可以有效降低开发成本；对客户而言，能够降低企业运维成本；而对整个行业而言，将助力行业稳健发展。
安装玲珑
此文将为大家介绍 UOS 1070 与 deepin V23 玲珑安装。
备注：此文档适用于 1.5.0, 请使用 ll-cli --version 检查您的玲珑程序版本。
玲珑由三部分组成：
- ll-builder 用来构建和调试玲珑应用，由 linglong-builder 提供；
ll-box 沙箱容器，由 linglong-box 提供；
ll-cli 管理和运行玲珑应用，由 linglong-bin 提供。
1、UOS 1070
目前支持 amd64、arm64、loongarch64（龙芯旧世界）架构。
1）添加玲珑仓库源
echo "deb [trusted=yes] https://ci.deepin.com/repo/deepin/deepin-community/linglong-repo/ unstable main" | sudo tee -a /etc/apt/sources.list
2）安装玲珑构建工具包
sudo apt update
sudo apt install linglong-builder linglong-box linglong-bin
2、deepin V23
目前支持 amd64、arm64 架构。
sudo apt install linglong-builder linglong-box linglong-bin
安装 pica 工具
本工具目前提供 deb 包转换为玲珑包的能力，生成构建玲珑应用需要的 linglong.yaml 文件，并依赖 ll-builder 来实现应用构建和导出。
1、UOS 1070
目前支持 amd64、arm64 架构。
根据玲珑安装步骤，添加玲珑仓库源
sudo apt install linglong-pica
2、deepin V23
目前支持 amd64、arm64 架构。
sudo apt install linglong-pica
邀您体验 10 分钟快速构建
访问玲珑官网（https://linglong.dev/）获取10分钟快速构建指南。
1、从零构建示例
以 deepin-calculator 作为从源码构建玲珑应用的例子。玲珑应用的 appid 需要使用倒置域名的方式命名。
1）创建
mkdir org.deepin.calculator
目录下创建 linglong.yaml 文件
touch org.deepin.calculator/linglong.yaml
进入目录
cd org.deepin.calculator
使用文本编辑器编辑 linglong.yaml
![]()
linglong.yaml 文件遵循 yaml 语法规范。
2）构建
ll-builder build
等待玲珑应用构建完成。
3）运行玲珑应用
ll-builder run
ll-builder run 运行成功输出如下：
![]()
为了便于调试，可以使用额外的 --exec /bin/bash 参数，替换进入容器后默认执行的程序，如：
ll-builder run --exec /bin/bash
2、转换 deb 应用
以百度网盘为例，介绍将 deb 包转为玲珑包的过程。目前只支持转换遵循应用商店打包规范的软件。
1）获取 deb 包文件
apt download com.baidu.baidunetdisk
2）转换应用
ll-pica convert -c com.baidu.baidunetdisk_4.17.7_amd64.deb -w work -b
进入目录
cd work/package/com.baidu.baidunetdisk/amd64
3）安装 layer 文件
ll-cli install ./com.baidu.baidunetdisk_4.17.7.0_x86_64_runtime.layer
4）运行应用
ll-cli run com.baidu.baidunetdisk
![]()
常见问题
1、常见构建问题
1）cmake 类型构建，出现 -lxxx 失败，但 ldconfig 与 pkg-config 均能查询到该库信息。
链接库路径不在常规路径，新路径为 /runtime/lib。
添加环境变量 LIBRARY_PATH=<libpath>，目前构建环境已默认包含该环境变量。
2）构建时 link 静态库失败，要求重新使用 fPIC 构建。
构建静态库时使用 -fPIC 参数。
3）构建时启动 box 失败，如下图：
![]()
内核不支持 unprivilege namespace，开启 unprivilege namespace 解决。
sudo sysctl -w kernel.unprivileged_userns_clone=1
4）qtbase 构建成功，但无法构建 qt 应用，提示 module,mkspec 相关错误。
低版本 fuse-overlay mount 存在问题，导致 qtbase commit 时文件内容被污染 ，无法正常使用。使用 fuse-overlayfs >= 1.7 版本。
2、常见运行问题
1）应用运行读取 /usr/share 下应用安装资源文件，为什么读取失败？
玲珑应用是在容器环境中运行，应用数据会挂载到 /opt/apps/<appid>/下。/usr/share 目录只会存在系统数据，不会存在应用相关数据。因此直接读取 /usr/share 会失败。
建议：采用 XDG_DATA_DIRS 环境变量读取资源，/opt/apps/<appid>/files/share 会存在此环境变量搜索路径中。
2）应用运行时找不到字体库文件？为什么 deb 包安装时能读取到对应的字体库？
deb 包安装时，会依赖带入对应的字体库文件。而玲珑包格式采用自给自足打包格式。
除了基本的系统库、runtime 里面提供的 Qt 库与 DTK 库文件不用自己提供，其他依赖数据文件，均需自己提供。
建议：对应的数据文件放入 files/share，采用环境变量 XDG_DATA_DIRS 读取路径。
3）玲珑应用 runtime 里面有什么？能不能往里面添加一些库文件进去？
目前玲珑应用依赖的 runtime 里面提供的是 Qt 库与 DTK 库。因 runtime 有严格的大小限制，目前不允许往 runtime 里面添加额外的库文件。
4）应用在容器内运行，运行过程中是否能往容器任意路径下创建配置文件？
可以在 XDG_CONFIG_HOME 下创建配置文件。
5）应用数据保存到哪里？在容器外哪里能找到？
因玲珑应用遵循互不干涉的原则。
XDG_DATA_HOME、
XDG_CONFIG_HOME、
XDG_CACHE_HOME
环境变量被定义到宿主机 ~/.linglong/<appid>/ 对应的路径下，因此用户应用数据会保存在此路径下。应用运行过程中写入数据，也应该读取对应的环境变量写入数据。禁止读写其它应用的配置。
6）应用提供了 dbus service 文件，如何放置？Exec 段写什么？
应用提供 dbus service 文件时，需要放到 entries/dbus-1/services 目录下。如果 Exec 执行玲珑包内二进制，使用 --exec 选项参数执行对应的二进制。
7）应用安装后，启动器无法找到？
TryExec=xxx, 当 xxx 在 $PATH 路径中不存在时，会认为该应用不存在不予显示。
8）为什么图标显示为小黑点？
desktop 写了 Icon 字段，Icon 字段名称不对或者使用绝对路径。
9）为什么图标显示为齿轮？
desktop 未提供 Icon 字段。
10）图标存放在哪个路径？
svg →$PREFIX/share/icons/hicolor/scalable/apps/
其他格式按分辨率存放，如16X16
png/xpm → $PREFIX/share/icons/hicolor/16X16/apps/
11）应用自带的 xdg-open、xdg-email 为什么失效？
runtime 中玲珑特殊处理了 xdg-open、xdg-email，因此应用禁止执行自己携带的 xdg-open、xdg-email 可执行文件或者脚本。
12）应用使用系统环境变量未生效，为什么？
当使用环境变量时，需要确认容器内是否存在对应的环境变量。如果没有，需要联系玲珑团队处理。
13）应用运行需要的库文件没找到，如何提供？
应用需要使用的资源文件，与库文件需要应用自身提供。库文件放到 $PREFIX/lib 路径下。
14）应用运行时，为什么 Qt WebEngine 渲染进程崩溃？
因系统升级了 glibc，导致应用使用内置浏览器时失败，需要应用重新适配。
临时解决方案是设置环境变量：
export QTWEBENGINE_DISABLE_SANDBOX=1。
15）应用运行时，找不到 libqxcb.so 库或者 qtwebengine 报错？
存在 qt.conf 文件时，在文件中配置正确路径，或者使用
QTWEBENGINEPROCESS_PATH、
QTWEBENGINE_RESOURCES_PATH、
QT_QPA_PLATFORM_PLUGIN_PATH、
QT_PLUGIN_PATH 环境变量配置搜索路径。
16）应用能否自己携带数据库文件，并在运行中往数据库中写入数据？
容器内文件系统是只读文件系统，不允许往应用资源文件中写入数据。
17）为什么执行携带 suid、guid 权限二进制失效？
玲珑容器为保证系统安全，容器内禁止执行此类权限二进制。
18）uab 离线包格式在 Debian、Ubuntu 下输入法无法使用？
建议安装 fictx 输入法后体验。
19）怎么知道容器环境中安装了哪些包？
ll-builder run --exec bash 进入容器环境，使用 cat /var/lib/dpkg/status | grep "^Package: " 命令查看预装的软件包，另外源码编译的库可以使用 cat /runtime/packages.list 查看。
附录：
