confserver docs: Merge the build-system docs info about confserver into the README
Add link into the README from the docs
This commit is contained in:
Angus Gratton
Angus Gratton
parent
89fb104747
commit
d9d7a906b1
|
|
@ -1381,47 +1381,7 @@ A tool called ``confserver.py`` is provided to allow IDEs to easily integrate wi
|
|||
|
||||
You can run ``confserver.py`` from a project via ``idf.py confserver`` or ``ninja confserver``, or a similar target triggered from a different build generator.
|
||||
|
||||
The config server outputs human-readable errors and warnings on stderr and JSON on stdout. On startup, it will output the full values of each configuration item in the system as a JSON dictionary, and the available ranges for values which are range constrained. The same information is contained in ``sdkconfig.json``::
|
||||
|
||||
{"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } }
|
||||
|
||||
Only visible configuration items are sent. Invisible/disabled items can be parsed from the static ``kconfig_menus.json`` file which also contains the menu structure and other metadata (descriptions, types, ranges, etc.)
|
||||
|
||||
The Configuration Server will then wait for input from the client. The client passes a request to change one or more values, as a JSON object followed by a newline::
|
||||
|
||||
{"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } }
|
||||
|
||||
The Configuration Server will parse this request, update the project ``sdkconfig`` file, and return a full list of changes::
|
||||
|
||||
{"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}}
|
||||
|
||||
Items which are now invisible/disabled will return value ``null``. Any item which is newly visible will return its newly visible current value.
|
||||
|
||||
If the range of a config item changes, due to conditional range depending on another value, then this is also sent::
|
||||
|
||||
{"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } }
|
||||
|
||||
If invalid data is passed, an "error" field is present on the object::
|
||||
|
||||
{"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]}
|
||||
|
||||
By default, no config changes are written to the sdkconfig file. Changes are held in memory until a "save" command is sent::
|
||||
|
||||
{"version": 1, "save": null }
|
||||
|
||||
To reload the config values from a saved file, discarding any changes in memory, a "load" command can be sent::
|
||||
|
||||
{"version": 1, "load": null }
|
||||
|
||||
The value for both "load" and "save" can be a new pathname, or "null" to load/save the previous pathname.
|
||||
|
||||
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.
|
||||
|
||||
Any combination of "load", "set", and "save" can be sent in a single command and commands are executed in that order. Therefore it's possible to load config from a file, set some config item values and then save to a file in a single command.
|
||||
|
||||
.. note:: 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.
|
||||
|
||||
.. note:: 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.
|
||||
For more information about ``confserver.py``, see :idf_file:`tools/kconfig_new/README.md`.
|
||||
|
||||
Build System Internals
|
||||
=======================
|
||||
|
|
|
|||
|
|
@ -954,47 +954,7 @@ JSON 配置服务器
|
|||
|
||||
您可以通过 ``idf.py confserver`` 或 ``ninja confserver`` 从项目中运行 ``confserver.py``，也可以使用不同的构建生成器来触发类似的目标。
|
||||
|
||||
配置服务器会向 stderr 输出方便阅读的错误和警告信息，向 stdout 输出 JSON 文件。启动时，配置服务器将以 JSON 字典的形式输出系统中每个配置项的完整值，以及范围受限的值的可用范围。``sdkconfig.json`` 中包含有相同的信息::
|
||||
|
||||
{"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } }
|
||||
|
||||
配置服务器仅发送可见的配置项，其它不可见的或者被禁用的配置项可从 ``kconfig_menus.json`` 静态文件中解析得到，此文件还包含菜单结构和其它元数据（描述、类型、范围等）。
|
||||
|
||||
然后配置服务器将等待客户端的输入，客户端会发起请求，要求更改一个或多个配置项的值，内容的格式是个 JSON 对象，后面跟一个换行符::
|
||||
|
||||
{"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } }
|
||||
|
||||
配置服务器将解析此请求，更新 ``sdkconfig`` 文件，并返回完整的变更列表::
|
||||
|
||||
{"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}}
|
||||
|
||||
当前不可见或者禁用的配置项会返回 ``null``，任何新的可见配置项则会返回其当前新的可见值。
|
||||
|
||||
如果配置项的取值范围因另一个值的变化发生了改变，那么配置服务器会发送::
|
||||
|
||||
{"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } }
|
||||
|
||||
如果传递的数据无效，那么 JSON 对象中会有 ``error`` 字段::
|
||||
|
||||
{"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]}
|
||||
|
||||
默认情况下，变更后的配置不会被写进 sdkconfig 文件。更改的内容在发出 “save” 命令之前会先储存在内存中::
|
||||
|
||||
{"version": 1, "save": null }
|
||||
|
||||
若要从已保存的文件中重新加载配置值，并丢弃内存中的任何更改，可以发送 “load” 命令::
|
||||
|
||||
{"version": 1, "load": null }
|
||||
|
||||
“load” 和 “save” 的值可以是新的路径名，也可以设置为 "null" 用以加载/保存之前使用的路径名。
|
||||
|
||||
配置服务器对 “load” 命令的响应始终是完整的配置值和取值范围的集合，这与服务器初始启动阶段的响应相同。
|
||||
|
||||
“load”、“set” 和 “save” 的任意组合可以在一条单独的命令中发送出去，服务器按照组合中的顺序执行命令。因此，可以使用一条命令实现从文件中加载配置，更新配置值，然后将其保存到文件中。
|
||||
|
||||
.. Note:: 配置服务器不会自动加载外部对 ``sdkconfig`` 文件的任何更改。如果文件被外部编辑，则需要发送 “load” 命令或重启服务器。
|
||||
|
||||
.. Note:: ``sdkconfig`` 文件更新后，配置服务器不会重新运行 CMake 来生成其它的构建文件和元数据文件。这些文件会在下一次运行 ``CMake`` 或 ``idf.py`` 时自动生成。
|
||||
有关 confserver.py 的更多信息，请参阅 :idf_file:`tools/kconfig_new/README.md`
|
||||
|
||||
.. _gnu-make-to:
|
||||
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ The `set` key is optional. If present, its value must be a dictionary of new val
|
|||
|
||||
Additional optional keys:
|
||||
|
||||
* `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.
|
||||
* `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.
|
||||
|
||||
* `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.
|
||||
|
||||
|
|
@ -82,6 +82,19 @@ After a request is processed, a response is printed to stdout similar to this:
|
|||
* `visible` contains any visibility changes, where the visible config symbols have changed.
|
||||
* `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.
|
||||
|
||||
If 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:
|
||||
|
||||
```
|
||||
{ "version": 2,
|
||||
"values": {"OTHER_NAME": true },
|
||||
"visible": { },
|
||||
"ranges" : { "HAS_RANGE" : [ 3, 4 ] } }
|
||||
```
|
||||
|
||||
Note: 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.
|
||||
|
||||
Note: 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.
|
||||
|
||||
### KConfig Item Types
|
||||
|
||||
* `string` types are represented as JSON strings.
|
||||
|
|
|
|||
Loading…
Reference in a new issue