User Manual.md · liulxb/pkg-mapping-lcy

# linux发行版之间的包名映射使用手册

## 背景

当在不同os下进行编译包，使用系统自带的包管理工具安装依赖包时，存在着包名不一致的问题。这就需要一份包名映射表可以切换到不同os下自动构建软件包。

## 环境配置

### Python

首先，安装依赖包：
> yum install zlib-devel bzip2-devel openssl-devel ncurses-devel sqlite-devel readline-devel tk-devel gcc make

然后，去官方下载到本地然后上传到服务器或者wget下载；
> wget https://www.python.org/ftp/python/3.9.12/Python-3.9.12.tgz

解压并安装：
> tar -zxvf Python-3.9.12.tgz
>
> cd Python-3.9.12
>
> ./configure
>
> make&&make install

执行完make&&make install之后，如果出现以下这种报错：“ModuleNotFound：No module named '_ctypes'”，则需要执行
> yum install libffi-devel -y

执行完继续make&&make install

### ElasticSearch

首先，从官网（https://www.elastic.co/cn/downloads/elasticsearch）上下载对应架构的压缩包并上传到服务器上或者wget下载:

> wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-8.6.2-linux-x86_64.tar.gz

然后解压并创建数据目录：
> tar -zxvf elasticsearch-8.6.2-linux-x86_64.tar.gz
>
> mv elasticsearch-8.6.2 elasticsearch
>
> mkdir /elasticsearch/data

此外，修改配置文件：

> cd /elasticsearch/config/
>
> cp elasticsearch.yml elasticsearch.yml.cp
> 
> vim elasticsearch.yml

在文件末尾修改或添加以下配置(不变动端口的话，默认为9200)：

> http.host: 0.0.0.0
> 
> http.port: 10200
>
> cluster.initial_master_nodes: ["crystal.ci"]

由于防火墙开启的缘故，需要开放ES的端口：

> exit
>
> firewall-cmd --zone=public --add-port=10200/tcp --permanent
>
> firewall-cmd --reload

并且由于es不允许使用root用户操作，需要单独添加用户(es)，并给es文件夹赋权：

> useradd es
> 
> chown -R es:es /elasticsearch/

最后，后台启动es：

> su es
> 
> cd /elasticsearch/bin/
> 
> ./elasticsearch -d

如果要设置es的用户名和密码，需要按照以下步骤进行操作：

1. 打开配置文件config/elasticsearch.yml
2. 找到xpack.security.enabled这一行，确保该行的值为true，表示启用安全功能
3. 找到xpack.security.authc.api_key.enabled这一行，确保该行的值为false，表示禁用API密钥认证（如果不需要使用API密钥认证）
4. 保存并关闭配置文件
5. 重新启动es服务

在重新启动后，可以使用以下命令：

> bin/elasticsearch-setup-passwords interactive

来创建用户名和密码，按照提示输入密码并确认即可设置用户名和密码。

PS：如果不改变代码（pkg-mapping/utils/es_util.py）的情况下，则需要将配置文件中的端口设置为：10200，并添加用户名：root和密码：Helloman@12#&。

### Docker

在创建debian和ubuntu的docker镜像时，需要将存储二进制包名的txt文件（由pkg-mapping/utils/XXX_binary_package_web.py生成的“XXX_XX_binary_package.txt”）、执行提取二进制包特征提取py文件（见下）都docker cp到镜像的同一目录下即可

## 主要流程

最终是从ElasticSearch数据库取出软件包的信息进行比较，所以需要先把数据都录入ES，主要流程如下所示：
* 源码包和二进制包下载与解压
* 提取源码包和二进制包的特征信息
* 将源码包和二进制包的特征信息入库
* 源码包比较得出源码包映射关系
* 二进制包比较得出二进制包映射关系

## 软件包入库

### 下载源码包、二进制包

从华为镜像源（https://mirrors.huaweicloud.com）中寻找对应的OS，并将其源码包、二进制包通过输入
>bash get_package/download_XXX.sh

命令自动化下载到本地对应路径下。特别地，debian和ubuntu需要利用docker进行下载，分别通过输入
> docker run -it -v $PWD/download_debian_11_source_packages.sh:/c/download_debian_11_source_packages.sh -v /c/pkgmapping/debian/11/sdeb:/c/pkgmapping/debian/11/sdeb cfb8bd69acfc bash /c/download_debian_11_source_packages.sh

