# debtokaiming转换文档

**Repository Path**: kaiming-docs/debtokaiming-docs

## Basic Information

- **Project Name**: debtokaiming转换文档
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-07
- **Last Updated**: 2025-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# deb转换工具简介

开明deb包自动转化工具是一款为麒麟操作系统生态设计的命令行程序,可以将基于Debian/Ubuntu开发的deb安装包快速转换为符合开明规范的应用包格式. 工具通过自动化解析,格式重构,自动填充等功能,降低开发者手动适配的工作量,保障应用向开明包的平滑迁移。

## 一、快速入门

### 1.安装

使用deb转换工具前需确保：

- 可以访问互联网。
- 已安装deb转换工具及开明工具。

通过麒麟开发者平台下载deb转换工具和开明工具：

[麒麟软件-开发者平台](https://developer.kylinos.cn/develop/page?pageId=25)

下载完成后执行以下命令安装deb转换工具：

`sudo apt install ./debtokaiming_*.deb`

### 2.功能说明

deb转换工具是将deb软件包直接导出为开明应用的脚本。主要面向软件开发人员及爱好者，提供一种方法便捷的将deb包转为开明应用。

deb转换工具debtokaiming可以将桌面deb应用转换为开明桌面应用；此外，工具支持hostmode模式，该模式可将符合开明原生部署规范的deb包转换为kaiming格式的ok包，此模式生成的ok包在安装时，会依据原deb安装路径及内容直接部署在宿主机环境运行。关于hostmode模式的具体使用条件及操作方法可查看文档第三章。

### 3.注意事项

- 部分类型的deb包无法转换。

    转换工具目前不支持lib库的转换,被转换的deb包中需要含有desktop文件。

- 安全类应用转换

    安装类应用需使用debtokaiming的hostmode模式转换。

## 二、转换工具使用介绍

通过一个示例介绍使用转换工具debtokaiming将deb工具转换为开明包的实际过程。可通过debtokaiming --help查看帮助信息。

### 1.命令格式
转换工具debtokaiming使用格式：
`debtokaiming [hostmode]  <选项> `
 **hostmode模式:**  `debtokaiming hostmode <选项>`，其中<选项>是模式hostmode下需要传递的参数，可支持参数详细查看第三章第3节。

### 2.转换过程示例

#### 2.1.执行转换

假设目录下已有deb包ukui-clock_1.0.1_amd64.deb并且安装好deb转换工具和开明的base以及runtime后，在当前目录执行命令：

`sudo debtokaiming ./ukui-clock_1.0.1_amd64.deb `

如有特殊需要，可追加参数，如下：

`sudo debtokaiming ./ukui-clock_1.0.1_amd64.deb --id top.kylin.test --id-version 1.0.2`

该命令将生成的开明包id修改为top.kylin.test，开明包版本号修改为1.0.2。全部支持的参数参考第二章第3节。

#### 2.2.结果验证

等待命令执行结束后，查看当前目录，可以发现目录下生成文件夹build和ok，分别存放转换过程文件和开明包。进入ok目录，可以看到转换完成的开明包。

执行以下命令，可将开明包安装到系统中：

`sudo kaiming install top.openkylin.Clock-x86_64-1.0.1-stable-binary-squashfs.ok`

#### 2.3.转换日志

默认只在终端显示必要命令，若要查看更详细的命令执行日志。可在转换命令的执行目录下，查看.km-debapp目录下对应的.log文件。

### 3.参数解析

 **--id  id**
 	
设置生成的ok包名称,默认会根据deb包的Package 字段自动填充为：top.kylin.Package。例如:

`debtokaiming tree.deb --id top.test.tree。`

 **--id-version  id-version**  		
			
设置生成的ok包的版本号, 默认会根据deb包的版本号转换为符合开明版本号要求的字段。例如:

`debtokaiming tree.deb --id-version 2.0.3。`

 **--comp algorithm** 

选择压缩算法，当前支持：`gzip lzma lzo lz4 xz zstd`。例如：

`debtokaiming tree.deb --comp xz`。

 **--base  base**
 								
base为制作出的kaiming包依赖的base名称，默认为空。例如：

`debtokaiming tree.deb --base top.openkylin.base`。

 **--base-version  base-version**
			
指定base的版本，默认为空。例如：

`debtokaiming tree.deb --base top.openkylin.base --base-version 1.0.2`。

 **--runtime  runtime**
  	 					
runtime 为制作出的kaiming包依赖的runtime，默认为空，需要和--base一起被指定。例如:

`debtokaiming tree.deb --base top.openkylin.base --runtime top.openkylin.ukui`。

 **--runtime-version  runtime-version** 
 	
指定runtime 的版本, 默认为空。例如：

`debtokaiming tree.deb --base top.openkylin.base --runtime top.openkylin.ukui --runtime 1.0.2`。

 **--desktop  desktop**
  	 					
指定desktop文件，默认command 会根据deb包的/usr/share/application/desktop文件名称自动填充。例如:
 
`debtokaiming app.deb --desktop test.desktop`。

 **--sources-file  file** 
 							
替换默认软件源的文件,文件内容必须符合apt软件源规范,可以添加 [ trusted=yes ] 尝试处理gpg错误。例如:

`debtokaiming app.deb --sources-file v11.list`。

 **--env  key=value**
  							
设置程序运行时的相关环境变量。例如：

`debtokaiming app.deb --env XDG_SESSION_TYPE=x11`。

 **--extra-deb  deb** 
 							
和app一起安装的deb包，用来作为依赖补充，可以指定多个。例如:
 
`debtokaiming app.deb --extra-deb test.deb --extra-deb test2.deb`。

 **--branch  branch**
							
指定分支名称，默认分支为stable。例如：

`debtokaiming tree.deb --branch test_stable`。

 **--command  "command"**
  					
设置info.json 中默认执行的命令。例如：

`debtokaiming tree.deb --command “tree -L3”`。

 **--shortcut-desktop  xxx.desktop**
 
需要创建桌面快捷方式的desktop文件路径，要求全路径，这个字段可以指定多个。例如：

`debtokaiming tree.deb --shortcut-desktop /usr/share/application/a.desktop`。
 
 **--privilege** 
  									
设置应用以sudo权限执行；默认为false。例如：

`debtokaiming tree.deb --privilege`。

 **--no-kpct**
  									
禁用kpct查找。例如：

`debtokaiming tree.deb --no-kpct`。

 **--debug**
   									
打开调试模式。例如：

`debtokaiming tree.deb --debug`。

  **--help**
				
显示帮助信息。例如：

`debtokaiming --help`。

### 4.典型参数使用场景

#### 4.1.--id

该参数可修改开明软件的id名称。若不添加该参数工具会自动将软件的homepage的倒置域名作为开明软件的id名称。如未获取到homepage,取“top.kylin.deb名”作为开明id。使用方法如下：

`sudo debtokaiming ./ukui-clock_1.0.1_amd64.deb --id top.kylin.test`

#### 4.2.--base,--base-version，--runtime,--runtime-verison
  
该参数修改了软件转换以及运行过程中将要使用到的开明基础环境名称和版本。根据当前电脑中安装的基础环境名称及版本酌情修改该变量，runtime可置空。如不添加该组参数，工具将默认使用top.openkylin.base和top.openkylin.ukui作为base和runtime。例如：

`sudo debtokaiming ./test.deb --base cn.kylin.v10sp1-base  --runtime ""` 

将使用cn.kylin.v10sp1-base作为base,runtime为空，base的版本将自动获取当前系统中安装的最新版本base。

也可指定要使用的版本，例如：

`sudo debtokaiming ./test.deb --base cn.kylin.v10sp1-base --base-version 1.0.0 --runtime ""`

选择1.0.0版本的cn.kylin.v10sp1-base作为即将要使用到的base。

#### 4.3.--env

实际使用中，如遇到启动失败需要配置运行过程中环境变量的情况时，在转包过程中通过添加--env参数做处理。以下以两种可能会用到该参数的情况为例：

实际含有需要使用到的动态链接库，但运行过程中提示找不到，添加参数指定动态链接库寻找，转包时可添加环境变量LD_LIBRARY_PATH，如下：

`sudo debtokaiming ./test.deb --env LD_LIBRARY_PATH= /opt/apps/test/lib:/usr/lib:/lib/usr/local/lib:/usr/lib64:/usr/lib32:/lib64:/lib32`

部分软件不支持wlcom显示环境。通过XDG_SESSION_TYPE，GDK_BACKEND等环境变量将起显示环境修改为x11。转包时命令如下：

`sudo debtokaiming ./test.deb --env GDK_BACKEND=x11  --env XDG_SESSION_TYPE=x11`

#### 4.4.--desktop

若在转包过程中出现报错“找不到desktop, 请使用工具参数--desktop xxx.desktop 指定需要的desktop”，但实际deb包中含有desktop文件的情况，说明desktop文件的存放路径不在/usr/share/application/下，需要将desktop文件的名称作--desktop参数的值传入，以便工具获取到desktop。转换命令如下：

`sudo debtokaiming ./test.deb --desktop test.desktop`

## 三、hostmode原生部署模式

转换工具debtokaiming的hostmode模式专为原生部署场景设计。在此模式下，转成deb生成的ok包安装后将直接部署到宿主机环境，其运行依赖宿主机的系统环境。需要特别说明的是，此过程不会直接改变原deb的安装路径及内容，确保原生应用特性完整保留。

命令格式：

`debtokaiming hostmode <选项>`

### 1.使用条件

该模式下所转deb需要满足以下条件：

1)deb软件包安装时所有释放的资源文件不在 /usr 下。

