From 43b17b1cd0dd3eac740e4770be77db2c9010ad04 Mon Sep 17 00:00:00 2001 From: Kartik Agaram Date: Thu, 31 May 2018 22:15:55 -0700 Subject: [PATCH] restore documentation on the build config language Kconfig-language.txt was deleted in commit 4fa499a17b52b back in 2006. Move to docs/ as suggested by Xabier Oneca: http://lists.busybox.net/pipermail/busybox/2014-May/080914.html Also update references to it everywhere. Signed-off-by: Kartik Agaram Signed-off-by: Denys Vlasenko --- Config.in | 2 +- archival/Config.src | 2 +- console-tools/Config.src | 2 +- coreutils/Config.src | 2 +- debianutils/Config.src | 2 +- docs/Kconfig-language.txt | 255 ++++++++++++++++++++++++++++++++ e2fsprogs/Config.src | 2 +- editors/Config.src | 2 +- findutils/Config.src | 2 +- init/Config.src | 2 +- klibc-utils/Config.src | 2 +- libbb/Config.src | 2 +- loginutils/Config.src | 2 +- miscutils/Config.src | 2 +- modutils/Config.src | 2 +- networking/Config.src | 2 +- networking/udhcp/Config.src | 2 +- printutils/Config.src | 2 +- procps/Config.src | 2 +- runit/Config.src | 2 +- selinux/Config.src | 2 +- shell/Config.src | 2 +- sysklogd/Config.src | 2 +- util-linux/Config.src | 2 +- util-linux/volume_id/Config.src | 2 +- 25 files changed, 279 insertions(+), 24 deletions(-) create mode 100644 docs/Kconfig-language.txt diff --git a/Config.in b/Config.in index 51ff01ef4..ae21f52ef 100644 --- a/Config.in +++ b/Config.in @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # mainmenu "Configuration" diff --git a/archival/Config.src b/archival/Config.src index 449914565..6f4f30c43 100644 --- a/archival/Config.src +++ b/archival/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Archival Utilities" diff --git a/console-tools/Config.src b/console-tools/Config.src index e6587ade4..c30caf0e1 100644 --- a/console-tools/Config.src +++ b/console-tools/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Console Utilities" diff --git a/coreutils/Config.src b/coreutils/Config.src index 7a8a3a634..1bded03a6 100644 --- a/coreutils/Config.src +++ b/coreutils/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Coreutils" diff --git a/debianutils/Config.src b/debianutils/Config.src index 61daeb047..17b0d8945 100644 --- a/debianutils/Config.src +++ b/debianutils/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Debian Utilities" diff --git a/docs/Kconfig-language.txt b/docs/Kconfig-language.txt new file mode 100644 index 000000000..0ba8932ba --- /dev/null +++ b/docs/Kconfig-language.txt @@ -0,0 +1,255 @@ +Introduction +------------ + +The configuration database is collection of configuration options +organized 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 used +to determine the visible of an entry. Any child entry is only +visible if its parent entry is also visible. + +Menu entries +------------ + +Most entries define a config option, all other entries help to organize +them. A single configuration option is defined like this: + +config MODVERSIONS + bool "Set version information on all module symbols" + depends 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 multiple +arguments. "config" starts a new config entry. The following lines +define attributes for this config option. Attributes can be the type of +the config option, input prompt, dependencies, help text and default +values. A config option can be defined multiple times with the same +name, but every definition can have only a single input prompt and the +type must not conflict. + +Menu attributes +--------------- + +A menu entry can have a number of attributes. Not all of them are +applicable everywhere (see syntax). + +- type definition: "bool"/"tristate"/"string"/"hex"/"integer" + Every config option must have a type. There are only two basic types: + tristate and string, the other types base on these two. The type + definition optionally accepts an input prompt, so these two examples + are equivalent: + + bool "Networking support" + and + bool + prompt "Networking support" + +- input prompt: "prompt" ["if" ] + Every menu entry can have at most one prompt, which is used to display + to the user. Optionally dependencies only for this prompt can be added + with "if". + +- default value: "default" ["if" ] + A config option can have any number of default values. If multiple + default values are visible, only the first defined one is active. + Default values are not limited to the menu entry, where they are + defined, this means the default can be defined somewhere else or be + overridden by an earlier definition. + The default value is only assigned to the config symbol if no other + value was set by the user (via the input prompt above). If an input + prompt is visible the default value is presented to the user and can + be overridden by him. + Optionally dependencies only for this default value can be added with + "if". + +- dependencies: "depends on"/"requires" + This defines a dependency for this menu entry. If multiple + dependencies are defined they are connected with '&&'. Dependencies + are applied to all other options within this menu entry (which also + accept "if" expression), so these two examples are equivalent: + + bool "foo" if BAR + default y if BAR + and + depends on BAR + bool "foo" + default y + +- help text: "help" + This defines a help text. The end of the help text is determined by + the level indentation, this means it ends at the first line which has + a smaller indentation than the first line of the help text. + + +Menu dependencies +----------------- + +Dependencies define the visibility of a menu entry and can also reduce +the input range of tristate symbols. The tristate logic used in the +expressions uses one more state than normal boolean logic to express the +module state. Dependency expressions have the following syntax: + + ::= (1) + '=' (2) + '!=' (3) + '(' ')' (4) + '!' (5) + '||' (6) + '&&' (7) + +Expressions are listed in decreasing order of precedence. + +(1) Convert the symbol into an expression. Boolean and tristate symbols + are simply converted into the respective expression values. All + other 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) Returns the value of the expression. Used to override precedence. +(5) Returns the result of (2-/expr/). +(6) Returns the result of min(/expr/, /expr/). +(7) Returns the result of max(/expr/, /expr/). + +An expression can have a value of 'n', 'm' or 'y' (or 0, 1, 2 +respectively for calculations). A menu entry becomes visible when it's +expression evaluates to 'm' or 'y'. + +There are two type of symbols: constant and nonconstant symbols. +Nonconstant symbols are the most common ones and are defined with the +'config' statement. Nonconstant symbols consist entirely of alphanumeric +characters or underscores. +Constant symbols are only part of expressions. Constant symbols are +always surrounded by single or double quotes. Within the quote any +other 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. First +it can be specified explicitely: + +menu "Network device support" + depends NET + +config NETDEVICES + ... + +endmenu + +All entries within the "menu" ... "endmenu" block become a submenu of +"Network device support". All subentries inherit the dependencies from +the menu entry, e.g. this means the dependency "NET" is added to the +dependency list of the config option NETDEVICES. + +The other way to generate the menu structure is done by analyzing the +dependencies. If a menu entry somehow depends on the previous entry, it +can be made a submenu of it. First the the previous (parent) symbol must +be part of the dependency list and then one of these two condititions +must 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 MODULES + +comment "module support disabled" + depends !MODULES + +MODVERSIONS directly depends on MODULES, this means it's only visible if +MODULES is different from 'n'. The comment on the other hand is always +visible when MODULES it's visible (the (empty) dependency of MODULES is +also part of the comment dependencies). + + +Kconfig syntax +-------------- + +The configuration file describes a series of menu entries, where every +line starts with a keyword (except help texts). The following keywords +end a menu entry: +- config +- choice/endchoice +- comment +- menu/endmenu +- if/endif +- source +The first four also start the definition of a menu entry. + +config: + + "config" + + +This defines a config symbol and accepts any of above +attributes as options. + +choices: + + "choice" + + + "endchoice" + +This defines a choice group and accepts any of above attributes as +options. A choice can only be of type bool or tristate, while a boolean +choice only allows a single config entry to be selected, a tristate +choice also allows any number of config entries to be set to 'm'. This +can be used if multiple drivers for a single hardware exists and only a +single driver can be compiled/loaded into the kernel, but all drivers +can be compiled as modules. +A choice accepts another option "optional", which allows to set the +choice to 'n' and no entry needs to be selected. + +comment: + + "comment" + + +This defines a comment which is displayed to the user during the +configuration process and is also echoed to the output files. The only +possible options are dependencies. + +menu: + + "menu" + + + "endmenu" + +This defines a menu block, see "Menu structure" above for more +information. The only possible options are dependencies. + +if: + + "if" + + "endif" + +This defines an if block. The dependency expression is appended +to all enclosed menu entries. + +source: + + "source" + +This reads the specified configuration file. This file is always parsed. diff --git a/e2fsprogs/Config.src b/e2fsprogs/Config.src index a20d849e6..ad15f470c 100644 --- a/e2fsprogs/Config.src +++ b/e2fsprogs/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Linux Ext2 FS Progs" diff --git a/editors/Config.src b/editors/Config.src index 0920bc494..3b2e4a6c0 100644 --- a/editors/Config.src +++ b/editors/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Editors" diff --git a/findutils/Config.src b/findutils/Config.src index 9ee71a845..c28c5844e 100644 --- a/findutils/Config.src +++ b/findutils/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Finding Utilities" diff --git a/init/Config.src b/init/Config.src index 5767c93f0..b19b0bea1 100644 --- a/init/Config.src +++ b/init/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Init Utilities" diff --git a/klibc-utils/Config.src b/klibc-utils/Config.src index fe7cb1315..cf4552e51 100644 --- a/klibc-utils/Config.src +++ b/klibc-utils/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "klibc-utils" diff --git a/libbb/Config.src b/libbb/Config.src index 16e16480b..312aa1831 100644 --- a/libbb/Config.src +++ b/libbb/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # comment "Library Tuning" diff --git a/loginutils/Config.src b/loginutils/Config.src index 680f42118..cbb09646b 100644 --- a/loginutils/Config.src +++ b/loginutils/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Login/Password Management Utilities" diff --git a/miscutils/Config.src b/miscutils/Config.src index 7325fb8fa..d10b00b28 100644 --- a/miscutils/Config.src +++ b/miscutils/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Miscellaneous Utilities" diff --git a/modutils/Config.src b/modutils/Config.src index e413702bb..188296814 100644 --- a/modutils/Config.src +++ b/modutils/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Linux Module Utilities" diff --git a/networking/Config.src b/networking/Config.src index 492c60da4..2ce5287de 100644 --- a/networking/Config.src +++ b/networking/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Networking Utilities" diff --git a/networking/udhcp/Config.src b/networking/udhcp/Config.src index 50bff2e8c..e5958804b 100644 --- a/networking/udhcp/Config.src +++ b/networking/udhcp/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # config UDHCPD diff --git a/printutils/Config.src b/printutils/Config.src index e53b9d093..5f1d65f6c 100644 --- a/printutils/Config.src +++ b/printutils/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Print Utilities" diff --git a/procps/Config.src b/procps/Config.src index 515d79938..2b1b8ab11 100644 --- a/procps/Config.src +++ b/procps/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Process Utilities" diff --git a/runit/Config.src b/runit/Config.src index 8cde89680..403ec8724 100644 --- a/runit/Config.src +++ b/runit/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Runit Utilities" diff --git a/selinux/Config.src b/selinux/Config.src index 9cb755a0f..f8fcdadf9 100644 --- a/selinux/Config.src +++ b/selinux/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "SELinux Utilities" diff --git a/shell/Config.src b/shell/Config.src index 81c4ec874..959d3cb42 100644 --- a/shell/Config.src +++ b/shell/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Shells" diff --git a/sysklogd/Config.src b/sysklogd/Config.src index 684e7d414..321be0117 100644 --- a/sysklogd/Config.src +++ b/sysklogd/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "System Logging Utilities" diff --git a/util-linux/Config.src b/util-linux/Config.src index 68fcc266f..0fad3e5c0 100644 --- a/util-linux/Config.src +++ b/util-linux/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # menu "Linux System Utilities" diff --git a/util-linux/volume_id/Config.src b/util-linux/volume_id/Config.src index ac208c9cc..fe3b14a71 100644 --- a/util-linux/volume_id/Config.src +++ b/util-linux/volume_id/Config.src @@ -1,6 +1,6 @@ # # For a description of the syntax of this configuration file, -# see scripts/kbuild/config-language.txt. +# see docs/Kconfig-language.txt. # config VOLUMEID -- 2.25.1