> docker run -it -v $PWD/download_ubuntu_18.04_source_packages.sh:/c/download_ubuntu_18.04_source_packages.sh -v /c/pkgmapping/ubuntu/18.04/sdeb:/c/pkgmapping/ubuntu/18.04/sdeb d1a528908992 bash /c/download_ubuntu_18.04_source_packages.sh

命令来下载deb文件，其中，“cfb8bd69acfc”和“d1a528908992”为docker镜像（例如，通过"docker pull ubuntu:18.04"命令搭建）的id。此外，由于fedora的下载源与服务器之间网速不佳，因此需要先单独输入
> python get_package/fedora_url.py

命令来获取文件的下载链接，再执行 shell 脚本。

此外，Linux各个OS存储源码包和二进制包信息的文件格式不完全相同，其大致可分为三类：
1. 在centos、fedora、opensuse和openeuler中，源码包的存储文件为rpm文件和primary.xml文件，二进制包的存储文件为filelists.xml文件。
2. 在debian、ubuntu中，源码包的存储文件为dsc文件，二进制包的存储文件为deb文件。
3. 在archlinux中，源码包的存储文件为tar文件，二进制包的存储文件为pkg.tar文件。

### 解压源码包、二进制包

由于OS从镜像源中下载的源码包、二进制包是压缩文件，因此输入
>bash unzip_package/unzip_XXX.sh

命令进行解压操作，之后才能提取其中的特征信息。特别地，archlinux的解压操作已实现在其下载脚本中，因此无需执行解压脚本。

## 提取特征

从下载的源码包和二进制包中提取出后续映射所需要的特征信息，并将这些特征信息存储在对应的json文件中。

* 源码包的特征信息：
> {
  "name": "",
  "version": "",
  "summary": "",
  "description": "",
  "url": "",
  "requires": [],
  "providers": [],
  "binaryList": [],
  "buildRequires": [],
  "source0": "",
  "macro_names": [],
  "email_names": [],
  "class_names": [],
  "path_names": [],
  "url_names": []
}
* 二进制包的特征信息：
> {
  "name": "",
  "arch": "",
  "filelist": [],
}

### 源码包特征提取

基于上述所介绍的不同OS存储源码包和二进制包信息的文件格式不完全相同，提取源码包特征的操作可分为两类：一类是需要从rpm包和primary.xml文件中提取特征，另一类是只需要从其源码包中提取。

#### 类型一
##### centos、fedora、opensuse、openeuler
对于centos、fedora、opensuse和openeuler，源码包的特征提取需要输入
> python feature_extract/extract_rpm.py -o "OS的名字"

命令来生成“XXX_rpm.json”文件，输入

> python feature_extract/extract_spec.py -o "OS的名称"

命令来生成“XXX_spec.json”文件。

之后，通过输入
> python utils/merge_json.py -rpm "XXX_rpm.json的文件路径" -spec "XXX_spec.json的文件路径" -merge "合并后的json的文件路径"

命令来将两个json文件整合在同一个json文件中。

#### 类型二
##### debian、ubuntu
对于debian和ubuntu，源码包的特征提取需要输入
> python feature_extract/extract_deb.py -f "sdeb文件夹路径" -s "repo文件夹路径" -j "json文件路径"

命令来生成“XXX_src.json”文件。
##### archlinux
对于archlinux，源码包的特征提取需要输入
> python feature_extract/extract_archlinux.py

命令来生成“XXX_src.json”文件。

特别地，由于archlinux的源码包中没有“binaryList”特征，因此还需要输入
> python feature_extract/extract_archlinux_web.py

命令来通过爬虫的方式补充“binaryList”特征信息（速度较慢），并生成一个“archlinux_src_new.json”文件。

### 二进制包特征提取
由于部分OS的二进制包中没有“filelist”特征信息，因此提取源码包特征的操作可分为三类：一类是从下载的二进制包中直接提取特征，另一类是需要通过“apt-file list”命令方式提取特征。

#### 类型一
对于centos、fedora、opensuse、openeuler和archlinux，二进制包的特征提取通过输入
> python feature_extract/extract_bin.py -o "OS的名称"

