1. 介绍

YODA(Yitian Optimal Development Assistant，倚天应用迁移工具)旨在帮助用户更加高效、便捷地实现跨平台、跨结构下的应用迁移，大幅度缩短客户在新平台上端到端性能验证所需的人力和时间，使得客户更加专注于应用本身算法的优化，协同客户实现降本增效。

1.1 简介

YODA倚天应用迁移工具是一款可以简化客户应用迁移到基于倚天710的服务器的过程的工具。当前，工具仅支持x86 Linux到Yitian Linux的扫描与分析，不支持Windows软件代码的扫描、分析与迁移。

当客户有x86平台上源代码的软件要迁移到基于倚天710的服务器上时，既可以使用该工具分析可迁移性和迁移投入，也可以使用该工具自动分析出需修改的代码内容，并指导用户如何修改。

YODA倚天应用迁移工具既解决了客户软件迁移评估分析过程中人工分析投入大、准确率低、整体效率低下的痛点，通过该工具能够自动分析并输出指导报告；也解决了用户代码兼容性人工排查困难、迁移经验欠缺、反复依赖编译调错定位等痛点。

当前工具支持的功能特性如下：

1.2 应用场景

软件迁移评估：自动扫描并分析软件包（非源码包）、已安装的软件，提供可迁移性评估报告。

源码迁移：当用户有软件要迁移到基于倚天710的服务器上时，可先用该工具分析源码并得到迁移修改建议。

兼容软件包推荐：为用户提供兼容版本推荐，帮助用户重构适用于倚天平台的软件安装包。

1.3 部署方式

Docker镜像部署。

2. 安装部署

2.1 环境要求

2.1.1 硬件要求

为了使多任务并发正常执行，要求使用多核CPU，16GB以上内存配置的服务器。

2.1.2 操作系统要求

• 当前Docker版本基于Alibaba Cloud Linux for Apsara release 8 (Soaring Falcon)版本发布。
• 为了运行当前的镜像环境，需要操作系统提前安装docker等依赖，以保证镜像的正常加载和使用。
• 操作系统字符集使用UTF-8。

2.1.3 运行环境要求

2.1.4 依赖要求

2.2 获取软件包

2.2.1 获取镜像包

• 这里x.x.x标识当前YODA的版本号，yyyymmddhhmmss标识当前版本的时间戳信息。
• 如有新版本，可直接使用已提供的内测新版本使用，具备更多功能和特性支持。

2.2.2 获取license

检测工具的执行依赖用户许可文件license.lic，如需获取或者购买license许可，可邮件联系邮箱（tangguoqing.tgq@alibaba-inc.com）或者技术支持与销售团队。

• 当前镜像包在发布时，默认包含一个有效期为30天（以镜像包时间戳为起始时间）的license。
• 如需30天试用，可点击这里获取最新的试用license进行30天内使用（直接替换原有的license.lic即可）。
• 如当前业务正在阿里云做倚天迁移适配，需更长时间的使用，也可以联系相关技术支持或者市场经理等获取license。

2.3 安装

2.3.1 前提条件

• 已准备用于安装YODA倚天应用迁移工具的服务器。
• 已安装操作系统，操作系统版本要求请参见2.1.2 操作系统要求。
• 已安装远程SSH登录工具，如Xshell、MobaXterm、PuTTY等。
• 已安装docker工具。

2.3.2 加载镜像

docker load -i [镜像包名称]

2.3.3 查看镜像

docker images

如正常加载成功，可在此查看到名为t-ptg-yoda-x.x.x-yyyymmddhhmmss.al8.[x86_64/aarch64]，tag为x.x.x的镜像。

2.3.4 启动镜像

docker run [镜像ID]

如需挂载本地盘检测，可在镜像启动时挂载本地路径：

docker run -d --privileged=true -v /path/to/local/mnt:/path/to/docker/yoda/workspace [镜像ID]

2.4 验证

docker run -it [镜像ID] /bin/bash

