Merge cb5d3d31fa into dd641d0b94

更新 文档25.2.1 的运行时版本

.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: None
+#
+# SPDX-License-Identifier: CC0-1.0
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-xml
+
+  - repo: https://github.com/pre-commit/mirrors-clang-format
+    rev: v21.1.5
+    hooks:
+      - id: clang-format
+        name: clang-format (C/C++)
+        files: \.(c|cc|cpp|cxx|h|hpp)$
+        args: ['-i', '--sort-includes', '--style=file']
+        exclude: |
+          (?x)^(
+            build/|
+            external/|
+            libs/api/src/linglong/api/types/v1/
+          )
+
+  - repo: https://github.com/scop/pre-commit-shfmt
+    rev: v3.12.0-2
+    hooks:
+      - id: shfmt
+        args: ['-i', '4', '-ci', '-sr']

.tx/transifex.yaml

@@ -7,5 +7,10 @@ filters:
     file_format: PO
     source_language: en_US
     translation_files_expression: po/<lang>.po
+  - filter_type: file
+    source_file: misc/share/polkit-1/translations/policy.ts
+    file_format: QT
+    source_language: en_US
+    translation_files_expression: misc/share/polkit-1/translations/policy_<lang>.ts
 settings:
   pr_branch_name: transifex_update_<br_unique_id>

README.md

@@ -146,74 +146,113 @@ For assistance, use the following channels:
 
 ### Command-line Tools
 
-- [Introduction](./docs/pages/en/guide/ll-cli/introduction.md)
-- [Install](./docs/pages/en/guide/ll-cli/install.md)
-- [Run](./docs/pages/en/guide/ll-cli/run.md)
-- [Uninstall](./docs/pages/en/guide/ll-cli/uninstall.md)
-- [Upgrade](./docs/pages/en/guide/ll-cli/update.md)
-- [List](./docs/pages/en/guide/ll-cli/list.md)
-- [Prune](./docs/pages/en/guide/ll-cli/prune.md)
-- [Exec](./docs/pages/en/guide/ll-cli/exec.md)
-- [Content](./docs/pages/en/guide/ll-cli/content.md)
-- [Info](./docs/pages/en/guide/ll-cli/info.md)
-- [PS](./docs/pages/en/guide/ll-cli/ps.md)
-- [Kill](./docs/pages/en/guide/ll-cli/kill.md)
-- [Search](./docs/pages/en/guide/ll-cli/query.md)
+- [Introduction](./docs/pages/en/guide/reference/commands/ll-cli/ll-cli.md)
+- [Install](./docs/pages/en/guide/reference/commands/ll-cli/install.md)
+- [Run](./docs/pages/en/guide/reference/commands/ll-cli/run.md)
+- [Uninstall](./docs/pages/en/guide/reference/commands/ll-cli/uninstall.md)
+- [Upgrade](./docs/pages/en/guide/reference/commands/ll-cli/upgrade.md)
+- [List](./docs/pages/en/guide/reference/commands/ll-cli/list.md)
+- [Prune](./docs/pages/en/guide/reference/commands/ll-cli/prune.md)
+- [Enter](./docs/pages/en/guide/reference/commands/ll-cli/enter.md)
+- [Content](./docs/pages/en/guide/reference/commands/ll-cli/content.md)
+- [Info](./docs/pages/en/guide/reference/commands/ll-cli/info.md)
+- [PS](./docs/pages/en/guide/reference/commands/ll-cli/ps.md)
+- [Kill](./docs/pages/en/guide/reference/commands/ll-cli/kill.md)
+- [Search](./docs/pages/en/guide/reference/commands/ll-cli/search.md)
 
 ### Build Tools
 
-- [Introduction](./docs/pages/en/guide/ll-builder/introduction.md)
-- [Demo](./docs/pages/en/guide/ll-builder/demo.md)
-- [Create](./docs/pages/en/guide/ll-builder/create.md)
-- [Run](./docs/pages/en/guide/ll-builder/run.md)
-- [Push](./docs/pages/en/guide/ll-builder/push.md)
-- [Export](./docs/pages/en/guide/ll-builder/export.md)
+- [Introduction](./docs/pages/en/guide/reference/commands/ll-builder/ll-builder.md)
+- [Demo](./docs/pages/en/guide/building/demo.md)
+- [Create](./docs/pages/en/guide/reference/commands/ll-builder/create.md)
+- [Run](./docs/pages/en/guide/reference/commands/ll-builder/run.md)
+- [Push](./docs/pages/en/guide/reference/commands/ll-builder/push.md)
+- [Export](./docs/pages/en/guide/reference/commands/ll-builder/export.md)
+- [Build](./docs/pages/en/guide/reference/commands/ll-builder/build.md)
+- [Extract](./docs/pages/en/guide/reference/commands/ll-builder/extract.md)
+- [Import](./docs/pages/en/guide/reference/commands/ll-builder/import.md)
+- [List](./docs/pages/en/guide/reference/commands/ll-builder/list.md)
+- [Remove](./docs/pages/en/guide/reference/commands/ll-builder/remove.md)
+- [Repository](./docs/pages/en/guide/reference/commands/ll-builder/repo.md)
 
 ### Package Conversion Tools
 
 #### deb Conversion
 
-- [Introduction](./docs/pages/en/guide/ll-pica/introduction.md)
-- [Init](./docs/pages/en/guide/ll-pica/init.md)
-- [Convert](./docs/pages/en/guide/ll-pica/convert.md)
-- [Adep](./docs/pages/en/guide/ll-pica/adep.md)
+- [Introduction](./docs/pages/en/guide/reference/commands/ll-pica/ll-pica.md)
+- [Init](./docs/pages/en/guide/reference/commands/ll-pica/ll-pica-init.md)
+- [Convert](./docs/pages/en/guide/reference/commands/ll-pica/ll-pica-convert.md)
+- [Adep](./docs/pages/en/guide/reference/commands/ll-pica/ll-pica-adep.md)
 
 #### AppImage Conversion
 
-- [Introduction](./docs/pages/en/guide/ll-appimage-convert/introduction.md)
-- [Convert](./docs/pages/en/guide/ll-appimage-convert/convert-appimage.md)
+- [Introduction](./docs/pages/en/guide/reference/commands/ll-appimage-convert/ll-appimage-convert.md)
+- [Convert](./docs/pages/en/guide/reference/commands/ll-appimage-convert/ll-appimage-convert-convert.md)
 
 #### Flatpak Conversion
 
-- [Introduction](./docs/pages/en/guide/ll-flatpak-convert/introduction.md)
-- [Convert](./docs/pages/en/guide/ll-flatpak-convert/convert-flatpak.md)
+- [Introduction](./docs/pages/en/guide/reference/commands/ll-pica-flatpak/ll-pica-flatpak.md)
+- [Convert](./docs/pages/en/guide/reference/commands/ll-pica-flatpak/ll-pica-flatpak-convert.md)
 
 ### Debugging
 
-- [Debug](/docs/pages/en/guide/debug/debug.md)
+- [Debug](./docs/pages/en/guide/debug/debug.md)
 
 ### FAQs
 
-- [Runtime FAQs](/docs/pages/en/guide/debug/faq.md)
-- [Linyaps Builder FAQs](/docs/pages/en/guide/debug/ll-builder-faq.md)
-- [Linyaps Conversion Tool FAQs](/docs/pages/en/guide/debug/ll-pica-faq.md)
+- [Runtime FAQs](./docs/pages/en/guide/tips-and-faq/faq.md)
+- [Linyaps Builder FAQs](./docs/pages/en/guide/tips-and-faq/ll-builder-faq.md)
+- [Linyaps Conversion Tool FAQs](./docs/pages/en/guide/tips-and-faq/ll-pica-faq.md)
 
 ## :book: Learning Resources
 
