zephyr/doc/reference/kbuild_kconfig.rst

.. _kconfig:

The Kconfig File Structure
**************************

Introduction
============

The Kconfig files describe: the configuration symbols supported in the
build system, the logical organization and structure to group the symbols in menus and sub-menus,
and the relationships between the different configuration symbols that govern the valid
configuration combinations.

The Kconfig files are distributed across the build directory tree. The files are organized
based on their common characteristics and on what new symbols they add to the configuration
menus. For example:

* The Kconfig file at the root directory contains the general configuration options like
  :option:`ARCH` and :option:`KERNEL VERSION`. These symbols are defined for and apply to the
  entire build system.

* The Kconfig file at the :file:`kernel` directory contains the general configuration related to
  the micro- and the nanokernel. Some configuration options contained here are: :option:`Kernel
  Type` and :option:`Enhanced Security`.

* The Kconfig file at the :file:`driver` directory organizes the inclusion of the various Kconfig
  files needed for each supported driver in the system.

* The Kconfig file at the :file:`misc` directory contains the configuration symbols that affect
  different aspects of the build system. For example, the :option:`Custom Compiler Options` and the
  :option:`Minimal Libc` are general build options that apply to the build system.
  :option:`Debugging Options` and :option:`System Monitoring Options` are also examples of build
  options that apply to the entire system.

* The Kconfig file at the :file:`net` directory contains the different symbols that define the
  configuration options for the communications stack code.

* The Kconfig file at the :file:`crypto` directory contains the different symbols that define the
  configuration options for the cryptography algorithms supported.

Dependencies
============

Dependencies allow you to define the valid and invalid configuration combinations in the system.
Each dependency is a rule that a particular symbol must follow to be either selected or allowed to
have a specific value. For example, the configuration symbol *B* states a dependency on
another one, *A*.

.. code-block:: kconfig

   config B bool

   config A depends on B

The symbol A does not exist as a configuration option in the system unless B is set to true.

The complete set of dependency rules defines the valid configuration combinations that the system
can use.


Default Configurations
======================

The default configuration files define the default configuration
for a specific kernel on a specific platform. For example:
:file:`arch/arm/configs`, :file:`arch/x86/configs` and :file:`arch/arc/configs`.

The file name convention for a :abbr:`defconfig (default configuration)` file mandates that the
type of kernel and the platform are included within the file name. Further, all the defconfig files
must end with the suffix defconfig. For example, the :file:`micro_galileo_defconfig` file contains
the configuration information for the microkernel architecture for the galileo platform
configuration and the :file:`nano_basic_atom_defconfig` file contains the configuration
information for the nanokernel architecture for the basic atom platform.

The defconfig files are used to dynamically determine the configuration that corresponds to the
platform tested by the sanity checks.

The :file:`Makefile.inc` file uses defconfig files to provide a clean interface to developers using
environment variables to define the kernel type and the platform of new projects. Developers can
provide the build system with a target's defconfig. The build system takes the specified defconfig
file and sets it as the current :file:`.config` file for the current project. For example:

.. code-block:: bash

   $ make defconfig micro_galileo_defconfig

The command takes the default configuration for the microkernel architecture and the galileo
platform configuration to compile the kernel.

.. _configuration_snippets:

Merging Configuration Snippets
==============================

Configuration file snippets can be merged with the current project configuration during the build.

Developers can provide a configuration file that defines a small subset of configuration options.
The subset must contain the specific configuration options that differ from the default
configuration.

The **initconfig** target pulls the default configuration file and merges it with the configuration
snippet. For example, the sample application **hello world** overrides the base configuration with
the configuration snippet :file:`prj.conf`.

.. caution::
   Invalid configurations, or configurations that do not comply with the dependencies stated in the
   Kconfig files, are ignored by the merge process. When adding configuration options through a
   configuration snippet, ensure that the the complete sequence complies with the dependency rules
   defined in the Kconfig files.