.. _kbuild_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. There
are common characteristics followed by several examples to
organize the Kconfig files and to add new symbols configuration menus:

* The Kconfig file at the root directory holds general
  configuration options like the ARCH symbol and the KERNEL VERSION.
  These symbols are defined and apply to the entire build system.

* The Kconfig file at the kernel directory holds the general
  configuration related to the micro and the nanokernel.
  These are some configuration options hosted here:
  **Kernel Type** and **Enhanced Security**.

* The Kconfig file at the driver directory organizes the inclusion of
  the different Kconfig files for every driver supported in the system.

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

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

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 following configuration symbol states a dependency on
another one.

.. code-block:: kconfig

   config B bool

   config A depends on B

This means that 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 be set to.

Experimental Symbols
--------------------

The Kconfig file located at :file:`misc/` defines the
**EXPERIMENTAL** symbols.
This symbol controls which configuration symbols are
considered experimental from the development standpoint.

This specific symbol hides the options marked as experimental from the
end user. Experimental options are prone to error and users must
specifically enable the **EXPERIMENTAL** symbol to enable the options
listed with the experimental option.

The following convention applies: Always make new experimental
symbols dependent on the **EXPERIMENTAL** symbol.

.. code-block:: kconfig

   config NEW_EXP_SYMBOLS depends on EXPERIMENTAL


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 of a default configuration file contains the
type of kernel and the platform that is defined within the file.
All the defconfig files must end with the suffix defconfig.
For example, :file:`micro_galileo_defconfig` contains the configuration
information for the microkernel architecture for the galileo platform and
:file:`nano_generic_pc_pentium4` contains the configuration
information for the nanokernel architecture for the generic PC platform
with the Pentium processor platform variant.

The sanity checks use the default configuration files to dynamically
define what configuration corresponds to the platform that is being tested.

The :file:`Makefile.inc` file uses them as well to provide a
clean interface for the users that want to define new projects by
using environment variables to define the kernel type and the platform.

The build system provides the target defconfig. This target 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_snippets:

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

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

The user can provide a configuration file (:file:`prj.conf`) that describes
a small set of configuration symbols. This set must correspond with the
specific configuration symbols that differ from the default configuration.

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

.. caution::
   Note that invalid configurations, or configurations that do not comply
   with the dependencies stated in the Kconfig files, are ignored by the
   merge process. If you are adding configuration symbols through a
   configuration snippet, ensure that the the complete sequence of symbols
   complies with the dependency rules stated in the Kconfig files.