dist-3.0at70/mcon/NOTES

   1 This file shortly documents the built-in interpreter and other new
   2 features from metaconfig.
   3
   4 The notion of "conditional unit" has been added.  In the ?MAKE:  line,
   5 each unit whose name begins with a "+" will not be loaded in the
   6 Configure script unless its exact value is a mandatory.  The default
   7 value specified in ?DEF:  will be used instead.  If no ?DEF:  line is
   8 found, then the symbol is initialized with a null default value.
   9
  10 In the config.h.SH file, only the necessary symbols are loaded.  Note
  11 that the format in ?H:  line has changed.  It is no longer necessary to
  12 write ?H:?%1:  to get a line included in config.h.  First of all, the %1
  13 symbol is not defined any more.  Secondly, the unit's name is now %< and
  14 it does not matter whether the name appears first in the ?MAKE:  line or
  15 not.  Lastly, metaconfig can guess for itself whether to include a
  16 symbol or not.
  17
  18 Sometimes, it is necessary to force a given value, because metaconfig is
  19 not smart enough to guess 100% of the time.  See voidflags.U for an
  20 example (look at the ?C: and ?H: lines and read the comments).
  21
  22 The Myread.U unit changed. It is now able to do variable substitutions,
  23 and it sets the prompt correctly if there is no supplied default. Thus,
  24 instead of the old:
  25
  26         dflt=y
  27         rp="Question? [$dflt]"
  28         $echo $n "$rp $c"
  29         . myread
  30
  31 you must now write:
  32
  33         dflt=y
  34         rp='Question?'
  35         . myread
  36
  37 and 'myread' will take care of echoing the question with the default
  38 put in square brakets.
  39
  40 Likewise, question asking for filenames or pathnames may now use the Getfile.U
  41 unit to take care of all the burden. The presetting is the same as for myread
  42 and the answer is finally held in $ans. But the variable $fn must be set to
  43 indicate the type of file and enable/disable some of the sanity checks. See
  44 leading comments in Getfile.U. Here is a simple example to locate the active
  45 file:
  46
  47         dflt='~news/lib'
  48         fn='l~:active'
  49         rp='Where is the active file?'
  50         . getfile
  51         active="$ans"
  52
  53 The user may answer the question by using ~substitution and giving only the
  54 directory where the active file is located (in which case getfile will try
  55 to locate a file named 'active' in that directory). A full path may also be
  56 given of course, if the basename of the file is not 'active'.
  57
  58 The units are now filtered by a built-in interpreter before getting
  59 loaded in Configure.  That way, a Configure script can be more or less
  60 tuned.  See d_gethname.U for a complex example.
  61
  62 All the interpreter commands start with a leading '@'.  Possible
  63 commands include:
  64
  65 o if/elsif/else/end is the traditional conditional construct.
  66 o define <symbol> tells metaconfig the <symbol> is to be defined.
  67
  68 Expressions in conditional constructs can include the &&, || and !
  69 operator with same meaning as in the shell.  Backslash at the end of a
  70 line stands for the continuation character.  All the symbols in the
  71 expression stands for themselves, and their value is true if they are
  72 defined/wanted and false otherwise.
  73
  74 It is possible to include shell and perl test.  All the text enclosed in
  75 single brackets as {<text>} is expanded in a shell as
  76
  77         if <text> >/dev/null 2>&1; then exit 0; else exit 1; fi
  78
  79 whereas text in double brackets as {{<text>}} is expanded in perl as
  80
  81         if (<text> {exit 0;} else {exit 1;}
  82
  83 and the exit status is used in the standard way to get a boolean value
  84 (i.e 0 is true and everything else is false).  See Oldconfig.U for an
  85 example.
  86
  87 Metaconfig's interpreter has standard C operator priority, but you may
  88 force the evaluation order with parenthesis.  A simple error recovery
  89 attempt is made, so that you should get meaningful error messages.
  90
  91 The simple test ?sym:  means "keep the remaining of the line iff the
  92 symbol is defined" and %sym:  is the same for non-definedness.
  93
  94 Some special symbols may be put in a unit and will get expanded,
  95 provided the ?MAKE:  command line is 'wipe' and not 'add'.  Here are the
  96 available symbols:
  97
  98         <PACKAGENAME> is the name $package as found in .package
  99         <MAINTLOC> is the $maintloc variable as found in .pakcage
 100         <VERSION> is metaconfig's version number
 101         <PATCHLEVEL> is metaconfig's patchlevel
 102         <DATE> is the current frozen date as given by `date`
 103
 104 A 'wipe'ed unit is passed through the interpreter too.
 105
 106 It is also possible to declare a symbol obsolete. A warning message
 107 will be issued if the symbol is used and the Glossary mentions it.
 108 the "Obsolete" clause. The syntax is:
 109
 110         ?C:symbol (obsolete list):
 111         ?S:symbol (obsolete list):
 112
 113 If metaconfig is used with the -o option, it will generate code to remap
 114 those old symbols to the new ones, so the old code does not have to be changed
 115 right away. If you do not use -o, the Obsolete file will still be generated
 116 to warn you about obsolete symbols but no maping will be done.
 117
 118 The new ?W: line can be use to tie up the destiny of some symbols. The syntax
 119 is:
 120
 121         ?W:shell symbols list:C symbol list
 122
 123 and the symbols in the shell list will be defined if one of the C symbols is.
 124 For instance, unit d_const.U uses the following:
 125
 126         ?W:%<:const
 127
 128 so that any 'const' usage in the C code will have %< (the unit name) handled
 129 as a wanted symbol. In particular, this has the interesting side effect of
 130 loading the unit into Configure when the 'const' keyword is used.
 131
 132 This shell symbol list part may be left empty. For example unit i_time.U uses:
 133
 134         ?W::timezone
 135
 136 for its side effect: the symbol 'timezone' may now be part of the interpreter
 137 tests to conditionally load some code into Configure when struct timezone is
 138 used.
 139
 140 C symbol aliasing can be used to let metaconfig know that the symbol comment
 141 is to be loaded in config_h.SH even when the main symbol is not used in C.
 142 For instance, d_const.U writes:
 143
 144         ?C:HASCONST ~ %<:
 145
 146 so that the HASCONST hype is loaded iff the unit (%<) is wanted. This is why
 147 the ?H: lines are also explicitely tied to the wanted-ness of the d_const
 148 symbol, by writing:
 149
 150         ?H:?%<:#$d_const HASCONST       /**/
 151         ?H:?%<:#ifndef HASCONST
 152         ?H:?%<:#define const
 153         ?H:?%<:#endif
 154         ?H:.
 155
 156 because we want all those lines to appear in config_h.SH as soon as the d_const
 157 unit is loaded into Configure.
 158
 159 Because of the new -s (silent) option of Configure, the important messages which
 160 are to appear even in silent mode must be written on file descriptor #4. Others
 161 will simply not be echoed under -s. Note that all the questions and default
 162 answers are written on #4. You should write:
 163
 164         echo " "
 165         echo "Checking to see if......" >&4
 166         .....
 167         echo "Yes, it does"
 168
 169 which will have the traditional behaviour unless -s is used, in which case only
 170 the line
 171
 172         Checking to see if.....
 173
 174 will echo on the terminal.