1Config Language Specification 218 October 1999 3Michael Elizabeth Chastain, <mailto:mec@shout.net> 4 5 6 7=== Introduction 8 9Config Language is not 'bash'. 10 11This document describes Config Language, the Linux Kernel Configuration 12Language. config.in and Config.in files are written in this language. 13 14Although it looks, and usually acts, like a subset of the 'sh' language, 15Config Language has a restricted syntax and different semantics. 16 17Here is a basic guideline for Config Language programming: use only the 18programming idioms that you see in existing Config.in files. People often 19draw on their shell programming experience to invent idioms that look 20reasonable to shell programmers, but silently fail in Config Language. 21 22Config Language is not 'bash'. 23 24 25 26=== Interpreters 27 28Four different configuration programs read Config Language: 29 30 scripts/Configure make config, make oldconfig 31 scripts/Menuconfig make menuconfig 32 scripts/tkparse make xconfig 33 mconfig ftp.kernel.org/pub/linux/kernel/people/hch/mconfig/ 34 35'Configure' is a bash script which interprets Config.in files by sourcing 36them. Some of the Config Language commands are native bash commands; 37simple bash functions implement the rest of the commands. 38 39'Menuconfig' is another bash script. It scans the input files with a 40small awk script, builds a shell function for each menu, sources the 41shell functions that it builds, and then executes the shell functions 42in a user-driven order. Menuconfig uses 'lxdialog', a back-end utility 43program, to perform actual screen output. 'lxdialog' is a C program 44which uses curses. 45 46'scripts/tkparse' is a C program with an ad hoc parser which translates 47a Config Language script to a huge TCL/TK program. 'make xconfig' 48then hands this TCL/TK program to 'wish', which executes it. 49 50'mconfig' is the next generation of Config Language interpreters. It is a 51C program with a bison parser which translates a Config Language script 52into an internal syntax tree and then hands the syntax tree to one of 53several user-interface front ends. 54 55 56 57=== Statements 58 59A Config Language script is a list of statements. There are 21 simple 60statements; an 'if' statement; menu blocks; and a 'source' statement. 61 62A '\' at the end of a line marks a line continuation. 63 64'#' usually introduces a comment, which continues to the end of the line. 65Lines of the form '# ... is not set', however, are not comments. They 66are semantically meaningful, and all four config interpreters implement 67this meaning. 68 69Newlines are significant. You may not substitute semicolons for newlines. 70The 'if' statement does accept a semicolon in one position; you may use 71a newline in that position instead. 72 73Here are the basic grammar elements. 74 75 A /prompt/ is a single-quoted string or a double-quoted string. 76 If the word is double-quoted, it may not have any $ substitutions. 77 78 A /word/ is a single unquoted word, a single-quoted string, or a 79 double-quoted string. If the word is unquoted or double quoted, 80 then $-substitution will be performed on the word. 81 82 A /symbol/ is a single unquoted word. A symbol must have a name of 83 the form CONFIG_*. scripts/mkdep.c relies on this convention in order 84 to generate dependencies on individual CONFIG_* symbols instead of 85 making one massive dependency on include/linux/autoconf.h. 86 87 A /dep/ is a dependency. Syntactically, it is a /word/. At run 88 time, a /dep/ must evaluate to "y", "m", "n", or "". 89 90 An /expr/ is a bash-like expression using the operators 91 '=', '!=', '-a', '-o', and '!'. 92 93Here are all the statements: 94 95 Text statements: 96 97 mainmenu_name /prompt/ 98 comment /prompt/ 99 text /prompt/ 100 101 Ask statements: 102 103 bool /prompt/ /symbol/ 104 hex /prompt/ /symbol/ /word/ 105 int /prompt/ /symbol/ /word/ 106 string /prompt/ /symbol/ /word/ 107 tristate /prompt/ /symbol/ 108 109 Define statements: 110 111 define_bool /symbol/ /word/ 112 define_hex /symbol/ /word/ 113 define_int /symbol/ /word/ 114 define_string /symbol/ /word/ 115 define_tristate /symbol/ /word/ 116 117 Dependent statements: 118 119 dep_bool /prompt/ /symbol/ /dep/ ... 120 dep_mbool /prompt/ /symbol/ /dep/ ... 121 dep_hex /prompt/ /symbol/ /word/ /dep/ ... 122 dep_int /prompt/ /symbol/ /word/ /dep/ ... 123 dep_string /prompt/ /symbol/ /word/ /dep/ ... 124 dep_tristate /prompt/ /symbol/ /dep/ ... 125 126 Unset statement: 127 128 unset /symbol/ ... 129 130 Choice statements: 131 132 choice /prompt/ /word/ /word/ 133 nchoice /prompt/ /symbol/ /prompt/ /symbol/ ... 134 135 If statements: 136 137 if [ /expr/ ] ; then 138 /statement/ 139 ... 140 fi 141 142 if [ /expr/ ] ; then 143 /statement/ 144 ... 145 else 146 /statement/ 147 ... 148 fi 149 150 Menu block: 151 152 mainmenu_option next_comment 153 comment /prompt/ 154 /statement/ 155 ... 156 endmenu 157 158 Source statement: 159 160 source /word/ 161 162 163 164=== mainmenu_name /prompt/ 165 166This verb is a lot less important than it looks. It specifies the top-level 167name of this Config Language file. 168 169Configure: ignores this line 170Menuconfig: ignores this line 171Xconfig: uses /prompt/ for the label window. 172mconfig: ignores this line (mconfig does a better job without it). 173 174Example: 175 176 # arch/sparc/config.in 177 mainmenu_name "Linux/SPARC Kernel Configuration" 178 179 180 181=== comment /prompt/ 182 183This verb displays its prompt to the user during the configuration process 184and also echoes it to the output files during output. Note that the 185prompt, like all prompts, is a quoted string with no dollar substitution. 186 187The 'comment' verb is not a Config Language comment. It causes the 188user interface to display text, and it causes output to appear in the 189output files. 190 191Configure: implemented 192Menuconfig: implemented 193Xconfig: implemented 194mconfig: implemented 195 196Example: 197 198 # drivers/net/Config.in 199 comment 'CCP compressors for PPP are only built as modules.' 200 201 202 203=== text /prompt/ 204 205This verb displays the prompt to the user with no adornment whatsoever. 206It does not echo the prompt to the output file. mconfig uses this verb 207internally for its help facility. 208 209Configure: not implemented 210Menuconfig: not implemented 211Xconfig: not implemented 212mconfig: implemented 213 214Example: 215 216 # mconfig internal help text 217 text 'Here are all the mconfig command line options.' 218 219 220 221=== bool /prompt/ /symbol/ 222 223This verb displays /prompt/ to the user, accepts a value from the user, 224and assigns that value to /symbol/. The legal input values are "n" and 225"y". 226 227Note that the bool verb does not have a default value. People keep 228trying to write Config Language scripts with a default value for bool, 229but *all* of the existing language interpreters discard additional values. 230Feel free to submit a multi-interpreter patch to linux-kbuild if you 231want to implement this as an enhancement. 232 233Configure: implemented 234Menuconfig: implemented 235Xconfig: implemented 236mconfig: implemented 237 238Example: 239 240 # arch/i386/config.in 241 bool 'Symmetric multi-processing support' CONFIG_SMP 242 243 244 245=== hex /prompt/ /symbol/ /word/ 246 247This verb displays /prompt/ to the user, accepts a value from the user, 248and assigns that value to /symbol/. Any hexadecimal number is a legal 249input value. /word/ is the default value. 250 251The hex verb does not accept range parameters. 252 253Configure: implemented 254Menuconfig: implemented 255Xconfig: implemented 256mconfig: implemented 257 258Example: 259 260 # drivers/sound/Config.in 261 hex 'I/O base for SB Check from manual of the card' CONFIG_SB_BASE 220 262 263 264 265=== int /prompt/ /symbol/ /word/ 266 267This verb displays /prompt/ to the user, accepts a value from the user, 268and assigns that value to /symbol/. /word/ is the default value. 269Any decimal number is a legal input value. 270 271The int verb does not accept range parameters. 272 273Configure: implemented 274Menuconfig: implemented 275Xconfig: implemented 276mconfig: implemented 277 278Example: 279 280 # drivers/char/Config.in 281 int 'Maximum number of Unix98 PTYs in use (0-2048)' \ 282 CONFIG_UNIX98_PTY_COUNT 256 283 284 285 286=== string /prompt/ /symbol/ /word/ 287 288This verb displays /prompt/ to the user, accepts a value from the user, 289and assigns that value to /symbol/. /word/ is the default value. Legal 290input values are any ASCII string, except for the characters '"' and '\\'. 291Configure will trap an input string of "?" to display help. 292 293The default value is mandatory. 294 295Configure: implemented 296Menuconfig: implemented 297Xconfig: implemented 298mconfig: implemented 299 300Example: 301 302 # drivers/sound/Config.in 303 string ' Full pathname of DSPxxx.LD firmware file' \ 304 CONFIG_PSS_BOOT_FILE /etc/sound/dsp001.ld 305 306 307 308=== tristate /prompt/ /symbol/ 309 310This verb displays /prompt/ to the user, accepts a value from the user, 311and assigns that value to /symbol/. Legal values are "n", "m", or "y". 312 313The value "m" stands for "module"; it indicates that /symbol/ should 314be built as a kernel module. The value "m" is legal only if the symbol 315CONFIG_MODULES currently has the value "y". 316 317The tristate verb does not have a default value. 318 319Configure: implemented 320Menuconfig: implemented 321Xconfig: implemented 322mconfig: implemented 323 324Example: 325 326 # fs/Config.in 327 tristate 'NFS filesystem support' CONFIG_NFS_FS 328 329 330 331=== define_bool /symbol/ /word/ 332 333This verb the value of /word/ to /symbol/. Legal values are "n" or "y". 334 335For compatibility reasons, the value of "m" is also legal, because it 336will be a while before define_tristate is implemented everywhere. 337 338Configure: implemented 339Menuconfig: implemented 340Xconfig: implemented 341mconfig: implemented 342 343Example: 344 345 # arch/alpha/config.in 346 if [ "$CONFIG_ALPHA_GENERIC" = "y" ] 347 then 348 define_bool CONFIG_PCI y 349 define_bool CONFIG_ALPHA_NEED_ROUNDING_EMULATION y 350 fi 351 352 353 354=== define_hex /symbol/ /word/ 355 356This verb assigns the value of /word/ to /symbol/. Any hexadecimal 357number is a legal value. 358 359Configure: implemented 360Menuconfig: implemented 361Xconfig: implemented 362mconfig: implemented 363 364Example: 365 366 # Not from the corpus 367 bool 'Specify custom serial port' CONFIG_SERIAL_PORT_CUSTOM 368 if [ "$CONFIG_SERIAL_PORT_CUSTOM" = "y" ]; then 369 hex 'Serial port number' CONFIG_SERIAL_PORT 370 else 371 define_hex CONFIG_SERIAL_PORT 0x3F8 372 fi 373 374 375 376=== define_int /symbol/ /word/ 377 378This verb assigns /symbol/ the value /word/. Any decimal number is a 379legal value. 380 381Configure: implemented 382Menuconfig: implemented 383Xconfig: implemented 384mconfig: implemented 385 386Example: 387 388 # drivers/char/ftape/Config.in 389 define_int CONFIG_FT_ALPHA_CLOCK 0 390 391 392 393=== define_string /symbol/ /word/ 394 395This verb assigns the value of /word/ to /symbol/. Legal input values 396are any ASCII string, except for the characters '"' and '\\'. 397 398Configure: implemented 399Menuconfig: implemented 400Xconfig: implemented 401mconfig: implemented 402 403Example 404 405 # Not from the corpus 406 define_string CONFIG_VERSION "2.2.0" 407 408 409 410=== define_tristate /symbol/ /word/ 411 412This verb assigns the value of /word/ to /symbol/. Legal input values 413are "n", "m", and "y". 414 415As soon as this verb is implemented in all interpreters, please use it 416instead of define_bool to define tristate values. This aids in static 417type checking. 418 419Configure: implemented 420Menuconfig: implemented 421Xconfig: implemented 422mconfig: implemented 423 424Example: 425 426 # drivers/video/Config.in 427 if [ "$CONFIG_FB_AMIGA" = "y" ]; then 428 define_tristate CONFIG_FBCON_AFB y 429 define_tristate CONFIG_FBCON_ILBM y 430 else 431 if [ "$CONFIG_FB_AMIGA" = "m" ]; then 432 define_tristate CONFIG_FBCON_AFB m 433 define_tristate CONFIG_FBCON_ILBM m 434 fi 435 fi 436 437 438 439=== dep_bool /prompt/ /symbol/ /dep/ ... 440 441This verb evaluates all of the dependencies in the dependency list. 442Any dependency which has a value of "y" does not restrict the input 443range. Any dependency which has an empty value is ignored. 444Any dependency which has a value of "n", or which has some other value, 445(like "m") restricts the input range to "n". Quoting dependencies is not 446allowed. Using dependencies with an empty value possible is not 447recommended. See also dep_mbool below. 448 449If the input range is restricted to the single choice "n", dep_bool 450silently assigns "n" to /symbol/. If the input range has more than 451one choice, dep_bool displays /prompt/ to the user, accepts a value 452from the user, and assigns that value to /symbol/. 453 454Configure: implemented 455Menuconfig: implemented 456XConfig: implemented 457mconfig: implemented 458 459Example: 460 461 # drivers/net/Config.in 462 dep_bool 'Aironet 4500/4800 PCI support 'CONFIG_AIRONET4500_PCI $CONFIG_PCI 463 464Known bugs: 465- Xconfig does not write "# foo is not set" to .config (as well as 466 "#undef foo" to autoconf.h) if command is disabled by its dependencies. 467 468 469=== dep_mbool /prompt/ /symbol/ /dep/ ... 470 471This verb evaluates all of the dependencies in the dependency list. 472Any dependency which has a value of "y" or "m" does not restrict the 473input range. Any dependency which has an empty value is ignored. 474Any dependency which has a value of "n", or which has some other value, 475restricts the input range to "n". Quoting dependencies is not allowed. 476Using dependencies with an empty value possible is not recommended. 477 478If the input range is restricted to the single choice "n", dep_bool 479silently assigns "n" to /symbol/. If the input range has more than 480one choice, dep_bool displays /prompt/ to the user, accepts a value 481from the user, and assigns that value to /symbol/. 482 483Notice that the only difference between dep_bool and dep_mbool 484is in the way of treating the "m" value as a dependency. 485 486Configure: implemented 487Menuconfig: implemented 488XConfig: implemented 489mconfig: implemented 490 491Example: 492 493 # Not from the corpus 494 dep_mbool 'Packet socket: mmapped IO' CONFIG_PACKET_MMAP $CONFIG_PACKET 495 496Known bugs: 497- Xconfig does not write "# foo is not set" to .config (as well as 498 "#undef foo" to autoconf.h) if command is disabled by its dependencies. 499 500 501=== dep_hex /prompt/ /symbol/ /word/ /dep/ ... 502=== dep_int /prompt/ /symbol/ /word/ /dep/ ... 503=== dep_string /prompt/ /symbol/ /word/ /dep/ ... 504 505I am still thinking about the semantics of these verbs. 506 507Configure: not implemented 508Menuconfig: not implemented 509XConfig: not implemented 510mconfig: not implemented 511 512 513 514=== dep_tristate /prompt/ /symbol/ /dep/ ... 515 516This verb evaluates all of the dependencies in the dependency list. 517Any dependency which has a value of "y" does not restrict the input range. 518Any dependency which has a value of "m" restricts the input range to 519"m" or "n". Any dependency which has an empty value is ignored. 520Any dependency which has a value of "n", or which has some other value, 521restricts the input range to "n". Quoting dependencies is not allowed. 522Using dependencies with an empty value possible is not recommended. 523 524If the input range is restricted to the single choice "n", dep_tristate 525silently assigns "n" to /symbol/. If the input range has more than 526one choice, dep_tristate displays /prompt/ to the user, accepts a value 527from the user, and assigns that value to /symbol/. 528 529Configure: implemented 530Menuconfig: implemented 531Xconfig: implemented 532mconfig: implemented 533 534Example: 535 536 # drivers/char/Config.in 537 dep_tristate 'Parallel printer support' CONFIG_PRINTER $CONFIG_PARPORT 538 539Known bugs: 540- Xconfig does not write "# foo is not set" to .config (as well as 541 "#undef foo" to autoconf.h) if command is disabled by its dependencies. 542 543 544=== unset /symbol/ ... 545 546This verb assigns the value "" to /symbol/, but does not cause /symbol/ 547to appear in the output. The existence of this verb is a hack; it covers 548up deeper problems with variable semantics in a random-execution language. 549 550Configure: implemented 551Menuconfig: implemented 552Xconfig: implemented (with bugs) 553mconfig: implemented 554 555Example: 556 557 # arch/mips/config.in 558 unset CONFIG_PCI 559 unset CONFIG_MIPS_JAZZ 560 unset CONFIG_VIDEO_G364 561 562 563 564=== choice /prompt/ /word/ /word/ 565 566This verb implements a choice list or "radio button list" selection. 567It displays /prompt/ to the user, as well as a group of sub-prompts 568which have corresponding symbols. 569 570When the user selects a value, the choice verb sets the corresponding 571symbol to "y" and sets all the other symbols in the choice list to "n". 572 573The second argument is a single-quoted or double-quoted word that 574describes a series of sub-prompts and symbol names. The interpreter 575breaks up the word at white space boundaries into a list of sub-words. 576The first sub-word is the first prompt; the second sub-word is the 577first symbol. The third sub-word is the second prompt; the fourth 578sub-word is the second symbol. And so on, for all the sub-words. 579 580The third word is a literal word. Its value must be a unique abbreviation 581for exactly one of the prompts. The symbol corresponding to this prompt 582is the default enabled symbol. 583 584Note that because of the syntax of the choice verb, the sub-prompts 585may not have spaces in them. 586 587Configure: implemented 588Menuconfig: implemented 589Xconfig: implemented 590mconfig: implemented 591 592Example: 593 594 # arch/i386/config.in 595 choice ' PCI access mode' \ 596 "BIOS CONFIG_PCI_GOBIOS \ 597 Direct CONFIG_PCI_GODIRECT \ 598 Any CONFIG_PCI_GOANY" Any 599 600 601 602=== nchoice /prompt/ /symbol/ /prompt/ /symbol/ ... 603 604This verb has the same semantics as the choice verb, but with a sensible 605syntax. 606 607The first /prompt/ is the master prompt for the entire choice list. 608 609The first /symbol/ is the default symbol to enable (notice that this 610is a symbol, not a unique prompt abbreviation). 611 612The subsequent /prompt/ and /symbol/ pairs are the prompts and symbols 613for the choice list. 614 615Configure: not implemented 616Menuconfig: not implemented 617XConfig: not implemented 618mconfig: implemented 619 620 621 622=== if [ /expr/ ] ; then 623 624This is a conditional statement, with an optional 'else' clause. You may 625substitute a newline for the semicolon if you choose. 626 627/expr/ may contain the following atoms and operators. Note that, unlike 628shell, you must use double quotes around every atom. 629 630 /atom/: 631 "..." a literal 632 "$..." a variable 633 634 /expr/: 635 /atom/ = /atom/ true if atoms have identical value 636 /atom/ != /atom/ true if atoms have different value 637 638 /expr/: 639 /expr/ -o /expr/ true if either expression is true 640 /expr/ -a /expr/ true if both expressions are true 641 ! /expr/ true if expression is not true 642 643Note that a naked /atom/ is not a valid /expr/. If you try to use it 644as such: 645 646 # Do not do this. 647 if [ "$CONFIG_EXPERIMENTAL" ]; then 648 bool 'Bogus experimental feature' CONFIG_BOGUS 649 fi 650 651... then you will be surprised, because CONFIG_EXPERIMENTAL never has a 652value of the empty string! It is always "y" or "n", and both of these 653are treated as true (non-empty) by the bash-based interpreters Configure 654and Menuconfig. 655 656Configure: implemented 657Menuconfig: implemented 658XConfig: implemented, with bugs 659mconfig: implemented 660 661Xconfig has some known bugs, and probably some unknown bugs too: 662 663- literals with an empty "" value are not properly handled. 664 665 666 667=== mainmenu_option next_comment 668 669This verb introduces a new menu. The next statement must have a comment 670verb. The /prompt/ of that comment verb becomes the title of the menu. 671(I have no idea why the original designer didn't create a 'menu ...' verb). 672 673Statements outside the scope of any menu are in the implicit top menu. 674The title of the top menu comes from a variety of sources, depending on 675the interpreter. 676 677Configure: implemented 678Menuconfig: implemented 679Xconfig: implemented 680mconfig: implemented 681 682 683 684=== endmenu 685 686This verb closes the scope of a menu. 687 688Configure: implemented 689Menuconfig: implemented 690Xconfig: implemented 691mconfig: implemented 692 693 694 695=== source /word/ 696 697This verb interprets the literal /word/ as a filename, and interpolates 698the contents of that file. The word must be a single unquoted literal 699word. 700 701Some interpreters interpret this verb at run time; some interpreters 702interpret it at parse time. 703 704Inclusion is textual inclusion, like the C preprocessor #include facility. 705The source verb does not imply a submenu or any kind of block nesting. 706 707Configure: implemented (run time) 708Menuconfig: implemented (parse time) 709Xconfig: implemented (parse time) 710mconfig: implemented (parse time) 711