Linglong

As a new type of independent package management toolkit, Linglong primarily provides a layered and isolated operating environment, addressing compatibility issues caused by strong dependencies in traditional package management systems, as well as security issues resulting from lax permissions. Currently, Linglong supports four distributions, including deepin, UnionTech UOS, Debian, and Ubuntu. Linglong's isolation technology can completely decouple applications from the system, thereby thoroughly resolving compatibility conflicts between the system and applications, and among applications themselves, caused by upgrades and adaptation. For developers, this can effectively reduce development costs; for customers, it can reduce enterprise operational costs; and for the entire industry, it will help the industry to develop steadily.

 

Install Linglong

This article will introduce the installation of Linglong on UOS 1070 and deepin V23.

Note: This document is applicable to version 1.5.0, please use  "ll-cli -- version"  to check your Linglong program version.

Linglong consists of three parts:

• ll-builder is used for building and debugging Linglong applications, provided by linglong-builder;
• ll-box is a sandbox container, provided by linglong-box;
• ll-cli is for managing and running Linglong applications, provided by linglong-bin.

 

1、UOS 1070

Currently supports amd64, arm64, and loongarch64 (Loongson old world) architectures.

1)  Add Linglong repository source

echo "deb [trusted=yes] https://ci.deepin.com/repo/deepin/deepin-community/linglong-repo/ unstable main" | sudo tee -a /etc/apt/sources.list

2) Install the Linglong build toolkit

sudo apt update

sudo apt install linglong-builder linglong-box linglong-bin

 

2、deepin V23

Currently supports amd64 and arm64 architectures.

sudo apt install linglong-builder linglong-box linglong-bin

 

Install the Pica Tool

This tool currently offers the capability to convert deb packages into Linglong packages, generate the linglong.yaml file needed for building Linglong applications, and relies on ll-builder to implement application building and exportation.

1、UOS 1070

Currently supports amd64 and arm64 architectures.

According to the Linglong installation steps, add the Linglong repository source.

sudo apt install linglong-pica

 

2、deepin V23

Currently supports amd64 and arm64 architectures.

sudo apt install linglong-pica

 

10-Minute Quick Build

Visit the Linglong official website to obtain the 10-Minute Quick Build Guide（https://linglong.dev/）.

1、Building an Example from Scratch

Use deepin-calculator as an example to build a Linglong application from source code. The appid for a Linglong application should be named using a reversed domain name notation

1）Create

mkdir org.deepin.calculator

 

Create a "linglong.yaml file"  in the directory

touch org.deepin.calculator/linglong.yaml

 

Enter the directory

cd org.deepin.calculator

 

Edit the linglong.yaml file using a text editor.

linglong.yaml file follows the YAML syntax specifications.

 

2）Build

ll-builder build

Wait for the Linglong application to be built.

 

3）Run the Linglong application

ll-builder run

If the ll-builder run command is successful, the output will be as follows:

 

For easier debugging, you can use the additional  "--exec /bin/bash" parameter to replace the default program that is executed after entering the container, like this:

ll-builder run --exec /bin/bash

 

2、Converting deb Applications

Using Baidu Netdisk as an example, this section introduces the process of converting a deb package into a Linglong package. Currently, only software that adheres to the app store's packaging standards can be converted.

1）Obtain the deb package file

apt download com.baidu.baidunetdisk

 

2）Convert the application

ll-pica convert -c com.baidu.baidunetdisk_4.17.7_amd64.deb -w work -b

Enter the directory

cd work/package/com.baidu.baidunetdisk/amd64

 

3）Install the layer file

ll-cli install ./com.baidu.baidunetdisk_4.17.7.0_x86_64_runtime.layer

 

4）Run the application

ll-cli run com.baidu.baidunetdisk

 

Common Issues

1、Common Build Issues

1)  For cmake-based builds, if you encounter a failure with -lxxxxx but can find the library information with both ldconfig and pkg-config.

The library path is not in the standard path, and the new path is /runtime/lib.

Add the environment variable LIBRARY_PATH=<libpath>. The current build environment already includes this environment variable by default.

 

2）Failure to link static libraries during build, requiring a rebuild with fPIC.

Use the -fPIC parameter when building static libraries.

 

3）Failure to start the box during build, as shown in the figure below:

The kernel does not support unprivileged namespaces, solve this by enabling unprivileged namespaces.

sudo sysctl -w kernel.unprivileged_userns_clone=1

 

There is an issue with the lower version of the fuse-overlay mount, which leads to file content corruption when qtbase is committed, making it unusable. Use a version of fuse-overlayfs that is >= 1.7.

 

2、Common Runtime Issues