命令来生成“XXX_binary.json”文件。

#### 类型二
对于debian和ubuntu，通过在对应版本OS的docker镜像下，输入
> python feature_extract/extract_XXX_bin_aptfile.py

命令将filelist特征存储在“XXX_binary.txt”文件中。然后将该txt文件拷贝到对应的路径下，并输入
> python feature_extract/update_features_XXX_binary_filelist.py

命令来生成“XXX_binary.json”文件。

## 特征入库
### 导入特征信息
将上述生成的各个json文件导入到ES数据库中，需要先通过输入
> cd elasticsearch-8.6.2/bin/

> ./elasticsearch

命令启动ES数据库，然后输入
> python package_mapping/import_feature.py -f "存储特征的json文件的路径" -o "{OS名称}@{OS版本号}" -t "特征类型，可选值为 'src' 和 'binary' "

命令进行某个OS的源码包或者二进制包特征的数据导入。特别地，建议先导入二进制包特征，再导入源码包特征。

### 提取二进制包名
将特征数据导入ES数据库后，还需要输入
> cd data/pkgs/

> mkdir {OS名称}@{OS版本号}

命令创建一个名为“{OS名称}@{OS版本号}”存放对应二进制包名的文件夹，之后再输入

> python utils/json_extract_binname.py -json "binary-特征json文件路径" -output "data/pkgs/{OS名称}@{OS版本号}"

命令将二进制包名按照架构（arch）存储在各个txt文件。最后，还需要通过输入
> mv output_bin_XXX.txt XXX.txt
 
命令将这些文件的文件名从“output_bin_XXX.txt”修改为“XXX.txt”。

## 软件包映射
在进行映射之前或之后，可以在config/constant.py文件中调整与映射相关的参数（0 < 各个参数数值 < 1）:
* 调整特征权重（两个包的总相似度为各个特征相似度的加权平均值）：修改config/constant.py 中 FEATURE_WEIGHT_MAP的值。
* 调整相似度阈值（两个包的的总相似度大于阈值才认为它们可能匹配）：修改config/constant.py中 SIMILARITY_THRESHOLD （src包）、SIMILARITY_BINARY_THRESHOLD（binary包）。
* 修改特征计算的函数：package_mapping 中的similarity_calculator.py

| OS映射 | FEATURE_WEIGHT_MAP | SIMILARITY_THRESHOLD | SIMILARITY_BINARY_THRESHOLD |
| :----: | :----: | :----: | :----: |
| centos-openeuler | {'name': 0.15, 'version': 0.05, 'summary': 0.05, 'description': 0.05, 'url': 0.05, 'requires': 0.05, 'providers': 0.05, 'binaryList': 0.1, 'buildRequires': 0.1, 'source0': 0.05, 'macro_names': 0.1, 'macro_counts': 0.05, 'email_names': 0.1, 'email_counts': 0.05, 'filelist': 0.4} | 0.3 | 0.15 |
| fedora-openeuler | {'name': 0.15, 'version': 0.05, 'summary': 0.05, 'description': 0.05, 'url': 0.05, 'requires': 0.05, 'providers': 0.05, 'binaryList': 0.1, 'buildRequires': 0.1, 'source0': 0.05, 'macro_names': 0.1, 'macro_counts': 0.05, 'email_names': 0.1, 'email_counts': 0.05, 'filelist': 0.4} | 0.3 | 0.15 |
| opensuse-openeuler | {'name': 0.15, 'version': 0.05, 'summary': 0.05, 'description': 0.05, 'url': 0.05, 'requires': 0.05, 'providers': 0.05, 'binaryList': 0.1, 'buildRequires': 0.1, 'source0': 0.05, 'macro_names': 0.1, 'macro_counts': 0.05, 'email_names': 0.1, 'email_counts': 0.05, 'filelist': 0.4} | 0.2 | 0.1 |
| debian-openeuler | {'name': 0.3, 'version': 0.15, 'summary': 0, 'description': 0, 'url': 0.15, 'requires': 0.2, 'providers': 0, 'binaryList': 0.2, 'buildRequires': 0, 'source0': 0, 'macro_names': 0, 'macro_counts': 0, 'email_names': 0, 'email_counts': 0, 'filelist': 0.4} | 0.3 | 0.15 |
| ubuntu-openeuler | {'name': 0.3, 'version': 0.15, 'summary': 0, 'description': 0, 'url': 0.15, 'requires': 0.2, 'providers': 0, 'binaryList': 0.2, 'buildRequires': 0, 'source0': 0, 'macro_names': 0, 'macro_counts': 0, 'email_names': 0, 'email_counts': 0, 'filelist': 0.4} | 0.3 | 0.15 |
| archlinux-openeuler | {'name': 0.15, 'version': 0.05, 'summary': 0, 'description': 0.1, 'url': 0.05, 'requires': 0.1, 'providers': 0, 'binaryList': 0.1, 'buildRequires': 0.1, 'source0': 0.05, 'macro_names': 0.1, 'macro_counts': 0.05, 'email_names': 0.1, 'email_counts': 0.05, 'filelist': 0.4} | 0.2 | 0.1 |

