(1)Basic Knowledge of Linyaps Application Packaging

Before formally starting a Linyaps application packaging project, it is essential to understand the foundational concepts of Linyaps application packaging. This knowledge will help determine what materials to prepare and what types of operations to perform.

Basic Steps for Linyaps Application Packaging

To begin a Linyaps application packaging project, it is crucial to understand the steps involved in transforming input resources (source code, binary files, etc.) into an installable package. These steps will clarify the necessary preparations:

1. Obtain source files (open-source project code, application binaries, etc.)
2. Determine packaging type based on the source files and select an appropriate packaging strategy.
3. Prepare a compliant Linyaps build environment.
4. Customize the build configuration file linglong.yaml according to the packaging type and source code.
5. Prepare generic resources such as icons and other non-binary assets.

Required Materials for Linyaps Packaging

Based on the above steps, the following files are essential for a complete Linyaps application packaging process:

1. Build configuration file: linglong.yaml
2. Application source code or pre-compiled binaries.
3. Non-binary generic resources (icons, metadata, etc.).

Mainstream Standards Followed by Linyaps Applications

To ensure functionality and user experience, Linyaps adheres to established standards for Linux desktop software packaging. These standards ensure compatibility and ecosystem sustainability.

Linyaps complies with the following mainstream standards:

1. Freedesktop XDG Specifications
2. Linyaps Application Directory Structure Standards
3. Linyaps Build Configuration File (linglong.yaml) Specifications

Freedesktop XDG Specifications

1. Graphical applications must include icon files and .desktop files compliant with Freedesktop XDG standards.
2. Icons must be categorized under $PREFIX/share/icons/hicolor/ with appropriate resolutions.
3. Environment variables like XDG_DATA_DIRS are used within the Linyaps container to read/write host user directories.

Linyaps Directory Structure Standards

1. $PREFIX Rule: All application files must reside under the $PREFIX directory, which includes subdirectories like bin and share.
2. Isolation: Applications in Linyaps containers cannot access host system binaries or libraries.
3. Build Directory Mapping: The project directory is mapped to /project inside the container.
4. Runtime Paths:
   • Foundation Runtime: System paths like /usr/bin, /usr/include are mapped as the base environment.
   • Custom Runtime: Paths like /runtime/usr/bin, /runtime/usr/include are used for runtime-specific dependencies.

Example of environment variable handling:

PATH=/bin:/usr/bin:/runtime/bin:$PREFIX/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games:/sbin:/usr/sbin  

Standards for Generic Resources in Linyaps Packaging

Icon Directory Standards

According to the Freedesktop XDG Specifications and Linyaps Application Directory Structure Standards, icons must be placed in corresponding directories based on their dimensions.

Standard non-vector icon sizes: 16x16, 24x24, 32x32, 48x48, 128x128, 256x256, 512x512 To ensure optimal user experience, at least one non-vector icon with a size of 128x128 or larger is required. This restriction does not apply to vector icons.

Thus, the icon directory structure for a Linyaps application should follow this example:

$PREFIX/share/icons/hicolor/16x16/apps  
$PREFIX/share/icons/hicolor/24x24/apps  
$PREFIX/share/icons/hicolor/32x32/apps  
$PREFIX/share/icons/hicolor/48x48/apps  
$PREFIX/share/icons/hicolor/128x128/apps  
$PREFIX/share/icons/hicolor/256x256/apps  
$PREFIX/share/icons/hicolor/512x512/apps  
$PREFIX/share/icons/hicolor/scalable/apps  

* The scalable directory is used for vector icons, typically in .svg format.

If your Linyaps application provides both a 128x128 non-vector icon linyaps-app-demo.png and a 128x128 vector icon linyaps-app-demo.svg, the container should exhibit the following structure:

$PREFIX/share/icons/hicolor/128x128/apps/linyaps-app-demo.png  
$PREFIX/share/icons/hicolor/scalable/apps/linyaps-app-demo.svg  

* To avoid icon conflicts or overrides, use the application’s unique English name or Linyaps ID for icon filenames.

Desktop File Standards

Linyaps supports .desktop files compliant with Freedesktop XDG standards. Key fields:

Field	Requirement
Exec	Must match the command value in linglong.yaml.
Icon	Must match the icon filename (without extension) in the icons directory.

Example .desktop File:

