Introduction¶

The configuration database is a collection of configuration optionsorganized in a tree structure:

+- Code maturity level options|  +- Prompt for development and/or incomplete code/drivers+- General setup|  +- Networking support|  +- System V IPC|  +- BSD Process Accounting|  +- Sysctl support+- Loadable module support|  +- Enable loadable module support|     +- Set version information on all module symbols|     +- Kernel module loader+- ...

Every entry has its own dependencies. These dependencies are usedto determine the visibility of an entry. Any child entry is onlyvisible if its parent entry is also visible.

Menu entries¶

Most entries define a config option; all other entries help to organizethem. A single configuration option is defined like this:

config MODVERSIONS      bool "Set version information on all module symbols"      depends on MODULES      help        Usually, modules have to be recompiled whenever you switch to a new        kernel.  ...

Every line starts with a key word and can be followed by multiplearguments. “config” starts a new config entry. The following linesdefine attributes for this config option. Attributes can be the type ofthe config option, input prompt, dependencies, help text and defaultvalues. A config option can be defined multiple times with the samename, but every definition can have only a single input prompt and thetype must not conflict.

Menu attributes¶

A menu entry can have a number of attributes. Not all of them areapplicable everywhere (see syntax).

• type definition: “bool”/”tristate”/”string”/”hex”/”int”

  Every config option must have a type. There are only two basic types:tristate and string; the other types are based on these two. The typedefinition optionally accepts an input prompt, so these two examplesare equivalent:

  bool "Networking support"

  and:

  boolprompt "Networking support"

• input prompt: “prompt” <prompt> [“if” <expr>]

  Every menu entry can have at most one prompt, which is used to displayto the user. Optionally dependencies only for this prompt can be addedwith “if”. If a prompt is not present, the config option is a non-visiblesymbol, meaning its value cannot be directly changed by the user (such asaltering the value in.config) and the option will not appear in anyconfig menus. Its value can only be set via “default” and “select” (seebelow).

• default value: “default” <expr> [“if” <expr>]

  A config option can have any number of default values. If multipledefault values are visible, only the first defined one is active.Default values are not limited to the menu entry where they aredefined. This means the default can be defined somewhere else or beoverridden by an earlier definition.The default value is only assigned to the config symbol if no othervalue was set by the user (via the input prompt above). If an inputprompt is visible the default value is presented to the user and canbe overridden by him.Optionally, dependencies only for this default value can be added with“if”.

The default value deliberately defaults to ‘n’ in order to avoid bloating thebuild. With few exceptions, new config options should not change this. Theintent is for “make oldconfig” to add as little as possible to the config fromrelease to release.

Note:

Things that merit “default y/m” include:

1. A new Kconfig option for something that used to always be builtshould be “default y”.

2. A new gatekeeping Kconfig option that hides/shows other Kconfigoptions (but does not generate any code of its own), should be“default y” so people will see those other options.

3. Sub-driver behavior or similar options for a driver that is“default n”. This allows you to provide sane defaults.

4. Hardware or infrastructure that everybody expects, such as CONFIG_NETor CONFIG_BLOCK. These are rare exceptions.

• type definition + default value:

  "def_bool"/"def_tristate" <expr> ["if" <expr>]

  This is a shorthand notation for a type definition plus a value.Optionally dependencies for this default value can be added with “if”.

• dependencies: “depends on” <expr>

  This defines a dependency for this menu entry. If multipledependencies are defined, they are connected with ‘&&’. Dependenciesare applied to all other options within this menu entry (which alsoaccept an “if” expression), so these two examples are equivalent:

  bool "foo" if BARdefault y if BAR

  and:

  depends on BARbool "foo"default y

• reverse dependencies: “select” <symbol> [“if” <expr>]

  While normal dependencies reduce the upper limit of a symbol (seebelow), reverse dependencies can be used to force a lower limit ofanother symbol. The value of the current menu symbol is used as theminimal value <symbol> can be set to. If <symbol> is selected multipletimes, the limit is set to the largest selection.Reverse dependencies can only be used with boolean or tristatesymbols.

  Note:

  select should be used with care. select will forcea symbol to a value without visiting the dependencies.By abusing select you are able to select a symbol FOO evenif FOO depends on BAR that is not set.In general use select only for non-visible symbols(no prompts anywhere) and for symbols with no dependencies.That will limit the usefulness but on the other hand avoidthe illegal configurations all over.

  If “select” <symbol> is followed by “if” <expr>, <symbol> will beselected by the logical AND of the value of the current menu symboland <expr>. This means, the lower limit can be downgraded due to thepresence of “if” <expr>. This behavior may seem weird, but we rely onit. (The future of this behavior is undecided.)