2)deb需要实现软件包依赖自包含。

### 2.hostmode模式转换过程示例

通过一个示例介绍使用debtokaiming将符合上述条件的deb工具转换为开明格式的ok包。此过程在hostmode模式下进行，可使用debtokaiming hostmode --help来查看帮助信息。

#### 2.1执行转换命令

假设目录下已有deb包ukui-clock_1.0.1_amd64.deb并且安装好deb转换工具后，在当前目录执行命令：

`sudo debtokaiming hostmode ./ukui-clock_1.0.1_amd64.deb` 

如有特殊需要，可追加参数，如下：

`sudo debtokaiming hostmode ./ukui-clock_1.0.1_amd64.deb --deb a.deb`

该命令将a.deb与ukui-clock_1.0.1_amd64.deb一起打入到开明包中。工具全部支持的参数参考章节1.4.2。

#### 2.2.查询转换结果并安装

等待命令执行结束后，查看当前目录，可以发现目录下生成文件夹build和ok，分别存放转换过程文件和开明包。进入ok目录，可以看到转换完成的开明包。

执行以下命令，可将开明包安装到系统中：

`sudo kaiming install top.openkylin.Clock-x86_64-1.0.1-stable-binary-squashfs.ok`

#### 2.3.查看转换日志

默认只在终端显示必要命令，若要查看更详细的命令执行日志。可在转换命令的执行目录下，查看.km-hostapp目录下对应的.log文件。