/yoda -h

# exit退出

显示如下内容说明安装成功：

3. 使用方法

当前YODA倚天应用迁移工具以二进制，结合命令行CML方式进行使用，在执行或者调用其进行应用检测时，需要指定必要的参数以提供输入文件和对应的输出文件类型，从而实现检测结果的正常获取。

其中必要参数为检测时必须要指定或者提供的参数，可选参数可根据实际需要进行配置。

当前YODA支持的参数选项可通过“yoda -h/--help"进行获取查看。

3.1 必要参数

• -f/--file：用于指定单个输入文件进行检测
• -d/--directory: 用于指定单个文件目录进行检测
• -e/--engine <java | python>: 用于指定当前检测文件或者目录需要调用的引擎类型。如不指定则会先后分别调用java和python引擎执行，分别输出二者的检测结果（以“_java”或“_python”结尾）。

3.2 默认参数

• -t/--type <txt | csv | json>: 指定输出结果类型，默认类型为txt。
• -b/--binary: 指定java引擎时跳过.java/.class的源码扫描，只保留二进制及pom等依赖的扫描结果，该选项默认关闭。
• -n：指定进程数，默认为单进程，当前进程数的具体配置可参考运行服务器的可用核数。

3.3 可选参数

• -q/--quite: 关闭终端的标准输出显示，默认开启。
• -o/--output: 指定输出检测结果文件路径和名称，如不指定，默认输出名称为“result_$date.log”。
• --class <cs | udf | xarch>: 专有输出格式，需配合“-t”选项使用，只影响最终输出结果，不影响引擎的检测过程。
• --temp: 指定检测时临时文件的保存路径，如不指定则默认中间临时文件保存在“~/tmp/yoda/”目录。如检测文件或者目录较大，临时文件超过系统的存储的可用大小，建议设置该选项指定到相对较大的目录下。

3.3 标准输出

以csv格式为例（其他格式txt/json输出检测字段与csv一致，同理可读取与显示），在不指定“--class”选项时，默认以标准化格式输出。常见的执行命令如下：

/yoda -e java -f /path/to/file_to_test -b -t csv

执行完毕后，在当前执行目录下生成“result_$date_java/python.csv”文件，例如“result_20230523180012_java.csv”，打开后其包含如下信息：

3.3.1 表头参数信息

3.3.2 输入文件信息

包含上述6个字段，其含义分别为：

3.3.3 检测建议信息

3.3.4 升级推荐信息

包含上述6个字段，其含义分别为：

3.4 专有输出

3.4.1 -t csv --class udf

该格式为UDF输入文件类型下的输出格式，支持同时扫描java和python文件，典型的使用命令如下：

/yoda -d /path/to/directory/to/test -q -b -t csv --class udf

典型输出结果如下所示：

3.4.2 -t json --class cs

该格式为CodeScan下的输出格式，与其前端显示输出相互关联匹配，典型的使用命令如下：

/yoda -e java -d /path/to/directory/to/test -q -b -t json --class cs

典型输出结果如下所示：

{

 "arch": "aarch64",

 "branch": "",

 "commit": "",

 "errors": [],

 "file_summary": {

   "jar": {

     "count": 1,

     "fileName": "JAR File",

     "loc": 0

   },

   "so": {

     "count": 0,

     "fileName": "SO Binary",

     "loc": 0

   },

   "other": {

     "count": 0,

     "fileName": "Other File",

     "loc": 0

   }

 },

 "git_repo": "",

 "issue_summary": {

   "ConfigurationInfoIssue": {

     "count": 0,

     "des": "CONFIGURATION_INFO"

   },

   "Error": {

     "count": 0,

     "des": "NO_ISSUES_FOUND_REMARK"

   },

   "ImageIssue": {

     "count": 0,

     "des": "IMAGE"

   },

   "OtherIssue": {

     "count": 1,

     "des": "NO_ISSUES_FOUND_REMARK"

   },

   "PluginIssue": {

     "count": 0,

     "des": "PLUGIN"

   }

 },

 "issue_type_config": "Open source",

 "issues": [

   {

     "checkpoint": "Check whether the type of so file is aarch64, and if not, judge whether it is incompatible.",

     "description": "",

     "filename": "/path/to/test/cases/snappy-java.jar/libsnappyjava.so",

     "issue_type": {

       "des": "NO_ISSUES_FOUND_REMARK",

       "type": "OtherIssue"

     },

     "lineno": "",

     "snippet": "",

     "advice": {

       "UPGRADE": "libsnappyjava.so",

       "NAME": "Alibaba",

       "TYPE-SRC": "snappyjava",

       "PACKAGE": "1.1.8.4"

     }

   }

 ],

 "language_type": "JAVA",

 "march": "",

 "output": "",

 "progress": true,

 "quiet": false,

 "remarks": [],

 "root_directory": "/path/to/test/cases",

 "source_dirs": [],

 "source_files": [

   "/path/to/test/cases/snappy-java.jar"

 ],

 "target_os": "OpenAnolis",

 "total_issue_count": 1

}

3.4.3 -t csv --class xarch

添加“-t csv --class xarch”选项的情况下，支持多架构扫描，并以专有格式输出。其中关于文件检测结果的架构兼容性分类为输出结果的CATEGORY字段，包含如下5个标识信息：

1. 专有输出格式与标准输出格式基本一致，主要变化为表头信息统计Summary和输入文件CATEGORY字段。
2. 如CATEGORY字段标识为x86_64，则会在其关联的字段INCOMPATIBILITY里面显示不兼容文件，同时如有兼容版本也会做相应推荐填充到对应字段。
3. 除x86_64标识外的其他标识下，关联的字段都会默认为NULL。

该格式为支持多架构（xarch）扫描下的输出格式，典型的使用命令如下：

/yoda -e java -d /path/to/directory/to/test -q -b -t csv --class xarch

典型输出结果如下所示：

4. 典型案例

4.1 Java引擎

在大数据场景下，以LZ4 压缩算法和 xxHash 哈希算法的 Java 端口和绑定lz4-java 为例，整个检测过程如下：

Step1: 下载源文件lz4-java-1.4.jar

Step2: 将源文件上传至已安装YODA倚天应用迁移工具的目标服务器，并保存至待检测目录/path/to/test/cases下面.

Step3: 运行yoda工具进行检测

/yoda -e java -f /path/to/test/cases/lz4-java-1.4.jar -t csv

Step4: 运行后如无报错，正常结束，则可以在当前yoda运行目录下得到名为result_$date_java检测结果，保存格式依-t类型为准。同时在未开启-q选项的情况下，也会在终端标准输出实时显示检测结果：

--------------------------------------------------------------------------------

NAME                : lz4-java-1.4.jar    

MD5                  : 642fc4c01a1a4f8c40bf0a5a1d279cf0

COMPATIBILITY  : No                  

TYPE                 : jar                  

INCOMPATIBILITY: liblz4-java.so;liblz4-java.so;liblz4-java.so;liblz4-java.so;java.util.zip;net.jpountz.util;net.jpountz.xxhash;net.jpountz.lz4;java.io;java.util;java.lang.reflect;sun.misc;java.nio

CONCLUSION     : Self-compiled        

UPGRADE          : jar                  

   |NAME |TYPE-SRC |PACKAGE |VERSION                  

   |/path/to/test/cases/lz4-java-1.4.jar/net/jpountz/util/linux/amd64/liblz4-java.so |Maven |lz4-java       |1.8.0                                              

   |/path/to/test/cases/lz4-java-1.4.jar/net/jpountz/util/linux/i386/liblz4-java.so     |Maven |lz4-java      |1.8.0                                              

   |/path/to/test/cases/lz4-java-1.4.jar/net/jpountz/util/linux/ppc64le/liblz4-java.so |Maven |lz4-java     |1.8.0                                              

   |/path/to/test/cases/lz4-java-1.4.jar/net/jpountz/util/linux/s390x/liblz4-java.so   |Maven  |lz4-java     |1.8.0                                              

   |java.util.zip           | | |                                              

   |net.jpountz.util      | | |                                                  

   |net.jpountz.xxhash | | |                                                  

   |net.jpountz.lz4      | | |                                                  

   |java.io                 | | |                                                  

   |java.util               | | |                                                  

   |java.lang.reflect    | | |                                              

   |sun.misc              | | |                                    

   |java.nio                | | |