• weak reverse dependencies: “imply” <symbol> [“if” <expr>]

  This is similar to “select” as it enforces a lower limit on anothersymbol except that the “implied” symbol’s value may still be set to nfrom a direct dependency or with a visible prompt.

  Given the following example:

  config FOO    tristate "foo"    imply BAZconfig BAZ    tristate "baz"    depends on BAR

  The following values are possible:

  FOO	BAR	BAZ’s default	choice for BAZ
  n	y	n	N/m/y
  m	y	m	M/y/n
  y	y	y	Y/m/n
  n	m	n	N/m
  m	m	m	M/n
  y	m	m	M/n
  y	n		N

  This is useful e.g. with multiple drivers that want to indicate theirability to hook into a secondary subsystem while allowing the user toconfigure that subsystem out without also having to unset these drivers.

  Note: If the feature provided by BAZ is highly desirable for FOO,FOO should imply not only BAZ, but also its dependency BAR:

  config FOO    tristate "foo"    imply BAR    imply BAZ

  Note: If “imply” <symbol> is followed by “if” <expr>, the default of <symbol>will be the logical AND of the value of the current menu symbol and <expr>.(The future of this behavior is undecided.)

• limiting menu display: “visible if” <expr>

  This attribute is only applicable to menu blocks, if the condition isfalse, the menu block is not displayed to the user (the symbolscontained there can still be selected by other symbols, though). It issimilar to a conditional “prompt” attribute for individual menuentries. Default value of “visible” is true.

• numerical ranges: “range” <symbol> <symbol> [“if” <expr>]

  This allows to limit the range of possible input values for intand hex symbols. The user can only input a value which is larger thanor equal to the first symbol and smaller than or equal to the secondsymbol.

• help text: “help”

  This defines a help text. The end of the help text is determined bythe indentation level, this means it ends at the first line which hasa smaller indentation than the first line of the help text.

• module attribute: “modules”This declares the symbol to be used as the MODULES symbol, whichenables the third modular state for all config symbols.At most one symbol may have the “modules” option set.

• transitional attribute: “transitional”This declares the symbol as transitional, meaning it should be processedduring configuration but omitted from newly written .config files.Transitional symbols are useful for backward compatibility during configoption migrations - they allow olddefconfig to process existing .configfiles while ensuring the old option doesn’t appear in new configurations.

  A transitional symbol:- Has no prompt (is not visible to users in menus)- Is processed normally during configuration (values are read and used)- Can be referenced in default expressions of other symbols- Is not written to new .config files- Cannot have any other properties (it is a pass-through option)

  Example migration from OLD_NAME to NEW_NAME:

  config NEW_NAME    bool "New option name"    default OLD_NAME    help      This replaces the old CONFIG_OLD_NAME option.config OLD_NAME    bool    transitional    help      Transitional config for OLD_NAME to NEW_NAME migration.

  With this setup, existing .config files with “CONFIG_OLD_NAME=y” willresult in “CONFIG_NEW_NAME=y” being set, while CONFIG_OLD_NAME will beomitted from newly written .config files.

Menu dependencies¶

Dependencies define the visibility of a menu entry and can also reducethe input range of tristate symbols. The tristate logic used in theexpressions uses one more state than normal boolean logic to express themodule state. Dependency expressions have the following syntax:

<expr> ::= <symbol>                           (1)         <symbol> '=' <symbol>                (2)         <symbol> '!=' <symbol>               (3)         <symbol1> '<' <symbol2>              (4)         <symbol1> '>' <symbol2>              (4)         <symbol1> '<=' <symbol2>             (4)         <symbol1> '>=' <symbol2>             (4)         '(' <expr> ')'                       (5)         '!' <expr>                           (6)         <expr> '&&' <expr>                   (7)         <expr> '||' <expr>                   (8)

Expressions are listed in decreasing order of precedence.

1. Convert the symbol into an expression. Boolean and tristate symbolsare simply converted into the respective expression values. Allother symbol types result in ‘n’.

2. If the values of both symbols are equal, it returns ‘y’,otherwise ‘n’.

3. If the values of both symbols are equal, it returns ‘n’,otherwise ‘y’.

4. If value of <symbol1> is respectively lower, greater, lower-or-equal,or greater-or-equal than value of <symbol2>, it returns ‘y’,otherwise ‘n’.

5. Returns the value of the expression. Used to override precedence.

6. Returns the result of (2-/expr/).

7. Returns the result of min(/expr/, /expr/).

8. Returns the result of max(/expr/, /expr/).

An expression can have a value of ‘n’, ‘m’ or ‘y’ (or 0, 1, 2respectively for calculations). A menu entry becomes visible when itsexpression evaluates to ‘m’ or ‘y’.

