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