michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: kconfig: Explain why zephyr/.config assigns promptless symbols

Browse source 
I think a lot of the confusion with promptless symbols being assigned
might come from opening zephyr/.config, seeing that it assigns a bunch
of promptless symbols, and assuming that Kconfig must respect those
assignments, even though it doesn't.

Explain why zephyr/.config assigns promptless symbols (it's because it
doubles as configuration output). That should clarify things a bit.

Also mention what "invisible" means for symbols early on in the page.

Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
This commit is contained in:
Ulf Magnusson 2020-01-17 17:28:14 +01:00 • committed by Carles Cufí
commit 31822c6d5b
1 changed files with 45 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

48
doc/guides/kconfig/tips.rst
View file

@ -25,9 +25,17 @@ When deciding whether something belongs in Kconfig, it helps to distinguish
between symbols that have prompts and symbols that don't.
If a symbol has a prompt (e.g. ``bool "Enable foo"``), then the user can change
the symbol's value in the ``menuconfig`` or ``guiconfig`` interface (or by
manually editing configuration files). Therefore, only put a prompt on a symbol
if it makes sense for the user to change its value.
the symbol's value in the ``menuconfig`` or ``guiconfig`` interface (see
:ref:`menuconfig`), or by manually editing configuration files. Conversely, a
symbol without a prompt can never be changed directly by the user, not even by
manually editing configuration files.
Only put a prompt on a symbol if it makes sense for the user to change its
value.
Symbols without prompts are called *hidden* or *invisible* symbols, because
they don't show up in ``menuconfig`` and ``guiconfig``. Symbols that have
prompts can also be invisible, when their dependencies are not satisfied.
In Zephyr, Kconfig configuration is done after selecting a machine, so in
general, it does not make sense to put a prompt on a symbol that corresponds to
@ -416,6 +424,40 @@ interface, to make sure that things behave the way you expect. This is
especially true when making moderately complex changes like these.
Assignments to promptless symbols in configuration files
********************************************************
Assignments to hidden (promptless, also called *invisible*) symbols in
configuration files are always ignored. Hidden symbols get their value
indirectly from other symbols, via e.g. ``default`` and ``select``.
A common source of confusion is opening the output configuration file
(:file:`zephyr/.config`), seeing a bunch of assignments to hidden symbols,
and assuming that those assignments must be respected when the configuration is
read back in by Kconfig. In reality, all assignments to hidden symbols in
:file:`zephyr/.config` are ignored by Kconfig, like for other configuration
files.
To understand why :file:`zephyr/.config` still includes assignments to hidden
symbols, it helps to realize that :file:`zephyr/.config` serves two separate
purposes:
1. It holds the saved configuration, and
2. it holds configuration output. :file:`zephyr/.config` is parsed by the CMake
files to let them query configuration settings, for example.
The assignments to hidden symbols in :file:`zephyr/.config` are just
configuration output. Kconfig itself ignores assignments to hidden symbols when
calculating symbol values.
.. note::
A *minimal configuration*, which can be generated from within the
:ref:`menuconfig and guiconfig interfaces <menuconfig>`, could be considered
closer to just a saved configuration, without the full configuration output.
``depends on`` and ``string``/``int``/``hex`` symbols
*****************************************************