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