README.md
1# System Capability Encoder and Decoder Tools
2
3SysCap(SystemCapability) encoder and decoder tools common usage scenarios as follow：
4
5APP development: IDE collect APP required SysCap and API verssion as in rpcid encoder input. And IDE will decode pcid to device SysCap list when it imported. This tool is only for use by the IDE, developers will not be used directly.
6
7Main function：
8
91. pcid Encode: Encode SysCap list to pcid.
10
112. pcid Decode: Decode pcid to get system SysCap list.
12
133. rpcid Encode: Encode APP required SysCap list to rpcid.
14
154. rpcid Decode: Decode rpcid to get APP required SysCap list.
16
17## File Structure
18
19```
20/developtools
21├── syscap_codec # syscap codec代码目录
22│ ├── include
23│ │ ├──code_config # syscap_tool_shared对外接口定义
24│ │ │ └──syscap_define.h
25│ │ ├── context_tool.h
26│ │ ├── create_pcid.h
27│ │ └── syscap_tool.h
28│ ├── interfaces/inner_api # 提供部件之间的接口
29│ │ ├── syscap_interface.c
30│ │ └── syscap_interface.h
31│ ├── napi # napi 接口实现
32│ │ ├── BUILD.gn
33│ │ ├── napi_query_syscap.cpp
34│ │ └── query_syscap.js
35│ ├── src
36│ │ ├── common_method.c
37│ │ ├── common_method.h
38│ │ ├── context_tool.c
39│ │ ├── create_pcid.c
40│ │ ├── endian_internal.h # 内部实现的大小端转换接口定义(便于win、mac、linux平台通用)
41│ │ ├── endian_internal.c # 大小端转换实现
42│ │ ├── main.c # syscap_tool命令行工具代码实现
43│ │ └── syscap_tool.c # syscap_tool编解码接口的实现
44│ └── test
45│ │ └── unittest/common # inner 接口测试代码实现
46│ │ ├── BUILD.gn
47│ │ ├── include
48│ │ │ └── syscap_codec_test.h
49│ │ └── syscap_codec_test.cpp # syscap_tool功能测试代码实现
50| |—— tools
51| │ ├── requirements.txt
52│ │ ├── syscap_check.py # syscap一致性检查脚本
53│ │ ├── syscap_collector.py
54| │ └── syscap_config_merge.py
55```
56
57### API
58
59PC tools, no API provided.
60
61### Building Manually
62
63syscap_tool binary building steps as follow：
64
651. Build commands：SysCap tools binary building and installation will be tiggered by SDK compiling procedure. How to build SDK please refer to https://gitee.com/openharmony/build/blob/master/README_zh.md.
66
672. Building cmd should be adjust for host platform as same as SDK compiling, the archive will in corresponding platform directoty.
68
69Note: Ubuntu host only avaiable for windows/linux building, MacOs binary should building on MacOs host.
70
71### Downloading Binary
72
731. Downlaod SDK(recommonded)
74
75Download daily builds( https://ci.openharmony.cn/workbench/cicd/dailybuild/dailylist ) which included SDK.
76
772. Supported Host
78
79Windows x86_64/Linux x86_64/Darwin x86_64
80
81### Help
82
83SysCap tools usually integrate to IDE, APP store and bundle tools. Follow instructions for debugging manually:
84
85./syscap_tool -h or ./syscap_tool --help：
86
87```
88./syscap_tool --help
89
90./syscap_tool -R/P -e/d -i filepath [-o outpath]
91
92-h, --help : how to use
93
94-R, --rpcid : encode or decode rpcid
95
96-P, --pcid : encode or decode pcid
97
98-e, --encode : to encode
99
100-d, --encode : to decode
101
102-i filepath, --input filepath : input file
103
104-o outpath, --output outpath : output path
105```
106
107## Syscap consistency check tool
108
109### Functions and dependencies
110
111The tool provides the following functions:
112
1131. Collect syscap fields of all components (or specified components), compare them with arraySyscap in developtools/ syscap_codec/include/syscap_define.h, and output the check results. If they are inconsistent, output the cause of the discrepancy.
1142. Collect the syscap fields of all components and compare them with the @syscap property set in *.d.ts in the Interface/sdk-js/api directory. If the check results are inconsistent, output the cause of the inconsistency.
1153. Compare syscap attributes in *.d.ts in all interface/ sdK-JS/API directories with arraySyscap in developtools/syscap_codec/include/syscap_define.h. If they are inconsistent, output the cause of the inconsistency.
116
117### How to use it
118
119This tool is written in Python language and needs to be executed using the Python interpreter.
120
121requirements：
122
123```txt
124prettytable==3.3.0
125```
126
127usage：
128
129```shell
130# check syscap field in all components for consistency with arraySyscap in syscap_define.h
131python3 syscap_check.py -p path_of_openarmony -t component_codec
132
133# check that the SYSCAP field in bundle.json of the specified part is consistent with arraySyscap in syscap_define.h. Note： --bundles is valid only if --check_target is component_codec
134python3 syscap_check.py -p path_of_openarmony -t component_codec -b path_of_component1/bundle.json path_of_component2/bundle.json
135
136# check the consistency of the syscap field of all components with the "@syscap" property set in *.d.ts
137python3 syscap_check.py -p path_of_openarmony -t component_sdk
138
139# check the "@syscap" attribute set in *.d.ts for consistency with arraSyscap in syscap_define.h
140python3 syscap_check.py -p path_of_openarmony -t sdk_codec
141```
142
143### Release Note
144
145v1.0.0 2022-3-8 first release, SysCap codec supported for Windows/Linux/Mac host.
146
README_ZH.md
1# 系统能力编解码工具
2
3系统能力(SystemCapability, 本文中使用SysCap缩写)编解码工具应用场景如下：
4
5应用开发时，IDE会根据应用配置的SysCap和API版本生成描述rpcid(Required Product Compatibility ID)的json文件，并调用编解码工具syscap_tool将该json文件编码成rpcid。另一方面，IDE拿到开发者导入pcid(Product Compatibility ID)，使用该工具解码出设备的SysCap集合。该工具仅供IDE使用，对用户不可见。
6
7提供的主要功能：
8
91. pcid编码：对描述SysCap集合的文件编码生成pcid。
10
112. pcid解码：对编码后的pcid文件解码获取SysCap集合。
12
133. rpcid编码：对描述应用所需的SysCap集合的文件编码生成rpcid。
14
154. rpcid解码：对编码后的rpcid文件解码获取应用所需的SysCap集合。
16
175. 编码字符串：将sc后缀形式的pcid/rpcid编码为字符串形式。
18
196. pcid与rpcid比较：查询pcid是否满足rpcid的要求，并输出不满足的地方。
20
21## 代码目录
22
23```
24/developtools
25├── syscap_codec # syscap codec代码目录
26│ ├── include
27│ │ ├──code_config # syscap_tool_shared对外接口定义
28│ │ │ └──syscap_define.h
29│ │ ├── context_tool.h
30│ │ ├── create_pcid.h
31│ │ └── syscap_tool.h
32│ ├── interfaces/inner_api # 提供部件之间的接口
33│ │ ├── syscap_interface.c
34│ │ └── syscap_interface.h
35│ ├── napi # napi 接口实现
36│ │ ├── BUILD.gn
37│ │ ├── napi_query_syscap.cpp
38│ │ └── query_syscap.js
39│ ├── src
40│ │ ├── common_method.c
41│ │ ├── common_method.h
42│ │ ├── context_tool.c
43│ │ ├── create_pcid.c
44│ │ ├── endian_internal.h # 内部实现的大小端转换接口定义(便于win、mac、linux平台通用)
45│ │ ├── endian_internal.c # 大小端转换实现
46│ │ ├── main.c # syscap_tool命令行工具代码实现
47│ │ └── syscap_tool.c # syscap_tool编解码接口的实现
48│ └── test
49│ │ └── unittest/common # inner 接口测试代码实现
50│ │ ├── BUILD.gn
51│ │ ├── include
52│ │ │ └── syscap_codec_test.h
53│ │ └── syscap_codec_test.cpp # syscap_tool功能测试代码实现
54| |—— tools
55| │ ├── requirements.txt
56│ │ ├── syscap_check.py # syscap一致性检查脚本
57│ │ ├── syscap_collector.py
58| │ └── syscap_config_merge.py
59```
60
61## API
62
63PC端工具，不对外提供API。
64
65## PC端编译说明
66
67syscap_tool PC端可执行文件编译步骤：
68
691. 编译命令：参考[编译构建](https://gitee.com/openharmony/build/blob/master/README_zh.md)文档，执行其指定的sdk编译命令来编译整个sdk，syscap_tool会被编译打包到里面。
702. 编译：在目标开发机上运行上面调整好的sdk编译命令，正常编译syscap_tool会输出到sdk平台相关目录下。
71
72注意：ubuntu环境下只能编译windows/linux版本工具，mac版需要在macos开发机上编译。
73
74## PC端获取说明
75
761. 下载sdk获取(建议)
77 通过访问本社区门禁[每日构建](https://ci.openharmony.cn/workbench/cicd/dailybuild/dailylist)网站，下载最新的ohos-sdk压缩包，并从相应平台的toolchains压缩包中提取syscap_tool。
782. 支持运行环境
79 Windows x86_64/Linux x86_64/Darwin x86_64
80
81## 命令帮助
82
83本工具一般被IDE、应用市场和包管理器集成，手工调试时可参考以下说明。
84
85使用./syscap_tool -h或者./syscap_tool --help查看：
86
87```shell
88syscap_tool -R/P -e/d -i filepath [-o outpath]
89-h, --help : how to use
90-R, --rpcid : encode or decode rpcid
91-P, --pcid : encode or decode pcid
92-C, --compare : compare pcid with rpcid string format.
93 -s, --string : input string.
94-e, --encode : encode to sc format.
95 -s, --string : encode to string format.
96-d, --decode : decode to json format.
97 -s, --string : decode string format.
98-i filepath, --input filepath : input file
99-o outpath, --output outpath : output path
100-v, --version : print syscap_tool version information.
101
102syscap_tool v1.1.1
103```
104
105### 使用示例
106
107```shell
108# 将 rpcid.json 编码为SC格式，文件名rpcid.sc
109syscap_tool -Rei rpcid.json -o path/
110
111# 将 rpcid.sc 解码为JSON格式，文件名rpcid.json
112syscap_tool -Rdi rpcid.sc -o path/
113
114# 将 pcid.json 编码为SC格式，文件名pcid.sc
115syscap_tool -Pei pcid.json -o path/
116
117# 将 pcid.sc 解码为JSON格式，文件名pcid.json
118syscap_tool -Pdi pcid.sc -o path/
119
120# 将 rpcid.sc 编码为字符串格式，文件名rpcid.txt
121syscap_tool -Resi rpcid.sc -o path/
122
123# 将 pcid.sc 编码为字符串格式，文件名pcid.txt
124syscap_tool -Pesi pcid.sc -o path/
125
126# 比较字符串格式的pcid和rpcid，pcid 符合条件返回成功提示，不符合则提示原因。
127syscap_tool -C pcid.txt rpcid.txt
128
129# 功能类似 -C选项，区别为 -sC 选项为直接输入字符串。
130syscap_tool -sC "pcidstring" "rpcidstring"
131
132# 将字符串格式的 pcid 转为 json 格式，文件名 pcid.json。
133syscap_tool -Pdsi pcid.txt -o path/
134```
135
136**说明：** -o 选项指定输出目录，缺省为当前目录。
137
138## syscap一致性检查工具
139
140### 功能及依赖
141
142本工具主要提供如下功能：
143
1441. 收集所有部件（或指定部件）的syscap字段并与developtools/sysap_codec/include/syscap_define.h中的arraySyscap比较，输出检查结果，若不一致，输出不一致的原因
1452. 收集所有部件的syscap字段并与interface/sdk-js/api目录下的*.d.ts中的“@syscap”属性集合比较，输出检查结果，若不一致，输出不一致的原因
1463. 收集所有interface/sdk-js/api目录下的*.d.ts中的syscap属性与developtools/syscap_codec/include/syscap_define.h中的arraySyscap比较，若不一致，输出不一致的原因
147
148### 使用方法
149
150本工具使用python语言编写，需使用python解释器进行执行。
151
152requirements：
153
154```txt
155prettytable==3.3.0
156```
157
158使用python3 syscap_check.py -h或python3 syscap_check.py --help查看用法：
159
160```shell
161usage: syscap_check.py [-h] [-p PROJECT_PATH] -t {component_codec,component_sdk,sdk_codec}
162 [-b [BUNDLES [BUNDLES ...]]]
163
164optional arguments:
165 -h, --help show this help message and exit
166 -p PROJECT_PATH, --project_path PROJECT_PATH
167 root path of project. default: ./
168 -t {component_codec,component_sdk,sdk_codec}, --check_target {component_codec,component_sdk,sdk_codec}
169 the target to be compared
170 -b [BUNDLES [BUNDLES ...]], --bundles [BUNDLES [BUNDLES ...]]
171 this option will take effect only when the check_target is component_codec. allow multiple
172 json file. default: all bundle.json file
173```
174
175使用示例：
176
177```shell
178# 检查所有部件的syscap字段与syscap_define.h中的arraySyscap一致性情况
179python3 syscap_check.py -p path_of_openarmony -t component_codec
180
181# 检查指定的部件的bundle.json中的syscap字段与syscap_define.h中的arraySyscap一致性情况，注意，只要当--check_target为component_codec时，--bundles才生效
182python3 syscap_check.py -p path_of_openarmony -t component_codec -b path_of_component1/bundle.json path_of_component2/bundle.json
183
184# 检查所有部件的syscap字段与*.d.ts中的“@syscap”属性集合的一致性情况
185python3 syscap_check.py -p path_of_openarmony -t component_sdk
186
187# 检查*.d.ts中的“@syscap"属性集合与syscap_define.h中的arraSyscap的一致性情况
188python3 syscap_check.py -p path_of_openarmony -t sdk_codec
189```
190
191## syscap_define.h 文件规则
192
193- 每一个 SyscapNum 枚举值都唯一对应于一个 syscap 字符串。
194- 如果弃用某个 syscap，在对应的枚举值后面注释 "// abandoned" 即可，请勿删除和修改。对应的 syscap 字符串也不需要修改。
195- 添加 syscap，请在 SyscapNum 和 g_arraySyscap 末尾添加相应数据。
196- 数组 g_arraySyscap 按照 SyscapNum 枚举值从小到大排序。
197
198## Release Note
199
200v1.1.0 2022-6-17 添加转字符串格式以及比较功能。
201v1.0.0 2022-3-8 首版本，提供Windows/Linux/Mac平台的系统能力编解码。
202