如何贡献OpenHarmony三方库

1.什么是OpenHarmony三方库

OpenHarmony（OpenAtom OpenHarmony简称“OpenHarmony”）三方库，是经过验证可在OpenHarmony系统上可重复使用的软件组件，可帮助开发者快速开发OpenHarmony应用。根据其开发语言分为了2种，一种是使用JavaScript和TypeScript语言的三方库，通常以源码或OpenHarmony HAR/HSP的方式引入，在应用开发中使用。另一种是C和C++语言的三方库，通常在应用开发中通过N-API暴露JS接口的方式使用，或直接编译在OpenHarmony操作系统镜像中。  
非常欢迎开发者贡献三方库，我们鼓励开发者通过发布OHPM和OpenHarmony-TPC的方式，分享自己的开源三方库，能让更多的开发者使用，繁荣OpenHarmony应用生态。
2.如何查找和使用已有OpenHarmony三方库
在OpenHarmony三方库中心仓上，通过关键字检索所需 OpenHarmony 三方库信息。可参考帮助文档，使用ohpm install命令，将三方库安装到应用中。



3.创建新的三方库
创建OpenHarmony三方库，支持通过IDE界面创建和OHPM命令行创建两种方式。
方法1：通过IDE界面创建
在现有应用工程中，新创建Module，选择"Static Library"模板，创建完成后，完善
oh-package.json5的信息，其中名称、版本等信息根据实际情况填写。


方法2：通过OHPM命令行创建
执行ohpm init命令创建包信息文件oh-package.json5，其中名称、版本等信息根据实际情况填写。使用ohpm init 指令前需要将ohpm-cli所在路径添加到Path环境变量。


完善oh-package.json5文件
将三方库发布到 OpenHarmony 三方库中心仓，必须包含 oh-package.json5 文件，其是对当前三方库的元数据描述。
一个 oh-package.json5 文件：

• 列出项目中所依赖的三方库
• 使用 semver 规范指定项目中可以使用的三方库版本
  

oh-package.json5 字段说明：


4.开发三方库
在开发三方库前，建议搜索下业界是否已有JS/TS开源三方库，如果实在没找到合适的，也建议选择移植C/C++三方库的方案，通过N-API或@ohos/aki的方式提供js接口给应用使用，尽量不要采用完全自研的方式。

4.1移植JS三方库
第一步：JS/TS库选型
由于OpenHarmony应用是基于ArkTS开发，因此在开发OpenHarmony三方库时，建议首选在成熟的JS/TS开源三方库上开发。通常方法是在GitHub/NPM上按照特性和语言搜索，找到star/fork数量较高的，且开源协议友好的JS/TS开源三方库。


第二步：工具扫描三方库，检查是否依赖node.js/web内置模块
由于OpenHarmony开发框架里的API不完全兼容V8运行时的Build-In API，因此建议在使用JS三方库前，使用js-e2e工具扫描三方库，检查是否存在Node.js/Web内置模块的依赖。js-e2e工具是基于ESLint进行封装，可分析出JS库代码对Node.js和Web浏览器的内置模块、对象的依赖及兼容ES标准版本，使用该工具，可以快速知道该库是否依赖Node.js或者Web内置模块。
如果扫描结果不依赖Node.js/Web内置模块，恭喜你，这个库将会比较轻松地移植。如果大量依赖Node.js/Web库，那可能需要Fork源库代码，进行侵入式修改，或者是再找下是否有更合适地其他三方库。
注意，扫描的时候也需要同时扫描下package.json里面dependencies下的直接依赖和间接依赖，因为发布OpenHarmony三方库中心仓时，需要依赖的组件都发布。建议使用npm install下载所有依赖的代码后，一起扫描看结果。
第三步：跑通XTS用例，验证所有对外暴露接口可用
非UI的库，通常使用XTS用例验证和保障对外暴露的接口在OpenHarmony上可用。通常建议把这个三方库的源码拷贝到DevEco Studio中，采用源库的单元测试用例，连接OpenHarmony系统的rom设备，跑单元测试，来验证该库是否能在OpenHarmony系统100%运行。

其中把源码拷贝到src/main/ets下，测试代码拷贝到src/ohosTest/ets下。
在Ability.test.ets文件中导入源库的测试用例，如下图


由于JS或者TS断言接口与OpenHarmony系统提供的断言接口不一致，所以，在源库的测试用例上，需要手动更改下断言。下面提供下OpenHarmony断言的接口列表：

接口名	描述
assertClose	检验actualvalue和expectvalue(0)的接近程度是否是expectValue(1)
assertContain	检验actualvalue中是否包含expectvalue
assertEqual	检验actualvalue是否等于expectvalue[0]
assertFail	抛出一个错误
assertFalse	检验actualvalue是否是false
assertTrue	检验actualvalue是否是true
assertInstanceOf	检验actualvalue是否是expectvalue类型
assertLarger	检验actualvalue是否大于expectvalue
assertLess	检验actualvalue是否小于expectvalue
assertNull	检验actualvalue是否是null
assertThrowError	检验actualvalue抛出Error内容是否是expectValue
assertUndefined	检验actualvalue是否是undefined

如：

可以参考diff库的单元测试用例：

根据对应的断言，运行测试用例，看源库的单元测试用例是否能通过。如果通过，则可以大概率该库在OpenHarmony系统下能运行。

如果不通过，可以通过以下几个方面进行排查并解决问题；

• 检查测试代码的接口调用是否使用正确。
• 如果是Node.js/Web内置模块问题，则需要使用OpenHarmony SDK替代对应的系统方法。
• 如果是系统限制，如不支持动态函数、eval等语法，则需要更换实现。
• 如果是系统接口差异，则建议在OpenHarmony Gitee仓下提Issue或者在OpenHarmony开发者论坛上描述问题求助。
  

第四步：规范源码目录结构，开源代码到Gitee/GitHub
参考axios三方库的目录，规范源码目录结构。

1. |---- axios三方库名称
   
2. |     |---- AppScrope  # 示例代码文件夹
   
3. |     |---- entry  # 示例代码文件夹
   
4. |     |---- hvigor # 项目配置  
   
5. |     |---- screenshot # 效果截图
   
6. |     |---- lottieArkTS # 项目配置
   
7. |     |---- axios  # axios三方库文件夹(一般为库名)
   
8. |           |---- build  # axios模块打包后的文件
   
9. |           |---- src  # 模块代码
   
10. |                |---- ets/components   # 模块代码
    
11. |                     |---- lib         # axios 网络请求核心代码
    
12. |                     |---- sandbox     # axios 网络请求sample代码
    
13. |                     |---- templates   # axios 网络请求核心代码
    
14. |                     |---- index.d.ts  # axios 接口类型定义
    
15. |            |---- index.js        # 入口文件
    
16. |            |---- index.d.ts      # 声明文件
    
17. |            |---- *.json5      # 配置文件
    
18. |     |---- README.md  #  需要包括功能介绍，使用方法，API说明， 约束与限制
    
19. |     |---- README.OpenSource  # 使用的开源软件说明
    
20. |     |---- CHANGELOG.md  # 更新日志
    
21. |     |---- LICENSE  # 开源协议
    
22. |     |---- TEST.md  # XTS覆盖接口说明
    

复制代码

4.2移植C/C++三方库
如果没有合适的JS/TS三方库，此时可以查找是否有成熟的C/C++三方库可以移植到OpenHarmony中，目前可以在这里查看其他开发者已验证可在OpenHarmony上编译通过的C/C++三方库。
通常相对于JS/TS的三方组件来说，C/C++三方库运行效率更高，但首先要能完成在OpenHarmony编译环境下的构建，而且需要再封装NAPI或者使用@ohos/aki对应用提供JS接口。接下来将介绍如何快速高效的移植一个C/C++三方库到OpenHarmony上。
C/C++三方库适配问题与解决方案


由上图可以了解到，C/C++三方库移植的流程、关键阻塞点和解决方法，接下来我们详细介绍具体的步骤。

第一步：三方库运行时依赖分析
针对运行时依赖的分析，我们开发了对应的C/C++三方库风险识别工具，通过该工具可以扫描出三方库是否有对NDK，OpenGL等接口的依赖，以及是否有bionic的C库接口的依赖等。该工具可以让我们快速的对一个C/C++三方库进行风险识别。
工具的使用请参照C/C++三方库风险识别工具使用方法。
如果依赖无法兼容的接口则该库无法移植，建议更换其他库；如果不依赖以上接口，仍需要继续验证。注意：同时需要分析依赖库的源码。

第二步：三方库编译构建
OpenHarmony的应用编译开发使用的是DevEco Studio，而该工具目前只支持cmake的编译，但开源的C/C++三方库编译方式多样化，包含cmake，configured等方式。对于原生库cmake无法在IDE上编译构建的，我们需要分析问题原因并需要针对IDE修改原生CMakeLists.txt。而非cmake编译方式的三方库，我们也需要分析该库的编译方式进行手写CMakeLists.txt文件将该库编译方式改为cmake编译构建。这些过程比较耗时，尤其对一些大型的C/C++三方库。
针对于这些问题，我们开发一套基于Linux下用原生库的编译脚本进行交叉编译三方库的工具lycium。该工具协助开发者，在 Linux系统上快速编译构建能在OpenHamony上运行的c/c++ 三方库。
使用lycium工具编译开源库，在lycium工具目录会生成usr目录，里面是三方库头文件及生成的库，该目录下存在已编译完成的32位和64位三方库。需要注意的是：

