警告！此规范内容是不稳定版本，可能会发生破坏兼容性的更新。当无法保障向下兼容时，将会升级此文档的主版本号，如从“1.0”更新到“2.0”。反之，普通更新只会升级次版本号，如“1.0”更新到“1.1”，其对“1.0”版本向下兼容。请在使用前确认此文档的版本号，并为将来可能发生的兼容性变化做好准备。

桌面应用打包规范

维护者：
- 吴荣杰 wurongjie@uniontech.com
- 周涛 zhoutao@uniontech.com
修改日期：2021.06.1
版本：0.1
议题：#19

1. 、应用标识（包名）

应用标识/包名(appid)是应用的唯一标识，桌面应用只接受使用倒置域名规则命名，如:

text

org.desktopspec.demo

org.desktopspec.demo

必须使用已经拥有的域名作为应用名称。如果使用未拥有的域名作为前缀，可能会引起该域名拥有者进行申诉，导致你的应用被删除。

2. 、应用安装

2.1. 、安装路径

应用的全部安装文件必须在如下目录：

/opt/apps/${appid}/

-- 说明：禁止使用 deb 的 postinst 等钩子对系统进行修改，包含这些脚本的软件包都无法上架 --

3. 、目录结构

text

├── DEBIAN
│   ├── control
│   └── md5sums
└── opt
    └── apps
        └── org.desktopspec.demo
            ├── entries
            │   ├── icons
            │   │   └── hicolor
            │   │       └── scalable
            │   │           └── apps
            │   │               └── org.desktopspec.demo.svg
            │   ├── mime
            │   │   └── packages
            │   │       └── org.desktopspec.demo.xml
            │   ├── locale
            │   │   └── zh_CN
            │   │       └── info.json
            │   └── services
            │   │   └── org.desktopspec.demo.xml
            ├── files
            │   ├── bin
            │   │   └── org.desktopspec.demo
            │   ├── doc
            │   │   ├── changelog.gz
            │   │   └── copyright
            │   └── libs
            │       └── libdemo.so.5.2.1
            └── info.json

├── DEBIAN
│   ├── control
│   └── md5sums
└── opt
    └── apps
        └── org.desktopspec.demo
            ├── entries
            │   ├── icons
            │   │   └── hicolor
            │   │       └── scalable
            │   │           └── apps
            │   │               └── org.desktopspec.demo.svg
            │   ├── mime
            │   │   └── packages
            │   │       └── org.desktopspec.demo.xml
            │   ├── locale
            │   │   └── zh_CN
            │   │       └── info.json
            │   └── services
            │   │   └── org.desktopspec.demo.xml
            ├── files
            │   ├── bin
            │   │   └── org.desktopspec.demo
            │   ├── doc
            │   │   ├── changelog.gz
            │   │   └── copyright
            │   └── libs
            │       └── libdemo.so.5.2.1
            └── info.json

应用根目录下面有 entries/files 两个目录和一个 info.json 文件.

3.1. 、 info.json 文件

info.json 文件是应用的描述文件，使用 json 格式， info.json 内容如下：

json

{
  "appid": "org.desktopspec.demo",
  "name": "Demo",
  "version": "5.0.0.0",
  "arch": ["amd64", "mips64"],
  "permissions": [
    "autostart",
    "notification",
    "trayicon",
    "clipboard",
    "account",
    "bluetooth",
    "camera",
    "audio_record",
    "installed_apps"
  ]
}

{
  "appid": "org.desktopspec.demo",
  "name": "Demo",
  "version": "5.0.0.0",
  "arch": ["amd64", "mips64"],
  "permissions": [
    "autostart",
    "notification",
    "trayicon",
    "clipboard",
    "account",
    "bluetooth",
    "camera",
    "audio_record",
    "installed_apps"
  ]
}

info.json 的 JSON Schema

json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "appid": {
      "type": "string",
      "maxLength": 255,
      "minLength": 3,
      "pattern": "^[a-zA-Z0-9][-a-zA-Z0-9]{0,62}(\\.[a-zA-Z0-9][-a-zA-Z0-9]{0,62})+$"
    },
    "name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 3
    },
    "version": {
      "type": "string",
      "minLength": 3
    },
    "arch": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "all",
          "amd64",
          "i386",
          "arm64",
          "mips64",
          "sw_64",
          "loongarch64"
        ]
      }
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "autostart",
          "notification",
          "trayicon",
          "clipboard",
          "account",
          "bluetooth",
          "camera",
          "audio_record",
          "installed_apps"
        ]
      }
    }
  },
  "required": [
    "appid",
    "arch",
    "categories",
    "exec",
    "icon",
    "name",
    "version",
    "desktop"
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "appid": {
      "type": "string",
      "maxLength": 255,
      "minLength": 3,
      "pattern": "^[a-zA-Z0-9][-a-zA-Z0-9]{0,62}(\\.[a-zA-Z0-9][-a-zA-Z0-9]{0,62})+$"
    },
    "name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 3
    },
    "version": {
      "type": "string",
      "minLength": 3
    },
    "arch": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "all",
          "amd64",
          "i386",
          "arm64",
          "mips64",
          "sw_64",
          "loongarch64"
        ]
      }
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "autostart",
          "notification",
          "trayicon",
          "clipboard",
          "account",
          "bluetooth",
          "camera",
          "audio_record",
          "installed_apps"
        ]
      }
    }
  },
  "required": [
    "appid",
    "arch",
    "categories",
    "exec",
    "icon",
    "name",
    "version",
    "desktop"
  ]
}

