sync docs automatically.

OpenAtom-Linyaps · Oct 15, 2024 · c11d42e · c11d42e
1 parent 8f1f4f1
commit c11d42e
Show file tree

Hide file tree

Showing 14 changed files with 490 additions and 9 deletions.
diff --git a/en/guide/ll-appimage-convert/convert-appimage.md b/en/guide/ll-appimage-convert/convert-appimage.md
@@ -0,0 +1,86 @@
+<!--
+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 linglong 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 specified app name( `--name` option), it will as a root directory of the linglong project, where the `linglong.yaml` file is located. and it supports two convert methods:
+
+1. you can use `--file` option to convert to linglong application according to specified appimage file;
+2. you can use `--url` and `--hash` option to convert to linglong application according to specified appimage url and hash value;
+3. you can use `--layer` option to export `.layer`, or it will export `.uab` default.
+
+`Tips: When the linglong version is greater than 1.5.7, the default convert package format is `.uab`, if you want to export a `.layer` file, you need to add the --layer option.`
+
+you can use `--output` option to generate config file( `linglong.yaml` ) of linglong project and a script of build linglong `.layer`(`.uab`)
+then you can execute script file to generate after you modify the `linglong.yaml` file. if you do not specify this option, it will export linglong `.layer` or linglong `.uab` directly.
+
+Take converting [BrainWaves](https://github.com/makebrainwaves/BrainWaves/releases/download/v0.15.1/BrainWaves-0.15.1.AppImage) into linglong `.layer` through `--url` as an example, the main steps as follows:
+
+Specify the relevant parameters of the linglong package you want to convert, you can acquire `io.github.brainwaves_0.15.1.0_x86_64_runtime.layer` or `io.github.brainwaves_0.15.1.0_x86_64_runtime.uab` wait a moment.
+
+```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` needs to be installed and verified. install the layer file and run the application, you can refer to: [Install the application](../ll-cli/install.md)
diff --git a/en/guide/ll-appimage-convert/introduction.md b/en/guide/ll-appimage-convert/introduction.md
@@ -0,0 +1,42 @@
+# ll-appimage-convert introduction
+
+This tool is provided by the `linglong-pica` package.which provides the ability to convert appimage packages into Linglong packages, generate the linglong.yaml file required to build Linglong 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 LingLong'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 the 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.
+```
diff --git a/en/guide/ll-builder/convert.md b/en/guide/ll-builder/convert.md
@@ -4,6 +4,8 @@ SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
 SPDX-License-Identifier: LGPL-3.0-or-later
 -->
 
+**Tips: This document is applicable to linglong versions below 1.6.3. if the version of linglong is above 1.6.3, please refer to the document: [Conversion appimage application](../ll-appimage-convert/convert-appimage.md)**
+
 # convert `appimage` format( `.appimage` or `.AppImage` ) pkg to linglong format( `.layer` or `.uab` ) pkg
 
 Use `ll-builder convert` to convert `appimage` format( `.appimage` or `.AppImage` ) pkg to linglong format( `.layer` or `.uab` ) pkg.

diff --git a/en/guide/ll-builder/manifests.md b/en/guide/ll-builder/manifests.md
@@ -152,7 +152,7 @@ package:
     calculator for deepin os.
 
 command:
-  - /opt/apps/org.deepin.demo/files/bin/deepin-calculator
+  - /opt/apps/org.deepin.calculator/files/bin/deepin-calculator
 
 base: org.deepin.foundation/23.0.0
 runtime: org.deepin.Runtime/23.0.1
@@ -166,6 +166,7 @@ sources:
   - kind: git
     url: https://github.com/linuxdeepin/dde-qt-dbus-factory.git
     version: master
+    commit: d952e1913172c5507af080f644a654f9ba5fed95
 
 build: |
   # build dde-qt-dbus-factory
@@ -182,7 +183,7 @@ build: |
   cd /project/linglong/sources/deepin-calculator.git
   cmake -Bbuild \
         -DCMAKE_INSTALL_PREFIX=${PREFIX} \
-        -DCMAKE_INSTALL_LIBDIR=${PREFIX}/lib/${TRIPLET}
+        -DCMAKE_INSTALL_LIBDIR=${PREFIX}/lib/${TRIPLET} \
         -DCMAKE_BUILD_TYPE=Release \
         -DCMAKE_SAFETYTEST_ARG="CMAKE_SAFETYTEST_ARG_OFF" \
         -DAPP_VERSION=5.7.21 \

diff --git a/en/guide/ll-flatpak-convert/convert-flatpak.md b/en/guide/ll-flatpak-convert/convert-flatpak.md
@@ -0,0 +1,75 @@
+## Conversion Flatpak application
+
+The `ll-pica-flatpak convert` command is used to convert Flatpak applications into Linglong 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 Linglong 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 Linglong 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 Linglong 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 LingLong software package, which is not suitable for systems that can normally connect to the LingLong repository. Instead, one should utilize the delta transfer scheme provided by the LingLong software repository to reduce the network transmission size.
+
+Installing Layer Files and Running the Application Reference：[Install Linglong Apps](../ll-cli/install.md)
diff --git a/en/guide/ll-flatpak-convert/introduction.md b/en/guide/ll-flatpak-convert/introduction.md
@@ -0,0 +1,37 @@
+# ll-flatpak-convert introduction
+
+This tool is provided by the `linglong-pica` package.which provides the ability to convert flatpak packages into Linglong packages, generate the linglong.yaml file required to build Linglong 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 LingLong'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 [command]
+
+Available Commands:
+  convert     Convert flatpak to uab
+  help        Help about any command
+
+Flags:
+  -h, --help      help for ll-pica-flatpak
+```
diff --git a/en/guide/start/how_to_use.md b/en/guide/start/how_to_use.md
@@ -29,7 +29,7 @@ cd org.deepin.calculator
 Edit the linglong.yaml file using a text editor.
 
 ```bash
-version: "1"
+version: '1'
 
 package:
   id: org.deepin.calculator
@@ -54,6 +54,7 @@ sources:
   - kind: git
     url: https://github.com/linuxdeepin/dde-qt-dbus-factory.git
     version: master
+    commit: d952e1913172c5507af080f644a654f9ba5fed95
 
 build: |
   # build dde-qt-dbus-factory
@@ -70,7 +71,7 @@ build: |
   cd /project/linglong/sources/deepin-calculator.git
   cmake -Bbuild \
         -DCMAKE_INSTALL_PREFIX=${PREFIX} \
-        -DCMAKE_INSTALL_LIBDIR=${PREFIX}/lib/${TRIPLET}
+        -DCMAKE_INSTALL_LIBDIR=${PREFIX}/lib/${TRIPLET} \
         -DCMAKE_BUILD_TYPE=Release \
         -DCMAKE_SAFETYTEST_ARG="CMAKE_SAFETYTEST_ARG_OFF" \
         -DAPP_VERSION=5.7.21 \

diff --git a/guide/ll-appimage-convert/convert-appimage.md b/guide/ll-appimage-convert/convert-appimage.md
@@ -0,0 +1,85 @@
+<!--
+SPDX-FileCopyrightText: 2024 UnionTech Software Technology Co., Ltd.
+
+SPDX-License-Identifier: LGPL-3.0-or-later
+-->
+
+## 转换appimage应用
+
+转换 `appimage` 包格式( `.appimage` 或 `.AppImage` ) 到玲珑包格式( `.layer` 或 `.uab` )
+
+查看`ll-appimage-convert convert` 命令的帮助信息：
+
+```bash
+ll-appimage-convert convert --help
+```
+
+`ll-appimage-convert convert` 命令的帮助信息如下：
+
+```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
+```
+
+`ll-appimage-convert convert` 命令会根据指定的应用名称（ `--name` 选项）生成一个目录，该目录会作为玲珑项目的根目录，即 `linglong.yaml` 文件所在的位置。它支持两种转换方法：
+
+1. 你可以使用 `--file` 选项将指定的 `appimage` 文件转换为玲珑包文件；
+2. 你可以使用 `--url` 和 `--hash` 选项将指定的 `appimage url` 和 `hash` 值转换为玲珑包文件;
+3. 你可以使用 `--layer` 选项导出 `.layer` 格式文件，否则将默认导出 `.uab` 格式文件。
+
+`Tips: 在玲珑版本大于1.5.7时，convert 默认导出 uab 包，如果想要导出 layer 文件，需要加上 --layer 参数`
+
+你可以使用 `--output` 选项生成玲珑项目的配置文件( `linglong.yaml` )和构建玲珑 `.layer` ( `.uab` )的脚本文件
+然后你可以执行该脚本去生成对应的玲珑包当你修改 `linglong.yaml` 配置文件后。如果不指定该选项，将直接导出对应的玲珑包。
+
+以通过 `--url` 选项将 [BrainWaves](https://github.com/makebrainwaves/BrainWaves/releases/download/v0.15.1/BrainWaves-0.15.1.AppImage) `appimage` 文件转换为玲珑 `.layer` 文件为例，主要步骤如下：
+
+指定要转换的玲珑包的相关参数，稍等片刻后你就可以得到 `io.github.brainwaves_0.15.1.0_x86_64_runtime.layer` 或者 `io.github.brainwaves_0.15.1.0_x86_64_runtime.uab` 包文件。
+
+```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
+```
+
+以通过 `--file` 选项将 `BrainWaves-0.15.1.AppImage` 转换为玲珑 `.uab` 为例，主要步骤如下：
+
+```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
+```
+
+转换完成的目录结构如下:
+```text
+├── io.github.brainwaves_x86_64_0.15.1.0_main.uab
+├── linglong
+└── linglong.yaml
+```
+
+以通过 `--file` 选项将 `BrainWaves-0.15.1.AppImage` 转换为玲珑 `.layer` 为例，主要步骤如下：
+```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
+```
+
+转换完成的目录结构如下:
+```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` 或 `.layer` 文件验证
+导出的`.uab`或者`.layer`需要安装后进行验证，安装 layer 文件和运行应用参考：[安装应用](../ll-cli/install.md)