doc: kconfig: Cover a common gotcha related to "stuck" symbol values
Explain a common subtle Kconfig gotcha where it might appear that symbols with prompts are incorrectly "stuck" to a particular value in the menuconfig interface. I've seen it come up several times now, e.g. in the discussion that lead to https://github.com/zephyrproject-rtos/zephyr/pull/20702. I also suspect it's what's causing https://github.com/zephyrproject-rtos/zephyr/issues/20673. Also give suggestions for how to make things behave as intended. Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
This commit is contained in:
parent
429dde19c6
commit
28487d088f
1 changed files with 91 additions and 0 deletions
|
@ -324,6 +324,97 @@ error-prone, since it can be hard to spot that the same dependency is added
|
|||
twice.
|
||||
|
||||
|
||||
"Stuck" symbols in menuconfig
|
||||
*****************************
|
||||
|
||||
There is a common subtle gotcha related to interdependent configuration symbols
|
||||
with prompts. Consider these symbols:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
config FOO
|
||||
bool "Foo"
|
||||
|
||||
config STACK_SIZE
|
||||
hex "Stack size"
|
||||
default 0x200 if FOO
|
||||
default 0x100
|
||||
|
||||
Assume that the intention here is to use a larger stack whenever ``FOO`` is
|
||||
enabled, and that the configuration initially has ``FOO`` disabled. Also,
|
||||
remember that Zephyr creates an initial configuration in :file:`zephyr/.config`
|
||||
in the build directory by merging configuration files (including e.g.
|
||||
:file:`prj.conf`). This configuration file exists before ``menuconfig`` is run.
|
||||
|
||||
When first entering the ``menuconfig`` interface, the value of ``STACK_SIZE``
|
||||
is 0x100, as expected. After enabling ``FOO``, you might reasonably expect the
|
||||
value of ``STACK_SIZE`` to change to 0x200, but it stays as 0x100.
|
||||
|
||||
To understand what's going on, remember that ``STACK_SIZE`` has a prompt,
|
||||
meaning it is user-configurable, and consider that all Kconfig has to go on
|
||||
from the initial configuration is this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
CONFIG_STACK_SIZE=0x100
|
||||
|
||||
Since Kconfig can't know if the 0x100 value came from a ``default`` or was
|
||||
typed in by the user, it has to assume that it came from the user. Since
|
||||
``STACK_SIZE`` is user-configurable, the value from the configuration file is
|
||||
respected, and any symbol defaults are ignored. This is why the value of
|
||||
``STACK_SIZE`` appears to be "frozen" at 0x100 when toggling ``FOO``.
|
||||
|
||||
The right fix depends on what the intention is. Here's some different scenarios
|
||||
with suggestions:
|
||||
|
||||
- If ``STACK_SIZE`` can always be derived automatically and does not need to be
|
||||
user-configurable, then just remove the prompt:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
config STACK_SIZE
|
||||
hex
|
||||
default 0x200 if FOO
|
||||
default 0x100
|
||||
|
||||
Symbols without prompts ignore any value from the saved configuration.
|
||||
|
||||
- If ``STACK_SIZE`` should usually be user-configurable, but needs to be set to
|
||||
0x200 when ``FOO`` is enabled, then disable its prompt when ``FOO`` is
|
||||
enabled, as described in `optional prompts`_:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
config STACK_SIZE
|
||||
hex "Stack size" if !FOO
|
||||
default 0x200 if FOO
|
||||
default 0x100
|
||||
|
||||
- If ``STACK_SIZE`` should usually be derived automatically, but needs to be
|
||||
set to a custom value in rare circumstances, then add another option for
|
||||
making ``STACK_SIZE`` user-configurable:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
config CUSTOM_STACK_SIZE
|
||||
bool "Use a custom stack size"
|
||||
help
|
||||
Enable this if you need to use a custom stack size. When disabled, a
|
||||
suitable stack size is calculated automatically.
|
||||
|
||||
config STACK_SIZE
|
||||
hex "Stack size" if CUSTOM_STACK_SIZE
|
||||
default 0x200 if FOO
|
||||
default 0x100
|
||||
|
||||
As long as ``CUSTOM_STACK_SIZE`` is disabled, ``STACK_SIZE`` will ignore the
|
||||
value from the saved configuration.
|
||||
|
||||
It is a good idea to try out changes in the ``menuconfig`` interface, to make
|
||||
sure that things behave the way you expect. This is especially true when making
|
||||
moderately complex changes like these.
|
||||
|
||||
|
||||
``depends on`` and ``string``/``int``/``hex`` symbols
|
||||
*****************************************************
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue