diff --git a/OrganizationDescription.md b/OrganizationDescription.md index b8bb04690aa5345ab6726f9f8fdadaf1d615be33..f40702f0214f2f3075beae8cd2298cd86ce7f810 100644 --- a/OrganizationDescription.md +++ b/OrganizationDescription.md @@ -5,8 +5,6 @@ OpenHarmony-TPC(Third Party Components)用于汇集OpenHarmony系统上的 OpenHarmony-TPC由OpenHarmony知识体系工作组下属的OpenHarmony三方库SIG主导,欢迎您使用及参与贡献。 - - # 查找OpenHarmony三方库 - [三方组件资源汇总](https://gitee.com/openharmony-tpc/tpc_resource) - [OpenHarmony三方库中心仓](https://ohpm.openharmony.cn/) @@ -15,11 +13,11 @@ OpenHarmony-TPC由OpenHarmony知识体系工作组下属的OpenHarmony三方库S - [如何安装 OpenHarmony ohpm 包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_har_usage.md) # 贡献OpenHarmony三方库 -- [创建新的三方库](/contribute/create.md) -- [移植js三方库](/contribute/js.md) -- [移植c/c++三方库](/contribute/c.md) -- [OpenHarmony三方库发布标准](/contribute/standard.md) -- [发布OpenHarmony三方库中心仓](/contribute/ohpm.md) +- [创建新的三方库](/contribute/adapter/create.md) +- [移植js三方库](/contribute/adapter/js.md) +- [移植c/c++三方库](/contribute/adapter/c.md) +- [OpenHarmony三方库发布标准](/contribute/adapter/standard.md) +- [发布OpenHarmony三方库中心仓](/contribute/adapter/ohpm.md) - [贡献到Openharmony-TPC](/contribute/tpc.md) # 治理规则 @@ -36,7 +34,6 @@ OpenHarmony-TPC由OpenHarmony知识体系工作组下属的OpenHarmony三方库S - [@金永生](https://gitee.com/Cruise2019) - [@zeeman_wang](https://gitee.com/zeeman_wang) - # 社区交流 - 微信群:待补充 - 邮件列表: 待补充 diff --git a/contribute/c.md b/contribute/adapter/c.md similarity index 57% rename from contribute/c.md rename to contribute/adapter/c.md index 0c95d878358872623a084f92f6b5d6005354bf0d..f9438ca139466f8609f02ac1873260265f2a37be 100644 --- a/contribute/c.md +++ b/contribute/adapter/c.md @@ -1,78 +1,90 @@ # 移植c/c++三方库 + 如果没有合适的js/ts三方库,此时可以查找是否有成熟的C/C++三方库可以移植到OpenHarmony中,目前可以在这里查看其他开发者已验证可在OpenHarmony上编译通过的C/C++三方库。 通常相对于JS/TS的三方组件来说,C/C++三方库运行效率更高,但首先要能完成在OpenHarmony编译环境下的构建,而且需要再封装NAPI或者使用@ohos/aki对应用提供js接口。接下来将介绍如何快速高效的移植一个C/C++三方库到OpenHarmony上。 C/C++三方库适配问题与解决方案 -![img](../imgs/c_migrate.png) +![img](../../imgs/c_migrate.png) 由上图可以了解到,C/C++三方库移植的流程、关键阻塞点和解决方法,接下来我们详细介绍具体的步骤。 ## 第一步:三方库运行时依赖分析 + 针对运行时依赖的分析,我们开发了对应的[c/c++风险识别工具](https://gitee.com/han_jin_fei/e2e/tree/master/thirdparty_compare),通过该工具可以扫描出三方库是否有对NDK,OpenGL等接口的依赖,以及是否有bionic的C库接口的依赖等。该工具可以让我们快速的对一个C/C++三方库进行风险识别。 如果依赖无法兼容的接口则该库无法移植,建议更换其他库;如果不依赖以上接口,仍需要继续验证。注意:同时需要分析依赖库的源码。 ## 第二步:三方库编译构建 + OpenHarmony的应用编译开发使用的是[Deveco Studio](https://developer.harmonyos.com/cn/develop/deveco-studio#download),而该工具目前只支持cmake的编译,但开源的C/C++三方库编译方式多样化,包含cmake,configured等方式。对于原生库cmake无法在IDE上编译构建的,我们需要分析问题原因并需要针对IDE修改原生CMakeLists.txt。而非cmake编译方式的三方库,我们也需要分析该库的编译方式进行手写CMakeLists.txt文件将该库编译方式改为cmake编译构建。这些过程比较耗时,尤其对一些大型的C/C++三方库。 针对于这些问题,我们开发一套基于linux下用原生库的编译脚本进行交叉编译三方库的工具[lycium](https://gitee.com/openharmony-sig/tpc_c_cplusplus/tree/master/lycium)。该工具协助开发者,在 linux系统上快速编译构建能在OpenHamony上运行的c/c++ 三方库。 使用lycium工具编译开源库,在lycium工具目录会生成usr目录,里面是三方库头文件及生成的库,该目录下存在已编译完成的32位和64位三方库。需要注意的是: -●有依赖库的必须将依赖库一起编译,否则框架无法进行编译。 -●安装目录下对应的三方库有2份,其中armeabi-v7a对应的32位的库,arm64-v8a对应的是64位的库。 + +- 有依赖库的必须将依赖库一起编译,否则框架无法进行编译。 +- 安装目录下对应的三方库有2份,其中armeabi-v7a对应的32位的库,arm64-v8a对应的是64位的库。 + 接下来就可以对三方库进行测试验证了。 ## 第三步:三方库测试验证 + 业界内C/C++三方库测试框架多种多样,我们无法将其统一,因此为了保证原生库功能完整,我们基于原生库的测试用例进行测试验证。为此,我们集成了一套可以在OH环境上进行make test等操作的环境:[CITools](https://gitee.com/openharmony-sig/tpc_c_cplusplus/blob/master/lycium/CItools/README_zh.md) ,通过配置完这套环境,我们就可以在OH环境上运行原生库的测试用例了。 ## 第四步:三方库的使用 + 验证通过后,就可以使用三方库了。将三方库二进制拷贝到对应的工程/entry/libs/armxx/目录,头文件拷贝到工程/entry/src/main/cpp目录下。 可参考curl集成到应用hap,了解三方库的使用: -●拷贝动态库到\\entry\libs\${OHOS_ARCH}\目录: 动态库需要在\\entry\libs\${OHOS_ARCH}\目录,才能集成到hap包中,所以需要将对应的so文件拷贝到对应CPU架构的目录 -![img](../imgs/c_lib.png) +- 拷贝动态库到\\entry\libs\${OHOS_ARCH}\目录: 动态库需要在\\entry\libs\${OHOS_ARCH}\目录,才能集成到hap包中,所以需要将对应的so文件拷贝到对应CPU架构的目录 + +![img](../../imgs/c_lib.png) + +- 在IDE的cpp目录下新增thirdparty目录,将编译生成的库拷贝到该目录下,如下图所示: -●在IDE的cpp目录下新增thirdparty目录,将编译生成的库拷贝到该目录下,如下图所示 -![img](../imgs/c_include.png) +![img](../../imgs/c_include.png) -●在最外层(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) +- 在最外层(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接口 + 提供NAPI或者使用@ohos/aki,对应用提供js/ts接口。 ## 第六步:规范源码目录 + 参考[commons-compress](https://gitee.com/openharmony-tpc/CommonsCompress)三方库的目录,规范源码目录结构,把三方库的源码或二进制引入到cpp目录,在ets目录中引入js api。 -``` -/commons-compress # 三方库源代码 -├── src # 框架代码 + +```shell +/commons-compress # 三方库源代码 +├── src # 框架代码 │ └── main -│ └── cpp -│ ├── zstd # # zstd C源码目录 -│ └── zstd.cpp # zstd Napi封装接口 -│ └── ets -│ └── components -│ └── archivers -│ ├── ar # ar源代码存放目录 -│ ├── cpio # cpio源代码存放目录 -│ ├── dump # dump源代码存放目录 -│ ├── lzma # lzma源代码存放目录 -│ ├── tar # tar源代码存放目录 -│ └── zip # zip源代码存放目录 -│ └── compressors -│ ├── brotli # brotli源代码存放目录 -│ ├── bzip2 # bzip2源代码存放目录 -│ ├── lz77support # lz77support源代码存放目录 -│ ├── lzw # lzw源代码存放目录 -│ ├── snappy # snappy源代码存放目录 -│ ├── xz # xz源代码存放目录 -│ └── z # z源代码存放目录 -│ ├── deflate # deflate源代码存放目录 -│ ├── gzip # gzip源代码存放目录 -│ ├── lz4 # lz4源代码存放目录 -│ ├── util # 工具源代码存放目录 -│ └── zstd # zstd源代码存放目录 +│ └── cpp +│ ├── zstd # zstd C源码目录 +│ └── zstd.cpp # zstd Napi封装接口 +│ └── ets +│ └── components +│ └── archivers +│ ├── ar # ar源代码存放目录 +│ ├── cpio # cpio源代码存放目录 +│ ├── dump # dump源代码存放目录 +│ ├── lzma # lzma源代码存放目录 +│ ├── tar # tar源代码存放目录 +│ └── zip # zip源代码存放目录 +│ └── compressors +│ ├── brotli # brotli源代码存放目录 +│ ├── bzip2 # bzip2源代码存放目录 +│ ├── lz77support # lz77support源代码存放目录 +│ ├── lzw # lzw源代码存放目录 +│ ├── snappy # snappy源代码存放目录 +│ ├── xz # xz源代码存放目录 +│ └── z # z源代码存放目录 +│ ├── deflate # deflate源代码存放目录 +│ ├── gzip # gzip源代码存放目录 +│ ├── lz4 # lz4源代码存放目录 +│ ├── util # 工具源代码存放目录 +│ └── zstd # zstd源代码存放目录 ``` - - diff --git a/contribute/create.md b/contribute/adapter/create.md similarity index 92% rename from contribute/create.md rename to contribute/adapter/create.md index c5334239139017e17dbe9a17730afe8b78d5eeb9..cb3eff6170210921fe245e8123a099a3d868b32c 100644 --- a/contribute/create.md +++ b/contribute/adapter/create.md @@ -6,12 +6,11 @@ 在现有应用工程中,新创建Module,选择"Static Library"模板,创建完成后,完善 oh-package.json5的信息,其中包名称、版本等包信息根据实际情况填写。 -![img](../imgs/create_byide.png) - +![img](../../imgs/create_byide.png) ### 方法2:ohpm命令行创建 执行ohpm init命令创建包信息文件oh-package.json5,其中包名称、版本等包信息根据实际情况填写。 -![img](../imgs/create_byconsole.png) +![img](../../imgs/create_byconsole.png) ## 完善oh-package.json5文件 将三方库发布到 OpenHarmony 三方库中心仓,必须包含 oh-package.json5 文件,其是对当前三方库的元数据描述。 @@ -21,7 +20,7 @@ oh-package.json5的信息,其中包名称、版本等包信息根据实际情 - 使用 semver 规范指定项目中可以使用的三方库版本 oh-package.json5 字段说明: -![img](../imgs/oh-package.json5.png) +![img](../../imgs/oh-package.json5.png) ## 编译打包HAR/HSP 开发完库模块后,选中模块名,然后通过DevEco Studio菜单栏的Build > Make Module ${libraryName}进行编译构建,生成HAR/HSP。HAR/HSP可用于工程其它模块的引用,或将HAR/HSP上传至ohpm仓库,供其他开发者下载使用。若部分源码文件不需要打包至HAR/HSP中,可通过创建.ohpmignore文件,配置打包时要忽略的文件/文件夹。 diff --git a/contribute/js.md b/contribute/adapter/js.md similarity index 100% rename from contribute/js.md rename to contribute/adapter/js.md diff --git a/contribute/ohpm.md b/contribute/adapter/ohpm.md similarity index 94% rename from contribute/ohpm.md rename to contribute/adapter/ohpm.md index 71c0be24fedc37734d01be61a40b11687ada4620..bf3cd55785450f5caf7b38141d956097a8147e89 100644 --- a/contribute/ohpm.md +++ b/contribute/adapter/ohpm.md @@ -5,7 +5,7 @@ ## 发布准备 1. 在进行 publish 发布前,请先确保在[OpenHarmony三方库中心仓](https://ohpm.openharmony.cn/)上已经创建了帐号,且进行了[安全设置](https://ohpm.openharmony.cn/#/cn/help/personalset)。 -![img](../imgs/ohpm_message.png) +![img](../../imgs/ohpm_message.png) 2. 登录OpenHarmony三方库中心仓,从 【个人中心】页面中【复制发布码】,并配置到 .ohpmrc 文件中 publish_id 字段上,可执行如下命令: @@ -30,9 +30,9 @@ publish 命令其他使用方法及相关规则,请参阅 ohpm publish 常用 上架审核通过通知消息示例: -![img](../imgs/ohpm_new.png) +![img](../../imgs/ohpm_new.png) ## 管理已发布的三方库 登录OpenHarmony三方库中心仓,在【个人中心】-【Package】管理界面,查看已发布的三方库审核、上下架状态。 -![img](../imgs/ohpm_package.png) +![img](../../imgs/ohpm_package.png) diff --git a/contribute/standard.md b/contribute/adapter/standard.md similarity index 100% rename from contribute/standard.md rename to contribute/adapter/standard.md diff --git a/contribute/tpc.md b/contribute/tpc.md index b7ddf0d43daf648c06a7a4d74cdbaf0b0f8a0503..0d628ee7c8a359b3ce5411533c01060928462fc9 100644 --- a/contribute/tpc.md +++ b/contribute/tpc.md @@ -1,5 +1,9 @@ # 贡献到Openharmony-TPC + ## 建仓申请(可选) + 在OpenHarmony 架构SIG会以上[申报议题](https://gitee.com/openharmony/community/blob/master/zh/pmc.md),申请在openharmony-sig建仓,孵化成功后转到openharmony-tpc下。 + ## 发布到社区“三方库资源汇总” + 按照三方库分类,发布PR到[资源汇总](https://gitee.com/openharmony-tpc/tpc_resource) diff --git a/contribute/tpc_contribute.md b/contribute/tpc_contribute.md new file mode 100755 index 0000000000000000000000000000000000000000..bd6e33b7686e73c68e85fc5e8b2f14a4a489bead --- /dev/null +++ b/contribute/tpc_contribute.md @@ -0,0 +1,94 @@ +# OpenHarmony-TPC 开源三方库贡献 + +共建三方库到OpenHarmony-TPC的方式有两种: + +- 将开源三方库共建到openharmony-tpc仓库
+ 将源码托管到openharmony-tpc上 +- 将开源三方库的链接发布到社区“三方库资源汇总”
+ 按照三方库分类,发布PR到[资源汇总](https://gitee.com/openharmony-tpc/tpc_resource) + +本文重点讲解将开源三方库共建到openharmony-tpc仓库 + +## 如何将开源三方库贡献到OpenHarmony-TPC + +开发者贡献一个三方库到[OpenHarmony-TPC](https://gitee.com/openharmony-tpc)的流程是:三方库立项——>OpenHarmony-sig 孵化——>毕业准出到OpenHarmony-TPC + +在该过程中我们需要先在[OpenHarmony-sig](https://gitee.com/openharmony-sig)上申请一个孵化仓,sig孵化过程是一个检验并保证三方库质量的过程。 + +### OpenHarmony-sig建仓 + +- 建仓申请 + + 在OpenHarmony 架构SIG会议上申报议题,议题内容是申请建三方库仓。上会时需要准备建仓申请材料,会议上需要说明 三方库的背景,能力,价值以及选型。建仓会议申请请参照文档[sig管理](https://gitee.com/openharmony/community/blob/master/zh/sig_governance.md#21--openharmony-%E9%A1%B9%E7%9B%AE%E4%BB%93%E5%BA%93%E7%AE%A1%E7%90%86%E6%B5%81%E7%A8%8B) + +- 创建三方库SIG仓 + + 1. [登录OpenHarmony数字化平台](http://ci.openharmony.cn/workbench/cicd/codecontrol/list)
+  ![登录](../imgs/ci_login1.png) +  ![登录](../imgs/ci_login2.png) + 2. 选SIG管理下的SIG仓申请
+ 建仓具体步骤如下图所示:
+  ![建仓步骤](../imgs/warehouse_create_step.png) + 3. SIG建仓内容填写
+  ![建仓内容填写](../imgs/warehouse_infomations.png)
+ ***建仓申请通过了构架SIG评审后,会议纪要会上传到:https://lists.openatom.io/hyperkitty/list/dev@openharmony.io/, 通过该网址按时间搜索到具体的纪要信息*** + 4. 填写完后后提交申请,可以通过`审批人`一栏联系当前的审批人进行审批,审批通过后仓库自动建成。 + +- 门禁配置 + + 门禁是保证代码质量是否达到质量要求关键手段之一,其主要包含代码编译、静态/安全/开源检查、敏感词/copyright扫描等。
+ 门禁申请的主要步骤如下:
+ 1. 在OpenHarmony-sig的[manifest仓]()创建对应三方仓的xml配置文件。 + 2. 登录[OpenHarmony数字化平台](http://ci.openharmony.cn/workbench/cicd/codecontrol/list),在SIG管理下选择流水线申请,具体如下图所示:
+  ![门禁内容](../imgs/pipeline_process_info1.png) +  ![门禁内容](../imgs/pipeline_process_info2.png) + + 门禁所需填写的内容如上图所示,其余部分使用默认内容即可。OpenHarmony-TPC开源三方库当前预编译命令: + + ```shell + rm -rf cicd && git clone https://gitee.com/openharmony-sig/cicd.git -b tpc_compile && chmod 777 cicd/js/* && ./cicd/js/prebuild.sh ${PR_URL} + ``` + + 编译命令: + + ```shell + ./cicd/js/build.sh ${PR_URL} + ``` + + 3. 流水线审批 + 流水线提交申请后可以通过`当前处理人`一栏查看审批人员,可以联系审批人员对申请进行处理。 + + 流水线审批通过后,仓库的门禁就可以正常运行。 + +### OpenHarmony-sig孵化毕业 + +当三方库功能完成且符合[sig孵化毕业要求](https://gitee.com/openharmony/community/blob/master/sig/sig_qa/guidance_for_incubation_project_graduation_cn.md#sig%E5%AD%B5%E5%8C%96%E9%A1%B9%E7%9B%AE%E6%AF%95%E4%B8%9A%E8%AF%84%E5%AE%A1%E6%A3%80%E6%9F%A5%E9%A1%B9)后,可以申请申请孵化毕业,将该三方库孵化到OpenHarmony-TPC社区。 +孵化毕业的流程主要包含: + +- 孵化预审
+ 孵化预审会议定在每周二上午,孵化预审的步骤: + 1. [申请议题](https://gitee.com/openharmony/community/blob/master/zh/sig_governance.md#232-%E7%94%B3%E8%AF%B7%E8%B4%A8%E9%87%8Fsig%E5%AD%B5%E5%8C%96%E5%87%86%E5%87%BA%E8%AF%84%E5%AE%A1)。每次议题需要在上一周周日前申报完。 + 2. 申请完议题后需准备好预审材料(其中需要注意当时建仓时是否有遗留问题,此次评审需要保证之前的预留问题已解决),[预审材料模板](https://gitee.com/openharmony/community/blob/master/sig/sig_architecture/meetings/repository_review_template.pptx) +- 准出评审
+ 孵化预审通过后,需要申请质量SIG孵化准出评审,该会议定在每周二下午。 + 1. [申请议题](https://gitee.com/openharmony/community/blob/master/zh/sig_governance.md#23-%E4%BB%93%E5%BA%93%E5%AD%B5%E5%8C%96%E5%87%86%E5%87%BA)。 + 2. 参考[准出标准](https://gitee.com/openharmony/community/blob/master/sig/sig_qa/guidance_for_incubation_project_graduation_cn.md#sig%E5%AD%B5%E5%8C%96%E9%A1%B9%E7%9B%AE%E6%AF%95%E4%B8%9A%E8%AF%84%E5%AE%A1%E6%A3%80%E6%9F%A5%E9%A1%B9)准备孵化准出材料。 + 3. 涉及`代码检查报告`、`OAT扫描报告`、`Foss license扫描报告`、`资料规范性扫描报告`、`漏洞扫描报告`、`病毒扫描报告`、`XTS测试报告`等优先通过OpenHarmony数字化平台的孵化准出流程中获取,如若获取失败在通过其他方法获取。 + +- CI 平台孵化准出申请
+ 准出评审通过后,可以在[登录OpenHarmony数字化平台](http://ci.openharmony.cn/workbench/cicd/codecontrol/list)提交孵化准出电子流,具体步骤如下: + 1. [登录OpenHarmony数字化平台](http://ci.openharmony.cn/workbench/cicd/codecontrol/list) + 2. 选择孵化准出 + +  ![选择孵化准出](../imgs/incubate_step.png) + + 3. 填写孵化准出内容 + +  ![孵化准出内容1](../imgs/incubate_content1.png) +  ![孵化准出内容2](../imgs/incubate_content.png) + +### 合入OpenHarmony-TPC + +三方仓孵化准出成功后自动合入到OpenHarmony-TPC。 + +## 参考资料 diff --git a/imgs/ci_login1.png b/imgs/ci_login1.png new file mode 100755 index 0000000000000000000000000000000000000000..7c635fbed0c1f5b025f85e6f1ffae9d5bc1ec84c Binary files /dev/null and b/imgs/ci_login1.png differ diff --git a/imgs/ci_login2.png b/imgs/ci_login2.png new file mode 100755 index 0000000000000000000000000000000000000000..5b75719b81a1daa64453fa57d9d87982172c2e10 Binary files /dev/null and b/imgs/ci_login2.png differ diff --git a/imgs/incubate_content.png b/imgs/incubate_content.png new file mode 100755 index 0000000000000000000000000000000000000000..a1b9cef1c29bf3ba097145a1feadc86f38cabdd6 Binary files /dev/null and b/imgs/incubate_content.png differ diff --git a/imgs/incubate_content1.png b/imgs/incubate_content1.png new file mode 100755 index 0000000000000000000000000000000000000000..c3c3c3867ab9743522a6174b0376e67554b47546 Binary files /dev/null and b/imgs/incubate_content1.png differ diff --git a/imgs/incubate_step.png b/imgs/incubate_step.png new file mode 100755 index 0000000000000000000000000000000000000000..7cb5eca3326184f0441545bb10e17a27d4bda910 Binary files /dev/null and b/imgs/incubate_step.png differ diff --git a/imgs/pipeline_process_info1.png b/imgs/pipeline_process_info1.png new file mode 100755 index 0000000000000000000000000000000000000000..316616787c04414090965fc790ee98c2f10f2f8e Binary files /dev/null and b/imgs/pipeline_process_info1.png differ diff --git a/imgs/pipeline_process_info2.png b/imgs/pipeline_process_info2.png new file mode 100755 index 0000000000000000000000000000000000000000..b9adf0a9104d34d16d8f47e7f90ef5beb6c1651e Binary files /dev/null and b/imgs/pipeline_process_info2.png differ diff --git a/imgs/warehouse_create_step.png b/imgs/warehouse_create_step.png new file mode 100755 index 0000000000000000000000000000000000000000..e5a3dd7c51b96d3e58e25595c80e82dbbd61a4a3 Binary files /dev/null and b/imgs/warehouse_create_step.png differ diff --git a/imgs/warehouse_infomations.png b/imgs/warehouse_infomations.png new file mode 100755 index 0000000000000000000000000000000000000000..7023b9df2be4db00a041e359920cf72275dea3b1 Binary files /dev/null and b/imgs/warehouse_infomations.png differ