home *** CD-ROM | disk | FTP | other *** search
/ The Fatted Calf / The Fatted Calf.iso / Unix / Shells / zsh / Source / src / config / config.README < prev   
Encoding:
Text File  |  1994-04-07  |  6.5 KB  |  237 lines

  1. PURPOSE
  2.  
  3.     This directory contains shell scripts that are used by
  4.     src/buildzsh.
  5.  
  6. FILES
  7.  
  8.     Hierarchical list    Function of
  9.     of scripts called by    the particular
  10.     buildzsh.        script.
  11.     --------------------    --------------
  12.  
  13.     bz.init            Initialization...
  14.         bz.saveargv        saving argv
  15.         bz.defaults        for parameters
  16.         bz.ifksh        for ksh-must
  17.     bz.argh            Argument handling...
  18.         bz.help            showing help
  19.     bz.check        Argument checking...
  20.         bz.doksh        do ksh if necessary
  21.         bz.sanity        fix up some parameters
  22.     bz.hs            Header building...
  23.         bz.config.h        config.h
  24.         bz.signals.h        signals.h
  25.     bz.Makefile        Architecture-specific Makefile building...
  26.     bz.finale        Shall we $MAKE?
  27.     
  28. NOTES
  29.  
  30.     The following notes are meant for buildzsh hackers,
  31.     for others it will be a healthy example about the
  32.     problems of writing large and portable shell scripts.
  33.  
  34.     The notes are indicated by a '*' in the left margin and
  35.     they are are followed by (some of) the names of the bz.* files
  36.     that are affected by the particular note.
  37.  
  38. * all the sh-constructs must be also "Korn-compliant"
  39.   so that ksh also can munch this script.  This is normally not
  40.   a big headache because ksh should be superset of Bourne sh.
  41.  
  42.   some miserable Bourne shells fail for some reason or another
  43.   while executing buildzsh, we will try for those wrecthes whether
  44.   ksh comes to rescue.
  45.  
  46.     bz.ifksh
  47.     bz.doksh
  48.     bz.Makefiles
  49.  
  50. * because the Makefiles are built by <<eof method *inside* buildzsh,
  51.   they have to be BOTH "Bourne-compliant" AND "Korn-compliant".
  52.   Therefore, certain measures have to be taken as certain
  53.   constructs are understood differently amongst sh/ksh/make.
  54.   These constructs are
  55.         
  56.         $@              (sh and make)
  57.         $(foo)          (ksh and make)
  58.  
  59.   If these constructs are to be as "make" them understands, they MUST
  60.   be escaped with a leading backlash as follows
  61.  
  62.         \$@
  63.         \$(foo)
  64.  
  65.   All the "here-document" (<<EOF) situations cannot be handled with
  66.   <<'quoted-eof' trick, which would cure both the above problems,
  67.   because the expansion of $bar by sh/ksh is extensively used by
  68.   for example
  69.  
  70.         CC=$CC
  71.  
  72.   where $CC has been resolved by sh/ksh.  Note, however, that when
  73.   no $bar style expansions are needed during <<, the <<'quoted-eof'
  74.   method is viable and the \ escaping is not needed.
  75.  
  76.     bz.Makefiles
  77.  
  78. * do NOT even think about using the <<trick as
  79.  
  80.   if test ...
  81.   then
  82.   exec >somefile
  83.   cat <<eof
  84.   ...
  85.   eof
  86.   fi
  87.   
  88.   thanks to Sun.  In ScumOS, you will get error messages like
  89.   buildzsh: /tmp/sh1708429: No such file or directory
  90.   after each 'cat' for each exec-cat pair.
  91.   One must resort to the work-around: using subshells
  92.  
  93.   if test ...
  94.   then
  95.   (exec >somefile
  96.   cat >>eof
  97.   ...
  98.   eof
  99.   )
  100.   fi
  101.   
  102.   Note that one must be careful about the closing (: it can come
  103.   many lines after the initial cat <<'s eof, in buildzsh normally
  104.   just before the 'fi' that closes down the building of some file
  105.  
  106.   if test ...doing-some-file
  107.   then
  108.   (exec >some-file
  109.   ...
  110.   )
  111.   fi
  112.  
  113.     bz.Makefile
  114.     bz.config.h
  115.  
  116. * do not use "test -x" because some braindead (but wide-spread)
  117.   tests do not know such a flag, use "-f" instead, that *should* work
  118.   everywhere.
  119.  
  120.     bz.Makefile
  121.     bz.config.h
  122.     bz.doksh
  123.     bz.help
  124.     bz.hosttype
  125.  
  126. * do not use "tr -s", either, use sed for that.
  127.  
  128. * the argument list of the buildzsh is saved by bz.init/bz.saveargv
  129.   in to a variable called _argv that can be used in constructs like
  130.  
  131.   for i in $_argv
  132.   do
  133.     ...
  134.  
  135.   Whitespace is correctly saved in _argv.
  136.   (but exotic quoting might get fatal?)
  137.  
  138. * there are a couple of subroutinish scripts that are used to automatize
  139.   the chores of asking/looking for different kinds of questions.
  140.  
  141.   The calling sequence is as follows
  142.  
  143.     set arg1 arg2 arg3 arg4 ...
  144.     . bz.foo
  145.   
  146.   Worrying about $@?  Saved in $_argv, see above.
  147.  
  148.   bz.define:
  149.  
  150.     Usage:
  151.  
  152.     set symbol_name default_value description [ empty_ok [ quote_it ] ]
  153.     . bz.define
  154.  
  155.     Used to #define FOO, the definition is output to stdout.
  156.  
  157.     If empty answer is ok, the 4th argument should be non-empty.
  158.     
  159.     If the 5th argument is either " or ', the whole answer is
  160.     quoted with that particular character (on both sides, of course).
  161.  
  162.   bz.ifdef:
  163.  
  164.     Usage:
  165.  
  166.     set test symbol_name default_value yea_feature \
  167.             [ nay_feature [ feature_name ] ]
  168.  
  169.     Used to #define but only iff some condition holdsds,
  170.     the definition is output to stdout.
  171.  
  172.     In query mode the question is normally paraphrased as
  173.     "Do you have YEA_FEATURE?".  These can be (and are)
  174.     customized: Do is G_verb1_, you is G_subj_, have is G_verb2_.
  175.     See for example the "suspended"/"stopped" question in
  176.     bz.config.h, there the "have" is changed into "prefer".
  177.  
  178.     This is the subroutine that says "using foo..." or
  179.     "not using foo...".  Also the "using" can be customized,
  180.     it is G_verb3a_ and G_verb3b_, corresponding to the positive
  181.     and negative senses.
  182.  
  183.     All the G_{verb,subject}X customizations are temporary:
  184.     each bz.ifdef call resets the defaults.
  185.  
  186.     You can test the variables _yea and _nay after the
  187.     bz.ifdef call to know which alternative was chosen.
  188.  
  189.   bz.walk:
  190.  
  191.     set variable_name "file ..." "dir ..." default
  192.     . bz.walk
  193.  
  194.       Searches PATH-like for multiple files from multiple directories.
  195.       The first existing dir/file is set as the value of variable_name.
  196.       If no such exists, the default is used as the value.
  197.       The outer loop steps through files and the inner through directories.
  198.       For example:
  199.  
  200.     set gorp "cc gcc" "/usr/local/bin /usr/bin /bin" /bin/echo
  201.     . bz.walk
  202.  
  203.       This will try /usr/local/bin/cc, /usr/bin/cc, /bin/cc,
  204.     /usr/local/bin/gcc, /usr/bin/gcc, and /bin/gcc, in that order.
  205.     If none of these exist, gorp will have the value /bin/echo.
  206.  
  207. * As soon as you know for certain whether your C compiler groks -c and -o
  208.   simultaneously or not, add the correct variable to test to
  209.   either CC_GROK_c_o or CC_LOSE_c_o in bz.defaults, respectively.
  210.   Neither matching means running $CC *each and every* time buildzsh is run.
  211.  
  212.     bz.Makefile
  213.     bz.defaults
  214.  
  215. * As soon as you know for certain whether your C compiler groks -g and -O
  216.   simultaneously or not, add the correct variable to test to
  217.   either CC_GROK_g_O or CC_LOSE_g_O in bz.defaults, respectively.
  218.   Neither matching means running $CC *each and every* time buildzsh is run.
  219.   Variables like test:foo:bar mean testing for variable "test",
  220.   if that succeeds, setting CC_gFLAGS to "foo" and CC_OFLAGS to "bar".
  221.  
  222.     For example: CC_GROK_g_O="AIX CC_MIPS_STYLE:-g3:-O GCC:-g:-O6"
  223.  
  224.   Use 'quotes' to protect whitespace.
  225.  
  226.     bz.Makefile
  227.     bz.defaults
  228.  
  229. * if you want to display something to "stdin" while building
  230.   Makefile, you must "1>&2" it
  231.  
  232.     bz.Makefile
  233.  
  234. * the naming of the various sh variables is a total mess.
  235.  
  236. ---
  237.