diff --git a/src/cli/h2sa/docs/figures/service_file.png b/src/cli/h2sa/docs/figures/service_file.png new file mode 100644 index 00000000..282359d0 Binary files /dev/null and b/src/cli/h2sa/docs/figures/service_file.png differ diff --git a/src/cli/h2sa/docs/figures/service_frame_structure.png b/src/cli/h2sa/docs/figures/service_frame_structure.png new file mode 100644 index 00000000..49ee3d9b Binary files /dev/null and b/src/cli/h2sa/docs/figures/service_frame_structure.png differ diff --git a/src/cli/h2sa/docs/figures/service_runLogic.png b/src/cli/h2sa/docs/figures/service_runLogic.png new file mode 100644 index 00000000..57184e2a Binary files /dev/null and b/src/cli/h2sa/docs/figures/service_runLogic.png differ diff --git a/src/cli/h2sa/docs/guide/h2sa_Develop_Guide.md b/src/cli/h2sa/docs/guide/h2sa_Develop_Guide.md new file mode 100644 index 00000000..45a7c20c --- /dev/null +++ b/src/cli/h2sa/docs/guide/h2sa_Develop_Guide.md @@ -0,0 +1,81 @@ +## Develop Guide + +### service代码生成工具使用场景 + +​ 当开发人员为OpenHarmony系统框架开发某些功能时，有时需要将这个功能包装成一个独立的服务进程运行在系统中，为了其它应用进程能够调用此服务，开发人员需要基于系统IPC通信框架编写一套远程接口调用实现。 Service代码生成工具能够帮助用户生成框架代码，提升开发效率。用户只需提供一个定义远程方法的.h头文件，工具会自动生成整个Service框架的代码，包含Ability注册、proxy/stub类实现、MessageParcel数据包构造、Service子系统编译及开机自启动相关配置文件。用户可基于框架代码专注于业务功能的编写。 + +![image](../figures/service_file.png) + +--- + +### service工具代码框架说明 + +~~~ +napi_generator\src\cli\h2sa + +h2sa +├── docs //文档 +├── README_ZH.md //usage,使用说明 +├── package.json //Node.js打包配置文件 +└── src + ├── gen + │ ├── analyze.js //包含用于分析C++头文件的逻辑。读取头文件内容；解析文件以提取类、方法、参数等信息。 + │ ├── file_template.js //包含生成代码时使用的模板字符串。模板中的占位符将在代码生成过程中被实际的数据替换，以生成所需的代码文件。（之后换成inl或者tmpl模板文件，并分出不同版本的文件夹，不同类型的文件） + │ ├── generate.js //包含核心的代码生成逻辑。调用analyze.js来获取分析结果；使用fileTemplate.js中的模板和分析结果来生成代码。 + │ ├── header_parser.py //脚本，与analyze.js协同工作，用于解析C++头文件 + │ └── test.h //生成sa的提示文件 + │ └── main.js //项目的入口。初始化日志记录和其它工具；解析命令行参数，以确定用户想要执行的操作；调用generate.js来启动代码生成过程。 + └── tools + ├── common.js //包含整个项目中使用的通用函数和常量 + ├── file_rw.js //包含文件读写操作的JavaScript模块 + ├── napi_log.js //日志记录模块 + ├── re.js //包含正则表达式相关功能的模块 + └── tool.js //包含一些辅助工具函数 +~~~ + +### 运行逻辑 + +![image](../figures/service_runLogic.png) + +main.js为脚本入口，其中使用stdio.getopt获取参数，其中,参数详情如下： + + -f，定义远程服务的.h文件； + + -l, 日志级别（0-3），默认为1； + + -o, 生成框架代码输入到指定路径下； + + -s, 指定serviceID。 - + + -v, 指定版本（3.2和4.1，默认版本为3.2） + +~~~ +let ops = stdio.getopt({ + 'filename': { key: 'f', args: 1, description: '.h file', default: '' }, + 'out': { key: 'o', args: 1, description: 'output directory', default: '.' }, + 'loglevel': { key: 'l', args: 1, description: 'Log Level: 0~3', default: '1' }, + 'serviceId': { key: 's', args: 1, description: 'service register id: 9000~16777214', default: '9000' }, + 'versionTag': { key: 'v', args: 1, description: 'version tag: 4.1 / 3.2', default: '3.2' } +}); +~~~ + +### 开发指导 + +#### 适配新版本 + +用户可对工具进行二次开发。例如：当前工具适配的源码版本是4.1，需要适配其它版本时，可修改以下文件进行适配： + +1.在main.js中，在allowedVersion数组中加入适配的版本号，如4.1统一为v4_1, 5.0统一为v5_0。 + +2.在file_template.js中，以适配5.0源码为例，参考bundleJsonTemplate41，buildGnTemplate41 新增v5_0版本对应的bundle.json模板、BUILD.gn模板；在module.exports中新增5.0版本的bundle.json,BUILD.gn模板对应的变量名。 + +3.在generate.js中，在doGenerate方法、genFilesByTemplate方法、genFileNames方法中修改相应代码；当rootInfo.version为v5_0时，替换对应的BUILD.gn, bundle.json模板路径。 + +4.适配新版本需要增加其它配置，可在file_template.js中增加配置模板，并增加配置文件模板的路径，在generate.js中生成配置文件。 + +#### RoadMap + +| 时间点 | 预期任务 | 验收标准 | 完成情况 | +| :----- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------- | +| 9月份 | 1，代码去重方案提供（不同版本模板，proxy-stub框架，hidumper框架，hitrace）；
2，适配5.0release版本，增加代码中hidump、hitrace等日志跟踪定位工具的使用； | 1，设计文档；
2，适配5.0时，可以编译出对应版本的工具，且编译验证成功 | 预计2024.9.24 | +| 10月份 | 增加testapp调用 sa接口，包括死亡监听； | 杀掉服务后，有信息 | | \ No newline at end of file diff --git a/src/cli/h2sa/h2sa_README_ZH.md b/src/cli/h2sa/docs/usage/h2sa_README_ZH.md similarity index 100% rename from src/cli/h2sa/h2sa_README_ZH.md rename to src/cli/h2sa/docs/usage/h2sa_README_ZH.md diff --git a/src/cli/h2sa/docs/usage/usage.md b/src/cli/h2sa/docs/usage/usage.md new file mode 100644 index 00000000..695aeefb --- /dev/null +++ b/src/cli/h2sa/docs/usage/usage.md @@ -0,0 +1,198 @@ +### Usage Guide + +## 简介 + +h2sa工具，即SERVICE框架生成工具，当开发者为OpenHarmony系统框架开发某些功能时，有时需要将这个功能包装成一个独立的服务进程运行在系统中，为了其它应用进程能够调用此服务，开发人员需要基于系统IPC通信框架编写一套远程接口调用实现。实现Service远程调用接口需要开发人员熟悉IPC通信框架，了解proxy/stub的继承与实现方式，掌握C++类型转为MessageParcel数据包的各种API方法，有一定的学习成本。而Service代码生成工具能够帮助使用者生成框架代码，提升开发效率。用户只需提供一个定义远程方法的.h头文件，工具会自动生成整个Service框架的代码，包含Ability注册、proxy/stub类实现、MessageParcel数据包构造、Service子系统编译及开机自启动相关配置文件。 + +## 约束 + +系统：建议Ubuntu 20.04或者Windows 10 + +依赖版本：VS Code 1.62.0 + +## 使用方法 + +#### 命令行 + +1. 安装python库 CppHeaderParser + + ~~~ + pip install CppHeaderParser + ~~~ + +2. 安装typescript：在napi_generator/src/cli/h2sa/src目录下执行命令 + + ~~~ + npm i typescript + ~~~ + +3. 安装stdio：在napi_generator/src/cli/h2sa目录下执行命令 + + ~~~ + npm i stdio + ~~~ + +4. 在napi_generator/src/cli/h2sa/src/gen目录下执行命令生成service框架代码： + + ~~~ + node main.js -f test.h + ~~~ + +其中,参数详情如下： + +-f，定义远程服务的.h文件； + +-l，可选参数，日志级别（0-3），默认为1； + +-o，可选参数，生成框架代码输入到指定路径下； + +-s，可选参数，指定serviceID，默认为19000； + +-v，可选参数，指定版本（3.2和4.1，默认版本为3.2） + +#### 生成物 + +1. 输出testservice文件夹，其中的文件如下所示： + + ![](../figures/h2sa_outRes.png) + + ~~~ + ├── BUILD.gn # 整个服务的编译文件，包含2个内容:1)服务端程序动态库编译 2)客户端可执行程序编译 + ├── bundle.json # 将服务包装成一个OpenHarmoney子系统组件，提供相关信息 + ├── etc # 服务启动配置目录，如果服务不需要开机自动启动，可以删除此目录。 + │ ├── BUILD.gn + │ └── test_service.cfg # 服务自启动配置文件，编译烧录后会在/ect/init/下生成xxx_service.cfg启动文件 + ├── include + │ ├── test_service.h # 服务端头文件 + │ ├── test_service_proxy.h # proxy 客户端头文件，为开发人员封装remote请求发送的处理 + │ └── test_service_stub.h # stub 服务端头文件，为开发人员封装remote请求接收的处理 + ├── interface + │ └── i_test_service.h # 由用户提供的.h文件生成的remote接口文件，stub和proxy都基于此文件实现接口。 + ├── sa_profile + │ ├── 19000.json # 服务配置文件 + │ └── BUILD.gn + └── src + ├── i_test_service.cpp # 接口实现文件 + ├── test_client.cpp # 客户端程序 + ├── test_service.cpp # 服务端程序 + ├── test_service_proxy.cpp # 客户端代理实现 + └── test_service_stub.cpp # 服务端 stub 实现 + ~~~ + +#### 应用和验证 + +1. 将生成的testservice文件夹放在对应版本的源码根目录下 + +2. 修改服务配置文件 + + 在foundation/systemabilitymgr/samgr/interfaces/innerkits/samgr_proxy/include/system_ability_definition.h增加以下一行： + + ``` + TEST_SERVICE_ID = {serviceID}, //保证ID与参数-s的值一致且没有重复，例如：默认值19000 + ``` + +3. 修改子系统配置文件 + + 在build/subsystem_config.json中增加以下内容。 + + ``` + "testservice": { + "path":"testservice", + "name": "testservice" + } + ``` + +4. 修改产品配置，如rk3568 + + 在vendor/hihope/rk3568/config.json中增加以下内容： + + ``` + { + "subsystem": "testservice", + "components": [ + { + "component": "testservice_part", + "features": [] + } + ] + } + ``` + +5. 修改权限配置 + + 在相应的产品目录的vendor/hihope/rk3568/security_config/high_privilege_process_list.json中增加以下内容： + + ``` + { + "name": "testservice", + "uid": "system", + "gid": ["root", "system"] + } + ``` + +6. selinux权限配置 + + vendor/hihope/rk3568/config.json中"build_selinux"属性若为true， 即要配置selinux权限，应修改以下文件；若为false，无需修改 + + > 1. testservice/etc/sample_service.cfg + > + > ``` + > "secon" : "u:r:testservice:s0" + > ``` + > + > 2. base/security/selinux_adapter/sepolicy/base/public/service_contexts + > + > ``` + > 9016 u:object_r:sa_testservice:s0 + > ``` + > + > 3. base/security/selinux_adapter/sepolicy/base/public/service.te + > + > ``` + > type sa_testservice, sa_service_attr; + > ``` + > + > 4. base/security/selinux_adapter/sepolicy/ohos_policy/startup/init/system/init.te + > + > ``` + > allow init testservice:process { getattr rlimitinh siginh transition }; + > ``` + > + > 5. base/security/selinux/sepolicy/base/public/type.te + > + > ``` + > type testservice, sadomain, domain; + > ``` + > + > 6. /base/security/selinux/sepolicy/base/te目录下增加新service的te文件，新增文件名即为服务名，例如：testservice.te + > + > ``` + > allow testservice init_param:file { map open read }; + > allow testservice sa_testservice:samgr_class { add get }; + > ``` + +7. 编码完成后，执行镜像编译命令 + + ~~~ + ./build.sh --product-name 产品名 + + 若编译rk3568开发板，则执行 + ./build.sh --product-name rk3568 + ~~~ + +8. 烧录镜像 + +9. 运行验证 + + >验证一： shell登录开发板。 查看服务端进程是否已正常启动 + > + >~~~ + >ps -ef | grep testservice + >system 288 1 0 00:02:13 ? 00:00:00 testservice_sa --- 服务进程已正常运行 + >~~~ + > + >验证二：运行客户端 + > + >~~~ + >/system/bin/testclient + >~~~ \ No newline at end of file diff --git a/src/cli/h2sa/examples/sample.h b/src/cli/h2sa/examples/sample.h deleted file mode 100644 index 26125694..00000000 --- a/src/cli/h2sa/examples/sample.h +++ /dev/null @@ -1,117 +0,0 @@ -/* -* Copyright (c) 2022 Shenzhen Kaihong Digital Industry Development Co., Ltd. -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ -#ifndef EXAM_H -#define EXAM_H - -#include -#include -#include -#include - -using std::string; - -namespace OHOS { -namespace Example { -class Basic { -public: - std::string basicName; - - int getBasicId() - { - return this->basicId; - } - void setBasicId (int id) - { - this->basicId = id; - } - -private: - int basicId; -}; - -class Human : public Basic { -public: - bool getOpFlag() - { - return this->opFlag; - }; - void setOpFlag (bool flag) - { - this->opFlag = flag; - }; - std::string getOpDesc() - { - return this->opDesc; - }; - void setOpDesc(std::string desc) - { - this->opDesc = desc; - }; - int getOpSeqId() - { - return this->opSeqId; - }; - void setOpSeqId(int id) - { - opSeqId = id; - }; - - std::string opName; - int age = 0; -private: - bool opFlag; - std::string opDesc; - int opSeqId; -} - -struct Book { - int getCc() - { - return this->cc; - }; - void setCc(int cc) - { - this->cc = cc; - }; - Basic getBasicObj() - { - return this->basicObj; - }; - void setBasicObj(Basic obj) - { - this->basicObj = obj; - }; -public: - int aa; - bool bb; - Basic direcObj; -private: - int cc; - Basic basicObj; -} - -/** - * @brief service服务，提供IPC调用接口 - * @ServiceClass - */ -class Exam2 { -public: - Book getBook(Basic& basic); - int fun1 (Book v1); - int fun2 (Basic& basic, Human& human); -}; -} // namespace Example -} // namespace OHOS -#endif // EXAM_H diff --git a/src/cli/h2sa/src/package.json b/src/cli/h2sa/package.json similarity index 100% rename from src/cli/h2sa/src/package.json rename to src/cli/h2sa/package.json diff --git a/src/cli/h2sa/src/src/gen/analyze.js b/src/cli/h2sa/src/gen/analyze.js similarity index 99% rename from src/cli/h2sa/src/src/gen/analyze.js rename to src/cli/h2sa/src/gen/analyze.js index 514ab2bf..d8c41557 100644 --- a/src/cli/h2sa/src/src/gen/analyze.js +++ b/src/cli/h2sa/src/gen/analyze.js @@ -12,7 +12,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -const { NapiLog } = require('../tools/NapiLog'); +const { NapiLog } = require('../tools/napi_log'); const fs = require('fs'); const os = require('os'); const { AllParseFileList } = require('../tools/common'); diff --git a/src/cli/h2sa/src/src/gen/fileTemplate.js b/src/cli/h2sa/src/gen/file_template.js similarity index 100% rename from src/cli/h2sa/src/src/gen/fileTemplate.js rename to src/cli/h2sa/src/gen/file_template.js diff --git a/src/cli/h2sa/src/src/gen/generate.js b/src/cli/h2sa/src/gen/generate.js similarity index 99% rename from src/cli/h2sa/src/src/gen/generate.js rename to src/cli/h2sa/src/gen/generate.js index 43ecb20c..01d62405 100644 --- a/src/cli/h2sa/src/src/gen/generate.js +++ b/src/cli/h2sa/src/gen/generate.js @@ -13,13 +13,13 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -const { NapiLog } = require('../tools/NapiLog'); +const { NapiLog } = require('../tools/napi_log'); const { replaceAll, getTab } = require('../tools/tool'); const re = require('../tools/re'); const { iServiceHTemplate, proxyHTemplate, stubHTemplate, serviceHTemplate, proxyCppTemplate, proxyFuncTemplate, stubCppTemplate, stubInnerFuncTemplate, serviceCppTemplate, serviceFuncImplTemplate, clientCppTemplate, buildGnTemplate, buildGnTemplate41, bundleJsonTemplate, bundleJsonTemplate41, profileGnTemplate, profileGnTemplate41, profileJsonTemplate, - profileXmlTemplate, serviceCfgTemplate, serviceCfgTemplate41, serviceCfgGnTemplate, iServiceCppTemplate } = require('./fileTemplate'); + profileXmlTemplate, serviceCfgTemplate, serviceCfgTemplate41, serviceCfgGnTemplate, iServiceCppTemplate } = require('./file_template'); const { DATA_W_MAP, DATA_R_MAP, VECTOR_W_MAP, VECTOR_R_MAP, getParcelType, AllParseFileList, MarshallInfo, ProcessingClassList } = require('../tools/common'); const numericTypes = ['short', 'int', 'long', 'long long', 'float', 'double']; diff --git a/src/cli/h2sa/src/src/gen/header_parser.py b/src/cli/h2sa/src/gen/header_parser.py similarity index 100% rename from src/cli/h2sa/src/src/gen/header_parser.py rename to src/cli/h2sa/src/gen/header_parser.py diff --git a/src/cli/h2sa/src/src/gen/main.js b/src/cli/h2sa/src/gen/main.js similarity index 97% rename from src/cli/h2sa/src/src/gen/main.js rename to src/cli/h2sa/src/gen/main.js index 4f2cac82..2e2c20fd 100644 --- a/src/cli/h2sa/src/src/gen/main.js +++ b/src/cli/h2sa/src/gen/main.js @@ -17,17 +17,17 @@ const stdio = require('stdio'); const fs = require('fs'); const re = require('../tools/re'); -const { NapiLog } = require('../tools/NapiLog'); +const { NapiLog } = require('../tools/napi_log'); const { print } = require('../tools/tool'); const analyze = require('./analyze'); const gen = require('./generate'); -const { writeFile, createFolder } = require('../tools/FileRW'); +const { writeFile, createFolder } = require('../tools/file_rw'); let ops = stdio.getopt({ 'filename': { key: 'f', args: 1, description: '.h file', default: '' }, 'out': { key: 'o', args: 1, description: 'output directory', default: '.' }, 'loglevel': { key: 'l', args: 1, description: 'Log Level: 0~3', default: '1' }, - 'serviceId': { key: 's', args: 1, description: 'service register id: 9000~16777214', default: '9000' }, + 'serviceId': { key: 's', args: 1, description: 'service register id: 9000~16777214', default: '19000' }, 'versionTag': { key: 'v', args: 1, description: 'version tag: 4.1 / 3.2', default: '3.2' } }); diff --git a/src/cli/h2sa/examples/test.h b/src/cli/h2sa/src/gen/test.h similarity index 100% rename from src/cli/h2sa/examples/test.h rename to src/cli/h2sa/src/gen/test.h diff --git a/src/cli/h2sa/src/src/tools/common.js b/src/cli/h2sa/src/tools/common.js similarity index 100% rename from src/cli/h2sa/src/src/tools/common.js rename to src/cli/h2sa/src/tools/common.js diff --git a/src/cli/h2sa/src/src/tools/FileRW.js b/src/cli/h2sa/src/tools/file_rw.js similarity index 98% rename from src/cli/h2sa/src/src/tools/FileRW.js rename to src/cli/h2sa/src/tools/file_rw.js index df7b44b7..4e7b0616 100644 --- a/src/cli/h2sa/src/src/tools/FileRW.js +++ b/src/cli/h2sa/src/tools/file_rw.js @@ -15,8 +15,12 @@ const fs = require('fs'); function utf8ArrayToStr(array) { - var out, i, len, c; - var char2, char3; + let out; + let i; + let len; + let c; + let char2; + let char3; out = ''; len = array.length; diff --git a/src/cli/h2sa/src/src/tools/NapiLog.js b/src/cli/h2sa/src/tools/napi_log.js similarity index 97% rename from src/cli/h2sa/src/src/tools/NapiLog.js rename to src/cli/h2sa/src/tools/napi_log.js index 947eb213..689b11ae 100644 --- a/src/cli/h2sa/src/src/tools/NapiLog.js +++ b/src/cli/h2sa/src/tools/napi_log.js @@ -32,9 +32,9 @@ NapiLog.LEV_DEBUG = 2; NapiLog.LEV_INFO = 3; const LEV_STR = ['[NON]', '[ERR]', '[DBG]', '[INF]']; -var logLevel = NapiLog.LEV_ERROR; -var logFileName = null; -var logResultMessage = [true, '']; +let logLevel = NapiLog.LEV_ERROR; +let logFileName = null; +let logResultMessage = [true, '']; function getDateString() { let nowDate = new Date(); diff --git a/src/cli/h2sa/src/src/tools/re.js b/src/cli/h2sa/src/tools/re.js similarity index 100% rename from src/cli/h2sa/src/src/tools/re.js rename to src/cli/h2sa/src/tools/re.js diff --git a/src/cli/h2sa/src/src/tools/tool.js b/src/cli/h2sa/src/tools/tool.js similarity index 96% rename from src/cli/h2sa/src/src/tools/tool.js rename to src/cli/h2sa/src/tools/tool.js index 87d1d234..3617508f 100644 --- a/src/cli/h2sa/src/src/tools/tool.js +++ b/src/cli/h2sa/src/tools/tool.js @@ -28,7 +28,7 @@ function print(...args) { } String.prototype.format = function (...args) { - var result = this; + let result = this; let reg = new RegExp('%[sd]{1}'); for (let i = 0; i < args.length; i++) { let p = result.search(reg); @@ -57,7 +57,7 @@ function replaceAll(s, sfrom, sto) { function getTab(tabLv) { let tab = ''; - for (var i = 0; i < tabLv; ++i) { + for (let i = 0; i < tabLv; ++i) { tab += ' '; } return tab;