patch-2.2.2 linux/Documentation/kbuild/config-language.txt

Next file: linux/Documentation/proc.txt
Previous file: linux/Documentation/kbuild/commands.txt
Back to the patch index
Back to the overall index

diff -u --recursive --new-file v2.2.1/linux/Documentation/kbuild/config-language.txt linux/Documentation/kbuild/config-language.txt
@@ -0,0 +1,630 @@
+Config Language Specification
+21 January 1999
+Michael Elizabeth Chastain, <mailto:mec@shout.net>
+
+
+
+=== Introduction
+
+Config Language is not 'bash'.
+
+This document describes Config Language, the Linux Kernel Configuration
+Language.  config.in and Config.in files are written in this language.
+
+Although it looks, and usually acts, like a subset of the 'sh' language,
+Config Language has a restricted syntax and different semantics.
+
+Here is a basic guideline for Config Language programming: use only the
+programming idioms that you see in existing Config.in files.  People often
+draw on their shell programming experience to invent idioms that look
+reasonable to shell programmers, but silently fail in Config Language.
+
+Config Language is not 'bash'.
+
+
+
+=== Interpreters
+
+Four different configuration programs read Config Language:
+
+    scripts/Configure   make config, make oldconfig
+    scripts/Menuconfig  make menuconfig
+    scripts/tkparse     make xconfig
+    mconfig             (in development)
+
+'Configure' is a bash script which interprets Config.in files by sourcing
+them.  Some of the Config Language commands are native bash commands;
+simple bash functions implement the rest of the commands.
+
+'Menuconfig' is another bash script.  It scans the input files with a
+small awk script, builds a shell function for each menu, sources the
+shell functions that it builds, and then executes the shell functions
+in a user-driven order.  Menuconfig uses 'lxdialog', a back-end utility
+program, to perform actual screen output.  'lxdialog' is a C program
+which uses curses.
+
+'scripts/tkparse' is a C program with an ad hoc parser which translates
+a Config Language script to a huge TCL/TK program.  'make xconfig'
+then hands this TCL/TK program to 'wish', which executes it.
+
+'mconfig' is the next generation of Config Language interpreters.  It is a
+C program with a bison parser which translates a Config Language script
+into an internal syntax tree and then hands the syntax tree to one of
+several user-interface front ends.
+
+This document describes the behaviour of all four interpreters, even though
+mconfig has not been released at the time of writing.
+
+
+
+=== Statements
+
+A Config Language script is a list of statements.  There are 21 simple
+statements; an 'if' statement; menu blocks; and a 'source' statement.
+
+A '\' at the end of a line marks a line continuation.
+
+'#' usually introduces a comment, which continues to the end of the line.
+Lines of the form '# ... is not set', however, are not comments.  They
+are semantically meaningful, and all four config interpreters implement
+this meaning.
+
+Newlines are significant.  You may not substitute semicolons for newlines.
+The 'if' statement does accept a semicolon in one position; you may use
+a newline in that position instead.
+
+Here are the basic grammar elements.
+
+    A /prompt/ is a single-quoted string or a double-quoted string.
+    If the word is double-quoted, it may not have any $ substitutions.
+
+    A /word/ is a single unquoted word, a single-quoted string, or a
+    double-quoted string.  If the word is unquoted or double quoted,
+    then $-substition will be performed on the word.
+
+    A /symbol/ is a single unquoted word.
+
+    A /dep/ is a dependency.  Syntactically, it is a /word/.  At run
+    time, a /dep/ must evaluate to "y", "m", "n", or "".
+
+    An /expr/ is a bash-like expression using the operators
+    '=', '!=', '-a', '-o', and '!'.
+
+Here are all the statements:
+
+    Text statements:
+
+        mainmenu_name   /prompt/
+        comment         /prompt/
+        text            /prompt/
+
+    Ask statements:
+
+        bool            /prompt/ /symbol/
+        hex             /prompt/ /symbol/ /word/
+        int             /prompt/ /symbol/ /word/
+        string          /prompt/ /symbol/ /word/
+        tristate        /prompt/ /symbol/
+
+    Define statements:
+
+        define_bool     /symbol/ /word/
+        define_hex      /symbol/ /word/
+        define_int      /symbol/ /word/
+        define_string   /symbol/ /word/
+        define_tristate /symbol/ /word/
+
+    Dependent statements:
+
+        dep_bool        /prompt/ /symbol/ /dep/ ...
+        dep_hex         /prompt/ /symbol/ /word/ /dep/ ...
+        dep_int         /prompt/ /symbol/ /word/ /dep/ ...
+        dep_string      /prompt/ /symbol/ /word/ /dep/ ...
+        dep_tristate    /prompt/ /symbol/ /dep/ ...
+
+    Unset statement:
+
+        unset /symbol/ ...
+
+    Choice statements:
+
+        choice          /prompt/ /word/ /word/
+        nchoice         /prompt/ /symbol/ /prompt/ /symbol/ ...
+
+    If statements:
+
+        if [ /expr/ ] ; then
+	  /statement/
+	  ...
+        fi
+
+        if [ /expr/ ] ; then
+	  /statement/
+	  ...
+        else
+	  /statement/
+	  ...
+        fi
+
+    Menu block:
+
+        mainmenu_option next_comment
+        comment /prompt/
+          /statement/
+	  ...
+        endmenu
+
+    Source statement:
+
+        source /word/
+
+
+
+=== mainmenu_name /prompt/
+
+This verb is a lot less important than it looks.  It specifies the top-level
+name of this Config Language file.
+
+Configure:  ignores this line
+Menuconfig: ignores this line
+Xconfig:    uses /prompt/ for the label window.
+mconfig:    ignores this line (mconfig does a better job without it).
+
+Example:
+
+    # arch/sparc/config.in
+    mainmenu_name "Linux/SPARC Kernel Configuration"
+
+
+
+=== comment /prompt/
+
+This verb displays its prompt to the user during the configuration process
+and also echoes it to the output files during output.  Note that the
+prompt, like all prompts, is a quoted string with no dollar substitution.
+
+The 'comment' verb is not a Config Language comment.  It causes the
+user interface to display text, and it causes output to appear in the
+output files.
+
+Configure:  implemented
+Menuconfig: implemented
+Xconfig:    does not display, but writes to output files
+mconfig:    implemented
+
+Example:
+
+    # drivers/net/Config.in
+    comment 'CCP compressors for PPP are only built as modules.'
+
+
+
+=== text /prompt/
+
+This verb displays the prompt to the user with no adornment whatsoever.
+It does not echo the prompt to the output file.  mconfig uses this verb
+internally for its help facility.
+
+Configure:  not implemented
+Menuconfig: not implemented
+Xconfig:    not implemented
+mconfig:    implemented
+
+Example:
+
+    # mconfig internal help text
+    text 'Here are all the mconfig command line options.'
+
+
+
+=== bool /prompt/ /symbol/
+
+This verb displays /prompt/ to the user, accepts a value from the user,
+and assigns that value to /symbol/.  The legal input values are "n" and
+"y".
+
+Note that the bool verb does not have a default value.  People keep
+trying to write Config Language scripts with a default value for bool,
+but *all* of the existing language interpreters discard additional values.
+Feel free to submit a multi-interpreter patch to linux-kbuild if you
+want to implement this as an enhancment.
+
+Configure:  implemented
+Menuconfig: implemented
+Xconfig:    implemented
+mconfig:    implemented
+
+Example:
+
+    # arch/i386/config.in
+    bool 'Symmetric multi-processing support' CONFIG_SMP
+
+
+
+=== hex /prompt/ /symbol/ /word/
+
+This verb displays /prompt/ to the user, accepts a value from the user,
+and assigns that value to /symbol/.  Any hexadecimal number is a legal
+input value.  /word/ is the default value.
+
+The hex verb does not accept range parameters.
+
+Configure:  implemented
+Menuconfig: implemented
+Xconfig:    implemented
+mconfig:    implemented
+
+Example:
+
+    # drivers/sound/Config.in
+    hex 'I/O base for SB Check from manual of the card' CONFIG_SB_BASE 220
+
+
+
+=== int /prompt/ /symbol/ /word/
+
+This verb displays /prompt/ to the user, accepts a value from the user,
+and assigns that value to /symbol/.  /word/ is the default value.
+Any decimal number is a legal input value.
+
+The int verb does not accept range parameters.
+
+Configure:  implemented
+Menuconfig: implemented
+Xconfig:    implemented
+mconfig:    implemented
+
+Example:
+
+    # drivers/char/Config.in
+    int 'Maximum number of Unix98 PTYs in use (0-2048)' \
+        CONFIG_UNIX98_PTY_COUNT 256
+
+
+
+=== string /prompt/ /symbol/ /word/
+
+This verb displays /prompt/ to the user, accepts a value from the user,
+and assigns that value to /symbol/.  /word/ is the default value.  Legal
+input values are any ASCII string, except for the characters '"' and '\\'.
+
+The default value is mandatory.
+
+Configure:  implemented
+Menuconfig: implemented
+Xconfig:    implemented
+mconfig:    implemented
+
+Example:
+
+    # drivers/sound/Config.in
+    string '  Full pathname of DSPxxx.LD firmware file' \
+        CONFIG_PSS_BOOT_FILE /etc/sound/dsp001.ld
+
+
+
+=== tristate /prompt/ /symbol/
+
+This verb displays /prompt/ to the user, accepts a value from the user,
+and assigns that value to /symbol/.  Legal values are "n", "m", or "y".
+
+The value "m" stands for "module"; it indicates that /symbol/ should
+be built as a kernel module.  The value "m" is legal only if the symbol
+CONFIG_MODULES currently has the value "y".
+
+The tristate verb does not have a default value.
+
+Configure:  implemented
+Menuconfig: implemented
+Xconfig:    implemented
+mconfig:    implemented
+
+Example:
+
+    # fs/Config.in
+    tristate 'NFS filesystem support' CONFIG_NFS_FS
+
+
+
+=== define_bool /symbol/ /word/
+
+This verb the value of /word/ to /symbol/.  Legal values are "n" or "y".
+
+For compatibility reasons, the value of "m" is also legal, because it
+will be a while before define_tristate is implemented everywhere.
+
+Configure:  implemented
+Menuconfig: implemented
+Xconfig:    implemented
+mconfig:    implemented
+
+Example:
+
+    # arch/alpha/config.in
+    if [ "$CONFIG_ALPHA_GENERIC" = "y" ]
+    then
+            define_bool CONFIG_PCI y
+            define_bool CONFIG_ALPHA_NEED_ROUNDING_EMULATION y
+    fi
+
+
+
+=== define_hex /symbol/ /word/
+
+This verb assigns the value of /word/ to /symbol/.  Any hexadecimal
+number is a legal value.
+
+Configure:  implemented
+Menuconfig: not implemented
+Xconfig:    not implemented
+mconfig:    implemented
+
+Example:
+
+    # Not from the corpus
+    bool 'Specify custom serial port' CONFIG_SERIAL_PORT_CUSTOM
+    if [ "$CONFIG_SERIAL_PORT_CUSTOM" = "y" ]; then
+	hex 'Serial port number' CONFIG_SERIAL_PORT
+    else
+	define_hex CONFIG_SERIAL_PORT 0x3F8
+    fi
+
+
+
+=== define_int /symbol/ /word/
+
+This verb assigns /symbol/ the value /word/.  Any decimal number is a
+legal value.
+
+Configure:  implemented
+Menuconfig: not implemented
+Xconfig:    not implemented
+mconfig:    implemented
+
+Example:
+
+    # Not from the corpus
+    define_int CONFIG_UID_TORVALDS 2026
+
+
+
+=== define_string /symbol/ /word/
+
+This verb assigns the value of /word/ to /symbol/.  Legal input values
+are any ASCII string, except for the characters '"' and '\\'.
+
+Configure:  implemented
+Menuconfig: not implemented
+Xconfig:    not implemented
+mconfig:    implemented
+
+Example
+
+    # Not from the corpus
+    define_string CONFIG_VERSION "2.2.0"
+
+
+
+=== define_tristate /symbol/ /word/
+
+This verb assigns the value of /word/ to /symbol/.  Legal input values
+are "n", "m", and "y".
+
+As soon as this verb is implemented in all interpreters, please use it
+instead of define_bool to define tristate values.  This aids in static
+type checking.
+
+Configure:  not implemented
+Menuconfig: not implemented
+Xconfig:    not implemented
+mconfig:    implemented
+
+Example:
+
+    # not from the corpus
+    if [ "$CONFIG_ZFTAPE" != "n" ]; then
+      comment 'The compressor will be built as a module only!'
+      define_tristate CONFIG_ZFT_COMPRESSOR m
+    fi
+
+
+
+=== dep_bool /prompt/ /symbol/ /dep/ ...
+
+This verb evaluates all of the dependencies in the dependency list.
+Any dependency which has a value of "y" does not restrict the input
+range.  Any dependency which has a value of "n", or which has some
+other value, restricts the input range to "n".
+
+If the input range is restricted to the single choice "n", dep_bool
+silently assigns "n" to /symbol/.  If the input range has more than
+one choice, dep_bool displays /prompt/ to the user, accepts a value
+from the user, and assigns that value to /symbol/.
+
+Configure:  not implemented
+Menuconfig: not implemented
+XConfig:    not implemented
+mconfig:    implemented
+
+    # not from the corpus
+    dep_bool 'RZ1000 chipset bugfix/support' CONFIG_BLK_DEV_RZ1000 $CONFIG_PCI
+
+
+
+=== dep_hex /prompt/ /symbol/ /word/ /dep/ ...
+=== dep_int /prompt/ /symbol/ /word/ /dep/ ...
+=== dep_string /prompt/ /symbol/ /word/ /dep/ ...
+
+I am still thinking about the semantics of these verbs.
+
+Configure:  not implemented
+Menuconfig: not implemented
+XConfig:    not implemented
+mconfig:    not implemented
+
+
+
+=== dep_tristate /prompt/ /symbol /dep/ ...
+
+This verb evaluates all of the dependencies in the dependency list.
+Any dependency which as a value of "y" does not restrict the input range.
+Any dependency which has a value of "m" restricts the input range to
+"m" or "n".  Any dependency which has a value of "n", or which has some
+other value, restricts the input range to "n".
+
+If the input range is restricted to the single choice "n", dep_tristate
+silently assigns "n" to /symbol/.  If the input range has more than
+one choice, dep_tristate displays /prompt/ to the user, accepts a value
+from the user, and assigns that value to /symbol/.
+
+Configure:  implemented
+Menuconfig: implemented (but silently ignores dependencies after the first)
+Xconfig:    implemented (but silently ignores dependencies after the first)
+mconfig:    implemented
+
+
+
+=== unset /symbol/ ...
+
+This verb assigns the value "" to /symbol/, but does not cause /symbol/
+to appear in the output.  The existence of this verb is a hack; it covers
+up deeper problems with variable semantics in a random-execution language.
+
+Configure:  implemented
+Menuconfig: implemented
+Xconfig:    not implemented
+mconfig:    implemented
+
+
+
+=== choice /prompt/ /word/ /word/
+
+This verb implements a choice list or "radio button list" selection.
+It displays /prompt/ to the user, as well as a group of sub-prompts
+which have corresponding symbols.
+
+When the user selects a value, the choice verb sets the corresponding
+symbol to "y" and sets all the other symbols in the choice list to "n".
+
+The second argument is a single-quoted or double-quoted word that
+describes a series of sub-prompts and symbol names.  The interpreter
+breaks up the word at white space boundaries into a list of sub-words.
+The first sub-word is the first prompt; the second sub-word is the
+first symbol.  The third sub-word is the second prompt; the fourth
+sub-word is the second symbol.  And so on, for all the sub-words.
+
+The third word is a literal word.  Its value must be a unique abbreviation
+for exactly one of the prompts.  The symbol corresponding to this prompt
+is the default enabled symbol.
+
+Note that because of the syntax of the choice verb, the sub-prompts
+may not have spaces in them.
+
+Configure:  implemented
+Menuconfig: implemented
+Xconfig:    implemented
+mconfig:    implemented
+
+
+
+=== nchoice /prompt/ /symbol/ /prompt/ /symbol/ ...
+
+This verb has the same semantics as the choice verb, but with a sensible
+syntax.
+
+The first /prompt/ is the master prompt for the entire choice list.
+
+The first /symbol/ is the default symbol to enable (notice that this
+is a symbol, not a unique prompt abbreviation).
+
+The subsequent /prompt/ and /symbol/ pairs are the prompts and symbols
+for the choice list.
+
+Configure:  not implemented
+Menuconfig: not implemented
+XConfig:    not implemented
+mconfig:    implemented
+
+
+
+=== if [ /expr/ ] ; then
+
+This is a conditional statement, with an optional 'else' clause.  You may
+substitute a newline for the semicolon if you choose.
+
+/expr/ may contain the following atoms and operators.  Note that, unlike
+shell, you must use double quotes around every atom.
+
+    "..."		a literal
+    "$..."		a variable
+
+    /atom/  = /atom/	true if atoms have identical value
+    /atom/ != /atom/	true if atoms have different value
+
+    /expr/ -o /expr/	true if either expression is true
+    /expr/ -a /expr/	true if both expressions are true
+    ! /expr/		true if expression is not true
+
+Configure:  implemented
+Menuconfig: implemented
+XConfig:    implemented, with bugs
+mconfig:    implemented
+
+Xconfig has several known bugs, and probably some unknown bugs too:
+
+- In a comparison, if the left-hand atom is a variable and that variable
+  is from a choice list, the right-hand atom must be "y".
+
+- In a comparison, if the right-hand atom is a variable and that variable
+  is from a choice list, you lose.  tkparse will throw a segmentation
+  violation, silently generate bizarre TCL code, or something else.
+
+- tkparse gives the wrong precedence to -o, -a, and !.  Don't use both
+  -o and -a in an expression.  Don't use ! at all.
+
+
+
+=== mainmenu_option next_comment
+
+This verb introduces a new menu.  The next statement must have a comment
+verb.  The /prompt/ of that comment verb becomes the title of the menu.
+(I have no idea why the original designer didn't create a 'menu ...' verb).
+
+Statements outside the scope of any menu are in the implicit top menu.
+The title of the top menu comes from a variety of sources, depending on
+the interpreter.
+
+Configure:  implemented
+Menuconfig: implemented
+Xconfig:    implemented
+mconfig:    implemented
+
+
+
+=== endmenu
+
+This verb closes the scope of a menu.
+
+Configure:  implemented
+Menuconfig: implemented
+Xconfig:    implemented
+mconfig:    implemented
+
+
+
+=== source /word/
+
+This verb interprets the literal /word/ as a filename, and interpolates
+the contents of that file.  The word must be a single unquoted literal
+word.
+
+Some interpreters interpret this verb at run time; some interpreters
+interpret it at parse time.
+
+Inclusion is textual inclusion, like the C preprocessor #include facility.
+The source verb does not imply a submenu or any kind of block nesting.
+
+Configure:  implemented (run time)
+Menuconfig: implemented (parse time)
+Xconfig:    implemented (parse time)
+mconfig:    implemented (parse time)
FUNET's LINUX-ADM group, linux-adm@nic.funet.fi
TCL-scripts by Sam Shen (who was at: slshen@lbl.gov)