info.json 文件中各个字段的说明如下： appid：应用标识

name：应用名称

version：应用版本，格式为 {MAJOR}.{MINOR}.{PATCH}.{BUILD},所有版本号均为纯数字

arch：应用支持架构，当前桌面系统支持如下 CPU 架构

all：适用所有架构的包
i386：适用 i386 架构 CPU
amd64：适用 x86_64 架构 CPU
mips64：适用龙芯系列 CPU
loongarch64：适用新版龙芯系列 CPU
arm64：适用 ARM64 位 CPU
sw_64：适用申威 CPU

permissions：应用权限描述。

autostart：允许自启动
notification：允许使用通知
trayicon：运行显示托盘图标
clipboard：允许使用剪切板
account：允许读取登录用户信息
bluetooth：允许使用蓝牙设备
camera：允许使用视频设备
audio_record：允许进行录音
installed_apps：允许读取安装软件列表

desktop：应用桌面图标根据该字段自动生成 desktop 文件，字段说明：

字段	说明
name	显示的名称
icon	显示的图标，可使用图标文件的绝对路径或使用相对名称以便于系统根据主题规范查找对应的图标文件
exec	程序的入口,一般为程序的可执行二进制，后期会被沙箱启动。
comment	程序说明。
terminal	是否为终端应用。
mimeType	程序支持的文件关联，用于关联文件的打开方式。
keywords	程序关键字，一般用于搜索。
categories	程序的的类型，用于程序分类。
prefersNonDefaultGPU	声明优先使用独立显卡，一般为游戏应用需要。
path	程序工作目录

开发者需要注意，应用只允许使用普通用户权限启动，禁止应用以任何形式获取 root 权限。

3.2. 、entries 目录

存放程序的各种入口文件，一般在 entries 目录下有 autostart、services、icons、mime、locale 等目录.开发者请按规范将对应的文件放到指定的目录进行打包，安装完成之后系统会自动链接到对应目录。

3.2.2. 、autostart 目录

程序自启动入口文件。注意如果需要程序自启动，请在 info.json 文件中配置打开自启动权限，即设置 autostart 为 true。

自启动权限为高风险权限，用户可以在不告知应用的情况下关闭应用的自启动权限。

示例：

打包路径	安装路径
entries/autostart/org.desktopspec.demo.desktop	$XDG_CONFIG_DIRS/autostart/org.desktopspec.demo.desktop

3.2.3. 、services 目录

程序注册的 dbus 服务目录，例如:

ini

[D-BUS Service]
Name=org.desktopspec.demo
Exec=/opt/apps/org.desktopspec.demo/files/bin/org.desktopspec.demo --dbus

[D-BUS Service]
Name=org.desktopspec.demo
Exec=/opt/apps/org.desktopspec.demo/files/bin/org.desktopspec.demo --dbus

一个应用允许配置多个 service，服务名必须是子域名 示例：

打包路径	安装路径
entries/services/org.desktopspec.demo.service	$XDG_DATA/dbus-1/service/org.desktopspec.demo.service
entries/services/org.desktopspec.demo.hello.service	$XDG_DATA/dbus-1/service/org.desktopspec.demo.hello.service

3.2.4. 、icons 目录

放置应用图标 icons，目录结构与系统 icons 目录结构保持一致即可，建议路径为 icons/hicolor/scalable/apps/org.desktopspec.demo.svg，使用 svg 格式图标。参考图标文件格式规范

如果使用非矢量格式，请按照分辨率来放置图标，如：

text

entries/icons/hicolor/24x24/apps/org.desktopspec.demo.png
entries/icons/hicolor/16x16/apps/org.desktopspec.demo.png

entries/icons/hicolor/24x24/apps/org.desktopspec.demo.png
entries/icons/hicolor/16x16/apps/org.desktopspec.demo.png

支持的分辨率包括:16/24/32/48/128/256/512。 示例：