### 3.参数解析

 **--id  id** 
									
设置生成的ok包名称,默认会根据deb包的Package字段自动填充为：top.kylin.Package。例如:

`debtokaiming hostmode tree.deb --id top.test.tree`。

 **--id-version  id-version**
 		
设置生成的ok包的版本号, 默认会根据deb包的版本号转换为符合开明版本号要求的字段。例如:

`debtokaiming hostmode tree.deb --id-version 2.0.3`。

 **--comp algorithm**
 
选择压缩算法，当前支持：gzip lzma lzo lz4 xz zstd。例如：

`debtokaiming hostmode tree.deb --comp zstd`。

 **--base  base**
  								
base为制作出的kaiming包依赖的base名称， 默认为空。例如：

`debtokaiming hostmode tree.deb --base top.openkylin.base`。

 **--base-version  base-version**
  			
指定base的版本，base 的 version 默认为空。例如：

`debtokaiming hostmode tree.deb --base top.openkylin.base --base-version 1.0.2`。

 **--runtime  runtime**
  						
制作出的kaiming包依赖的runtime，默认为空。例如：

`debtokaiming hostmode tree.deb --base top.openkylin.base --runtime top.openkylin.ukui`。

 **--runtime-version  runtime-version**
  	
runtime的版本, 默认为空。例如：

