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:
Ulf Magnusson 2019-12-10 19:03:22 +01:00 committed by Carles Cufí
commit 28487d088f

View file

@ -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
*****************************************************