Source statements

A source statement declares a file to be inserted in place of the source statement in the file, and treated as if the entire contents of that file were present in the current file at the point of their source statement.

Any implementation of CML2 must allow source statements to be nested to a depth of at least 15 levels. The reference implementation has no hard limit.

Symbol declarations

The body of a symbols section consists of pairs of tokens; a symbol (which may be an ordinary configuration symbol, a menu name, a message string, or an explanation string) and a prompt string. Each pair may optionally be followed by a text section declaring associated help text, or by the keyword like and a symbol specifying an existing symbol with help text.

Rationale: Having these name-to-prompt associations be separate from the dependency rules will help make the text parts of the system easier to localize for different languages. Declaring all query symbols up front means we can do better and faster sanity checks. Some symbols (derivations) are not pre-declared.

Property declarations

A property name declaration declares aliases for a given property. Usually these aliases are short (often one letter) and are intended to be embedded in menus.

Associating a property with a symbol means that property will be included in a comment following the symbol value dump on its line.

Rationale: Annotation label may be used as instructions to configuration-file postprocessors. The sets of symbols defined by properties may be used by configurators that have knowledge specific to a particular rulebase.

Visibility rules

A visibility declaration associates a visibility predicate with a set of configuration symbols. The fact that several symbols may occur on the right side of such a rule is just a notational convenience; the rule

      unless GUARD suppress SYMBOL1 SYMBOL2 SYMBOL3

is exactly equivalent to

      unless GUARD suppress SYMBOL1
      unless GUARD suppress SYMBOL2
      unless GUARD suppress SYMBOL3

Putting a menu on the right side of a visibility rule suppresses that menu and all its children. In general, suppressing a symbol also implicitly suppresses all its dependents.

If multiple visibility declarations touch a symbol on the right-hand side, the resulting test is the logical conjunction of all of them.

As a convenience,

      when GUARD suppress SYMBOL1 SYMBOL2 SYMBOL3

is syntactic sugar for

      unless GUARD==n suppress SYMBOL1 SYMBOL2 SYMBOL3

When a derived symbol is suppressed, this prevents its value from being written out to the configuration file.

      unless GUARD suppress dependent SYMBOL

    unless FOO!=n and BAR==m suppress dependent BAZ

     unless FOO!=n and BAR==m suppress BAZ
     require BAZ <= FOO and BAZ <= BAR 

    unless FOO!=n and (BAR==m or BAZ==y) suppress dependent QUUX

     unless FOO!=n and (BAR==m or BAZ==y) suppress QUUX
     require QUUX <= FOO

Saveability rules

Normally, CML2 configurators save a symbol to the output configurator if it is either been set during the configuration session or is visible at save time.

Occasionally it is necessary to force the default of a symbol to be saved even when it is not visible at save time. For this purpose the language supports giving symbols an explicit saceability predicate:

      when GUARD1 save SYMBOL1 SYMBOL2 SYMBOL3
      unless GUARD2 save SYMBOL4 SYMBOL5 SYMBOL6

The guard expressions may be any legal expression.

Menu definitions

A menu definition associates a sequence of configuration symbols and (sub)menu identifiers with a menu identifier (and its banner string). It is an error for any symbol or menu name to be referenced in more than one menu.

If there are multiple menu definitions referring to the same menu name, the compiler builds a single menu from all of them listing their contents in the order they are compiled. This is explicitly permitted in order to allow menu add-ons in CML2 source files generated by concatenation.

Any implementation of CML2 must allow menus to be nested to a depth of at least 15 levels. The reference implementation has no hard limit.

Symbol references in menus may have suffixes which change the default boolean type of the symbol. The suffixes are as follows:

    ?      trit type
    %      decimal type
    @      hexadecimal type
    $      string type

A choices definition associates a choice of boolean configuration symbols with a menu identifier (and its banner string). It may optionally declare a default symbol to be set to y at the time the menu is instantiated; if there is no specified default, the first symbol in the menu becomes the default.

If the default symbol of a choices menu is invisible at menu instantiation time, the configurator is expected to search forward into the symbols following the default until a visible alternative is found. If a visible alternative is found, it is used. If no visible alternative is found, the behavior is undefined (but the recommended behavior is to throw an except and exit).

In a complete CML2 system, these definitions link all menus together into a single big tree, which is normally traversed depth-first (except that visibility predicates may suppress parts of it).

If the list of symbols has subtrees in it (indicated by curly braces) then the symbol immediately before the opening curly brace is declared a visibility and dependency guard for all symbols within the braces. That is, the menu declaration

    menu foo 
         SYM1 SYM2 {SYM3 SYM4} SYM5

not only associates SYM[12345] with foo, it also registers rules equivalent to

       unless SYM2 suppress dependent SYM3 SYM4

Such submenu declarations may be nested to any depth.

Normally, a symbol used as a sub-menu guard will be a bool or trit. They are also permitted to be numeric, in which case value zero is considered equivalent to boolean n and all other values are considered equivalent to boolean y.

