1.. _setting_configuration_values: 2 3Setting Kconfig configuration values 4#################################### 5 6The :ref:`menuconfig and guiconfig interfaces <menuconfig>` can be used to test 7out configurations during application development. This page explains how to 8make settings permanent. 9 10An auto-generated list of all Kconfig options can be found in the :ref:`Kconfig 11symbol reference <configuration_options>`. 12 13.. note:: 14 15 Before making changes to Kconfig files, it's a good idea to also go through 16 the :ref:`kconfig_tips_and_tricks` page. 17 18 19Visible and invisible Kconfig symbols 20************************************* 21 22When making Kconfig changes, it's important to understand the difference 23between *visible* and *invisible* symbols. 24 25- A visible symbol is a symbol defined with a prompt. Visible symbols show 26 up in the interactive configuration interfaces (hence *visible*), and can be 27 set in configuration files. 28 29 Here's an example of a visible symbol: 30 31 .. code-block:: none 32 33 config FPU 34 bool "Support floating point operations" 35 depends on HAS_FPU 36 37 The symbol is shown like this in ``menuconfig``, where it can be toggled: 38 39 .. code-block:: none 40 41 [ ] Support floating point operations 42 43- An *invisible* symbol is a symbol without a prompt. Invisible symbols are 44 not shown in the interactive configuration interfaces, and users have no 45 direct control over their value. They instead get their value from defaults 46 or from other symbols. 47 48 Here's an example or an invisible symbol: 49 50 .. code-block:: none 51 52 config CPU_HAS_FPU 53 bool 54 help 55 This symbol is y if the CPU has a hardware floating point unit. 56 57 In this case, ``CPU_HAS_FPU`` is enabled through other symbols having 58 ``select CPU_HAS_FPU``. 59 60 61Setting symbols in configuration files 62************************************** 63 64Visible symbols can be configured by setting them in configuration files. The 65initial configuration is produced by merging a :file:`*_defconfig` file for the 66board with application settings, usually from :file:`prj.conf`. See 67:ref:`initial-conf` below for more details. 68 69Assignments in configuration files use this syntax: 70 71.. code-block:: none 72 73 CONFIG_<symbol name>=<value> 74 75There should be no spaces around the equals sign. 76 77``bool`` symbols can be enabled or disabled by setting them to ``y`` or ``n``, 78respectively. The ``FPU`` symbol from the example above could be enabled like 79this: 80 81.. code-block:: none 82 83 CONFIG_FPU=y 84 85.. note:: 86 87 A boolean symbol can also be set to ``n`` with a comment formatted like 88 this: 89 90 .. code-block:: none 91 92 # CONFIG_SOME_OTHER_BOOL is not set 93 94 This is the format you will see in the merged configuration in 95 :file:`zephyr/.config`. 96 97 This style is accepted for historical reasons: Kconfig configuration files 98 can be parsed as makefiles (though Zephyr doesn't use this). Having 99 ``n``-valued symbols correspond to unset variables simplifies tests in Make. 100 101Other symbol types are assigned like this: 102 103.. code-block:: none 104 105 CONFIG_SOME_STRING="cool value" 106 CONFIG_SOME_INT=123 107 108Comments use a #: 109 110.. code-block:: none 111 112 # This is a comment 113 114Assignments in configuration files are only respected if the dependencies for 115the symbol are satisfied. A warning is printed otherwise. To figure out what 116the dependencies of a symbol are, use one of the :ref:`interactive 117configuration interfaces <menuconfig>` (you can jump directly to a symbol with 118:kbd:`/`), or look up the symbol in the :ref:`Kconfig symbol reference 119<configuration_options>`. 120 121 122.. _initial-conf: 123 124The Initial Configuration 125************************* 126 127The initial configuration for an application comes from merging configuration 128settings from three sources: 129 1301. A ``BOARD``-specific configuration file stored in 131 :file:`boards/<architecture>/<BOARD>/<BOARD>_defconfig` 132 1332. Any CMake cache entries prefix with ``CONFIG_`` 134 1353. The application configuration 136 137The application configuration can come from the sources below. By default, 138:file:`prj.conf` is used. 139 1401. If ``CONF_FILE`` is set, the configuration file(s) specified in it are 141 merged and used as the application configuration. ``CONF_FILE`` can be set 142 in various ways: 143 144 1. In :file:`CMakeLists.txt`, before calling ``find_package(Zephyr)`` 145 146 2. By passing ``-DCONF_FILE=<conf file(s)>``, either directly or via ``west`` 147 148 3. From the CMake variable cache 149 1502. Otherwise if ``CONF_FILE`` is set, and a single configuration file of the 151 form :file:`prj_<build>.conf` is used, then if file 152 :file:`boards/<BOARD>_<build>.conf` exists in same folder as file 153 :file:`prj_<build>.conf`, the result of merging :file:`prj_<build>.conf` and 154 :file:`boards/<BOARD>_<build>.conf` is used. 155 1563. Otherwise, :file:`prj_<BOARD>.conf` is used if it exists in the application 157 directory. 158 1594. Otherwise, if :file:`boards/<BOARD>.conf` exists in the application 160 directory, the result of merging it with :file:`prj.conf` is used. 161 1625. Otherwise, if board revisions are used and 163 :file:`boards/<BOARD>_<revision>.conf` exists in the application 164 directory, the result of merging it with :file:`prj.conf` and 165 :file:`boards/<BOARD>.conf` is used. 166 1676. Otherwise, :file:`prj.conf` is used if it exists in the application 168 directory 169 170If a symbol is assigned both in :file:`<BOARD>_defconfig` and in the 171application configuration, the value set in the application configuration takes 172precedence. 173 174The merged configuration is saved to :file:`zephyr/.config` in the build 175directory. 176 177As long as :file:`zephyr/.config` exists and is up-to-date (is newer than any 178``BOARD`` and application configuration files), it will be used in preference 179to producing a new merged configuration. :file:`zephyr/.config` is also the 180configuration that gets modified when making changes in the :ref:`interactive 181configuration interfaces <menuconfig>`. 182 183 184Configuring invisible Kconfig symbols 185************************************* 186 187When making changes to the default configuration for a board, you might have to 188configure invisible symbols. This is done in 189:file:`boards/<architecture>/<BOARD>/Kconfig.defconfig`, which is a regular 190:file:`Kconfig` file. 191 192.. note:: 193 194 Assignments in :file:`.config` files have no effect on invisible symbols, 195 so this scheme is not just an organizational issue. 196 197Assigning values in :file:`Kconfig.defconfig` relies on defining a Kconfig 198symbol in multiple locations. As an example, say we want to set ``FOO_WIDTH`` 199below to 32: 200 201.. code-block:: none 202 203 config FOO_WIDTH 204 int 205 206To do this, we extend the definition of ``FOO_WIDTH`` as follows, in 207:file:`Kconfig.defconfig`: 208 209.. code-block:: none 210 211 if BOARD_MY_BOARD 212 213 config FOO_WIDTH 214 default 32 215 216 endif 217 218.. note:: 219 220 Since the type of the symbol (``int``) has already been given at the first 221 definition location, it does not need to be repeated here. Only giving the 222 type once at the "base" definition of the symbol is a good idea for reasons 223 explained in :ref:`kconfig_shorthands`. 224 225``default`` values in :file:`Kconfig.defconfig` files have priority over 226``default`` values given on the "base" definition of a symbol. Internally, this 227is implemented by including the :file:`Kconfig.defconfig` files first. Kconfig 228uses the first ``default`` with a satisfied condition, where an empty condition 229corresponds to ``if y`` (is always satisfied). 230 231Note that conditions from surrounding top-level ``if``\ s are propagated to 232symbol properties, so the above ``default`` is equivalent to 233``default 32 if BOARD_MY_BOARD``. 234 235.. warning:: 236 237 When defining a symbol in multiple locations, dependencies are ORed together 238 rather than ANDed together. It is not possible to make the dependencies of a 239 symbol more restrictive by defining it in multiple locations. 240 241 For example, the direct dependencies of the symbol below becomes 242 ``DEP1 || DEP2``: 243 244 .. code-block:: none 245 246 config FOO 247 ... 248 depends on DEP1 249 250 config FOO 251 ... 252 depends on DEP2 253 254 When making changes to :file:`Kconfig.defconfig` files, always check the 255 symbol's direct dependencies in one of the :ref:`interactive configuration 256 interfaces <menuconfig>` afterwards. It is often necessary to repeat 257 dependencies from the base definition of the symbol to avoid weakening a 258 symbol's dependencies. 259 260 261Motivation for Kconfig.defconfig files 262-------------------------------------- 263 264One motivation for this configuration scheme is to avoid making fixed 265``BOARD``-specific settings configurable in the interactive configuration 266interfaces. If all board configuration were done via :file:`<BOARD>_defconfig`, 267all symbols would have to be visible, as values given in 268:file:`<BOARD>_defconfig` have no effect on invisible symbols. 269 270Having fixed settings be user-configurable would clutter up the configuration 271interfaces and make them harder to understand, and would make it easier to 272accidentally create broken configurations. 273 274When dealing with fixed board-specific settings, also consider whether they 275should be handled via :ref:`devicetree <dt-guide>` instead. 276 277 278Configuring choices 279------------------- 280 281There are two ways to configure a Kconfig ``choice``: 282 2831. By setting one of the choice symbols to ``y`` in a configuration file. 284 285 Setting one choice symbol to ``y`` automatically gives all other choice 286 symbols the value ``n``. 287 288 If multiple choice symbols are set to ``y``, only the last one set to ``y`` 289 will be honored (the rest will get the value ``n``). This allows a choice 290 selection from a board :file:`defconfig` file to be overridden from an 291 application :file:`prj.conf` file. 292 2932. By changing the ``default`` of the choice in :file:`Kconfig.defconfig`. 294 295 As with symbols, changing the default for a choice is done by defining the 296 choice in multiple locations. For this to work, the choice must have a name. 297 298 As an example, assume that a choice has the following base definition (here, 299 the name of the choice is ``FOO``): 300 301 .. code-block:: none 302 303 choice FOO 304 bool "Foo choice" 305 default B 306 307 config A 308 bool "A" 309 310 config B 311 bool "B" 312 313 endchoice 314 315 To change the default symbol of ``FOO`` to ``A``, you would add the 316 following definition to :file:`Kconfig.defconfig`: 317 318 .. code-block:: none 319 320 choice FOO 321 default A 322 endchoice 323 324The :file:`Kconfig.defconfig` method should be used when the dependencies of 325the choice might not be satisfied. In that case, you're setting the default 326selection whenever the user makes the choice visible. 327 328 329More Kconfig resources 330====================== 331 332The :ref:`kconfig_tips_and_tricks` page has some tips for writing Kconfig 333files. 334 335The :zephyr_file:`kconfiglib.py <scripts/kconfig/kconfiglib.py>` docstring 336docstring (at the top of the file) goes over how symbol values are calculated 337in detail. 338