glafp-utils/msub/msub.ms

   1 .SH
   2 Theory of Operation
   3 .LP
   4 .I msub
   5 reads the makefile in the current directory (or the file named after the
   6 .B \-f
   7 flag) and finds all variable definitions and references.
   8 Definitions are lines of the form ``\fIname\fR = \fIvalue\fR''.
   9 References are instances of ``$(\fIvar\fR)'' or ``${\fIvar\fR}'', either in
  10 the value part of definition lines, or any part of dependency or command lines.
  11 Then variable values are examined to eliminate references to other variables
  12 by replacing the referenced variables with their values.
  13 Variables which are referenced but never defined have a value of the empty
  14 string.
  15 .LP
  16 Then
  17 .I msub
  18 reads any files named on the command line (or
  19 .I stdin
  20 if none) and looks for instances of ``$(\fIvar\fR)'' or ``${\fIvar\fR}'',
  21 where
  22 .I var
  23 is known from the makefile, and substitutes the value of
  24 .I var .
  25 .SH
  26 Purpose
  27 .LP
  28 The motivation for
  29 .I msub
  30 is that project configuration information is often contained in makefiles
  31 and it is often desirable to make use of that information.
  32 .I msub
  33 allows files to be produced from templates that contain references
  34 to makefile variables.
  35 In this sense it is similar to the way that the C preprocessor
  36 .I cpp
  37 uses #define statements in header files; the
  38 makefile is the implicit ``header'' file and definition lines are the
  39 ``#define'' statements.
  40 .LP
  41 Although it is possible to use
  42 .I cpp
  43 to perform substitutions on templates, a disadvantage of
  44 .I cpp
  45 is that it modifies its source in other ways (eg., lines beginning with
  46 ``#'' are special and comments (``/* ... */'') are deleted.
  47 Also, it is necessary to pass a -D flag for every symbol to be substituted.
  48 Similarly, for C programs it can be simpler to use
  49 .I msub
  50 to produce a single configuration header file from a template
  51 than to pass a lot of -D flags to each invocation of
  52 .I cc .
  53 .LP
  54 .I msub
  55 performs no textual modification besides substitution of references
  56 to makefile variables; it leaves everything else alone.
  57 In particular,
  58 references to variables not known from the makefile are left untouched.
  59 This allows
  60 .I msub
  61 to be used to produce shell scripts that use variables of
  62 their own.
  63 .LP
  64 .I msub
  65 is particularly useful in software projects that use
  66 .I imake .
  67 Virtually all configuration information is propagated into makefiles
  68 thus produced, so it is available for propagation into other files using
  69 .I msub .
  70 .SH
  71 Problems
  72 .LP
  73 If
  74 .I msub
  75 is used to produce shell scripts, it is unwise for the script to use names
  76 for its own variables that are the same as those in the makefile.
  77 The problem can be avoided entirely if, for instance, variables in makefiles
  78 are all uppercase and the scripts' own variables are lowercase or mixed case.
  79 .LP
  80 Circular references in makefile variables are not expanded.
  81 If a makefile contains the definitions ``X = ${Y}'' and ``Y = ${X}'',
  82 neither X nor Y will be expanded.
  83 But that is really a problem with the makefile, not
  84 .I msub .
  85 .LP
  86 .I make
  87 recognizes
  88 .B \-f\ \-
  89 to mean the makefile should be read from
  90 .I stdin .
  91 .I msub
  92 does not.
  93 .LP
  94 CC, YACC, etc., have implicit values in
  95 .I make
  96 even if not defined in the makefile.
  97 Not true in
  98 .I msub .
  99 .LP
 100 .I msub
 101 is more restrictive in the variable names that it recognizes and
 102 performs substitutions on.
 103 Names that do not begin with a letter and
 104 that contain any characters besides letters, digits and underscores are
 105 ignored.
 106 This means that variable names such as ``${1}'' are not recognized;
 107 the reason for this is that shell scripts often use such variables and
 108 they should be left untouched.
 109 Also,
 110 ``$\fIx\fR'' is legal in
 111 .I make
 112 when
 113 .I x
 114 is a single character, but
 115 .I msub
 116 ignores such references.
 117 .i msub
 118 .LP
 119 .I make
 120 allows variables to be defined on the command line.
 121 .I msub
 122 does not.
 123 .LP
 124 If you try to be tricky with your variable references, e.g., by using
 125 recursive references, you may get burned.
 126 .LP
 127 There is no way to prevent substitution, in a source file, of a reference to
 128 a variable known from the makefile.