From 3e69a0e465a51e1aae0978b4f55a10e3669fa95d Mon Sep 17 00:00:00 2001 From: Ulf Magnusson Date: Thu, 23 May 2019 15:38:01 +0200 Subject: [PATCH] doc: kconfig: Explain the 'menuconfig' keyword and good uses for it Takes a while to figure out what it's there for, so explain what it does and give an example of a good use for it. Signed-off-by: Ulf Magnusson --- doc/guides/kconfig/index.rst | 77 ++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/doc/guides/kconfig/index.rst b/doc/guides/kconfig/index.rst index 3584323c578..cadbd4408c0 100644 --- a/doc/guides/kconfig/index.rst +++ b/doc/guides/kconfig/index.rst @@ -351,6 +351,83 @@ the symbols harder to understand, even if code never looks at ``FOO_DEVICE_FREQUENCY`` when ``FOO_DEVICE`` is disabled. +``menuconfig`` symbols +********************** + +If the definition of a symbol ``FOO`` is immediately followed by other symbols +that depend on ``FOO``, then those symbols become children of ``FOO``. If +``FOO`` is defined with ``config FOO``, then the children are shown indented +relative to ``FOO``. Defining ``FOO`` with ``menuconfig FOO`` instead puts the +children in a separate menu rooted at ``FOO``. + +``menuconfig`` has no effect on evaluation. It's just a display option. + +``menuconfig`` can cut down on the number of menus and make the menu structure +easier to navigate. For example, say you have the following definitions: + +.. code-block:: none + + menu "Foo subsystem" + + config FOO_SUBSYSTEM + bool "Foo subsystem" + + if FOO_SUBSYSTEM + + config FOO_FEATURE_1 + bool "Foo feature 1" + + config FOO_FEATURE_2 + bool "Foo feature 2" + + config FOO_FREQUENCY + int "Foo frequency" + + ... lots of other FOO-related symbols + + endif # FOO_SUBSYSTEM + + endmenu + +In this case, it's probably better to get rid of the ``menu`` and turn +``FOO_SUBSYSTEM`` into a ``menuconfig`` symbol: + +.. code-block:: none + + menuconfig FOO_SUBSYSTEM + bool "Foo subsystem" + + if FOO_SUBSYSTEM + + config FOO_FEATURE_1 + bool "Foo feature 1" + + config FOO_FEATURE_2 + bool "Foo feature 2" + + config FOO_FREQUENCY + int "Foo frequency" + + ... lots of other FOO-related symbols + + endif # FOO_SUBSYSTEM + +In the ``menuconfig`` interface, this will be displayed as follows: + +.. code-block:: none + + [*] Foo subsystem ---> + +Note that making a symbol without children a ``menuconfig`` is meaningless. It +should be avoided, because it looks identical to a symbol with all children +invisible: + +.. code-block:: none + + [*] I have no children ---- + [*] All my children are invisible ---- + + Checking changes in ``menuconfig`` **********************************