Setting Kconfig configuration values¶
The menuconfig and guiconfig interfaces can be used to test out configurations during application development. This page explains how to make settings permanent.
All Kconfig options can be searched in the Kconfig search page.
Before making changes to Kconfig files, it’s a good idea to also go through the Kconfig - Tips and Best Practices 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:
config FPU bool "Support floating point operations" depends on HAS_FPU
The symbol is shown like this in
menuconfig, where it can be toggled:
[ ] 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 of an invisible symbol:
config CPU_HAS_FPU bool help This symbol is y if the CPU has a hardware floating point unit.
In this case,
CPU_HAS_FPUis enabled through other symbols having
Setting symbols in configuration files¶
Visible symbols can be configured by setting them in configuration files. The
initial configuration is produced by merging a
*_defconfig file for the
board with application settings, usually from
The Initial Configuration below for more details.
Assignments in configuration files use this syntax:
There should be no spaces around the equals sign.
bool symbols can be enabled or disabled by setting them to
FPU symbol from the example above could be enabled like
A boolean symbol can also be set to
n with a comment formatted like
# CONFIG_SOME_OTHER_BOOL is not set
This is the format you will see in the merged configuration in
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:
CONFIG_SOME_STRING="cool value" CONFIG_SOME_INT=123
Comments use a #:
# 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 interactive configuration interfaces (you can jump directly to a symbol with /), or look up the symbol in the Kconfig search page.
The Initial Configuration¶
The initial configuration for an application comes from merging configuration settings from three sources:
BOARD-specific configuration file stored in
Any CMake cache entries prefix with
The application configuration
The application configuration can come from the sources below (each file is
known as a Kconfig fragment, which are then merged to get the final
configuration used for a particular build). By default,
CONF_FILEis set, the configuration file(s) specified in it are merged and used as the application configuration.
CONF_FILEcan be set in various ways:
CMakeLists.txt, before calling
-DCONF_FILE=<conf file(s)>, either directly or via
From the CMake variable cache
CONF_FILEis set as single configuration file of the form
prj_<build>.confand if file
boards/<BOARD>_<build>.confexists in same folder as file
prj_<build>.conf, the result of merging
prj_<BOARD>.confis used if it exists in the application configuration directory.
boards/<BOARD>.confexists in the application configuration directory, the result of merging it with
Otherwise, if board revisions are used and
boards/<BOARD>_<revision>.confexists in the application configuration directory, the result of merging it with
prj.confis used from the application configuration directory. If it does not exist then a fatal error will be emitted.
All configuration files will be taken from the application’s configuration
directory except for files with an absolute path that are given with the
EXTRA_DTC_OVERLAY_FILE arguments. For these,
a file in a Zephyr module can be referred by escaping the Zephyr module dir
variable like this
when setting any of said variables in the application’s
See Application Configuration Directory on how the application configuration directory is defined.
If a symbol is assigned both in
<BOARD>_defconfig and in the
application configuration, the value set in the application configuration takes
The merged configuration is saved to
zephyr/.config in the build
As long as
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.
zephyr/.config is also the
configuration that gets modified when making changes in the interactive
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
boards/<architecture>/<BOARD>/Kconfig.defconfig, which is a regular
.config files have no effect on invisible symbols,
so this scheme is not just an organizational issue.
Assigning values in
Kconfig.defconfig relies on defining a Kconfig
symbol in multiple locations. As an example, say we want to set
below to 32:
config FOO_WIDTH int
To do this, we extend the definition of
FOO_WIDTH as follows, in
if BOARD_MY_BOARD config FOO_WIDTH default 32 endif
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 Common Kconfig shorthands.
default values in
Kconfig.defconfig files have priority over
default values given on the “base” definition of a symbol. Internally, this
is implemented by including the
Kconfig.defconfig files first. Kconfig
uses the first
default with a satisfied condition, where an empty condition
if y (is always satisfied).
Note that conditions from surrounding top-level
ifs are propagated to
symbol properties, so the above
default is equivalent to
default 32 if BOARD_MY_BOARD.
Multiple symbol definitions¶
When a symbol is defined in multiple locations, each definition acts as an
independent symbol that happens to share the same name. This means that
properties are not appended to previous definitions. If the conditions
for ANY definition result in the symbol resolving to
y, the symbol
y. It is therefore not possible to make the dependencies of a
symbol more restrictive by defining it in multiple locations.
For example, the dependencies of the symbol
FOO below are satisfied if
DEP2 are true, it does not require both:
config FOO ... depends on DEP1 config FOO ... depends on DEP2
Symbols without explicit dependencies still follow the above rule. A
symbol without any dependencies will result in the symbol always being
assignable. The definition below will result in
FOO always being
enabled by default, regardless of the value of
config FOO bool "FOO" depends on DEP1 config FOO default y
This dependency weakening can be avoided with the configdefault extension if the desire is only to add a new default without modifying any other behaviour of the symbol.
When making changes to
Kconfig.defconfig files, always check the
symbol’s direct dependencies in one of the interactive configuration
interfaces afterwards. It is often necessary to repeat
dependencies from the base definition of the symbol to avoid weakening a
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
all symbols would have to be visible, as values given in
<BOARD>_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 should be handled via devicetree instead.
There are two ways to configure a Kconfig
By setting one of the choice symbols to
yin a configuration file.
Setting one choice symbol to
yautomatically gives all other choice symbols the value
If multiple choice symbols are set to
y, only the last one set to
ywill be honored (the rest will get the value
n). This allows a choice selection from a board
defconfigfile to be overridden from an application
By changing the
defaultof the choice in
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
choice FOO bool "Foo choice" default B config A bool "A" config B bool "B" endchoice
To change the default symbol of
A, you would add the following definition to
choice FOO default A endchoice
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 Kconfig - Tips and Best Practices page has some tips for writing Kconfig files.
The kconfiglib.py docstring (at the top of the file) goes over how symbol values are calculated in detail.