Documentation/kbuild/config-language.txt

   1 Config Language Specification
   2 18 October 1999
   3 Michael Elizabeth Chastain, <mailto:mec@shout.net>
   4
   5
   6
   7 === Introduction
   8
   9 Config Language is not 'bash'.
  10
  11 This document describes Config Language, the Linux Kernel Configuration
  12 Language.  config.in and Config.in files are written in this language.
  13
  14 Although it looks, and usually acts, like a subset of the 'sh' language,
  15 Config Language has a restricted syntax and different semantics.
  16
  17 Here is a basic guideline for Config Language programming: use only the
  18 programming idioms that you see in existing Config.in files.  People often
  19 draw on their shell programming experience to invent idioms that look
  20 reasonable to shell programmers, but silently fail in Config Language.
  21
  22 Config Language is not 'bash'.
  23
  24
  25
  26 === Interpreters
  27
  28 Four 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
  36 them.  Some of the Config Language commands are native bash commands;
  37 simple bash functions implement the rest of the commands.
  38
  39 'Menuconfig' is another bash script.  It scans the input files with a
  40 small awk script, builds a shell function for each menu, sources the
  41 shell functions that it builds, and then executes the shell functions
  42 in a user-driven order.  Menuconfig uses 'lxdialog', a back-end utility
  43 program, to perform actual screen output.  'lxdialog' is a C program
  44 which uses curses.
  45
  46 'scripts/tkparse' is a C program with an ad hoc parser which translates
  47 a Config Language script to a huge TCL/TK program.  'make xconfig'
  48 then hands this TCL/TK program to 'wish', which executes it.
  49
  50 'mconfig' is the next generation of Config Language interpreters.  It is a
  51 C program with a bison parser which translates a Config Language script
  52 into an internal syntax tree and then hands the syntax tree to one of
  53 several user-interface front ends.
  54
  55
  56
  57 === Statements
  58
  59 A Config Language script is a list of statements.  There are 21 simple
  60 statements; an 'if' statement; menu blocks; and a 'source' statement.
  61
  62 A '\' at the end of a line marks a line continuation.
  63
  64 '#' usually introduces a comment, which continues to the end of the line.
  65 Lines of the form '# ... is not set', however, are not comments.  They
  66 are semantically meaningful, and all four config interpreters implement
  67 this meaning.
  68
  69 Newlines are significant.  You may not substitute semicolons for newlines.
  70 The 'if' statement does accept a semicolon in one position; you may use
  71 a newline in that position instead.
  72
  73 Here 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
  93 Here 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
 166 This verb is a lot less important than it looks.  It specifies the top-level
 167 name of this Config Language file.
 168
 169 Configure:  ignores this line
 170 Menuconfig: ignores this line
 171 Xconfig:    uses /prompt/ for the label window.
 172 mconfig:    ignores this line (mconfig does a better job without it).
 173
 174 Example:
 175
 176     # arch/sparc/config.in
 177     mainmenu_name "Linux/SPARC Kernel Configuration"
 178
 179
 180
 181 === comment /prompt/
 182
 183 This verb displays its prompt to the user during the configuration process
 184 and also echoes it to the output files during output.  Note that the
 185 prompt, like all prompts, is a quoted string with no dollar substitution.
 186
 187 The 'comment' verb is not a Config Language comment.  It causes the
 188 user interface to display text, and it causes output to appear in the
 189 output files.
 190
 191 Configure:  implemented
 192 Menuconfig: implemented
 193 Xconfig:    implemented
 194 mconfig:    implemented
 195
 196 Example:
 197
 198     # drivers/net/Config.in
 199     comment 'CCP compressors for PPP are only built as modules.'
 200
 201
 202
 203 === text /prompt/
 204
 205 This verb displays the prompt to the user with no adornment whatsoever.
 206 It does not echo the prompt to the output file.  mconfig uses this verb
 207 internally for its help facility.
 208
 209 Configure:  not implemented
 210 Menuconfig: not implemented
 211 Xconfig:    not implemented
 212 mconfig:    implemented
 213
 214 Example:
 215
 216     # mconfig internal help text
 217     text 'Here are all the mconfig command line options.'
 218
 219
 220
 221 === bool /prompt/ /symbol/
 222
 223 This verb displays /prompt/ to the user, accepts a value from the user,
 224 and assigns that value to /symbol/.  The legal input values are "n" and
 225 "y".
 226
 227 Note that the bool verb does not have a default value.  People keep
 228 trying to write Config Language scripts with a default value for bool,
 229 but *all* of the existing language interpreters discard additional values.
 230 Feel free to submit a multi-interpreter patch to linux-kbuild if you
 231 want to implement this as an enhancement.
 232
 233 Configure:  implemented
 234 Menuconfig: implemented
 235 Xconfig:    implemented
 236 mconfig:    implemented
 237
 238 Example:
 239
 240     # arch/i386/config.in
 241     bool 'Symmetric multi-processing support' CONFIG_SMP
 242
 243
 244
 245 === hex /prompt/ /symbol/ /word/
 246
 247 This verb displays /prompt/ to the user, accepts a value from the user,
 248 and assigns that value to /symbol/.  Any hexadecimal number is a legal
 249 input value.  /word/ is the default value.
 250
 251 The hex verb does not accept range parameters.
 252
 253 Configure:  implemented
 254 Menuconfig: implemented
 255 Xconfig:    implemented
 256 mconfig:    implemented
 257
 258 Example:
 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
 267 This verb displays /prompt/ to the user, accepts a value from the user,
 268 and assigns that value to /symbol/.  /word/ is the default value.
 269 Any decimal number is a legal input value.
 270
 271 The int verb does not accept range parameters.
 272
 273 Configure:  implemented
 274 Menuconfig: implemented
 275 Xconfig:    implemented
 276 mconfig:    implemented
 277
 278 Example:
 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
 288 This verb displays /prompt/ to the user, accepts a value from the user,
 289 and assigns that value to /symbol/.  /word/ is the default value.  Legal
 290 input values are any ASCII string, except for the characters '"' and '\\'.
 291 Configure will trap an input string of "?" to display help.
 292
 293 The default value is mandatory.
 294
 295 Configure:  implemented
 296 Menuconfig: implemented
 297 Xconfig:    implemented
 298 mconfig:    implemented
 299
 300 Example:
 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
 310 This verb displays /prompt/ to the user, accepts a value from the user,
 311 and assigns that value to /symbol/.  Legal values are "n", "m", or "y".
 312
 313 The value "m" stands for "module"; it indicates that /symbol/ should
 314 be built as a kernel module.  The value "m" is legal only if the symbol
 315 CONFIG_MODULES currently has the value "y".
 316
 317 The tristate verb does not have a default value.
 318
 319 Configure:  implemented
 320 Menuconfig: implemented
 321 Xconfig:    implemented
 322 mconfig:    implemented
 323
 324 Example:
 325
 326     # fs/Config.in
 327     tristate 'NFS filesystem support' CONFIG_NFS_FS
 328
 329
 330
 331 === define_bool /symbol/ /word/
 332
 333 This verb the value of /word/ to /symbol/.  Legal values are "n" or "y".
 334
 335 For compatibility reasons, the value of "m" is also legal, because it
 336 will be a while before define_tristate is implemented everywhere.
 337
 338 Configure:  implemented
 339 Menuconfig: implemented
 340 Xconfig:    implemented
 341 mconfig:    implemented
 342
 343 Example:
 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
 356 This verb assigns the value of /word/ to /symbol/.  Any hexadecimal
 357 number is a legal value.
 358
 359 Configure:  implemented
 360 Menuconfig: implemented
 361 Xconfig:    implemented
 362 mconfig:    implemented
 363
 364 Example:
 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
 378 This verb assigns /symbol/ the value /word/.  Any decimal number is a
 379 legal value.
 380
 381 Configure:  implemented
 382 Menuconfig: implemented
 383 Xconfig:    implemented
 384 mconfig:    implemented
 385
 386 Example:
 387
 388     # drivers/char/ftape/Config.in
 389     define_int CONFIG_FT_ALPHA_CLOCK 0
 390
 391
 392
 393 === define_string /symbol/ /word/
 394
 395 This verb assigns the value of /word/ to /symbol/.  Legal input values
 396 are any ASCII string, except for the characters '"' and '\\'.
 397
 398 Configure:  implemented
 399 Menuconfig: implemented
 400 Xconfig:    implemented
 401 mconfig:    implemented
 402
 403 Example
 404
 405     # Not from the corpus
 406     define_string CONFIG_VERSION "2.2.0"
 407
 408
 409
 410 === define_tristate /symbol/ /word/
 411
 412 This verb assigns the value of /word/ to /symbol/.  Legal input values
 413 are "n", "m", and "y".
 414
 415 As soon as this verb is implemented in all interpreters, please use it
 416 instead of define_bool to define tristate values.  This aids in static
 417 type checking.
 418
 419 Configure:  implemented
 420 Menuconfig: implemented
 421 Xconfig:    implemented
 422 mconfig:    implemented
 423
 424 Example:
 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
 441 This verb evaluates all of the dependencies in the dependency list.
 442 Any dependency which has a value of "y" does not restrict the input
 443 range.  Any dependency which has an empty value is ignored.
 444 Any 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
 446 allowed. Using dependencies with an empty value possible is not
 447 recommended.  See also dep_mbool below.
 448
 449 If the input range is restricted to the single choice "n", dep_bool
 450 silently assigns "n" to /symbol/.  If the input range has more than
 451 one choice, dep_bool displays /prompt/ to the user, accepts a value
 452 from the user, and assigns that value to /symbol/.
 453
 454 Configure:  implemented
 455 Menuconfig: implemented
 456 XConfig:    implemented
 457 mconfig:    implemented
 458
 459 Example:
 460
 461     # drivers/net/Config.in
 462     dep_bool 'Aironet 4500/4800 PCI support 'CONFIG_AIRONET4500_PCI $CONFIG_PCI
 463
 464 Known 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
 471 This verb evaluates all of the dependencies in the dependency list.
 472 Any dependency which has a value of "y" or "m" does not restrict the
 473 input range.  Any dependency which has an empty value is ignored.
 474 Any dependency which has a value of "n", or which has some other value,
 475 restricts the input range to "n".  Quoting dependencies is not allowed.
 476 Using dependencies with an empty value possible is not recommended.
 477
 478 If the input range is restricted to the single choice "n", dep_bool
 479 silently assigns "n" to /symbol/.  If the input range has more than
 480 one choice, dep_bool displays /prompt/ to the user, accepts a value
 481 from the user, and assigns that value to /symbol/.
 482
 483 Notice that the only difference between dep_bool and dep_mbool
 484 is in the way of treating the "m" value as a dependency.
 485
 486 Configure:  implemented
 487 Menuconfig: implemented
 488 XConfig:    implemented
 489 mconfig:    implemented
 490
 491 Example:
 492
 493     # Not from the corpus
 494     dep_mbool 'Packet socket: mmapped IO' CONFIG_PACKET_MMAP $CONFIG_PACKET
 495
 496 Known 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
 505 I am still thinking about the semantics of these verbs.
 506
 507 Configure:  not implemented
 508 Menuconfig: not implemented
 509 XConfig:    not implemented
 510 mconfig:    not implemented
 511
 512
 513
 514 === dep_tristate /prompt/ /symbol/ /dep/ ...
 515
 516 This verb evaluates all of the dependencies in the dependency list.
 517 Any dependency which has a value of "y" does not restrict the input range.
 518 Any 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.
 520 Any dependency which has a value of "n", or which has some other value,
 521 restricts the input range to "n".  Quoting dependencies is not allowed.
 522 Using dependencies with an empty value possible is not recommended.
 523
 524 If the input range is restricted to the single choice "n", dep_tristate
 525 silently assigns "n" to /symbol/.  If the input range has more than
 526 one choice, dep_tristate displays /prompt/ to the user, accepts a value
 527 from the user, and assigns that value to /symbol/.
 528
 529 Configure:  implemented
 530 Menuconfig: implemented
 531 Xconfig:    implemented
 532 mconfig:    implemented
 533
 534 Example:
 535
 536     # drivers/char/Config.in
 537     dep_tristate 'Parallel printer support' CONFIG_PRINTER $CONFIG_PARPORT
 538
 539 Known 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
 546 This verb assigns the value "" to /symbol/, but does not cause /symbol/
 547 to appear in the output.  The existence of this verb is a hack; it covers
 548 up deeper problems with variable semantics in a random-execution language.
 549
 550 Configure:  implemented
 551 Menuconfig: implemented
 552 Xconfig:    implemented (with bugs)
 553 mconfig:    implemented
 554
 555 Example:
 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
 566 This verb implements a choice list or "radio button list" selection.
 567 It displays /prompt/ to the user, as well as a group of sub-prompts
 568 which have corresponding symbols.
 569
 570 When the user selects a value, the choice verb sets the corresponding
 571 symbol to "y" and sets all the other symbols in the choice list to "n".
 572
 573 The second argument is a single-quoted or double-quoted word that
 574 describes a series of sub-prompts and symbol names.  The interpreter
 575 breaks up the word at white space boundaries into a list of sub-words.
 576 The first sub-word is the first prompt; the second sub-word is the
 577 first symbol.  The third sub-word is the second prompt; the fourth
 578 sub-word is the second symbol.  And so on, for all the sub-words.
 579
 580 The third word is a literal word.  Its value must be a unique abbreviation
 581 for exactly one of the prompts.  The symbol corresponding to this prompt
 582 is the default enabled symbol.
 583
 584 Note that because of the syntax of the choice verb, the sub-prompts
 585 may not have spaces in them.
 586
 587 Configure:  implemented
 588 Menuconfig: implemented
 589 Xconfig:    implemented
 590 mconfig:    implemented
 591
 592 Example:
 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
 604 This verb has the same semantics as the choice verb, but with a sensible
 605 syntax.
 606
 607 The first /prompt/ is the master prompt for the entire choice list.
 608
 609 The first /symbol/ is the default symbol to enable (notice that this
 610 is a symbol, not a unique prompt abbreviation).
 611
 612 The subsequent /prompt/ and /symbol/ pairs are the prompts and symbols
 613 for the choice list.
 614
 615 Configure:  not implemented
 616 Menuconfig: not implemented
 617 XConfig:    not implemented
 618 mconfig:    implemented
 619
 620
 621
 622 === if [ /expr/ ] ; then
 623
 624 This is a conditional statement, with an optional 'else' clause.  You may
 625 substitute a newline for the semicolon if you choose.
 626
 627 /expr/ may contain the following atoms and operators.  Note that, unlike
 628 shell, 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
 643 Note that a naked /atom/ is not a valid /expr/.  If you try to use it
 644 as 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
 652 value of the empty string!  It is always "y" or "n", and both of these
 653 are treated as true (non-empty) by the bash-based interpreters Configure
 654 and Menuconfig.
 655
 656 Configure:  implemented
 657 Menuconfig: implemented
 658 XConfig:    implemented, with bugs
 659 mconfig:    implemented
 660
 661 Xconfig 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
 669 This verb introduces a new menu.  The next statement must have a comment
 670 verb.  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
 673 Statements outside the scope of any menu are in the implicit top menu.
 674 The title of the top menu comes from a variety of sources, depending on
 675 the interpreter.
 676
 677 Configure:  implemented
 678 Menuconfig: implemented
 679 Xconfig:    implemented
 680 mconfig:    implemented
 681
 682
 683
 684 === endmenu
 685
 686 This verb closes the scope of a menu.
 687
 688 Configure:  implemented
 689 Menuconfig: implemented
 690 Xconfig:    implemented
 691 mconfig:    implemented
 692
 693
 694
 695 === source /word/
 696
 697 This verb interprets the literal /word/ as a filename, and interpolates
 698 the contents of that file.  The word must be a single unquoted literal
 699 word.
 700
 701 Some interpreters interpret this verb at run time; some interpreters
 702 interpret it at parse time.
 703
 704 Inclusion is textual inclusion, like the C preprocessor #include facility.
 705 The source verb does not imply a submenu or any kind of block nesting.
 706
 707 Configure:  implemented (run time)
 708 Menuconfig: implemented (parse time)
 709 Xconfig:    implemented (parse time)
 710 mconfig:    implemented (parse time)