增加scan工具使用文档

Signed-off-by: gou-jingjing <goujingjing@kaihong.com>
2024-11-26 18:20:35 +00:00 · 2024-07-12 14:19:57 +08:00 · 2024-07-12 14:19:57 +08:00 · ad4c6e53bc
commit ad4c6e53bc
parent d7809bb3cc
5 changed files with 287 additions and 10 deletions
--- a/docs/readme.md
+++ b/docs/readme.md
@ -22,4 +22,4 @@

 ## scan（API扫描工具）

-[readme](https://gitee.com/openharmony/napi_generator/blob/master/src/tool/api/README_ZH.md)
+[readme](https://gitee.com/openharmony/napi_generator/blob/master/src/tool/api/scan_README_ZH.md)
--- a/docs/usage.md
+++ b/docs/usage.md
@ -68,26 +68,20 @@ vscode插件使用说明：[vscode插件使用说明](https://gitee.com/openharm

 **开发说明**

-可执行程序开发说明：[]()
-
-intelliJ插件开发说明：暂无
+可执行程序开发说明：[可执行程序开发说明](https://gitee.com/openharmony/napi_generator/blob/master/src/cli/h2dtscpp/docs/guide/DEVELOP_ZH.md)

 **使用说明**

 可执行程序使用说明：[可执行程序使用说明](https://gitee.com/openharmony/napi_generator/blob/master/src/cli/h2dtscpp/docs/usage/INSTRUCTION_ZH.md)

-intelliJ插件使用说明：暂无
-
 ## scan（API扫描工具）

 **开发说明** 

-暂无
+可执行程序使用说明：[可执行程序开发说明](https://gitee.com/openharmony/napi_generator/blob/master/src/tool/api/docs/scan_DEVELOP_ZH.md)

 **使用说明**

-可执行程序使用说明：[可执行程序使用说明](https://gitee.com/openharmony/napi_generator/blob/master/src/tool/api/docs/INSTRUCTION_ZH.md)
-
-intelliJ插件使用说明：暂无
+可执行程序使用说明：[可执行程序使用说明](https://gitee.com/openharmony/napi_generator/blob/master/src/tool/api/docs/scan_INSTRUCTION_ZH.md)

 vscode插件使用说明：[vscode插件使用说明](https://gitee.com/openharmony/napi_generator/blob/master/src/tool/api/api_scan_vs_plugin/docs/INSTRUCTION_ZH.md)
--- a/src/tool/api/docs/scan_DEVELOP_ZH.md
+++ b/src/tool/api/docs/scan_DEVELOP_ZH.md
@ -0,0 +1,95 @@
+# scan工具开发说明
+
+若当前工具功能不满足开发者需求，开发者需增强工具能力，则可基于已有源码进行工具二次开发，编译打包生成自定义的可执行文件和插件。
+
+## 工具开发
+
+### 可执行文件开发说明
+
+#### 环境说明
+
+系统：建议Ubuntu 20.04或者Windows 10
+
+#### 开发步骤
+
+##### Linux
+1.下载Andr_N_Games_api.xlsx文件，并放置在napi_generator/src/tool/api/src文件夹下，下载链接如下：
+
+//待增加链接
+
+2.安装typescript：在napi_generator/src/tool/api/src目录下执行命令：
+
+	npm i typescript
+
+3.安装stdio：在napi_generator/src/tool/api/src目录下执行命令：
+
+	npm i stdio
+
+4.安装pkg : 在napi_generator/src/tool/api/src目录下执行命令：
+
+	sudo npm i -g pkg
+
+5.打包三个版本 : 在napi_generator/src/tool/api/src目录下执行命令：
+
+	pkg .
+
+执行以上步骤后，即可在napi_generator/src/tool/api/src目录下生成Windows、linux、mac系统下的可执行程序:
+
+	search-win.exe、search-linux、search-macos
+
+6.根据需求打包指定系统下的可执行文件。若想只打包windows系统下可执行文件，可执行命令：
+
+	pkg -t node14-win . -o search-win.exe
+
+若想只打包linux系统下可执行文件，可执行命令：
+
+	pkg -t node14-linux . -o search-linux
+
+若想只打包macos系统下可执行文件，可执行命令：
+
+	pkg -t node14-macos . -o search-macos
+
+备注：参数-t为指定系统，参数-o为指定可执行文件名称。
+
+
+##### Windows
+
+1.下载Andr_N_Games_api.xlsx文件，并放置在napi_generator/src/tool/api/src文件夹下，下载链接如下：
+
+//待增加链接
+
+2.使用管理员身份进入终端：
+
+![](../figures/pic_admin.png)
+
+3.安装typescript：使用管理员身份在napi_generator/src/tool/api/src目录下执行命令：
+
+	npm i typescript
+
+4.安装stdio：使用管理员身份在napi_generator/src/tool/api/src目录下执行命令：
+
+	npm i stdio
+
+5.安装pkg : 使用管理员身份在napi_generator/src/tool/api/src目录下执行命令：
+
+	npm i -g pkg
+
+6.打包三个版本 : 使用管理员身份在napi_generator/src/tool/api/src目录下执行命令：
+
+	pkg .
+
+执行以上步骤后，即可在napi_generator/hdc/api目录下生成Windows、linux、mac系统下的可执行程序:
+
+	search-win.exe、search-linux、search-macos
+
+7.根据需求打包指定系统下的可执行文件。若想只打包windows系统下可执行文件，可执行命令：
+
+	pkg -t node14-win . -o search-win.exe
+
+若想只打包linux系统下可执行文件，可执行命令：
+
+	pkg -t node14-linux . -o search-linux
+
+若想只打包macos系统下可执行文件，可执行命令：
+
+	pkg -t node14-macos . -o search-macos
--- a/src/tool/api/docs/scan_INSTRUCTION_ZH.md
+++ b/src/tool/api/docs/scan_INSTRUCTION_ZH.md
@ -0,0 +1,104 @@
+# scan工具使用说明
+## 简介
+
+scan工具，即API扫描工具，支持两种入口，分别是可执行程序、VS Code插件，使用者可以根据自己的需要选择合适的工具。
+
+## 工具介绍
+
+通过API扫描工具，开发者可以扫描输出三方库中存在，而OpenHarmony源码中不存在的风险接口，移植之前预知风险，降低移植难度，提高开发效率。
+
+![](./../figures/pic-api-frm.png)
+
+## 生成result文件
+
+### 准备
+
+可执行程序打包步骤如下：
+
+[工具开发说明](https://gitee.com/openharmony/napi_generator/blob/master/src/tool/api/docs/scan_DEVELOP_ZH.md)
+
+### 可执行程序使用方法
+
+#### Linux
+1、Ubuntu中存在将要扫描的三方库源码，如下所示：
+
+	Openharmony@Ubuntu-64:~/service$ ls /home/harmony/linshi/
+	opencv
+
+2、将打包的search-linux可执行程序放置任意路径下，如下所示：
+
+	Openharmony@Ubuntu-64:~/service$ ls
+	search-linux
+
+3、进入到search-linux可执行程序路径下，并执行可执行程序，执行命令如下：
+
+	Openharmony@Ubuntu-64:~/service$ ./search-linux -d /home/linshi/opencv/ -o ./
+
+其中,参数详情如下：
+	-d, 被扫描项目的路径；
+	-o, 可选参数，默认为当前路径下，输出结果存放路径。
+
+4、运行成功后会在当前目录下生成result.xlsx文件：
+
+	Openharmony@Ubuntu-64:~/service$ ls
+	result.xlsx  search-linux
+
+并在屏幕上打出风险接口名称：
+
+```
+{
+  function: Set(70) {
+    'AndroidBitmap_getInfo',
+    ......
+    'ANativeWindow_release'
+  },
+  include: Set(3) { 'bitmap.h', 'input.h', 'log.h' }
+}
+```
+
+#### Windows
+
+1、E:\workspace\杂七杂八\service\目录下存在将要扫描的项目opencv。
+
+2、将下载的search-win.exe可执行程序放置任意路径下，如下所示：
+
+	E:\demo\api>dir /B
+	search-win.exe
+
+3、进入search-win.exe可执行程序路径下，并执行可执行程序，执行过程如下：
+
+	E:\demo\api>search-win.exe -d E:\workspace\service\opencv -o ./
+
+其中,参数详情如下：
+	-d, 被扫描项目的路径
+	-o, 可选参数，默认为当前路径下，输出结果存放路径。
+
+4、运行成功后会在当前目录下生成result.xlsx文件：
+
+	E:\demo\api>dir /B
+	result.xlsx
+	search-win.exe
+
+并在屏幕上打出风险接口名称：
+
+```
+{
+  function: Set(70) {
+    'AndroidBitmap_getInfo',
+    ......
+    'ANativeWindow_release'
+  },
+  include: Set(3) { 'bitmap.h', 'input.h', 'log.h' }
+}
+```
+
+#### Mac
+
+方法步骤参考windows、Linux的使用方法。
+
+### VS Code插件使用方法
+
+具体的插件使用步骤，可以左键单击以下链接了解：
+
+[VS插件开发说明](https://gitee.com/openharmony/napi_generator/blob/master/src/tool/api/api_scan_vs_plugin/docs/INSTRUCTION_ZH.md)
+
--- a/src/tool/api/scan_README_ZH.md
+++ b/src/tool/api/scan_README_ZH.md
@ -0,0 +1,84 @@
+# scan工具
+
+## 简介
+
+scan工具即API扫描工具，它可以扫描三方库中包含OpenHarmony源码不包含的接口，并输出result.xlsx文档。开发者移植三方库到OpenHarmony源码中，若三方库中包含一些OpenHarmony中不存在的接口，便会增加移植难度。此时可使用API扫描工具，提前预知风险接口，降低移植难度，提高开发效率。目前工具支持命令行和VS Code插件两种入口。
+
+	├── napi_generator                           
+	│   ├── ...                                  # 其他文档
+	│   ├── src/tool
+	│   │   ├── api                              # api扫描工具
+	│   │   |   ├── api_scan_vs_plugin           # VS Code插件源码
+	│   │   |   ├── ...
+
+## 约束
+系统：建议Ubuntu 20.04或者Windows 10
+
+依赖版本：VS Code 1.62.0
+
+## 使用方法
+
+### 使用对象
+
+系统开发者
+### 使用场景
+
+移植三方库到OpenHarmony前预知风险接口。
+
+### 工具获取
+
+#### 命令行
+
+命令行工具可根据源码自行打包，打包步骤如下：
+
+[工具开发说明](https://gitee.com/openharmony/napi_generator/tree/master/src/tool/api/api_scan_vs_plugin/docs/DEVELOP_ZH.md)
+
+#### vscode插件
+
+工具支持VS Code插件，可在VS Code插件市场直接下载。
+
+### 工具输入
+
+根据使用者指定三方库项目源码，工具会输出风险接口。为了方便使用者快速上手工具，此处使用opencv项目为例，项目目录如下：
+
+![](./figures/opencv.png)
+
+### 工具使用
+
+#### 命令行
+
+[命令行使用说明](https://gitee.com/openharmony/napi_generator/blob/master/src/tool/api/docs/scan_INSRTUCTION_ZH.md)
+
+#### vscode插件
+
+具体的工具使用步骤，可以左键单击以下链接了解：
+
+[工具使用说明](https://gitee.com/openharmony/napi_generator/tree/master/src/tool/api/api_scan_vs_plugin/docs/INSTRUCTION_ZH.md)
+
+### 工具输出
+
+在window环境下的，根据输入三方库项目,生成的输出文件result.xlsx，如下所示：
+
+![](./figures/opencv_result.png)
+
+其中生成的result.xlsx文件，风险接口如下所示：
+
+![](./figures/opencv_include.png)
+
+![](./figures/opencv_h.png)
+
+## 版本说明
+
+暂无
+
+## FAQ
+
+  [FAQ](https://gitee.com/openharmony/napi_generator/tree/master/src/tool/api/FAQ.md)
+
+## 参与贡献
+
+暂无
+
+## 相关仓
+
+暂无