1Output API as JSON data
2=======================
3
4We have written a script that will read the header files in LVGL and outputs a more friendly JSON format for the API.
5This is done so that bindings that generate code automatically will have an easy way to collect the needed information
6without having to reinvent the wheel. The JSON data format has already made libraries for reading the format for just
7about every programming language out there.
8
9The script in order to run does have some requirements.
10
11- Python >= 3.10
12- Pycparser >= 2.21: Python Library for reading the preprocessor ouotput from the C compiler
13- PyMSVC >= 0.4.0: Python library is using MSVC Compiler
14- C compiler, gcc for Linux, clang for OSX and MSVC for Windows
15- Doxygen: used to read the docstrings from the header files.
16
17
18There are several options when running the script. They are as follows
19
20- `--output-path`: output directory for JSON file. If one is not supplied then it will be output stdout
21- `--lvgl-config`: path to lv_conf.h (including file name), if this is not set then a config file will be
22  generated that has most common things turned on
23- `--develop`: leaves the temporary folder in place.
24
25
26to use the script
27
28.. code-block:: shell
29
30    python /scripts/gen_json/gen_json.py --output-path=json/output/directory --lvgl-config=path/to/lv_conf.h
31
32
33or if you want to run a subprocess from inside of a generation script and read the output from stdout
34
35.. code-block:: shell
36
37    python /scripts/gen_json/gen_json.py --lvgl-config=path/to/lv_conf.h
38
39
40The JSON data is broken apart into a couple of main categories.
41
42- enums
43- functions
44- function_pointers
45- structures
46- unions
47- variables
48- typedefs
49- forward_decls
50- macros
51
52Those categories are the element names undert the root of the JSON data.
53The value for each categry is an array of JSON elements. There is a bit of
54nesting with the elements in the arrays and I have created "json_types" that
55will allow you to identify exactly what you are dealing with.
56
57The different "json_types" are as follows:
58
59- ``"array"``: The array type is used to identify arrays.
60
61  Available JSON fields:
62    - ``"dim"``: number of items in the array
63    - ``"quals"``: array of qualifiers, IE "const"
64    - ``"type"``: This may or may not be available.
65    - ``"name"``: the name of the data type
66
67
68- ``"field"``: This type is used to describe fields in structures and unions.
69  It is used in the ``"fields"`` array of the ``"struct"`` and ``"union"`` JSON types.
70
71  Available JSON fields:
72    - ``"name"``: The name of the field.
73    - ``"type"``: This contains the type information for the field. Check the
74      ``"json_type"`` to know what type you are dealing with.
75    - ``"bitsize"``: The number of bits the field has or ``null``
76      if there is no bit size defined
77    - ``"docstring"``: you should know what this is.
78
79
80- ``"arg"``: Used to describe an argument/parameter in a function or a function pointer.
81
82  Available JSON fields:
83    - ``"name"``: The name of the argument/parameter.
84    - ``"type"``: This contains the type information for the field. Check the
85      ``"json_type"`` to know what type you are dealing with.
86    - ``"docstring"``: you should know what this is.
87    - ``"quals"``: array of qualifiers, IE "const"
88
89
90- ``"forward_decl"``: Describes a forward declaration.There are structures in
91  LVGL that are considered to be private and that is what these desccribe.
92
93  Available JSON fields:
94    - ``"name"``: The name of the formard declaration.
95    - ``"type"``: This contains the type information for the field. Check the
96      ``"json_type"`` to know what type you are dealing with.
97    - ``"docstring"``: you should know what this is.
98    - ``"quals"``: array of qualifiers, IE "const"
99
100
101- ``"function_pointer"``: Describes a function pointer. These are used when
102  registering callback functions in LVGL.
103
104  Available JSON fields:
105    - ``"name"``: The name of the function pointer.
106    - ``"type"``: This contains the return type information for the function pointer.
107    - ``"docstring"``: you should know what this is.
108    - ``"args"``: array of ``"arg"`` Widgets. This describes the function arguments/parameters.
109    - ``"quals"``: array of qualifiers, IE "const"
110
111
112- ``"variable"``: Describes a global variable.
113
114  Available JSON fields:
115    - ``"name"``: The name of the variable.
116    - ``"type"``: This contains the type information for the field. Check the
117      ``"json_type"`` to know what type you are dealing with.
118    - ``"docstring"``: you should know what this is.
119    - ``"quals"``: array of qualifiers, IE "const"
120    - ``"storage"``: array of storage classifiers, IE "extern"
121
122
123- ``"special_type"``:  Currently only used to describe an ellipsis argument
124  for a function.
125
126  Available JSON fields:
127    - ``"name"``: will always be "ellipsis".
128
129
130- ``"primitive_type"``: This is a base type. There or no other types beneith this.
131  This tells you that the type is a basic or primitive C type.
132  IE: struct, union, int, unsigned int, etc...
133
134  Available JSON fields:
135    - ``"name"``: The name of the primitive type.
136
137
138- ``"enum"``: Describes a grouping of enumeration items/members.
139
140  Available JSON fields:
141    - ``"name"``: The name of the enumeration group/type.
142    - ``"type"``: This contains the type information for the enumeration group.
143      This is always going to be an "int" type. Make sure you do not use this
144      type as the type for the members of this enumeration group. Check the
145      enumeration members type to get the correct type.
146    - ``"docstring"``: you should know what this is.
147    - ``"members"``: array of ``"enum_member"`` Widgets
148
149
150- ``"enum_member"``: Describes an enumeration item/member. Only found under
151  the ``"members"`` field of an ``"enum"`` JSON type
152
153  Available JSON fields:
154    - ``"name"``: The name of the enumeration.
155    - ``"type"``: This contains the type information for the enum member.
156      This gets a bit tricky because the type specified in here is not always
157      going to be an "int". It will usually point to an lvgl type and the type
158      of the lvgl type can be found in the ``"typedefs"`` section.
159    - ``"docstring"``: you should know what this is.
160    - ``"value"``: the enumeration member/item's value
161
162
163- ``"lvgl_type"``: This is a base type. There or no other types beneith this.
164  This tells you that the type is an LVGL data type.
165
166  Available JSON fields:
167    - ``"name"``: The name of the type.
168    - ``"quals"``: array of qualifiers, IE "const
169
170
171- ``"struct"``: Describes a structure
172
173  Available JSON fields:
174    - ``"name"``: The name of the structure.
175    - ``"type"``: This contains the primitive type information for the structure.
176    - ``"docstring"``: you should know what this is.
177    - ``"fields"``: array of ``"field"`` elements.
178    - ``"quals"``: array of qualifiers, IE "const"
179
180
181- ``"union"``: Describes a union
182
183  Available JSON fields:
184    - ``"name"``: The name of the union.
185    - ``"type"``: This contains the primitive type information for the union.
186    - ``"docstring"``: you should know what this is.
187    - ``"fields"``: array of ``"field"`` elements.
188    - ``"quals"``: array of qualifiers, IE "const"
189
190
191- ``"macro"``: describes a macro. There is limited information that can be
192  collected about macros and in most cases a binding will need to have these
193  statically added to a binding. It is more for collecting the docstrings than
194  anything else.
195
196  Available JSON fields:
197    - ``"name"``: The name of the macro.
198    - ``"docstring"``: you should know what this is.
199
200
201- ``"ret_type"``: return type from a function. This is only going to be seen in the ``"type"``
202  element of a ``"function"`` type.
203
204  Available JSON fields:
205    - ``"type"``: This contains the type information for the field. Check the
206      ``"json_type"`` to know what type you are dealing with.
207    - ``"docstring"``: you should know what this is.
208
209
210- ``"function"``: Describes a function.
211
212  Available JSON fields:
213    - ``"name"``: The name of the function.
214    - ``"type"``: This contains the type information for the return value.
215    - ``"docstring"``: you should know what this is.
216    - ``"args"``: array of ``"arg"`` json types. This describes the function arguments/parameters.
217
218
219- ``"stdlib_type"``: This is a base type, meaning that there are no more
220  type levels beneith this. This tells us that the type is from the C stdlib.
221
222  Available JSON fields:
223    - ``"name"``: The name of the type.
224    - ``"quals"``: array of qualifiers, IE "const
225
226
227- ``"unknown_type"``: This should not be seen. If it is then there needs to be
228  an adjustment made to the script. Please open an issue and let us know if you see this type.
229
230  Available JSON fields:
231    - ``"name"``: The name of the type.
232    - ``"quals"``: array of qualifiers, IE "const
233
234
235- ``"pointer"``: This is a wrapper object to let you know that the type you
236  are dealing with is a pointer
237
238  Available JSON fields:
239    - ``"type"``: This contains the type information for the pointer. Check the
240      ``"json_type"`` to know what type you are dealing with.
241    - ``"quals"``: array of qualifiers, IE "const", may or may not be available.
242
243
244- ``"typedef"``: type definitions. I will explain more on this below.
245
246  Available JSON fields:
247    - ``"name"``: The name of the typedef.
248    - ``"type"``: This contains the type information for the field. Check the
249      ``"json_type"`` to know what type you are dealing with.
250    - ``"docstring"``: you should know what this is.
251    - ``"quals"``: array of qualifiers, IE "const"
252
253
254
255Here is an example of what the output will look like.
256
257.. code-block:: json
258
259    {
260        "enums":[
261            {
262                "name":"_lv_result_t",
263                "type":{
264                    "name":"int",
265                    "json_type":"primitive_type"
266                },
267                "json_type":"enum",
268                "docstring":"LVGL error codes. ",
269                "members":[
270                    {
271                        "name":"LV_RESULT_INVALID",
272                        "type":{
273                            "name":"_lv_result_t",
274                            "json_type":"lvgl_type"
275                        },
276                        "json_type":"enum_member",
277                        "docstring":"",
278                        "value":"0x0"
279                    },
280                    {
281                        "name":"LV_RESULT_OK",
282                        "type":{
283                            "name":"_lv_result_t",
284                            "json_type":"lvgl_type"
285                        },
286                        "json_type":"enum_member",
287                        "docstring":"",
288                        "value":"0x1"
289                    }
290                ]
291            }
292        ],
293        "functions":[
294            {
295                "name":"lv_version_info",
296                "type":{
297                    "type":{
298                        "type":{
299                            "name":"char",
300                            "json_type":"primitive_type",
301                            "quals":[
302                                "const"
303                            ]
304                        },
305                        "json_type":"pointer",
306                        "quals":[]
307                    },
308                    "json_type":"ret_type",
309                    "docstring":""
310                },
311                "json_type":"function",
312                "docstring":"",
313                "args":[
314                    {
315                        "name":null,
316                        "type":{
317                            "name":"void",
318                            "json_type":"primitive_type",
319                            "quals":[]
320                        },
321                        "json_type":"arg",
322                        "docstring":"",
323                        "quals":[]
324                    }
325                ]
326            }
327        ],
328        "function_pointers":[
329            {
330                "name":"lv_tlsf_walker",
331                "type":{
332                    "type":{
333                        "name":"void",
334                        "json_type":"primitive_type",
335                        "quals":[]
336                    },
337                    "json_type":"ret_type",
338                    "docstring":""
339                },
340                "json_type":"function_pointer",
341                "docstring":"",
342                "args":[
343                    {
344                        "name":"ptr",
345                        "type":{
346                            "type":{
347                                "name":"void",
348                                "json_type":"primitive_type",
349                                "quals":[]
350                            },
351                            "json_type":"pointer",
352                            "quals":[]
353                        },
354                        "json_type":"arg",
355                        "docstring":""
356                    },
357                    {
358                        "name":"size",
359                        "type":{
360                            "name":"size_t",
361                            "json_type":"stdlib_type",
362                            "quals":[]
363                        },
364                        "json_type":"arg",
365                        "docstring":""
366                    },
367                    {
368                        "name":"used",
369                        "type":{
370                            "name":"int",
371                            "json_type":"primitive_type",
372                            "quals":[]
373                        },
374                        "json_type":"arg",
375                        "docstring":""
376                    },
377                    {
378                        "name":"user",
379                        "type":{
380                            "type":{
381                                "name":"void",
382                                "json_type":"primitive_type",
383                                "quals":[]
384                            },
385                            "json_type":"pointer",
386                            "quals":[]
387                        },
388                        "json_type":"arg",
389                        "docstring":""
390                    }
391                ],
392                "quals":[]
393            }
394        ],
395        "structures":[
396            {
397                "name":"_lv_gradient_cache_t",
398                "type":{
399                    "name":"struct",
400                    "json_type":"primitive_type"
401                },
402                "json_type":"struct",
403                "docstring":null,
404                "fields":[
405                    {
406                        "name":"color_map",
407                        "type":{
408                            "type":{
409                                "name":"lv_color_t",
410                                "json_type":"lvgl_type",
411                                "quals":[]
412                            },
413                            "json_type":"pointer",
414                            "quals":[]
415                        },
416                        "json_type":"field",
417                        "bitsize":null,
418                        "docstring":""
419                    },
420                    {
421                        "name":"opa_map",
422                        "type":{
423                            "type":{
424                                "name":"lv_opa_t",
425                                "json_type":"lvgl_type",
426                                "quals":[]
427                            },
428                            "json_type":"pointer",
429                            "quals":[]
430                        },
431                        "json_type":"field",
432                        "bitsize":null,
433                        "docstring":""
434                    },
435                    {
436                        "name":"size",
437                        "type":{
438                            "name":"uint32_t",
439                            "json_type":"stdlib_type",
440                            "quals":[]
441                        },
442                        "json_type":"field",
443                        "bitsize":null,
444                        "docstring":""
445                    }
446                ]
447            }
448        ],
449        "unions":[],
450        "variables":[
451            {
452                "name":"lv_global",
453                "type":{
454                    "name":"lv_global_t",
455                    "json_type":"lvgl_type",
456                    "quals":[]
457                },
458                "json_type":"variable",
459                "docstring":"",
460                "quals":[],
461                "storage":[
462                    "extern"
463                ]
464            }
465        ],
466        "typedefs":[
467            {
468                "name":"lv_pool_t",
469                "type":{
470                    "type":{
471                        "name":"void",
472                        "json_type":"primitive_type",
473                        "quals":[]
474                    },
475                    "json_type":"pointer"
476                },
477                "json_type":"typedef",
478                "docstring":"",
479                "quals":[]
480            }
481        ],
482        "forward_decls":[
483            {
484                "name":"lv_fragment_managed_states_t",
485                "type":{
486                    "name":"struct",
487                    "json_type":"primitive_type"
488                },
489                "json_type":"forward_decl",
490                "docstring":"",
491                "quals":[]
492            }
493        ],
494        "macros":[
495            {
496                "name":"ZERO_MEM_SENTINEL",
497                "json_type":"macro",
498                "docstring":""
499            }
500        ]
501    }
502