1）Why does the application fail to read the installation resource files under /usr/share when running?

Linglong applications run in a container environment, and application data is mounted under /opt/apps/<appid>/. The /usr/share directory will only contain system data and will not contain application-related data. Therefore, reading directly from /usr/share will fail.

Suggestion: Use the XDG_DATA_DIRS environment variable to read resources. The path /opt/apps/<appid>/files/share will be included in the search path of this environment variable.

 

2）Why can't the application find the font library files when running? Why could they be read when the deb package was installed?

When a deb package is installed, it brings along the corresponding font library files as dependencies. In contrast, the Linglong package format uses a self-contained packaging format.

Apart from the basic system libraries and the Qt and DTK library files provided in the runtime, all other dependent data files must be provided by yourself.

Suggestion: Place the corresponding data files in files/share and use the environment variable XDG_DATA_DIRS to read the paths.

 

3）What is inside the Linglong application runtime? Can I add some library files to it?

The runtime that Linglong applications currently depend on provides Qt libraries and DTK libraries. Due to strict size limitations on the runtime, it is not currently allowed to add additional library files to the runtime.

 

4）Can configuration files be created at any path within the container during the application's runtime?

Configuration files can be created under XDG_CONFIG_HOME.

 

5) Where is the application data saved? Where can it be found outside the container?

Because Linglong applications follow the principle of non-interference.

The environment variables

• XDG_DATA_HOME,
• XDG_CONFIG_HOME,
• XDG_CACHE_HOME

are defined to point to the corresponding paths on the host machine at "~/.linglong/<appid>/." . Therefore, user application data is saved at this path. During the application's runtime, any data written should be done by reading and writing to the corresponding environment variables. It is forbidden to read from or write to the configurations of other applications.

 

6）How to place the provided D-Bus service file? What should be written in the Exec section?

When an application provides a D-Bus service file, it needs to be placed in the entries/dbus-1/services directory. If the Exec section is to execute a binary within the Linglong package, use the --exec option parameter to execute the corresponding binary.

 

7）After the application is installed, the launcher cannot be found?

If TryExec=xxx is used and xxx is not found in the $PATH, the application will be considered non-existent and will not be displayed.

 

8） Why does the icon appear as a small black dot?

The .desktop file has an Icon field specified, but the name of the icon field is incorrect or an absolute path is used.

 

9）Why does the icon appear as a gear?

The .desktop file does not provide an Icon field.

 

10）Where are the icons stored?

For SVG icons:

svg →$PREFIX/share/icons/hicolor/scalable/apps/

For other formats according to resolution, such as 16x16:

png/xpm → $PREFIX/share/icons/hicolor/16X16/apps/

 

11）Why do the application's own xdg-open and xdg-email fail to work?

In the runtime, Linglong has special handling for xdg-open and xdg-email, so applications are prohibited from executing their own carried xdg-open and xdg-email executables or scripts.

 

12）Why are the system environment variables not effective when used by the application?

When using environment variables, it is necessary to confirm whether the corresponding environment variables exist within the container. If they do not exist, you may need to contact the Linglong team for assistance.

 

13）How to provide missing library files required for application execution?

The application itself needs to provide the resource files and library files it requires. Place the library files in the $PREFIX/lib directory.

 

14）Why does the Qt WebEngine rendering process crash during application runtime?

The system upgrade of glibc has caused the application to fail when using the built-in browser, requiring the application to be re-adapted.

A temporary solution is to set the environment variable:

export QTWEBENGINE_DISABLE_SANDBOX=1。

 

15）Why can't the application find the libqxcb.so library or why does qtwebengine report an error?

If a qt.conf file exists, configure the correct path in the file, or use the following environment variables to configure the search paths:

QTWEBENGINEPROCESS_PATH
QTWEBENGINE_RESOURCES_PATH
QT_QPA_PLATFORM_PLUGIN_PATH
QT_PLUGIN_PATH

 

16）Can the application carry its own database files and write data to the database during runtime?

The file system within the container is a read-only file system, and writing data to the application resource files is not allowed.

 

17) Why does the execution of binaries with SUID or GUID permissions fail?

To ensure system security, Linglong containers prohibit the execution of binaries with such permissions.

 

18) Why can't the input method in the uab offline package format be used on Debian or Ubuntu?

It is recommended to install the fictx input method and then try it out.

 

19)  How do you know which packages are installed in the container environment?

Use ll-builder run --exec bash to enter the container environment, then use the command cat /var/lib/dpkg/status | grep "^Package: " to view the pre-installed software packages. Additionally, for libraries compiled from source, you can use cat /runtime/packages.list to view them.

 

Scan the QR code below to join the Linglong community on WeChat: