【潤和軟件DAYU200開發(fā)板體驗】三方庫移植之NAPI開發(fā)[1]—Hello OpenHarmony NAPI

本文來源電子發(fā)燒友社區(qū)，作者：離北況歸， 帖子地址：https://bbs.elecfans.com/jishu_2308792_1_1.html


本文通過一個Hello OpenHarmony NAPI樣例講述了NPAI接口開發(fā)基礎知識。開發(fā)基于最新的OpenHarmony3.2Beta3版本及其對應SDK。標準系統(tǒng)開發(fā)板為潤和軟件dayu200。（附開發(fā)板體驗完整視頻，詳見作者原帖子）

將C/C++ 三方庫移植到OpenHarmony標準系統(tǒng)后，需要通過NAPI框架將其C/C++ 接口轉換成JS/ETS接口給應用層調用。

---

通過本文您將熟悉：

• 如何注冊NAPI模塊及接口。

• 如何在ArkUI eTS代碼中調用擴展的NAPI接口。

• full-SDK的替換。

  什么是NAPI

• NAPI（Native API）組件是一套對外接口基于Node.js N-API規(guī)范開發(fā)的原生模塊擴展開發(fā)框架。

• OpenHarmony 標準系統(tǒng)應用開發(fā)基于ArkUI框架，開發(fā)語言使用JS/eTS。部分業(yè)務場景依賴使用現(xiàn)有的C/C++ 庫，或為了獲取更高的性能。OpenHarmony提供NAPI機制，用于規(guī)范封裝IO、CPU密集型、OS底層等能力并對外暴露JS接口，通過NAPI實現(xiàn)JS和C/C++代碼的互相訪問.

  • 例如： 鐘祿平和林嘉誠老師在如何在OpenHarmony上使用SeetaFace2人臉識別庫？一文中，重點講解了NAPI接口如何實現(xiàn)OpenCV以及SeetaFace的調用。一句話概括就是，鐘祿平和林嘉誠老師講述了移植了三方庫后通過NAPI將庫的C/C++接口變成JS/ETS接口給應用層調用。

• OpenHarmony 中的 N-API 定義了由 JS/ETS 語言編寫的代碼和 native 代碼（使用 C/C++ 編寫）交互的方式，由 Node.js N-API 框架擴展而來。

• N-API：Native Application Programming Interface（本地應用程序接接口）
• 什么是Node.js N-API 框架
  Node.js N-API為開發(fā)者提供了一套C/C++ API用于開發(fā)Node.js的Native擴展模塊。從Node.js 8.0.0開始，N-API以實驗性特性作為Node.js本身的一部分被引入，并且從Node.js 10.0.0開始正式全面支持N-API。

添加OpenHarmony自定義子系統(tǒng)、組件、模塊

• 這部分內容涉及三方庫移植，為便于本篇NAPI基礎的學習。筆者在此自定義一個子系統(tǒng)用于開發(fā)NAPI。如在已存在的子系統(tǒng)組件中添加擴展NAPI，則跳過此步。
• 需要準備好OpenHarmonyBeta3源碼和編譯環(huán)境

添加子系統(tǒng)、組件

直接在OpenHarmony源碼根目錄創(chuàng)建子系統(tǒng)文件夾，取名mysubsys。并在目錄下添加子系統(tǒng)的構建配置文件ohos.build
完整內容如下：

{
  "subsystem": "mysubsys",
  "parts": {
    "hello": {
      "module_list": [
        "http://mysubsys/hello/hellonapi:hellonapi"
      ],
      "inner_kits": [
      ],
      "system_kits": [
      ],
      "test_list": [
      ]
    }
  }
}

• 另外ohos.build里面不支持加注釋，后面編譯的時候會莫名其妙報錯。別問，問就是筆者踩過坑了。（好像也沒必要加注釋）
  
  需要明白以下知識點：

"subsystem": "mysubsys",

• subsystem后面的mysubsy是子系統(tǒng)的名稱。

"parts": {
    "hello": {
   }
  }

• hello是組件名稱，被mysubsys子系統(tǒng)包含

"module_list": [
        "http://mysubsys/hello/hellonapi:hellonapi"

• hellonapi是模塊名，被hello組件包含。

接著將子系統(tǒng)配置到源碼下buildsubsystem_config.json文件，在該文件中插入如下內容。

"mysubsys": {
    "project": "hmf/mysubsys",
    "path": "mysubsys",
    "name": "mysubsys",
    "dir": ""
  }

• OpenHarmony系統(tǒng)架構中，子系統(tǒng)是一個邏輯概念，它具體由對應的組件構成。組件是對子系統(tǒng)的進一步拆分，可復用的軟件單元，它包含源碼、配置文件、資源文件和編譯腳本；能獨立構建，以二進制方式集成，具備獨立驗證能力的二進制單元。

本示例按子系統(tǒng)system > 組件part > 組件module 創(chuàng)建了3級目錄

mysubsys                    -- 子系統(tǒng)目錄
├── hello
│   └── hellonapi           -- 組件目錄
│       ├── BUILD.gn
│       └── hellonapi.cpp   -- 組件module目錄
└── ohos.build

源碼實現(xiàn)

最后在組件目錄下中創(chuàng)建代碼文件hellonapi.cpp

完整內容如下：

#include 
#include "napi/native_node_api.h"
#include "napi/native_api.h"

//接口業(yè)務實現(xiàn)C/C++代碼
//std::string 需要引入string頭文件，#include 
static napi_value getHelloString(napi_env env, napi_callback_info info) {
  napi_value result;
  std::string words = "Hello OpenHarmony NAPI";
  NAPI_CALL(env, napi_create_string_utf8(env, words.c_str(), words.length(), &result));
  return result;
}

// napi_addon_register_func
//2.指定模塊注冊對外接口的處理函數(shù)，具體擴展的接口在該函數(shù)中聲明
static napi_value registerFunc(napi_env env, napi_value exports)
{
    static napi_property_descriptor desc[] = {
        // 聲明該napi_module對外具體的提供的API
        DECLARE_NAPI_FUNCTION("getHelloString", getHelloString),
    };
    NAPI_CALL(env, napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc));
    return exports;
}

// 1.先定義napi_module，指定當前NAPI模塊對應的模塊名
//以及模塊注冊對外接口的處理函數(shù)，具體擴展的接口在該函數(shù)中聲明
// nm_modname: 模塊名稱，對應eTS代碼為import nm_modname from '@ohos.ohos_shared_library_name'
//示例對應eTS代碼為：import hellonapi from '@ohos.hellonapi'
static napi_module hellonapiModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = registerFunc, // 模塊對外接口注冊函數(shù)
    .nm_modname = "hellonapi",  // 自定義模塊名
    .nm_priv = ((void*)0),
    .reserved = { 0 },
};

//3.模塊定義好后，調用NAPI提供的模塊注冊函數(shù)napi_module_register(napi_module* mod)函數(shù)注冊到系統(tǒng)中。
// register module，設備啟動時自動調用此constructor函數(shù)，把模塊定義的模塊注冊到系統(tǒng)中
extern "C" __attribute__((constructor)) void hellonapiModuleRegister()
{
    napi_module_register(&hellonapiModule);
}

代碼解析如下：

接口業(yè)務實現(xiàn)C/C++代碼

// std::string 需要引入string頭文件，#include 
static napi_value getHelloString(napi_env env, napi_callback_info info) {
  napi_value result;
  std::string words = "Hello OpenHarmony NAPI";
  NAPI_CALL(env, napi_create_string_utf8(env, words.c_str(), words.length(), &result));
  return result;
}

添加NAPI接口頭文件

NAPI提供了提供了一系列接口函數(shù)，聲明包含如下2個頭文件中，先添加這2個頭文件到hellonapi.cpp

#include "napi/native_api.h"
#include "napi/native_node_api.h"

• native_api.h和native_node_api.h這兩個頭文件
  • 在OpenHarmony-3.1-release源碼下是在//foundation/ace/napi/interfaces/kits目錄下
  • 在3.2beta3版本中分別在//foundation/arkui/napi/interfaces/kits和//foundation/arkui/napi/interfaces/inner_api目錄下了。

注冊NAPI模塊、添加接口聲明

定義的hellonapi模塊，其對應結構體為napi_module。

• 指定當前NAPI模塊對應的模塊名以及模塊注冊對外接口的處理函數(shù)，具體擴展的接口在該函數(shù)中聲明。

// 定義napi_module
// nm_modname: 模塊名稱，對應eTS代碼為import nm_modname from '@ohos.ohos_shared_library_name'
// 示例對應eTS代碼為：import hellonapi from '@ohos.hellonapi'
static napi_module hellonapiModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = registerFunc, // 模塊對外接口注冊函數(shù)
    .nm_modname = "hellonapi",  // 自定義模塊名
    .nm_priv = ((void*)0),
    .reserved = { 0 },
};