It is perfectly legal for a menu-ID to have no child nodes. In CML2, this is how you embed text in menus, by making it the banner of a menu symbol with no children.

Choice groups

Declaring a group of logical symbols to be a choice group creates the constraint that at most one of those symbols can have the value y or m. Setting a symbol in a choicegroup to one of these values clears all other symbols in the group. It is a compile-time error for a choice group to contain symbols that are not of logical type.

Choices menus are a special case of choicegroups that are constrained always to have one choice selected.

Derivations

A derivation binds a symbol to a formula, so the value of that symbol is always the current value of the formula. Symbols may be evaluated either when a menu containing them is instantiated or at the time the final configuration file is written.

The compiler performs type inference to deduce the type of a derived symbol. In particular, derived symbols for which the top-level expression is an arithmetic operator are deduced to be decimal. Derived symbols for which the top level of the expression is a boolean operator are deduced to be bool. Derived symbols for which the top level of the expression is a trit operator are deduced to be trit.

Derived symbols are never set directly by the user and have no associated prompt string.

Defaults

A default definition sets the value a symbol will have until it is explicitly set by the user's answer to a question. The right-hand side of a default is not limited to being a constant value; it may be any valid expression.

Default expressions are treated as symbolic macros to be evaluated either when a menu containing the defaulted symbol is instantiated, or at the time the final configuration file is written, or during the evaluation of any formula (such as a derivation or visibility predicate) referring to the defaulted symbol.