• 有依赖库的必须将依赖库一起编译，否则框架无法进行编译。
• 安装目录下对应的三方库有2份，其中armeabi-v7a对应的32位的库，arm64-v8a对应的是64位的库。
  

接下来就可以对三方库进行测试验证了。

第三步：三方库测试验证
业界内C/C++三方库测试框架多种多样，我们无法将其统一，因此为了保证原生库功能完整，我们基于原生库的测试用例进行测试验证。为此，我们集成了一套可以在OH环境上进行make test等操作的环境:CITools，通过配置完这套环境，我们就可以在OH环境上运行原生库的测试用例了。

第四步：三方库的使用
验证通过后，就可以使用三方库了。将三方库二进制拷贝到对应的工程/entry/libs/armxx/目录，头文件拷贝到工程/entry/src/main/cpp目录下。
可参考curl集成到应用hap，了解三方库的使用：

• 拷贝动态库到\\entry\libs\${OHOS_ARCH}\目录： 动态库需要在\\entry\libs\${OHOS_ARCH}\目录，才能集成到hap包中，所以需要将对应的so文件拷贝到对应CPU架构的目录
  

      

• 在IDE的cpp目录下新增thirdparty目录，将编译生成的库拷贝到该目录下，如下图所示
  

   

• 在最外层（cpp目录下）CMakeLists.txt中添加将将三方库和三方库的头文件和加入工程中语句。
  

#将三方库加入工程中target_link_libraries(entry PRIVATE ${CMAKE_SOURCE_DIR}/../../../libs/${OHOS_ARCH}/libcurl.so)#将三方库的头文件加入工程中target_include_directories(entry PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/curl/${OHOS_ARCH}/include)
接下来就可以使用三方库了。
第五步：开发JS/TS接口
提供N-API或者使用@ohos/aki，对应用提供JS/TS接口。

第六步：规范源码目录，开源到gitee/github仓库
参考commons-compress三方库的目录，规范源码目录结构，把三方库的源码或二进制引入到cpp目录，在ets目录中引入js api。


5.补充三方库必要文件
5.1 README.md
为了帮助其他人在 OHPM 上找到您的三方库并在他们的项目中使用您的代码获得良好的体验，我们建议在您的三方库目录中包含一个 README 文件。README 文件可能包含安装、配置和使用包中代码的说明，以及用户可能认为有帮助的任何其他信息，建议包含简介，示例动图，下载安装，所需权限，使用示例，接口说明，约束与限制(支持API几，SDK版本)，目录结构，贡献代码，开源协议。
5.2 LICENSE
开源协议，如果是移植的三方库，必须保留之前三方库的开源协议。
5.3 CHANGELOG.md
修改记录
5.4 TEST.md
补充XTS测试用例的覆盖情况，参考qr-code-generator。
5.4 .ohpmignore(可选)
若部分工程源文件无需构建到HAR包中，可在module目录下新建.ohpmignore文件，用于配置打包时要忽略的文件，支持正则表达式写法。将无需打包进HAR包的文件/文件夹名称写入.ohpmignore文件中。Deveco Studio构建时将过滤掉.ohpmignore文件中所包含的文件目录。
5.5 entry应用示例
提供一个demo应用，演示三方库的调用方法和调用效果。

6.编译打包HAR/HSP
开发完库模块后，选中模块名，然后通过DevEco Studio菜单栏的Build > Make Module ${libraryName}进行编译构建，生成HAR/HSP。HAR/HSP可用于工程其它模块的引用，或将HAR/HSP上传至ohpm仓库，供其他开发者下载使用。若部分源码文件不需要打包至HAR/HSP中，可通过创建.ohpmignore文件，配置打包时要忽略的文件/文件夹。

7.发布OpenHarmony三方库中心仓
7.1 ohpm publish到中心仓
为了让其他开发者更方便地使用三方库，需要将完成的三方库打包成HAR/HSP包，并发布到OpenHarmony三方库中心仓，详见创建及发布三方库。

待管理员审核通过后（在OpenHarmony三方库中心仓的个人中心-》消息中查看审核结果），即可使用ohpm install下载安装


7.2 源码打标签
对应源码在Gitee/GitHub上打标签。

8.贡献到OpenHarmony-TPC
8.1 建仓申请(可选)
在OpenHarmony 架构SIG会上申报议题，申请在OpenHarmony-SIG建仓，孵化成功后转到OpenHarmony-TPC下。
8.2 发布到社区“三方组件资源汇总”
按照三方库分类，发布PR到https://gitee.com/openharmony-tpc/tpc_resource