napi_generator(一)——NAPI框架生成工具介绍

个人简介：深圳技术大学FSR实验室大三学生，正于九联科技实习，共同学习研究OpenHarmony开发知识。博客主页：https://ost.51cto.com/person/posts/15624680

前言

对于南向设备开发者进行OpenHarmony 标准系统应用开发来说，在进行设备开发的过程中，难免要与北向应用层打交道，为北向应用开发提供一些硬件控制的接口，这是就需南向开发者学习OpenHarmony提供的NAPI机制，而这又需要开发者了解JS/eTS的一些知识，关注Nodejs语法、C++与JS之间的数据类型转换等上层应用转换逻辑，通过了这几天的学习也发现学习和使用NAPI确实要耗费挺大的精力。在学习NAPI框架的过程中，偶然间在源码下napi_generator目录发现这么一款好用的工具，简直是南向开发者的福音，通过NAPI框架生成工具，使用者可输入一个接口定义的ts文件，一键生成NAPI框架代码、业务代码框架、GN脚本等文件，并使用生成的NAPI接口及功能。使用者也可以输入一个定义方法的.h头文件，反向生成ts文件。这让开发者只关注底层业务逻辑即可，专业的人做专业的事，从而可以大大提高开发效率，下面先介绍一下这款工具的安装和使用教程。

参考资料

本工具由深开鸿公司开发，这里也感谢将这么一款好用的工具开源，本篇对于工具的详细使用，也大多出自文档，可以参考napi_generator仓库： NAPI框架生成工具使用说明——作者：深圳开鸿数字产业发展有限公司对于NAPI机制，已经有许多博主介绍得很详细了，不懂的童鞋可以先了解下： NAPI组件仓库基于OpenHarmony Native Api框架实现控制LED灯亮灭三方库移植之NAPI开发[1]—Hello OpenHarmony NAPI OpenHarmony 源码解析之JavaScript API框架(NAPI) 标准设备应用开发—Native Api-开源基础软件社区-51CTO.COM

使用环境

OpenHarmony-3.2-Beta5
九联UnionPi-Tiger开发板
Visual Studio Code（版本需1.62.0及以上）

工具简介及下载

NAPI框架代码生成工具，它可以根据用户指定路径下的ts(typescript)接口文件一键生成NAPI框架代码、业务代码框架、GN文件等。NAPI框架生成工具支持三种入口，分别是可执行程序、VS Code插件、IntelliJ插件，使用者可以根据自己的需要选择合适的工具，本人IntelliJ插件没尝试过，主要介绍一下可执行程序以及VS code 插件的使用，这两者也会比较常用一点。可执行文件、IntelliJ插件、VS Code插件下载路径如下： http://ftp.kaihong.com:5000/fsdownload/PC6uOorrM/NAPI

下载文件说明：

│   │   |── generator.jar           # IntelliJ插件
│   │   |── gnapi-0.0.1.vsix        # VS Code插件
│   │   |── napi_generator-linux    # Linux可执行程序 
│   │   |── napi_generator-win.exe  # Windows可执行程序    
│   │   └── napi_generator-macos    # Mac可执行程序

使用方法

一. 预检查

napi_generator的可执行程序方式和插件方式都具有预检查的功能，如果.d.ts文件中存在语法错误，那么执行的时候命令行会打印出错误信息，指出代码中存在错误的行号。使用效果如下：

joey@joey-virtual-machine:~/code/napi_test$ ./napi_generator-linux -f @ohos.napitest.d.ts
@ohos.napitest.d.ts (33,12): Identifier expected.
@ohos.napitest.d.ts (33,13): ';' expected.
@ohos.napitest.d.ts (33,13): An identifier or keyword cannot immediately follow a numeric literal.
@ohos.napitest.d.ts (33,13): Cannot find name 'shutdownDevice'.
@ohos.napitest.d.ts (33,28): Cannot find name 'reason'.
@ohos.napitest.d.ts (33,34): ',' expected.
@ohos.napitest.d.ts (33,36): 'string' only refers to a type, but is being used as a value here.
@ohos.napitest.d.ts (33,43): ';' expected.
@ohos.napitest.d.ts (33,49): Expression expected.

joey@joey-virtual-machine:~/code/napi_test$

二.生成框架

通过可执行程序生成（Linux环境下）

首先准备待转换的.d.ts文件，这里选择napi_generator/examples/ts下的@ohos.napitest.d.ts文件进行测试。若.d.ts文件中声明了basic.d.ts文件，将basic.d.ts文件放置在待转换.d.ts文件上一级目录；若除此之外还声明其它.d.ts文件，将此类文件放置在待转换.d.ts文件同级目录。此处在example下新建out文件夹，用于存放生成框架代码。

cd napi_generator/examples/ts
mkdir ../out

运行napi_generator-linux，命令如下（~/tools/napi_generator-linux根据自己的下载位置更改）：

~/tools/napi_generator-linux -f @ohos.napitest.d.ts -o ../out -i false -n int

其中，参数详情如下： -f, 待转换的.d.ts文件，若同时转换多个文件，文件之间用“,”隔开； -d, 根据指定路径转换该文件夹中所有.d.ts文件； -i, 可选参数，默认false，待转换.d.ts文件中引用非basic.d.ts的ts文件时打开开关； -o, 可选参数，默认为当前目录，指定生成框架代码输出路径； -n, 可选参数，默认为uint32_t，指定生成框架代码中number类型全部为指定类型。备注：-f与-d两个参数只选其中一个参数即可。

运行成功后会在out目录下生成框架代码文件，如下所示：

Windows 上的方法与Linux上的类似，可以自行参考仓库教程进行尝试。

通过VS code插件生成

打开VS code，在左侧边栏中选择插件，点击右上角的三个小圆点，选择从VISI安装，注意如果代码在远程服务器的话要将插件文件下载到服务器上，选择在服务器进行安装。
选择刚才下载的gnapi-0.0.1.vsix插件文件，再单击确定进行安装。
安装完成后就会在VS Code的插件管理器中能看到gnapi这个插件了。
选择需要转换的.d.ts文件，若.d.ts文件中声明了basic.d.ts文件，将basic.d.ts文件放置在待转换.d.ts文件上一级目录；若除此之外还声明其它.d.ts文件，将此类文件放置在待转换.d.ts文件同级目录。例如napi_generator下的一个exampl，位于napi_generator/examples/ts/@ohos.napitest.d.ts下，右键文件选择Generate Napi Frame。
工具弹出Generate Napi Frame弹窗，选择Napi-Gen页签。接口文件文本框填写.d.ts文件路径；生成框架路径文本框填写生成框架存放路径（这里我在example下新建了out目录）；编译脚本路径默认填写；number目的类型此处选择float，表示指定生成框架代码中number类型全部为float类型。；启用import功能不选择（待转换.d.ts文件未引用其它文件）；点击ok。

6. 执行结束后会在out目录下生成框架代码文件。

三. 生成文件总结

napitest.cpp:生成的napitest.cpp文件中的接口即为.d.ts文件中定义的接口，开发者只需要使用C/C++实现对于的接口功能即可。
BUILD.gn: GN脚本,需要注意一点就是生成的BUILD.gn文件中的ace_napi路径位置可能不准确，需根据自己的OpenHarmony进行修改，以及所属子系统，组件等，根据自己需要进行配置。
napitest_middle，tool_utility ：NAPI中间文件，包括NAPI模块定义，模块注册，接口工具都存放在里面。
napi_gen.log：生成过程日志、