Thus, the evaluated default of a symbol may differ depending on the timing of evaluation relative to other symbol settings (in particular, of the default expression's component symbols). This is intentional. The compiler detects circularities resulting from cycles of default expressions or derivations that would cause infinite recursion.

If a decimal or hexadecimal symbol is defaulted from a symbol or expression that has bool or trit values, the values y and m are cast to 1 and the value n is cast to 0. If a boolean or trit symbol is defaulted from a decimal- or hexadecimal-valued expression, a value of zero is cast to n and all other values are cast to y. The results of mixing other types are undefined, should be considered accidents of the implementation, and should not be relied on.

If a non-string symbol is not explicitly defaulted, it gets the zero value of its type; n for bools and trits, 0 for decimal and hexadecimal symbols. String symbols always require a default.

The optional range or enumeration part may be used to constrain legal values for decimal or hexadecimal-valued symbol. A default declaration may have either a range or an enumeration part, but not both.

A range specification consists of any number of either single values or paired upper and lower bounds separated by a dash, interpreted as inclusive ranges. The symbol has a legal value if it either matches a specified single value or is contained in one of the intervals.

An enumeration consists of a series of pairs separated by '='. Each pair associates a symbol (which must have been previously declared in an explanation statement) with an integer value. The symbol must match one of the values. The front end may use the prompt value of the symbol in each pair to stand in for the value (e.g. when generating a pull-down menu of alternatives.)

Requirements

derive SPARC from SPARC32 or SPARC64
require SPARC implies ISA==n and PCMCIA==n and VT==y and VT_CONSOLE==y
    and BUSMOUSE==y and SUN_MOUSE==y and SERIAL==y and SERIAL_CONSOLE==y
    and SUN_KEYBOARD==y

Start declaration

The start definition specifies the name of the root menu of the hierarchy. One such declaration is required per CML2 ruleset.

Prefix declaration

A prefix declaration sets a string to be prepended to each symbol name whenever it is written out to a result configuration file. This prefix is also ignored when present as a prefix of symbol names, whether in a rule file or when read in from a defconfig file.

Rationale: This was added so the CML2 rule system for the Linux kernel would not have to include the common CONFIG_ prefix, which adds bulk and makes reading the rules file visually confusing. The alternative of wiring that prefix into the code would compromise CML2's potential usefulness for other applications. Prefix-stripping in rule files was added as a backward-compatibility hack to permit names such as CONFIG_3C515 that have leading numerics and would be treated as numbers if given without prefix.

Banner declaration

A banner definition sets the menu id banner string to used in the configurator greeting line. The string attached to the specified menu id should identify the system being configured.

Rationale: As for the prefix string.

Condition statement

The condition statement ties a CML2 feature flag to a query symbol; that is, the value of the feature flag is the value of the symbol. The initial value of the flag when a rulebase is read in is simply the associated symbol's default. If there is no symbol associated with the the flag, the flag's value is n.

The condition value may also be a constant, in which case the value of the feature flag is set to that constant.

Warndepend declaration

The warndepend declaration takes a list of symbol names. All dependents of each symbol have their prompts suffixed with the name of the symbol in parentheses to indicate that they are dependent on it.

Rationale: Added to support the EXPERIMENTAL symbol in the Linux kernel configuration. This declaration is better than tracking experimental status by hand because it guarantees that subsidiary symbols dependent on an experimental feature will always be flagged for the user.

Icon declaration

An icon declaration associates graphic data (encoded in RFC2045 base64) with the rulebase. Front ends may use this data as an identification icon.

The reference front-end implementation uses the image to iconify the configurator when it is minimized while running in X mode.

The reference front-end accepts the image in GIF format. In the future (when underlying library support permits) PNG support will be added and GIF removed.

Debug

This declaration enables debugging output from the compiler (it has no effect on front-end behavior). It takes an integer value and uses it to set the current debug level. It may change or be removed in future releases.

Expressions

All arithmetic is integer. The compiler permits some kinds of type promotion, described below.

For purposes of the relational operators, trit values are strictly ordered with y > m > n.

Arithmetic operations + - * / have the expected semantics on decimal and hexadecimal value.

Boolean logical expressions may be used as parts of integer-valued formulas (e,g in derivations and constraints). The value of true is 1, and of false is 0.

It is a compile-time error to apply the logical operators or/and/implies to trit or numeric values. Also, expressions occurring in guards (in unless/suppress, or require/prohibit declarations) must yield a value of boolean type. The compiler does type propagation in expressions to check these constraints.

The purpose of these restriction is to enable compile-time detection of situations where confusion of trit or numeric with boolean values might induce subtle errors. For the same reason, if the symbol FOO is trit-valued it is a compile-time error to say just "FOO" in an expression, as opposed to "FOO!=n" or some other more explicit relational.

Thus, because the symbol SCSI is trit-valued:

    unless SCSI suppress A2091_SCSI

is illegal and will raise an error. Write an unambiguous test instead:

    unless SCSI>=m suppress A2091_SCSI

The obvious booleans operations (and, or) are supported; they are commutative and associative. An 'implies' operation is also supported:

    FOO implies BAR  <=>  not (FOO and (not BAR))

The implies operation is neither commutative nor associative.

The usual relational tests (==, !=, >=, <=, >, <) are supported. Relationals bind more tightly than boolean operators, so FOO!=n and BAR==m behaves as expected. Additionally, and binds more tightly than or, so that FOO or BAR and BAZ is FOO or (BAR and BAZ).

Ternary-select is available as in C. The value of a ? b : c is b if a is true, c otherwise.

The following additional ternary-logic operations are available. It is an error to apply these to operands with types other than bool or trit.

Max or union; notation |. Here is a truth table:

Min or intersection; notation &. Here is a truth table:

Similarity; notation $. Here is a truth table:

The operator precedence implied by the BNF above is implemented in the parser.

Symbol Assignment and Side Effects

Setting a symbol's value may have side-effects on other symbols in two ways.

First, it may trigger a change in other variables through explicit requirements. See the section called Using requirements to force variables for discussion.

Second, each symbol has two implicit lists associated with it: of symbols it depends on (ancestors) and symbols that depend on it (dependents). Whenever a symbol is changed, any side-effects are propagated through those lists. Changing the value of the symbol upward (n to m, or m to y) may change the value of ancestors; changing it downward (y to m or m to n) may affect the value of dependents.

See also the section called Dependence for discussion of the two syntactically different ways dependencies can be created.

CML2 interpreters are required to implement all-or-nothing side effects; that is, after an assignment, either the assignment and all its side-effects have been performed, or (in the event the new values would violate a requirement) none of them are.

The reference implementation achieves this by implementing two-phase commit; the assignment and its side-effects can be made tentatively, constraints checked, and then either committed or rolled back.

Side-effect bindings remain linked to the symbol whose value change triggered them, and are backed out whenever that symbol is changed again. Backing out a side-effect may expose previous side-effects on a symbol from other, earlier bindings.

To see how this works, consider the following sequence of actions given the constraints A: (FOO==y implies BAR==y) and B: (BAZ==y implies BAR==n):

The easiest way to understand this is by visualizing the variable-binding transactions as a stack. After the first step, the stack looks like this:

1: FOO=y:         FOO=y BAR=y

After the second step:

2: BAZ=y:         FOO=n BAR=n BAZ=y
1: FOO=y:         FOO=y BAR=y

The third step adds another unrelated binding:

3: QUUX=y:                          QUUX=y
2: BAZ=y:         FOO=n BAR=n BAZ=y
1: FOO=y:         FOO=y BAR=y

The fourth step both adds a binding and backs out the old one:

4: BAZ=n:                     BAZ=n               
3: QUUX=y:                          QUUX=y
1: FOO=y:         FOO=y BAR=y

The reference implementation journals all side-effects and always looks for the most recent binding of a symbol (highest in the stack) when evaluating it.

Order Dependencies

In general, the relative order of CML2 declarations does not change their effect. The prefix declaration, however, is used in interpreting symbol names, so it must precede symbol declarations.

There is a subtler kind of order dependency possible between constraints. Consider the following set of constraints:

1: require FOO==y implies DEP1==y
2: require DEP1 implies BAR==n
3: require FOO==y and BAR==y implies DEP2==n

Now suppose we set FOO to y. Then the values that variables get forced to will be different depending on the order in which the theorem-prover finds the constraints:

1, 2, 3: DEP1==y, BAR==n, DEP2 unchanged.
1, 3, 2: DEP1==y, BAR==n, DEP2==n

In practice this should seldom be a difficulty, but it is well to bear such possibilities in mind when writing complex constraints.