• NAPI提供DECLARE_NAPI_FUNCTION(name, func)函數(shù)用于聲明api，傳入名稱和其他實現(xiàn)函數(shù)。在registerFunc函數(shù)中添加DECLARE_NAPI_FUNCTION，本例添加了一個getString接口。
• 模塊定義好后，調用NAPI提供的模塊注冊函數(shù)napi_module_register(napi_module* mod)函數(shù)注冊到系統(tǒng)中。

// napi_addon_register_func
static napi_value registerFunc(napi_env env, napi_value exports)
{
    static napi_property_descriptor desc[] = {
        // 聲明該napi_module對外具體的提供的API
        DECLARE_NAPI_FUNCTION("getHelloString", getHelloString),
    };
    NAPI_CALL(env, napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc));
    return exports;
}

自定義子系統(tǒng)構建

hellonapi編譯gn化,新增gn工程構建腳本。

在模塊hellonapi目錄下新建BUILD.gn文件，內容如下：

gn文件支持注釋，以#開頭

import("http://build/ohos.gni")

#ohos_shared_library（）中的hellonapi決定了生成動態(tài)庫的名稱，增量編譯階段生成動態(tài)庫libhellonapi.z.so 

ohos_shared_library("hellonapi") {   

   include_dirs = [
   #NAPI頭文件目錄
   "http://foundation/arkui/napi/interfaces/kits", 

   #根據(jù)增量編譯階段報錯添加的頭文件目錄
   "http://foundation/arkui/napi/interfaces/inner_api", 
   "http://third_party/node/src"                       
  ]

   #根據(jù)增量編譯時clang編譯器報警，添加的cflag
  cflags_cc = [ 
   #編譯時報錯提示"-Werror"，則加上"-Wno-error"
          "-Wno-error", 
   #編譯時報錯提示"-Wunused-function"，則加上"-Wno-unused-function"
          "-Wno-unused-function", 
  ]
   
  #編譯需要的源文件
  sources = [
    "hellonapi.cpp"
  ]

  #指定編譯依賴libace_napi.z.so動態(tài)庫
  deps = [ "http://foundation/arkui/napi:ace_napi" ] 

  #指定庫生成的路徑
  #libhellonapi.z.so會安裝在rk3568開發(fā)板的system/lib/module目錄下
  relative_install_dir = "module"
  
  #子系統(tǒng)名稱是mysubsys
  subsystem_name = "mysubsys"
  
  #組件名稱是hello
  part_name = "hello"
}

修改產(chǎn)品配置

將組件添加到需要的產(chǎn)品配置文件,源碼目錄下的productdefine/common/products/ohos-arm64.json。

• 插入位置任意，但要注意行尾的逗號，確保格式json文件格式正確。

"parts":{
    ...
    "mysubsys:hello":{},
    ...
  }

• mysubsys是本示例自定義的子系統(tǒng)名稱
• hello是自定義子系統(tǒng)下的組件名稱
• parts格式如下：

"parts":{
        "部件所屬子系統(tǒng)名:部件名":{}
    }

修改build/subsystem_config.json

新增子系統(tǒng)定義。

• subsystem_config.json文件定義了有哪些子系統(tǒng)以及這些子系統(tǒng)所在文件夾路徑，添加子系統(tǒng)時需要說明子系統(tǒng)path與name，分別表示子系統(tǒng)路徑和子系統(tǒng)名。

注意json文件也不支持注釋?。?！

"mysubsys": {
    "project": "hmf/mysubsys",
    "path": "mysubsys",
    "name": "mysubsys"
}

修改vendor/hihope/rk3568/config.json文件

將mysubsys子系統(tǒng)添加至rk3568開發(fā)板，在vendor目錄下新增產(chǎn)品的定義。

{
      "subsystem": "mysubsys",
      "components": [
        {
          "component": "hello",
          "features": []
        }
      ]
    }

編譯燒錄

先進行增量編譯出子系統(tǒng)的動態(tài)庫，增量編譯沒有報錯后。再全量編譯出鏡像，將其燒錄到開發(fā)板上。

• 增量編譯命令

./build.sh --product-name rk3568 --ccache --build-target=hellonapi --target-cpu arm64

• 全量編譯和燒錄
  這部分的內容不重復敘述，大家可以參考社區(qū)文章。

鏡像文件在源碼目錄下位置如下：

調用接口

full-SDK替換（可選）

從OpenHarmony 3.2 Beta2起，SDK會同時提供Public SDK和Full SDK。通過DevEco Studio默認獲取的SDK為Public SDK。
兩者差異如下：

• Public SDK
  • 面向應用開發(fā)者提供，不包含需要使用系統(tǒng)權限的系統(tǒng)接口。通過DevEco Studio默認獲取的SDK為Public SDK。
• Full SDK
  • 面向OEM廠商提供，包含了需要使用系統(tǒng)權限的系統(tǒng)接口。使用Full SDK時需要手動從鏡像站點獲取，并在DevEco Studio中替換

筆者使用的DevEco Studio版本為3.0.0.993，即DevEco Studio 3.0。API為API9。

full-SDK替換請參考官方文檔：full-SDK替換指南

若提示找不到npm，需要配置一下環(huán)境變量，將以下路徑添加到環(huán)境變量中即可

D:DevEco Studioohossdketsbuild-toolsets-loader

創(chuàng)建OpenHarmony標準應用

新建項目，選擇OpenHarmony。

compile sdk選擇9，其他保持默認即可。

插一句題外話，3.1release版本發(fā)布的時候。華為是把DevEco Studio分成了OpenHarmony和HarmonyOS兩個版本的，現(xiàn)在又合并到一起了。

調用接口

• 調用方式和ArkUI框架提供的API一樣，先import引入擴展的NAPI模塊，后直接調用。

index.ets內容如下：

import prompt from '@system.prompt'

// 引入擴展的NAPI模塊 
// 在hellonapi.cpp文件中定義nm_modname（模塊名稱）為hellonapi
// 在BUILD.gn文件中定義ohos_shared_library結構體名稱為hellonapi
// 所以是import hellonapi from '@ohos.hellonapi'
import hellonapi from '@ohos.hellonapi'


@Entry
@Component
struct HelloNAPI {
  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button("NAPI: hellonapi.getHelloString()").margin(10).fontSize(24).onClick(() => {
        // 調用getHelloString接口
        let strFromNAPI = hellonapi.getHelloString()
        prompt.showToast({ message: strFromNAPI })
      })
    }
    .width('100%')
    .height('100%')
  }
}

然后選擇自動簽名

將應用安裝到dayu200開發(fā)板上

運行效果如下：

• 也可以參考其他模塊的.d.ts創(chuàng)建擴展模塊@ohos.hellonapi.d.ts定義文件，放到IDE安裝OpenHarmony SDK的目錄路徑ohossdkets3.2.7.5api下。
  • .d.ts文件的命名為@ohos.ohos_shared_library_name.d.ts，ohos_shared_library為BUID.gn文件中定義的動態(tài)庫名稱

@ohos.hellonapi.d.ts內容如下：

declare namespace hellonapi {
	function getHelloString(): string;
    /**
     * 
     *
     * @since 9
     * @syscap SystemCapability.HiviewDFX.HiAppEvent
     */

}
export default hellonapi;

• 其中@syscap SystemCapability.HiviewDFX.HiAppEvent語句在.d.ts文件中一定要添加，否則IDE還是會報錯找不到該文件。
• 其中declare namespace hellonapi的hellonapi是BUILD.gn中的定義的ohos_shared_library_name。
• 其中function getHelloString(): string;中的getHelloString()是hellonapi.cpp文件中指定的模塊注冊對外接口的處理函數(shù)

IDE問題掃描如下：

如果不新建@ohos.hellonapi.d.ts放在sdkets3.2.7.5api，則IDE會報錯

標準應用編譯不是強依賴OpenHarmony SDK，所以可忽略IDE中告警，直接編譯打包hap。但是有的時候IDE會提示找不到@ohos.hellonapi.d.ts，然后有小概率的機會無法安裝hap。這個時候就要參考ohossdkets3.2.7.5api下的.d.ts文件編寫@ohos.hellonapi.d.ts了。

知識點附送

Native API中支持的標準庫

表1OpenHarmony支持的標準庫

名稱	簡介
標準C庫	libc、libm、libdl組合實現(xiàn)C11標準C庫。
標準C++庫	libc++是C++標準庫的一種實現(xiàn)。
OpenSL ES	OpenSL ES是一個嵌入式跨平臺的音頻處理庫。
zlib	Zlib是基于C/C++語言實現(xiàn)的一個通用的數(shù)據(jù)壓縮庫。
EGL	EGL是渲染API與底層原生窗口系統(tǒng)之間的一種標準的軟件接口。
OpenGL ES	OpenGL ES是一個嵌入式跨平臺的為 3D 圖形處理硬件指定標準的軟件接口。