+### Getting Started
+
+- [Overview](./docs/pages/en/guide/start/whatis.md) - Introduction to Linyaps basic concepts
+- [Installation](./docs/pages/en/guide/start/install.md) - Detailed installation guide
+- [Build Your First App](./docs/pages/en/guide/start/build_your_first_app.md) - Complete tutorial for beginners
+
+### Building and Packaging
+
+- [Package Specification](./docs/pages/en/guide/building/linyaps_package_spec.md) - Detailed packaging standards
+- [Build Configuration](./docs/pages/en/guide/building/manifests.md) - Understanding linglong.yaml
+- [Module Management](./docs/pages/en/guide/building/modules.md) - Module splitting and management
+- [Multi-architecture Support](./docs/pages/en/guide/building/multiarch.md) - Cross-platform building
+- [Demo Examples](./docs/pages/en/guide/building/demo.md) - Practical build demonstrations
+
+### Reference Documentation
+
+- [Basic Concepts](./docs/pages/en/guide/reference/basic-concepts.md) - Core concepts and terminology
+- [Runtime Component](./docs/pages/en/guide/reference/runtime.md) - Runtime system details
+- [Driver Documentation](./docs/pages/en/guide/reference/driver.md) - Driver-related information
+
+### Advanced Topics
+
+- [Desktop Integration](./docs/pages/en/guide/desktop-integration/README.md) - Desktop environment integration
+- [Unit Testing](./docs/pages/en/guide/extra/unit-testing.md) - Testing frameworks and practices
+- [Bundle Format](./docs/pages/en/guide/extra/bundle-format.md) - Package format specifications
+- [System Helper](./docs/pages/en/guide/extra/system-helper.md) - System utility documentation
+- [Application Configuration](./docs/pages/en/guide/extra/app-conf.md) - App configuration guide
+- [Root Filesystem](./docs/pages/en/guide/extra/rootfs.md) - Root filesystem management
+- [UAB Build](./docs/pages/en/guide/extra/uab-build.md) - UAB format building
+- [Repository Management](./docs/pages/en/guide/publishing/repositories.md) - Repository operations
+- [UAB Publishing](./docs/pages/en/guide/publishing/uab.md) - UAB format publishing
+- [Mirror Sites](./docs/pages/en/guide/publishing/mirrors.md) - Mirror configuration
+
+### Tutorial Series
+
+- [Linyaps Packaging Basics](./docs/pages/en/guide/lessons/basic-notes.md)
+- [Manual Compilation in Container](./docs/pages/en/guide/lessons/build-in-env.md)
+- [Offline Source Compilation](./docs/pages/en/guide/lessons/build-offline-src.md)
+- [Compilation with Git & Patch](./docs/pages/en/guide/lessons/build-git-patch.md)
+- [Automated Testing Suite](./docs/pages/en/guide/lessons/test-with-toolchains.md)
+
 ### Related Projects
 
 - [OSTree](https://github.com/ostreedev/ostree)
 - [Linyaps Packaging Tool - ll-killer-go](https://github.com/System233/ll-killer-go)
 - [Linyaps Web Store](https://github.com/yoloke/Linglong-Shop)
 
-### Tutorial Series
-
-- [Linyaps Packaging Basics](/docs/pages/guide/lessons/basic-notes.md)
-- [Manual Compilation in Container](/docs/pages/guide/lessons/build-in-env.md)
-- [Offline Source Compilation](/docs/pages/guide/lessons/build-offline-src.md)
-- [Compilation with Git & Patch](/docs/pages/guide/lessons/build-git-patch.md)
-- [Automated Testing Suite](/docs/pages/guide/lessons/test-with-toolchains.md)
-
 Explore more tutorials at [Linyaps Official Website](https://linyaps.org.cn/learn).
 
 ## :hammer_and_pick: Contribution

README.zh_CN.md

@@ -148,74 +148,113 @@ ll-cli run cn.org.linyaps.demo
 
 ### 命令行工具
 
-- [introduction](./docs/pages/en/guide/ll-cli/introduction.md)
-- [install](./docs/pages/en/guide/ll-cli/install.md)
-- [run](./docs/pages/en/guide/ll-cli/run.md)
-- [uninstall](./docs/pages/en/guide/ll-cli/uninstall.md)
-- [upgrade](./docs/pages/en/guide/ll-cli/update.md)
-- [list](./docs/pages/en/guide/ll-cli/list.md)
-- [prune](./docs/pages/en/guide/ll-cli/prune.md)
-- [exec](./docs/pages/en/guide/ll-cli/exec.md)
-- [content](./docs/pages/en/guide/ll-cli/content.md)
-- [info](./docs/pages/en/guide/ll-cli/info.md)
-- [ps](./docs/pages/en/guide/ll-cli/ps.md)
-- [kill](./docs/pages/en/guide/ll-cli/kill.md)
-- [search](./docs/pages/en/guide/ll-cli/query.md)
+- [介绍](./docs/pages/guide/reference/commands/ll-cli/ll-cli.md)
+- [安装](./docs/pages/guide/reference/commands/ll-cli/install.md)
+- [运行](./docs/pages/guide/reference/commands/ll-cli/run.md)
+- [卸载](./docs/pages/guide/reference/commands/ll-cli/uninstall.md)
+- [升级](./docs/pages/guide/reference/commands/ll-cli/upgrade.md)
+- [列表](./docs/pages/guide/reference/commands/ll-cli/list.md)
+- [清理](./docs/pages/guide/reference/commands/ll-cli/prune.md)
+- [进入](./docs/pages/guide/reference/commands/ll-cli/enter.md)
+- [内容](./docs/pages/guide/reference/commands/ll-cli/content.md)
+- [信息](./docs/pages/guide/reference/commands/ll-cli/info.md)
+- [进程](./docs/pages/guide/reference/commands/ll-cli/ps.md)
+- [终止](./docs/pages/guide/reference/commands/ll-cli/kill.md)
+- [搜索](./docs/pages/guide/reference/commands/ll-cli/search.md)
 
 ### 构建工具
 
-- [introduction](./docs/pages/en/guide/ll-builder/introduction.md)
-- [demo](./docs/pages/en/guide/ll-builder/demo.md)
-- [create](./docs/pages/en/guide/ll-builder/create.md)
-- [run](./docs/pages/en/guide/ll-builder/run.md)
-- [push](./docs/pages/en/guide/ll-builder/push.md)
-- [export](./docs/pages/en/guide/ll-builder/export.md)
+- [介绍](./docs/pages/guide/reference/commands/ll-builder/ll-builder.md)
+- [演示](./docs/pages/guide/building/demo.md)
+- [创建](./docs/pages/guide/reference/commands/ll-builder/create.md)
+- [运行](./docs/pages/guide/reference/commands/ll-builder/run.md)
+- [推送](./docs/pages/guide/reference/commands/ll-builder/push.md)
+- [导出](./docs/pages/guide/reference/commands/ll-builder/export.md)
+- [构建](./docs/pages/guide/reference/commands/ll-builder/build.md)
+- [提取](./docs/pages/guide/reference/commands/ll-builder/extract.md)
+- [导入](./docs/pages/guide/reference/commands/ll-builder/import.md)
+- [列表](./docs/pages/guide/reference/commands/ll-builder/list.md)
+- [删除](./docs/pages/guide/reference/commands/ll-builder/remove.md)
+- [仓库](./docs/pages/guide/reference/commands/ll-builder/repo.md)
 
 ### 包转换工具
 
 #### deb 包转换
 
-- [introduction](./docs/pages/en/guide/ll-pica/introduction.md)
-- [init](./docs/pages/en/guide/ll-pica/init.md)
-- [convert](./docs/pages/en/guide/ll-pica/convert.md)
-- [adep](./docs/pages/en/guide/ll-pica/adep.md)
+- [介绍](./docs/pages/guide/reference/commands/ll-pica/ll-pica.md)
+- [初始化](./docs/pages/guide/reference/commands/ll-pica/ll-pica-init.md)
+- [转换](./docs/pages/guide/reference/commands/ll-pica/ll-pica-convert.md)
+- [依赖](./docs/pages/guide/reference/commands/ll-pica/ll-pica-adep.md)
 
 #### AppImage 包转换
 
-- [introduction](./docs/pages/en/guide/ll-appimage-convert/introduction.md)
-- [convert](./docs/pages/en/guide/ll-appimage-convert/convert-appimage.md)
+- [介绍](./docs/pages/guide/reference/commands/ll-appimage-convert/ll-appimage-convert.md)
+- [转换](./docs/pages/guide/reference/commands/ll-appimage-convert/ll-appimage-convert-convert.md)
 
 #### Flatpak 包转换
 
-- [introduction](./docs/pages/en/guide/ll-flatpak-convert/introduction.md)
-- [convert](./docs/pages/en/guide/ll-flatpak-convert/convert-flatpak.md)
+- [介绍](./docs/pages/guide/reference/commands/ll-pica-flatpak/ll-pica-flatpak.md)
+- [转换](./docs/pages/guide/reference/commands/ll-pica-flatpak/ll-pica-flatpak-convert.md)
 
 ### 调试
 
-- [debug](/docs/pages/en/guide/debug/debug.md)
+- [调试指南](./docs/pages/guide/debug/debug.md)
 
 ### 常见问题
 
-- [运行相关常见问题](/docs/pages/en/guide/debug/faq.md)
-- [如意玲珑构建工具常见问题](/docs/pages/en/guide/debug/ll-builder-faq.md)
-- [如意玲珑转换工具常见问题](/docs/pages/en/guide/debug/ll-pica-faq.md)
+- [运行相关常见问题](./docs/pages/guide/tips-and-faq/faq.md)
+- [如意玲珑构建工具常见问题](./docs/pages/guide/tips-and-faq/ll-builder-faq.md)
+- [如意玲珑转换工具常见问题](./docs/pages/guide/tips-and-faq/ll-pica-faq.md)
 
 ## :book: 学习和参考
 
+### 入门指南
+
+- [概述](./docs/pages/guide/start/whatis.md) - 如意玲珑基本概念介绍
+- [安装指南](./docs/pages/guide/start/install.md) - 详细安装说明
+- [构建第一个应用](./docs/pages/guide/start/build_your_first_app.md) - 初学者完整教程
+
+### 构建和打包
+
+- [包规范](./docs/pages/guide/building/linyaps_package_spec.md) - 详细打包标准
+- [构建配置](./docs/pages/guide/building/manifests.md) - 理解 linglong.yaml
+- [模块管理](./docs/pages/guide/building/modules.md) - 模块拆分和管理
+- [多架构支持](./docs/pages/guide/building/multiarch.md) - 多架构构建
+- [演示示例](./docs/pages/guide/building/demo.md) - 实际构建演示
+
+### 参考文档
+
+- [基本概念](./docs/pages/guide/reference/basic-concepts.md) - 核心概念和术语
+- [运行时组件](./docs/pages/guide/reference/runtime.md) - 运行时系统详情
+- [驱动文档](./docs/pages/guide/reference/driver.md) - 驱动相关信息
+
+### 高级主题
+
+- [桌面集成](./docs/pages/guide/desktop-integration/README.md) - 桌面环境集成
+- [单元测试](./docs/pages/guide/extra/unit-testing.md) - 测试框架和实践
+- [包格式](./docs/pages/guide/extra/bundle-format.md) - 包格式规范
+- [系统助手](./docs/pages/guide/extra/system-helper.md) - 系统工具文档
+- [应用配置](./docs/pages/guide/extra/app-conf.md) - 应用配置指南
+- [根文件系统](./docs/pages/guide/extra/rootfs.md) - 根文件系统管理
+- [UAB 构建](./docs/pages/guide/extra/uab-build.md) - UAB 格式构建
+- [仓库管理](./docs/pages/guide/publishing/repositories.md) - 仓库操作
+- [UAB 发布](./docs/pages/guide/publishing/uab.md) - UAB 格式发布
+- [镜像站点](./docs/pages/guide/publishing/mirrors.md) - 镜像配置
+
+### 系列教程
+
+- [玲珑应用构建工程基础知识](./docs/pages/guide/lessons/basic-notes.md)
+- [容器内手动编译应用](./docs/pages/guide/lessons/build-in-env.md)
+- [本地源码手动编译应用](./docs/pages/guide/lessons/build-offline-src.md)
+- [使用 git&patch 编译应用](./docs/pages/guide/lessons/build-git-patch.md)
+- [玲珑应用自动化测试套件](./docs/pages/guide/lessons/test-with-toolchains.md)
+
 ### 相关项目
 
 - [OStree](https://github.com/ostreedev/ostree)
 - [如意玲珑打包工具 - ll-killer-go](https://github.com/System233/ll-killer-go)
 - [如意玲珑网页商店](https://github.com/yoloke/Linglong-Shop)
 
-### 系列教程
-
-- [玲珑应用构建工程基础知识](/docs/pages/guide/lessons/basic-notes.md)
-- [容器内手动编译应用](/docs/pages/guide/lessons/build-in-env.md)
-- [本地源码手动编译应用](/docs/pages/guide/lessons/build-offline-src.md)
-- [使用 git&patch 编译应用](/docs/pages/guide/lessons/build-git-patch.md)
-- [玲珑应用自动化测试套件](/docs/pages/guide/lessons/test-with-toolchains.md)
-
 更多课程可参考如意玲珑官网：<https://linyaps.org.cn/learn>
 
 ## :hammer_and_pick: 参与

REUSE.toml

@@ -172,7 +172,7 @@ SPDX-FileCopyrightText = "2018 Xiphos Development Team"
 SPDX-License-Identifier = "GPL-2.0-or-later"
 
 [[annotations]]
-path = ["po/**.po", "po/**.pot", "po/POTFILES.in", "po/LINGUAS"]
+path = ["po/**.po", "po/**.pot", "po/POTFILES.in", "po/LINGUAS", "misc/share/polkit-1/translations/*.ts"]
 precedence = "aggregate"
 SPDX-FileCopyrightText = "UnionTech Software Technology Co., Ltd."
 SPDX-License-Identifier = "LGPL-3.0-only"

api/schema/v1.json

@@ -1025,11 +1025,15 @@
       "type": "object",
       "description": "package manager uninstall parameters",
       "required": [
-        "package"
+        "package",
+        "options"
       ],
       "properties": {
         "package": {
           "$ref": "#/$defs/PackageManager1Package"
+        },
+        "options": {
+          "$ref": "#/$defs/CommonOptions"
         }
       }
     },

api/schema/v1.yaml

@@ -790,9 +790,12 @@ $defs:
     description: package manager uninstall parameters
     required:
       - package
+      - options
     properties:
       package:
         $ref: '#/$defs/PackageManager1Package'
+      options:
+        $ref: '#/$defs/CommonOptions'
   PackageManager1UpdateParameters:
     type: object
     description: package manager update result

apps/ll-builder/src/main.cpp

@@ -740,7 +740,7 @@ int main(int argc, char **argv)
     Q_INIT_RESOURCE(builder_releases);
     // 初始化应用，builder在非tty环境也输出日志
     linglong::utils::global::applicationInitialize(true);
-    linglong::utils::global::initLinyapsLogSystem(argv[0]);
+    linglong::utils::global::initLinyapsLogSystem(linglong::utils::log::LogBackend::Console);
 
     CLI::App commandParser{ _("linyaps builder CLI \n"
                               "A CLI program to build linyaps application\n") };

apps/ll-cli/src/main.cpp

@@ -326,6 +326,9 @@ void addUninstallCommand(CLI::App &commandParser,
     cliUninstall->add_option("--module", uninstallOptions.module, _("Uninstall a specify module"))
       ->type_name("MODULE")
       ->check(validatorString);
+    cliUninstall->add_flag("--force",
+                           uninstallOptions.forceOpt,
+                           _("Force uninstall base or runtime"));
 
     // below options are used for compatibility with old ll-cli
     const auto &pruneDescription = std::string{ _("Remove all unused modules") };
@@ -930,7 +933,7 @@ int main(int argc, char **argv)
     QCoreApplication app(argc, argv);
     // application initialize
     applicationInitialize();
-    initLinyapsLogSystem(argv[0]);
+    initLinyapsLogSystem(linglong::utils::log::LogBackend::Journal);
 
     // invoke method
     auto ret = QMetaObject::invokeMethod(

apps/ll-package-manager/src/main.cpp

@@ -151,7 +151,7 @@ auto main(int argc, char *argv[]) -> int
     QCoreApplication app(argc, argv);
 
     applicationInitialize();
-    initLinyapsLogSystem(argv[0]);
+    initLinyapsLogSystem(linglong::utils::log::LogBackend::Journal);
 
     auto ociRuntimeCLI = qgetenv("LINGLONG_OCI_RUNTIME");
     if (ociRuntimeCLI.isEmpty()) {

docs/app-conf.md

@@ -1,53 +0,0 @@
-# Application Run Configuration
-
-Application run configuration is the file that the Linglong runtime module uses to load the app.
-
-The configuration is machine-related, and the user can set mount paths and permission control files for the app.
-
-## File Format
-
-Should be a yaml file.
-
-## Storage
-
-The config is highly user related, it should be stored in ~/.linglong/{appid}/app.yaml
-
-If not exist, create it first from info.json.
-
-## Content
-
-```yaml
-# should be 1.0 now
-version: 1.0
-
-package:
-  ref: com.qq.weixin.deepin/3.2.1.154deepin8/x86_64
-
-runtime:
-  ref: org.deepin.Runtime/20/x86_64
-
-  # This section can only be set by developers and only works with debug enabled
-  debug:
-    # Override entrypoint
-    args:
-      - /opt/apps/com.qq.weixin.work.deepin/files/run.sh
-      - --debug
-    # Override the base, carefully set the debug args
-    mount-bottom:
-      - /usr:/usr
-
-permissions:
-  # mount after all runtime container build
-  mounts:
-    - /etc/passwd:/etc/passwd
-    - /etc/group:/etc/group
-    - ${HOME}/Documents:${HOME}/Documents
-    - ${HOME}/Desktop:${HOME}/Desktop
-    - ${HOME}/Downloads:${HOME}/Downloads
-  # TODO: session and system bus
-  dbus:
-    owner:
-      - com.qq.weixin.work.deepin
-    talk:
-      - org.freedesktop.Notifications
-```

docs/bundle-format.md

@@ -1,51 +0,0 @@
-# Bundle Format
-
-## Introduction
-
-Green software refers to binaries that do not install any files to the system.
-
-The basic constraints of green software are:
-
-- Path independence, meaning it has nothing to do with local files
-- High compatibility, so the software should contain all dependencies that the system does not have
-
-The well-known technology for building green software on Linux is AppImage.
-
-However, there are many problems with that technology. The biggest problem is that the host system ABI cannot stay stable and differs from one system to another. Linglong cannot solve that problem either. We should maintain a baseline of supported systems or ABIs.
-
-A trick on UnionTech OS or Deepin is to only support systems after UnionTech OS 1020, which reduces the testing work for different base systems.
-
-## Target
-
-The green bundle is not just simple support for running applications independently. It is also designed to be the offline maintainer package format for office system services that support self-running and installation. Therefore, keep the changeability of the bundle format in mind when designing.
-
-When a user has internet access, we mostly use online differential updates or install from repositories. We do not use bundles if we can access the repository when distributing applications.
-
-## Specification
-
-The specification for the export bundle:
-
-- MUST be an ELF file, which can be FlatELF
-- MUST be statically-linked
-- MUST contain a data segment that can be mounted with FUSE
-- MUST contain a loader executable at the root of the FUSE-mounted filesystem
-
-## Implementation
-
-**The implementation changes over time. If you change the implementation, update this section as soon as possible!**
-
-### Prototype
-
-- The bundle is a sample ELF loader that joins a read-only filesystem with cat
-- The loader simply calls read_elf64 to calculate the offset of the read-only filesystem
-- The loader mounts the read-only filesystem with `squashfuse -o ro,offset=xxx`
-- The filesystem is now a read-only filesystem
-  - The root of the filesystem should contain a file named loader (by the way, currently it's .loader)
-  - The directory structure should be: /{id}/{version}/{arch}/
-- The read-only filesystem should support EROFS, and MAY support squashfs
-
-A full example of the filesystem is:
-
-```bash
-
-```

docs/mirrors.md

@@ -1,69 +0,0 @@
-# 玲珑仓库 Mirror 功能设计
-
-在 ll-cli 和 ll-builder 中添加了 enable-mirror 和 disable-mirror 命令，用于启用和禁用镜像功能。
-
-在对某个仓库启用 mirror 功能时，会更新 ostree 的 config 文件，添加 contenturl 配置项：
-
-```diff
-url=$repo_url/repos/$repo_name
-gpg-verify=false
-http2=false
-+ contenturl=mirrorlist=$repo_url/api/v2/mirrors/$repo_name
-```
-
-当添加 contenturl 配置项后，ostree 会优先使用 contenturl 下载静态文件如 files，url 仅用于获取元数据如 summary。contenturl 支持 file://、http://、https:// 三种协议。
-
-如果在 url 前面添加 mirrorlist=，则 ostree 会先从 url 获取按行分割的镜像列表，然后从镜像列表中选择镜像用于下载文件，具体逻辑见 [ostree pull 步骤](#ostree-pull-步骤) 章节。
-
-/api/v2/mirrors/$repo_name 是玲珑服务器的一个 API 接口，通过客户端 IP 获取客户端所在国家，从配置文件获取对应国家的镜像列表，然后返回给 ostree，这样就实现了根据用户所在国家自动分流仓库文件下载的功能。
-
-## 镜像站配置
-
-玲珑的镜像站只需提供仓库静态文件的 HTTPS 访问即可，玲珑仓库支持 rsync 和 ostree 两种同步协议。
-
-### 使用 rsync 同步配置
-
-优点是同步速度快，缺点是需要从支持 rsync 协议的镜像站或官方仓库同步仓库。
-
-```bash
-rsync rsync://rsync.linyaps.org.cn/repos/stable $www_root/repos/stable
-```
-
-### 使用 ostree 同步配置
-
-优点是无须协议支持，可从任意镜像站同步仓库，缺点是同步速度较慢。
-
-保存下面脚本，并命名为 sync.sh，然后执行 `sh sync.sh https://mirror-repo-linglong.deepin.com/repos/stable/ $www_root/repos/stable`
-
-```bash
-#!/bin/bash
-set -e
-url=$1
-dir=$2
-echo sync $url to $dir
-sleep 3
-ostree init --repo=$dir --mode archive
-ostree --repo=$dir remote add --if-not-exists --no-sign-verify remote $url
-for ref in $(ostree --repo=$dir remote refs remote); do
-    echo pull $ref;
-    ostree --repo=$dir pull --mirror $ref;
-done
-```
-
-## ostree pull 步骤
-
-### 判断镜像是否可用
-
-在 pull 时，ostree 先从 contenturl 获取镜像列表，然后从每个 url 获取 /config 文件。如果获取不到 /config 文件，则认为该 mirror 不可用；如果获取到 /config 文件，则认为该 mirror 可用。如果没有可用 mirror，pull 失败。
-
-### 获取 summary 文件
-
-ostree 会从 url 获取 summary 文件。如果获取不到 summary 文件，或者 summary 文件中不存在 ref，pull 失败。
-
-### delta-indexes 文件获取
-
-ostree 会在每个可用的 mirror 中获取 delta-indexes。如果 mirror 服务器返回 4xx 或 5xx，则在下一个 mirror 中获取 delta-indexes。如果最后的 mirror 返回 5xx，则 pull 失败；如果最后的 mirror 返回 4xx，则跳过 delta 步骤直接拉取 files。
-
-### files 文件获取
-
-ostree 会按顺序从可用的 mirror 中获取 files。如果 mirror 服务器返回 403、404、410，则认为错误不可恢复，pull 失败；如果 mirror 服务器返回其他错误码，则使用下一个 mirror 获取 files。如果所有 mirror 都无法获取 files，则 pull 失败。

docs/pages/README.zh_CN.md

@@ -0,0 +1,3 @@
+# 通知
+
+这些文件将通过 GitHub Action 自动同步到另一个 GitHub 仓库 [linglong-homepage](https://github.com/OpenAtom-Linyaps/linyaps-doc)。

docs/pages/en/guide/building/demo.md

@@ -4,17 +4,17 @@ SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
 SPDX-License-Identifier: LGPL-3.0-or-later
 -->
 
-# Build Example Demo
+# Building Example Demonstration
 
-## Initialize a Linglong Application Project
+## Initialize a Linyaps Application Project
 
 ```bash
 ll-builder create org.deepin.demo
 ```
 
-## Edit the linglong.yaml Configuration File
+## Edit linglong.yaml Configuration File
 
-### Configure Package Metadata
+### Configure Package Metadata Information
 
 ```yaml
 package:
@@ -26,7 +26,7 @@ package:
     A simple demo app.
 ```
 
-### Configure Application Startup Command
+### Configure Application Launch Command
 
 ```yaml
 command:
@@ -42,7 +42,7 @@ runtime: org.deepin.runtime.dtk/23.1.0
 
 ### Configure Source Code Information
 
-Use Git to Fetch the Source Code
+Fetch source code using Git
 
 ```yaml
 sources:
@@ -55,13 +55,14 @@ sources:
 ### Configure Build Rules
 
 ```yaml
-cd /project/linglong/sources/linglong-builder-demo
-rm -rf build || true
-mkdir build
-cd build
-qmake ..
-make
-make install
+build: |
+  cd /project/linglong/sources/linglong-builder-demo
+  rm -rf build || true
+  mkdir build
+  cd build
+  qmake ..
+  make
+  make install
 ```
 
 ### Complete linglong.yaml Configuration File
@@ -99,11 +100,11 @@ build: |
   make install
 ```
 
-For more details on configuration file fields, please refer to [Configuration File Description](./manifests.md)
+For more configuration file field definitions, refer to [Configuration File Reference](./manifests.md)
 
 ## Execute the Build Process
 
-In the root directory of the Linglong project, execute the build command:
+Execute the build command in the Linyaps project root directory:
 
 ```bash
 ll-builder build
@@ -111,7 +112,7 @@ ll-builder build
 
 ## Run the Application
 
-After a successful build, execute the run command in the Linglong project directory. The application can be run directly without installation.
+After successful build, execute the run command in the Linyaps project directory to directly run the application without installation.
 
 ```bash
 ll-builder run
@@ -119,13 +120,13 @@ ll-builder run
 
 ## Export Build Artifacts
 
-In the root directory of the Linglong project, execute the export command to check out the build content.
+Execute the export command in the Linyaps project root directory to export the build contents.
 
 ```bash
 ll-builder export --layer
 ```
 
-The directory structure after export is as follows:
+The exported directory structure is as follows:
 
 ```text
 ├── linglong
@@ -134,9 +135,9 @@ The directory structure after export is as follows:
 └── org.deepin.demo_1.0.0.0_x86_64_develop.layer
 ```
 
-## More Reference Examples
+## Additional Reference Examples
 
-[qt5](https://github.com/linglongdev/cn.org.linyaps.demo.qt5) - qt5 application
+[qt5](https://github.com/linglongdev/cn.org.linyaps.demo.qt5) - qt5 program
 
 [dtk5](https://github.com/linglongdev/cn.org.linyaps.demo.dtk5.qmake) - dtk5 + qmake
 
@@ -146,10 +147,10 @@ The directory structure after export is as follows:
 
 [electron](https://github.com/myml/electron-vue-linyaps-app) - electron + vue example
 
-[plantuml](https://github.com/linglongdev/com.plantuml.gpl) - a Java application for drawing flowcharts programmatically
+[plantuml](https://github.com/linglongdev/com.plantuml.gpl) - a Java application for programmatic flowchart creation
 
-[org.sumatrapdfreader](https://github.com/linglongdev/org.sumatrapdfreader) - a Wine application, a PDF reader
+[org.sumatrapdfreader](https://github.com/linglongdev/org.sumatrapdfreader) - a Wine application, PDF reader
 
-## More Complete Examples
+## More Complete Example
 
-[Complete Example](../start/how_to_use.md) - a complete example that includes how to build an application, export build content, install, and run.
+[Complete Example](../start/build_your_first_app.md) - Contains a complete workflow example of how to build applications, export build contents, install, and run.

docs/pages/en/guide/building/linyaps_package_spec.md

@@ -0,0 +1,900 @@
+# Linyaps Application Packaging Specification
+
+The keywords **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL**[^rfc2119-keywords] in this document shall be interpreted as described in [RFC 2119][rfc-2119].
+
+The correspondence between these keywords and their English counterparts is shown in the following table:
+
+| Chinese    | English     |
+| ---------- | ----------- |
+| **必须**   | MUST        |
+| **禁止**   | MUST NOT    |
+| **必要的** | REQUIRED    |
+| **应当**   | SHALL       |
+| **不应**   | SHALL NOT   |
+| **推荐的** | RECOMMENDED |
+| **允许**   | MAY         |
+| **可选的** | OPTIONAL    |
+
+[rfc-2119]: https://datatracker.ietf.org/doc/html/rfc2119
+
+This document aims to help application developers standardize application building processes to migrate to the Linyaps package management system.
+
+## General
+
+This section mainly records some general specifications that almost all projects should follow.
+
+### Application Name
+
+Application names **SHALL** use [reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation), such as `org.deepin.demo`.
+
+This application name is mainly used for desktop file naming, DBus service naming, etc.
+
+- Developers **SHALL** use the reverse of a domain they actually own as the application name prefix, followed by the application name
+
+  **Note**: If a developer cannot prove they actually own the domain, it may result in the application package being removed from the repository.
+
+- For third-party applications developed on GitHub, if the organization hosting the application has an additional domain, it **SHALL** be preferred; otherwise, `io.github.<GITHUB_ID>.` **SHALL** be used as the prefix.
+
+  Particularly, if the application's organization name and application name are the same, such as <https://github.com/neovim/neovim>, packagers **SHALL NOT** omit the repeated application name and organization name. The application ID **SHALL** be `io.github.neovim.neovim`.
+
+  **Note**: In reality, the organization owns the domain `neovim.io`, so the most reasonable application name **SHALL** be `io.neovim.neovim`.
+
+- Application names containing `-` are **NOT RECOMMENDED**. If a domain/application name genuinely contains `-`, using `_` **IS RECOMMENDED** instead.
+
+- Application names ending with `.desktop` are **NOT RECOMMENDED**
+
+These specifications come from the [Desktop Entry Specification][desktop-entry-specification].
+
+[desktop-entry-specification]: https://specifications.freedesktop.org/desktop-entry-spec/latest
+
+Further reading: <https://docs.flatpak.org/en/latest/conventions.html#application-ids>
+
+### `prefix` and `$DESTDIR`
+
+When writing an application's build process, developers **SHALL NOT** assume a fixed installation location. Installing executables to hardcoded paths in Makefile/CMakeLists.txt, such as `/usr/bin`, is non-compliant behavior.
+
+When developers write build/install processes, they **SHALL** respect the build system's `prefix` configuration and the value of the `$DESTDIR` environment variable to allow packagers to conveniently configure the application's specific installation location during packaging.
+
+`prefix` refers to the specific location in the system where the application will ultimately be installed, as specified to the build system during build/install time.
+
+When developers do not specify an installation location, its default value **SHALL** be `/usr/local`. When packaging through the package management system, the package management system configures this value. When using dpkg-related tools for packaging, the value is configured as `/usr`. However, when writing build/install processes, developers should consider that `prefix` may be configured to any value.
+
+`$DESTDIR` is an environment variable agreed upon for the build system's installation process to facilitate distribution packaging and other processes. Its general working logic is as follows:
+
+If the build system completes the build work and during the installation process is specified `prefix=/usr` and `$DESTDIR=./tmp`, after completing installation, all product files should appear in the `./tmp/usr` directory. Packaging tools will then treat `./tmp` as the root directory for compression, packaging, and other work on the files contained within.
+
+Here we use common build systems as examples to show **RECOMMENDED** ways of writing common file installation processes. These writing methods all respect the `prefix` configuration and `$DESTDIR`:
+
+#### Makefile
+
+This section is mainly referenced from content in <https://www.gnu.org/prep/standards/standards.html> and <https://wiki.debian.org/Multiarch/Implementation>.
+
+Here we define default values for some variables and other common parts for writing examples later. Explanations of these variable defaults can be found in the links above.
+
+```makefile
+DESTDIR ?=
+
+prefix      ?= /usr/local
+bindir      ?= $(prefix)/bin
+libdir      ?= $(prefix)/lib
+libexecdir  ?= $(prefix)/libexec
+datarootdir ?= $(prefix)/share
+
+INSTALL         ?= install
+INSTALL_PROGRAM ?= $(INSTALL)
+INSTALL_DATA    ?= $(INSTALL) -m 644
+
+# The above defined variables with default values are recommended behaviors in the above specifications and should not be modified.
+
+PKG_CONFIG ?= pkg-config
+
+.PHONY: install
+```
+
+- Executable files
+
+  ```makefile
+  install:
+      $(INSTALL) -d "$(DESTDIR)$(bindir)"
+      $(INSTALL_PROGRAM) path/to/your/executable "$(DESTDIR)$(bindir)"/executable
+  ```
+
+- Internal executables
+
+  Refers to executables that should not be directly invoked by users in the terminal. These executables **SHALL NOT** be accessible via `$PATH`.
+
+  ```makefile
+  install:
+      $(INSTALL) -d "$(DESTDIR)$(libexecdir)"
+      $(INSTALL_PROGRAM) path/to/my/internal/executable "$(DESTDIR)$(libexecdir)"/executable
+  ```
+
+- Static libraries
+
+  ```makefile
+  install:
+      $(INSTALL) -d "$(DESTDIR)$(libdir)"
+      $(INSTALL_DATA) path/to/my/library.a "$(DESTDIR)$(libdir)"/library.a
+  ```
+
+- pkg-config configuration files
+
+  ```makefile
+  pc_dir ?= $(libdir)/pkgconfig
+  ifeq ($(findstring $(pc_dir), $(subst :, , $(shell \
+      $(PKG_CONFIG) --variable=pc_path)), )
+  $(warning pc_dir="$(pc_dir)" \
+      is not in the search path of current pkg-config installation)
+  endif
+
+  .PHONY: install-pkg-config
+  install-pkg-config:
+      $(INSTALL) -d "$(DESTDIR)$(pc_dir)"
+      $(INSTALL_DATA) path/to/your.pc "$(DESTDIR)$(pc_dir)"/your.pc
+  ```
+
+  If it can be determined that the file is cross-architecture compatible, `$(datarootdir)` **MAY** be used instead of `$(libdir)`.
+
+- System-level systemd units
+
+  ```makefile
+  systemd_system_unit_dir ?= $(shell \
+      $(PKG_CONFIG) --define-variable=prefix=$(prefix) \
+      systemd --variable=systemd_system_unit_dir)
+  ifeq ($(findstring $(systemd_system_unit_dir), $(subst :, , $(shell \
+      $(PKG_CONFIG) systemd --variable=systemd_system_unit_path))), )
+  $(warning systemd_system_unit_dir="$(systemd_system_unit_dir)" \
+      is not in the system unit search path of current systemd installation)
+  endif
+
+  .PHONY: install-systemd-system-unit
+  install-systemd-system-unit:
+      $(INSTALL) -d "$(DESTDIR)$(systemd_system_unit_dir)"
+      $(INSTALL_DATA) path/to/your.service "$(DESTDIR)$(systemd_system_unit_dir)"/your.service
+  ```
+
+- User-level systemd units
+
+  ```makefile
+  systemd_user_unit_dir ?= $(shell \
+      $(PKG_CONFIG) --define-variable=prefix=$(prefix) \
+      systemd --variable=systemd_user_unit_dir)
+  ifeq ($(findstring $(systemd_user_unit_dir), $(subst :, , $(shell \
+      $(PKG_CONFIG) systemd --variable=systemd_user_unit_path))), )
+  $(warning systemd_user_unit_dir="$(systemd_user_unit_dir)" \
+      is not in the user unit search path of current systemd installation)
+  endif
+
+  .PHONY: install-systemd-user-unit
+  install-systemd-user-unit:
+      $(INSTALL) -d "$(DESTDIR)$(systemd_user_unit_dir)"
+      $(INSTALL_DATA) path/to/your.service "$(DESTDIR)$(systemd_user_unit_dir)"/your.service
+  ```
+
+- Desktop files
+
+  ```makefile
+  install:
+      $(INSTALL) -d "$(DESTDIR)$(datarootdir)"/applications
+      $(INSTALL_PROGRAM) path/to/your.desktop "$(DESTDIR)$(datarootdir)"/applications/your.desktop
+  ```
+
+- Desktop file icons
+
+  See: <https://specifications.freedesktop.org/icon-theme-spec/latest/#install_icons>
+  - If installing icons of fixed sizes, using PNG format **IS RECOMMENDED**
+
+    At least a 48x48 PNG **MUST** be installed to ensure proper basic functionality of icon-related features in the desktop environment
+
+  - If installing vector versions of icons, using SVG format **IS RECOMMENDED**
+
+  ```makefile
+  install:
+      $(INSTALL) -d "$(DESTDIR)$(datarootdir)"/icons/hicolor/48x48/apps
+      $(INSTALL_DATA) path/to/your.png "$(DESTDIR)$(datarootdir)"/icons/hicolor/48x48/apps/your.png
+      # Add more sizes of .png icons here...
+
+      $(INSTALL) -d "$(DESTDIR)$(datarootdir)"/icons/hicolor/scalable/apps
+      $(INSTALL_DATA) path/to/your.svg "$(DESTDIR)$(datarootdir)"/icons/hicolor/scalable/apps/your.svg
+  ```
+
+#### CMake
+
+This section is mainly referenced from content in <https://cmake.org/cmake/help/v3.30/module/GNUInstallDirs.html#module:GNUInstallDirs> and <https://wiki.debian.org/Multiarch/Implementation>.
+
+Here we define default values for some variables and other common parts for writing examples later. Explanations of these variable defaults can be found in the links above.
+
+The writing logic is consistent with the related content in the Makefile section.
+
+```cmake
+include(GNUInstallDirs)
+```
+
+- Executable files
+
+  See: <https://cmake.org/cmake/help/v3.30/command/install.html#programs>
+
+  ```cmake
+  install(PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/path/to/your/executable TYPE BIN)
+  ```
+
+- Internal executables
+
+  Refers to executables that should not be directly invoked in the terminal. These executables **SHALL NOT** be accessible via `$PATH`
+
+  See: <https://cmake.org/cmake/help/v3.30/command/install.html#programs>
+
+  ```cmake
+  install(PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/path/to/your/executable DESTINATION ${CMAKE_INSTALL_LIBEXECDIR})
+  ```
+
+  Note: TYPE is not used because TYPE does not currently support LIBEXEC
+
+- Target files/Export files
+
+  To be supplemented
+
+- pkg-config configuration files
+
+  To be supplemented
+
+- System-level systemd units
+
+  ```cmake
+  find_package(PkgConfig)
+  if(NOT SYSTEMD_SYSTEM_UNIT_DIR)
+      if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.28")
+          pkg_get_variable(SYSTEMD_SYSTEM_UNIT_DIR systemd systemd_system_unit_dir
+                           DEFINE_VARIABLES prefix=${CMAKE_INSTALL_PREFIX})
+      else()
+          pkg_get_variable(SYSTEMD_PREFIX systemd prefix)
+          pkg_get_variable(SYSTEMD_SYSTEM_UNIT_DIR systemd systemd_system_unit_dir)
+          string(REPLACE "${SYSTEMD_PREFIX}" "${CMAKE_INSTALL_PREFIX}"
+                 SYSTEMD_SYSTEM_UNIT_DIR "${SYSTEMD_SYSTEM_UNIT_DIR}")
+      endif()
+  endif()
+  pkg_get_variable(SYSTEMD_SYSTEM_UNIT_PATH systemd systemd_system_unit_path)
+  if(NOT SYSTEMD_SYSTEM_UNIT_PATH MATCHES ".*:${SYSTEMD_SYSTEM_UNIT_DIR}:.*")
+      message(WARNING SYSTEMD_SYSTEM_UNIT_DIR="${SYSTEMD_SYSTEM_UNIT_DIR}" is not
+                      in the system unit search path of
+                      current systemd installation)
+  endif()
+
+  install(FILES path/to/your.service
+          DESTINATION ${SYSTEMD_SYSTEM_UNIT_DIR})
+  ```
+
+- User-level systemd units
+
+  ```cmake
+  find_package(PkgConfig)
+  if(NOT SYSTEMD_USER_UNIT_DIR)
+      if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.28")
+          pkg_get_variable(SYSTEMD_USER_UNIT_DIR systemd systemd_user_unit_dir
+                           DEFINE_VARIABLES prefix=${CMAKE_INSTALL_PREFIX})
+      else()
+          pkg_get_variable(SYSTEMD_PREFIX systemd prefix)
+          pkg_get_variable(SYSTEMD_USER_UNIT_DIR systemd systemd_user_unit_dir)
+          string(REPLACE "${SYSTEMD_PREFIX}" "${CMAKE_INSTALL_PREFIX}"
+                 SYSTEMD_USER_UNIT_DIR "${SYSTEMD_USER_UNIT_DIR}")
+      endif()
+  endif()
+  pkg_get_variable(SYSTEMD_USER_UNIT_PATH systemd systemd_user_unit_path)
+  if(NOT SYSTEMD_USER_UNIT_PATH MATCHES ".*:${SYSTEMD_USER_UNIT_DIR}:.*")
+      message(WARNING SYSTEMD_USER_UNIT_DIR="${SYSTEMD_USER_UNIT_DIR}" is not
+                      in the user unit search path of
+                      current systemd installation)
+  endif()
+
+  install(FILES path/to/your.service
+          DESTINATION ${SYSTEMD_USER_UNIT_DIR})
+  ```
+
+- Desktop files
+
+  ```cmake
+  install(FILES path/to/your.desktop
+          DESTINATION ${CMAKE_INSTALL_DATADIR}/applications)
+  ```
+
+- Desktop file icons
+
+  ```cmake
+  install(FILES path/to/your.png
+          DESTINATION ${CMAKE_INSTALL_DATADIR}/icons/hicolor/48x48/apps)
+  # Add more sizes of .png icons here...
+
+  install(FILES path/to/your.svg
+          DESTINATION ${CMAKE_INSTALL_DATADIR}/icons/hicolor/scalable/apps)
+  ```
+
+### Configuration Files
+
+#### Desktop files
+
+Desktop file names **SHALL NOT** contain `-`. After removing the `.desktop` suffix, they **SHALL** comply with the relevant specifications described in the Application Name section.
+
+- **RECOMMENDED** to fill the [`TryExec` field][key-tryexec] to ensure that the desktop file is no longer valid after the application has been uninstalled
+- **RECOMMENDED** to fill the [`WMClass` field][key-startupwmclass] to ensure that desktop environment basic functions based on window and application matching, such as taskbar, work properly
+- **RECOMMENDED** to use only the executable file name rather than absolute paths when filling the [`Exec` field][key-exec]
+- **NOT RECOMMENDED** to use absolute paths when filling the [`Icon` field][key-icon]
+
+[key-tryexec]: https://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html#key-tryexec
+[key-startupwmclass]: https://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html#key-startupwmclass
+[key-exec]: https://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html#key-exec
+[key-icon]: https://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html#key-icon
+
+#### DBus Services
+
+- **RECOMMENDED** that service file names match the Name field in the file
+- **RECOMMENDED** to use absolute paths in the Exec field of service files
+- **RECOMMENDED** to fill the SystemdService field
+- **RECOMMENDED** that the service name in the SystemdService field matches the Name field
+- **RECOMMENDED** that the Name field ends with a number
+
+#### Systemd Services
+
+- **RECOMMENDED** that service files with BusName have file names matching the BusName
+- **RECOMMENDED** to use absolute paths in the ExecStart field
+
+When the above configuration files use absolute paths, **NOT RECOMMENDED** to hardcode paths. Their paths **SHALL** remain consistent with the final installation location. **RECOMMENDED** to first write template files in the project, using placeholders to represent absolute paths, and generate final configuration files after the build system replaces the placeholders.
+
+Here we use desktop files as examples to show how to generate final configuration files under several common build systems.
+
+Assume the final product `org.deepin.demo.desktop` content is as follows:
+
+```ini
+[Desktop Entry]
+Name=demo
+Exec=/usr/bin/demo
+Type=Application
+Terminal=false
+```
+
+- Using Makefile as the build system.
+  1. First, write the template file `org.deepin.demo.desktop.in` with the following content:
+
+  ```ini
+  [Desktop Entry]
+  Name=demo
+  Exec=@BINDIR@/demo
+  Type=Application
+  Terminal=false
+  ```
+
+  2. Write the corresponding makefile rules.
+
+  ```makefile
+  DESKTOP_TEMPLATE = org.deepin.demo.desktop.in
+  DESKTOP_FILE = org.deepin.demo.desktop
+
+  # Replace placeholders and generate the final .desktop file
+  desktop: $(DESKTOP_TEMPLATE)
+    sed -e "s/@BINDIR@/$(bindir)/g" \
+        $(DESKTOP_TEMPLATE) > $(DESKTOP_FILE)
+
+  install:
+      $(INSTALL) -d "$(DESTDIR)$(datarootdir)"/applications
+      $(INSTALL_PROGRAM) $(DESKTOP_FILE) "$(DESTDIR)$(datarootdir)"/applications/$(DESKTOP_FILE)
+
+  clean:
+    rm -f $(DESKTOP_FILE)
+
+  all: desktop
+  ```
+
+- If using CMake as the build system.
+  1. Write the desktop template file.
+
+  ```desktop
+  [Desktop Entry]
+  Name=demo
+  Exec=@CMAKE_INSTALL_BINDIR@/demo
+  Type=Application
+  Terminal=false
+  ```
+
+  2. Write the corresponding cmake rules.
+
+  ```cmake
+  set(DESKTOP_FILE "org.deepin.demo.desktop")
+  # Use configure_file for placeholder replacement
+  configure_file(
+      ${CMAKE_CURRENT_SOURCE_DIR}/org.deepin.demo.desktop.in
+      ${CMAKE_CURRENT_BINARY_DIR}/${DESKTOP_FILE}
+      @ONLY
+  )
+  install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${DESKTOP_FILE}
+          DESTINATION ${CMAKE_INSTALL_DATADIR}/applications)
+  ```
+
+### Header Files and Libraries
+
+The Linyaps environment consists of up to three parts. Taking compiling `org.deepin.demo` under the `x86_64` architecture as an example, the default search paths for header files and library files include the following parts:
+
+| **Component**      | **Package Name**       | **Header Files**                        | **Library Files**                                                                           |
+| ------------------ | ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------- |
+| base               | org.deepin.base        | /usr/include                            | /usr/lib<br>/usr/lib/x86_64-linux-gnu                                                       |
+| runtime (optional) | org.deepin.runtime.dtk | /runtime/include                        | /runtime/lib<br>/runtime/lib/x86_64-linux-gnu                                               |
+| app                | org.deepin.demo        | /opt/apps/org.deepin.demo/files/include | /opt/apps/org.deepin.demo/files/lib<br>/opt/apps/org.deepin.demo/files/lib/x86_64-linux-gnu |
+
+Priority is arranged from top to bottom. If a header file exists in both `org.deepin.base` and `org.deepin.demo`, the file in `org.deepin.demo` will be matched with higher priority during use. The same applies to library files.
+
+Default search paths are suitable for standard libraries or development libraries without configuration files. In actual build scenarios, development libraries usually provide configuration files to facilitate users' compilation and linking. Developers **SHALL** use these files in their build systems rather than relying on default search paths.
+
+Common configuration files include `.pc`, `.cmake`, etc. How to use them specifically depends on the development library and build system. Here we give examples of using configuration files with several common build systems.
+
+#### Makefile
+
+##### Using `.pc` files
+
+```makefile
+# Common variables, inherit CXXFLAGS environment variable and append content
+CXX = g++
+CXXFLAGS = $(CXXFLAGS) -Wall -Wextra -std=c++11
+# Get .pc file content through pkg-config tool
+# Return value is generally content of -I/path -lname type
+PKG_CONFIG = pkg-config
+LIBS = $(shell $(PKG_CONFIG) --cflags --libs libname)
+
+TARGET = demo
+
+SRCS = main.cpp
+
+all: $(TARGET)
+
+# Provide .pc information to compiler during build
+$(TARGET): $(SRCS)
+ $(CXX) $(CXXFLAGS) $(LIBS) -o $@ $^
+
+clean:
+ rm -f $(TARGET)
+```
+
+#### CMake
+
+##### Using `.pc` files
+
+```cmake
+find_package(PkgConfig REQUIRED)
+pkg_check_modules(PackageAliasName REQUIRED IMPORTED_TARGET PackageName)
+
+# Add executable
+add_executable(demo main.cpp)
+
+# Set linking libraries. Header file search paths will be automatically expanded.
+target_link_libraries(demo PRIVATE PkgConfig::PackageAliasName)
+```
+
+##### Using `.cmake` files
+
+```cmake
+find_package(<PackageName> REQUIRED COMPONENTS <Component>)
+
+# Add executable
+add_executable(demo main.cpp)
+
+# Set linking libraries. Header file search paths will be automatically expanded.
+target_link_libraries(demo PRIVATE PackageName::Component)
+```
+
+Note:
+
+**NOT RECOMMENDED** to directly hardcode the above default search paths in project build configuration files.
+**NOT RECOMMENDED** to override environment variables such as CFLAGS/CXXFLAGS. If there are additional parameters, they **SHALL** be appended to these variables.
+
+### Dependency Introduction
+
+As mentioned in the "Header Files and Libraries" section, the Linyaps environment consists of multiple parts. If the content in base or even runtime cannot meet requirements, developers **SHALL** introduce missing dependencies on the APP side. The introduction method is to declare them under the `sources` field in the `linglong.yaml` file and write corresponding installation or compilation rules under the `build` field.
+
+`sources` supports multiple file types, **MAY** introduce source code or compiled binary files, even a deb. However, for introducing compiled binary files, developers **MUST** consider whether they are compatible with the current base or runtime.
+
+#### Using Source Code Introduction
+
+Introducing dependencies through source code is a **RECOMMENDED** practice, as it can greatly ensure the stability and maintainability of the build process. The downside is that it may take developers considerable time to write yaml files, as dependencies may have their own dependencies.
+
+_If developers find that dependencies are complex and repeatedly used by other applications, they **SHOULD** consider integrating the dependencies into a runtime-type package._
+
+When dependencies are compiled under the Linyaps environment, their configuration files are usually "reliable". After compilation and installation, developers can directly use them in their projects.
+
+```yaml
+sources:
+  - kind: git
+    url: # app source url
+    commit: # commit hash
+  - kind: git
+    url: # dependency source url
+    commit: # commit hash
+build:
+  # Compile dependency
+  cd /project/your_dependency_name/
+  cmake -Bbuild -DCMAKE_INSTALL_PREFIX=$PREFIX
+  make install
+
+  # Compile and install APP
+  cd /project/your_app_name
+  cmake -Bbuild -DCMAKE_INSTALL_PREFIX=$PREFIX
+  make install
+```
+
+#### Using deb Introduction
+
+This is a "shortcut". If developers do not consider subsequent updates of the application, this method **MAY** be used. Developers can use auxiliary tools to analyze dependency relationships and batch import the involved dependencies into sources.
+
+##### Using VSCode Linyaps Extension
+
+1. Install the aptly command-line tool
+2. Search for linglong in the VSCode extension store and install related plugins.
+3. Place the sources field at the end of linglong.yaml
+4. Add gen_deb_source comment at the end of sources
+5. Press Ctrl+Shift+P and search for linglong: Gen deb sources command
+
+After execution, the yaml file will automatically write the following content:
+
+```yaml
+build:
+  # Extract and import deb, install_dep file is automatically downloaded by the plugin
+  bash ./install_dep linglong/sources "$PREFIX"
+
+  # Compile and install APP
+sources:
+  # Source code
+  - kind: git
+    url: # app source url
+    commit: # commit hash
+  # The following comments are generated and used by the plugin, retrieving libical-dev from repository to analyze its dependencies, automatically generating sources below the comments
+  # linglong:gen_deb_source sources amd64 https://ci.deepin.com/repo/deepin/deepin-community/backup/rc2 beige main
+  # linglong:gen_deb_source install libical-dev
+```
+
+Note:
+The compiled products of deb have an installation prefix of `/usr`. The `install_dep` script automatically handles `.pc` files in it, replacing `/usr` with `$PREFIX`. `xxx.cmake` type files cannot be batch processed. If there are hardcoded path behaviors, they may not work properly.
+
+## Linyaps
+
+This section mainly describes some special requirements of the Linyaps package management system for applications.
+
+### Limitations
+
+- Applications that need to be packaged through the Linyaps package management system **MUST** run as the user who started the Linyaps container (usually a regular user). Any form of privilege escalation mechanism is unavailable when the Linyaps package management system runs applications, including but not limited to SUID bits recorded in the file system and capabilities and other permission escalation mechanisms based on file system extended attributes.
+- Linyaps currently does not support packaging applications containing system-level systemd units.
+- **NOT RECOMMENDED** to package Desktop Environment components, such as launchers, file managers, resource managers, status bars, etc.
+
+### Specifications
+
+#### Application Package Name
+
+Linyaps application package names **MUST** fully comply with the relevant regulations in the "Application Name" section above. Additionally:
+
+- Application names are case-insensitive
+
+#### Application Version Number
+
+Linyaps package application version numbers **MUST** be four groups of decimal numbers separated by `.`, for example `1.0.0.0`.
+
+If the specified version number has fewer than four groups, zeros will be supplemented backward until the conditions are met, for example `1.90` will be automatically supplemented to `1.90.0.0`.
+
+The overall length of the version number after automatic supplementation to four groups **SHALL NOT** exceed 256 bytes in string meaning.
+
+#### Runtime Environment
+
+Linyaps applications **MUST** select a base as the basic runtime environment. Available bases:
+
+| **Base Library** | **Package Name/Version** |
+| ---------------- | ------------------------ |
+| glibc(2.38)      | org.deepin.base/23.1.0.0 |
+
+If frameworks beyond the basic environment need to be used additionally, **SHALL** use appropriate runtime. Available runtime:
+
+| **Framework**       | **Package Name/Version**        |
+| ------------------- | ------------------------------- |
+| QT(5.15) + DTK(5.6) | org.deepin.runtime.dtk/23.1.0.0 |
+
+When using base or runtime, version numbers **SHALL** fill the first three digits, such as '23.1.0', to facilitate receiving updates later. Filling all four digits version means **FORBIDDEN** base or runtime updates.
+
+#### Installation Location
+
+During the build and installation process, Linyaps build tools will set the `$PREFIX` environment variable. The value of this environment variable **SHALL** be `/opt/apps/${APPID}/files`, but it is not recommended to directly use its common value when writing build and installation processes. **RECOMMENDED** to always read the `$PREFIX` environment variable.
+
+For the application's build and installation process, writable directories are only:
+
+1. The `/source` directory for placing source code required for building
+2. The installation location, i.e., the location specified by `$PREFIX`
+
+Installing files to other locations in the build process is **FORBIDDEN**, which usually leads to write failures or applications being unable to find these files at runtime.
+
+The following are examples of using the `$PREFIX` environment variable to control application installation location when calling some common build systems:
+
+##### cmake
+
+```bash
+cd path/to/build && cmake path/to/source -DCMAKE_INSTALL_PREFIX="$PREFIX"
+```
+
+##### make
+
+```bash
+cd path/to/source && make prefix="$PREFIX"
+```
+
+##### meson
+
+```bash
+cd path/to/source && meson configure --prefix="$PREFIX" path/to/build
+```
+
+## Build Artifacts
+
+This section mainly describes the composition and related functions of application build artifacts after successful build.
+
+### Directory Structure
+
+After successful application build, Linyaps build tools will submit the artifacts to local cache. When distributing offline, they should be exported as `.layer` or `.uab` type files.
+
+By extracting the build artifact layer file:
+
+```bash
+ll-builder extract org.deepin.demo_0.0.0.1_x86_64_binary.layer ./tmp
+```
+
+The following directory structure can be obtained:
+
+```plain
+  ./tmp
+  ├── entries
+  │   └── share -> ../files/share
+  ├── files
+  │   ├── bin
+  │   │   └── demo
+  │   ├── share
+  │   │   ├── applications
+  │   │   │   └── org.deepin.demo.desktop
+  │   │   ├── icons
+  │   │   │   └── hicolor
+  │   │   │       └── scalable
+  │   │   │           └── apps
+  │   │   │               └── org.deepin.demo.svg
+  │   │   ├── doc
+  │   │   │   ├── changelog.gz
+  │   │   │   └── copyright
+  │   │   ├── mime
+  │   │   │   └── packages
+  │   │   │        └── org.deepin.demo.xml
+  │   │   ├── locale
+  │   │   │   └── zh_CN
+  │   │   │       └── info.json
+  │   │   └── services
+  │   │       └── org.deepin.demo.xml
+  │   └── libs
+  │       └── libdemo.so.5.2.1
+  ├── info.json
+  └── org.deepin.demo.install
+```
+
+When the application runs, these files or directories will be mapped to the following paths in the container:
+
+```plain
+/
+├── bin
+├── ...
+├── opt
+│   └── apps
+│       └── org.deepin.demo
+│            ├── files
+│            ├── entries
+│            ├── info.json
+│            └── org.deepin.demo.install
+└── var
+```
+
+#### info.json file
+
+info.json is an application description file defined by Linyaps. This file is automatically generated by build tools and **SHALL NOT** be manually modified. Its content is as follows:
+
+```json
+{
+  "id": "org.deepin.demo",
+  "arch": ["x86_64"],
+  "base": "main:org.deepin.foundation/23.0.0/x86_64",
+  "channel": "main",
+  "command": ["/opt/apps/org.deepin.demo/files/bin/demo"],
+  "description": "simple Qt demo.\n",
+  "kind": "app",
+  "module": "runtime",
+  "name": "demo",
+  "runtime": "main:org.deepin.Runtime/23.0.1/x86_64",
+  "size": 118763,
+  "version": "0.0.0.1"
+}
+```
+
+Below is a sequential explanation of each field in info.json:
+
+`id`: Software package identifier, i.e., application package name.
+
+`arch`: Supported architectures for the software package. Currently supports the following CPU architectures:
+
+- `amd64`: Applicable to `x86_64` architecture `CPU`.
+- `loongarch64`: Applicable to new Loongson series `CPU`.
+- `arm64`: Applicable to `ARM64` bit `CPU`.
+
+`base`: Basic environment used by the software package at runtime.
+
+`channel`: Software package distribution channel.
+
+`command`: Default startup command for the software package.
+
+`description`: Description information of the software package.
+
+`kind`: Software package category.
+
+`module`: Software package module.
+
+`name`: Common name of the software package.
+
+`runtime`: Environment used by the software package at runtime.
+
+`size`: Software package size.
+
+`version`: Application version, whose format shall meet the requirements described in the Application Version Number section.
+
+#### entries directory
+
+This directory is used to share application configuration files with the host (desktop environment). This directory usually has the following subdirectories:
+
+- entries/share/applications
+- entries/share/dbus-1/services
+- entries/share/systemd/user
+- entries/share/icons
+- entries/share/mime
+- entries/share/fonts
+
+The entries directory is automatically generated by build tools. The directory only contains a soft link named share, which points to the files/share directory in the upper level directory.
+
+When an application is installed on the host, the Linyaps package manager will use this link file to link all files in it to the path added by Linyaps to the `$XDG_DATA_DIRS` variable. That is, `/var/lib/linglong/entries/share/`.
+
+```bash
+$ ls /var/lib/linglong/entries/share/applications/ -l
+lrwxrwxrwx 1 deepin-linglong deepin-linglong 101 July 30 11:13 org.deepin.demo.desktop -> ../../../layers/main/org.deepin.demo/0.0.0.1/x86_64/runtime/entries/share/applications/org.deepin.demo.desktop
+```
+
+##### applications directory
+
+Place application startup configuration files, i.e., .desktop files.
+
+```ini
+[Desktop Entry]
+Exec=demo
+Name=demo
+TryExec=demo
+Type=Application
+```
+
+This file will be automatically modified during build to:
+
+```ini
+[Desktop Entry]
+Exec=/usr/bin/ll-cli run org.deepin.demo -- demo
+Name=demo
+TryExec=/usr/bin/ll-cli
+Type=Application
+```
+
+Applications can have multiple desktop files.
+
+**Path correspondence:**
+
+| **Packaging Path**                                 | **Installation Path**                                     |
+| -------------------------------------------------- | --------------------------------------------------------- |
+| $PREFIX/share/applications/org.deepin.demo.desktop | $XDG_DATA_DIRS/share/applications/org.deepin.demo.desktop |
+
+##### dbus services directory
+
+Directory for dbus services registered by programs, for example:
+
+```ini
+[D-BUS Service]
+Name=org.deepin.demo
+Exec=/opt/apps/org.deepin.demo/files/bin/demo --dbus
+```
+
+This file will be automatically modified during build to:
+
+```ini
+[D-BUS Service]
+Name=org.deepin.demo
+Exec=/usr/bin/ll-cli run org.deepin.demo -- /opt/apps/org.deepin.demo/files/bin/demo --dbus
+```
+
+An application can configure multiple services. Service names must be subdomains.
+
+**Path correspondence:**
+
+| **Packaging Path**                                   | **Installation Path**                                       |
+| ---------------------------------------------------- | ----------------------------------------------------------- |
+| $PREFIX/share/services/org.deepin.demo.service       | $XDG_DATA_DIRS/dbus-1/service/org.deepin.demo.service       |
+| $PREFIX/share/services/org.deepin.demo.hello.service | $XDG_DATA_DIRS/dbus-1/service/org.deepin.demo.hello.service |
+
+##### User-level systemd services
+
+Directory for user-level services registered by programs, for example:
+
+```ini
+[Unit]
+Description = demo service
+After=user-session.target
+
+[Service]
+Type = simple
+ExecStart = demo
+
+[Install]
+WantedBy=user-session.target
+```
+
+This file will be automatically modified during build to:
+
+```ini
+[Unit]
+Description = demo service
+After=user-session.target
+
+[Service]
+Type = simple
+ExecStart = ll-cli run org.deepin.demo -- demo
+
+[Install]
+WantedBy=user-session.target
+```
+
+Unlike dbus service, files installed to `$PREFIX/lib/systemd/user` will be automatically copied to `$PREFIX/share/systemd/user`.
+
+**Path correspondence:**
+
+| **Packaging Path**                               | **Installation Path**                               |
+| ------------------------------------------------ | --------------------------------------------------- |
+| $PREFIX/lib/systemd/user/org.deepin.demo.service | $XDG_DATA_DIRS/systemd/user/org.deepin.demo.service |
+
+##### icons directory
+
+Directory for application icons. The structure should be consistent with the system icons directory structure.
+
+**Path correspondence:**
+
+| **Packaging Path**                                            | **Installation Path**                                          |
+| ------------------------------------------------------------- | -------------------------------------------------------------- |
+| $PREFIX/share/icons/hicolor/scalable/apps/org.deepin.demo.svg | $XDG_DATA_DIRS/icons/hicolor/scalable/apps/org.deepin.demo.svg |
+| $PREFIX/share/icons/hicolor/24x24/apps/org.deepin.demo.png    | $XDG_DATA_DIRS/icons/hicolor/24x24/apps/org.deepin.demo.png    |
+| $PREFIX/share/icons/hicolor/16x16/apps/org.deepin.demo.png    | $XDG_DATA_DIRS/icons/hicolor/16x16/apps/org.deepin.demo.png    |
+
+##### mime directory
+
+MIME (Multipurpose Internet Mail Extensions) multipurpose internet mail extensions type. This directory is used to store mime configuration files, which are in XML format and end with .xml.
+
+**Path correspondence:**
+
+| **Packaging Path**                              | **Installation Path**                            |
+| ----------------------------------------------- | ------------------------------------------------ |
+| $PREFIX/share/mime/packages/org.deepin.demo.xml | $XDG_DATA_DIRS/mime/packages/org.deepin.demo.xml |
+
+##### fonts directory
+
+Font storage path.
+
+#### files directory
+
+Store various files required by the application. There are no restrictions on placing files in this directory, but it is recommended to place executable programs in the bin subdirectory. Third-party libraries that applications or plugins depend on are recommended to be placed in /opt/apps/${id}/files/lib directory.
+
+#### .install file
+
+The org.deepin.demo.install file in the above example org.deepin.demo is a file automatically generated during the build process. This file is used to define which files should be installed in the binary module and can be used for final software package artifact volume trimming.
+
+When this file is not defined in the same directory level as linglong.yaml, all content is installed to the binary module according to the rules under build in linglong.yaml.
+
+Usage method:
+
+After the first successful build, an .install file will be generated in the artifacts and record all files installed to the binary module. Copy this file to the directory level of linglong.yaml. After modifying the content in the .install file and building again, only the content noted in .install will be submitted to the binary module.
+
+## References
+
+[Desktop Application Packaging Specifications](https://github.com/linuxdeepin/deepin-specifications/blob/master/unstable/%E6%A1%8C%E9%9D%A2%E5%BA%94%E7%94%A8%E6%89%93%E5%8C%85%E8%A7%84%E8%8C%83.md)

docs/pages/en/guide/building/manifests.md

@@ -0,0 +1,361 @@
+<!--
+SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
+
+SPDX-License-Identifier: LGPL-3.0-or-later
+-->
+
+# Build Configuration File Introduction
+
+`linglong.yaml` is the description file for Linyaps project engineering, which records relevant information needed for building, such as build artifact names, versions, source code addresses, build dependencies, etc.
+
+## Project Directory Structure
+
+```bash
+{project-root}
+├── linglong.yaml
+└── linglong
+
+{user-home}
+└── .cache
+    └── linglong-builder
+        ├── repo
+        └── layers
+```
+
+## Field Definitions
+
+The `linglong.yaml` file structure follows specific specifications. First, the version of the configuration file needs to be declared at the top level of the file:
+
+```yaml
+version: "1"
+```
+
+| Name    | Description                                            | Required |
+| ------- | ------------------------------------------------------ | -------- |
+| version | Version of the build configuration file, currently '1' | Yes      |
+
+Next are the main configuration blocks. Among them, `package`, `base`, and `build` must be defined.
+
+### Package Metadata Configuration (`package`)
+
+Defines basic information about build artifacts. This `package` configuration block is required.
+
+```yaml
+package:
+  id: org.deepin.calculator
+  name: deepin-calculator
+  version: 5.7.21.0
+  kind: app
+  description: |
+    calculator for deepin os.
+  architecture: x86_64 # Optional
+  channel: main # Optional
+```
+
+| Name         | Description                                                                | Required |
+| ------------ | -------------------------------------------------------------------------- | -------- |
+| id           | Unique name of build artifact (for example: `org.deepin.calculator`)       | Yes      |
+| name         | Name of build artifact (for example: `deepin-calculator`)                  | Yes      |
+| version      | Version of build artifact, recommend four digits (for example: `5.7.21.0`) | Yes      |
+| kind         | Type of build artifact: `app` (application), `runtime` (runtime)           | Yes      |
+| description  | Detailed description of build artifact                                     | Yes      |
+| architecture | Target architecture of build artifact (for example: `x86_64`, `arm64`)     | No       |
+| channel      | Channel of build artifact (for example: `main`, `dev`)                     | No       |
+
+### Command (`command`)
+
+Defines how to start the application. This is a list of strings. The first element in the list is usually the absolute path of the executable file (relative to inside the container), and subsequent elements are parameters passed to the executable.
+
+```yaml
+command:
+  - /opt/apps/org.deepin.calculator/files/bin/deepin-calculator
+  # - --some-argument # Can add more parameters
+```
+
+| Name    | Description                                                                                                             | Required |
+| ------- | ----------------------------------------------------------------------------------------------------------------------- | -------- |
+| command | Defines the executable file path and its parameter list for starting the application. Usually required for `kind: app`. | No       |
+
+### Base Environment (`base`)
+
+Specifies the minimal root filesystem required for building and running. This field is required.
+
+```bash
+base: org.deepin.base/23.1.0
+```
+
+| Name | Description                                                                                             | Required |
+| ---- | ------------------------------------------------------------------------------------------------------- | -------- |
+| base | Identifier of the base, in the format `id/version`. Version numbers support three-digit fuzzy matching. | Yes      |
+
+### Runtime
+
+Application runtime dependencies, also build dependencies.
+
+```text
+runtime: org.deepin.runtime.dtk/23.1.0
+```
+
+| Name    | Description                                                     |
+| ------- | --------------------------------------------------------------- |
+| id      | Unique name of the runtime                                      |
+| version | Version of the runtime, three digits can fuzzy match the fourth |
+
+### Sources (`sources`)
+
+Describes source code information required by the project. `sources` is a list that can contain multiple source items. Fetched source code is stored by default in the `linglong/sources` directory at the same level as `linglong.yaml`.
+
+#### git Type
+
+```yaml
+sources:
+  - kind: git
+    url: https://github.com/linuxdeepin/deepin-calculator.git
+    commit: d7e207b4a71bbd97f7d818de5044228c1a6e2c92 # Branch, tag or commit, used to precisely specify the commit
+    name: deepin-calculator.git # Optional, specify the directory name after download
+```
+
+| Name   | Description                                                                                         | Required (within single source) |
+| ------ | --------------------------------------------------------------------------------------------------- | ------------------------------- |
+| kind   | `git`, indicating using git tool to download.                                                       | Yes                             |
+| url    | Source code repository address                                                                      | Yes                             |
+| commit | Source code repository branch, tag or hash value of a specific commit, used for precise checkout    | Yes                             |
+| name   | Optional, specify the subdirectory name in `linglong/sources` directory after source code download. | No                              |
+
+#### file Type
+
+```yaml
+sources:
+  - kind: file
+    url: https://example.com/some-file.dat
+    digest: sha256:... # Recommend providing sha256 hash value
+    name: my-data.dat # Optional, specify the filename after download
+```
+
+| Name   | Description                                                                    | Required (within single source) |
+| ------ | ------------------------------------------------------------------------------ | ------------------------------- |
+| kind   | `file`, indicating direct file download.                                       | Yes                             |
+| url    | File download address                                                          | Yes                             |
+| digest | Optional, sha256 hash value of the file, used for verification.                | No                              |
+| name   | Optional, specify the filename in `linglong/sources` directory after download. | No                              |
+
+#### archive Type
+
+```yaml
+sources:
+  - kind: archive
+    url: https://github.com/linuxdeepin/deepin-calculator/archive/refs/tags/6.5.4.tar.gz
+    digest: 9675e27395891da9d9ee0a6094841410e344027fd81265ab75f83704174bb3a8 # Recommend providing sha256 hash value
+    name: deepin-calculator-6.5.4 # Optional, specify the directory name after extraction
+```
+
+| Name   | Description                                                                                           | Required (within single source) |
+| ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------- |
+| kind   | `archive`, download compressed package and automatically extract. Supports common compressed formats. | Yes                             |
+| url    | Compressed package download address                                                                   | Yes                             |
+| digest | Optional, sha256 hash value of the compressed package file, used for verification.                    | No                              |
+| name   | Optional, specify the directory name in `linglong/sources` directory after extraction.                | No                              |
+
+#### dsc Type
+
+```yaml
+sources:
+  - kind: dsc
+    url: https://cdn-community-packages.deepin.com/deepin/beige/pool/main/d/deepin-calculator/deepin-calculator_6.0.1.dsc
+    digest: ce47ed04a427a887a52e3cc098534bba53188ee0f38f59713f4f176374ea2141 # Recommend providing sha256 hash value
+    name: deepin-calculator-dsc # Optional, specify the directory name after download and extraction
+```
+
+| Name   | Description                                                                                         | Required (within single source) |
+| ------ | --------------------------------------------------------------------------------------------------- | ------------------------------- |
+| kind   | `dsc`, handle Debian source package description files and their associated files.                   | Yes                             |
+| url    | `.dsc` file download address                                                                        | Yes                             |
+| digest | Optional, sha256 hash value of the `.dsc` file, used for verification.                              | No                              |
+| name   | Optional, specify the directory name in `linglong/sources` directory after download and extraction. | No                              |
+
+### Export Trimming Rules (`exclude`/`include`)
+
+After building the application and exporting to UAB package, files that need to be trimmed are as follows:
+
+```yaml
+exclude:
+  - /usr/share/locale # Trim entire folder
+  - /usr/lib/libavfs.a # Trim single file
+
+include:
+  - /usr/share/locale/zh_CN.UTF-8 # Work with exclude to only export certain files in a folder
+```
+
+| Name    | Description                                                                                                             |
+| ------- | ----------------------------------------------------------------------------------------------------------------------- |
+| exclude | Absolute paths inside the container, can be files or folders, used for exclusion.                                       |
+| include | Absolute paths inside the container, files that must be included in UAB package (even if parent directory is excluded). |
+
+### Build Rules (`build`)
+
+Describes how to compile and install the project in the build environment. This field is required, and its content is a multi-line string that will be executed as a shell script.
+
+Describe build rules.
+
+```yaml
+build: |
+  qmake -makefile PREFIX=${PREFIX} LIB_INSTALL_DIR=${PREFIX}/lib/${TRIPLET}
+  make
+  make install
+```
+
+| Name  | Description                                                                                          | Required |
+| ----- | ---------------------------------------------------------------------------------------------------- | -------- |
+| build | Shell script executed during build phase. Script is executed inside the container build environment. | Yes      |
+
+### Build Extensions (`buildext`)
+
+Optional field, used to define extension behavior for specific build stages. Currently mainly supports `apt` extension, used to manage Debian package dependencies required for building and runtime.
+
+```yaml
+buildext:
+  apt:
+    build_depends: # Build-time dependencies, only installed in build environment
+      - build-essential
+      - cmake
+      - qt6-base-dev
+    depends: # Runtime dependencies, will be included in final application or runtime
+      - libqt6widgets6
+      - libglib2.0-0
+```
+
+| Name          | Description                                                                                                   | Required |
+| ------------- | ------------------------------------------------------------------------------------------------------------- | -------- |
+| buildext      | Container block for build extension configuration.                                                            | No       |
+| apt           | Extension configuration using apt package manager.                                                            | No       |
+| build_depends | A list of strings, listing packages needed at build time, these packages will not enter the final artifact.   | No       |
+| depends       | A list of strings, listing packages needed at runtime, these packages will be included in the final artifact. | No       |
+
+### Modules (`modules`)
+
+Optional field, used to split files installed to `${PREFIX}` directory into different modules. This is useful for on-demand downloads or providing optional functionality.
+
+```yaml
+modules:
+  - name: main # Main module name, usually same or related to package.id
+    files: # List of files or directories included in this module (relative to ${PREFIX})
+      - bin/
+      - share/applications/
+      - share/icons/
+      - lib/ # Include all libraries
+  - name: translations # Translation module
+    files:
+      - share/locale/
+  - name: extra-data # Optional data module
+    files:
+      - share/my-app/optional-data/
+```
+
+| Name    | Description                                                                                                        | Required                      |
+| ------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
+| modules | List of rules defining application module splitting.                                                               | No                            |
+| name    | Name of the module. Each module needs a unique name.                                                               | Yes (within each module item) |
+| files   | A list of strings, listing files or directories belonging to this module. Paths are relative to `${PREFIX}` paths. | Yes (within each module item) |
+
+**Note:** All files installed to `${PREFIX}` will be assigned to a module. When `modules` are not defined, the build system will automatically generate default `binary` and `develop` modules.
+
+### Variables
+
+Variables that can be used during the build process.
+
+| Name    | Description                                                                                                                    |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| PREFIX  | Environment variable used in the build field; provides installation path during build, such as /opt/apps/org.deepin.calculator |
+| TRIPLET | Environment variable used in the build field; provides a triplet containing architecture information, such as x86_64-linux-gnu |
+
+## Complete Examples
+
+### Build Application
+
+#### Calculator
+
+```yaml
+version: "1"
+
+package:
+  id: org.deepin.calculator
+  name: deepin-calculator
+  version: 5.7.21.0
+  kind: app
+  description: |
+    calculator for deepin os.
+
+command:
+  - /opt/apps/org.deepin.calculator/files/bin/deepin-calculator
+
+base: org.deepin.base/23.1.0
+runtime: org.deepin.runtime.dtk/23.1.0
+
+sources:
+  - kind: git
+    url: https://github.com/linuxdeepin/deepin-calculator.git
+    version: master
+    commit: d7e207b4a71bbd97f7d818de5044228c1a6e2c92
+
+  - kind: git
+    url: https://github.com/linuxdeepin/dde-qt-dbus-factory.git
+    version: master
+    commit: d952e1913172c5507af080f644a654f9ba5fed95
+
+build: |
+  # build dde-qt-dbus-factory
+  cd /project/linglong/sources/dde-qt-dbus-factory.git
+  qmake -makefile \
+        PREFIX=${PREFIX} \
+        LIB_INSTALL_DIR=${PREFIX}/lib/${TRIPLET} \
+        INSTALL_ROOT=${PREFIX}
+
+  make
+  make install
+
+  # build calculator
+  cd /project/linglong/sources/deepin-calculator.git
+  cmake -Bbuild \
+        -DCMAKE_INSTALL_PREFIX=${PREFIX} \
+        -DCMAKE_INSTALL_LIBDIR=${PREFIX}/lib/${TRIPLET} \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_SAFETYTEST_ARG="CMAKE_SAFETYTEST_ARG_OFF" \
+        -DAPP_VERSION=5.7.21 \
+        -DVERSION=5.7.21
+
+  cmake --build build
+  cmake --build build --target install
+
+buildext:
+  apt:
+    # Additional dependencies at build time
+    build_depends: []
+    # Additional dependencies at runtime
+    depends: []
+```
+
+### Build Root Filesystem
+
+```bash
+git clone git@github.com:linglongdev/org.deepin.foundation.git
+cd org.deepin.foundation
+bash build_base.sh beige amd64
+```
+
+This project is used to build the root filesystem used by Linyaps. beige refers to the distribution code name, amd64 refers to the architecture.
+
+| Distribution      | Architecture              |
+| ----------------- | ------------------------- |
+| eagle (UOS 20)    | amd64、arm64、loongarch64 |
+| beige (deepin 23) | amd64、arm64              |
+
+### Build Runtime
+
+```yaml
+git clone git@github.com:linglongdev/org.deepin.Runtime.git -b v23
+cd org.deepin.Runtime
+./depend-deb-list.sh | ./tools/download_deb_depend.bash
+ll-builder build --skip-fetch-source
+```
+
+Adds Qt and other basic environments on top of the root filesystem.

docs/pages/en/guide/building/modules.md

@@ -0,0 +1,73 @@
+<!--
+SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
+
+SPDX-License-Identifier: LGPL-3.0-or-later
+-->
+
+# Module Splitting
+
+When building with Linyaps, an application can be split into multiple modules, each containing part of the build artifacts. For example, debug symbols go to the `develop` module, translation files go to `lang-*` modules, etc. This allows users to install on demand and reduce application size.
+
+## Module Files
+
+Developers add a modules field in linglong.yaml and configure as follows:
+
+```yaml
+modules:
+  - name: module1
+    files:
+      - /path/to/file1
+      - /path/to/file2
+      - ^/path/to/dir1/.*
+  - name: module2
+    files:
+      - /path/to/files
+```
+
+Module names can be customized but cannot be duplicated. Some reserved module names have special meanings, such as `binary`, `develop`, `lang-*`, etc. It is recommended that developer-customized modules start with `x-` to avoid conflicts.
+
+`files` is a string array, each entry writes one file path, supporting regular expressions. File paths will automatically have the application installation path `$PREFIX` added as a prefix. So if a module wants to include the `$PREFIX/bin/demo` file, only `/bin/demo` needs to be written, and Linyaps will automatically convert it to paths like `/opt/apps/org.deepin.demo/files/bin/demo`.
+
+If the same file path is included by multiple modules, the file will only be moved to the first module (in the order of modules). When writing regular expressions in files, they need to start with `^`, otherwise they will be considered as ordinary file paths. Regular expressions will automatically add `$PREFIX` as a prefix after `^`, and packagers don't need to add it repeatedly.
+
+## Reserved Module Names
+
+### binary module
+
+_This is the default module and does not need to be declared in modules._ The binary module saves build artifacts not used by other modules. When the modules field does not exist, binary saves all build artifacts.
+
+When users install applications using ll-cli, the binary module is installed by default. Other modules can only be installed after installing the binary module. Uninstalling the binary module will uninstall other modules at the same time.
+
+### develop module
+
+This module can store debug symbols and development tools for applications. Linyaps will separate build artifact debug symbols to directories like `$PREFIX/lib/debug` and `$PREFIX/lib/include` after building. These directories are particularly suitable for storing in this module. So when Linyaps builds, if there is no modules field or the modules do not have a develop module, it will automatically create a develop module and use the following default values:
+
+```yaml
+modules:
+  - name: develop
+    files:
+      # Separated debug symbols
+      - ^/lib/debug/.+
+      # Header files
+      - ^/lib/include/.+
+      # Static link libraries
+      - ^/lib/.+\.a$
+```
+
+If you need to customize the develop module, you can add develop module configuration in the `modules` field to override the default values.
+
+### Packaging Testing
+
+The `ll-builder run` command can run compiled applications. You can use the `--modules` parameter to control which modules are used at runtime, which is convenient for packagers to test module combinations. Examples:
+
+Load multiple language modules: `ll-builder run --modules lang-zh_CN,lang-ru_RU`
+
+Load develop module: `ll-builder run --modules develop`, only as an example, not recommended for actual use, because the application's develop only has debug symbols without debugging tools. If you need to debug applications, you should use the --debug parameter, see [Debugging Applications in IDE](../debug/debug.md).
+
+### User Installation of Modules
+
+The `ll-cli install` command can install applications. By default, it will install the binary module of the application. If you need to install other modules, you can use the `--module` parameter. Note that unlike `ll-builder run --modules`, ll-cli can only install one module at a time. Examples:
+
+Install language module: `ll-cli install --module=lang-zh_CN org.xxx.xxx`
+
+Install develop module: `ll-cli install --module=develop org.xxx.xxx`

docs/pages/en/guide/building/multiarch.md

@@ -0,0 +1,73 @@
+# Linyaps Multi-Architecture Build Guide
+
+## Supported Architectures
+
+The current Linyaps packaging tool supports the following CPU architectures:
+
+- x86_64
+
+- arm64 (aarch64)
+
+- loong64
+
+- loongarch64 (Loongson old world)
+
+- sw64 (Sunway)
+
+- mips64
+
+## Build Limitation Description
+
+Cross-architecture cross-compilation is not supported: currently can only build packages for that architecture on machines of the corresponding architecture
+
+## Multi-Architecture Project Structure Recommendation
+
+It is recommended to use the following directory structure to manage multi-architecture builds:
+
+```txt
+project-root/
+├── arm64
+│   └── linglong.yaml # arm64 architecture configuration file
+├── linglong.yaml # x86_64 architecture configuration file
+├── loong64
+│   └── linglong.yaml # loong64 architecture configuration file
+├── resources # Shared resource files
+└── src # Shared source code
+```
+
+Place source code, resource files, etc. in the project root directory. The build for different architectures is determined by the configuration files for the respective architectures.
+
+## Build Command Examples
+
+ll-builder will prioritize finding the project configuration file for the current architecture. Therefore, executing ll-builder on machines of different architectures will automatically use the configuration file corresponding to the current architecture. If the architecture configuration file is not in the default location, you can use the following method to specify the configuration file location:
+
+```bash
+# Build arm64 architecture package
+ll-builder -f arm64/linglong.yaml
+
+# Build loong64 architecture package
+ll-builder -f loong64/linglong.yaml
+```
+
+Note that the project configuration file (the linglong.yaml file specified by -f) needs to be in the directory or subdirectory of the project directory (the current directory where ll-builder is run).
+
+## Loongson
+
+For differences between Loongson's old and new worlds, see [Are We Loong Yet](https://areweloongyet.com/docs/old-and-new-worlds/)
+
+> You can use the file tool to conveniently check which world a binary program belongs to. Suppose you want to check a file called someprogram, just execute file someprogram. If the output line contains these phrases:
+> interpreter /lib64/ld.so.1, for GNU/Linux 4.15.0
+> it indicates this is an old world program.
+> Accordingly, if the output line contains these phrases:
+> interpreter /lib64/ld-linux-loongarch-lp64d.so.1, for GNU/Linux 5.19.0
+
+Given that the differences between old and new worlds are quite significant, Linyaps divides old and new worlds into two architectures. The new world uses the more concise loong64 as the architecture code name.
+
+Considering that there are still some applications supporting Loongson on the market that have not been adapted to the new world, Linyaps has created old world bases (org.deepin.foundation/20.0.0) and runtime (org.deepin.Runtime/20.0.0.12) that can run on new world architectures to migrate applications supporting old world to new world.
+
+Migration steps:
+
+1. Prepare a new world architecture machine and install deepin or uos system.
+2. Install the `liblol-dkms` kernel module on the host machine: `apt install liblol-dkms`.
+3. Write a linglong.yaml file, fill in the base and runtime versions mentioned above.
+4. Extract the old world application software package in linglong.yaml and copy it to the `$PREFIX` directory.

docs/pages/en/guide/debug/debug.md

@@ -4,74 +4,173 @@ SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
 SPDX-License-Identifier: LGPL-3.0-or-later
 -->
 
-# Debug App
+# Debugging Linyaps Applications
 
-The following tutorial uses the [linglong-builder-demo](https://github.com/linuxdeepin/linglong-builder-demo) project mentioned in the "Building Tools" section as an example. We put the project in `/path/to/project`. Make sure to **replace the path** when referring to this tutorial.
+The following tutorial uses the org.deepin.demo project mentioned in the "Building Tools" section as an example.
 
-Since the linyaps application runs in a container, we need to use `gdbserver` to run the application in the container to debug it on the host. So you'll need to install `gdbserver` first.
+We place the project in `/tmp`. When following the tutorial, **pay attention to replace the paths**.
 
-We can use the `gdbserver` provided by the distribution, using `apt` as an example:
+## Debugging with gdb in Terminal
 
-```bash
-sudo apt install gdbserver gdb -y
+### Running Application in Debug Environment
+
+In the [Running Compiled Applications](../reference/commands/ll-builder/run.md) section, we already know that using `ll-builder run --exec /bin/bash` can run the compiled application and enter the container terminal. Simply add the `--debug` parameter after `run` to run the container in debug environment and enter it. The main differences between debug environment and non-debug environment are as follows:
+
+1. Debug environment uses binary+develop modules of base and runtime, while non-debug environment uses binary modules. The gdb tool is in the develop module of base.
+2. Debug environment uses binary+develop modules of app, while non-debug environment uses binary modules by default (debug symbols are usually saved to develop module).
+3. Debug environment generates linglong/gdbinit file in project directory and mounts it to ~/.gdbinit path in container.
+
+Please execute `ll-builder run --debug --exec /bin/bash` in project directory to enter debug environment container, then execute `gdb /opt/apps/org.deepin.demo/binary/demo` to start application debugging, which is no different from using command line debugging externally. This is thanks to the debugging linglong/gdbinit file providing initial configuration for `gdb`.
+
+### Debugging Application in Runtime Environment
+
+There are minor differences between debug environment and normal user runtime environment. If you need to debug application directly in runtime environment, you can use `ll-builder run --exec /bin/bash` to enter container, then execute `gdbserver 127.0.0.1:12345 /opt/apps/org.deepin.demo/bin/demo`. gdbserver will use tcp protocol to listen on port 12345 and wait for gdb connection.
+
+Open another host terminal, execute `gdb` in project directory, and input the following commands line by line:
+
+```txt
+set substitute-path /project /tmp/org.deepin.demo
+set debug-file-directory /tmp/org.deepin.demo/linglong/output/develop/files/lib/debug
+target remote 127.0.0.1:12345
 ```
 
 Next, refer to the tutorial in "Run compiled App", run `bash` in the container through the `ll-builder run` command, and run the application to be debugged through `gdbserver`:
 
-```bash
-ll-build run --exec /bin/bash
+_If runtime environment doesn't have gdbserver command, please check if application uses org.deepin.base as base and try upgrading to latest version of org.deepin.base._
 
-# In the container:
-gdbserver:10240 deepin-draw
+## Debugging with gdb in vscode
+
+First install C/C++ extension for vscode. Since vscode runs on host machine, it also needs to provide debugging for Linyaps container application through gdbserver. Similar to previous step, start gdbserver in runtime environment first, then configure launch.json file in vscode. Configuration is as follows:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "(gdb) linglong",
+      "type": "cppdbg",
+      "request": "launch",
+      "program": "${workspaceFolder}/linglong/output/binary/files/bin/demo",
+      "args": [],
+      "stopAtEntry": true,
+      "cwd": "${workspaceFolder}",
+      "MIMode": "gdb",
+      "miDebuggerServerAddress": "127.0.0.1:12345",
+      "setupCommands": [
+        {
+          "text": "set substitute-path /project ${workspaceFolder}"
+        },
+        {
+          "text": "set debug-file-directory ${workspaceFolder}/linglong/output/develop/files/lib/debug"
+        }
+      ]
+    }
+  ]
+}
 ```
 
-In the above command, `:10240` is any tcp port that is not currently occupied. Then we need to do two more things:
+Some configurations need to be changed according to actual project:
 
-1. Use `gdb` outside the container to connect to the `gdbserver` in the container;
-2. Set the source map path.
+- "program": "${workspaceFolder}/linglong/output/binary/files/bin/demo",
 
-## Debugging with gdb in terminal
+  This is the binary file passed to gdb, `demo` needs to be changed to actual binary filename of project
 
-1. Find the location of the executable file executed in the container on the host. For the above project, the file is located in `/path/to/project/.linglong-target/overlayfs/up/opt/apps/org.deepin. demo/files/bin/demo`.
+- "stopAtEntry": true
 
-   For applications installed via `ll-cli`, the executables are generally located under `$LINGLONG_ROOT/layers/[appid]/[version]/[arch]/files/bin`.
+  This requires gdb to automatically stop at main function, can be set to false if not needed
 
-   Use `gdb` to load the program outside the container:
+- "miDebuggerServerAddress": "127.0.0.1:12345"
 
-   ```bash
-   gdb /path/to/project/.linglong-target/overlayfs/up/opt/apps/org.deepin.demo/files/bin/demo
-   ```
+  This is the remote address for gdb connection, if port is not default 12345 when starting gdbserver, need to modify to actual port.
 
-2. Use the `target` command in `gdb` to connect to the `gdbserver` as follows:
+- "text": "set substitute-path /project ${workspaceFolder}"
 
-   ```bash
-   target remote :10240
-   ```
+  This sets source path substitution, `${workspaceFolder}` will be automatically replaced by vscode with current working directory, can be modified to actual path if needed.
 
-3. Enter the following command in `gdb` to set the path mapping and help `gdb` to find the corresponding source code, assuming the source code is placed in the `Desktop` of the host, the command is as follows:
+- "text": "set debug-file-directory ${workspaceFolder}/linglong/output/develop/files/lib/debug"
 
-   ```bash
-   set substitute-path /source /path/to/project
-   ```
+  This sets debug files directory, if debug symbols are not saved to `develop` module, need to modify to actual location.
 
-Then just use `gdb` normally.
+## Debugging with gdb in Qt Creator
 
-## QtCreator configuration
-
-Referring to the above process, we can easily complete the configuration of `QtCreator`:
-
-Click: Debug > Start Debugging > Connect to the Running Debug Server, and fill in the dialog box:
+Qt Creator also integrates gdb support. After starting Qt Creator, open menu bar `Debug` -> `Start Debugging` -> `Connect to Debug Server`, and fill in the dialog that pops up:
 
 ```text
-Server port: `10240`
+Server Port: `12345`
 
-Local executable file: `/path/to/project/.linglong-target/overlayfs/up/opt/apps/org.deepin.demo/files/bin/demo`
+Local Executable: `/tmp/org.deepin.demo/linglong/output/binary/files/bin/demo`
 
-Init Commands: `set substitute-path /source /path/to/project`
+Working Directory: `/tmp/org.deepin.demo`
+
+Init Commands: `set substitute-path /project /tmp/org.deepin.demo`
+
+Debug Information: `/tmp/org.deepin.demo/linglong/output/develop/files/lib/debug`
 ```
 
-The general configuration is shown in the following figure:
+Configuration is roughly as shown in figure:
 
-![qt-creator](images/qt-creator.jpg)
+![qt-creator](images/qt-creator.png)
 
-After the configuration is complete, you can use `QtCreator` to debug normally.
+After configuration, `QtCreator` can be used normally for debugging.
+
+## Saving Debug Symbols
+
+Linyaps automatically strips binary debug symbols after building applications and stores them in `$PREFIX/lib/debug` directory. However, some toolchains strip debug symbols during build process in advance, which causes Linyaps unable to find these symbols in binary files. If your project uses qmake, need to add following configuration in pro file:
+
+```bash
+# Linyaps sets -g option in CFLAGS and CXXFLAGS environment variables, qmake needs to inherit this environment variable
+QMAKE_CFLAGS += $$(CFLAGS)
+QMAKE_CXXFLAGS += $$(CXXFLAGS)
+# Use debug option to avoid qmake automatically stripping debug symbols
+CONFIG += debug
+```
+
+cmake automatically uses cflags and cxxflags environment variables, so no additional configuration is needed. Other build tools can refer to their documentation.
+
+## Downloading Debug Symbols from Debian Repository
+
+Since base images don't contain debug symbols, if you need to debug system dependency libraries of applications, you need to manually download debug symbol packages from corresponding Debian repository of base. Specific steps are as follows:
+
+1. Enter container command line environment using one of the following commands:
+
+   ```bash
+   ll-builder run --bash
+   # or
+   ll-cli run $appid --bash
+   ```
+
+2. Check repository address used by base image:
+
+   ```bash
+   cat /etc/apt/sources.list
+   ```
+
+3. Open repository address in host browser and locate directory where dependency library deb packages are located:
+   - Use command `apt-cache show <package-name> | grep Filename` to check deb package path in repository
+   - Complete download address is: repository address + deb package path
+
+   For example, to download debug symbols package for libgtk-3-0:
+
+   ```bash
+   apt-cache show libgtk-3-0 | grep Filename
+   # Output: pool/main/g/gtk+3.0/libgtk-3-0_3.24.41-1deepin3_amd64.deb
+   # Complete directory: <repo-url>/pool/main/g/gtk+3.0/
+   ```
+
+4. Look for corresponding debug symbol packages in that directory, usually has two naming formats:
+   - `<package-name>-dbgsym.deb`
+   - `<package-name>-dbg.deb`
+
+5. Download and extract debug symbol package:
+
+   ```bash
+   dpkg-deb -R <package-name>-dbgsym.deb /tmp/<package-name>
+   ```
+
+6. Configure debugger to find debug symbols:
+   When setting debug-file-directory in scenarios above, append extracted directory, separated by colon:
+   ```
+   ${workspaceFolder}/linglong/output/develop/files/lib/debug:/tmp/<package-name>/usr/lib/debug
+   ```
+
+This way debugger can find debug symbols of system dependency libraries in extracted directory.

docs/pages/en/guide/debug/faq.md

@@ -1,91 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Run FAQ
-
-1. When the application runs to read the application installation resource file under `/usr/share`, why does the reading fail?
-
-   linyaps applications run in a container, and the application data will be mounted to `/opt/apps/<appid>`/. Only system data will exist in the `/usr/share` directory, and there will be no application-related data. Therefore, reading directly from `/usr/share` will fail. Suggested processing: Use the `XDG_DATA_DIRS` environment variable to read resources, and `/opt/apps/<appid>/files/share` will exist in this environment variable search path.
-
-2. The font library file cannot be found when the application is running. Why can the corresponding font library be read when the `deb` package is installed?
-
-   When the `deb` package is installed, it will depend on the corresponding font library file. The linyaps package format adopts a self-sufficient packaging format. Except for the basic system library, `Qt` library and `DTK` library files provided in `runtime`, do not need to be provided by yourself, other dependent data files need to be provided by yourself. It is recommended to put the corresponding data file under `files/share`, and use the environment variable `XDG_DATA_DIRS` to read the path.
-
-3. What is in the linyaps application `runtime`? Can you add some library files to it?
-
-   At present, the `runtime` that linyaps application depends on provides the `Qt` library and the `DTK` library. Because `runtime` has a strict size limit, adding additional library files to `runtime` is currently not allowed.
-
-4. The application runs in the container. Can a configuration file be created in any path of the container during the running process?
-
-   You can create configuration files under `XDG_CONFIG_HOME`.
-
-5. Where is app data saved? Where can I find it outside the container?
-
-   Because linyaps applications follow the principle of non-interference, the `XDG_DATA_HOME`, `XDG_CONFIG_HOME`, `XDG_CACHE_HOME` environment variables are defined in the corresponding path of the host machine, `~/.linglong/<appid>`/. So the user application data will be saved under this path. When writing data while the application is running, it should also be able to read the corresponding environment variable to write the data. Prohibit reading and writing configurations of other applications.
-
-6. The application provides the `dbus service` file, where do I place it? What does the `Exec` field write?
-
-   When the application provides the `dbus service` file, it needs to be placed in the `entries/dbus-1/services` directory. If `Exec` executes the binary in the linyaps package, use the `--exec` option parameter to execute the corresponding binary.
-
-7. After the app is installed, the launcher cannot find it?
-
-   TryExec=xxx, if xxx does not exist in the $PATH, the application is considered non-existent and will not be displayed.
-
-8. Why is the Icon displayed as a small black dot?
-
-   The desktop file has an 'Icon' field written, but the Icon field name is incorrect or an absolute path is being used.
-
-9. Why is the Icon field as a gear?
-
-   The desktop file does not provide Icon field.
-
-10. Where are the icons stored?
-
-    svg → $PREFIX/share/icons/hicolor/scalable/apps/
-
-    Other formats are stored according to resolution, such as 16x16.
-
-    png/xpm → $PREFIX/share/icons/hicolor/16x16/apps/
-
-11. Why do `xdg-open` and `xdg-email` that come with the application fail?
-
-    linyaps specially handles `xdg-open` and `xdg-email` in `runtime`, so the application is forbidden to execute the executable file or script of `xdg-open` and `xdg-email` that it carries.
-
-12. Why doesn't the system environment variable used by the application take effect?
-
-    When using environment variables, you need to confirm whether there are corresponding environment variables in the container. If not, you need to contact the linyaps team for processing.
-
-13. The library files required for the application to run were not found. How can I provide them?
-
-    The resource files that the application needs to use and the library files both need to be provided by the application itself. The library files are placed in the `$PREFIX/lib` path.
-
-14. Why has the `Qt WebEngine` rendering process crashed when the application is running?
-
-    Due to the system upgrade of `glibc`, the application fails to use the built-in browser, and the application needs to be re-adapted. A temporary solution is to set the environment variable: `export QTWEBENGINE_DISABLE_SANDBOX=1`.
-
-15. When the application is running, the `libqxcb.so` library cannot be found or the `qtwebengine` error is reported. What can I do?
-
-    When a `qt.conf` file exists, you need to configure the correct path in the file or use the `QTWEBENGINEPROCESS_PATH`, `QTWEBENGINE_RESOURCES_PATH`, `QT_QPA_PLATFORM_PLUGIN_PATH`, and `QT_PLUGIN_PATH` environment variables to configure the search path.
-
-16. Can the application carry the database file by itself and write data to the database during operation?
-
-    The file system in the container is a read-only file system and does not allow data to be written to application resource files.
-
-17. Why does the execution of binary with `suid` and `guid` permissions fail?
-
-    In order to ensure system security, linyaps container prohibits the execution of such permission binaries in the container.
-
-18. Can the input method of uab offline package format not be used under Debian and Ubuntu?
-
-    It is recommended to install the `fcitx` input method to experience it.
-
-19. How can I know which packages are installed in a container environment?
-
-    Enter the container environment using the command `ll-builder run --exec bash`. To view the pre-installed packages, utilize the command `cat /var/lib/dpkg/status | grep "^Package: "`. Additionally, for libraries compiled from source code, you can inspect them using `cat /runtime/packages.list`.
-
-20. Why is the application tray not displayed after the application is launched?
-
-    This issue might be caused by applications registering to the system tray using the same service name. According to the KDE/freedesktop StatusNotifierItem specification, applications register with a service name in the format of org.kde.StatusNotifierItem-`<process id>`-`<instance number>`. In the case of the linyaps application, the PID during runtime is 19. You can check whether there's a registered service using the following command: `dbus-send --session --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.NameHasOwner string:org.kde.StatusNotifierItem-19-1` If the reply contains boolean true, it indicates that the service has been registered.

docs/pages/en/guide/debug/images/build_parameter_list.png.license

@@ -1,3 +0,0 @@
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later

docs/pages/en/guide/debug/images/node.png.license

@@ -1,3 +0,0 @@
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later

docs/pages/en/guide/debug/images/qt-creator.jpg.license

@@ -1,3 +0,0 @@
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later

docs/pages/en/guide/debug/ll-builder-faq.md

@@ -1,29 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Build FAQ
-
-1. `-lxxx` failed in `cmake` type build, but `ldconfig` and `pkg-config` can query the library information.
-
-   The link library path is not a regular path, the new path is `/runtime/lib`. Add the environment variable `LIBRARY_PATH=<libpath>`, which is included in the build environment by default.
-
-2. `link` static library failed when building, which requires re-building with `-fPIC`.
-
-   Use the `-fPIC` parameter when building a static library.
-
-3. Failed to start `box` during build, as shown below.
-
-   ![ll-box start failed](images/ll-box-start-failed.png)
-
-   The kernel does not support `unprivileged namespace`, please open `unprivileged namespace` to solve it.
-
-   ```bash
-   sudo sysctl -w kernel.unprivileged_userns_clone=1
-   ```
-
-4. The build of `qtbase` is successful, but the `qt` application cannot be built, which prompts `module`, `mkspec` related errors.
-
-   There is a problem in the lower version of `fuse-overlay mount`, which leads to the polluted file content when `qtbase commit`, and cannot be used. Use `fuse-overlayfs >= 1.8.2` version.

docs/pages/en/guide/debug/ll-pica-faq.md

@@ -1,20 +0,0 @@
-# FAQ
-
-1. Where is the default configuration located for the `linglong.yaml` file generated by `ll-pica`?
-
-   The configuration file for `ll-pica` is located at `~/.pica/config.json`.
-
-2. Does ll-pica fail to convert software such as Wine, Android apps, input methods, or security applications?
-
-   linyaps applications currently do not support this type of application, and consequently, ll-pica cannot convert them either.
-
-3. Why is there no sound from software that requires audio?
-
-   Prompt "libpulsecommon-12.2.so not found" can be addressed by adding a line in the `build` section of the linglong.yaml file: `mv $PREFIX/lib/$TRIPLET/pulseaudio/* $PREFIX/lib/$TRIPLET`.
-
-4. Why is the `command` field empty in the generated `linglong.yaml` file?
-
-   ll-pica retrieves the 'Exec' field from the desktop file within the deb package. If the command is empty, please verify if the desktop file path
-   within the deb package exists in the following locations.
-   - /opt/apps/$appid/entries/applications
-   - /usr/share/applications

docs/pages/en/guide/desktop-integration/README.md

@@ -0,0 +1 @@
+This directory contains documentation related to how Linyaps integrates with the desktop environment. (To be supplemented) - portals: Introduces how to create desktop portals for Linyaps to achieve seamless integration with the desktop environment.

docs/pages/en/guide/docs-index.md

@@ -0,0 +1,187 @@
+# Linyaps Documentation Index
+
+This document provides a comprehensive index of all documentation files in the Linyaps project.
+
+## Directory Structure Overview
+
+```
+docs/pages/en/guide/
+├── building/                    # Build-related documentation
+├── debug/                       # Debug-related documentation
+├── desktop-integration/         # Desktop integration documentation
+├── extra/                       # Additional documentation
+├── lessons/                     # Tutorials and examples
+├── linyaps-devel/               # Developer documentation
+├── publishing/                  # Publishing-related documentation
+├── reference/                   # Reference documentation
+├── start/                       # Getting started guide
+└── tips-and-faq/                # Tips and FAQ
+```
+
+## Detailed Documentation Index
+
+### Getting Started (start/)
+
+| Document Name                | File Path                       | Description                                                                                                          |
+| ---------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Overview                     | `start/whatis.md`               | Introduction to Linyaps basic concepts, advantages, and comparison with other package management tools               |
+| Install Linyaps              | `start/install.md`              | Detailed steps for installing Linyaps on different Linux distributions                                               |
+| Build Your First Linyaps App | `start/build_your_first_app.md` | Complete tutorial for building Linyaps packages from source, including calculator example and deb package conversion |
+| ll-pica Installation         | `start/ll-pica-install.md`      | Installation guide for ll-pica package conversion tool                                                               |
+| Release Notes                | `start/release_note.md`         | Version release notes and changelog                                                                                  |
+
+### Build Related (building/)
+
+| Document Name                         | File Path                          | Description                                                                                                                 |
+| ------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Linyaps Package Specification         | `building/linyaps_package_spec.md` | Detailed application packaging specifications, including naming conventions, build configuration, directory structure, etc. |
+| Build Configuration File Introduction | `building/manifests.md`            | Detailed explanation and field definitions for `linglong.yaml` configuration file                                           |
+| Module Management                     | `building/modules.md`              | Module splitting and management instructions                                                                                |
+| Multi-architecture Support            | `building/multiarch.md`            | Multi-architecture build support instructions                                                                               |
+| Demo Example                          | `building/demo.md`                 | Build demonstration example with practical use cases                                                                        |
+
+### Debug Related (debug/)
+
+| Document Name              | File Path        | Description                                                                                     |
+| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- |
+| Debug Linyaps Applications | `debug/debug.md` | Detailed guide for debugging Linyaps applications using gdb, vscode, Qt Creator and other tools |
+
+### Desktop Integration (desktop-integration/)
+
+| Document Name                    | File Path                       | Description                                                       |
+| -------------------------------- | ------------------------------- | ----------------------------------------------------------------- |
+| Desktop Integration Instructions | `desktop-integration/README.md` | Linyaps and desktop environment integration related documentation |
+
+### Tutorials and Examples (lessons/)
+
+| Document Name        | File Path                         | Description                                               |
+| -------------------- | --------------------------------- | --------------------------------------------------------- |
+| Basic Notes          | `lessons/basic-notes.md`          | Basic usage notes and best practices                      |
+| Build Git Patches    | `lessons/build-git-patch.md`      | Git patch building tutorial for version management        |
+| Build in Environment | `lessons/build-in-env.md`         | Tutorial for building in specific environments            |
+| Build Offline Source | `lessons/build-offline-src.md`    | Tutorial for building source code in offline environments |
+| Test with Toolchains | `lessons/test-with-toolchains.md` | Tutorial for testing with different toolchains            |
+
+### Developer Documentation (linyaps-devel/)
+
+| Document Name           | File Path                 | Description                                        |
+| ----------------------- | ------------------------- | -------------------------------------------------- |
+| Developer Documentation | `linyaps-devel/README.md` | Developer-related documentation and API references |
+
+### Publishing Related (publishing/)
+
+| Document Name         | File Path                    | Description                                                                      |
+| --------------------- | ---------------------------- | -------------------------------------------------------------------------------- |
+| Repository Management | `publishing/repositories.md` | Linyaps repository basic concepts, management and publishing update instructions |
+| UAB Format Publishing | `publishing/uab.md`          | UAB format publishing instructions and best practices                            |
+| Mirrors               | `publishing/mirrors.md`      | Mirror site configuration and management                                         |
+
+### Additional Documentation (extra/)
+
+| Document Name             | File Path                | Description                                       |
+| ------------------------- | ------------------------ | ------------------------------------------------- |
+| Unit Testing              | `extra/unit-testing.md`  | Unit testing documentation and testing frameworks |
+| Bundle Format             | `extra/bundle-format.md` | Bundle format documentation and specifications    |
+| System Helper             | `extra/system-helper.md` | System helper documentation and utilities         |
+| Application Configuration | `extra/app-conf.md`      | Application configuration documentation           |
+| Root Filesystem           | `extra/rootfs.md`        | Root filesystem documentation and management      |
+| Reference                 | `extra/ref.md`           | Reference documentation and quick lookup guides   |
+| UAB Build                 | `extra/uab-build.md`     | UAB build documentation and build process         |
+| README                    | `extra/README.md`        | Additional documentation overview                 |
+
+### Reference Documentation (reference/)
+
+#### Basic Concepts
+
+| Document Name               | File Path                     | Description                                                                 |
+| --------------------------- | ----------------------------- | --------------------------------------------------------------------------- |
+| Basic Concepts Introduction | `reference/basic-concepts.md` | Introduction to core concepts like Base, Runtime, sandbox, repository, etc. |
+| Runtime Component           | `reference/runtime.md`        | Detailed introduction to Runtime component                                  |
+| Driver                      | `reference/driver.md`         | Driver-related documentation and specifications                             |
+
+#### Command Reference
+
+**ll-appimage-convert Command**
+
+- `reference/commands/ll-appimage-convert/ll-appimage-convert.md` - Main command description
+- `reference/commands/ll-appimage-convert/ll-appimage-convert-convert.md` - convert subcommand
+
+**ll-builder Command**
+
+- `reference/commands/ll-builder/ll-builder.md` - Main command description
+- `reference/commands/ll-builder/build.md` - build subcommand
+- `reference/commands/ll-builder/create.md` - create subcommand
+- `reference/commands/ll-builder/export.md` - export subcommand
+- `reference/commands/ll-builder/extract.md` - extract subcommand
+- `reference/commands/ll-builder/import.md` - import subcommand
+- `reference/commands/ll-builder/list.md` - list subcommand
+- `reference/commands/ll-builder/push.md` - push subcommand
+- `reference/commands/ll-builder/remove.md` - remove subcommand
+- `reference/commands/ll-builder/repo.md` - repo subcommand
+- `reference/commands/ll-builder/run.md` - run subcommand
+
+**ll-cli Command**
+
+- `reference/commands/ll-cli/ll-cli.md` - Main command description
+- `reference/commands/ll-cli/content.md` - content subcommand
+- `reference/commands/ll-cli/enter.md` - enter subcommand
+- `reference/commands/ll-cli/info.md` - info subcommand
+- `reference/commands/ll-cli/install.md` - install subcommand
+- `reference/commands/ll-cli/kill.md` - kill subcommand
+- `reference/commands/ll-cli/list.md` - list subcommand
+- `reference/commands/ll-cli/prune.md` - prune subcommand
+- `reference/commands/ll-cli/ps.md` - ps subcommand
+- `reference/commands/ll-cli/repo.md` - repo subcommand
+- `reference/commands/ll-cli/run.md` - run subcommand
+- `reference/commands/ll-cli/search.md` - search subcommand
+- `reference/commands/ll-cli/uninstall.md` - uninstall subcommand
+- `reference/commands/ll-cli/upgrade.md` - upgrade subcommand
+
+**ll-pica Command**
+
+- `reference/commands/ll-pica/ll-pica.md` - Main command description
+- `reference/commands/ll-pica/install.md` - install subcommand
+- `reference/commands/ll-pica/ll-pica-adep.md` - adep subcommand
+- `reference/commands/ll-pica/ll-pica-convert.md` - convert subcommand
+- `reference/commands/ll-pica/ll-pica-init.md` - init subcommand
+
+**ll-pica-flatpak Command**
+
+- `reference/commands/ll-pica-flatpak/ll-pica-flatpak.md` - Main command description
+- `reference/commands/ll-pica-flatpak/ll-pica-flatpak-convert.md` - convert subcommand
+
+### Tips and FAQ (tips-and-faq/)
+
+| Document Name  | File Path                        | Description                                  |
+| -------------- | -------------------------------- | -------------------------------------------- |
+| Common Issues  | `tips-and-faq/faq.md`            | Common runtime issues and solutions          |
+| ll-builder FAQ | `tips-and-faq/ll-builder-faq.md` | Build tool common issues and troubleshooting |
+| ll-pica FAQ    | `tips-and-faq/ll-pica-faq.md`    | Package conversion tool common issues        |
+
+## Quick Navigation
+
+### Getting Started for New Users
+
+1. Read [`start/whatis.md`](start/whatis.md) to understand basic concepts
+2. Follow [`start/install.md`](start/install.md) to install Linyaps
+3. Follow [`start/build_your_first_app.md`](start/build_your_first_app.md) to build your first application
+
+### Developer Reference
+
+- Package Specification: [`building/linyaps_package_spec.md`](building/linyaps_package_spec.md)
+- Configuration File: [`building/manifests.md`](building/manifests.md)
+- Debug Guide: [`debug/debug.md`](debug/debug.md)
+
+### Command Reference
+
+- Build Tool: [`reference/commands/ll-builder/`](reference/commands/ll-builder/ll-builder.md) directory
+- CLI Tool: [`reference/commands/ll-cli/`](reference/commands/ll-cli/ll-cli.md) directory
+- Deb Package Conversion Tool: [`reference/commands/ll-pica/`](reference/commands/ll-pica/ll-pica.md) directory
+- AppImage Conversion Tool: [`reference/commands/ll-appimage-convert/`](reference/commands/ll-appimage-convert/ll-appimage-convert.md) directory
+- Flatpak Conversion Tool: [`reference/commands/ll-pica-flatpak/`](reference/commands/ll-pica-flatpak/ll-pica-flatpak.md) directory
+
+### Common Issues
+
+- Runtime Issues: [`tips-and-faq/faq.md`](tips-and-faq/faq.md)
+- Build Issues: [`tips-and-faq/ll-builder-faq.md`](tips-and-faq/ll-builder-faq.md)
+- Conversion Issues: [`tips-and-faq/ll-pica-faq.md`](tips-and-faq/ll-pica-faq.md)

docs/pages/en/guide/extra/README.md

@@ -0,0 +1,18 @@
+This directory contains additional documentation and advanced topics for Linyaps development.
+
+# Additional Documentation Topics
+
+## Available Documents
+
+- [Bundle Format](bundle-format.md): Detailed information about the Linyaps bundle format
+- [Unit Testing](unit-testing.md): Guidelines for writing unit tests in Linyaps projects
+- [Application Configuration](app-conf.md): Configuration options for Linyaps applications
+- [System Helper](system-helper.md): System helper utilities and integration
+- [Reference](ref.md): API reference and detailed specifications
+- [Root Filesystem](rootfs.md): Root filesystem management and customization
+
+## Development Notes
+
+This directory contains comprehensive documentation for advanced users and developers who need detailed information about specific aspects of the Linyaps platform. Each document provides in-depth coverage of its respective topic.
+
+For basic getting started information, please refer to the main documentation in the parent directory.

docs/pages/en/guide/extra/app-conf.md

@@ -0,0 +1,51 @@
+# Application Runtime Configuration
+
+Application runtime configuration is the file that describes how the Linyaps runtime module loads the application. The configuration is machine-specific, and the user can set mount paths and permission control files for the application.
+
+## File Format
+
+Must be a YAML file.
+
+## Storage Location
+
+The configuration is highly user-specific and should be stored at `~/.linglong/{appid}/app.yaml`
+
+If it doesn't exist, it should be created first from `info.json`.
+
+## Content
+
+```yaml
+# Should be 1.0 now
+version: 1.0
+
+package:
+  ref: com.qq.weixin.deepin/3.2.1.154deepin8/x86_64
+
+runtime:
+  ref: org.deepin.Runtime/20/x86_64
+
+# The section can only be set by developers and only works when debug is enabled
+debug:
+  # Override entrypoint
+  args:
+    - /opt/apps/com.qq.weixin.work.deepin/files/run.sh
+    - --debug
+  # Override the base, carefully set the debug args
+  mount-bottom:
+    - /usr:/usr
+
+permissions:
+  # Mount after all runtime container builds
+  mounts:
+    - /etc/passwd:/etc/passwd
+    - /etc/group:/etc/group
+    - ${HOME}/Documents:${HOME}/Documents
+    - ${HOME}/Desktop:${HOME}/Desktop
+    - ${HOME}/Downloads:${HOME}/Downloads
+  # TODO: session and system bus
+  dbus:
+    owner:
+      - com.qq.weixin.work.deepin
+    talk:
+      - org.freedesktop.Notifications
+```

docs/pages/en/guide/extra/bundle-format.md

@@ -0,0 +1,51 @@
+# Bundle Format
+
+## Introduction
+
+Green software refers to binaries that do not install any files to the system.
+
+The fundamental constraints of green software are:
+
+- **Path independence**: Has nothing to do with local files.
+- **High compatibility**: The software should contain all dependencies that the system does not have.
+
+The well-known technology for building green software is AppImage on Linux.
+
+However, there are many problems with this technology. The biggest issue is that the host system ABI cannot remain stable and differs from one another. Linyaps cannot solve this problem either. We should maintain a baseline of supported systems or ABI.
+
+A strategy used on UnionTech OS or Deepin is to only support systems after UnionTech OS 1020, which reduces testing work for different base systems.
+
+## Target
+
+The green bundle is not just simple support for application runtime path independence. It is also designed to be the offline maintenance package format on the office system, supporting self-run and installation while maintaining the changeability of the bundle format when designing.
+
+When a user has internet access, we mostly use online differential updates or installation via repo. We do not use bundles if we can access the repo when distributing applications.
+
+## Specification
+
+The specifications for export bundles:
+
+- **MUST** be an ELF, can be FlatELF
+- **MUST** be statically-linked
+- **MUST** contain a data segment that can be mounted with FUSE
+- **MUST** contain a loader executable at the root of the FUSE mount filesystem
+
+## Implementation
+
+**The implementation changes over time. If you change the implementation, update this section as soon as possible !!!**
+
+### Prototype
+
+- The bundle is a simple ELF loader that combines a readonly filesystem with cat.
+- The loader simply calls read_elf64 to calculate the offset of the readonly filesystem.
+- The loader mounts the readonly filesystem with `squashfuse -o ro,offset=xxx`
+- The filesystem is now a readonly filesystem
+  - The root of the filesystem should contain a file named loader (currently .loader)
+  - The directory structure should be: `/{id}/{version}/{arch}/`
+- The readonly filesystem should support EROFS, and MAY support SquashFS
+
+A full example of the filesystem is:
+
+```bash
+
+```

docs/pages/en/guide/extra/ref.md

@@ -0,0 +1,89 @@
+# Reference (Ref)
+
+## Definition
+
+Component: A component is generally equivalent to artifacts/component/module/package in other systems. In Linyaps, we use "layer" to represent a component.
+
+## Format
+
+Ref is the unique identifier of a component in the storage repository (index information in the storage repository). A complete ref includes repository name, channel, ID, version number, architecture, branch name and other information.
+
+The ref format is as follows:
+
+```bash
+${repo}/${channel}:${id}/${version}/${arch}
+```
+
+Examples:
+
+```bash
+deepin/main:org.deepin.runtime/20/x86_64
+
+deepin/project1:org.deepin.calculator/1.2.2/x86_64
+```
+
+Where:
+
+- `deepin` is the name of the remote repository to which the software package belongs
+- `main` and `project1` are distribution channels, which can be empty by default
+- `org.deepin.calculator` is the ID
+- `1.2.2` is the version
+- `x86_64` is the architecture
+
+### Value Range
+
+| Field   | Allowed Values                                                                                                  |
+| ------- | --------------------------------------------------------------------------------------------------------------- |
+| repo    | Lowercase letters + underscore                                                                                  |
+| channel | Lowercase letters + underscore                                                                                  |
+| id      | Reverse domain name                                                                                             |
+| version | 4 digits separated by `.`. Pad with 0 if less than 4 digits, append subsequent numeric strings to the 4th digit |
+| arch    | Architecture description string, currently supports x86_64/arm/loongarch                                        |
+
+## Usage
+
+Ref contains two parts: remote address identifier and local identifier. The `:` separates the remote identifier from the local identifier.
+
+The remote identifier is mainly used to define how this layer is obtained. The channel is not currently used and can be empty. The repo represents an alias for the mapping of the remote repository (URL) locally.
+
+During installation, using a complete ref can uniquely identify a layer. For example:
+
+```bash
+ll-cli install deepin/main:org.deepin.calculator/1.2.2/x86_64
+```
+
+Once a layer is installed, all local operations on the layer will not change its remote properties, especially during upgrades.
+
+```bash
+# Upgrade org.deepin.calculator from deepin/main, its version will change, but repo and channel will not
+# Note: install will update the package here
+ll-cli install org.deepin.calculator/1.2.2/x86_64
+
+# This will use the layer from deepin/project channel to replace the local org.deepin.calculator/1.2.2/x86_64
+ll-cli install deepin/project:org.deepin.calculator/1.2.2/x86_64
+```
+
+Notes:
+
+- When switching repo or channel, local versions need to be deleted, especially when there are multiple versions under an ID (the underlying layer can be considered for reuse, but logically ensure that layer versions are under the corresponding channel).
+
+### Shorthand
+
+Ref supports shorthand with the following main rules:
+
+1. Default repo is `deepin`
+2. Default channel is `main` (currently not implemented, temporarily not considered)
+3. Default version is the remote latest version or local latest version, inferred according to the scenario, error if ambiguous
+4. Default architecture is the current ll-cli runtime architecture
+
+If any field in ref is explicitly specified, it takes precedence based on that field.
+
+## Implementation
+
+Currently, the layers storage path is:
+
+```bash
+/deepin/linglong/layers
+```
+
+This path will definitely be replaced later, so please avoid hardcoding this field in too many places.

docs/pages/en/guide/extra/rootfs.md

@@ -1,8 +1,8 @@
-# Rootfs
+# Root Filesystem (Rootfs)
 
-As per the OCI runtime specification, the runtime starts from a rootfs. However, in Linglong, it prepares the rootfs in ll-box. Therefore, we put the information for constructing the rootfs in annotations to ll-box.
+As per the OCI runtime specification, the runtime starts from a rootfs, but in Linyaps, it prepares rootfs in ll-box. Therefore, we put the information for constructing rootfs in annotations to ll-box.
 
-An example of annotations is:
+The example of annotations is:
 
 ```json
   "annotations": {
@@ -77,6 +77,6 @@ An example of annotations is:
   }
 ```
 
-The ll-box supports two methods to build rootfs: using native read-only bind mount or with overlayfs.
+The ll-box supports two methods to build rootfs: using native read-only bind mounts or with overlayfs.
 
 `container_root_path` is the working directory of ll-box.

docs/pages/en/guide/extra/system-helper.md

@@ -0,0 +1,17 @@
+# System Helper
+
+Users without privileges can mount erofs filesystems to directories using the following D-Bus call:
+
+```bash
+busctl --system call org.deepin.linglong.SystemHelper \
+    /org/deepin/linglong/FilesystemHelper \
+    org.deepin.linglong.FilesystemHelper \
+    Mount \
+    sssa{sv} \
+    '/var/lib/linglong/vfs/blobs/6f6b34b09e8a72ec52013407289064f5' \
+    '/run/user/1000/linglong/vfs/layers/com.qq.music/1.1.3/x86_64/' \
+    'erofs' \
+    0
+```
+
+This command uses the SystemHelper D-Bus interface to mount an erofs filesystem without requiring elevated privileges.

docs/pages/en/guide/extra/uab-build.md

@@ -0,0 +1,19 @@
+# uab Build
+
+Creating a runnable uab file from a Linyaps-oriented project requires the following configuration files:
+
+1. **linglong.yaml**: The Linyaps project configuration file that determines how the package will be compiled and installed;
+2. **loader**: An executable file that serves as the entry point for the uab.
+3. **extra-files.txt**: A text file that specifies which files the application depends on from base and runtime. These files will be copied to the uab package and placed in their corresponding locations during application runtime. If the application can run without depending on other files from runtime and base, this file can be omitted.
+
+If you only want to export the project as a uab for submitting applications to the Linyaps store and don't need it to be runnable, you don't need to provide the loader and extra-files.txt.
+
+Example loader code:
+
+```bash
+#!/bin/env sh
+APPID=org.deepin.demo
+./ll-box $APPID $PWD /opt/apps/$APPID/files/bin/demo
+```
+
+The last parameter passed to ll-box is the binary that needs to run in the container.

docs/pages/en/guide/extra/unit-testing.md

@@ -0,0 +1,11 @@
+# Unit Testing
+
+Linyaps utilizes GoogleTest (gtest) as its unit testing framework. Simply include your test code and test data in the `test/` directory at the project root.
+
+Since certain tests are challenging to execute in CI environments, they are disabled by default.
+
+The following environment variables control test execution. All are empty by default:
+
+| Variable Name     | Value                           | Description                     |
+| ----------------- | ------------------------------- | ------------------------------- |
+| LINGLONG_TEST_ALL | If set, enables all unit tests | Executes complete unit test suite |

docs/pages/en/guide/lessons/basic-notes.md

@@ -0,0 +1,265 @@
+# Basic Knowledge of Linyaps Application Build Projects
+
+Before officially starting to build a Linyaps application project, we need to have a certain understanding of the basic knowledge regarding Linyaps application building. This will help us better decide what materials to prepare and what types of operations to perform before starting the build project.
+
+## Basic Steps for Linyaps Application Building
+
+Before officially starting to build a Linyaps application project, we need to understand the basic steps a Linyaps application goes through from resource input (source code, binary files, etc.) to application package export. This helps us determine what necessary files we need to prepare:
+
+1. Obtain build target source files (open source project source code, application binary files, etc.)
+2. Determine the Linyaps application build type based on source files and select the appropriate build solution
+3. Prepare a Linyaps build environment that meets requirements
+4. Customize the build configuration file `linglong.yaml` according to the build type and source code content
+5. Prepare general resources used by the application, including icons and other non-binary resources
+
+## Materials Required for Linyaps Application Build Projects
+
+Based on the above knowledge, we can understand that throughout the entire Linyaps application build process, the following files are mainly involved:
+
+1. Linyaps application build project configuration file `linglong.yaml`
+2. Application source code/binary files and other resources to be packaged
+3. General non-binary files and other resources
+
+## Mainstream Standards Followed by Linyaps Applications
+
+In order to ensure complete functionality and good experience, every Linux desktop software package management solution needs to comply with various specifications proposed by the package management solution. This maximizes the functionality of the package management solution and ensures the application ecosystem experience.
+
+Linyaps is not always unique and needs to meet certain specifications to ensure the steady and continuous development of the Linyaps ecosystem.
+
+Currently, the Linyaps solution complies with the following mainstream standards:
+
+1. Freedesktop XDG specification
+2. Linyaps application directory structure specification
+3. Linyaps application build project configuration file `linglong.yaml` specification
+
+### Freedesktop XDG Specification
+
+1. The Linyaps application solution follows the Freedesktop XDG specification. A normal graphical application should have icon files and desktop files that comply with the Freedesktop XDG specification.
+2. Linyaps application icon files should be categorized into different sizes under the `$PREFIX/share/icons/hicolor/` directory
+3. Linyaps applications use environment variables like `XDG_DATA_DIRS` in containers to support reading and writing user directories in the host machine
+
+### Linyaps Application Directory Structure Specification
+
+1. Linyaps applications follow the $PREFIX path rule. This variable is automatically generated, and all application-related files need to be stored under this directory. Under this directory level, there are directories like `bin` and `share`.
+
+2. Applications in Linyaps containers will not be allowed to read binary files and runtime libraries in the host machine's system directories
+
+3. During the build process, the build project directory will be mapped to the Linyaps container and mounted as `/project`
+
+4. The directories where runtime libraries and header files are located in Linyaps application containers will vary depending on the runtime environment type:
+   - foundation type: Mapped as normal system paths `/usr/bin` `/usr/include` etc. in Linyaps containers, serving as the basic runtime system environment
+   - runtime type: Mapped as runtime container paths `/runtime/usr/bin` `/runtime/usr/include` etc. in Linyaps containers, serving as the basic runtime system environment
+
+\*By default, the environment variables inside the Linyaps container have been automatically processed for path recognition, such as:
+
+```
+PATH=szbt@szbt-linyaps23:/project$ echo $PATH
+/bin:/usr/bin:/runtime/bin:/opt/apps/com.tencent.wechat/files/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games:/sbin:/usr/sbin
+```
+
+General expression is:
+
+```
+PATH=szbt@szbt-linyaps23:/project$ echo $PATH
+/bin:/usr/bin:/runtime/bin:$PREFIX/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games:/sbin:/usr/sbin
+```
+
+## Specifications for General Resources in Linyaps Application Build Projects
+
+In Linyaps application build projects, different resource files need to comply with relevant specifications to ensure that the build and experience meet requirements
+
+### Icons Directory Specification
+
+According to the `Freedesktop XDG specification` and `Linyaps application directory structure specification` followed by Linyaps, icons are placed in corresponding directories according to different sizes
+
+Mainstream non-vector icon sizes are: `16x16` `24x24` `32x32` `48x48` `128x128` `256x256` `512x512`
+To ensure icons can achieve better experience effects in the system, at least one non-vector icon file with a size not smaller than `128x128` is required. Vector icons do not have this restriction.
+
+Therefore, in a Linyaps application installation directory, the icons directory should be as shown in the following 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 to place `vector icon` files, generally in `.svg` format
+
+Assuming your Linyaps application provides both a non-vector icon file `linyaps-app-demo.png` with size `128x128` and a vector icon file `linyaps-app-demo.svg` with size `128x128`, they should appear in the following state in the Linyaps container:
+
+```
+$PREFIX/share/icons/hicolor/128x128/apps/linyaps-app-demo.png
+$PREFIX/share/icons/hicolor/scalable/apps/linyaps-app-demo.svg
+```
+
+\* To avoid icon conflicts being overwritten, please use the application's `unique English name` or `Linyaps application ID` for the icon file name
+
+### Desktop File Specification
+
+Linyaps applications are compatible with most `desktop startup files` that comply with the `Freedesktop XDG specification`. The following fields need special attention:
+
+| Field | Value Requirements                                                                                                                                                                                                           |
+| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Exec  | This value is used to set the command executed when clicking this desktop file. It needs to be consistent with the `command` value in `linglong.yaml`                                                                        |
+| Icon  | This value is used to set the application icon displayed by this desktop file. It needs to be consistent with the icon file name in the `Icons Directory Specification`. This value does not require the file name extension |
+
+Therefore, a desktop file that complies with Linyaps application specifications can refer to:
+
+```
+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 Build Project `linglong.yaml` Specification
+
+Like other traditional package management suites, manually creating a Linyaps application build project requires setting up a build rule file `linglong.yaml`. In the build rules, it is divided into `global fields` and `custom fields` according to usage. \* In the case, all space symbols and placeholders in the `linglong.yaml` body are valid characters. Please do not delete or change the format
+
+### Global Field Specification
+
+In `linglong.yaml`, fields that are not affected by the build type are called `global fields`. The following are the main reference specifications:
+
+1. A `linglong.yaml` that can normally start a build project should contain the following key parts:
+   | Module | Explanation |
+   |--------|-------------|
+   | version | Build project version number |
+   | package | Basic information of Linyaps application |
+   | base | Linyaps application container base environment and version setting. The base environment contains some basic runtime libraries |
+   | runtime | Linyaps application runtime library `runtime` and version setting. This module can be deleted when the basic runtime libraries in `base` meet the program runtime requirements |
+   | command | Command executed when Linyaps application container starts. It is consistent with the `Exec` field content of the `desktop` file |
+   | sources | Source file type of Linyaps application build project |
+   | build | Build rules to be executed by Linyaps application build project |
+
+The `package` module contains several sub-modules:
+| Sub-module | Explanation |
+|-------------|-------------|
+| id | Linyaps application ID/package name |
+| name | Linyaps application name, use English name |
+| version | Linyaps application version number |
+| kind | Linyaps application type, default is `app` |
+| description | Linyaps application description |
+
+2. Linyaps applications follow the $PREFIX path rule. This variable is automatically generated, and all application-related files need to be stored under this directory. If installation file operations are needed in the build rules, they all need to be installed to the $PREFIX path. \* The $PREFIX variable name is the actual content filled in. **Please do not use `absolute path` or any content with absolute value effect as a substitute**
+
+3. Linyaps applications currently follow the `four-digit` version number naming rule. Applications that do not comply with the rule cannot start the build project
+
+4. `base` and `runtime` versions support automatic matching of the latest version `tail number`. The version number can only fill in the `first three digits` of the version number. For example:
+   When base `org.deepin.foundation` provides both `23.0.0.28` and `23.0.0.29`, if only the following is filled in `linglong.yaml`:
+
+```
+base: org.deepin.foundation/23.0.0
+```
+
+Then when starting the Linyaps application build project, it will default to using the highest version number `23.0.0.29`
+
+5. The Linyaps application build project configuration file is currently not directly compatible with configuration files of other package build tools. It needs to be adapted and modified according to build project configuration file cases:
+   https://linglong.dev/guide/ll-builder/manifests.html
+
+### Custom Fields
+
+According to the Linyaps application build project source file type, Linyaps application build projects can be divided into `local file builds` and `git source repository pull builds`. Different types require filling in different `linglong.yaml` content.
+The Linyaps application build project source file type `sources` mainly supports these types: `git` `local` `file` `archive`
+Complete description reference: [Build Configuration File Introduction](https://linyaps.org.cn/guide/ll-builder/manifests.html)
+
+#### Git Pull Source Code Compilation Mode
+
+When the Linyaps application build project needs to pull open source project repository resources to local for building through git, the `sources` source file type `kind` should be set to `git` and fill in the `linglong.yaml` according to requirements.
+At this time, you need to write the `sources` and `build` modules according to specifications.
+
+1. `sources` Example:
+
+```yaml
+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     | Source code repository address that needs to be pulled through git. The repository needs to support git functionality. When the network condition is poor, mirror addresses can be used as alternatives                                                                                                              |
+| version | Specify the version number of the source code repository, i.e., `tag label`, or pull the main line `master`                                                                                                                                                                                                          |
+| commit  | Pull source code based on the `commit` change history of the repository. Fill in the value corresponding to the commit here, which will apply all changes up to this commit in the repository. \*This field has higher priority than `version`. Please do not fill in any `commit` after the merge time of `version` |
+
+\* Supports adding multiple git repositories as `sources` pulls simultaneously
+
+2. `build` Example:
+
+```yaml
+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 module is the main body of build rules, and the path follows the `Linyaps Application Directory Structure Specification`
+After `sources` is pulled to local, the repository files will be stored in the `/project/linglong/sources` directory. At this time, different repository directories are named with `xxx.git`
+Supports using the `git patch` function to conveniently maintain the source code
+
+#### Local Resource Operation Mode
+
+When the Linyaps application build project needs to operate on files in the build directory, the `kind` should be set to `local` type and fill in the `linglong.yaml` according to requirements.
+At this time, you need to write the `sources` and `build` modules according to specifications.
+
+1. `sources` Example:
+
+```yaml
+sources:
+source:
+  - kind: local
+    name: "qBittorrent"
+```
+
+| Name | Description                                    |
+| ---- | ---------------------------------------------- |
+| kind | Source file type                               |
+| name | Source file name identifier, has no actual use |
+
+\* When the `kind` is set to `local` type, the build project will not perform any operations on source files
+
+2. `build` Example:
+
+```yaml
+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 module is the main body of build rules, and the path follows the `Linyaps Application Directory Structure Specification`
+At this time, the `build` rules support multiple writing methods to simulate manual operations. \* You need to ensure that all steps of this build rule can be executed normally, otherwise the current build task will be interrupted
+
+#### Container Internal Manual Operation Mode
+
+If you plan to directly enter the Linyaps container for manual operations instead of through the build rule file `linglong.yaml`, you should refer to the `Local Resource Operation Mode` to fill in the `linglong.yaml`.
+
+1. The `sources` part is written consistently with the `Local Resource Operation Mode`
+2. Since manual operations are used, complete and executable `build` rules are not required. At this time, `linglong.yaml` is used to generate a container that meets the description rather than executing all tasks. For specific operations, please refer to subsequent courses about container internal build file cases

docs/pages/en/guide/lessons/build-git-patch.md

@@ -0,0 +1,177 @@
+# Adapting Qt5-Based Open Source Application -- qBittorrent to Support Automated Linyaps Application Build Projects
+
+Continuing from the previous chapter, we will explore how to adapt the `linglong.yaml` to support automated build versions.
+Since we have already determined the build rules that can successfully complete the compilation and build tasks in the previous section, this section mainly discusses how to use the `git` function to complete the following automated operations:
+
+1. Automatically pull open source project git repository resources
+2. Automatically apply custom patch content
+
+## Modifying `linglong.yaml`
+
+In the previous section, we obtained a `linglong.yaml` that can successfully compile local source code. Since it's the same application project, we can directly modify it based on the existing configuration.
+
+For `linglong.yaml`, the two core parts are mainly the `sources` and `build` modules. This time we will explain these two parts separately.
+
+### `sources` Module
+
+According to the [Linyaps Application Build Project `linglong.yaml` Specification], when the build project's source files are git repositories (i.e., pulling source code repositories through git clone), the source file type `kind` of `sources` should be set to `git` and fill in the relevant information of the repository.
+
+According to the [Linyaps Application Build Project `linglong.yaml` Specification] `Git Pull Source Code Compilation Mode` specification, we need to master the following information about the source code repository:
+
+1. url, which is the address used for git clone, can use mirror addresses like ordinary git clone
+2. version, which is the specific version number of the repository that needs to be fetched, generally the `Tags` label
+3. The repository commit number that needs to be applied. Fill in the value corresponding to the commit here, which will apply all changes up to this commit in the repository. This field has higher priority than `version`. Please do not fill in any `commit` after the merge time of `version`
+
+Combined with the compilation notes in the second section, we collected information about the `qBittorrent.git` and `libtorrent.git` repositories. To reduce build progress blocking caused by network issues, I chose to use mirror addresses here:
+
+```yaml
+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
+```
+
+![commit-1](images/4-commit-1.png)
+
+![commit-2](images/4-commit-2.png)
+
+As can be seen from the figures, the filled commit values all match the commits when the corresponding tags were generated.
+
+### `build` Module
+
+After completing the source file information settings, we start modifying the build rules.
+Considering that we have obtained executable build rules in the previous lesson, we only need to modify the source code path according to the relevant specifications in the [Linyaps Application Build Project `linglong.yaml` Specification] `Git Pull Source Code Compilation Mode`.
+
+After completing the modifications, we will get the following build rules:
+
+```yaml
+build: |
+  mkdir -p ${PREFIX}/bin/ ${PREFIX}/share/
+  ##Build 3rd libs
+  mkdir /project/linglong/sources/libtorrent.git/build
+  cd /project/linglong/sources/libtorrent.git/build
+  cmake -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=$PREFIX ..
+  make -j$(nproc)
+  make install
+
+  ##Build main
+  mkdir /project/linglong/sources/qBittorrent.git/build
+  cd /project/linglong/sources/qBittorrent.git/build
+  cmake -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=$PREFIX ..
+  make -j$(nproc)
+  make install
+
+  ##Extract common res
+  cp -rf /project/template_app/* ${PREFIX}/share/
+```
+
+### Custom Patch Application
+
+In this case, we also introduce a new scenario: after pulling open source project repository resources of a specific version number, we need to modify the source code to achieve patch effects for fixing vulnerabilities and bugs.
+
+For this, we need to learn new knowledge: `git patch` related content. The git program has a built-in patch management system that needs to conveniently use this function to revise the source code. Generally, there are the following steps:
+
+1. Pull the open source project repository resources to the local directory through `git clone`
+2. Manually modify based on the pulled resources. At this time, you can compare the differences and changes with the initial state through the `git diff` function. This forms the content of the patch. The specific patch division can vary according to the maintainer
+3. After generating the patch document, pull the same open source project repository again. At this time, apply this patch through `git apply` to achieve automatic revision based on change records, and also facilitate recording source code maintenance records
+
+For example, after pulling the `qBittorrent--4.6.7` repository in this case, I need to add a merge related to security vulnerabilities:
+https://github.com/qbittorrent/qBittorrent/pull/21364
+![commit-3](images/4-commit-3.png)
+
+It should be noted that this submission is based on the `qBittorrent--5.x` version, which means that if I want to fix this vulnerability on `qBittorrent--4.6.7`, I need to manually modify the source code.
+Considering that the main version number of this application maintained in the short term will not be iterated to `5.x`, and with the possibility of other security vulnerabilities occurring and reducing the labor cost of repeatedly modifying the source code, I adopted the method of adding patches to assist me in modifying the source code.
+
+The following shows my process of obtaining & applying patches:
+
+1. First, I pulled the `qBittorrent--4.6.7` repository in `sources` to the local directory through `git clone`
+2. Enter the pulled directory and check whether the current directory is a valid git directory through the git program:
+
+```zsh
+❯ git remote -v
+origin  https://ghp.ci/https://github.com/qbittorrent/qBittorrent.git (fetch)
+origin  https://ghp.ci/https://github.com/qbittorrent/qBittorrent.git (push)
+```
+
+As can be seen, after executing the command, information about the remote repository can be returned, indicating that this directory meets the requirements.
+
+3. Then, manually modify the source code according to the file changes when the above security vulnerability was submitted. \* Here, the maintainer needs to judge which specific submissions need to be merged based on experience
+
+4. After the modification is completed, return to the root directory of the source code and execute `git diff` to view the existing difference comparison:
+
+5. After confirmation, save this difference locally to form a patch file
+
+```bash
+ziggy@linyaps23:/media/szbt/Data/ll-build/QT/qBittorrent-local$ git diff > ./
+```
+
+6. After obtaining the patch file, we will add the content of the applied patch to the existing `build` build rules:
+
+```yaml
+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
+
+  ##Build 3rd libs
+  mkdir /project/linglong/sources/libtorrent.git/build
+  cd /project/linglong/sources/libtorrent.git/build
+  cmake -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=$PREFIX ..
+  make -j$(nproc)
+  make install
+
+  ##Build main
+  mkdir /project/linglong/sources/qBittorrent.git/build
+  cd /project/linglong/sources/qBittorrent.git/build
+  cmake -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=$PREFIX ..
+  make -j$(nproc)
+  make install
+
+  ##Extract common res
+  cp -rf /project/template_app/* ${PREFIX}/share/
+```
+
+7. At this point, we can return to the build directory and start the build test. Execute:
+
+```bash
+ziggy@linyaps23:/media/szbt/Data/ll-build/QT/qBittorrent-local$ ll-builder build -v
+```
+
+This build ended quickly and successfully. We execute the following command to export the container as a Linyaps application installation package `binary.layer`:
+
+```bash
+ziggy@linyaps23:/media/szbt/Data/ll-build/QT/qBittorrent-local$ ll-builder export --layer
+```
+
+## Local Build Result Testing
+
+After obtaining the Linyaps application installation package, I tried to experience it on different mainstream distributions that support the Linyaps environment to confirm whether the binary programs built through Linyaps containers have universality.
+
+### deepin 23
+
+![deepin 23](images/4-test-1.png)
+
+### openKylin 2.0
+
+![openKylin 2.0](images/4-test-2.png)
+
+### Ubuntu 2404
+
+![Ubuntu 2404](images/4-test-3.png)
+
+### OpenEuler 2403
+
+![OpenEuler 2403](images/4-test-4.png)
+
+So far, it is sufficient to prove that `Qt5-based open source application--qBittorrent` can achieve one-stop pulling of project source code and compilation into executable binary files after adding custom patches and modifying build rules, and can also be used on other distributions!

docs/pages/en/guide/lessons/build-in-env.md

@@ -0,0 +1,139 @@
+# Compiling Qt5-Based Open Source Application -- qBittorrent in Linyaps Container
+
+After learning the `Basic Knowledge of Linyaps Application Build Projects` in the previous chapter, we are about to enter the practical classroom and use the knowledge we have learned to officially build a Linyaps application.
+
+Today, we will demonstrate how to enter the Linyaps container and compile the source code of an open source graphical application `qBittorrent` into binary files and test its operation.
+
+## Preliminary Preparation
+
+According to the requirements in `Basic Knowledge of Linyaps Application Build Projects` for the `Specifications for General Resources in Linyaps Application Build Projects`, we should provide both `icons` icon files and `desktop` startup files for graphical applications to ensure desktop user experience.
+
+However, this practical classroom will only perform compilation and testing operations in the Linyaps container, so general resources do not need to be prepared temporarily.
+
+This sharing is based on the `deepin 23` distribution, so before performing any of the following steps, you need to prepare a `deepin 23` system environment that can build Linyaps applications:
+
+1. Ensure that the `ll-builder` build suite has been installed in the environment. For installation methods on different distributions, please refer to: [Install Linyaps](https://linyaps.org.cn/guide/start/install.html)
+
+2. Since we need to connect to the network to obtain the runtime libraries of the Linyaps container and possibly needed third-party libraries during the build process, we need to ensure smooth network connection throughout the entire operation process
+
+3. Before compiling through the Linyaps container, you had better successfully compiled `qBittorrent` in `deepin 23` which is relatively close to this build container to ensure you have some understanding of the source code compilation
+
+4. Combine the [Linyaps Application Build Project `linglong.yaml` Specification] in the previous section and simply write a Linyaps build project configuration file `linglong.yaml` according to the following template to generate a container that meets the requirements
+
+The main points to note are: \* Since this operation directly enters the container for operation, the build rules in the `build` part do not need to be written in detail \* Since this compilation operation is involved, in order to include the required runtime libraries to the greatest extent, we add the `runtime` section. For specific writing specifications, please refer to [Basic Knowledge of Linyaps Application Build Projects]
+
+```yaml
+# SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+version: "4.6.7.2"
+
+package:
+  id: org.qbittorrent.qBittorrent
+  name: "qBittorrent"
+  version: 4.6.7.2
+  kind: app
+  description: |
+    qBittorrent binary
+
+base: org.deepin.foundation/23.0.0
+runtime: org.deepin.Runtime/23.0.1
+
+command:
+  - /opt/apps/org.qbittorrent.qBittorrent/files/bin/qbittorrent
+
+source:
+  - kind: local
+    name: "qBittorrent"
+
+build: |
+  mkdir -p ${PREFIX}/bin/ ${PREFIX}/share/
+```
+
+### Project Compilation Demonstration
+
+\*Here we need to review a knowledge point: According to [Linyaps Application Directory Structure Specification], the build directory at the same level as the build project configuration file `linglong.yaml` will be mapped as the `/project` directory
+Everything is ready, we can start compiling
+
+1. For convenience of operation, we open two shell windows in the build directory at the same time, which are used for `Linyaps Container Operation` and `Normal Operation` respectively
+
+2. After completing the preparation of `linglong.yaml` editing, we can start generating the container. Execute limited operations to directly enter the Linyaps container:
+
+```
+szbt@szbt-linyaps23:/media/szbt/Data/ll-build/QT/qBittorrent-git$ ll-builder build --exec bash
+```
+
+When the path changes similar to the following, it means we have entered the Linyaps container:
+
+```
+szbt@szbt-linyaps23:/project$
+```
+
+3. Extract the `qBittorrent-4.6.7` source code to the build directory through the `Normal Operation` window. I extracted it to a subdirectory here separately
+
+```
+szbt@szbt-linyaps23:/media/szbt/Data/ll-build/QT/qBittorrent-git$ tar -xvf qBittorrent-4.6.7-git-origin-src.tar.zst -C src/
+```
+
+4. After the source code is extracted, according to [Basic Steps for Linyaps Application Building], we should correctly choose which compilation system/tools to use before compiling any source code. We observe the `qBittorrent-4.6.7` source code directory and can see that it has a `CMakeLists.txt` file, which is a `CMake` build project.
+   ![1](images/2-1.png)
+
+5. Since the [qBittorrent INSTALL](https://github.com/qbittorrent/qBittorrent/blob/release-4.6.7/INSTALL) briefly describes the runtime libraries mainly used by this project, we can compare this document to determine which runtime libraries exist in the `base` and `runtime` provided by Linyaps and which runtime libraries are not provided. For runtime libraries that are not officially provided, we may need to pre-compile the necessary third-party libraries before compiling the main program.
+
+Since the runtime libraries described in the document are few, we can directly perform a test compilation this time to confirm the missing runtime libraries
+
+6. Without delay, we enter the source code directory through the `Linyaps Container Operation` window. In order to avoid interference with the source directory as much as possible, I create a new `build` directory here for compilation. After entering the `build` directory, we enter CMake-related configuration parameters to configure the build project.
+   According to [Linyaps Application Directory Structure Specification], we assign the value of `DCMAKE_INSTALL_PREFIX` to `$PREFIX`. Finally, I executed the following operations locally:
+
+```
+	cmake -DCMAKE_BUILD_TYPE=Release\
+ -DCMAKE_INSTALL_PREFIX=$PREFIX ..
+```
+
+7. As can be seen from the figure, an error occurred here that prevented the configuration from being completed. We see that `pkg-config` has an error: the `libtorrent-rasterbar>=1.2.19` library cannot meet the conditions:
+
+![error-1](images/2-error-1.png)
+
+```
+-- Found PkgConfig: /bin/pkg-config (found version "1.8.1")
+-- Checking for module 'libtorrent-rasterbar>=1.2.19'
+```
+
+I also cannot obtain relevant information about this library through `pkg-config` alone:
+
+```
+szbt@szbt-linyaps23:/project/src/qBittorrent-release-4.6.7-szbt2/build$ pkg-config --print-provides libtorrent-rasterbar
+```
+
+Based on this error, we can basically determine that the library is missing, so we need to compile and install this third-party library before compiling the main program
+
+8. We return to the `Normal Operation` window and download the source code corresponding to the `libtorrent-rasterbar>=1.2.19` library to the current build directory. Enter the `Linyaps Container Operation` window to recompile
+
+9. After the source code is extracted, according to [Basic Steps for Linyaps Application Building], we should correctly choose which compilation system/tools to use before compiling any source code. We observe the `libtorrent-rasterbar-2.0.9` source code directory and can see that it has a `CMakeLists.txt` file, which is a `CMake` build project.
+
+![2](images/2-2.png)
+
+10. We enter the source code directory through the `Linyaps Container Operation` window. In order to avoid interference with the source directory as much as possible, I create a new `build` directory here for compilation. After entering the `build` directory, we enter CMake-related configuration parameters to configure the build project.
+    According to [Linyaps Application Directory Structure Specification], we assign the value of `DCMAKE_INSTALL_PREFIX` to `$PREFIX`. Finally, I executed the following operations locally:
+
+```
+	cmake -DCMAKE_BUILD_TYPE=Release\
+ -DCMAKE_INSTALL_PREFIX=$PREFIX ..
+	make -j$(nproc)
+	make install
+```
+
+As can be seen, the third-party library `libtorrent-rasterbar-2.0.9` was successfully compiled and installed into the `$PREFIX` directory in the container. We can start the next operation
+
+11. We return to the `Linyaps Container Operation` window and enter the `qBittorrent-4.6.7` source code directory. Re-execute the configuration, compilation, and installation operations. No errors exist.
+
+### Compilation Result Testing
+
+After the process ends, we find the binary executable file of this project in the `$PREFIX` directory `/opt/apps/org.qbittorrent.qBittorrent/files/bin/qbittorrent` and run the test in the container. \* This operation needs to be performed in the terminal of the graphical desktop, otherwise the graphical interface of the program may not be invoked
+
+It seems that because it is not directly started through the container, there is a problem that the runtime library cannot be found. Since the reported library is also in $PREFIX, we directly use the variable `LD_LIBRARY_PATH` to specify the dynamic runtime library search path
+
+![test](images/2-test.png)
+
+So far, it is sufficient to prove that `Qt5-based open source application--qBittorrent` can be successfully compiled and run in the `Linyaps` application container!

docs/pages/en/guide/lessons/build-offline-src.md

@@ -0,0 +1,224 @@
+# Adapting Qt5-based Open Source Application--qBittorrent to Support Automated Linyaps Application Build Project
+
+After learning from the previous chapter "Compiling Qt5-based Open Source Application--qBittorrent in Linyaps Container", we have roughly understood how to compile the Qt5-based open source application--qBittorrent project source code into executable binary program files in the Linyaps container.
+
+Today, we will complete the final step in the "Basic Steps of Linyaps Application Building" on this basis--writing a complete Linyaps application build project configuration file `linglong.yaml`, mainly achieving the following goals:
+
+1. Automatically pull open source project source code
+2. Automatically apply patches to modify the source code
+3. Automatically execute compilation, build, and installation operations
+
+## Preliminary Preparation
+
+According to the requirements in "Basic Knowledge of Linyaps Application Build Project" regarding "General Resource Specifications for Linyaps Application Build Project", we should provide both `icons` icon files and `desktop` launch files that ensure desktop user experience for a graphical application.
+
+Therefore, in order to write a complete `linglong.yaml` that can automatically compile `qBittorrent` today, we need to additionally prepare the following materials:
+
+1. Non-binary file general resources: icons, desktop files
+2. Main program qBittorrent open source project repository git information, tag version, commit information
+3. Third-party runtime library libtorrent open source project repository git information, tag version, commit information
+
+### General Resource Preparation
+
+Since in the previous lesson we successfully compiled and ran `qBittorrent` in the Linyaps container, and this application provided both the icons directory and desktop launch file after installation to $PREFIX, we check these two items and confirm they both comply with the "Freedesktop XDG Specification", so we only need to copy them directly from the container to local, that is, copy to the build directory `/project`.
+
+```
+ziggy@linyaps23:/project/src/qBittorrent-release-4.6.7-szbt2/build$ ls $PREFIX/share/applications/
+org.qbittorrent.qBittorrent.desktop
+```
+
+```
+ziggy@linyaps23:/project/src/qBittorrent-release-4.6.7-szbt2/build$ ls $PREFIX/share/icons/hicolor/128x128/apps/
+qbittorrent.png
+```
+
+Thus, we obtained the "non-binary file general resources". For convenience of being used by build components, I placed these files in the `template_app` subdirectory of the build directory. The current structure is:
+
+```
+template_app
+├── linglong.yaml
+└── template_app
+    ├── applications
+    │   └── org.qbittorrent.qBittorrent.desktop
+    ├── icons
+    │   └── hicolor
+    │       ├── 128x128
+    │       │   ├── apps
+    │       │   │   └── qbittorrent.png
+    │       │   └── status
+    │       │       └── qbittorrent-tray.png
+    │       └── scalable
+    │           ├── apps
+    │           │   └── qbittorrent.svg
+    │           └── status
+    │               ├── qbittorrent-tray-dark.svg
+    │               ├── qbittorrent-tray-light.svg
+    │               └── qbittorrent-tray.svg
+```
+
+### Desktop Launch File Customization
+
+According to the "General Resource Specifications for Linyaps Application Build Project" in the basic knowledge course, we need to ensure the current desktop file complies with relevant specifications.
+We open the desktop file exported from the container, check the Exec and Icon fields, and draw the following conclusions:
+
+```
+[Desktop Entry]
+Categories=Network;FileTransfer;P2P;Qt;
+Exec=qbittorrent %U
+GenericName=BitTorrent client
+Comment=Download and share files over BitTorrent
+Icon=qbittorrent
+```
+
+Main conclusions:
+
+1. Icon field value is consistent with icon file, compliant with specification
+2. Exec field value is not the compilation result in Linyaps container, needs to be modified to content that complies with "General Resource Specifications for Linyaps Application Build Project". Here we replace it with absolute path pointing to the specific binary file in the container, used to wake up the container and launch the application
+
+## Build Project Configuration File `linglong.yaml` Preparation
+
+After preparing the essential general resources for graphical applications, we begin writing build rules.
+Since in the previous lesson we already prepared a simple version of `linglong.yaml` that doesn't have complete build functionality, we can customize it based on that. The current initial state is:
+
+```yaml
+version: "4.6.7.2"
+
+package:
+  id: org.qbittorrent.qBittorrent
+  name: "qBittorrent"
+  version: 4.6.7.2
+  kind: app
+  description: |
+    qBittorrent binary
+
+base: org.deepin.foundation/23.0.0
+runtime: org.deepin.Runtime/23.0.1
+
+command:
+  - /opt/apps/org.qbittorrent.qBittorrent/files/bin/qbittorrent
+
+sources:
+  - kind: local
+    name: "qBittorrent"
+
+build: |
+  mkdir -p ${PREFIX}/bin/ ${PREFIX}/share/
+```
+
+### Build Rule Writing & Testing
+
+For smooth transition, I will first import the compilation instructions into the build rules, temporarily not introducing automatic git repository pulling content, to ensure the build rules we write are accurate and usable.
+Since it's not recommended to execute too many `tar` instructions in build rules, I open two shell windows in the build directory here, respectively for "Linyaps Container Operations" and "Normal Operations".
+The following is the formal transformation process:
+
+1. Through the "Normal Operations" window, use `git` to pull or extract `qBittorrent` and `libtorrent-rasterbar` source code to the build directory. Here I extract them to subdirectories through source code compressed packages separately
+
+```
+ziggy@linyaps23:/media/szbt/Data/ll-build/QT/qBittorrent-local$ tar -xvf qBittorrent-4.6.7-git-origin-src.tar.zst -C src/
+ziggy@linyaps23:/media/szbt/Data/ll-build/QT/qBittorrent-local$ tar -xvf libtorrent-rasterbar-2.0.9.tar.gz -C 3rd/
+
+```
+
+2. From the "Linyaps Application Directory Structure Specification", we know that the build directory will be mapped as `/project`, so we need to write the manual compilation commands used in the previous lesson into the `build` module
+
+```
+build: |
+  mkdir -p ${PREFIX}/bin/ ${PREFIX}/share/
+  ##Build 3rd libs Comment: Enter `libtorrent-rasterbar` source directory and compile install to container
+  mkdir /project/3rd/libtorrent-rasterbar-2.0.9/build
+  cd /project/3rd/libtorrent-rasterbar-2.0.9/build
+  cmake -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=$PREFIX ..
+  make -j$(nproc)
+  make install
+  ##Build main Comment: Enter `qBittorrent` source directory and compile install to container
+  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
+  ##Extract common res Comment: Copy general files to install to container corresponding directory, comply with "Linyaps Application Directory Structure Specification"
+  cp -rf /project/template_app/* ${PREFIX}/share/
+```
+
+After completing this build rule block, we can start trying to compile local source code into binary programs through automated building and export Linyaps application installation package `binary.layer`. \* Since this version of configuration file doesn't provide extract and delete functions, these directories need to be cleared and re-extracted before each rebuild
+
+### Local One-Stop Build Test
+
+After completing the `build` module, the current `linglong.yaml` status is:
+
+```yaml
+version: "2"
+
+package:
+  id: org.qbittorrent.qBittorrent
+  name: "qBittorrent"
+  version: 4.6.7.2
+  kind: app
+  description: |
+    qBittorrent binary
+
+base: org.deepin.foundation/23.0.0
+runtime: org.deepin.Runtime/23.0.1
+
+command:
+  - /opt/apps/org.qbittorrent.qBittorrent/files/bin/qbittorrent
+
+source:
+  - kind: local
+    name: "qBittorrent"
+
+build: |
+  ##Build 3rd libs
+  mkdir -p ${PREFIX}/bin/ ${PREFIX}/share/
+  mkdir /project/3rd/libtorrent-rasterbar-2.0.9/build
+  cd /project/3rd/libtorrent-rasterbar-2.0.9/build
+  cmake -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=$PREFIX ..
+  make -j$(nproc)
+  make install
+  ##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
+  ##Extract common res
+  cp -rf /project/template_app/* ${PREFIX}/share/
+```
+
+At this point we can return to the build directory and start the build test, execute:
+
+```
+ziggy@linyaps23:/media/szbt/Data/ll-build/QT/qBittorrent-local$ ll-builder build -v
+```
+
+Thanks to the compilation notes in the Linyaps container, this build quickly ended successfully. We execute the following command to export the container as a Linyaps application installation package `binary.layer`:
+
+```
+ziggy@linyaps23:/media/szbt/Data/ll-build/QT/qBittorrent-local$ ll-builder export --layer
+```
+
+## Local Build Result Testing
+
+After obtaining the Linyaps application installation package, I tried to experience it on different mainstream distributions that support the Linyaps environment to confirm whether the binary programs built through the Linyaps container have universality.
+
+### deepin 23
+
+![deepin 23](images/3-test-1.png)
+
+### openKylin 2.0
+
+![openKylin 2.0](images/3-test-2.png)
+
+### Ubuntu 2404
+
+![Ubuntu 2404](images/3-test-3.png)
+
+### OpenEuler 2403
+
+![OpenEuler 2403](images/3-test-4.png)
+
+So far, it is sufficient to prove that the "Qt5-based open source application--qBittorrent" can be successfully built and run in third-party distributions that support the "Linyaps" application solution!

docs/pages/en/guide/lessons/test-with-toolchains.md

@@ -0,0 +1,184 @@
+# Advanced Linyaps Application Compatibility Testing -- Linyaps Application Automated Testing Suite
+
+As you may have noticed, in our previous Linyaps application compilation, we manually installed packages and launched applications to test compatibility
+However, this raises a question: as the number of applications that need testing continues to increase, doesn't the manual testing approach seem relatively inefficient?
+To address this, I would like to introduce to you the `Linyaps Application Automated Testing Suite -- Next Linyaps Testing Toolchains` currently available to ecosystem contributors in the Linyaps community
+
+## Project Introduction
+
+`Next Linyaps Testing Toolchains` is a Linyaps application testing toolchain composed of shell scripts, designed to bring more convenient solutions for Linyaps application testing
+This project is the legitimate spiritual successor of [linglong-automan](https://gitee.com/ziggy615/linglong-automan) and promises to remain open source forever
+
+## Implemented Features
+
+1. Organize scattered `*binary.layer` files in a specified directory into a standardized directory structure: `xxx/id/package` and generate two tables storing Linyaps application IDs and application version numbers
+
+2. After specifying the organized Linyaps file storage directory, start the streamlined installation process
+
+3. After specifying the resource storage directory and application information table, simulate launching applications through desktop files based on `installation status`, `desktop file existence status`, and `window generation status`, and take screenshots of test results \* The current code partially depends on `deepin 23` system components and needs to be re-adapted when used on other distributions
+
+4. Scan icon files for installed Linyaps applications, determine whether the current application icons directory and files comply with `Freedesktop XDG` specifications, and collect icons
+
+5. Batch uninstall installed Linyaps applications
+
+## Code Structure Analysis
+
+Entering the suite repository, you can see that the suite is divided into several key independent scripts according to function/role, roughly:
+
+1. `linyaps-auto-optimize.sh`, Linyaps application installation package `binary.layer` organization tool. Organize all `binary.layer` files in a directory into a structure suitable for the testing suite and produce two tables for recording Linyaps application IDs and version numbers, such as:
+
+```
+org.qbittorrent.qBittorrent/package/org.qbittorrent.qBittorrent_4.6.7.22_x86_64_binary.layer
+com.poki.apple-knight-golf.linyaps/package/com.poki.apple-knight-golf.linyaps_28.3.3.2_x86_64_binary.layer
+```
+
+ll-pkg-name.csv
+
+```
+org.qbittorrent.qBittorrent
+com.poki.apple-knight-golf.linyaps
+```
+
+ll-pkg-version.csv
+
+```
+4.6.7.22
+28.3.3.2
+```
+
+2. `linyaps-auto-install-release.sh`, Linyaps application installation package `binary.layer` batch installation tool, used to install packages organized by `linyaps-auto-optimize.sh`
+
+3. `linyaps-auto-screenshot-deepin23.sh`, application automated testing suite, including running status screenshot function, only for `deepin 23` environment
+
+4. `linyaps-auto-screenshot-general.sh`, application automated testing suite general version, does not include running status screenshot function, for non-deepin 23 environments
+
+5. `linyaps-auto-uninstall-release.sh`, Linyaps application batch uninstallation tool
+
+## Next Linyaps Testing Toolchains Practical Application
+
+After introducing the overall functions and code logic, we demonstrate how to complete batch testing of Linyaps application installation packages `binary.layer` produced in previous lessons through the `Linyaps Application Automated Testing Suite` based on `deepin 23`
+
+### Environment Preparation
+
+Before starting to use the testing suite, you need to ensure that the current environment meets the following conditions
+
+1. Some functions of the self-service compatibility testing suite used in this practical demonstration require the use of `Linux x11` window management tools, so you need to install the following software packages before use:
+
+```
+wmctrl x11-utils
+```
+
+2. The testing suite uses x11 window management tools to determine application window startup status, so you need to ensure that your system is an `x11` environment rather than a `Wayland` environment
+
+3. `wmctrl` and `xwininfo` components can work normally, and window information can be queried through `xwininfo`
+
+4. Since `deepin 23` provides compatibility testing result screenshot function, you need to install related software packages:
+
+```
+deepin-screen-recorder imagesmagick-6.q16
+```
+
+5. Manually start `deepin-screen-recorder` once to ensure that the system screenshot save path is in the current user's ~/Pictures/Screenshots, and the directory is empty
+
+### Start Testing Function
+
+1. In the previous practical lesson, we obtained the Linyaps installation package `org.qbittorrent.qBittorrent_4.6.7.22_x86_64_binary.layer` for `qBittorrent--4.6.7`. For convenience in demonstrating the suite's batch support capability, I separately found another installation package here
+
+2. Now we have two Linyaps application installation packages. First execute the `linyaps-auto-optimize.sh` script to organize the directory
+   This script mainly uses two parameters to point to the current directory storing Linyaps application installation packages `binary.layer` `$ll_origin_pool` and the destination directory that needs to be organized `$ll_stored_pool`
+
+3. I created two separate directories `ll-bins` `ll-pool` locally to point to `$ll_origin_pool` and `$ll_stored_pool`
+   The current directory structure of `ll-bins`:
+
+```
+├── ll-bins
+│   ├── org.qbittorrent.qBittorrent_4.6.7.22_x86_64_binary.layer
+│   └── com.poki.apple-knight-golf.linyaps_28.3.3.2_x86_64_binary.layer
+```
+
+4. Execute directory organization operation
+
+```bash
+ziggy@linyaps23:/media/szbt/Data/linyaps-testing-toolchains$ ./linyaps-auto-optimize.sh ./ll-bins ./ll-pool
+```
+
+After the organization is completed, the directory presents this structure:
+
+```
+ll-pool/
+├── org.qbittorrent.qBittorrent
+│   └── package
+│       └── org.qbittorrent.qBittorrent_4.6.7.22_x86_64_binary.layer
+└── com.poki.apple-knight-golf.linyaps
+    └── package
+        └── com.poki.apple-knight-golf.linyaps_28.3.3.2_x86_64_binary.layer
+
+```
+
+5. After the directory organization, two tables `ll-pkg-name.csv` `ll-pkg-version.csv` are generated to record application information. We merge the two columns into a new table `ll-pkg-info.csv`:
+
+ll-pkg-info.csv
+
+```
+org.qbittorrent.qBittorrent,4.6.7.22
+com.poki.apple-knight-golf.linyaps,28.3.3.2
+```
+
+6. Based on this file, we can start batch installing Linyaps applications
+   This script mainly uses one parameter to point to the current organized destination directory `$ll_stored_pool`:
+
+```bash
+ziggy@linyaps23:/media/szbt/Data/linyaps-testing-toolchains$ linyaps-auto-install-release.sh ./ll-pool
+```
+
+7. After installing the Linyaps applications and completing all prerequisite work, we can start the testing process. Here we create a new `res` directory to store test result resources such as icons and screenshots
+
+8. Open a terminal in the graphical interface and execute the screenshot script. Since we are in a `deepin 23 x11` environment and have installed the necessary programs, we run `linyaps-auto-screenshot-deepin23.sh`
+   This script mainly uses two parameters to point to the directory for placing test result resources `$ll_res_pool` and the table recording application information `$ll_pkgname_list`. Here it refers to the new table `ll-pkg-info.csv` we obtained in the previous step:
+
+```bash
+ziggy@linyaps23:/media/szbt/Data/linyaps-testing-toolchains$ ./linyaps-auto-screenshot-deepin23.sh ./res ./ll-pkg-info.csv
+```
+
+\* Remember, this script must be executed in a graphical terminal, otherwise the process cannot be properly launched
+
+9. After the script starts, minimize the terminal window and keep it running in the background. The testing suite will judge the application installation status and desktop file existence status to `start` and `close` application windows
+
+![test-1](images/5-test-1.png)
+![test-2](images/5-test-2.png)
+
+10. After meeting the running requirements, the suite will simulate launching the program through the desktop file and judge the window after about 30s delay, checking whether the application generates a new window after running
+
+![test-3](images/5-test-3.png)
+![test-4](images/5-test-4.png)
+
+11. After the application runs successfully, it will complete screenshot, icon detection & acquisition operations in sequence
+
+12. After the test is completed, you can see tables of different statuses and test result materials in the `res` directory. Since both applications here passed the compatibility test, they will be recorded in `all-good.csv`
+    Otherwise, two abnormal situations will occur:
+    a. Applications that timeout without generating windows will be written into the `failed.csv` file, judged as applications that cannot be launched
+    b. If the Linyaps application directory does not contain icon files, it will be written into the `icons-missing.csv` file, not meeting the specifications for graphical applications in the Linyaps community
+
+```
+res/
+├── all-good.csv
+├── com.poki.apple-knight-golf.linyaps
+│   ├── icons
+│   │   └── com.poki.apple-knight-golf.png		##Application icon file
+│   └── screenshots	##Application compatibility test screenshots
+│       ├── 1.png
+│       ├── 2.png
+│       └── 3.png
+└── org.qbittorrent.qBittorrent
+    ├── icons
+    │   ├── qbittorrent.png
+    │   └── qbittorrent.svg
+    └── screenshots
+        ├── 1.png
+        ├── 2.png
+        └── 3.png
+```
+
+![test-5](images/5-test-5.png)
+
+So far, we have successfully completed compatibility testing of Linyaps applications produced in previous lessons through the Linyaps Application Automated Testing Suite

docs/pages/en/guide/linyaps-devel/README.md

@@ -0,0 +1 @@
+This repository contains developer-related documentation. (To be supplemented)

docs/pages/en/guide/ll-appimage-convert/convert-appimage.md

@@ -1,88 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2024 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-## Conversion appimage application
-
-convert `appimage` format (`.appimage` or `.AppImage`) application to linyaps format (`.layer` or `.uab`) application
-
-View the help information for the `ll-appimage-convert convert --help` command:
-
-```bash
-ll-appimage-convert convert --help
-```
-
-Here is the output:
-
-```text
-Usage:
-  ll-appimage-convert convert [flags]
-Flags:
-  -b, --build                build linglong
-  -d, --description string   detailed description of the package
-  -f, --file string          app package file, it not required option,
-                             you can ignore this option
-                             when you set --url option and --hash option
-      --hash string          pkg hash value, it must be used with --url option
-  -h, --help                 help for convert
-  -i, --id string            the unique name of the package
-  -l, --layer                export layer file
-  -n, --name string          the description the package
-  -u, --url string           pkg url, it not required option,you can ignore this option when you set -f option
-  -v, --version string       the version of the package
-Global Flags:
-  -V, --verbose   verbose output
-```
-
-The `ll-appimage-convert convert` command will generate a directory according to the specified app name (`--name` option), which will serve as the root directory of the linyaps project where the `linglong.yaml` file is located. It supports two conversion methods:
-
-1. you can use the `--file` option to convert to linyaps application according to the specified appimage file;
-2. you can use the `--url` and `--hash` option to convert to linyaps application according to the specified appimage url and hash value;
-3. you can use the `--layer` option to export `.layer`, or it will export `.uab` by default.
-
-`Tips: When the linyaps version is greater than 1.5.7, the default converted package format is `.uab`. If you want to export a `.layer` file, you need to add the --layer option.`
-
-you can use the `--output` option to generate the configuration file (`linglong.yaml`) of the linyaps project and a script for building linyaps `.layer` (`.uab`)
-then you can execute the script file to generate after you modify the `linglong.yaml` file. If you do not specify this option, it will export linyaps `.layer` or `.uab` directly.
-
-Take converting [BrainWaves](https://github.com/makebrainwaves/BrainWaves/releases/download/v0.15.1/BrainWaves-0.15.1.AppImage) into linyaps `.layer` through `--url` as an example, the main steps are as follows:
-
-Specify the relevant parameters of the linyaps package you want to convert, and you will obtain `io.github.brainwaves_0.15.1.0_x86_64_runtime.layer` or `io.github.brainwaves_0.15.1.0_x86_64_runtime.uab` after a short wait.
-
-```bash
-ll-appimage-convert convert --url "https://github.com/makebrainwaves/BrainWaves/releases/download/v0.15.1/BrainWaves-0.15.1.AppImage" --hash "04fcfb9ccf5c0437cd3007922fdd7cd1d0a73883fd28e364b79661dbd25a4093" --name "io.github.brainwaves" --id "io.github.brainwaves" --version "0.15.1.0" --description "io.github.brainwaves" -b
-```
-
-Take converting BrainWaves-0.15.1.AppImage into `.uab` through `--file` as an example, the main steps as follows:
-
-```bash
-ll-appimage-convert convert -f ~/Downloads/BrainWaves-0.15.1.AppImage --name "io.github.brainwaves" --id "io.github.brainwaves" --version "0.15.1.0" --description "io.github.brainwaves" -b
-```
-
-The converted directory structure is as follows:
-
-```text
-├── io.github.brainwaves_x86_64_0.15.1.0_main.uab
-├── linglong
-└── linglong.yaml
-```
-
-Take converting BrainWaves-0.15.1.AppImage into `.layer` through `--file` as an example, the main steps as follows:
-
-```bash
-ll-appimage-convert convert -f ~/Downloads/BrainWaves-0.15.1.AppImage --name "io.github.brainwaves" --id "io.github.brainwaves" --version "0.15.1.0" --description "io.github.brainwaves" -b --layer
-```
-
-The converted directory structure is as follows:
-
-```text
-├── io.github.brainwaves_0.15.1.0_x86_64_binary.layer
-├── io.github.brainwaves_0.15.1.0_x86_64_develop.layer
-├── linglong
-└── linglong.yaml
-```
-
-`.uab` or `.layer` file verification
-The exported `.uab` or `.layer` files need to be installed and verified. Install the layer files and run the application. You can refer to: [Install the application](../ll-cli/install.md)

docs/pages/en/guide/ll-appimage-convert/introduction.md

@@ -1,42 +0,0 @@
-# ll-appimage-convert introduction
-
-This tool is provided by the `linglong-pica` package, which provides the ability to convert appimage packages into linyaps packages, generate the linglong.yaml file required to build linyaps applications, and relies on ll-builder to implement application building and export.
-
-:::tip
-
-The conversion tool is merely an auxiliary tool and does not guarantee
-that the converted application will definitely run. It's possible that
-the software depends on libraries installed in paths or other
-configuration paths that do not align with those inside linyaps's
-internal structure, leading to the inability to execute. In such cases,
-you would need to use the command `ll-builder run --exec bash` to enter the container for debugging purposes.
-:::
-
-View the help information for the `ll-appimage-convert` command:
-
-```bash
-ll-appimage-convert --help
-```
-
-Here is the output:
-
-```bash
-Convert appimage to uab. For example:
- Simple:
-         ll-appimage-convert  convert -f xxx.appimage -i "io.github.demo" -n "io.github.demo" -v "1.0.0.0" -d "this is a appimage convert demo" -b
-         ll-appimage-convert help
-
-Usage:
-  ll-appimage-convert [command]
-
-Available Commands:
-  convert     Convert appimage to uab
-  help        Help about any command
-
-Flags:
-  -h, --help      help for ll-appimage-convert
-  -V, --verbose   verbose output
-  -v, --version   version for ll-appimage-convert
-
-Use "ll-appimage-convert [command] --help" for more information about a command.
-```

docs/pages/en/guide/ll-builder/build.md

@@ -1,70 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Build App
-
-Use `ll-builder build` to build a linyaps application.
-
-View the help information for the `ll-builder build` command:
-
-```bash
-ll-builder build --help
-```
-
-Here is the output:
-
-```text
-Build a linyaps project
-Usage: ll-builder build [OPTIONS] [COMMAND...]
-
-Positionals:
-  COMMAND TEXT ...            Enter the container to execute command instead of building applications
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-  --file FILE:FILE [./linglong.yaml]
-                              File path of the linglong.yaml
-  --arch ARCH                 Set the build arch
-  --offline                   Only use local files. This implies --skip-fetch-source and --skip-pull-depend will be set
-  --skip-fetch-source         Skip fetch sources
-  --skip-pull-depend          Skip pull dependency
-  --skip-run-container        Skip run container
-  --skip-commit-output        Skip commit build output
-  --skip-output-check         Skip output check
-  --skip-strip-symbols        Skip strip debug symbols
-```
-
-The `ll-builder build` command can be run in two ways:
-
-1. In the root directory of the project, where the `linglong.yaml` file is located.
-2. Specify the linglong.yaml file path with the `--file` parameter.
-
-Taking the linyaps project `org.deepin.demo` as an example, the main steps to build a linyaps application would be as follows:
-
-Go to the `org.deepin.demo` project directory:
-
-```bash
-cd org.deepin.demo
-```
-
-Execute the `ll-builder build` command to start building:
-
-```bash
-ll-builder build
-```
-
-After the build is complete, the build content will be automatically committed to the local ostree cache. See `ll-builder export` for exporting build content.
-
-Use the `--exec` parameter to enter the linyaps container before the build script is executed:
-
-```bash
-ll-builder build --exec /bin/bash
-```
-
-After entering the container, you can execute `shell` commands, such as `gdb`, `strace`, etc.
-
-For more debugging information about linyaps application `debug` version, please refer to: [Debug App](../debug/debug.md).

docs/pages/en/guide/ll-builder/create.md

@@ -1,144 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Create linyaps project
-
-Use `ll-builder create` to create a linyaps project.
-
-View the help information for the `ll-builder create` command:
-
-```bash
-ll-builder create --help
-```
-
-Here is the output:
-
-```text
-Create linyaps build template project
-Usage: ll-builder create [OPTIONS] NAME
-
-Positionals:
-  NAME TEXT REQUIRED          Project name
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-```
-
-The `ll-builder create` command creates a folder in the current directory according to the project name and generates the `linglong.yaml` template file required for the build. Here is an example:
-
-```bash
-ll-builder create org.deepin.demo
-```
-
-Here is the output:
-
-```text
-org.deepin.demo/
-└── linglong.yaml
-```
-
-## Edit linglong.yaml
-
-### The syntax version of the linglong.yaml file.
-
-```yaml
-version: "1"
-```
-
-### App meta info
-
-```yaml
-package:
-  id: org.deepin.demo
-  name: hello
-  version: 0.0.0.1
-  kind: app
-  description: |
-    simple Qt demo.
-```
-
-### Base
-
-The minimum root filesystem.
-
-```yaml
-base: org.deepin.base/23.1.0
-```
-
-### Runtime
-
-On the basis of the rootfs, add fundamental environments such as Qt.
-
-```yaml
-runtime: org.deepin.runtime.dtk/23.1.0
-```
-
-### Command
-
-linyaps application startup command.
-
-```yaml
-command: [echo, -e, hello world]
-```
-
-### Source
-
-Use git source code
-
-```yaml
-sources:
-  kind: git
-  url: "https://github.com/linuxdeepin/linglong-builder-demo.git"
-  commit: a3b89c3aa34c1aff8d7f823f0f4a87d5da8d4dc0
-```
-
-### Build
-
-The commands required to build the project.
-
-```yaml
-build: |
-  cd /project/linglong/sources/linglong-builder-demo.git
-  qmake demo.pro
-  make -j${JOBS}
-  make install
-```
-
-### Completed `linglong.yaml` config
-
-The contents of the `linglong.yaml` file are as follows:
-
-```yaml
-version: "1"
-
-package:
-  id: @ID@
-  name: your name #set your application name
-  version: 0.0.0.1 #set your version
-  kind: app
-  description: |
-    your description #set a brief text to introduce your application.
-
-command: [echo, -e, hello world] #the commands that your application need to run.
-
-base: org.deepin.base/23.1.0 #set the base environment, this can be changed.
-
-#set the runtime environment if you need, a example of setting deepin runtime is as follows.
-#runtime:
-#runtime: org.deepin.runtime.dtk/23.1.0
-
-#set the source if you need, a simple example of git is as follows.
-#sources:
-#  - kind: git
-#    url: https://github.com/linuxdeepin/linglong-builder-demo.git
-#    version: master\n
-#    commit: a3b89c3aa34c1aff8d7f823f0f4a87d5da8d4dc0
-
-build: |
-  echo 'hello' #some operation to build this project
-
-```

docs/pages/en/guide/ll-builder/export.md

@@ -1,88 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023-2024 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Export
-
-The `ll-builder export` command is used to export applications from the local build cache into a UAB (Universal Application Bundle) file. This is the recommended format. It can also export to the deprecated linglong layer file format.
-
-## Basic Usage
-
-```bash
-ll-builder export [OPTIONS]
-```
-
-To view all available options and their detailed descriptions, run:
-
-```bash
-ll-builder export --help
-```
-
-## Main Options
-
-- `-f, --file FILE`: Specify the path to the `linglong.yaml` configuration file (default: `./linglong.yaml`). The directory containing `linglong.yaml` serves as the project's working directory.
-- `-o, --output FILE`: Specify the output file path. For UAB, this is typically the full path or filename of the `.uab` file. For layers, this is the prefix for the output filenames.
-- `-z, --compressor X`: Specify the compression algorithm. Supports `lz4` (UAB default), `lzma` (layer default), `zstd`.
-- `--icon FILE`: Specify an icon for the exported UAB file (UAB mode only, mutually exclusive with `--layer`).
-- `--loader FILE`: Specify a custom loader for the exported UAB file (UAB mode only, mutually exclusive with `--layer`).
-- `--layer`: **(Deprecated)** Export as layer file format instead of UAB (mutually exclusive with `--icon`, `--loader`).
-- `--no-develop`: When exporting layer files, do not include the `develop` module.
-
-## Exporting UAB Files (Recommended)
-
-A UAB (Universal Application Bundle) file is a self-contained, offline-distributable file format that includes the content required to run the application. This is the recommended export format.
-
-After execution, the `ll-builder export` command generates a `.uab` file in the project's working directory (or the path specified with `-o`), for example, `<app_id>_<version>_<arch>.uab`.
-
-You can customize the UAB export using other options:
-
-```bash
-# Export UAB file specifying icon and output path
-ll-builder export --icon assets/app.png -o dist/my-app-installer.uab
-
-# Export UAB file using zstd compression
-ll-builder export -z zstd -o my-app-zstd.uab
-
-# Export UAB file specifying a custom loader
-ll-builder export --loader /path/to/custom/loader -o my-app-custom-loader.uab
-```
-
-## Exporting Layer Files (Deprecated)
-
-**Note: Exporting layer file format is deprecated. Using the UAB format is recommended.**
-
-Export layer files using the command `ll-builder export --layer`. Other examples:
-
-```bash
-# Export layer format without the develop module
-ll-builder export --layer --no-develop
-
-# Export layer format and specify the output file prefix
-ll-builder export --layer -o my-app
-# (Generates my-app_binary.layer and my-app_develop.layer)
-```
-
-Exporting layer files generates the following files:
-
-- `*_binary.layer`: Contains the basic files required for the application to run.
-- `*_develop.layer`: (Optional) Contains files for development and debugging. This file is not generated if the `--no-develop` option is used.
-
-## Advanced Notes
-
-A UAB is a statically linked ELF executable intended to run on any Linux distribution. By default, exporting a UAB file uses the "bundle mode". Using the `--loader` parameter exports a UAB file in "custom loader mode".
-
-### Bundle Mode
-
-Bundle mode is primarily for distribution and supports self-running capabilities as much as possible. Users typically install offline-distributed applications via `ll-cli install <UABfile>`, which automatically completes the required runtime environment for the application. Once installed, the UAB application is used the same way as an application installed directly from a repository.
-
-During export in bundle mode, the builder attempts to automatically resolve application dependencies and export necessary content (best effort). If you grant executable permissions to a bundle mode UAB file and run it, the application runs directly without being installed. In this case, the application still runs in an isolated container, but missing parts of the runtime environment will use the host system's environment directly, so the application is not guaranteed to run.
-
-If application developers need to rely on the self-running feature, ensure the application includes the necessary runtime dependencies.
-
-### Custom Loader Mode
-
-A UAB file exported in custom loader mode contains only the application data and the provided custom loader. After the UAB file is unpacked and mounted, control is handed over to the custom loader, which runs outside the container environment. The environment variable `LINGLONG_UAB_APPROOT` stores the application's directory. The custom loader is responsible for initializing the application's required runtime environment, such as library search paths.
-
-In this mode, the application needs to ensure its compatibility with the target system. The recommended practice is to build the application on the oldest supported system version and include all dependencies.

docs/pages/en/guide/ll-builder/introduction.md

@@ -1,64 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Introduction to Linyaps Build Tools
-
-## Introduction to ll-builder
-
-`ll-builder` is a tool for developers to build linyaps applications.
-
-The main functions are as follows:
-
-- Supports building in a standalone sandbox
-
-<!-- - Defines a version management system. -->
-
-- Provides DTK software development kits
-
-<!-- - Contains a complete release process. -->
-
-View the help information for the `ll-builder` command:
-
-```bash
-ll-builder --help
-```
-
-Here is the output:
-
-```text
-linyaps builder CLI
-A CLI program to build linyaps application
-
-Usage: ll-builder [OPTIONS] [SUBCOMMAND]
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-  --version                   Show version
-
-Subcommands:
-  create                      Create linyaps build template project
-  build                       Build a linyaps project
-  run                         Run built linyaps app
-  export                      Export to linyaps layer or uab
-  push                        Push linyaps app to remote repo
-  import                      Import linyaps layer to build repo
-  extract                     Extract linyaps layer to dir
-  repo                        Display and manage repositories
-
-If you found any problems during use
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-## Introduction to Third-Party Tools
-
-[ll-killer](https://github.com/System233/ll-killer-go) A command-line tool designed to solve Linglong container application build issues
-
-[linglong-tools](https://github.com/myml/linglong-tools) A Linglong command-line tool
-
-[linglong-tools](https://github.com/System233/linglong-tools) An automated deb conversion tool for Linglong
-
-[linglong-builder-action](https://github.com/myml/linglong-builder-action) A GitHub action for building Linglong packages

docs/pages/en/guide/ll-builder/linyaps_package_spec.md

@@ -1,772 +0,0 @@
-# Linglong Application Packaging Specification
-
-The explanations of the keywords **must**, **prohibited**, **necessary**, **should**, **should not**, **recommended**, **allowed**, and **optional**[^rfc2119-keywords] in this document can be found in the description in [RFC 2119][rfc-2119].
-
-The correspondence between these keywords and the English words in the original text is shown in the following table:
-
-| Chinese         | English     |
-| --------------- | ----------- |
-| **Must**        | MUST        |
-| **Prohibited**  | MUST NOT    |
-| **Necessary**   | REQUIRED    |
-| **Should**      | SHALL       |
-| **Should not**  | SHALL NOT   |
-| **Recommended** | RECOMMENDED |
-| **Allowed**     | MAY         |
-| **Optional**    | OPTIONAL    |
-
-[rfc-2119]: https://datatracker.ietf.org/doc/html/rfc2119
-
-This document is intended to help application developers standardize the behavior of the application build process in order to migrate to the Linglong package management system.
-
-## General
-
-This section mainly records some general specifications that almost all projects should follow.
-
-### Application name
-
-The application name **should** use [reverse domain name notation](https://zh.wikipedia.org/wiki/%E5%8F%8D%E5%90%91%E5%9F%9F%E5%90%8D%E8%A1%A8%E7%A4%BA%E6%B3%95), such as `org.deepin.demo`.
-
-This application name is mainly used in scenarios such as naming desktop files and DBus services.
-
-- Developers **should** use the reverse of the domain name they actually own as the prefix of the application name, followed by the application name
-
-**Note**: If the developer cannot prove that they actually own the domain name, the application package may be removed from the repository.
-
-- For third-party applications developed on GitHub, if the organization where the application is located has an additional domain name, it should be used first, otherwise `io.github.<GITHUB_ID>.` should be used as the prefix.
-
-In particular, if the organization name and application name of the application are the same, such as <https://github.com/neovim/neovim>, the packager should not omit the duplicate application name and organization name, and the ID of this application should be `io.github.neovim.neovim`.
-
-**Note**: In fact, the organization owns the domain name `neovim.io`, so the most reasonable application name **should** be `io.neovim.neovim`.
-
-- **Not recommended** to use application names containing `-`. If the domain name/application name does contain `-`, **recommend** using `_` instead
-
-- **Not recommended** application names ending with `.desktop`
-
-The above specifications are from [Desktop Entry Specification][desktop-entry-specification].
-
-[desktop-entry-specification]: https://specifications.freedesktop.org/desktop-entry-spec/latest
-
-Further reading: <https://docs.flatpak.org/en/latest/conventions.html#application-ids>
-
-### `prefix` and `$DESTDIR`
-
-When writing the build process of an application, developers **should** not assume that the installation location is fixed. It is not standard to install executable files to a hard-coded path such as `/usr/bin` in Makefile/CMakeLists.txt.
-
-When writing the build/installation process, developers **should** respect the build system's `prefix` configuration and the value of the `$DESTDIR` environment variable so that packagers can easily configure the specific installation location of the application when packaging.
-
-`prefix` refers to the specific location specified to the build system during build/installation where the application will eventually be installed to the system.
-
-When the developer does not specify the installation location, the default value should be `/usr/local`.
-When packaging through the package management system, the package management system will configure its value. When using dpkg-related tools for packaging, its value will be configured as `/usr`. However, when writing the build/installation process, the developer should consider the case where `prefix` is configured to any value.
-
-`$DESTDIR` refers to an environment variable agreed upon when the build system is installed to facilitate the distribution packaging process. Its general working logic is as follows:
-
-If the build system completes the build work and executes the installation process, it is specified with `prefix=/usr` and `$DESTDIR=./tmp`, then after the installation is completed, all product files should appear in the `./tmp/usr` directory. The packaging tool will then treat `./tmp` as the root directory and compress and package the files in it.
-
-Here, taking the common build system as an example, several **recommended** ways of writing common file installation processes are given. These writing methods all respect the `prefix` configuration and `$DESTDIR`:
-
-#### Makefile
-
-This section is mainly written with reference to the relevant content in <https://www.gnu.org/prep/standards/standards.html> and <https://wiki.debian.org/Multiarch/Implementation>.
-
-Here, the default values ​​of some variables and other common parts are defined for the purpose of writing examples later. The relevant descriptions of the default values ​​of these variables can be found in the above link.
-
-```makefile
-DESTDIR ?=
-
-prefix ?= /usr/local
-bindir ?= $(prefix)/bin
-libdir ?= $(prefix)/lib
-libexecdir ?= $(prefix)/libexec
-datarootdir ?= $(prefix)/share
-
-INSTALL ?= install
-INSTALL_PROGRAM ?= $(INSTALL)
-INSTALL_DATA ?= $(INSTALL) -m 644
-
-# The variables with default values ​​defined above are the recommended behaviors in the above specifications, and no modification is recommended.
-
-PKG_CONFIG ?= pkg-config
-
-.PHONY: install
-```
-
-- Executable files
-
-```makefile
-install:
-$(INSTALL) -d "$(DESTDIR)$(bindir)"
-$(INSTALL_PROGRAM) path/to/your/executable "$(DESTDIR)$(bindir)"/executable
-```
-
-- Internal executable files
-
-Refers to executable files that should not be called directly by users in the terminal. These executable files **should** not be found through `$PATH`
-
-```makefile
-install:
-$(INSTALL) -d "$(DESTDIR)$(libexecdir)"
-$(INSTALL_PROGRAM) path/to/my/internal/executable "$(DESTDIR)$(libexecdir)"/executable
-```
-
-- Static libraries
-
-````makefile
-install:
-$(INSTALL) -d "$(DESTDIR)$(libdir)" $(INSTALL_DATA) path/to/my/library.a "$(DESTDIR)$(libdir)"/library.a ``` - pkg-config configuration file ```makefile pc_dir ?= $(libdir)/pkgconfig ifeq ($(findstring $(pc_dir), $(subst :, , $(shell \ $(PKG_CONFIG) --variable=pc_path)), ) $(warning pc_dir="$(pc_dir)" \ is not in the search path of current pkg-config installation) endif .PHONY: install-pkg-config install-pkg-config: $(INSTALL) -d "$(DESTDIR)$(pc_dir)" $(INSTALL_DATA) path/to/your.pc "$(DESTDIR)$(pc_dir)"/your.pc
-````
-
-If you are sure that the file is available across architectures, you can use `$(datarootdir)` instead of `$(libdir)`.
-
-- systemd system level unit `makefile systemd_system_unit_dir ?= $(shell \ $(PKG_CONFIG) --define-variable=prefix=$(prefix) \ systemd --variable=systemd_system_unit_dir) ifeq ($(findstring $(systemd_system_unit_dir), $(subst :, , $(shell \ $(PKG_CONFIG) systemd --variable=systemd_system_unit_path))), ) $(warning systemd_system_unit_dir="$(systemd_system_unit_dir)" \ is not in the system unit search path of current systemd installation) endif .PHONY: install-systemd-system-unit install-systemd-system-unit: $(INSTALL) -d "$(DESTDIR)$(systemd_system_unit_dir)" $(INSTALL_DATA) path/to/your.service "$(DESTDIR)$(systemd_system_unit_dir)"/your.service ` - systemd user-level unit ```makefile systemd_user_unit_dir ?= $(shell \ $(PKG_CONFIG) --define-variable=prefix=$(prefix) \ systemd --variable=systemd_user_unit_dir) ifeq ($(findstring $(systemd_user_unit_dir), $(subst :, , $(shell \ $(PKG_CONFIG) systemd --variable=systemd_user_unit_path))), ) $(warning systemd_user_unit_dir="$(systemd_user_unit_dir)" \ is not in the user unit search path of current systemd installation) endif .PHONY: install-systemd-user-unit install-systemd-user-unit: $(INSTALL) -d "$(DESTDIR)$(systemd_user_unit_dir)" $(INSTALL_DATA) path/to/your.service "$(DESTDIR)$(systemd_user_unit_dir)"/your.service
-
-````
-
-- desktop file
-
-```makefile
-install:
-$(INSTALL) -d "$(DESTDIR)$(datarootdir)"/applications
-$(INSTALL_PROGRAM) path/to/your.desktop "$(DESTDIR)$(datarootdir)"/applications/your.desktop
-````
-
-- desktop file corresponding icon
-
-See: <https://specifications.freedesktop.org/icon-theme-spec/latest/#install_icons>
-
-- If the installed icon is a fixed size version, it is **recommended** to use png format
-
-At least **need** to install a 48x48 size png to ensure the normal basic functions of icons in the desktop environment
-
-- If the installed icon is a vector version, it is **recommended** to use svg format
-
-````makefile
-install: $(INSTALL) -d "$(DESTDIR)$(datarootdir)"/icons/hicolor/48x48/apps $(INSTALL_DATA) path/to/your.png "$(DESTDIR)$(datarootdir)"/icons/hicolor/48x48/apps/your.png # Add more size of .png icons here... $(INSTALL) -d "$(DESTDIR)$(datarootdir)"/icons/hicolor/scalable/apps $(INSTALL_DATA) path/to/your.svg "$(DESTDIR)$(datarootdir)"/icons/hicolor/scalable/apps/your.svg ``` #### CMake
-
-This section is mainly written with reference to the relevant content in <https://cmake.org/cmake/help/v3.30/module/GNUInstallDirs.html#module:GNUInstallDirs> and <https://wiki.debian.org/Multiarch/Implementation>.
-
-Here we define the default values ​​of some variables and other common parts for writing examples later. The relevant descriptions of these variable default values ​​can be found in the link above.
-
-The writing logic is consistent with the relevant content in the Makefile section.
-
-```cmake
-include(GNUInstallDirs)
-````
-
-- Executable files
-
-See: <https://cmake.org/cmake/help/v3.30/command/install.html#programs>
-
-```cmake
-install(PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/path/to/your/executable TYPE BIN)
-```
-
-- Internal executable files
-
-Refers to executable files that should not be called directly in the terminal. These executable files **should** not be found through `$PATH`
-
-See: <https://cmake.org/cmake/help/v3.30/command/install.html#programs>
-
-```cmake
-install(PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/path/to/your/executable DESTINATION ${CMAKE_INSTALL_LIBEXECDIR})
-```
-
-Note: TYPE is not used because TYPE does not currently support LIBEXEC
-
-- Target file/export file
-
-To be added
-
-- pkg-config configuration file
-
-To be added
-
-- systemd system-level unit
-
-````cmake
-find_package(PkgConfig)
-if(NOT SYSTEMD_SYSTEM_UNIT_DIR)
-if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.28")
-pkg_get_variable(SYSTEMD_SYSTEM_UNIT_DIR systemd systemd_system_unit_dir
-DEFINE_VARIABLES prefix=${CMAKE_INSTALL_PREFIX})
-else()
-pkg_get_variable(SYSTEMD_PREFIX systemd prefix)
-pkg_get_variable(SYSTEMD_SYSTEM_UNIT_DIR systemd systemd_system_unit_dir)
-string(REPLACE "${SYSTEMD_PREFIX}" "${CMAKE_INSTALL_PREFIX}" SYSTEMD_SYSTEM_UNIT_DIR "${SYSTEMD_SYSTEM_UNIT_DIR}") endif() endif() pkg_get_variable(SYSTEMD_SYSTEM_UNIT_PATH systemd systemd_system_unit_path) if(NOT SYSTEMD_SYSTEM_UNIT_PATH MATCHES ".*:${SYSTEMD_SYSTEM_UNIT_DIR}:.*") message(WARNING SYSTEMD_SYSTEM_UNIT_DIR="${SYSTEMD_SYSTEM_UNIT_DIR}" is not in the system unit search path of current systemd installation) endif() install(FILES path/to/your.service DESTINATION ${SYSTEMD_SYSTEM_UNIT_DIR}) ``` - systemd user-level unit ```cmake find_package(PkgConfig) if(NOT SYSTEMD_USER_UNIT_DIR) if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.28") pkg_get_variable(SYSTEMD_USER_UNIT_DIR systemd systemd_user_unit_dir DEFINE_VARIABLES prefix=${CMAKE_INSTALL_PREFIX}) else() pkg_get_variable(SYSTEMD_PREFIX systemd prefix) pkg_get_variable(SYSTEMD_USER_UNIT_DIR systemd systemd_user_unit_dir) string(REPLACE "${SYSTEMD_PREFIX}" "${CMAKE_INSTALL_PREFIX}" SYSTEMD_USER_UNIT_DIR "${SYSTEMD_USER_UNIT_DIR}") endif() endif() pkg_get_variable(SYSTEMD_USER_UNIT_PATH systemd systemd_user_unit_path) if(NOT SYSTEMD_USER_UNIT_PATH MATCHES ".*:${SYSTEMD_USER_UNIT_DIR}:.*") message(WARNING SYSTEMD_USER_UNIT_DIR="${SYSTEMD_USER_UNIT_DIR}" is not in the user unit search path of current systemd installation) endif() install(FILES path/to/your.service DESTINATION ${SYSTEMD_USER_UNIT_DIR}) ``` - desktop file ```cmake install(FILES path/to/your.desktop DESTINATION ${CMAKE_INSTALL_DATADIR}/applications) ``` - icon corresponding to desktop file ```cmake install(FILES path/to/your.png
-DESTINATION ${CMAKE_INSTALL_DATADIR}/icons/hicolor/48x48/apps)
-# Add more size of .png icons here...
-
-install(FILES path/to/your.svg
-DESTINATION ${CMAKE_INSTALL_DATADIR}/icons/hicolor/scalable/apps)
-````
-
-### Configuration file
-
-#### desktop file
-
-It is **not** recommended\*\* to have `-` in the desktop file name. After removing the .desktop suffix, it should comply with the relevant specifications described in the application name section.
-
-- **Recommended** Fill in the [`TryExec` field][key-tryexec] to ensure that the desktop file is no longer valid after the application has been uninstalled
-- **Recommended** Fill in the [`WMClass` field][key-startupwmclass] to ensure that basic desktop environment functions such as the taskbar based on window and application matching can work properly
-- **Recommended** Use only the executable file name instead of the absolute path when filling in the [`Exec` field][key-exec]
-- **Not recommended** Use the absolute path when filling in the [`Icon` field][key-icon]
-
-[key-tryexec]: https://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html#key-tryexec
-[key-startupwmclass]: https://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html#key-startupwmclass
-
-[key-exec]: https://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html#key-exec [key-icon]: https://specifications.freedesktop.org/desktop-entry-spec/
-
-latest/recognized-keys.html#key-icon
-
-#### DBus service
-
-- **Recommend** that the file name of the service file is consistent with the Name field in the file
-- **Recommend** that the absolute path is used in the Exec field in the service file
-- **Recommend** that the SystemdService field is filled in
-- **Recommend** that the service name in the SystemdService field is consistent with the Name field
-- **Recommend** that the Name field ends with a number
-
-#### Systemd service
-
-- **Recommend** that the file name of the service file with BusName is consistent with BusName
-- **Recommend** that the absolute path is used in the ExecStart field
-
-When using absolute paths in the above configuration files, **hard-coded paths are **not recommended**. The path **should** be consistent with the final installation path. **Recommend\*\* that the template file be written in the project first, and the placeholder is used to represent the absolute path. The final configuration file is generated by replacing the placeholder through the build system.
-
-Here, taking the desktop file as an example, several examples of generating the final configuration file under common build systems are given.
-Assume that the final product `org.deepin.demo.desktop` has the following content:
-
-```ini
-[Desktop Entry]
-Name=demo
-Exec=/usr/bin/demo
-Type=Application
-Terminal=false
-```
-
-- Use Makefile as the build system.
-
-1. First write the template file `org.deepin.demo.desktop.in`, the content is as follows:
-
-```ini
-[Desktop Entry]
-Name=demo
-Exec=@BINDIR@/demo
-Type=Application
-Terminal=false
-```
-
-2. Write the corresponding makefile rules.
-
-```makefile
-DESKTOP_TEMPLATE = org.deepin.demo.desktop.in
-DESKTOP_FILE = org.deepin.demo.desktop
-
-# Replace placeholders and generate final .desktop file
-desktop: $(DESKTOP_TEMPLATE)
-sed -e "s/@BINDIR@/$(bindir)/g" \
-$(DESKTOP_TEMPLATE) > $(DESKTOP_FILE)
-
-install:
-$(INSTALL) -d "$(DESTDIR)$(datarootdir)"/applications
-$(INSTALL_PROGRAM) $(DESKTOP_FILE) "$(DESTDIR)$(datarootdir)"/applications/$(DESKTOP_FILE)
-
-clean:
-rm -f $(DESKTOP_FILE)
-
-all: desktop
-```
-
-- If using CMake as build system.
-
-1. Write the desktop template file.
-
-```desktop
-[Desktop Entry]
-Name=demo
-Exec=@CMAKE_INSTALL_BINDIR@/demo
-Type=Application
-Terminal=false
-```
-
-2. Write the corresponding cmake rules.
-
-```cmake
-set(DESKTOP_FILE "org.deepin.demo.desktop")
-# Use configure_file to replace placeholders
-configure_file(
-${CMAKE_CURRENT_SOURCE_DIR}/org.deepin.demo.desktop.in
-${CMAKE_CURRENT_BINARY_DIR}/${DESKTOP_FILE}
-@ONLY
-)
-install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${DESKTOP_FILE}
-DESTINATION ${CMAKE_INSTALL_DATADIR}/applications)
-```
-
-### Header files and link libraries
-
-Linglong's environment consists of up to three parts. Taking the compilation of `org.deepin.demo` under the `x86_64` architecture as an example, the default search path for header files and library files includes the following parts:
-
-| **Composition**    | **Package name**       | **Header file**                         | **Library files**                                                                           |
-| ------------------ | ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------- |
-| base               | org.deepin.base        | /usr/include                            | /usr/lib<br>/usr/lib/x86_64-linux-gnu                                                       |
-| runtime (optional) | org.deepin.runtime.dtk | /runtime/include                        | /runtime/lib<br>/runtime/lib/x86_64-linux-gnu                                               |
-| app                | org.deepin.demo        | /opt/apps/org.deepin.demo/files/include | /opt/apps/org.deepin.demo/files/lib<br>/opt/apps/org.deepin.demo/files/lib/x86_64-linux-gnu |
-
-Priority is in order from top to bottom. If a header file exists in both `org.deepin.base` and `org.deepin.demo`, the file in `org.deepin.base` will be matched first when used. The same applies to library files.
-
-The default search path is applicable to standard libraries or development libraries without configuration files. In actual build scenarios, development libraries usually provide configuration files to facilitate user compilation and linking. Developers should use this file in their own build system instead of relying on the default search path.
-
-Common configuration files include `.pc`, `.cmake`, etc. How to use it depends on the development library and the build system. Here are some examples of using configuration files in common build systems.
-
-#### Makefile
-
-##### Use `.pc` file
-
-```makefile
-# Common variables, inherit the environment variable CXXFLAGS and append content
-CXX = g++
-CXXFLAGS = $(CXXFLAGS) -Wall -Wextra -std=c++11
-# Get the content of the .pc file through the pkg-config tool
-# The return value is generally -I/path -lname type content
-PKG_CONFIG = pkg-config
-LIBS = $(shell $(PKG_CONFIG) --cflags --libs libname)
-
-TARGET = demo
-
-SRCS = main.cpp
-
-all: $(TARGET)
-
-# Provide the information provided by .pc to the compiler during construction
-$(TARGET): $(SRCS)
-$(CXX) $(CXXFLAGS) $(LIBS) -o $@ $^
-
-clean:
-rm -f $(TARGET)
-```
-
-#### CMake
-
-##### Using `.pc` files
-
-```cmake
-find_package(PkgConfig REQUIRED)
-pkg_check_modules(PackageAliasName REQUIRED IMPORTED_TARGET PackageName)
-
-# Add executable files
-add_executable(demo main.cpp)
-
-# Set the link library. The header file search path will be automatically expanded.
-target_link_libraries(demo PRIVATE PkgConfig::PackageAliasName)
-```
-
-##### Using `.cmake` files
-
-```cmake
-find_package(<PackageName> REQUIRED COMPONENTS <Component>)
-
-# Add executable files
-add_executable(demo main.cpp)
-
-# Set the link library. The header file search path will be automatically expanded.
-target_link_libraries(demo PRIVATE PackageName::Component)
-```
-
-Note:
-
-It is not recommended to hardcode the above default search paths directly in the project build configuration file.
-
-It is not recommended to overwrite environment variables such as CFLAGS/CXXFLAGS. Additional parameters should be appended to these variables.
-
-### Dependency introduction
-
-As mentioned in the section `Header files and link libraries`, the Linglong environment consists of multiple parts. If the content in the base or even the runtime cannot meet the requirements, the developer should introduce the missing dependencies on the APP side. The introduction method is to declare it under the `sources` field in the `linglong.yaml` file and write the corresponding installation or compilation rules under the `build` field.
-
-`sources` supports multiple file types, **allowing** to introduce source code or compiled binary files, even a deb. However, for the introduction of compiled binary files, developers must consider whether they are compatible with the current base or runtime.
-
-#### Use source code to introduce
-
-Introducing dependencies through source code is a **recommended** practice, which can greatly ensure the stability and maintainability of the build process. The disadvantage is that this may take developers a lot of time to write yaml files, because the dependencies may also have their own dependencies.
-
-_If developers find that the dependencies are complex and repeatedly used by other applications, they should consider integrating the dependencies into a runtime type package. _
-
-When the dependency is compiled in the Linglong environment, its configuration file is usually "reliable". After compilation and installation, developers can use it directly in the project.
-
-```yaml
-sources:
-- kind: git
-url: # app source url
-commit: # commit hash
-- kind: git
-url: # dependency source url
-commit: # commit hash
-build:
-# Compile dependency
-cd /project/your_dependency_name/
-cmake -Bbuild -DCMAKE_INSTALL_PREFIX=$PREFIX
-make install
-
-# Compile and install APP
-cd /project/your_app_name
-cmake -Bbuild -DCMAKE_INSTALL_PREFIX=$PREFIX
-make install
-```
-
-#### Import using deb
-
-This is a "shortcut". If the developer does not consider the subsequent updates of the application, this method can be used. The developer can use auxiliary tools to analyze the dependencies and import the dependencies involved in batches in sources.
-
-##### Use vscode linglong extension
-
-1. Install the aptly command line tool
-2. Search for linglong in the vscode extension store and install related plug-ins.
-3. Put the sources field at the end of linglong.yaml
-4. Add the gen_deb_source comment at the end of sources
-5. Press Ctrl+Shift+P to search and execute the linglong: Gen deb sources command
-
-After execution, the yaml file will automatically write the following content:
-
-```yaml
-build:
-# Unzip and import deb, install_dep file is automatically downloaded by the plugin
-bash ./install_dep linglong/sources "$PREFIX"
-
-# Compile and install APP
-sources:
-# Source code
-- kind: git
-url: # app source url
-commit: # commit hash
-# The following comments are generated and used by the plugin, retrieve libical-dev from the warehouse, analyze its dependencies, and automatically generate sources below the comments
-# linglong:gen_deb_source sources amd64 https://ci.deepin.com/repo/deepin/deepin-community/backup/rc2 beige main
-# linglong:gen_deb_source install libical-dev
-```
-
-Note:
-The installation prefix of the deb compilation product is `/usr`, and the `install_dep` script will automatically process the `.pc` file and replace `/usr` with `$PREFIX`. `xxx.cmake` type files cannot be processed in batches, and may not work properly if there is hard-coded path behavior.
-
-## Linglong
-
-This section mainly describes some special requirements of the Linglong package management system for applications.
-
-### Restrictions
-
-- Applications that need to be packaged through the Linglong package management system must be run as the user who starts the Linglong container (usually a normal user). Any form of privilege escalation mechanism is not available when the Linglong package management system runs applications, including but not limited to the SUID bit recorded in the file system and privilege escalation mechanisms based on file system extension attributes such as capabilities.
-- Linglong currently does not support packaging applications containing system-level systemd units.
-- It is **not recommended** to package desktop environment components such as launchers, file managers, resource managers, status bars, etc.
-
-### Specifications
-
-#### Application package name
-
-The package name of Linglong application **must** fully comply with the relevant provisions in the "Application Name" section above, except:
-
-- Application names are case-insensitive
-
-#### Application version number
-
-The application version number of Linglong package **must** be four groups of decimal numbers separated by `.`, for example, `1.0.0.0`.
-
-If the specified version number is less than four groups, 0 will be added to the back until the conditions are met, for example, `1.90` will be automatically added to `1.90.0.0`.
-
-The total length of the version number after automatically adding to four groups in the string sense **must** not exceed 256 bytes.
-
-#### Running environment
-
-Linglong application **must** select a base as the basic running environment. Available base:
-
-| **Base library** | **Package name/version** |
-| ---------------- | ------------------------ |
-| glibc(2.38)      | org.deepin.base/23.1.0.0 |
-
-If you need to use additional frameworks other than the base environment, you should use the appropriate runtime. Available runtime:
-
-| **Framework**       | **Package name/version**        |
-| ------------------- | ------------------------------- |
-| QT(5.15) + DTK(5.6) | org.deepin.runtime.dtk/23.1.0.0 |
-
-When using base or runtime, it is recommended to fill in the first three digits of the version number, such as '23.1.0', to facilitate subsequent updates. Filling in the full 4-digit version means that base or runtime updates are prohibited.
-
-#### Installation location
-
-During the build and installation process, Linglong's build tool will set the `$PREFIX` environment variable. The value of this environment variable **should** be `/opt/apps/${APPID}/files`, but it is not recommended to use its common value directly during the build and installation process. **Recommend** to always read the `$PREFIX` environment variable.
-
-For the application build and installation process, the only writable directories are
-
-1. The `/source` directory where the source code required for the build is placed
-
-2. The installation location, that is, the location specified by `$PREFIX`
-
-Installing files to other locations during the build process is **prohibited**, which usually causes write failures or the application cannot find these files at runtime.
-
-The following is an example of using the `$PREFIX` environment variable to control the application installation location when calling some common build systems:
-
-##### cmake
-
-```bash
-cd path/to/build && cmake path/to/source -DCMAKE_INSTALL_PREFIX="$PREFIX"
-```
-
-##### make
-
-```bash
-cd path/to/source && make prefix="$PREFIX"
-```
-
-##### meson
-
-```bash
-cd path/to/source && meson configure --prefix="$PREFIX" path/to/build
-```
-
-## Build products
-
-This section mainly describes the product composition and related functions after the application is successfully built.
-
-### Directory structure
-
-After the application is successfully built, Linglong's build tool will submit the product to the local cache. When distributing offline, it should be exported as a `.layer`
-or `.uab` type file.
-
-Build the product layer file by decompressing:
-
-```bash
-ll-builder extract org.deepin.demo_0.0.0.1_x86_64_binary.layer ./tmp
-```
-
-You can get the following directory structure:
-
-```plain
-./tmp
-├── entries
-│ └── share -> ../files/share
-├── files
-│ ├── bin
-│ │ └── demo
-│ ├── share
-│ │ ├── applications
-│ │ │ └── org.deepin.demo.desktop
-│ │ ├── icons
-│ │ │ └── hicolor
-│ │ │ └── scalable
-│ │ │ └── apps
-│ │ │ └── org.deepin.demo.svg │ │ ├── doc │ │ │ ├── changelog.gz │ │ │ └── copyright │ │ ├── mime │ │ │ └── packages │ │ │ └── org.deepin.demo.xml │ │ ├── locale │ │ │ └── zh_CN │ │ │ └── info.json │ │ └── services │ │ └── org.deepin.demo.xml │ └── libs │ └── libdemo.so.5.2.1 ├── info.json └── org.deepin.demo.install
-```
-
-When the application is running, these files or directories will be mapped to the following paths in the container:
-
-```plain
-/
-├── bin
-├── ...
-├── opt
-│ └── apps
-│ └── org.deepin.demo
-│ ├── files
-│ ├── entries
-│ ├── info.json
-│ └── org.deepin.demo.install
-└── var
-```
-
-#### info.json文件
-
-info.json is the application description file defined by Linglong. This file is automatically generated by the build tool and it **should** not be modified manually. Its content is as follows: ```json { "id": "org.deepin.demo", "arch": [ "x86_64" ], "base": "main:org.deepin.foundation/23.0.0/x86_64", "channel": "main", "command": [ "/opt/apps/org.deepin.demo/files/bin/demo" ], "description": "simple Qt demo.\n", "kind": "app", "module": "runtime", "name": "demo", "runtime": "main:org.deepin.Runtime/23.0.1/x86_64", "size": 118763, "version": "0.0.0.1"
-}
-
-````
-
-The following is a description of each field in info.json:
-
-`id`: package identifier, i.e., application package name.
-
-`arch`: package support architecture, currently supports the following CPU architectures.
-
-- `amd64`: Applicable to `x86_64` architecture `CPU`.
-
-- `loongarch64`: Applicable to the new version of Loongson series `CPU`.
-
-- `arm64`: Applicable to `ARM64` bit `CPU`.
-
-`base`: The basic environment used by the package when running.
-
-`channel`: Package distribution channel.
-
-`command`: The default startup command of the package.
-
-`description`: Description of the package.
-
-`kind`: Package category.
-
-`module`: Package module.
-
-`name`: Common name of the package.
-
-`runtime`: The environment used when the package runs.
-
-`size`: Package size.
-
-`version`: Application version, its format should meet the requirements described in the Application Version Number section.
-
-#### entries directory
-
-This directory is used to share application configuration files with the host (desktop environment). This directory usually has the following subdirectories:
-
-- entries/share/applications
-- entries/share/dbus-1/services
-- entries/share/systemd/user
-- entries/share/icons
-- entries/share/mime
-- entries/share/fonts
-
-The entries directory is automatically generated by the build tool. There is only one soft link named share in the directory. The link file points to the files/share in the upper directory.
-
-When the application is installed on the host, Linglong Package Manager will link all the files in it to the path added by Linglong to the `$XDG_DATA_DIRS` variable through the link file. That is, `/var/lib/linglong/entries/share/`.
-
-```bash $ ls /var/lib/linglong/entries/share/applications/ -l lrwxrwxrwx 1 deepin-linglong deepin-linglong 101 July 30 11:13 org.deepin.demo.desktop -> ../../../layers/main/org.deepin.demo/0.0.0.1/x86_64/runtime/entries/share/applications/org.deep
-in.demo.desktop
-````
-
-##### applications directory
-
-Place the application startup configuration file, that is, the .desktop file.
-
-```ini
-[Desktop Entry]
-Exec=demo
-Name=demo
-TryExec=demo
-Type=Application
-```
-
-When building, this file will be automatically modified to:
-
-```ini
-[Desktop Entry]
-Exec=/usr/bin/ll-cli run org.deepin.demo -- demo
-Name=demo
-TryExec=/usr/bin/ll-cli
-Type=Application
-```
-
-An application can have multiple desktop files.
-
-**Path correspondence:**
-
-| **Packaging path**                                 | **Installation path**                                     |
-| -------------------------------------------------- | --------------------------------------------------------- |
-| $PREFIX/share/applications/org.deepin.demo.desktop | $XDG_DATA_DIRS/share/applications/org.deepin.demo.desktop |
-
-##### dbus services directory
-
-The dbus service directory registered by the program, for example:
-
-```ini
-[D-BUS Service]
-Name=org.deepin.demo
-Exec=/opt/apps/org.deepin.demo/files/bin/demo --dbus
-```
-
-When building, this file will be automatically modified to:
-
-```ini
-[D-BUS Service]
-Name=org.deepin.demo
-Exec=/usr/bin/ll-cli run org.deepin.demo -- /opt/apps/org.deepin.demo/files/bin/demo --dbus
-```
-
-An application can be configured with multiple services, and the service name must be a subdomain.
-
-**Path correspondence:**
-
-| **Packaging path**                                   | **Installation path**                                       |
-| ---------------------------------------------------- | ----------------------------------------------------------- |
-| $PREFIX/share/services/org.deepin.demo.service       | $XDG_DATA_DIRS/dbus-1/service/org.deepin.demo.service       |
-| $PREFIX/share/services/org.deepin.demo.hello.service | $XDG_DATA_DIRS/dbus-1/service/org.deepin.demo.hello.service |
-
-##### User-level systemd service
-
-User-level service directory registered by the program, for example:
-
-```ini
-[Unit]
-Description = demo service
-After=user-session.target
-
-[Service]
-Type = simple
-ExecStart = demo
-
-[Install]
-WantedBy=user-session.target
-
-```
-
-This file will be automatically modified to when it is built ：
-
-```ini
-[Unit]
-Description = demo service
-After=user-session.target
-
-[Service]
-Type = simple
-ExecStart = ll-cli run org.deepin.demo -- demo
-
-[Install]
-WantedBy=user-session.target
-```
-
-Unlike dbus service, files installed to `$PREFIX/lib/systemd/user` will be automatically copied to `$PREFIX/share/systemd/user`.
-
-**Path correspondence:**
-
-| **Packaging path**                               | **Installation path**                               |
-| ------------------------------------------------ | --------------------------------------------------- |
-| $PREFIX/lib/systemd/user/org.deepin.demo.service | $XDG_DATA_DIRS/systemd/user/org.deepin.demo.service |
-
-##### icons directory
-
-The directory for storing application icons should be consistent with the system icons directory structure.
-
-**Path correspondence:**
-
-| **Packaging path**                                            | **Installation path**                                          |
-| ------------------------------------------------------------- | -------------------------------------------------------------- |
-| $PREFIX/share/icons/hicolor/scalable/apps/org.deepin.demo.svg | $XDG_DATA_DIRS/icons/hicolor/scalable/apps/org.deepin.demo.svg |
-| $PREFIX/share/icons/hicolor/24x24/apps/org.deepin.demo.png    | $XDG_DATA_DIRS/icons/hicolor/24x24/apps/org.deepin.demo.png    |
-| $PREFIX/share/icons/hicolor/16x16/apps/org.deepin.demo.png    | $XDG_DATA_DIRS/icons/hicolor/16x16/apps/org.deepin.demo.png    |
-
-##### mime directory
-
-MIME (Multipurpose Internet Mail Extensions) Multipurpose Internet Mail Extensions type. This directory is used to store mime configuration files. The files are in XML format and end with .xml.
-
-**Path correspondence:**
-
-| **Packaging path**                              | **Installation path**                            |
-| ----------------------------------------------- | ------------------------------------------------ |
-| $PREFIX/share/mime/packages/org.deepin.demo.xml | $XDG_DATA_DIRS/mime/packages/org.deepin.demo.xml |
-
-##### fonts directory
-
-Font storage path.
-
-#### files directory
-
-Store various files required by the application. There is no restriction on placing files in this directory, but it is recommended to place executable programs in the bin subdirectory. It is recommended that third-party libraries that applications or plug-ins depend on be placed in the /opt/apps/${id}/files/lib directory.
-
-#### .install file
-
-The org.deepin.demo.install file in the above example org.deepin.demo is a file automatically generated during the build process. This file is used to define which files should be installed in the binary module and can be used to trim the size of the final product of the software package.
-
-When the file is not defined in the same directory as linglong.yaml, all content is installed to the binary module according to the rules under build in linglong.yaml.
-
-Usage:
-
-After the first successful build, the .install file will be generated in the product and record all files installed to the binary module. Copy the file to the same directory as linglong.yaml, modify the content in the .install file and build again. Only the content noted in .install will be submitted to the binary module.
-
-## References
-
-[Desktop Application Packaging Specifications](https://github.com/linuxdeepin/deepin-specifications/blob/master/unstable/%E6%A1%8C%E9%9D%A2%E5%BA%94%E7%94%A8%E6%89%93%E5%8C%85%E8%A7%84%E8%8C%83.md)

docs/pages/en/guide/ll-builder/manifests.md

@@ -1,361 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Introduction to Build Configuration Files
-
-`linglong.yaml` is the description file for a linyaps project, recording relevant information required for building, such as the name, version, source address, and build dependencies of the build artifact.
-
-## Project Directory Structure
-
-```bash
-{project-root}
-├── linglong.yaml
-└── linglong
-
-{user-home}
-└── .cache
-    └── linglong-builder
-        ├── repo
-        └── layers
-```
-
-## Field Definitions
-
-The `linglong.yaml` file structure follows specific specifications. First, you need to declare the configuration file version at the top level:
-
-```yaml
-version: "1"
-```
-
-| Name    | Description                                                | Required |
-| ------- | ---------------------------------------------------------- | -------- |
-| version | The version of the build configuration file, currently '1' | Yes      |
-
-Next are the main configuration blocks. Among them, `package`, `base`, and `build` must be defined.
-
-### Package Metadata Configuration (`package`)
-
-Defines the basic information of the build artifact. This `package` configuration block is required.
-
-```yaml
-package:
-  id: org.deepin.calculator
-  name: deepin-calculator
-  version: 5.7.21.0 # Four-digit version number recommended
-  kind: app # or runtime
-  description: |
-    calculator for deepin os.
-  architecture: x86_64 # Optional
-  channel: stable # Optional
-```
-
-| Name         | Description                                                               | Required |
-| ------------ | ------------------------------------------------------------------------- | -------- |
-| id           | Unique name of the build artifact (e.g., `org.deepin.calculator`)         | Yes      |
-| name         | Name of the build artifact (e.g., `deepin-calculator`)                    | Yes      |
-| version      | Version of the build artifact, four digits recommended (e.g., `5.7.21.0`) | Yes      |
-| kind         | Type of the build artifact: `app` (Application), `runtime` (Runtime)      | Yes      |
-| description  | Detailed description of the build artifact                                | Yes      |
-| architecture | Target architecture of the build artifact (e.g., `x86_64`, `arm64`)       | No       |
-| channel      | Channel of the build artifact (e.g., `main`)                              | No       |
-
-### Command (`command`)
-
-Defines how to start the application. This is a list of strings, where the first element is usually the absolute path to the executable (relative to the container's interior), and subsequent elements are arguments passed to the executable.
-
-```yaml
-command:
-  - /opt/apps/org.deepin.calculator/files/bin/deepin-calculator
-  # - --some-argument # More arguments can be added
-```
-
-| Name    | Description                                                                                                       | Required |
-| ------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
-| command | Defines the executable path and its argument list for starting the application. Usually required for `kind: app`. | No       |
-
-### Base Environment (`base`)
-
-Specifies the minimum root filesystem required for building and running. This field is required.
-
-```yaml
-base: org.deepin.base/23.1.0
-```
-
-| Name | Description                                                                                       | Required |
-| ---- | ------------------------------------------------------------------------------------------------- | -------- |
-| base | Identifier for the base, format `id/version`. Version number supports three-digit fuzzy matching. | Yes      |
-
-### Runtime (`runtime`)
-
-Application runtime dependencies, which are also build dependencies.
-
-```yaml
-runtime: org.deepin.runtime.dtk/23.1.0
-```
-
-| Name    | Description                                              |
-| ------- | -------------------------------------------------------- |
-| id      | Unique name of the runtime                               |
-| version | Runtime version, three digits can fuzzy match the fourth |
-
-### Sources (`sources`)
-
-Describes the source information required for the project. `sources` is a list and can contain multiple source items. Fetched sources are stored by default in the `linglong/sources` directory at the same level as `linglong.yaml`.
-
-#### Git Type
-
-```yaml
-sources:
-  - kind: git
-    url: https://github.com/linuxdeepin/deepin-calculator.git
-    commit: d7e207b4a71bbd97f7d818de5044228c1a6e2c92 #Branch, tag or commit, used to precisely specify the commit
-    name: deepin-calculator.git # Optional, specifies the directory name after download
-```
-
-| Name   | Description                                                                          | Required (within a single source) |
-| ------ | ------------------------------------------------------------------------------------ | --------------------------------- |
-| kind   | `git`, indicates download using the git tool.                                        | Yes                               |
-| url    | Source repository address                                                            | Yes                               |
-| commit | Source code repository branch, tag, or hash value of a commit for accurate detection | Yes                               |
-| name   | Optional, specifies the subdirectory name under `linglong/sources` after download.   | No                                |
-
-#### File Type
-
-```yaml
-sources:
-  - kind: file
-    url: https://example.com/some-file.dat
-    digest: sha256:... # Recommended to provide sha256 hash
-    name: my-data.dat # Optional, specifies the filename after download
-```
-
-| Name   | Description                                                               | Required (within a single source) |
-| ------ | ------------------------------------------------------------------------- | --------------------------------- |
-| kind   | `file`, indicates direct file download.                                   | Yes                               |
-| url    | File download address                                                     | Yes                               |
-| digest | Optional, sha256 hash of the file, used for verification.                 | No                                |
-| name   | Optional, specifies the filename under `linglong/sources` after download. | No                                |
-
-#### Archive Type
-
-```yaml
-sources:
-  - kind: archive
-    url: https://github.com/linuxdeepin/deepin-calculator/archive/refs/tags/6.5.4.tar.gz
-    digest: 9675e27395891da9d9ee0a6094841410e344027fd81265ab75f83704174bb3a8 # Recommended to provide sha256 hash
-    name: deepin-calculator-6.5.4 # Optional, specifies the directory name after extraction
-```
-
-| Name   | Description                                                                                       | Required (within a single source) |
-| ------ | ------------------------------------------------------------------------------------------------- | --------------------------------- |
-| kind   | `archive`, downloads and automatically extracts the archive. Supports common compression formats. | Yes                               |
-| url    | Archive download address                                                                          | Yes                               |
-| digest | Optional, sha256 hash of the archive file, used for verification.                                 | No                                |
-| name   | Optional, specifies the directory name under `linglong/sources` after extraction.                 | No                                |
-
-#### DSC Type
-
-```yaml
-sources:
-  - kind: dsc
-    url: https://cdn-community-packages.deepin.com/deepin/beige/pool/main/d/deepin-calculator/deepin-calculator_6.0.1.dsc
-    digest: ce47ed04a427a887a52e3cc098534bba53188ee0f38f59713f4f176374ea2141 # Recommended to provide sha256 hash
-    name: deepin-calculator-dsc # Optional, specifies the directory name after download and extraction
-```
-
-| Name   | Description                                                                                    | Required (within a single source) |
-| ------ | ---------------------------------------------------------------------------------------------- | --------------------------------- |
-| kind   | `dsc`, handles Debian source package description files and associated files.                   | Yes                               |
-| url    | `.dsc` file download address                                                                   | Yes                               |
-| digest | Optional, sha256 hash of the `.dsc` file, used for verification.                               | No                                |
-| name   | Optional, specifies the directory name under `linglong/sources` after download and extraction. | No                                |
-
-### Export Rules (`exclude`/`include`)
-
-When exporting the built application to a UAB package, files to be trimmed are specified as shown in the example below:
-
-```yaml
-exclude:
-  - /usr/share/locale # Trim the entire folder
-  - /usr/lib/libavfs.a # Trim a single file
-
-include:
-  - /usr/share/locale/zh_CN.UTF-8 # Used with exclude to export only specific files under a folder
-```
-
-| Name    | Description                                                                                                                    |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| exclude | Absolute path within the container, can be a file or folder, used for exclusion.                                               |
-| include | Absolute path within the container, files that must be included in the UAB package (even if the parent directory is excluded). |
-
-### Build Rules (`build`)
-
-Describes how to compile and install the project in the build environment. This field is required, and its content is a multi-line string treated as a shell script.
-
-Describes the build rules.
-
-```yaml
-build: |
-  qmake -makefile PREFIX=${PREFIX} LIB_INSTALL_DIR=${PREFIX}/lib/${TRIPLET}
-  make
-  make install
-```
-
-| Name  | Description                                                                                | Required |
-| ----- | ------------------------------------------------------------------------------------------ | -------- |
-| build | Shell script executed during the build phase. Runs inside the container build environment. | Yes      |
-
-### Build Extensions (`buildext`)
-
-Optional field for defining extension behaviors for specific build stages. Currently mainly supports the `apt` extension for managing Debian package dependencies required for build and runtime.
-
-```yaml
-buildext:
-  apt:
-    build_depends: # Build-time dependencies, installed only in the build environment
-      - build-essential
-      - cmake
-      - qt6-base-dev
-    depends: # Runtime dependencies, included in the final application or runtime
-      - libqt6widgets6
-      - libglib2.0-0
-```
-
-| Name          | Description                                                                                  | Required |
-| ------------- | -------------------------------------------------------------------------------------------- | -------- |
-| buildext      | Container block for build extension configurations.                                          | No       |
-| apt           | Extension configuration using the apt package manager.                                       | No       |
-| build_depends | A list of strings listing packages needed at build time, not included in the final artifact. | No       |
-| depends       | A list of strings listing packages needed at runtime, included in the final artifact.        | No       |
-
-### Modules (`modules`)
-
-Optional field for splitting files installed under the `${PREFIX}` directory into different modules. Useful for on-demand downloads or providing optional features.
-
-```yaml
-modules:
-  - name: main # Main module name, usually same as or related to package.id
-    files: # List of files or directories included in this module (relative to ${PREFIX})
-      - bin/
-      - share/applications/
-      - share/icons/
-      - lib/ # Includes all libraries
-  - name: translations # Translation module
-    files:
-      - share/locale/
-  - name: extra-data # Optional data module
-    files:
-      - share/my-app/optional-data/
-```
-
-| Name    | Description                                                                                                 | Required                      |
-| ------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| modules | List defining the rules for splitting the application into modules.                                         | No                            |
-| name    | Name of the module. Each module requires a unique name.                                                     | Yes (within each module item) |
-| files   | A list of strings listing files or directories belonging to this module. Paths are relative to `${PREFIX}`. | Yes (within each module item) |
-
-**Note:** All files installed under `${PREFIX}` will be assigned to a module. When `modules` is not defined, the build system automatically generates default `binary` and `develop` modules.
-
-### Variables
-
-Describes variables that can be used during the build process.
-
-| Name    | Description                                                                                                                           |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| PREFIX  | Environment variable used under the `build` field; provides the installation path during build, e.g., /opt/apps/org.deepin.calculator |
-| TRIPLET | Environment variable used under the `build` field; provides a triplet containing architecture information, e.g., x86_64-linux-gnu     |
-
-## Complete Example
-
-### Build Application
-
-#### Calculator
-
-```yaml
-version: "1"
-
-package:
-  id: org.deepin.calculator
-  name: deepin-calculator
-  version: 5.7.21.0
-  kind: app
-  description: |
-    calculator for deepin os.
-
-command:
-  - /opt/apps/org.deepin.calculator/files/bin/deepin-calculator
-
-base: org.deepin.base/23.1.0
-runtime: org.deepin.runtime.dtk/23.1.0
-
-sources:
-  - kind: git
-    url: https://github.com/linuxdeepin/deepin-calculator.git
-    version: master
-    commit: d7e207b4a71bbd97f7d818de5044228c1a6e2c92
-
-  - kind: git
-    url: https://github.com/linuxdeepin/dde-qt-dbus-factory.git
-    version: master
-    commit: d952e1913172c5507af080f644a654f9ba5fed95
-
-build: |
-  # build dde-qt-dbus-factory
-  cd /project/linglong/sources/dde-qt-dbus-factory.git
-  qmake -makefile \
-        PREFIX=${PREFIX} \
-        LIB_INSTALL_DIR=${PREFIX}/lib/${TRIPLET} \
-        INSTALL_ROOT=${PREFIX}
-
-  make
-  make install
-
-  # build calculator
-  cd /project/linglong/sources/deepin-calculator.git
-  cmake -Bbuild \
-        -DCMAKE_INSTALL_PREFIX=${PREFIX} \
-        -DCMAKE_INSTALL_LIBDIR=${PREFIX}/lib/${TRIPLET} \
-        -DCMAKE_BUILD_TYPE=Release \
-        -DCMAKE_SAFETYTEST_ARG="CMAKE_SAFETYTEST_ARG_OFF" \
-        -DAPP_VERSION=5.7.21 \
-        -DVERSION=5.7.21
-
-  cmake --build build
-  cmake --build build --target install
-
-buildext:
-  apt:
-    # Extra packages depended on during build
-    build_depends: []
-    # Extra packages depended on during runtime
-    depends: []
-```
-
-### Build Root Filesystem
-
-```bash
-git clone git@github.com:linglongdev/org.deepin.foundation.git
-cd org.deepin.foundation
-bash build_base.sh beige amd64
-```
-
-This project is used to build the root filesystem used by Linglong. `beige` refers to the distribution codename, and `amd64` refers to the architecture.
-
-| Distribution Version | Architecture              |
-| -------------------- | ------------------------- |
-| eagle (UOS 20)       | amd64, arm64, loongarch64 |
-| beige (deepin 23)    | amd64, arm64              |
-
-### Build Runtime
-
-```bash
-git clone git@github.com:linglongdev/org.deepin.Runtime.git -b v23
-cd org.deepin.Runtime
-./depend-deb-list.sh | ./tools/download_deb_depend.bash
-ll-builder build --skip-fetch-source
-```
-
-Adds basic environments like Qt on top of the root filesystem.

docs/pages/en/guide/ll-builder/push.md

@@ -1,37 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Push UAB to Remote Repositories
-
-Use the `ll-builder push` command to push linyaps packages to linyaps remote repositories.
-
-View the help information for the `ll-builder push` command:
-
-```bash
-ll-builder push --help
-```
-
-Here is the output:
-
-```text
-Push linyaps app to remote repo
-Usage: ll-builder push [OPTIONS]
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-  --file FILE:FILE [./linglong.yaml]
-                              File path of the linglong.yaml
-  --repo-url URL              Remote repo url
-  --repo-name NAME            Remote repo name
-  --module TEXT               Push single module
-```
-
-The `ll-builder push` command reads the content of the `bundle` format package according to the file path and transfers the software data and `bundle` format package to the server.
-
-```bash
-ll-builder push <org.deepin.demo-1.0.0_x86_64.uab>
-```

docs/pages/en/guide/ll-builder/run.md

@@ -1,54 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Run Compiled App
-
-Use `ll-builder run` to run the compiled executable program.
-
-View the help information for the `ll-builder run` command:
-
-```bash
-ll-builder run --help
-```
-
-Here is the output:
-
-```text
-Run built linyaps app
-Usage: ll-builder run [OPTIONS] [COMMAND...]
-
-Positionals:
-  COMMAND TEXT ...            Enter the container to execute command instead of running application
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-  --file FILE:FILE [./linglong.yaml]
-                              File path of the linglong.yaml
-  --offline                   Only use local files
-  --modules modules ...       Run specified module. eg: --modules binary,develop
-  --debug                     Run in debug mode (enable develop module)
-```
-
-The `ll-builder run` command reads the operating system environment information related to the program according to the configuration file, constructs a container, and executes the program in the container without installation.
-
-```bash
-ll-builder run
-```
-
-If `ll-builder run` runs successfully, the output is as follows:
-
-```bash
-hello world
-```
-
-To facilitate debugging, use an additional `--exec /bin/bash` parameter to replace the default execution program after entering the container, such as:
-
-```bash
-ll-builder run --exec /bin/bash
-```
-
-With this option, `ll-builder` will enter the `bash` terminal after creating the container, and you can perform other operations inside the container.

docs/pages/en/guide/ll-cli/content.md

@@ -1,43 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Display App exported files
-
-Use `ll-cli content` to display the exported files.
-
-View the help information for the `ll-cli content` command:
-
-```bash
-ll-cli content --help
-```
-
-Here is the output:
-
-```text
-Display the exported files of installed application
-Usage: ll-cli content [OPTIONS] APP
-
-Positionals:
-  APP TEXT REQUIRED           Specify the installed application ID
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-
-If you find any problems during use,
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-Use `ll-cli content org.dde.calendar` to display the exported files of org.dde.calendar.
-
-Here is the output:
-
-```text
-/var/lib/linglong/entries/share/applications
-/var/lib/linglong/entries/share/applications/dde-calendar.desktop
-/var/lib/linglong/entries/share/metainfo
-/var/lib/linglong/entries/share/metainfo/org.deepin.calendar.metainfo.xml
-```

docs/pages/en/guide/ll-cli/exec.md

@@ -1,74 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Attach To Container
-
-Use `ll-cli exec` to enter the running linyaps container.
-
-View the help information for the `ll-cli exec` command:
-
-```bash
-ll-cli exec --help
-```
-
-Here is the output:
-
-```text
-Execute commands in the currently running sandbox
-Usage: ll-cli [OPTIONS] [SUBCOMMAND]
-
-Positionals:
-  INSTANCE TEXT REQUIRED      Specify the application running instance (you can get it by ps command)
-  COMMAND TEXT ...            Run commands in a running sandbox
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-  --working-directory PATH:DIR
-                              Specify working directory
-
-If you find any problems during use,
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-Open a new terminal window and run these commands:
-
-Example of using `ll-cli exec` to get inside org.dde.calendar container:
-
-1. Use `ll-cli ps` to get container ID:
-
-```bash
-App                                       ContainerID      Pid
-main:org.dde.calendar/5.14.5.0/x86_64     c3b5ce363172     539537
-```
-
-2. Enter the org.dde.calendar container
-
-```bash
-ll-cli exec main:org.dde.calendar/5.14.5.0/x86_64 /bin/bash
-```
-
-Use `ls -l /` to view the root directory structure. The output is as follows:
-
-```text
-lrwxrwxrwx   1 root   root        8  July 27 20:58 bin -> /usr/bin
-drwxr-xr-x   7 root   root      420  July 27 20:58 dev
-drwxr-xr-x 119 nobody nogroup 12288  July 27 20:37 etc
-drwxr-xr-x   3 root   root       60  July 27 20:58 home
-lrwxrwxrwx   1 root   root        8  July 27 20:58 lib -> /usr/lib
-lrwxrwxrwx   1 root   root       10  July 27 20:58 lib32 -> /usr/lib32
-lrwxrwxrwx   1 root   root       10  July 27 20:58 lib64 -> /usr/lib64
-lrwxrwxrwx   1 root   root       11  July 27 20:58 libx32 -> /usr/libx32
-drwxr-xr-x   2 root   root       40  July 27 20:58 ll-host
-drwxr-xr-x   3 root   root       60  July 27 20:58 opt
-dr-xr-xr-x 365 nobody nogroup     0  July 27 20:58 proc
-drwxr-xr-x   6 root   root      120  July 27 20:58 run
-drwxr-xr-x   7 nobody nogroup  4096  January  1  1970 runtime
-dr-xr-xr-x  13 nobody nogroup     0  July 21 16:43 sys
-drwxr-xr-x   3 root   root     4096  July 27 20:58 tmp
-drwxr-xr-x  15 nobody nogroup  4096  June 30 16:22 usr
-drwxr-xr-x  13 nobody nogroup  4096  June 30 16:23 var
-```

docs/pages/en/guide/ll-cli/info.md

@@ -1,58 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Display app information
-
-Use `ll-cli info` to display information about installed apps or runtimes.
-
-View the help information for the `ll-cli info` command:
-
-```bash
-ll-cli info --help
-```
-
-Here is the output:
-
-```text
-Display information about installed apps or runtimes
-Usage: ll-cli info [OPTIONS] APP
-
-Positionals:
-  APP TEXT REQUIRED           Specify the application ID, and it can also be a .layer file
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-
-If you find any problems during use,
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-Use `ll-cli info org.dde.calendar` to display information about org.dde.calendar.
-
-Here is the output:
-
-```text
-{
-    "arch": [
-        "x86_64"
-    ],
-    "base": "main:org.deepin.base/23.1.0/x86_64",
-    "channel": "main",
-    "command": [
-        "dde-calendar"
-    ],
-    "description": "calendar for deepin os.\n",
-    "id": "org.dde.calendar",
-    "kind": "app",
-    "module": "binary",
-    "name": "dde-calendar",
-    "runtime": "main:org.deepin.runtime.dtk/23.1.0/x86_64",
-    "schema_version": "1.0",
-    "size": 13483249,
-    "version": "5.14.5.1"
-}
-```

docs/pages/en/guide/ll-cli/install.md

@@ -1,103 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Install linyaps Apps
-
-Use `ll-cli install` to install linyaps apps.
-
-View the help information for the `ll-cli install` command:
-
-```bash
-ll-cli install --help
-```
-
-Here is the output:
-
-```text
-Installing an application or runtime
-Usage: ll-cli install [OPTIONS] APP
-
-Example:
-# install application by appid
-ll-cli install org.deepin.demo
-# install application by linyaps layer
-ll-cli install demo_0.0.0.1_x86_64_binary.layer
-# install application by linyaps uab
-ll-cli install demo_x86_64_0.0.0.1_main.uab
-# install specified module of the appid
-ll-cli install org.deepin.demo --module=binary
-# install specified version of the appid
-ll-cli install org.deepin.demo/0.0.0.1
-# install application by detailed reference
-ll-cli install stable:org.deepin.demo/0.0.0.1/x86_64
-
-
-Positionals:
-  APP TEXT REQUIRED           Specify the application ID, and it can also be a .uab or .layer file
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-  --module MODULE             Install a specific module
-  --force                     Force install the application
-  -y                          Automatically answer yes to all questions
-
-If you find any problems during use,
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-Example of using the `ll-cli install` command to install a linyaps app:
-
-```bash
-ll-cli install <org.deepin.calculator>
-```
-
-Enter the complete `appid` after `ll-cli install`. If the repository has multiple versions, the highest version will be installed by default.
-
-To install a specific version, append the corresponding version number after `appid`:
-
-```bash
-ll-cli install <org.deepin.calculator/5.1.2>
-```
-
-Here is the output of `ll-cli install org.deepin.calculator`:
-
-```text
-Install main:org.deepin.calculator/5.7.21.4/x86_64 success:100%
-```
-
-After the application is installed, the installation result will be displayed.
-
-The layer or UAB files exported using the `ll-builder export` command can be installed using the `ll-cli install` command.
-
-`.layer`
-
-```bash
-ll-cli install ./com.baidu.baidunetdisk_4.17.7.0_x86_64_runtime.layer
-```
-
-`.uab`
-There are two ways to install UAB files:
-
-- Use `ll-cli install` to install
-
-```bash
-ll-cli install com.baidu.baidunetdisk_x86_64_4.17.7.0_main.uab
-```
-
-- Execute the UAB file on a machine with linyaps environment to install the application.
-
-```bash
-./com.baidu.baidunetdisk_x86_64_4.17.7.0_main.uab
-```
-
-You can use the command `ll-cli list | grep com.baidu.baidunetdisk` to check if it has been installed successfully.
-
-Run the application using the following command.
-
-```bash
-ll-cli run com.baidu.baidunetdisk
-```

docs/pages/en/guide/ll-cli/introduction.md

@@ -1,43 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# ll-cli Introduction
-
-`ll-cli` is the command line tool of linyaps, used to install, uninstall, check, run, close, debug, and update linyaps applications.
-
-View the help information for the `ll-cli` command:
-
-```bash
-ll-cli --help
-```
-
-Here is the output:
-
-```text
-Run an application
-Usage: ll-cli run [OPTIONS] APP [COMMAND...]
-
-Example:
-# Run application by appid
-ll-cli run org.deepin.demo
-# Execute commands in the container rather than running the application
-ll-cli run org.deepin.demo bash
-ll-cli run org.deepin.demo -- bash
-ll-cli run org.deepin.demo -- bash -x /path/to/bash/script
-
-Positionals:
-  APP TEXT REQUIRED           Specify the application ID
-  COMMAND TEXT ...            Run commands in a running sandbox
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-  --file FILE:FILE            Pass file to applications running in a sandbox
-  --url URL                   Pass url to applications running in a sandbox
-
-If you find any problems during use,
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```

docs/pages/en/guide/ll-cli/kill.md

@@ -1,38 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Force Quit Running App
-
-Use `ll-cli kill` to force quit running linyaps apps.
-
-View the help information for the `ll-cli kill` command:
-
-```bash
-ll-cli kill --help
-```
-
-Here is the output:
-
-```text
-Stop running applications
-Usage: ll-cli kill [OPTIONS] APP
-
-Positionals:
-  APP TEXT REQUIRED           Specify the running application
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-
-If you find any problems during use,
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-Example of using the `ll-cli kill` command to force quit running linyaps apps:
-
-```bash
-ll-cli kill  org.deepin.calculator
-```

docs/pages/en/guide/ll-cli/prune.md

@@ -1,43 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Remove the unused base or runtime
-
-Use `ll-cli prune` to remove the unused base or runtime.
-
-View the help information for the `ll-cli prune` command:
-
-```bash
-ll-cli prune --help
-```
-
-Here is the output:
-
-```text
-Remove the unused base or runtime
-Usage: ll-cli prune [OPTIONS]
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-
-If you find any problems during use,
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-Use `ll-cli prune` to remove the unused base or runtime:
-
-Here is the output:
-
-```text
-Unused base or runtime:
-main:org.deepin.Runtime/23.0.1.2/x86_64
-main:org.deepin.foundation/20.0.0.27/x86_64
-main:org.deepin.Runtime/23.0.1.0/x86_64
-main:org.deepin.foundation/23.0.0.27/x86_64
-main:org.deepin.Runtime/20.0.0.8/x86_64
-5 unused base or runtime have been removed.
-```

docs/pages/en/guide/ll-cli/ps.md

@@ -1,42 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# View Running Apps
-
-Use `ll-cli ps` to view running linyaps apps.
-
-View the help information for the `ll-cli ps` command:
-
-```bash
-ll-cli ps --help
-```
-
-Here is the output:
-
-```text
-List running applications
-Usage: ll-cli ps [OPTIONS]
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-
-If you find any problems during use,
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-Use `ll-cli ps` to view running linyaps apps:
-
-```bash
-ll-cli ps
-```
-
-Here is the output of `ll-cli ps`:
-
-```text
-App                                       ContainerID      Pid
-main:org.dde.calendar/5.14.5.0/x86_64     c3b5ce363172     539537
-```

docs/pages/en/guide/ll-cli/query.md

@@ -1,73 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Search Apps From Remote
-
-Use `ll-cli search` to search app meta info from remote repository.
-
-View the help information for the `ll-cli search` command:
-
-```bash
-ll-cli search --help
-```
-
-Here is the output:
-
-```text
-Search the applications/runtimes containing the specified text from the remote repository
-Usage: ll-cli search [OPTIONS] KEYWORDS
-
-Example:
-# find remote app by name                                                                                                                                                                     ll-cli search org.deepin.demo
-# find remote runtime by name
-ll-cli search org.deepin.base --type=runtime
-# find all remote apps
-ll-cli search .
-# find all remote runtimes
-ll-cli search . --type=runtime
-
-Positionals:
-  KEYWORDS TEXT REQUIRED      Specify the Keywords
-
-Options:
-  -h,--help                   Print this help message and exit                                                                                                                                    --help-all                  Expand all help
-  --type TYPE [app]           Filter result with specific type. One of "runtime", "app" or "all"
-  --dev                       include development application in result
-
-If you find any problems during use,
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-Use `ll-cli search` to search app meta info from remote repository and local cache:
-
-```bash
-ll-cli search calculator
-```
-
-This command returns the info of all apps whose `appid` (appid is the app's unique identifier) contains the keyword "calculator", including the complete `appid`, application name, version, CPU architecture and description.
-
-Here is the output:
-
-```text
-id                               name                             version         arch        channel         module      description
-com.github.matrix-calculator.linyaps com.github.matrix-calculator     3.3.0.0         x86_64      main            runtime     convert from 3.3 build uos https://chinauos.com \Pyth...
-io.github.Calculator             Calculator                       0.0.1.0         x86_64      main            runtime     C++ GUI Calculator app.
-io.github.Calculator             Calculator                       0.0.1.1         x86_64      main            runtime     C++ GUI Calculator app.
-io.github.cupcalculator          cupcalculator                    1.1.2.0         x86_64      main            runtime     A program which calculates scorings from orienteering...
-io.github.cyber-calculator       cyber-calculator                 1.0.0.0         x86_64      main            runtime     CyberOS Calculator.
-io.github.galaxy-calculator      galaxy-calculator                0.0.2.0         x86_64      main            runtime     Galaxy Calculator: Given the size of the Galaxy you c...
-io.github.Huawei_modem_calculator_v2 Huawei_modem_calculator_v2       1.0.0.0         x86_64      main            runtime     Is it Huawei modem unlock code calculator from forth3...
-io.github.QT_GraphingCalculator  QT_GraphingCalculator            0.0.1.0         x86_64      main            runtime     Graphing calculator using QT and QTcustomplot
-io.github.Qt-calculator          Qt-calculator                    1.0.0.0         x86_64      main            runtime     A simple GUI calculator🧮 built using C++.
-io.github.SolarCalculator        SolarCalculator                  1.0.0.0         x86_64      main            runtime     Small app to calculate sunrise and sunset based on da...
-io.github.StringCalculator       StringCalculator                 0.0.1.0         x86_64      main            runtime     Full-featured calculator written in C++ with Qt frame...
-```
-
-If you need to look up Base and Runtime, you can use the following command:
-
-```bash
-ll-cli search . --type=runtime
-```

docs/pages/en/guide/ll-cli/run.md

@@ -1,65 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Run App
-
-Use `ll-cli run` command to start a linyaps application.
-
-View help for the `ll-cli run` command:
-
-```bash
-ll-cli run --help
-```
-
-Here is the output:
-
-```text
-Run an application
-Usage: ll-cli run [OPTIONS] APP [COMMAND...]
-
-Example:
-# run application by appid                                                                                                                                                                      ll-cli run org.deepin.demo
-# execute commands in the container rather than running the application
-ll-cli run org.deepin.demo bash
-ll-cli run org.deepin.demo -- bash
-ll-cli run org.deepin.demo -- bash -x /path/to/bash/script
-
-Positionals:
-  APP TEXT REQUIRED           Specify the application ID
-  COMMAND TEXT ...            Run commands in a running sandbox
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help                                                                                                                                                     --file FILE:FILE            Pass file to applications running in a sandbox
-  --url URL                   Pass url to applications running in a sandbox
-
-If you find any problems during use,
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-When the application is installed normally, use the `ll-cli run` command to start it:
-
-```bash
-ll-cli run org.deepin.calculator
-```
-
-Use the `ll-cli run` command to enter the specified program container:
-
-```bash
-ll-cli run org.deepin.calculator --exec /bin/bash
-```
-
-After entering, execute shell commands, such as `gdb`, `strace`, `ls`, `find`, etc.
-
-Since linyaps applications run in the container, they cannot be directly debugged in the conventional way. You need to run debugging tools in the container, such as `gdb`:
-
-```bash
-gdb /opt/apps/org.deepin.calculator/files/bin/deepin-calculator
-```
-
-The path is the absolute path of the application in the container.
-
-For more debugging information on linyaps application `release` version, please refer to: [Run FAQ](../debug/faq.md).

docs/pages/en/guide/ll-cli/uninstall.md

@@ -1,47 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Uninstall App
-
-Use `ll-cli uninstall` to uninstall linyaps apps.
-
-View the help information for the `ll-cli uninstall` command:
-
-```bash
-ll-cli uninstall --help
-```
-
-Here is the output:
-
-```text
-Uninstall the application or runtimes
-Usage: ll-cli uninstall [OPTIONS] APP
-
-Positionals:
-  APP TEXT REQUIRED           Specify the applications ID
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-  --module MODULE             Uninstall a specific module
-
-If you find any problems during use,
-You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-The command below gives an example of how to uninstall a linyaps app:
-
-```bash
-ll-cli uninstall <org.deepin.calculator>
-```
-
-Here is the output of `ll-cli uninstall org.deepin.calculator`:
-
-```text
-Uninstall main:org.deepin.calculator/5.7.21.4/x86_64 success:100%
-```
-
-After the command is executed successfully, the org.deepin.calculator will be uninstalled.

docs/pages/en/guide/ll-cli/update.md

@@ -1,54 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
-
-SPDX-License-Identifier: LGPL-3.0-or-later
--->
-
-# Update linyaps App
-
-Use `ll-cli upgrade` to upgrade linyaps apps.
-
-View the help information for the `ll-cli upgrade` command:
-
-```bash
-ll-cli upgrade --help
-```
-
-Here is the output:
-
-```text
-Upgrade the application or runtimes
-Usage: ll-cli upgrade [OPTIONS] [APP]
-
-Positionals:
-  APP TEXT                    Specify the application ID. If it is not specified, all applications will be upgraded
-
-Options:
-  -h,--help                   Print this help message and exit
-  --help-all                  Expand all help
-
-If you find any problems during use,                                                                                                                                                           You can report bugs to the linyaps team under this project: https://github.com/OpenAtom-Linyaps/linyaps/issues
-```
-
-Use `ll-cli upgrade` to upgrade all installed apps to the latest version:
-
-Here is the output:
-
-```text
-Upgrade main:org.dde.calendar/5.14.5.0/x86_64 to main:org.dde.calendar/5.14.5.1/x86_64 success:100%
-Upgrade main:org.deepin.mail/6.4.10.0/x86_64 to main:org.deepin.mail/6.4.10.1/x86_64 success:100%
-Please restart the application after saving the data to experience the new version.
-```
-
-Use `ll-cli upgrade org.deepin.calculator` to upgrade org.deepin.calculator to the latest version in the remote repository, such as:
-
-```bash
-ll-cli upgrade org.deepin.calculator
-```
-
-Here is the output:
-
-```text
-Upgrade main:org.deepin.calculator/5.7.21.3/x86_64 to main:org.deepin.calculator/5.7.21.4/x86_64 success:100%
-Please restart the application after saving the data to experience the new version.
-```

docs/pages/en/guide/ll-flatpak-convert/convert-flatpak.md

@@ -1,75 +0,0 @@
-## Convert Flatpak application
-
-The `ll-pica-flatpak convert` command is used to convert Flatpak applications into linyaps applications.
-
-View the help information for the `ll-pica-flatpak convert` command:
-
-```bash
-ll-pica-flatpak --help
-```
-
-Here is the output:
-
-```bash
-Convert the flatpak to uab. For example:
-Simple:
-        ll-pica-flatpak convert [flatpak name] --build
-
-Usage:
-  ll-pica-flatpak [command]
-
-Available Commands:
-  convert     Convert flatpak to uab
-  help        Help about any command
-
-Flags:
-  -h, --help      help for ll-pica-flatpak
-```
-
-Convert Flatpak application:
-
-```bash
-ll-pica-flatpak convert org.videolan.VLC --build
-```
-
-:::tip
-
-The package name for Flatpak is org.videolan.VLC. It can be found by visiting [https://flathub.org/](https://flathub.org/) => clicking on the app => selecting the Install drop-down menu => viewing the package name.
-
-ll-pica-flatpak uses ostree commands to retrieve the application data of org.videolan.VLC, and generates the corresponding linyaps base environment based on the runtime defined in the metadata.
-
-:::
-
-The application defaults to generating a UAB file. To export a layer file, you need to add the --layer parameter.
-
-```bash
-ll-pica-flatpak convert org.videolan.VLC --build --layer
-```
-
-To specify the version of the linyaps application to be generated, you need to add the --version parameter.
-
-```bash
-ll-pica-flatpak convert org.videolan.VLC --version "1.0.0.0" --build --layer
-```
-
-To specify the base environment and version of the linyaps application, you need to add the --base and --base-version parameters.
-
-```bash
-ll-pica-flatpak convert org.videolan.VLC --base "org.deepin.base.flatpak.kde" --base-version "6.7.0.2" --build --layer
-```
-
-The constructed products are as follows:
-
-```bash
-├── org.videolan.VLC
-│   ├── org.videolan.VLC_1.0.0.0_x86_64_develop.layer
-│   ├── org.videolan.VLC_1.0.0.0_x86_64_binary.layer
-    or
-│   ├── org.videolan.VLC_x86_64_1.0.0.0_main.uab
-```
-
-Layer files are divided into two categories: `binary` and `develop`. The `binary` includes the application's execution environment, while the `develop` layer, built upon the `binary`, retains the debugging environment.
-
-The UAB file is an offline distribution format used by the linyaps software package, which is not suitable for systems that can normally connect to the linyaps repository. Instead, one should utilize the delta transfer scheme provided by the linyaps software repository to reduce the network transmission size.
-
-Installing Layer Files and Running the Application Reference: [Install linyaps Apps](../ll-cli/install.md)

docs/pages/en/guide/ll-flatpak-convert/introduction.md

@@ -1,37 +0,0 @@
-# ll-flatpak-convert introduction
-
-This tool is provided by the `linglong-pica` package, which provides the ability to convert flatpak packages into linyaps packages, generate the linglong.yaml file required to build linyaps applications, and rely on ll-builder to implement application building and export.
-
-:::tip
-
-The conversion tool is merely an auxiliary tool and does not guarantee
-that the converted application will definitely run. It's possible that
-the software depends on libraries installed in paths or other
-configuration paths that do not align with those inside linyaps's
-internal structure, leading to the inability to execute. In such cases,
-you would need to use the command `ll-builder run --exec bash` to enter the container for debugging purposes.
-:::
-
-View the help information for the `ll-flatpak-convert` command:
-
-```bash
-ll-flatpak-convert --help
-```
-
-Here is the output:
-
-```bash
-Convert the flatpak to uab. For example:
-Simple:
-        ll-pica-flatpak convert [flatpak name] --build
-
-Usage:
-  ll-pica-flatpak [command]
-
-Available Commands:
-  convert     Convert flatpak to uab
-  help        Help about any command
-
-Flags:
-  -h, --help      help for ll-pica-flatpak
-```

docs/pages/en/guide/ll-pica/adep.md

@@ -1,35 +0,0 @@
-## Add dependency
-
-linyaps applications may lack package dependencies, which can currently
-be addressed by adding the corresponding package dependencies in the `linglong.yaml` file.
-
-The `ll-pica adep` command is used to add package dependencies to the `linglong.yaml` file.
-
-View the help information for the `ll-pica adep` command:
-
-```bash
-ll-pica adep --help
-```
-
-Here is the output:
-
-```bash
-Add dependency packages to linglong.yaml
-
-Usage:
-  ll-pica adep [flags]
-
-Flags:
-  -d, --deps string   dependencies to be added, separator is ','
-  -h, --help          help for adep
-  -p, --path string   path to linglong.yaml (default "linglong.yaml")
-
-Global Flags:
-  -V, --verbose   verbose output
-```
-
-```bash
-ll-pica adep -d "dep1,dep2" -p /path/to/linglong.yaml
-```
-
-If executing within the same path where the `linglong.yaml` file resides, there is no need to include the `-p` parameter.

docs/pages/en/guide/ll-pica/convert.md

@@ -1,76 +0,0 @@
-## Convert application
-
-The `ll-pica convert` command is used to generate the `linglong.yaml` file required by linyaps.
-
-View the help information for the `ll-pica convert` command:
-
-```bash
-ll-pica convert --help
-```
-
-Here is the output:
-
-```bash
-Convert deb to uab
-
-Usage:
-  ll-pica convert [flags]
-
-Flags:
-  -b, --build               build linglong
-  -c, --config string       config file
-      --exportFile string   export uab or layer (default "uab")
-  -h, --help                help for convert
-      --pi string           package id
-      --pn string           package name
-  -t, --type string         get app type (default "local")
-      --withDep             Add dependency tree
-  -w, --workdir string      work directory
-
-Global Flags:
-  -V, --verbose   verbose output
-```
-
-After executing the `ll-pica init -w w --pi com.baidu.baidunetdisk --pn com.baidu.baidunetdisk -t repo` command
-
-We only need to execute the command `ll-pica convert -w w -b` to convert the linyaps application. Here, we will use the `apt download` command to download the deb package named `com.baidu.baidunetdisk`.
-
-```bash
-ll-pica convert -c com.baidu.baidunetdisk_4.17.7_amd64.deb -w work -b
-```
-
-:::tip
-Here, the `apt download` command is used to download the deb package; however, the process may fail due to
-the deb package being excessively large or issues with obtaining the link. It is recommended to use the following command instead. If you use the following command directly, there is no need to execute the command `ll-pica init -w w --pi com.baidu.baidunetdisk --pn com.baidu.baidunetdisk -t repo`.
-:::
-
-```bash
-apt download com.baidu.baidunetdisk
-```
-
-```bash
-ll-pica convert -c com.baidu.baidunetdisk_4.17.7_amd64.deb -w w -b  --exportFile layer
-```
-
-- -w working directory.
-- -c The configuration method employed here utilizes deb files.
-- -b It indicates that a build is required; without adding this parameter, neither building nor exporting the layer file will take place.
-- --exportFile layer exports the output as a layer file. If you want to export a UAB file, use --exportFile uab.
-
-The constructed products are as follows:
-
-```bash
-├── package
-│   └── com.baidu.baidunetdisk
-│       ├── com.baidu.baidunetdisk_4.17.7.0_x86_64_develop.layer
-│       ├── com.baidu.baidunetdisk_4.17.7.0_x86_64_binary.layer
-	or
-│       ├── com.baidu.baidunetdisk_x86_64_4.17.7.0_main.uab
-└── package.yaml
-```
-
-Layer files are divided into two categories: `binary` and `develop`. The `binary` includes the application's execution environment, while the `develop` layer, built upon the `binary`, retains the debugging environment.
-
-The UAB file is an offline distribution format used by the linyaps software package, which is not suitable for systems that can normally connect to the linyaps repository. Instead, one should utilize the delta transfer scheme provided by the linyaps software repository to reduce the network transmission size.
-
-Installing Layer Files and Running the Application Reference: [Install linyaps Apps](../ll-cli/install.md)

docs/pages/en/guide/ll-pica/init.md

@@ -1,79 +0,0 @@
-# Initialization configuration
-
-The `ll-pica init` command is used to initialize the configuration information for the conversion package.
-
-View the help information for the `ll-pica init` command:
-
-```bash
-ll-pica init --help
-```
-
-Here is the output:
-
-```bash
-init config template
-
-Usage:
-  ll-pica init [flags]
-
-Flags:
-  -a, --arch string      runtime arch
-  -c, --config string    config file
-      --dv string        distribution Version
-  -h, --help             help for init
-      --pi string        package id
-      --pn string        package name
-  -s, --source string    runtime source
-  -t, --type string      get type
-  -v, --version string   runtime version
-  -w, --workdir string   work directory
-
-Global Flags:
-  -V, --verbose   verbose output
-```
-
-The specific command is as follows:
-
-```bash
-ll-pica init -w w --pi com.baidu.baidunetdisk --pn com.baidu.baidunetdisk -t repo
-```
-
-- -w working directory
-- --pi specifies the appid used by the linyaps application.
-- --pn specifies the correct package name that apt can search for.
-- -t specifies the type to retrieve, `repo` fetches from the apt repository.
-
-The specific configuration is as follows:
-
-```bash
-runtime:
-  version: 23.0.1
-  base_version: 23.0.0
-  source: https://community-packages.deepin.com/beige/
-  distro_version: beige
-  arch: amd64
-file:
-  deb:
-    - type: repo
-      id: com.baidu.baidunetdisk
-      name: com.baidu.baidunetdisk
-```
-
-Detailed Field Reference: [Manifests](../manifests.md)
-
-:::tip
-The default configuration file `~/.pica/config.json`
-is set to use Deepin v23. If you need to specify UOS 20 as the BASE and
-RUNTIME, modify the default configuration using the following command.
-Please update the link below, [https://professional-packages.chinauos.com/desktop-professional](https://professional-packages.chinauos.com/desktop-professional), to a version that does not require authentication.
-:::
-
-```bash
-ll-pica init --rv "20.0.0" --bv "20.0.0" -s "https://professional-packages.chinauos.com/desktop-professional" --dv "eagle/1070"
-```
-
-If it needs to be used on arm64, the default architecture needs to be modified.
-
-```bash
-ll-pica init -a "arm64"
-```

docs/pages/en/guide/ll-pica/install.md

@@ -1,29 +0,0 @@
-# Linglong conversion tool (pica) installation
-
-This tool provides the ability to convert deb, appimage, and flatpak packages to linyaps packages, generates the linglong.yaml file required to build linyaps applications, and relies on ll-builder to implement application building and export.
-
-## deepin v23
-
-```bash
-sudo apt install linglong-pica
-```
-
-## UOS 1070
-
-```bash
-echo "deb [trusted=yes] https://ci.deepin.com/repo/deepin/deepin-community/linglong-repo/ unstable main" | sudo tee -a /etc/apt/sources.list
-sudo apt update
-sudo apt install linglong-pica
-
-```
-
-## Arch Linux
-
-Install via [AUR repository](https://aur.archlinux.org/packages/linglong-pica) or [self-hosted repository](https://github.com/taotieren/aur-repo).
-
-```bash
-# AUR
-yay -Syu linglong-pica
-# OR self-hosted
-sudo pacman -Syu linglong-pica
-```

docs/pages/en/guide/ll-pica/introduction.md

@@ -1,52 +0,0 @@
-# ll-pica Introduction
-
-This tool currently provides the capability to convert DEB packages into linyaps packages. Generate the required `linglong.yaml` file for building linyaps applications and rely on `ll-builder` to implement application build and export. Only software packages that comply with the [app store packaging standards](https://doc.chinauos.com/content/M7kCi3QB_uwzIp6HyF5J) are supported for conversion.
-
-:::tip
-
-The conversion tool is merely an auxiliary tool and does not guarantee
-that the converted application will definitely run. It's possible that
-the software depends on libraries installed in paths or other
-configuration paths that do not align with those inside linyaps's
-internal structure, leading to the inability to execute. In such cases,
-you would need to use the command `ll-builder run --exec bash` to enter the container for debugging purposes.
-:::
-
-The following situations are likely to result in unsuccessful execution:
-
-1. Packages related to Wine, Android emulators, input methods, and security software cannot be converted.
-2. The package utilizes preinst, postinst, prerm, and postrm scripts.
-3. It is necessary to read configuration files from a fixed path.
-4. Need to obtain root permissions.
-
-View the help information for the `ll-pica` command:
-
-```bash
-ll-pica --help
-```
-
-Here is the output:
-
-```bash
-Convert the deb to uab. For example:
-Simple:
- ll-pica init -c package -w work-dir
- ll-pica convert -c package.yaml -w work-dir
- ll-pica help
-
-Usage:
-  ll-pica [command]
-
-Available Commands:
-  adep        Add dependency packages to linglong.yaml
-  convert     Convert deb to uab
-  help        Help about any command
-  init        init config template
-
-Flags:
-  -h, --help      help for ll-pica
-  -V, --verbose   verbose output
-  -v, --version   version for ll-pica
-
-Use "ll-pica [command] --help" for more information about a command.
-```

docs/pages/en/guide/ll-pica/manifests.md

@@ -1,56 +0,0 @@
-# Manifests
-
-The `package.yaml` file serves as the foundation for ll-pica to convert packages into DEB format. It encompasses essential information such as the base and runtime versions used in the build process, as well as the DEB package that is to be converted.
-
-## Project directory structure
-
-```bash
-{workdir}
-├── package
-│   └── {appid}
-│       ├── linglong
-│       ├── linglong.yaml
-│       └── start.sh
-└── package.yaml
-```
-
-## Field definitions
-
-### Build environment
-
-Conversion build environment for DEB packages to linyaps packages.
-
-```bash
-runtime:
-  version: 23.0.1
-  base_version: 23.0.0
-  source: https://community-packages.deepin.com/beige/
-  distro_version: beige
-  arch: amd64
-```
-
-| name           | description                                                                                |
-| -------------- | ------------------------------------------------------------------------------------------ |
-| version        | Runtime version, A three-digit number can be loosely matched with a potential fourth digit |
-| base_version   | Base version, A three-digit number can be loosely matched with a potential fourth digit    |
-| source         | Obtain the sources used by the dependencies of a deb package.                              |
-| distro_version | The codename of a distribution."                                                           |
-| arch           | The architecture required by a deb package.                                                |
-
-### Deb package information
-
-```bash
-file:
-  deb:
-    - type: local
-      id: com.baidu.baidunetdisk
-      name: com.baidu.baidunetdisk
-      ref: /tmp/com.baidu.baidunetdisk_4.17.7_amd64.deb
-```
-
-| name | description                                                                                                               |
-| ---- | ------------------------------------------------------------------------------------------------------------------------- |
-| type | The method of acquisition: 'local' requires specifying a reference, while 'repo' does not require specifying a reference. |
-| id   | Unique name of the build product                                                                                          |
-| name | Specify the correct package name that apt can search for.                                                                 |
-| ref  | The path of the deb package on the host machine.                                                                          |

docs/pages/en/guide/publishing/mirrors.md

@@ -0,0 +1,69 @@
+# Linyaps Repository Mirror Function Design
+
+The `enable-mirror` and `disable-mirror` commands have been added to ll-cli and ll-builder to enable and disable mirror functionality.
+
+When mirror functionality is enabled for a repository, the ostree config file is updated to add the contenturl configuration item:
+
+```diff
+url=$repo_url/repos/$repo_name
+gpg-verify=false
+http2=false
++ contenturl=mirrorlist=$repo_url/api/v2/mirrors/$repo_name
+```
+
+After adding the contenturl configuration item, ostree will prioritize using contenturl to download static files such as files, while url is only used to obtain metadata like summary. The contenturl supports three protocols: file://, http://, and https://.
+
+If `mirrorlist=` is added before the url, ostree will first obtain a line-separated mirror list from the url, then select mirrors from the mirror list for downloading files. See the [ostree_pull](#ostree-pull-steps) section for specific logic.
+
+/api/v2/mirrors/$repo_name is an API interface of the Linyaps server that obtains the client's country through the client IP, gets the corresponding country's mirror list from the configuration file, and then returns it to ostree. This implements the function of automatically diverting repository file downloads based on the user's country.
+
+## Mirror Site Configuration
+
+Linyaps mirror sites only need to provide https access to repository static files. Linyaps repositories support both rsync and ostree synchronization protocols.
+
+### Using rsync Synchronization Configuration
+
+The advantage is fast synchronization speed, the disadvantage is that it needs to synchronize from mirror sites or official repositories that support the rsync protocol.
+
+```bash
+rsync rsync://rsync.linyaps.org.cn/repos/stable $www_root/repos/stable
+```
+
+### Using ostree Synchronization Configuration
+
+The advantage is that no protocol support is needed, and repositories can be synchronized from any mirror site. The disadvantage is slower synchronization speed.
+
+Save the following script and name it sync.sh, then execute `sh sync.sh https://mirror-repo-linglong.deepin.com/repos/stable/ $www_root/repos/stable`
+
+```bash
+#!/bin/bash
+set -e
+url=$1
+dir=$2
+echo sync $url to $dir
+sleep 3
+ostree init --repo=$dir --mode archive
+ostree --repo=$dir remote add --if-not-exists --no-sign-verify remote $url
+for ref in $(ostree --repo=$dir remote refs remote); do
+    echo pull $ref;
+    ostree --repo=$dir pull --mirror $ref;
+done
+```
+
+## ostree pull Steps
+
+### Determine Mirror Availability
+
+When pulling, ostree first obtains the mirror list from contenturl, then gets the /config file from each url. If the /config file cannot be obtained, the mirror is considered unavailable. If the /config file is obtained, the mirror is considered available. If no mirrors are available, the pull fails.
+
+### Get summary File
+
+ostree gets the summary file from url. If the summary file cannot be obtained, or the summary file does not contain the ref, the pull fails.
+
+### delta-indexes File Acquisition
+
+ostree gets delta-indexes from each available mirror. If the mirror server returns 4xx or 5xx, it gets delta-indexes from the next mirror. If the last mirror returns 5xx, the pull fails. If the last mirror returns 4xx, it skips the delta step and directly pulls files.
+
+### files File Acquisition
+
+ostree gets files from available mirrors in order. If the mirror server returns 403, 404, or 410, the error is considered unrecoverable and the pull fails. If the mirror server returns other error codes, it uses the next mirror to get files. If all mirrors cannot get files, the pull fails.

docs/pages/en/guide/publishing/repositories.md

@@ -0,0 +1,13 @@
+# Repository
+
+The official Linyaps repository is the primary mechanism for publishing applications so that users can install applications more conveniently. Currently, after installing the Linyaps components, this repository is used by default.
+
+- Some basic concepts of repositories have been introduced in [Repository Basic Concepts](../reference/basic-concepts.md);
+- Adding, updating, and deleting repositories can be done using the `ll-cli repo` command. For specific usage, please refer to [ll-cli-repo(1)](../reference/commands/ll-cli/repo.md);
+- Using self-hosted repositories: To be supplemented;
+
+## Publishing Updates
+
+Linyaps repositories are similar to Git repositories in that they store each version of an application by recording the differences between each version. This makes updates efficient because when performing an update, only the differences (or "deltas") between the two versions need to be downloaded.
+
+When a new version of an application is added to the repository, it immediately becomes available to users. The app store can automatically check for and install new versions. Using the command line requires manually running `ll-cli list --upgradable` to check and use `ll-cli update` to update installed applications to the new version.

docs/pages/en/guide/publishing/uab.md

@@ -0,0 +1,142 @@
+# UAB Application Publishing
+
+This document supplements the relevant content for application publishing using UAB (Universal Application Bundle).
+
+## What is UAB
+
+UAB (Universal Application Bundle) is a cross-distribution application packaging format designed to solve the compatibility issues of Linux applications across different distributions. It packages applications and all their dependencies into a single file, enabling one-click installation and operation.
+
+## UAB Publishing Advantages
+
+- **Cross-distribution compatibility**: Applications packaged in UAB format can run on different Linux distributions
+- **One-click installation**: Users only need to download one file to complete the installation
+- **Dependency self-contained**: All dependencies are included in the package, avoiding dependency conflicts
+- **Easy to distribute**: A single file is easy to transmit and share
+
+## Creating UAB Packages
+
+### Prerequisites
+
+Before creating a UAB package, you need to:
+
+1. Complete the development and testing of the application
+2. Ensure the application can run normally in the Linyaps environment
+3. Prepare the application's metadata information (name, version, description, etc.)
+
+### Build Process
+
+1. Use `ll-builder` to build the application:
+
+```bash
+ll-builder build
+```
+
+2. Export as UAB format:
+
+```bash
+ll-builder export --type=uab
+```
+
+3. The generated UAB file will be saved in the current directory, with the file name format: `{app-id}_{version}_{arch}.uab`
+
+## UAB File Structure
+
+The UAB file is essentially a compressed package containing:
+
+- Application executable files and resource files
+- All dependent libraries and runtime environments
+- Application metadata and configuration files
+- Installation scripts and desktop entry files
+
+## Publishing UAB Applications
+
+### Method 1: Direct Distribution
+
+You can directly distribute the generated UAB file to users through the following methods:
+
+- Official website download
+- GitHub Releases
+- Third-party software download sites
+- USB flash drive or other storage media
+
+### Method 2: Repository Publishing
+
+Upload the UAB file to the Linyaps repository:
+
+```bash
+ll-builder push --repo=your-repo
+```
+
+### Method 3: App Store Publishing
+
+Submit the application to the app store through the official channel, and the app store will automatically handle the UAB package and provide it to users for download.
+
+## User Installation
+
+Users can install UAB applications in the following ways:
+
+### Command Line Installation
+
+```bash
+ll-cli install ./your-app.uab
+```
+
+### Graphical Interface Installation
+
+Double-click the UAB file, and the system will automatically call the Linyaps installer to complete the installation.
+
+## UAB Application Management
+
+### View Installed Applications
+
+```bash
+ll-cli list
+```
+
+### Update Applications
+
+```bash
+ll-cli update your-app-id
+```
+
+### Uninstall Applications
+
+```bash
+ll-cli uninstall your-app-id
+```
+
+## Best Practices
+
+1. **Version Management**: Use semantic versioning (Semantic Versioning) to manage application versions
+2. **Testing**: Test on multiple distributions to ensure compatibility
+3. **Documentation**: Provide detailed installation and usage instructions
+4. **Updates**: Regularly update applications and dependencies
+5. **Security**: Ensure that applications and dependencies do not contain security vulnerabilities
+
+## Common Issues
+
+### Installation Failure
+
+- Check if the UAB file is complete
+- Confirm that the system has Linyaps installed
+- View error logs to locate the problem
+
+### Runtime Errors
+
+- Check if dependencies are complete
+- Confirm system compatibility
+- View application logs
+
+### Update Issues
+
+- Check network connection
+- Confirm repository configuration
+- View update logs
+
+## Technical Support
+
+If you encounter problems during the UAB application publishing process, you can:
+
+1. View the official documentation: [Linyaps Documentation](https://linglong.dev)
+2. Submit an Issue: [GitHub Issues](https://github.com/OpenAtom-Linyaps/linyaps/issues)
+3. Community Support: Join the Linyaps community for discussion

docs/pages/en/guide/reference/basic-concepts.md

@@ -0,0 +1,24 @@
+# Linyaps Basic Concepts Introduction
+
+## Base
+
+Base can be understood as a lightweight "minimal system image" that contains core operating system components (such as glibc, bash, and other basic toolchains), providing a consistent underlying dependency environment for applications across different distributions. It ensures that applications running on different Linux distributions (such as Debian, Ubuntu, etc.) do not need to rely on the host system's libraries, avoiding compatibility issues caused by environmental differences.
+
+For detailed information, see: [Base Component](./runtime.md).
+
+## Runtime
+
+Runtime is the environment that applications depend on during execution, containing specific framework libraries required for application operation. For example, some applications may depend on specific graphical interface frameworks (such as DTK), browser engines (such as QT WebEngine), etc. Runtime provides the corresponding runtime environment support for these applications, ensuring they can start and run properly. It works together with the Base environment to ensure applications can run stably and efficiently across different Linux distributions. Runtime and Base use a hierarchical dependency relationship - applications must first select an appropriate Base, then choose a compatible Runtime. This design ensures cross-distribution compatibility for applications.
+
+For detailed information, see: [Runtime Component](./runtime.md).
+
+## Sandbox
+
+When using Linyaps, each application is built and runs in an isolated environment called a "sandbox". Each sandbox contains Base, Runtime, and the application itself.
+Out of necessity, some resources within the sandbox need to be exported to the host system for use. These exported resources include the application's desktop files and icons.
+
+## Repository
+
+Linyaps applications and runtimes are typically stored and distributed using repositories, which behave very similarly to Git repositories: a Linyaps repository can contain multiple objects, each of which is versioned, allowing for upgrades or even downgrades.
+Each system using Linyaps can be configured to access any number of remote repositories. Once a system is configured to access a 'remote', it can inspect, search the contents of the remote repository, and use it as a source for applications and runtimes.
+When performing updates, new versions of applications and runtimes are downloaded from the relevant remote repositories. Similar to Git, only the parts that have changed between versions are downloaded, making the process very efficient.