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 # root directory
22│ ├── include
23│ │ └── syscap_tool.h # interfaces
24│ └── src
25│ │ ├── endian_internel.h # internal big/little endian conversion headers(common for win、mac、linux)
26│ │ ├── endian_internel.c # big/little endian conversion implement
27│ │ ├── main.c # command line implement
28│ │ └── syscap_tool.c # codec implement
29│ └── test
30│ | └── syscap_tool_test.c # syscap_tool test codec implement
31| |—— tools
32| │ │
33| │ └── syscap_check.py # syscap一致性检查脚本
34```
35
36### API
37
38PC tools, no API provided.
39
40### Building Manually
41
42syscap_tool binary building steps as follow：
43
441. 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.
45
462. Building cmd should be adjust for host platform as same as SDK compiling, the archive will in corresponding platform directoty.
47
48Note: Ubuntu host only avaiable for windows/linux building, MacOs binary should building on MacOs host.
49
50### Downloading Binary
51
521. Downlaod SDK(recommonded)
53
54Download daily builds(http://ci.openharmony.cn/dailybuilds) which included SDK.
55
562. Supported Host
57
58Windows x86_64/Linux x86_64/Darwin x86_64
59
60### Help
61
62SysCap tools usually integrate to IDE, APP store and bundle tools. Follow instructions for debugging manually:
63
64./syscap_tool -h or ./syscap_tool --help：
65```
66./syscap_tool --help
67
68./syscap_tool -R/P -e/d -i filepath [-o outpath]
69
70-h, --help : how to use
71
72-R, --RPCID : encode or decode RPCID
73
74-P, --PCID : encode or decode PCID
75
76-e, --encode : to encode
77
78-d, --encode : to decode
79
80-i filepath, --input filepath : input file
81
82-o outpath, --input outpath : output path
83```
84
85## Syscap consistency check tool
86
87### Functions and dependencies
88
89The tool provides the following functions:
90
911. 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.
922. 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.
933. 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.
94
95### How to use it
96
97This tool is written in Python language and needs to be executed using the Python interpreter.
98
99requirements：
100
101```txt
102prettytable==3.3.0
103```
104
105usage：
106
107```shell
108# check syscap field in all components for consistency with arraySyscap in syscap_define.h
109python3 syscap_check.py -p path_of_openarmony -t component_codec
110
111# 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
112python3 syscap_check.py -p path_of_openarmony -t component_codec -b path_of_component1/bundle.json path_of_component2/bundle.json
113
114# check the consistency of the syscap field of all components with the "@syscap" property set in *.d.ts
115python3 syscap_check.py -p path_of_openarmony -t component_sdk
116
117# check the "@syscap" attribute set in *.d.ts for consistency with arraSyscap in syscap_define.h
118python3 syscap_check.py -p path_of_openarmony -t sdk_codec
119```
120
121### Release Note
122
123v1.0.0 2022-3-8 first release, SysCap codec supported for Windows/Linux/Mac host.
124
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/developtools
24├── syscap_codec # syscap codec代码目录
25│ ├── include # syscap_tool_shared对外接口定义
26│ │ ├── syscap_define.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│ │ └── syscap_interface.h
35│ ├── src
36│ │ ├── endian_internel.h # 内部实现的大小端转换接口定义(便于win、mac、linux平台通用)
37│ │ ├── endian_internel.c # 大小端转换实现
38│ │ ├── main.c # syscap_tool命令行工具代码实现
39│ │ └── syscap_tool.c # syscap_tool编解码接口的实现
40│ └── test
41│ │ ├── unittest/common # inner 接口测试代码实现
42│ │ │ ├── BUILD.gn
43│ │ │ ├── include
44│ │ │ │ └── syscap_codec_test.h
45│ │ │ └── syscap_codec_test.cpp
46│ │ └── syscap_tool_test.c # syscap_tool功能测试代码实现
47| |—— tools
48| │ │
49| │ └── syscap_check.py # syscap一致性检查脚本
50```
51
52## API
53PC端工具，不对外提供API。
54
55## PC端编译说明
56syscap_tool PC端可执行文件编译步骤：
571. 编译命令：参考[编译构建](https://gitee.com/openharmony/build/blob/master/README_zh.md)文档，执行其指定的sdk编译命令来编译整个sdk，syscap_tool会被编译打包到里面。
582. 编译：在目标开发机上运行上面调整好的sdk编译命令，正常编译syscap_tool会输出到sdk平台相关目录下。
59
60注意：ubuntu环境下只能编译windows/linux版本工具，mac版需要在macos开发机上编译。
61
62## PC端获取说明
631. 下载sdk获取(建议)
64 通过访问本社区门禁[每日构建](http://ci.openharmony.cn/dailys/dailybuilds)网站，下载最新的ohos-sdk压缩包，并从相应平台的toolchains压缩包中提取syscap_tool。
652. 支持运行环境
66 Windows x86_64/Linux x86_64/Darwin x86_64
67
68## 命令帮助
69本工具一般被IDE、应用市场和包管理器集成，手工调试时可参考以下说明。
70
71使用./syscap_tool -h或者./syscap_tool --help查看：
72```shell
73syscap_tool -R/P -e/d -i filepath [-o outpath]
74-h, --help : how to use
75-R, --RPCID : encode or decode RPCID
76-P, --PCID : encode or decode PCID
77-C, --compare : compare pcid with rpcid string format.
78 -s, --string : input string.
79-e, --encode : encode to sc format.
80 -s, --string : encode to string format.
81-d, --decode : decode to json format.
82 -s, --string : decode string format.
83-i filepath, --input filepath : input file
84-o outpath, --input outpath : output path
85-v, --version : print syscap_tool version information.
86
87syscap_tool v1.1.1
88```
89### 使用示例
90```shell
91# 将 RPCID.json 编码为SC格式，文件名RPCID.sc
92syscap_tool -Rei RPCID.json -o path/
93
94# 将 RPCID.sc 编码为JSON格式，文件名RPCID.json
95syscap_tool -Rdi RPCID.sc -o path/
96
97# 将 PCID.json 编码为SC格式，文件名PCID.sc
98syscap_tool -Pei PCID.json -o path/
99
100# 将 PCID.sc 编码为JSON格式，文件名PCID.json
101syscap_tool -Pdi PCID.sc -o path/
102
103# 将 RPCID.sc 编码为字符串格式，文件名RPCID.txt
104syscap_tool -Resi RPCID.sc -o path/
105
106# 将 PCID.sc 编码为字符串格式，文件名PCID.txt
107syscap_tool -Pesi PCID.sc -o path/
108
109# 比较字符串格式的PCID和RPCID，pcid 符合条件返回成功提示，不符合则提示原因。
110syscap_tool -C pcid.txt rpcid.txt
111
112# 功能类似 -C 选项，区别为 -SC 选项为直接输入字符串。
113syscap_tool -sC "pcidstring" "rpcidstring"
114
115# 将字符串格式的 pcid 转为 json 格式，文件名 PCID.json。
116syscap_tool -Pdsi pcid.txt -o path/
117```
118**说明：** -o 选项指定输出目录，缺省为当前目录。
119
120## syscap一致性检查工具
121
122### 功能及依赖
123
124本工具主要提供如下功能：
125
1261. 收集所有部件（或指定部件）的syscap字段并与developtools/sysap_codec/include/syscap_define.h中的arraySyscap比较，输出检查结果，若不一致，输出不一致的原因
1272. 收集所有部件的syscap字段并与interface/sdk-js/api目录下的*.d.ts中的“@syscap”属性集合比较，输出检查结果，若不一致，输出不一致的原因
1283. 收集所有interface/sdk-js/api目录下的*.d.ts中的syscap属性与developtools/syscap_codec/include/syscap_define.h中的arraySyscap比较，若不一致，输出不一致的原因
129
130### 使用方法
131
132本工具使用python语言编写，需使用python解释器进行执行。
133
134requirements：
135
136```txt
137prettytable==3.3.0
138```
139
140使用python3 syscap-check.py -h或python3 syscap-check.py --help查看用法：
141
142```shell
143usage: syscap_check.py [-h] [-p PROJECT_PATH] -t {component_codec,component_sdk,sdk_codec}
144 [-b [BUNDLES [BUNDLES ...]]]
145
146optional arguments:
147 -h, --help show this help message and exit
148 -p PROJECT_PATH, --project_path PROJECT_PATH
149 root path of project. default: ./
150 -t {component_codec,component_sdk,sdk_codec}, --check_target {component_codec,component_sdk,sdk_codec}
151 the target to be compared
152 -b [BUNDLES [BUNDLES ...]], --bundles [BUNDLES [BUNDLES ...]]
153 this option will take effect only when the check_target is component_codec. allow multiple
154 json file. default: all bundle.json file
155```
156
157使用示例：
158
159```shell
160# 检查所有部件的syscap字段与syscap_define.h中的arraySyscap一致性情况
161python3 syscap_check.py -p path_of_openarmony -t component_codec
162
163# 检查指定的部件的bundle.json中的syscap字段与syscap_define.h中的arraySyscap一致性情况，注意，只要当--check_target为component_codec时，--bundles才生效
164python3 syscap_check.py -p path_of_openarmony -t component_codec -b path_of_component1/bundle.json path_of_component2/bundle.json
165
166# 检查所有部件的syscap字段与*.d.ts中的“@syscap”属性集合的一致性情况
167python3 syscap_check.py -p path_of_openarmony -t component_sdk
168
169# 检查*.d.ts中的“@syscap"属性集合与syscap_define.h中的arraSyscap的一致性情况
170python3 syscap_check.py -p path_of_openarmony -t sdk_codec
171```
172
173## syscap_define.h 文件规则
174- 每一个 SyscapNum 枚举值都唯一对应于一个 syscap 字符串。
175- 如果弃用某个 syscap，在对应的枚举值后面注释 "// abandoned" 即可，请勿删除和修改。对应的 syscap 字符串也不需要修改。
176- 添加 syscap，请在 SyscapNum 和 g_arraySyscap 末尾添加相应数据。
177- 数组 g_arraySyscap 按照 SyscapNum 枚举值从小到大排序。
178
179
180## Release Note
181v1.1.0 2022-6-17 添加转字符串格式以及比较功能。
182v1.0.0 2022-3-8 首版本，提供Windows/Linux/Mac平台的系统能力编解码。
183