调整好参数后，再输入
> python package_mapping/pkg_mapping.py -o1 "{源OS名称}@{源OS版本号}" -o2 "{目标OS名称}@{目标OS版本号}

命令来进行两个OS之间的源码包和二进制包的映射，并将映射结果按照架构分别存于不同子文件夹但同名的"{源OS名称}@{源OS版本号}-to-{目标OS名称}@{目标OS版本号}.yml"文件中。

| 源OS名称 | 源OS版本号 | 目标OS名称 | 目标OS版本号 |
| :----: | :----: | :----: | :----: |
| centos | 7.8.2003 | openeuler | 22.03 |
| fedora | 33 | openeuler | 22.03 |
| opensuse | 15.4 | openeuler | 22.03 |
| debian | 11 | openeuler | 22.03 |
| ubuntu | 18.04 | openeuler | 22.03 |
| archlinux | 1 | openeuler | 22.03 |

| 源OS名称 | 源OS版本号 | 目标OS名称 | 目标OS版本号 |
| :----: | :----: | :----: | :----: |
| openeuler | 22.03 | centos | 7.8.2003 |
| openeuler | 22.03 | fedora | 33 |
| openeuler | 22.03 | opensuse | 15.4 |
| openeuler | 22.03 | debian | 11 |
| openeuler | 22.03 | ubuntu | 18.04 |
| openeuler | 22.03 | archlinux | 1 |

## 结果查询
经过上述的映射操作，通过输入
> cd /data/mapping

命令可以查询映射结果，所有的映射结果都会存储在该文件夹中，其中：
* /src文件夹中存放的yml文件是两个OS之间源码包的映射结果，其中带有“nosame”字段标题的yml文件为无同名软件包的映射结果，以“100”结尾标题的yml文件为随机抽取100条的映射结果；
* 除/src文件夹的其余文件夹中存放的yml文件是对应架构下，两个OS之间二进制包的映射结果，以“100”结尾标题的yml文件为随机抽取100条的映射结果。

## 映射结果检验
由于二进制包只有name、arch等简单的特征，因此只检验源码包的映射结果，用于优化映射操作（调整权重参数、增加特征等）。通过执行

> python search_invalid.py -o1 "{源OS名称}@{源OS版本号}" -o2 "{目标OS名称}@{目标OS版本号}

命令来了解源码包映射结果情况，输出映射的准确率，并将无效的映射结果按照表格的形式存入"/analyse"文件夹中对应"invalid"开头的txt文件中。

此外，为了人工检验映射结果，可以通过执行

> python search_random.py -o1 "{源OS名称}@{源OS版本号}" -o2 "{目标OS名称}@{目标OS版本号}

命令从所有映射结果中随机抽取100条数据存入"/analyse"文件夹中对应"random"开头的txt文件中。

如果想要了解更为详细的全部映射结果，可以通过执行

> python search_all.py -o1 "{源OS名称}@{源OS版本号}" -o2 "{目标OS名称}@{目标OS版本号}

命令将全部的映射信息存入"/analyse"文件夹中对应"all"开头的txt文件中。

liulxb/pkg-mapping-lcy

简介

发行版

贡献者

近期动态

liulxb/pkg-mapping-lcy .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

liulxb/pkg-mapping-lcy