org.qbittorrent.qBittorrent.desktop
[Desktop Entry]
Categories=Network;FileTransfer;P2P;Qt;
Exec=/opt/apps/org.qbittorrent.qBittorrent/files/bin/qbittorrent %U
Comment=Download and share files over BitTorrent
Icon=qbittorrent
MimeType=application/x-bittorrent;x-scheme-handler/magnet;
Name=qBittorrent
Type=Application
StartupWMClass=qbittorrent
Keywords=bittorrent;torrent;magnet;download;p2p;
​
StartupNotify=true
Terminal=false

Linyaps Application Packaging linglong.yaml Specifications

Like other traditional packaging systems, manually creating a Linyaps application packaging project requires configuring the build rule file linglong.yaml. The fields in this file are categorized into Global Fields and Custom Fields based on their purposes. * All spaces and placeholders in the linglong.yaml examples are functional characters. Do not delete or alter their formatting.

Global Fields Specifications

Global Fields in linglong.yaml are unaffected by build types and must adhere to the following rules:

A valid linglong.yaml must include the following key sections:

Section	Description
version	Build configuration version.
package	Basic application metadata.
base	Base container environment and version (includes foundational libraries).
runtime	Custom runtime and version (optional; omit if base meets requirements).
command	Command executed at container startup (matches .desktop Exec field).
sources	Source file types for packaging.
build	Build instructions.

The package section contains the following subfields:

Subfield	Description
id	Unique application ID/package name.
name	Application name (in English).
version	Application version.
kind	Application type (default: app).
description	Brief application description.

$PREFIX Path Rule: All application files must be installed under the $PREFIX directory. * $PREFIX is an auto-generated variable. Do not replace it with absolute paths or literal values.

Version Format: Linyaps requires four-digit version numbers (e.g., 23.0.0.29). Builds will fail if this format is violated.

Automatic Version Matching: For base and runtime, you may specify only the first three digits (e.g., 23.0.0). The highest available patch version will be selected automatically. Example: If org.deepin.foundation provides 23.0.0.28 and 23.0.0.29, and linglong.yaml specifies:

base: org.deepin.foundation/23.0.0  

The build will default to 23.0.0.29.

Compatibility: The linglong.yaml format is not directly compatible with other packaging tools. Refer to configuration examples for adaptation.

Custom Fields

Linyaps packaging projects are categorized into local file operations and git source compilation based on source types. The sources field supports git, local, file, and archive. Full documentation: Build Configuration Introduction

Git Source Compilation Mode

For projects requiring Git repository cloning, configure sources as git:

1. sources Example:

sources:
  - kind: git
    url: https://githubfast.com/qbittorrent/qBittorrent.git
    version: release-4.6.7
    commit: 839bc696d066aca34ebd994ee1673c4b2d5afd7b
​
  - kind: git
    url: https://githubfast.com/arvidn/libtorrent.git
    version: v2.0.9
    commit: 4b4003d0fdc09a257a0841ad965b22533ed87a0d

Name	Description
kind	Source file type
url	Repository address for git fetch. Use mirror if network is poor.
version	Repository version, i.e., or .
commit	Fetch source code based on repository history. Enter the commit value to apply all changes up to that commit. *This field has higher priority than . Do not enter any after the merge time of .
	* Supports adding multiple git repositories as

build Example:

build: |  
  mkdir -p ${PREFIX}/bin/ ${PREFIX}/share/  
  ## Apply patch for qBittorrent  
  cd /project/linglong/sources/qBittorrent.git  
  git apply -v /project/patches/linyaps-qBittorrent-4.6.7-szbt2.patch  

This section defines build rules. Source files are stored in /project/linglong/sources, with repositories named as xxx.git. * Use git patch for efficient source code modifications.

Local File Operation Mode

For projects operating on local files, set kind to local:

sources Example:

sources:  
  - kind: local  
    name: "qBittorrent"  

Field	Description
kind	Source type (local).
name	Identifier (no functional impact).
* No source file operations will occur in this mode.

build Example:

build: |  
  ## Build main  
  mkdir /project/src/qBittorrent-release-4.6.7-szbt2/build  
  cd /project/src/qBittorrent-release-4.6.7-szbt2/build  
  cmake -DCMAKE_BUILD_TYPE=Release \  
        -DCMAKE_INSTALL_PREFIX=$PREFIX ..  
  make -j$(nproc)  
  make install  

This section defines manual build steps. Ensure all commands are executable; otherwise, the build will fail.

Manual Container Operation Mode

For manual operations inside the container, follow the Local File Operation Mode configuration:

1. Use the same sources format as local mode.
2. Omit detailed build rules. The linglong.yaml will generate a container environment instead of executing tasks. Refer to advanced tutorials for containerized workflows.