From 31822c6d5b7fcf33cee555b9774e5d1b5d5a9656 Mon Sep 17 00:00:00 2001 From: Ulf Magnusson Date: Fri, 17 Jan 2020 17:28:14 +0100 Subject: [PATCH] doc: kconfig: Explain why zephyr/.config assigns promptless symbols 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 --- doc/guides/kconfig/tips.rst | 48 ++++++++++++++++++++++++++++++++++--- 1 file changed, 45 insertions(+), 3 deletions(-) diff --git a/doc/guides/kconfig/tips.rst b/doc/guides/kconfig/tips.rst index 00b9815c075..3dd91971618 100644 --- a/doc/guides/kconfig/tips.rst +++ b/doc/guides/kconfig/tips.rst @@ -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 `, could be considered + closer to just a saved configuration, without the full configuration output. + + ``depends on`` and ``string``/``int``/``hex`` symbols *****************************************************