michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: kconfig: Mention guiconfig on tips page

Browse source 
Mention guiconfig as well wherever menuconfig is mentioned.

Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
This commit is contained in:
Ulf Magnusson 2019-12-10 19:18:43 +01:00 • committed by Carles Cufí
commit e9cf3e9963
1 changed files with 27 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -25,9 +25,9 @@ When deciding whether something belongs in Kconfig, it helps to distinguish
between symbols that have prompts and symbols that don't. 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 If a symbol has a prompt (e.g. ``bool "Enable foo"``), then the user can change
the symbol's value in the ``menuconfig`` interface (or by manually editing the symbol's value in the ``menuconfig`` or ``guiconfig`` interface (or by
configuration files). Therefore, only put a prompt on a symbol if it makes manually editing configuration files). Therefore, only put a prompt on a symbol
sense for the user to change its value. if it makes sense for the user to change its value.
In Zephyr, Kconfig configuration is done after selecting a machine, so in 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 general, it does not make sense to put a prompt on a symbol that corresponds to
@ -324,8 +324,8 @@ error-prone, since it can be hard to spot that the same dependency is added
twice. twice.
"Stuck" symbols in menuconfig "Stuck" symbols in menuconfig and guiconfig
***************************** *******************************************
There is a common subtle gotcha related to interdependent configuration symbols There is a common subtle gotcha related to interdependent configuration symbols
with prompts. Consider these symbols: with prompts. Consider these symbols:
@ -344,10 +344,11 @@ Assume that the intention here is to use a larger stack whenever ``FOO`` is
enabled, and that the configuration initially has ``FOO`` disabled. Also, enabled, and that the configuration initially has ``FOO`` disabled. Also,
remember that Zephyr creates an initial configuration in :file:`zephyr/.config` remember that Zephyr creates an initial configuration in :file:`zephyr/.config`
in the build directory by merging configuration files (including e.g. in the build directory by merging configuration files (including e.g.
:file:`prj.conf`). This configuration file exists before ``menuconfig`` is run. :file:`prj.conf`). This configuration file exists before
``menuconfig`` or ``guiconfig`` is run.
When first entering the ``menuconfig`` interface, the value of ``STACK_SIZE`` When first entering the configuration interface, the value of ``STACK_SIZE`` is
is 0x100, as expected. After enabling ``FOO``, you might reasonably expect the 0x100, as expected. After enabling ``FOO``, you might reasonably expect the
value of ``STACK_SIZE`` to change to 0x200, but it stays as 0x100. 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, To understand what's going on, remember that ``STACK_SIZE`` has a prompt,
@ -410,9 +411,9 @@ with suggestions:
As long as ``CUSTOM_STACK_SIZE`` is disabled, ``STACK_SIZE`` will ignore the As long as ``CUSTOM_STACK_SIZE`` is disabled, ``STACK_SIZE`` will ignore the
value from the saved configuration. value from the saved configuration.
It is a good idea to try out changes in the ``menuconfig`` interface, to make It is a good idea to try out changes in the ``menuconfig`` or ``guiconfig``
sure that things behave the way you expect. This is especially true when making interface, to make sure that things behave the way you expect. This is
moderately complex changes like these. especially true when making moderately complex changes like these.
``depends on`` and ``string``/``int``/``hex`` symbols ``depends on`` and ``string``/``int``/``hex`` symbols
@ -434,10 +435,10 @@ disable any configuration output for it when ``FOO_DEVICE`` is disabled.
depends on FOO_DEVICE depends on FOO_DEVICE
In general, it's a good idea to check that only relevant symbols are ever shown In general, it's a good idea to check that only relevant symbols are ever shown
in the ``menuconfig`` interface. Having ``FOO_DEVICE_FREQUENCY`` show up when in the ``menuconfig``/``guiconfig`` interface. Having ``FOO_DEVICE_FREQUENCY``
``FOO_DEVICE`` is disabled (and possibly hidden) makes the relationship between show up when ``FOO_DEVICE`` is disabled (and possibly hidden) makes the
the symbols harder to understand, even if code never looks at relationship between the symbols harder to understand, even if code never looks
``FOO_DEVICE_FREQUENCY`` when ``FOO_DEVICE`` is disabled. at ``FOO_DEVICE_FREQUENCY`` when ``FOO_DEVICE`` is disabled.
``menuconfig`` symbols ``menuconfig`` symbols
@ -517,13 +518,13 @@ invisible:
[*] All my children are invisible ---- [*] All my children are invisible ----
Checking changes in ``menuconfig`` Checking changes in menuconfig/guiconfig
********************************** ****************************************
When adding new symbols or making other changes to Kconfig files, it is a good When adding new symbols or making other changes to Kconfig files, it is a good
idea to look up the symbols in the :ref:`menuconfig <menuconfig>` interface idea to look up the symbols in :ref:`menuconfig or guiconfig <menuconfig>`
afterwards. To get to a symbol quickly, use the menuconfig's jump-to feature afterwards. To get to a symbol quickly, use the jump-to feature (press
(press :kbd:`/`). :kbd:`/`).
Here are some things to check: Here are some things to check:
@ -532,8 +533,9 @@ Here are some things to check:
If one symbol depends on another, then it's often a good idea to place it If one symbol depends on another, then it's often a good idea to place it
right after the symbol it depends on. It will then be shown indented relative right after the symbol it depends on. It will then be shown indented relative
to the symbol it depends on in the ``menuconfig`` interface. This also works to the symbol it depends on in the ``menuconfig`` interface, and in a
if several symbols are placed after the symbol they depend on. separate menu rooted at the symbol in ``guiconfig``. This also works if
several symbols are placed after the symbol they depend on.
* Is it easy to guess what the symbols do from their prompts? * Is it easy to guess what the symbols do from their prompts?
@ -842,9 +844,9 @@ toggled off to select none of the symbols:
endchoice endchoice
In the menuconfig interface, this will be displayed e.g. as ``[*] Use legacy In the ``menuconfig`` interface, this will be displayed e.g. as
protocol (Legacy protocol 1) --->``, where the choice can be toggled off to ``[*] Use legacy protocol (Legacy protocol 1) --->``, where the choice can be
enable neither of the symbols. toggled off to enable neither of the symbols.
``visible if`` conditions ``visible if`` conditions