There are two types of symbols: constant and non-constant symbols.Non-constant symbols are the most common ones and are defined with the‘config’ statement. Non-constant symbols consist entirely of alphanumericcharacters or underscores.Constant symbols are only part of expressions. Constant symbols arealways surrounded by single or double quotes. Within the quote, anyother character is allowed and the quotes can be escaped using ‘'.

Menu structure¶

The position of a menu entry in the tree is determined in two ways. Firstit can be specified explicitly:

menu "Network device support"      depends on NETconfig NETDEVICES      ...endmenu

All entries within the “menu” ... “endmenu” block become a submenu of“Network device support”. All subentries inherit the dependencies fromthe menu entry, e.g. this means the dependency “NET” is added to thedependency list of the config option NETDEVICES.

The other way to generate the menu structure is done by analyzing thedependencies. If a menu entry somehow depends on the previous entry, itcan be made a submenu of it. First, the previous (parent) symbol mustbe part of the dependency list and then one of these two conditionsmust be true:

• the child entry must become invisible, if the parent is set to ‘n’

• the child entry must only be visible, if the parent is visible:

  config MODULES    bool "Enable loadable module support"config MODVERSIONS    bool "Set version information on all module symbols"    depends on MODULEScomment "module support disabled"    depends on !MODULES

MODVERSIONS directly depends on MODULES, this means it’s only visible ifMODULES is different from ‘n’. The comment on the other hand is onlyvisible when MODULES is set to ‘n’.

Kconfig syntax¶

The configuration file describes a series of menu entries, where everyline starts with a keyword (except help texts). The following keywordsend a menu entry:

• config

• menuconfig

• choice/endchoice

• comment

• menu/endmenu

• if/endif

• source

The first five also start the definition of a menu entry.

config:

"config" <symbol><config options>

This defines a config symbol <symbol> and accepts any of aboveattributes as options.

menuconfig:

"menuconfig" <symbol><config options>

This is similar to the simple config entry above, but it also gives ahint to front ends, that all suboptions should be displayed as aseparate list of options. To make sure all the suboptions will reallyshow up under the menuconfig entry and not outside of it, every itemfrom the <config options> list must depend on the menuconfig symbol.In practice, this is achieved by using one of the next two constructs:

(1):menuconfig Mif M    config C1    config C2endif(2):menuconfig Mconfig C1    depends on Mconfig C2    depends on M

In the following examples (3) and (4), C1 and C2 still have the Mdependency, but will not appear under menuconfig M anymore, becauseof C0, which doesn’t depend on M:

(3):menuconfig M    config C0if M    config C1    config C2endif(4):menuconfig Mconfig C0config C1    depends on Mconfig C2    depends on M

choices:

"choice"<choice options><choice block>"endchoice"

This defines a choice group and accepts “prompt”, “default”, “depends on”, and“help” attributes as options.

A choice only allows a single config entry to be selected.

comment:

"comment" <prompt><comment options>

This defines a comment which is displayed to the user during theconfiguration process and is also echoed to the output files. The onlypossible options are dependencies.

menu:

"menu" <prompt><menu options><menu block>"endmenu"

This defines a menu block, see “Menu structure” above for moreinformation. The only possible options are dependencies and “visible”attributes.

if:

"if" <expr><if block>"endif"

This defines an if block. The dependency expression <expr> is appendedto all enclosed menu entries.

source:

"source" <prompt>

This reads the specified configuration file. This file is always parsed.

mainmenu:

"mainmenu" <prompt>

This sets the config program’s title bar if the config program choosesto use it. It should be placed at the top of the configuration, before anyother statement.

‘#’ Kconfig source file comment:

An unquoted ‘#’ character anywhere in a source file line indicatesthe beginning of a source file comment. The remainder of that lineis a comment.

Kconfig hints¶

This is a collection of Kconfig tips, most of which aren’t obvious atfirst glance and most of which have become idioms in several Kconfigfiles.

# Generic IOMAP is used to ...config HAVE_GENERIC_IOMAPconfig GENERIC_IOMAP      depends on HAVE_GENERIC_IOMAP && FOO

obj-$(CONFIG_GENERIC_IOMAP) += iomap.o

config X86      select ...      select HAVE_GENERIC_IOMAP      select ...

config STACKPROTECTOR      bool "Stack Protector buffer overflow detection"      depends on $(cc-option,-fstack-protector)      ...

config CC_HAS_FOO      def_bool $(success,$(srctree)/scripts/cc-check-foo.sh $(CC))

config FOO      depends on BAR && m

config FOO      tristate "Support for foo hardware"      depends on BAR || !BAR

config FOO      tristate "Support for foo hardware"      depends on BAR_OPTIONALconfig BAR_OPTIONAL      def_tristate BAR || !BAR

foo_init(){        if (IS_REACHABLE(CONFIG_BAR))                bar_register(&foo);        ...}

make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig

make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig