README.md
1# kconfig_new
2
3kconfig_new is the kconfig support used by the CMake-based build system.
4
5It depends on the [kconfiglib](https://github.com/ulfalizer/Kconfiglib) package.
6
7## confserver.py
8
9confserver.py is a small Python program intended to support IDEs and other clients who want to allow editing sdkconfig, without needing to reproduce all of the kconfig logic in a particular program.
10
11After launching confserver.py (which can be done via `idf.py confserver` command or `confserver` build target in ninja/make), the confserver communicates via JSON sent/received on stdout. Out-of-band errors are logged via stderr.
12
13### Configuration Structure
14
15During cmake run, the CMake-based build system produces a number of metadata files including `build/config/kconfig_menus.json`, which is a JSON representation of all the menu items in the project configuration and their structure.
16
17This format is currently undocumented, however running CMake with an IDF project will give an indication of the format. The format is expected to be stable.
18
19### Initial Process
20
21After initializing, the server will print "Server running, waiting for requests on stdin..." on stderr.
22
23Then it will print a JSON dictionary on stdout, representing the initial state of sdkconfig:
24
25```
26{
27 "version": 2,
28 "ranges": {
29 "TEST_CONDITIONAL_RANGES": [0, 10] },
30 "visible": { "TEST_CONDITIONAL_RANGES": true,
31 "CHOICE_A": true,
32 "test-config-submenu": true },
33 "values": { "TEST_CONDITIONAL_RANGES": 1,
34 "CHOICE_A": true },
35}
36```
37
38(Note: actual output is not pretty-printed and will print on a single line. Order of dictionary keys is undefined.)
39
40* "version" key is the protocol version in use.
41* "ranges" holds is a dictionary for any config symbol which has a valid integer range. The array value has two values for min/max.
42* "visible" holds a dictionary showing initial visibility status of config symbols (identified by the config symbol name) and menus (which don't represent a symbol but are represented as an id 'slug'). Both these names (symbol name and menu slug) correspond to the 'id' key in kconfig_menus.json.
43* "values" holds a dictionary showing initial values of all config symbols. Invisible symbols are not included here.
44
45### Interaction
46
47Interaction consists of the client sending JSON dictionary "requests" to the server one at a time. The server will respond to each request with a JSON dictionary response. Interaction is done when the client closes stdout (at this point the server will exit).
48
49Requests look like:
50
51```
52{ "version": 2,
53 "set": { "TEST_CHILD_STR": "New value",
54 "TEST_BOOL": true }
55}
56```
57
58Note: Requests don't need to be pretty-printed, they just need to be valid JSON.
59
60The `version` key *must* be present in the request and must match a protocol version supported by confserver.
61
62The `set` key is optional. If present, its value must be a dictionary of new values to set on kconfig symbols.
63
64Additional optional keys:
65
66* `load`: If this key is set, sdkconfig file will be reloaded from filesystem before any values are set applied. The value of this key can be a filename, in which case configuration will be loaded from this file. If the value of this key is `null`, configuration will be loaded from the last used file. The response to a "load" command is always the full set of config values and ranges, the same as when the server is initially started.
67
68* `save`: If this key is set, sdkconfig file will be saved after any values are set. Similar to `load`, the value of this key can be a filename to save to a particular file, or `null` to reuse the last used file.
69
70After a request is processed, a response is printed to stdout similar to this:
71
72```
73{ "version": 2,
74 "ranges": {},
75 "visible": { "test-config-submenu": false},
76 "values": { "SUBMENU_TRIGGER": false }
77}
78```
79
80* `version` is the protocol version used by the server.
81* `ranges` contains any changed ranges, where the new range of the config symbol has changed (due to some other configuration change or because a new sdkconfig has been loaded).
82* `visible` contains any visibility changes, where the visible config symbols have changed.
83* `values` contains any value changes, where a config symbol value has changed. This may be due to an explicit change (ie the client `set` this value), or a change caused by some other change in the config system. Note that a change which is set by the client may not be reflected exactly the same in the response, due to restrictions on allowed values which are enforced by the config server. Invalid changes are ignored by the config server.
84
85If setting a value also changes the possible range of values that an item can have, this is also represented with a dictionary `ranges` that contains key/value pairs of config items to their new ranges:
86
87```
88{ "version": 2,
89 "values": {"OTHER_NAME": true },
90 "visible": { },
91 "ranges" : { "HAS_RANGE" : [ 3, 4 ] } }
92```
93
94Note: The configuration server does not automatically load any changes which are applied externally to the `sdkconfig` file. Send a "load" command or restart the server if the file is externally edited.
95
96Note: The configuration server does not re-run CMake to regenerate other build files or metadata files after `sdkconfig` is updated. This will happen automatically the next time ``CMake`` or ``idf.py`` is run.
97
98### KConfig Item Types
99
100* `string` types are represented as JSON strings.
101* `bool` and `tristate` types are represented as JSON Booleans, the third `tristate` state is not supported.
102* `int` types are represented as JSON integers
103* `hex` types are also represented as JSON integers, clients should read the separate metadata file to know if the UI representation is `int` or `hex`. It is possible to set a `hex` item by sending the server a JSON string of hex digits (no prefix) as the value, but the server always sends `hex` values as JSON integers.
104
105### Error Responses
106
107In some cases, a request may lead to an error message. In this case, the error message is printed to stderr but an array of errors is also returned in the `error` key of the response:
108
109```
110{ "version": 777,
111 "error": [ "Unsupported request version 777. Server supports versions 1-2" ]
112}
113```
114
115These error messages are intended to be human readable, not machine parseable.
116
117### Protocol Version Changes
118
119* V2: Added the `visible` key to the response. Invisible items are no longer represented as having value null.
120* V2: `load` now sends changes compared to values before the load, not the whole list of config items.
121