打包路径	安装路径
entries/icons/hicolor/scalable/apps/org.desktopspec.demo.svg	$XDG_DATA/icons/hicolor/scalable/apps/org.desktopspec.demo.svg
entries/icons/hicolor/24x24/apps/org.desktopspec.demo.png	$XDG_DATA/icons/hicolor/24x24/apps/org.desktopspec.demo.png
entries/icons/hicolor/16x16/apps/org.desktopspec.demo.png	$XDG_DATA/icons/hicolor/16x16/apps/org.desktopspec.demo.png

3.2.6. 、mime 目录

MIME(Multipurpose Internet Mail Extensions)多用途互联网邮件扩展类型。该目录用于存放 mime 配置文件,目录结构与系统 mime 目录结构保持一致即可，文件是 XML 格式,以.xml 结尾。

示例：

打包路径	安装路径
entries/mime/packages/org.desktopspec.demo.xml	$XDG_DATA/mime/packages/org.desktopspec.demo.xml

3.2.7. 、fonts 目录

存放字体和配置文件，包含 files 和 conf 两个子目录。 files 用来保存字体文件目录结构与系统 fonts 目录结构保持一致即可。
conf 目录用来存放字体配置，conf 目录内的文件会自动安装到 /etc/fonts/conf.d。字体配置文件添加字体目录指向 fonts/files

示例：

打包路径	安装路径
entries/fonts/conf.d/57-wenquanyi.conf	/etc/fonts/conf.d/57-wenquanyi.conf

3.3. 、files 目录

存放应用程序需要的各种文件，对于该目录放置文件并无限制，但是建议将可执行程序放置到 bin 子目录。应用程序或者插件依赖的第三方库推荐放置在/opt/apps/${appid}/files/lib 目录，启动时建议使用脚本添加环境变量启动，不允许安装到系统目录。

说明：lib 目录下的库请不要相互依赖，否则可能会导致应用**启动**插件库加载不正常。

4. 、文件系统权限

4.1. 、包文件权限

为保护应用程序的安全，避免在软件安装文件被普通用户修改，要求安装包内的文件要设置所属用户和所属组都为 root，目录权限为 0755，文件权限为 0644。

4.2. 、系统目录

系统分区为只读状态，主要用于为应用提供基本的运行依赖库。请不要依据系统目录内容来做任何特性，后期系统将会将应用运行在沙箱中，系统目录中的内容将会都不可信。

4.3. 、用户目录

软件包不允许直接向$HOME目录直接写入文件，后期系统将会使用沙箱技术重新定向$HOME,任何依赖该特性的行为都可能失效。

建议应用使用如下环境变量写入数据和配置：

text

$XDG_DATA_HOME

$XDG_CONFIG_HOME

$XDG_CACHE_HOME

$XDG_DATA_HOME

$XDG_CONFIG_HOME

$XDG_CACHE_HOME

以下目录可能需要用户同意才能进行写入

text

XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOCUMENTS_DIR="$HOME/Documents"
XDG_DOWNLOAD_DIR="$HOME/Downloads"
XDG_MUSIC_DIR="$HOME/Music"
XDG_PICTURES_DIR="$HOME/Pictures"
XDG_PUBLICSHARE_DIR="$HOME/.Public"
XDG_TEMPLATES_DIR="$HOME/.Templates"
XDG_VIDEOS_DIR="$HOME/Videos"

XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOCUMENTS_DIR="$HOME/Documents"
XDG_DOWNLOAD_DIR="$HOME/Downloads"
XDG_MUSIC_DIR="$HOME/Music"
XDG_PICTURES_DIR="$HOME/Pictures"
XDG_PUBLICSHARE_DIR="$HOME/.Public"
XDG_TEMPLATES_DIR="$HOME/.Templates"
XDG_VIDEOS_DIR="$HOME/Videos"

关于目录的定义，可以参考：

https://specifications.freedesktop.org/basedir-spec/basedir-spec-0.6.html

桌面应用打包规范 ​

1. 、应用标识（包名） ​

2. 、应用安装 ​

2.1. 、安装路径 ​

3. 、目录结构 ​

3.1. 、 info.json 文件 ​

3.2. 、entries 目录 ​

3.2.2. 、autostart 目录 ​

3.2.3. 、services 目录 ​

3.2.4. 、icons 目录 ​

3.2.6. 、mime 目录 ​

3.2.7. 、fonts 目录 ​

3.3. 、files 目录 ​

4. 、文件系统权限 ​

4.1. 、包文件权限 ​

4.2. 、系统目录 ​

4.3. 、用户目录 ​

桌面应用打包规范

1. 、应用标识（包名）

2. 、应用安装

2.1. 、安装路径

3. 、目录结构

3.1. 、 info.json 文件

3.2. 、entries 目录

3.2.2. 、autostart 目录

3.2.3. 、services 目录

3.2.4. 、icons 目录

3.2.6. 、mime 目录

3.2.7. 、fonts 目录

3.3. 、files 目录

4. 、文件系统权限

4.1. 、包文件权限

4.2. 、系统目录

4.3. 、用户目录