[PATCH] restore documentation on the build config language

Denys Vlasenko vda.linux at googlemail.com
Tue Jun 5 16:03:45 UTC 2018


Applied, thanks!

On Fri, Jun 1, 2018 at 7:15 AM, Kartik Agaram <akkartik at gmail.com> wrote:
> 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.
> ---
>  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 51ff01e..ae21f52 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 4499145..6f4f30c 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 e6587ad..c30caf0 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 7a8a3a6..1bded03 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 61daeb0..17b0d89 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 0000000..9b90bc3
> --- /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" <prompt> ["if" <expr>]
> +  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" <symbol> ["if" <expr>]
> +  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" <expr>
> +  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:
> +
> +<expr> ::= <symbol>                             (1)
> +           <symbol> '=' <symbol>                (2)
> +           <symbol> '!=' <symbol>               (3)
> +           '(' <expr> ')'                       (4)
> +           '!' <expr>                           (5)
> +           <expr> '||' <expr>                   (6)
> +           <expr> '&&' <expr>                   (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" <symbol>
> +    <config options>
> +
> +This defines a config symbol <symbol> and accepts any of above
> +attributes as options.
> +
> +choices:
> +
> +    "choice"
> +    <choice options>
> +    <choice block>
> +    "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" <prompt>
> +    <comment options>
> +
> +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" <prompt>
> +    <menu options>
> +    <menu block>
> +    "endmenu"
> +
> +This defines a menu block, see "Menu structure" above for more
> +information. The only possible options are dependencies.
> +
> +if:
> +
> +    "if" <expr>
> +    <if block>
> +    "endif"
> +
> +This defines an if block. The dependency expression <expr> is appended
> +to all enclosed menu entries.
> +
> +source:
> +
> +    "source" <prompt>
> +
> +This reads the specified configuration file. This file is always parsed.
> diff --git a/e2fsprogs/Config.src b/e2fsprogs/Config.src
> index a20d849..ad15f47 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 0920bc4..3b2e4a6 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 9ee71a8..c28c584 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 5767c93..b19b0be 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 fe7cb13..cf4552e 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 16e1648..312aa18 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 680f421..cbb0964 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 7325fb8..d10b00b 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 e413702..1882968 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 492c60d..2ce5287 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 50bff2e..e595880 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 e53b9d0..5f1d65f 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 515d799..2b1b8ab 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 8cde896..403ec87 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 9cb755a..f8fcdad 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 81c4ec8..959d3cb 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 684e7d4..321be01 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 68fcc26..0fad3e5 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 ac208c9..fe3b14a 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.7.4
> _______________________________________________
> busybox mailing list
> busybox at busybox.net
> http://lists.busybox.net/mailman/listinfo/busybox


More information about the busybox mailing list