--------------------------------------------------------------------------------

Java Summary:

       0 Compatible files, 1 Incompatible files, 0 To be verified, 0 Failures in Total 1

--------------------------------------------------------------------------------

Total time elapsed 36.393 Seconds, and average at 36.393 seconds of each file.

当前例子里面输出结果为result_20230630143006_java.csv，可通过cat/column等命令打开查看详细内容。

4.2 Python引擎

以AI与数据处理领域，通用的数值计算库numpy 1.19.0版本为例，整个检测过程如下：

Step1: 下载源文件numpy-1.19.0

Step2: 将源文件上传至已安装YODA倚天应用迁移工具的目标服务器，并保存至指定目录/path/to/test/cases.

Step3: 运行yoda工具进行检测（这里为了用-d目录形式演示，先对下载的gz包做了解压，该步骤非必要，可直接用-f以文件形式检测）。

/yoda -e python -d /path/to/test/cases/numpy-main -t json -q

Step4: 运行后如无报错，正常结束，则可以在当前yoda运行目录下得到名为result_$date_java检测结果，保存格式依-t类型为准。同时在开启-q选项的情况下，会关闭终端标准输出的实时显示。当前例子里面输出结果为result_20230630145854_python.json，输出的详细内容如下：

{

 "objects": "/path/to/test/cases/numpy-1.19.0",

 "command": "./yoda -e python -d /path/to/test/cases/numpy-1.19.0 -t json -q",

 "executor": "root",

 "time": "Fri Jun 30 02:58:54 PM CST 2023",

 "node": "iZbp13h7m94b5spw0mhhzgZ",

 "arch": "x86_64",

 "os": "Alibaba Cloud Linux release 3 (Soaring Falcon)",

 "kernel": "5.10.134-12_rc2.an8.x86_64",

 "branch": "",

 "commit": "",

 "errors": [],

 "summary": {

   "compatible": "1005",

   "incompatible": "0",

   "to_be_verified": "345",

   "others": "0",

   "total": "1350"

 },

 "details": [

   {

     "project": "numpy-1.19.0",

     "location": "/path/to/test/cases/numpy-1.19.0",

     "name": "site.cfg.example",

     "md5": "0da12b574ddfbac1de3f216e68d0d3a0",

     "category": "P0",

     "type": "C source",

     "incompatibility": []

   },

   {

     "project": "src",

     "location": "/path/to/test/cases/numpy-1.19.0/numpy/_build_utils/src",

     "name": "apple_sgemv_fix.c",

     "md5": "14c7128c989119b45ff802c29eb1655a",

     "category": "P0",

     "type": "c",

     "incompatibility": []

   },

   ...这里为了方便展示，省略剩余检测内容显示。

 ]

}

5. FAQ

5.1 java引擎检测时未指定“-b”选项，命令正常执行，但无输出

原因：未加“-b”选项时，java引擎会全量扫描并反汇编查看其中的.java/.class 等文件，反汇编时间较长，因此整个检测时间较长无输出，属于正常现象

解决方法：如不需要.java/.class等的依赖检测，可添加“-b”选项，跳过此类文件检测。

5.2 常见文件检测报错问题解决

引擎默认保存运行日志至“~/log/yoda/”路径，如发现报错等文件相关问题，可查看对应执行时间戳下“yoda_java/python”开头的日志文件，根据报错文件对应问题进行解决。