diff --git a/doc/application/index.rst b/doc/application/index.rst index f940b2eaa76..610a712d08f 100644 --- a/doc/application/index.rst +++ b/doc/application/index.rst @@ -48,13 +48,12 @@ These contents are: debug compiled binaries on real or emulated hardware, and more. * **Kernel configuration files**: An application typically provides a - configuration file (usually called :file:`prj.conf`) that specifies + Kconfig configuration file (usually called :file:`prj.conf`) that specifies application-specific values for one or more kernel configuration options. These application settings are merged with board-specific settings to produce a kernel configuration. - The :ref:`application_kconfig` section below goes over application - configuration in detail. + See :ref:`application-kconfig` below for more information. * **Application source code files**: An application typically provides one or more application-specific files, written in C or assembly language. These @@ -87,6 +86,9 @@ At the top of the tree there are several files that are of importance: The top-level Kconfig file, which refers to the file :file:`Kconfig.zephyr` also found at the top-level directory. + See :ref:`the Kconfig section of the manual ` for detailed Kconfig + documentation. + :file:`west.yml` The :ref:`west` manifest, listing the external repositories managed by the west command-line tool. @@ -221,15 +223,7 @@ Follow these steps to create a new application directory. (Refer to :file:`boilerplate.cmake`. The most recent of the two versions will be enforced by CMake. -#. Set any Kconfig values needed by your application. Zephyr uses the same - Kconfig system as the Linux kernel, but with its own database of - configuration options. - - For example, create a file named :file:`prj.conf` in the :file:`app` - directory, and enable or disable Kconfig features as needed. You can use - existing :ref:`samples-and-demos` to get started with Kconfig variables you - are interested in. See :ref:`application_kconfig` for more details, and - :ref:`configuration_options` for a complete list of available options. +#. Set Kconfig configuration options. See :ref:`application-kconfig`. #. Optionally, you can also configure any devicetree overlays needed by your application. See :ref:`application_dt` below for details. @@ -272,6 +266,8 @@ should know about. semicolons. Each file includes Kconfig configuration values that override the default configuration values. + See :ref:`initial-conf` for more information. + * :makevar:`DTC_OVERLAY_FILE`: Indicates the name of one or more devicetree overlay files. Multiple filenames can be separated with either spaces or semicolons. Each file includes devicetree values that override the default @@ -1087,7 +1083,7 @@ Make sure to follow these steps in order. set(CONF_FILE "fragment_file1.conf") list(APPEND CONF_FILE "fragment_file2.conf") - More details are available below in :ref:`application_kconfig`. + See :ref:`initial-conf` for more information. #. If your application uses a devicetree overlay file or files other than the usual :file:`.overlay`, add lines setting the @@ -1099,6 +1095,9 @@ Make sure to follow these steps in order. create a :file:`Kconfig` file in the same directory as your application's :file:`CMakeLists.txt`. + See :ref:`the Kconfig section of the manual ` for detailed + Kconfig documentation. + An (unlikely) advanced use case would be if your application has its own unique configuration **options** that are set differently depending on the build configuration. @@ -1112,12 +1111,12 @@ Make sure to follow these steps in order. .. note:: - Environment variables in ``source`` statements are expanded directly, - so you do not need to define an ``option env="ZEPHYR_BASE"`` Kconfig - "bounce" symbol. If you use such a symbol, it must have the same name as - the environment variable. + Environment variables in ``source`` statements are expanded directly, so + you do not need to define an ``option env="ZEPHYR_BASE"`` Kconfig + "bounce" symbol. If you use such a symbol, it must have the same name as + the environment variable. - See :ref:`kconfig_extensions` for more information. + See :ref:`kconfig_extensions` for more information. The :file:`Kconfig` file is automatically detected when placed in the application directory, but it is also possible for it to be @@ -1177,138 +1176,33 @@ documentation `runningcmake`_ . .. _runningcmake: http://cmake.org/runningcmake/ -.. _application_configuration: - Application Configuration ************************* -.. _application_kconfig: +.. _application-kconfig: Kconfig Configuration ===================== -Use the ``menuconfig`` and ``guiconfig`` interfaces to test out different -configurations during development. See :ref:`menuconfig` for more information. +Application configuration options are usually set in :file:`prj.conf` in the +application directory. For example, C++ support could be enabled with this +assignment: -The Initial Kconfig Configuration ---------------------------------- +.. code-block:: none -The initial configuration for an application is produced by merging -configuration settings from three sources: + CONFIG_CPLUSPLUS=y -1. A :makevar:`BOARD`-specific configuration file, stored in - :file:`boards/ARCHITECTURE/BOARD/BOARD_defconfig` in the Zephyr base - directory. +Looking at :ref:`existing samples ` is a good way to get +started. -2. Any CMakeCache entries that are prefixed with :makevar:`CONFIG_`. - -3. One or more application-specific configuration files. - -The application-specific configuration file(s) can be specified in any of the -following ways. The simplest option is to just have a single :file:`prj.conf` -file. - -1. If :makevar:`CONF_FILE` is set in :file:`CMakeLists.txt` (**before including - the boilerplate.cmake file**), or is present in the CMake variable cache, - or is specified via the ``-DCONF_FILE=`` when invoking CMake - (either directly or via ``west``) the configuration files specified in it - are merged and used as the application-specific settings. - -2. Otherwise (if (1.) does not apply), if a file :file:`prj_BOARD.conf` exists - in the application directory, where :makevar:`BOARD` is the BOARD value set - earlier, the settings in it are used. - -3. Otherwise (if (2.) does not apply), if a file :file:`boards/BOARD.conf` exists - in the application directory, where :makevar:`BOARD` is the BOARD value set - earlier, the settings in it are merged with :file:`prj.conf` and used. - -4. Otherwise, if a file :file:`prj.conf` exists in the application directory, - the settings in it are used. - -Configuration settings that have not been specified fall back on their -default value, as given in the :file:`Kconfig` files. - -The merged configuration is saved in :file:`zephyr/.config` in the build -directory. - -As long as :file:`zephyr/.config` exists and is up-to-date (is newer than the -:makevar:`BOARD` and application configuration files), it will be used in -preference to producing a new merged configuration. This can be used to test -out configurations during development, as described in :ref:`menuconfig`. - -For more information on Zephyr's Kconfig configuration scheme, see the -:ref:`setting_configuration_values` section in the :ref:`board_porting_guide`. -For some tips and general recommendations when writing Kconfig files, see the -:ref:`kconfig_tips_and_tricks` page. - -For information on available kernel configuration options, including -inter-dependencies between options, see the :ref:`configuration_options`. - -.. note:: - - Dependencies between options can also be viewed in the :ref:`interactive - configuration interfaces `. They will show the most up-to-date - dependencies, and also show which dependencies are currently unsatisfied. - - To view the dependencies of an option in e.g. ``menuconfig``, jump to it - with :kbd:`/` and press :kbd:`?`. For each unsatisfied dependency, jump to - it in turn to check its dependencies. - -.. _application_set_conf: - -Making Kconfig Configuration Settings Permanent ------------------------------------------------ - -This section describes how to edit Zephyr configuration (:file:`.conf`) files -to make configuration settings permanent. - -- Add each configuration entry on a new line. - -- Enable or disable a boolean option by setting its value to ``y`` or ``n``: - - .. code-block:: none - - CONFIG_SOME_BOOL=y - CONFIG_SOME_OTHER_BOOL=n - - .. note:: - - Another way to set a boolean symbol to ``n`` is with a comment with the - following format: - - .. code-block:: none - - # CONFIG_SOME_OTHER_BOOL is not set - - This style is accepted for a technical reason: Kconfig configuration files - can be parsed as makefiles (though Zephyr doesn't use this). Having - ``n``-valued symbols correspond to unset variables simplifies tests in - Make. - -- You can set integer and string options as well, like this: - - .. code-block:: none - - CONFIG_SOME_INT=42 - CONFIG_SOME_STRING="the best value ever" - -- Ensure that each entry setting an option contains no spaces - (including on either side of the = sign). - -- Use a # followed by a space to comment a line: - - .. code-block:: none - - # This is a comment. - -The example below shows a comment line and an override setting -:option:`CONFIG_PRINTK` to ``y``: - -.. code-block:: c - - # Enable printk for debugging - CONFIG_PRINTK=y +See :ref:`setting_configuration_values` for detailed documentation on setting +Kconfig configuration values. The :ref:`initial-conf` section on the same page +explains how the initial configuration is derived. See +:ref:`configuration_options` for a complete list of configuration options. +The other pages in the :ref:`Kconfig section of the manual ` are also +worth going through, especially if you planning to add new configuration +options. .. _application_dt: diff --git a/doc/guides/kconfig/index.rst b/doc/guides/kconfig/index.rst index fc92b61e8ff..d1cac66dff2 100644 --- a/doc/guides/kconfig/index.rst +++ b/doc/guides/kconfig/index.rst @@ -1,3 +1,5 @@ +.. _kconfig: + Kconfig ####### @@ -5,6 +7,7 @@ Kconfig :maxdepth: 1 menuconfig.rst + setting.rst tips.rst preprocessor-functions.rst extensions.rst diff --git a/doc/guides/kconfig/menuconfig.rst b/doc/guides/kconfig/menuconfig.rst index a5b72d7ce07..521a3cd915d 100644 --- a/doc/guides/kconfig/menuconfig.rst +++ b/doc/guides/kconfig/menuconfig.rst @@ -20,7 +20,7 @@ terminal, while ``guiconfig`` is a graphical configuration interface. re-configuring. To make a setting permanent, you should set it in a :file:`*.conf` file, as -described in :ref:`application_set_conf`. +described in :ref:`setting_configuration_values`. .. tip:: diff --git a/doc/guides/kconfig/setting.rst b/doc/guides/kconfig/setting.rst new file mode 100644 index 00000000000..d076be31cf2 --- /dev/null +++ b/doc/guides/kconfig/setting.rst @@ -0,0 +1,326 @@ +.. _setting_configuration_values: + +Setting Kconfig configuration values +#################################### + +The :ref:`menuconfig and guiconfig interfaces ` can be used to test +out configurations during application development. This page explains how to +make settings permanent. + +An auto-generated list of all Kconfig options can be found in the :ref:`Kconfig +symbol reference `. + +.. note:: + + Before making changes to Kconfig files, it's a good idea to also go through + the :ref:`kconfig_tips_and_tricks` page. + + +Visible and invisible Kconfig symbols +************************************* + +When making Kconfig changes, it's important to understand the difference +between *visible* and *invisible* symbols. + +- A visible symbol is a symbol defined with a prompt. Visible symbols show + up in the interactive configuration interfaces (hence *visible*), and can be + set in configuration files. + + Here's an example of a visible symbol: + + .. code-block:: none + + config FLOAT + bool "Support floating point operations" + depends on HAS_FPU + + The symbol is shown like this in ``menuconfig``, where it can be toggled: + + .. code-block:: none + + [ ] Support floating point operations + +- An *invisible* symbol is a symbol without a prompt. Invisible symbols are + not shown in the interactive configuration interfaces, and users have no + direct control over their value. They instead get their value from defaults + or from other symbols. + + Here's an example or an invisible symbol: + + .. code-block:: none + + config CPU_HAS_FPU + bool + help + This symbol is y if the CPU has a hardware floating point unit. + + In this case, ``CPU_HAS_FPU`` is enabled through other symbols having + ``select CPU_HAS_FPU``. + + +Setting symbols in configuration files +************************************** + +Visible symbols can be configured by setting them in configuration files. The +initial configuration is produced by merging a :file:`*_defconfig` file for the +board with application settings, usually from :file:`prj.conf`. See +:ref:`initial-conf` below for more details. + +Assignments in configuration files use this syntax: + +.. code-block:: none + + CONFIG_= + +There should be no spaces around the equals sign. + +``bool`` symbols can be enabled or disabled by setting them to ``y`` or ``n``, +respectively. The ``FLOAT`` symbol from the example above could be enabled like +this: + +.. code-block:: none + + CONFIG_FLOAT=y + +.. note:: + + A boolean symbol can also be set to ``n`` with a comment formatted like + this: + + .. code-block:: none + + # CONFIG_SOME_OTHER_BOOL is not set + + This is the format you will see in the merged configuration in + :file:`zephyr/.config`. + + This style is accepted for historical reasons: Kconfig configuration files + can be parsed as makefiles (though Zephyr doesn't use this). Having + ``n``-valued symbols correspond to unset variables simplifies tests in Make. + +Other symbol types are assigned like this: + +.. code-block:: none + + CONFIG_SOME_STRING="cool value" + CONFIG_SOME_INT=123 + +Comments use a #: + +.. code-block:: none + + # This is a comment + +Assignments in configuration files are only respected if the dependencies for +the symbol are satisfied. A warning is printed otherwise. To figure out what +the dependencies of a symbol are, use one of the :ref:`interactive +configuration interfaces ` (you can jump directly to a symbol with +:kbd:`/`), or look up the symbol in the :ref:`Kconfig symbol reference +`. + + +.. _initial-conf: + +The Initial Configuration +************************* + +The initial configuration for an application comes from merging configuration +settings from three sources: + +1. A ``BOARD``-specific configuration file stored in + :file:`boards///_defconfig` + +2. Any CMake cache entries prefix with ``CONFIG_`` + +3. The application configuration + +The application configuration can come from the sources below. By default, +:file:`prj.conf` is used. + +1. If ``CONF_FILE`` is set, the configuration file(s) specified in it are + merged and used as the application configuration. ``CONF_FILE`` can be set + in various ways: + + 1. In :file:`CMakeLists.txt`, before including :file:`boilerplate.cmake` + + 2. By passing ``-DCONF_FILE=``, either directly or via ``west`` + + 3. From the CMake variable cache + +2. Otherwise, :file:`prj_.conf` is used if it exists in the application + directory. + +3. Otherwise, if :file:`boards/.conf` exists in the application + directory, the result of merging it with :file:`prj.conf` is used. + +4. Otherwise, :file:`prj.conf` is used if it exists in the application + directory + +If a symbol is assigned both in :file:`_defconfig` and in the +application configuration, the value set in the application configuration takes +precedence. + +The merged configuration is saved to :file:`zephyr/.config` in the build +directory. + +As long as :file:`zephyr/.config` exists and is up-to-date (is newer than any +``BOARD`` and application configuration files), it will be used in preference +to producing a new merged configuration. :file:`zephyr/.config` is also the +configuration that gets modified when making changes in the :ref:`interactive +configuration interfaces `. + + +Configuring invisible Kconfig symbols +************************************* + +When making changes to the default configuration for a board, you might have to +configure invisible symbols. This is done in +:file:`boards///Kconfig.defconfig`, which is a regular +:file:`Kconfig` file. + +.. note:: + + Assignments in :file:`.config` files have no effect on invisible symbols, + so this scheme is not just an organizational issue. + +Assigning values in :file:`Kconfig.defconfig` relies on defining a Kconfig +symbol in multiple locations. As an example, say we want to set ``FOO_WIDTH`` +below to 32: + +.. code-block:: none + + config FOO_WIDTH + int + +To do this, we extend the definition of ``FOO_WIDTH`` as follows, in +:file:`Kconfig.defconfig`: + +.. code-block:: none + + if BOARD_MY_BOARD + + config FOO_WIDTH + default 32 + + endif + +.. note:: + + Since the type of the symbol (``int``) has already been given at the first + definition location, it does not need to be repeated here. Only giving the + type once at the "base" definition of the symbol is a good idea for reasons + explained in :ref:`kconfig_shorthands`. + +``default`` values in :file:`Kconfig.defconfig` files have priority over +``default`` values given on the "base" definition of a symbol. Internally, this +is implemented by including the :file:`Kconfig.defconfig` files first. Kconfig +uses the first ``default`` with a satisfied condition, where an empty condition +corresponds to ``if y`` (is always satisfied). + +Note that conditions from surrounding top-level ``if``\ s are propagated to +symbol properties, so the above ``default`` is equivalent to +``default 32 if BOARD_MY_BOARD``. + +.. warning:: + + When defining a symbol in multiple locations, dependencies are ORed together + rather than ANDed together. It is not possible to make the dependencies of a + symbol more restrictive by defining it in multiple locations. + + For example, the direct dependencies of the symbol below becomes + ``DEP1 || DEP2``: + + .. code-block:: none + + config FOO + ... + depends on DEP1 + + config FOO + ... + depends on DEP2 + + When making changes to :file:`Kconfig.defconfig` files, always check the + symbol's direct dependencies in one of the :ref:`interactive configuration + interfaces ` afterwards. It is often necessary to repeat + dependencies from the base definition of the symbol to avoid weakening a + symbol's dependencies. + + +Motivation for Kconfig.defconfig files +-------------------------------------- + +One motivation for this configuration scheme is to avoid making fixed +``BOARD``-specific settings configurable in the interactive configuration +interfaces. If all board configuration were done via :file:`_defconfig`, +all symbols would have to be visible, as values given in +:file:`_defconfig` have no effect on invisible symbols. + +Having fixed settings be user-configurable would clutter up the configuration +interfaces and make them harder to understand, and would make it easier to +accidentally create broken configurations. + +When dealing with fixed board-specific settings, also consider whether they +could be handled via :ref:`devicetree ` instead. + + +Configuring choices +------------------- + +There are two ways to configure a Kconfig ``choice``: + +1. By setting one of the choice symbols to ``y`` in a configuration file. + + Setting one choice symbol to ``y`` automatically gives all other choice + symbols the value ``n``. + + If multiple choice symbols are set to ``y``, only the last one set to ``y`` + will be honored (the rest will get the value ``n``). This allows a choice + selection from a board :file:`defconfig` file to be overridden from an + application :file:`prj.conf` file. + +2. By changing the ``default`` of the choice in :file:`Kconfig.defconfig`. + + As with symbols, changing the default for a choice is done by defining the + choice in multiple locations. For this to work, the choice must have a name. + + As an example, assume that a choice has the following base definition (here, + the name of the choice is ``FOO``): + + .. code-block:: none + + choice FOO + bool "Foo choice" + default B + + config A + bool "A" + + config B + bool "B" + + endchoice + + To change the default symbol of ``FOO`` to ``A``, you would add the + following definition to :file:`Kconfig.defconfig`: + + .. code-block:: none + + choice FOO + default A + endchoice + +The :file:`Kconfig.defconfig` method should be used when the dependencies of +the choice might not be satisfied. In that case, you're setting the default +selection whenever the user makes the choice visible. + + +More Kconfig resources +====================== + +The :ref:`kconfig_tips_and_tricks` page has some tips for writing Kconfig +files. + +The :zephyr_file:`kconfiglib.py ` docstring +docstring (at the top of the file) goes over how symbol values are calculated +in detail. diff --git a/doc/guides/kconfig/tips.rst b/doc/guides/kconfig/tips.rst index dcbd28605a7..7766b08e94b 100644 --- a/doc/guides/kconfig/tips.rst +++ b/doc/guides/kconfig/tips.rst @@ -589,8 +589,10 @@ with the C Kconfig tools, though an implicit 0 default might be less likely to be what was intended compared to other symbol types as well. -Common shorthands -================= +.. _kconfig_shorthands: + +Common Kconfig shorthands +========================= Kconfig has two shorthands that deal with prompts and defaults. diff --git a/doc/guides/porting/arch.rst b/doc/guides/porting/arch.rst index 2e149ce62fa..59ab12efbe0 100644 --- a/doc/guides/porting/arch.rst +++ b/doc/guides/porting/arch.rst @@ -13,11 +13,9 @@ The following are examples of ISAs and ABIs that Zephyr supports: * ARMv7-M ISA with Thumb2 instruction set and ARM Embedded ABI (aeabi) * ARCv2 ISA -For information on Kconfig configuration, see the -:ref:`setting_configuration_values` section in the :ref:`board_porting_guide`. -Architectures use a similar Kconfig configuration scheme. The -:ref:`kconfig_tips_and_tricks` page has some general recommendations and tips -for writing Kconfig files as well. +For information on Kconfig configuration, see +:ref:`setting_configuration_values`. Architectures use a Kconfig configuration +scheme similar to boards. An architecture port can be divided in several parts; most are required and some are optional: diff --git a/doc/guides/porting/board_porting.rst b/doc/guides/porting/board_porting.rst index 454bcf4535d..7a83fd306c7 100644 --- a/doc/guides/porting/board_porting.rst +++ b/doc/guides/porting/board_porting.rst @@ -125,7 +125,7 @@ A board port on Zephyr typically consists of two parts: - A hardware description (usually done by device tree), which specifies embedded SoC reference, connectors and any other hardware components such as LEDs, - buttons, sensors or communication peripherals (USB, BLE controller, ..). + buttons, sensors or communication peripherals (USB, BLE controller, ...). - A software configuration (done using Kconfig) of features and peripheral drivers. This default board configuration is subordinated to features @@ -143,10 +143,11 @@ When porting Zephyr to a board, you must provide the board's default Kconfig configuration, which is used in application builds unless explicitly overridden. -.. note:: - - See the :ref:`kconfig_tips_and_tricks` page for some best practices and tips - when writing Kconfig files. +Setting Kconfig configuration values is documented in detail in +:ref:`setting_configuration_values`, which you should go through. Note that the +default board configuration might involve both :file:`_defconfig` and +:file:`Kconfig.defconfig` files. The rest of this section contains some +board-specific guidelines. In order to provide consistency across the various boards and ease the work of users providing applications that are not board specific, the following @@ -172,192 +173,3 @@ peripherals should be disabled by default. - Enable all GPIO ports. - If available, enable pinmux and interrupt controller drivers. - -.. _setting_configuration_values: - -Setting configuration values -============================ - -Kconfig symbols can be set to their ``BOARD``-specific values in one of two -ways. The right method to use depends on whether the symbol is *visible* or -not. - - -Visible and invisible Kconfig symbols -------------------------------------- - -Kconfig symbols come in two varieties: - -- A Kconfig symbol defined with a prompt is *visible*, and can be configured from - the ``menuconfig`` configuration interface. - -- A Kconfig symbol defined without a prompt is *invisible*. The user has no - direct control over its value. - -Here are some examples of visible and invisible symbols: - -.. code-block:: none - - config NOT_VISIBLE - bool - default FOO - - config VISIBLE_1 - string - prompt "Foo value" - - config VISIBLE_2 - # Shorthand for giving a type and a prompt at the same time. This is - # the preferred style in Zephyr. - bool "Enable stuff" - - -Configuring visible Kconfig symbols ------------------------------------ - -Default ``BOARD``-specific configuration values for visible Kconfig symbols -*should* be given in :file:`boards/ARCHITECTURE/BOARD/BOARD_defconfig`, which -uses the standard Kconfig :file:`.config` file syntax. - - -Configuring invisible Kconfig symbols -------------------------------------- - -``BOARD``-specific configuration values for invisible Kconfig symbols *must* be -given in :file:`boards/ARCHITECTURE/BOARD/Kconfig.defconfig`, which uses -Kconfig syntax. - -.. note:: - - Assignments in :file:`.config` files have no effect on invisible symbols, - so this scheme is not just an organizational issue. - -Assigning values in :file:`Kconfig.defconfig` relies on being able to define a -Kconfig symbol in multiple locations. As an example, say we want to set -``FOO_WIDTH`` below to 32: - -.. code-block:: none - - config FOO_WIDTH - int - -To do this, we extend the definition of ``FOO_WIDTH`` as follows, in -:file:`Kconfig.defconfig`: - -.. code-block:: none - - if BOARD_MY_BOARD - - config FOO_WIDTH - default 32 - - endif - -.. note:: - - Since the type of the symbol (``int``) has already been given at the first - definition location, it does not need to be repeated here. - -``default`` values in :file:`Kconfig.defconfig` files have priority over -``default`` values given on the "base" definition of a symbol. Internally, this -is implemented by including the :file:`Kconfig.defconfig` files first. Kconfig -uses the first ``default`` with a satisfied condition, where an empty condition -works like ``if y`` (is always satisfied). - -.. note:: - - ``range`` properties on ``int`` and ``hex`` symbols work the same way, and - can also be added or overridden in :file:`Kconfig.defconfig` files. - -If you want a symbol to only be user-configurable on some boards, make its base -definition have no prompt, and then add a prompt to it in the -:file:`Kconfig.defconfig` files of the boards where it should be configurable. - -.. note:: - - Prompts added in :file:`Kconfig.defconfig` files show up at the location of - the :file:`Kconfig.defconfig` file in the ``menuconfig`` interface, rather - than at the location of the base definition of the symbol. - - -Configuring choices -------------------- - -There are two ways to configure a Kconfig ``choice``: - -1. By setting one of the choice symbols to ``y`` in :file:`BOARD_defconfig`. - - .. note:: - - Setting one choice symbol to ``y`` automatically gives all other choice - symbols the value ``n``. - - If multiple choice symbols are set to ``y``, only the last one set to - ``y`` will be honored (and the rest will get the value ``n``). This - allows a choice selection from a board :file:`defconfig` file to be - overridden from an application :file:`prj.conf` file. - -2. By changing the ``default`` of the choice in :file:`Kconfig.defconfig`. - - As with symbols, changing the default for a choice is done by defining the - choice in multiple locations. For this to work, the choice must have a name. - - As an example, assume that a choice has the following base definition (here, - the name of the choice is ``FOO``): - - .. code-block:: none - - choice FOO - bool "Foo choice" - default B - - config A - bool "A" - - config B - bool "B" - - endchoice - - To change the default symbol of ``FOO`` to ``A``, you would add the - following definition to :file:`Kconfig.defconfig`: - - .. code-block:: none - - choice FOO - default A - endchoice - -The :file:`Kconfig.defconfig` method should be used when the dependencies of -the choice might not be satisfied. In that case, you're setting the default -selection whenever the user makes the choice visible. - - -Motivation ----------- - -One motivation for this configuration scheme is to avoid making fixed -``BOARD``-specific settings configurable in the ``menuconfig`` interface. If -all configuration were done via :file:`BOARD_defconfig`, all symbols would have -to be visible, as values given in :file:`BOARD_defconfig` have no effect on -invisible symbols. - -Having fixed settings be user-configurable might be confusing, and would allow -the user to create broken configurations. - - -More Kconfig resources -====================== - -The official documentation for Kconfig is `kconfig-language.txt -`_ -and `kconfig-macro-language.txt -`_. - -The :ref:`kconfig_tips_and_tricks` page has some best practices and -tips for writing Kconfig files. - -The `kconfiglib.py -`_ -docstring (at the top of the file) goes over how symbol values are calculated -in detail.