Lines Matching +full:check +full:- +full:common +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>`__.
29 :ref:`menuconfig`), or by manually editing configuration files. Conversely, a
31 manually editing configuration files.
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
144 statements are common.
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
260 This makes it possible for other symbols to check for FPU support in a generic
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
305 adding a Kconfig default for the most common value.
312 Common sense applies, but be aware that ``select`` often causes issues in
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
335 A common misunderstanding related to ``if`` is to think that the following code
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
381 There is a common subtle gotcha related to interdependent configuration symbols
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
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
477 A common source of confusion is opening the output configuration file
482 files.
491 files to let them query configuration settings, for example.
513 .. code-block:: kconfig
522 In general, it's a good idea to check that only relevant symbols are ever shown
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
638 Here are some things to check:
640 * Are the symbols placed in a good spot? Check that they appear in a menu where
671 :zephyr_file:`scripts/kconfig/lint.py` script to check for some potential
673 ``--help`` to see available options.
676 check does not necessarily mean there's a problem. If a check returns a false
689 This section gives some style recommendations and explains some common Kconfig
693 Factoring out common dependencies
696 If a sequence of symbols/choices share a common dependency, the dependency can
701 .. code-block:: kconfig
725 .. code-block:: kconfig
755 .. code-block:: kconfig
795 .. code-block:: kconfig
807 .. code-block:: kconfig
819 Common Kconfig shorthands
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
920 .. code-block:: kconfig
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
1031 .. code-block:: kconfig
1048 .. code-block:: kconfig
1066 .. code-block:: cfg