• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# restool
2
3
4## Overview
5
6restool is a resource compilation tool that creates resource indexes and parses resources by compiling resource files. You can call the [resource management APIs](../reference/apis-localization-kit/js-apis-resource-manager.md) to obtain resources. The tool is stored in the **toolchains** subdirectory of the SDK installation directory.
7
8## Description
9
10### Command Options
11
12| Option| Default Value Allowed| Argument Carried| Description|
13| -------- | -------- | -------- | -------- |
14| -i | No| Yes| Resource directory or resource middleware to create.<br>You can specify a compiled Hap resource directory (in the decompressed state) in the resource directory and implement overlay compilation based on the Hap resource directory.<br>For details, see [Compiling Resources](#compiling-resources).|
15| -j | No| Yes| Path of the **config.json** or **module.json** file.|
16| -o | No| Yes| Output path of the compiled resource.|
17| -p | No| Yes| Bundle name of the compiled resource.|
18| -r | No| Yes| Header file path of the resource. The header file can be in .txt, .js, or .h format.|
19| -e | Yes| Yes| Start ID of the generated resource, for example, **0x01000000**. The value range is [0x01000000, 0x06FFFFFF) and [0x08000000, 0x41FFFFFF).|
20| -f | Yes| No| An existing output path will be forcibly deleted and a new one will be generated.|
21| -h | Yes| No| Help information.|
22| -m | Yes| Yes| Module name. During joint module compilation, multiple module names can be specified, separated by commas (,).|
23| -x | Yes| Yes| Resource directory for generating intermediate files or a single resource path. The same command can run multiple times.|
24| -z | Yes| No| Compilation result generated based on the resource intermediate file directory.|
25| -v | Yes| No| Tool version.|
26| --ids | Yes| Yes| Output directory of the generated **id_defined.json** file.|
27| --defined-ids | Yes| Yes| Path of the **id_defined.json** file. Generally, the file is generated by using **--ids**.<br>**id_defined.json** contains a list of resource types, names, and IDs.<br>You can customize resource IDs in **id_defined.json**.|
28| --icon-check | Yes| No| Whether to enable PNG image verification for icons and startWindowIcons.|
29| --thread | Yes| Yes| Number of child threads enabled during resource compilation.|
30| --target-config | Yes| Yes| Used together with the **-i** command to support compilation selection.<br>For details, see **target-config Parameters**.|
31| --ignored-file | Yes| Yes| Ignoring rule for files and folders during resource compilation. The value is a regular expression. Multiple rules are separated by colons (:\). For example, **\\.git:\\.svn** indicates that the files and folders whose names are **.git** and **.svn** are ignored. |
32
33**target-config** Parameters
34
35Supported parameters: **MccMnc**, **Locale**, **Orientation**, **Device**, **ColorMode**, and **Density**.
36
37Format: Use semicolons (;\) to separate different parameter configurations. Use square brackets ([]) to encapsulate values for a parameter and use commas (,) to separate values.
38
39**MccMnc** matching rule: The MCC must always be used for matching. If an MNC is not included, a match is found as long as the MCC is the same. If an MNC is included, a match is found when both the MCC and MNC are the same.
40
41**Locale** matching rules:
42
431. The language must always be used for matching.
44
452. If a script (text) is not included, a match is found as long as the language is the same. If a script is included, a match is found when both the language and script are the same.
46
473. If a country/region is not included, a match is found as long as the language is the same. If a country/region is included, a match is found when both the language and country/region are the same.
48
49Example: Locale[zh_CN,en_US];Device[phone]. This configuration uses the languages zh_CN and en_US and the device phone as filter criteria. A match is found only when the resources use zh_CN and en_US as the languages and apply to phones. Other parameters (such as **MccMnc** and **Orientation**) are not configured and any values of them can match.
50
51### Subcommands
52
53| Command | Description|
54| ---  | ---- |
55| dump | Dumps the resource content in the HAP file in JSON format.|
56
57**dump**
58
59```
60restool dump [-h] [config] filePath
61```
62
63Parameters
64
65| Parameter| Default Value Allowed| Argument Carried| Description|
66| --- | --------- | ---------- |------- |
67| -h  | Yes| No| Help information.|
68| config | Yes| No| Qualifiers of resources in the HAP file.|
69
70Example:
71
72```sh
73# Dump all resource information in the HAP file.
74restool dump entry.hap
75# Dump qualifiers of resources in the HAP file.
76restool dump config entry.hap
77```
78
79## Example
80
81An example **entry** directory structure is as follows:
82```
83entry/src/main
84|    |----resource
85|    |    |----base
86|    |    |    |----element
87|    |    |    |----media
88|    |    |    |----profile
89|    |    |----rawfile
90|    |    |----resfile
91|    |----config.json/module.json
92```
93
94### Compiling Resources
95
96There are three resource compilation modes: full resource compilation, incremental resource compilation, and overlay resource compilation. Incremental compilation is available only in preview mode and is used to preview the component effect in the development phase. Full compilation is used to build resource files of a project. Overlay compilation allows resources in a project to be added to existing Hap template resources and compiled resource items to be reused.
97
981. To compile all resources, run the following command:
99
100```
101restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out -r out/ResourceTable.txt -f
102```
103
1042. To compile incremental resources, perform the following steps:
105
106Step 1: Generate the resource middleware.
107
108```
109restool -x entry/src/main/resource -o out
110```
111Step 2: Compile the resource middleware.
112
113```
114restool -i out1 -i out2 -o out -p com.ohos.demo -r out/ResourceTable.txt -j entry/src/main/module.json -f -z
115```
116
1173. To compile overlay resources, run the following command:
118
119```
120# hapResource is the path of the decompressed HAP file.
121restool -i entry/src/main -i hapResource -j entry/src/main/module.json -p com.ohos.demo -o out -r out/ResourceTable.txt -f
122```
123
124### Fixing the Resource ID
125
126To fix the resource ID, perform the following steps:
127
128Step 1: Create the **id_defined.json** file. There are two ways to create the file.
129
130+ Run the following command to generate the file:
131
132```
133restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out -r out/ResourceTable.txt --ids out -f
134```
135
136+ Customize the **id_defined.json** file with the following content:
137
138```
139{
140    "record" :
141    [
142        {
143            "id": "0x01000000", // A fixed ID for the resource.
144            "name": "app_name", // Resource name.
145            "type": "string" // Resource type.
146        }
147    ]
148}
149```
150
151Step 2: Fix the resource ID. There are two ways to fix the resource ID.
152
153+ Run the following command to fix the resource ID:
154```
155restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out1 -r out1/ResourceTable.txt --defined-ids out/id_defined.json -f
156```
157
158+ Place the customized **id_defined.json** file in the **resource/base/element/** directory and then run the following command to fix the resource ID:
159```
160restool -i entry/src/main -j entry/src/main/module.json -p com.ohos.demo -o out1 -r out1/ResourceTable.txt  -f
161```
162