Lines Matching +full:user +full:- +full:files
3 Kconfig - Tips and Best Practices
11 The official Kconfig documentation is `kconfig-language.rst
12 <https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html>`__
13 and `kconfig-macro-language.rst
14 <https://www.kernel.org/doc/html/latest/kbuild/kconfig-macro-language.html>`__.
27 If a symbol has a prompt (e.g. ``bool "Enable foo"``), then the user can change
29 :ref:`menuconfig`), or by manually editing configuration files. Conversely, a
30 symbol without a prompt can never be changed directly by the user, not even by
31 manually editing configuration files.
33 Only put a prompt on a symbol if it makes sense for the user to change its
40 Symbols without prompts can't be configured directly by the user (they derive
54 a fixed machine-specific setting. Usually, such settings should be handled via
55 :ref:`devicetree <dt-guide>` instead.
64 controlled by. See :ref:`dt-drivers-that-depend` for alternatives.
66 Similarly, if your application depends on a hardware-specific PWM device to
68 :ref:`dt-apps-that-depend` for alternatives.
76 type phandle-array in the device binding, and using the
77 :ref:`devicetree-gpio-api` devicetree API from C. Similar advice applies to
78 other cases where devicetree.h provides :ref:`devicetree-hw-api` for referring
82 An application-specific devicetree :ref:`binding <dt-bindings>` to identify
86 For applications, see :zephyr:code-sample:`blinky` for a devicetree-based alternative.
95 .. code-block:: kconfig
119 .. code-block:: kconfig
131 .. code-block:: kconfig
149 .. code-block:: kconfig
173 Liberal use of ``select`` also tends to make Kconfig files harder to read, both
174 due to the extra dependencies and due to the non-local nature of ``select``,
184 .. code-block:: kconfig
198 An objection to using ``depends on`` here might be that configuration files
201 .. code-block:: cfg
206 This comes down to a trade-off, but if enabling ``CONSOLE`` is the norm, then a
209 .. code-block:: kconfig
215 This gives just a single assignment in configuration files:
217 .. code-block:: cfg
221 Note that configuration files that do not want ``CONSOLE`` enabled now have to
224 .. code-block:: cfg
241 .. code-block:: kconfig
263 .. code-block:: kconfig
272 .. code-block:: kconfig
280 machine has some arbitrarily-defined "large" amount of memory:
282 .. code-block:: kconfig
291 .. code-block:: kconfig
303 - Avoid selecting symbols with prompts or dependencies. Prefer ``depends on``.
304 If ``depends on`` causes annoying bloat in configuration files, consider
315 - Select simple helper symbols without prompts and dependencies however much
316 you like. They're a great tool for simplifying Kconfig files.
318 - An exemption are buses like I2C and SPI, and following the same thought
323 .. code-block:: kconfig
338 .. code-block:: kconfig
355 .. code-block:: kconfig
362 .. code-block:: kconfig
373 structure of the Kconfig files harder to understand, and also make changes more
374 error-prone, since it can be hard to spot that the same dependency is added
384 .. code-block:: kconfig
397 in the build directory by merging configuration files (including e.g.
406 meaning it is user-configurable, and consider that all Kconfig has to go on
409 .. code-block:: cfg
414 typed in by the user, it has to assume that it came from the user. Since
415 ``STACK_SIZE`` is user-configurable, the value from the configuration file is
422 - If ``STACK_SIZE`` can always be derived automatically and does not need to be
423 user-configurable, then just remove the prompt:
425 .. code-block:: kconfig
434 - If ``STACK_SIZE`` should usually be user-configurable, but needs to be set to
438 .. code-block:: kconfig
445 - If ``STACK_SIZE`` should usually be derived automatically, but needs to be
447 making ``STACK_SIZE`` user-configurable:
449 .. code-block:: kconfig
470 Assignments to promptless symbols in configuration files
474 configuration files are always ignored. Hidden symbols get their value
482 files.
491 files to let them query configuration settings, for example.
513 .. code-block:: kconfig
543 .. code-block:: kconfig
561 ... lots of other FOO-related symbols
570 .. code-block:: kconfig
586 ... lots of other FOO-related symbols
592 .. code-block:: none
594 [*] Foo subsystem --->
600 .. code-block:: none
602 [*] I have no children ----
603 [*] All my children are invisible ----
612 .. code-block:: kconfig
621 .. code-block:: kconfig
633 When adding new symbols or making other changes to Kconfig files, it is a good
635 afterwards. To get to a symbol quickly, use the jump-to feature (press
673 ``--help`` to see available options.
701 .. code-block:: kconfig
725 .. code-block:: kconfig
755 .. code-block:: kconfig
795 .. code-block:: kconfig
807 .. code-block:: kconfig
824 - ``<type> "prompt"`` is a shorthand for giving a symbol/choice a type and a
827 .. code-block:: kconfig
832 .. code-block:: kconfig
840 - ``def_<type> <value>`` is a shorthand for giving a type and a value at the
843 .. code-block:: kconfig
848 .. code-block:: kconfig
885 - Use this format for any header comments at the top of ``Kconfig`` files:
887 .. code-block:: none
892 # SPDX-License-Identifier: <License>
896 - Format comments as ``# Comment`` rather than ``#Comment``
898 - Put a blank line before/after each top-level ``if`` and ``endif``
900 - Use a single tab for each indentation
902 - Indent help text with two extra spaces
905 Lesser-known/used Kconfig features
917 USB keyboard support by default on the FOO SoC, while still allowing the user
920 .. code-block:: kconfig
938 by the user. For example, a value ``MASK`` that's hardcoded to 0xFF on some
941 .. code-block:: kconfig
951 .. code-block:: kconfig
969 .. code-block:: kconfig
984 ``[*] Use legacy protocol (Legacy protocol 1) --->``, where the choice can be
996 .. code-block:: kconfig
1015 .. code-block:: kconfig
1028 ``HAS_CONFIGURABLE_FOO`` is ``n``, but not be configurable by the user, then we
1031 .. code-block:: kconfig
1048 .. code-block:: kconfig
1066 .. code-block:: cfg