`debtokaiming hostmode tree.deb --base top.openkylin.base --runtime top.openkylin.ukui --runtime 1.0.3`。

 **--service  server-name** 
 					
原生应用支持server服务自启，这个字段可以指定多个。例如：

`debtokaiming hostmode qaxsafe.deb --service qaxsafed.service --service test.service`。

**--addsystemgroup  name** 
			
添加系统用户组, 这个字段可以指定多个。例如：

`debtokaiming hostmode tree.deb --addsystemgroup kylin --addsystemgroup kaiming`。

 **--deb  xxx.deb** 			
				
打包多个deb时使用，这个字段可以指定多个。例如：

`debtokaiming hostmode tree.deb --deb a.deb --deb b.deb`。

 **--shortcut-desktop  xxx.desktop** 
					
需要创建桌面快捷方式的desktop文件路径，要求全路径，这个字段可以指定多个。例如:

`debtokaiming hostmode tree.deb --shortcut-desktop /usr/share/./a.desktop`。

 **--autostart  file**
 								
开机自启文件，文件全路径，这个字段可以指定多个。例如:

`debtokaiming hostmode tree.deb --autostart /etc/xdg/.../a.desktop`。

 **--chmod  "xxx  file"** 
							
赋予文件权限， 权限和文件之间用空格隔开，这个字段可以指定多个。例如: 

`debtokaiming hostmode tree.deb --chmod "777 /etc/a."` 。

 **--installkill  arg**
 								
进程路径，安装时结束进程，这个字段可以指定多个。例如：

`debtokaiming hostmode tree.deb --installkill top.openkyin.clock`。

 **--uninstallkill  arg**
 						
进程路径，卸载时结束进程，这个字段可以指定多个。例如：

`debtokaiming hostmode tree.deb --uninstallkill top.openkyin.clock`。

 **--stopservice  service-name** 
					
服务名，停止服务，这个字段可以指定多个。例如：

`debtokaiming hostmode qaxsafe.deb --stopservice qaxsafed.service`。

 **--rmdir  dir**
 									
目录路径，卸载相关目录，这个字段可以指定多个。例如：

`debtokaiming hostmode qaxsafe.deb --rmdir tmp`。

 **--debug**
   										
打开调试模式。例如：

`debtokaiming hostmode tree.deb --debug`。

 **--help**
   										
显示帮助信息。例如：

`debtokaiming hostmode help`。


### 4. 典型参数使用场景

#### 4.1. --deb

如果一个deb工具会依赖其他的deb包，可以通过--deb参数将其依赖一同打入开明包中，可支持多次设置。例如：

`sudo debtokaiming hostmode test.deb --deb a .deb --deb b.deb`。

上述命令会把test.deb同a.deb和b.deb制作为一个开明包。

#### 4.2. --service

如果一个应用支持server自启，在转应用时可以使用--service设置要自启的服务。例如：

`sudo debtokaiming hostmode test.deb --service test_a.service`。

上述命令会制作test.deb的开明包，并保证在安装完成后自启动test_a.service服务。

#### 4.3. --autostart

如果应用需要开机自启动，则在转包的时候需要将其开机自启的文件通过--autostart进行设置，并且需要设置文件的全路径。例如：

`sudo debtokaiming hostmode test.deb --autostart /etc/xdg/xxx.desktop` 

上述命令会保证，在安装开明包时，可以将应用开启自启的文件放到系统开机自启目录下，从而保证应用可以开机自启。

#### 4.4. --chmod

应用中有文件在安装时需要修改文件权限。在转包时可以设置--chmod赋予文件某些权限，其中文件需要全路径。例如：

`sudo debtokaiming hostmode test.deb --chmod “777 /etc/test.sh”`。

上述命令可以实现，在安装开明包时赋予/etc/test.sh文件777权限。