1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
|
# **YANG Compiler**
## Overview
Yang compiler is a tool based on [YangKit](https://github.com/yang-central/yangkit), it's designed to solve the problem of YANG files compilation dependencies.
For example, after a YANG module is written, if you want to validate it, you need to add all missing YANG module dependencies to your path. This could be troublesome because dependencies are chained, and the chain of dependencies for a YANG module may be very long. In addition,
where these dependented YANG files are archived and how to obtain these YANG files are also difficult problems. This brings great inconvenience to users and
affects their enthusiasm for using YANG.
Yang compiler provide a mechanism to get the dependencies automatically when compiling YANG modules. Firstly, it will search the dependencies from yang sources to be complied, if not found, it will search these YANG files from local repository(it's defined in settings.json or default directory), and if it's not found also, it will search the dependencies from module information defined in settings.json(if available), and according to the information to download the YANG files. if it's still not found, it will search the dependencies for remote repository(defined in settings.json or
[yangcatalog](https://yangcatalog.org/api/) by default). If the dependencies are fetched, it will be saved into local repository.
Using Yang compiler, you can compile any YANG file regardless where it's dependencies are. Yang compiler allow developer to develop
plugin to extend customized functions.
## Architecture
## Specification
* search and download dependencies automatically.
* allow user to customize settings for compilation.
* customize local repository,{user.home}/.yang is default.
* customize remote repository, [yangcatalog](https://yangcatalog.org/api/) is default.
* support proxy.
* define module information directly if some modules are not in [yangcatalog](https://yangcatalog.org/api/).
* allow user to install yang files which are compiled OK.
* allow developer to develop customized plugin.
## Installation
###  Prerequisites
* JDK or JRE 1.8 or above
###  Obtain code
```
# git clone "https://gerrit.onap.org/r/a/modeling/yang-kit"
```
###  Build code
```
# cd yangkit/yang-compiler
# mvn clean install
```
 it will generate yang-compiler-1.0-SNAPSHOT.jar and libs directory under the directory target.
###  Make application package for YANG compiler
1. create a directory in anywhere (of your computer), we may call it application directory. The name of directory should be yang-compiler-x.y.z(e.g., yang-compiler-1.0.0)
2. copy yang-compiler-1.0-SNAPSHOT.jar and libs to the application directory you created in previous step.
3. (optional)place settings.json into application directory if needed.
4. (optional)create a sub-directory named 'plugins' under application directory if external plugins are need, then place plugins.json into this directory.
####   Example of application package
```
|--yang-compiler-1.0.0
|--libs
|--plugins
|----plugins.json
|--settings.json
|--yang-compiler-1.0.0.jar
```
## Specification of settings
1. local-repository: local repo directory to find the missing yang module dependencies, the default directory is {user.home}/.yang
2. remote-repository: remote url, it will fetch the yang module dependencies to local repo if yang compiler request, [yangcatalog](https://yangcatalog.org/api/) is default.
3. proxy: the proxy information, if you are in local network and can't access internet directly, the proxy information must be provided.
1. url: the url of proxy including port number.
2. authentication: the authentication information, username and password should be provided if needed by proxy.
4. token: the token information, if the remote repo needed.
5. module-info: the information of yang schema. if some dependencies are not in local and remote repos, you can specify the schema information by hand.
1. name: module name,mandatory.
2. revision: revision date,mandatory.
3. schema: the url where the yang schema stores.
###  Example:
```json
{
"settings": {
"local-repository": "/Users/llly/yang",
"remote-repository": "https://yangcatalog.org/api/",
"proxy": {
"url":"http:proxy.mydomain.com:8080",
"authentication": {
"username":"foo",
"password":"bar"
}
},
"module-info": [
{
"name": "openconfig-acl",
"revision": "2022-01-14",
"schema": "https://raw.githubusercontent.com/openconfig/public/master/release/models/acl/openconfig-acl.yang"
},
{
"name": "openconfig-packet-match-types",
"revision": "2021-07-14",
"schema": "https://raw.githubusercontent.com/openconfig/public/master/release/models/acl/openconfig-packet-match-types.yang"
}
]
}
}
```
## Develop plugin
The plugin system of Yang compiler support built-in plugin and external plugin. Built-in plugin is in yang-compiler project, and external plugin can be in anywhere.
###  Specification of plugin information
1. name: the name of plugin, it MUST be unique.
2. class-path: the class path of plugin class, it MUST be provided when the plugin is an external plugin. It can be relative path or absolute path,
if it's a relative path, the base path is plugins directory of application directory.
3. class: class name which implements org.yangcentral.yangkit.compiler.plugin.YangCompilerPlugin.
4. description: some description information about this plugin.
5. parameter: parameter information, it's json array. name and description of a parameter MUST be provided.
###  How to develop a built-in plugin
1. specified a unique plugin name. e.g. yang-tree-generator.
2. write a java class implements YangCompilerPlugin.
@see [YangValidator](src/main/java/org/yangcentral/yangkit/plugin/yangtree/YangTreeGenerator.java)
3. add plugin information in plugins.json(in src/main/resource)
####   Example
```json
{
"plugins": {
"plugin": [
{
"name": "validator_plugin",
"class": "org.onap.modelling.yangkit.compiler.plugin.validator.YangValidator",
"description": "a plugin for validating yang files",
"parameter": [
{
"name": "output",
"description": "the output directory."
}
]
}
]
}
}
```
###  How to develop an external plugin
1. specified a unique plugin name. e.g. yang-tree-generator.
2. create a java project, and write a java class implements YangCompilerPlugin.
3. build the java project, and get the corresponding jar.
4. add plugin information to plugins.json ({application directory}/plugins/plugins.json), class-path MUST point to the jar generated at previous step.
####   Example
```json
{
"plugins": {
"plugin": [
{
"name": "yang_comparator",
"class-path": "yang-comparator/yang-comparator-1.0-SNAPSHOT.jar",
"class": "org.onap.modelling.yangkit.comparator.app.YangComparatorPlugin",
"description": "a plugin for comparing two yang schema.",
"parameter": [
{
"name": "old-yang",
"description": "mandatory,the old version yang sources."
},
{
"name": "settings",
"description": "optional,the settings file path."
},
{
"name": "compare-type",
"description": "mandatory, specify compare-type, one of stmt,tree,or compatible-check"
},
{
"name": "rule",
"description": "optional, specify the path of compatible-rule file."
},
{
"name": "result",
"description": "mandatory, specify the compare result file path, the result file is a xml format."
}
]
}
]
}
}
```
## Compile YANG modules:
1. make a yang compiler project. You can create a directory in anywhere of your computer.
2. make a directory under project directory as target directory where YANG modules what you want to compile store. 'yang' is recommended as the name of the directory.
3. place build.json into project directory. The build.json specify the options of this compilation.
4. execute the commandline to compile YANG modules.
###  Example of yang compiler project
```
|--yang-test(project name)
|--yang(yang modules to be compiled)
|--build.json
```
###  Specification of compilation options
1. yang: source yang information, support directory, file list, module information, or hybrid.
2. settings: specify the path of settings.json, optional, if it's not present, the {user.home}/.yang/settings.json will be used.
3. plugin: a json array,specify the parameters of plugins which will be called.
1. name: the plugin name.
2. parameter: the parameters of a plugin. name and value should be specified.
####   Examples:
```json
{
"yang": {
"module": [
{
"name": "ietf-interfaces",
"revision": ""
},
{
"name": "huawei-ifm",
"revision": "2022-08-06"
},
{
"name": "huawei-bgp",
"revision": ""
},
{
"name": "huawei-network-instance",
"revision": ""
}
],
"dir" : [
"yang/ietf",
"yang/huawei"
],
"file" : [
"yang/ietf/ietf-interfaces.yang",
"yang/huawei/huawei-bgp.yang"
]
},
"settings" : "settings.json",
"plugin": [
{
"name": "validator_plugin",
"parameter": [
{
"name": "output",
"value": "yang/validator.txt"
}
]
},
{
"name": "yangtree_generator",
"parameter": [
{
"name": "output",
"value": "tree"
},
{
"name": "expand-grouping",
"value": "true"
}
]
},
{
"name": "yang_statistics",
"parameter" : [
{
"name": "output",
"value": "statistics/node_description.xlsx"
},
{
"name" : "tag",
"value": [
{
"name": "operation-exclude",
"keyword": "huawei-extension:operation-exclude"
}
]
}
]
}
]
}
```
###  Commandline
```
# java -jar yang-compiler-1.0.0-SNAPSHOT.jar [option=<_build.json_>] [install]
```
####   Parameters
1. option: optional, specify the build option. It's the path of build.json, if not present, the build.json in current directory will be used.
2. install: optional, if it's not present, the yang files to be complied will not be copied into local repo directory, if it's present, all yang files which is successfully compiled will be copied into local repository.
|
