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 10All Kconfig options can be searched in the :ref:`Kconfig search page 11<kconfig-search>`. 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:: kconfig 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 of an invisible symbol: 49 50 .. code-block:: kconfig 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:: cfg 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:: cfg 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:: cfg 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:: cfg 104 105 CONFIG_SOME_STRING="cool value" 106 CONFIG_SOME_INT=123 107 108Comments use a #: 109 110.. code-block:: cfg 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 search page 119<kconfig-search>`. 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 (each file is 138known as a Kconfig fragment, which are then merged to get the final 139configuration used for a particular build). By default, :file:`prj.conf` is 140used. 141 142#. If ``CONF_FILE`` is set, the configuration file(s) specified in it are 143 merged and used as the application configuration. ``CONF_FILE`` can be set 144 in various ways: 145 146 1. In :file:`CMakeLists.txt`, before calling ``find_package(Zephyr)`` 147 148 2. By passing ``-DCONF_FILE=<conf file(s)>``, either directly or via ``west`` 149 150 3. From the CMake variable cache 151 152 Furthermore if ``CONF_FILE`` is set as single configuration file of the 153 form :file:`prj_<build>.conf` and if file 154 :file:`boards/<BOARD>_<build>.conf` exists in same folder as file 155 :file:`prj_<build>.conf`, the result of merging :file:`prj_<build>.conf` and 156 :file:`boards/<BOARD>_<build>.conf` is used. 157 158#. Otherwise, :file:`prj_<BOARD>.conf` is used if it exists in the application 159 configuration directory. 160 161#. Otherwise, if :file:`boards/<BOARD>.conf` exists in the application 162 configuration directory, the result of merging it with :file:`prj.conf` is 163 used. 164 165#. Otherwise, if board revisions are used and 166 :file:`boards/<BOARD>_<revision>.conf` exists in the application 167 configuration directory, the result of merging it with :file:`prj.conf` and 168 :file:`boards/<BOARD>.conf` is used. 169 170#. Otherwise, :file:`prj.conf` is used from the application configuration 171 directory. If it does not exist then a fatal error will be emitted. 172 173All configuration files will be taken from the application's configuration 174directory except for files with an absolute path that are given with the 175``CONF_FILE``, ``EXTRA_CONF_FILE``, ``DTC_OVERLAY_FILE``, and 176``EXTRA_DTC_OVERLAY_FILE`` arguments. For these, 177a file in a Zephyr module can be referred by escaping the Zephyr module dir 178variable like this ``\${ZEPHYR_<module>_MODULE_DIR}/<path-to>/<file>`` 179when setting any of said variables in the application's :file:`CMakeLists.txt`. 180 181See :ref:`Application Configuration Directory <application-configuration-directory>` 182on how the application configuration directory is defined. 183 184If a symbol is assigned both in :file:`<BOARD>_defconfig` and in the 185application configuration, the value set in the application configuration takes 186precedence. 187 188The merged configuration is saved to :file:`zephyr/.config` in the build 189directory. 190 191As long as :file:`zephyr/.config` exists and is up-to-date (is newer than any 192``BOARD`` and application configuration files), it will be used in preference 193to producing a new merged configuration. :file:`zephyr/.config` is also the 194configuration that gets modified when making changes in the :ref:`interactive 195configuration interfaces <menuconfig>`. 196 197 198Configuring invisible Kconfig symbols 199************************************* 200 201When making changes to the default configuration for a board, you might have to 202configure invisible symbols. This is done in 203:file:`boards/<architecture>/<BOARD>/Kconfig.defconfig`, which is a regular 204:file:`Kconfig` file. 205 206.. note:: 207 208 Assignments in :file:`.config` files have no effect on invisible symbols, 209 so this scheme is not just an organizational issue. 210 211Assigning values in :file:`Kconfig.defconfig` relies on defining a Kconfig 212symbol in multiple locations. As an example, say we want to set ``FOO_WIDTH`` 213below to 32: 214 215.. code-block:: kconfig 216 217 config FOO_WIDTH 218 int 219 220To do this, we extend the definition of ``FOO_WIDTH`` as follows, in 221:file:`Kconfig.defconfig`: 222 223.. code-block:: kconfig 224 225 if BOARD_MY_BOARD 226 227 config FOO_WIDTH 228 default 32 229 230 endif 231 232.. note:: 233 234 Since the type of the symbol (``int``) has already been given at the first 235 definition location, it does not need to be repeated here. Only giving the 236 type once at the "base" definition of the symbol is a good idea for reasons 237 explained in :ref:`kconfig_shorthands`. 238 239``default`` values in :file:`Kconfig.defconfig` files have priority over 240``default`` values given on the "base" definition of a symbol. Internally, this 241is implemented by including the :file:`Kconfig.defconfig` files first. Kconfig 242uses the first ``default`` with a satisfied condition, where an empty condition 243corresponds to ``if y`` (is always satisfied). 244 245Note that conditions from surrounding top-level ``if``\ s are propagated to 246symbol properties, so the above ``default`` is equivalent to 247``default 32 if BOARD_MY_BOARD``. 248 249.. warning:: 250 251 When defining a symbol in multiple locations, dependencies are ORed together 252 rather than ANDed together. It is not possible to make the dependencies of a 253 symbol more restrictive by defining it in multiple locations. 254 255 For example, the direct dependencies of the symbol below becomes 256 ``DEP1 || DEP2``: 257 258 .. code-block:: kconfig 259 260 config FOO 261 ... 262 depends on DEP1 263 264 config FOO 265 ... 266 depends on DEP2 267 268 When making changes to :file:`Kconfig.defconfig` files, always check the 269 symbol's direct dependencies in one of the :ref:`interactive configuration 270 interfaces <menuconfig>` afterwards. It is often necessary to repeat 271 dependencies from the base definition of the symbol to avoid weakening a 272 symbol's dependencies. 273 274 275Motivation for Kconfig.defconfig files 276-------------------------------------- 277 278One motivation for this configuration scheme is to avoid making fixed 279``BOARD``-specific settings configurable in the interactive configuration 280interfaces. If all board configuration were done via :file:`<BOARD>_defconfig`, 281all symbols would have to be visible, as values given in 282:file:`<BOARD>_defconfig` have no effect on invisible symbols. 283 284Having fixed settings be user-configurable would clutter up the configuration 285interfaces and make them harder to understand, and would make it easier to 286accidentally create broken configurations. 287 288When dealing with fixed board-specific settings, also consider whether they 289should be handled via :ref:`devicetree <dt-guide>` instead. 290 291 292Configuring choices 293------------------- 294 295There are two ways to configure a Kconfig ``choice``: 296 2971. By setting one of the choice symbols to ``y`` in a configuration file. 298 299 Setting one choice symbol to ``y`` automatically gives all other choice 300 symbols the value ``n``. 301 302 If multiple choice symbols are set to ``y``, only the last one set to ``y`` 303 will be honored (the rest will get the value ``n``). This allows a choice 304 selection from a board :file:`defconfig` file to be overridden from an 305 application :file:`prj.conf` file. 306 3072. By changing the ``default`` of the choice in :file:`Kconfig.defconfig`. 308 309 As with symbols, changing the default for a choice is done by defining the 310 choice in multiple locations. For this to work, the choice must have a name. 311 312 As an example, assume that a choice has the following base definition (here, 313 the name of the choice is ``FOO``): 314 315 .. code-block:: kconfig 316 317 choice FOO 318 bool "Foo choice" 319 default B 320 321 config A 322 bool "A" 323 324 config B 325 bool "B" 326 327 endchoice 328 329 To change the default symbol of ``FOO`` to ``A``, you would add the 330 following definition to :file:`Kconfig.defconfig`: 331 332 .. code-block:: kconfig 333 334 choice FOO 335 default A 336 endchoice 337 338The :file:`Kconfig.defconfig` method should be used when the dependencies of 339the choice might not be satisfied. In that case, you're setting the default 340selection whenever the user makes the choice visible. 341 342 343More Kconfig resources 344====================== 345 346The :ref:`kconfig_tips_and_tricks` page has some tips for writing Kconfig 347files. 348 349The :zephyr_file:`kconfiglib.py <scripts/kconfig/kconfiglib.py>` docstring 350docstring (at the top of the file) goes over how symbol values are calculated 351in detail. 352
