zephyr/doc/build/kconfig/setting.rst

377 lines
12 KiB
ReStructuredText

.. _setting_configuration_values:
Setting Kconfig configuration values
####################################
The :ref:`menuconfig and guiconfig interfaces <menuconfig>` 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 :ref:`Kconfig search page
<kconfig-search>`.
.. 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:: kconfig
config FPU
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 of an invisible symbol:
.. code-block:: kconfig
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:: cfg
CONFIG_<symbol name>=<value>
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 ``FPU`` symbol from the example above could be enabled like
this:
.. code-block:: cfg
CONFIG_FPU=y
.. note::
A boolean symbol can also be set to ``n`` with a comment formatted like
this:
.. code-block:: cfg
# 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:: cfg
CONFIG_SOME_STRING="cool value"
CONFIG_SOME_INT=123
Comments use a #:
.. code-block:: cfg
# 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 <menuconfig>` (you can jump directly to a symbol with
:kbd:`/`), or look up the symbol in the :ref:`Kconfig search page
<kconfig-search>`.
.. _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/<architecture>/<BOARD>/<BOARD>_defconfig`
2. Any CMake cache entries prefix with ``CONFIG_``
3. 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, :file:`prj.conf` is
used.
#. 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 calling ``find_package(Zephyr)``
2. By passing ``-DCONF_FILE=<conf file(s)>``, either directly or via ``west``
3. From the CMake variable cache
Furthermore if ``CONF_FILE`` is set as single configuration file of the
form :file:`prj_<build>.conf` and if file
:file:`boards/<BOARD>_<build>.conf` exists in same folder as file
:file:`prj_<build>.conf`, the result of merging :file:`prj_<build>.conf` and
:file:`boards/<BOARD>_<build>.conf` is used.
#. Otherwise, :file:`prj_<BOARD>.conf` is used if it exists in the application
configuration directory.
#. Otherwise, if :file:`boards/<BOARD>.conf` exists in the application
configuration directory, the result of merging it with :file:`prj.conf` is
used.
#. Otherwise, if board revisions are used and
:file:`boards/<BOARD>_<revision>.conf` exists in the application
configuration directory, the result of merging it with :file:`prj.conf` and
:file:`boards/<BOARD>.conf` is used.
#. Otherwise, :file:`prj.conf` is 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
``CONF_FILE``, ``EXTRA_CONF_FILE``, ``DTC_OVERLAY_FILE``, and
``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 ``\${ZEPHYR_<module>_MODULE_DIR}/<path-to>/<file>``
when setting any of said variables in the application's :file:`CMakeLists.txt`.
See :ref:`Application Configuration Directory <application-configuration-directory>`
on how the application configuration directory is defined.
If a symbol is assigned both in :file:`<BOARD>_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 <menuconfig>`.
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/<architecture>/<BOARD>/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:: kconfig
config FOO_WIDTH
int
To do this, we extend the definition of ``FOO_WIDTH`` as follows, in
:file:`Kconfig.defconfig`:
.. code-block:: kconfig
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``.
.. _multiple_symbol_definitions:
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
will be ``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
either ``DEP1`` **OR** ``DEP2`` are true, it does not require both:
.. code-block:: none
config FOO
...
depends on DEP1
config FOO
...
depends on DEP2
.. warning::
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 ``DEP1``.
.. code-block:: kconfig
config FOO
bool "FOO"
depends on DEP1
config FOO
default y
This dependency weakening can be avoided with the :ref:`configdefault
<kconfig_extensions>` extension if the desire is only to add a new default
without modifying any other behaviour of the symbol.
.. note::
When making changes to :file:`Kconfig.defconfig` files, always check the
symbol's direct dependencies in one of the :ref:`interactive configuration
interfaces <menuconfig>` 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:`<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 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 :ref:`devicetree <dt-guide>` 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:: kconfig
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:: kconfig
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 <scripts/kconfig/kconfiglib.py>` docstring
(at the top of the file) goes over how symbol values are calculated in detail.