glafp-utils/msub/msub.man

   1 .TH MSUB 1
   2 .SH NAME
   3 msub \- substitute \fImake\fR variables into template to produce script
   4 .SH SYNOPSIS
   5 .B msub
   6 [
   7 .B \-e
   8 ] [
   9 .B \-f
  10 .I file
  11 ] [
  12 .BI \+R str
  13 ] [
  14 .BI \-R str
  15 ] [
  16 .IB variable = value
  17 ] [
  18 .I file
  19 \&...
  20 ]
  21 .SH DESCRIPTION
  22 Makefiles often contain project configuration information specified as
  23 .I make
  24 variables, and it is often desirable to make use of that information in other
  25 files.
  26 .I msub
  27 allows targets to be produced easily
  28 from templates that contain references to those variables.
  29 .I msub
  30 is particularly useful in software projects that use
  31 .IR imake
  32 because virtually all configuration parameters are written into Makefiles
  33 and are thus available for propagation into other files.
  34 .PP
  35 First
  36 .I msub
  37 reads the
  38 .I Makefile
  39 and finds all variable definition lines
  40 of the form ``\fIvar\fR = \fIvalue\fR''.
  41 Then
  42 .I msub
  43 reads any files named on the command line (or the standard input
  44 if none), looks for references to those variables, and replaces the
  45 references with the corresponding variable values.
  46 References to undefined variables are replaced by the empty string.
  47 The result is written to the standard output.
  48 .PP
  49 .I msub
  50 takes the following options:
  51 .TP
  52 .B \-e
  53 Environment variable values override assignments within Makefiles.
  54 Normally assignments within Makefiles override environment variables.
  55 .TP
  56 .BI \-f \ file
  57 By default, variable values are extracted from
  58 .I Makefile
  59 (or
  60 .I makefile
  61 if
  62 .I Makefile
  63 is missing) in the current directory.
  64 If the
  65 .B \-f
  66 .I file
  67 option is given, variable values are extracted from
  68 .I file
  69 instead.
  70 Multiple
  71 .B \-f
  72 options may be specified.
  73 (Note:
  74 .I make
  75 recognizes
  76 .B \-f\ \-
  77 to mean the
  78 .I Makefile
  79 should be read from
  80 .IR stdin .
  81 .I msub
  82 doesn't, because template input may come from
  83 .IR stdin .)
  84 .TP
  85 .BI +R str
  86 .TP
  87 .BI \-R str
  88 The default variable reference indicators within templates
  89 are the same as in Makefiles, i.e.,
  90 ``$('' and ``)'', and ``${'' and ``}''.
  91 These can be changed with the
  92 .B +R
  93 and
  94 .B \-R
  95 options, which must be specified in pairs.
  96 .B +R
  97 specifies the string that initiates a variable reference and
  98 .B \-R
  99 specifies the string that terminates it.
 100 Multiple pairs of reference indicators may be given.
 101 .TP
 102 .IB variable = value
 103 Variable definition.
 104 This definition overrides any regular definition for the specified
 105 variable within the makefile itself or in the environment.
 106 .SH EXAMPLES
 107 Suppose you want to produce for a program a help file that indicates the local
 108 e-mail address to which questions may be directed.
 109 If this address is specified as the variable EMAILHELPADDR in the
 110 .IR Makefile ,
 111 you can write a template
 112 .I helpfile.msub
 113 like this:
 114 .in +.5i
 115 .nf
 116 .sp .5v
 117 \&.\|.\|.\|\fIstuff\fP\|.\|.\|.
 118 Please direct questions to ${EMAILHELPADDR}.
 119 \&.\|.\|.\|\fImore stuff\fP\|.\|.\|.
 120 .sp .5v
 121 .fi
 122 .in
 123 Process the template to produce the help file like this:
 124 .in +.5i
 125 .nf
 126 .sp .5v
 127 msub helpfile.msub > helpfile
 128 .sp .5v
 129 .fi
 130 .in
 131 If the
 132 .I Makefile
 133 contains the following lines:
 134 .in +.5i
 135 .nf
 136 .sp .5v
 137 EMAILHELPADDR = postmaster@$(DOMAIN)
 138 DOMAIN = primate.wisc.edu
 139 .sp .5v
 140 .fi
 141 .in
 142 then
 143 .I helpfile
 144 will look like this:
 145 .in +.5i
 146 .nf
 147 .sp .5v
 148 \&.\|.\|.\|\fIstuff\fP\|.\|.\|.
 149 Please direct questions to postmaster@primate.wisc.edu.
 150 \&.\|.\|.\|\fImore stuff\fP\|.\|.\|.
 151 .sp .5v
 152 .fi
 153 .in
 154 .I msub
 155 can produce executable scripts, too.
 156 If the processor for which you're producing
 157 the script allows variable references, make sure you refer to
 158 .I make
 159 variables in the template in a different way than the processor refers to
 160 variables.
 161 For instance, ``${\fIvar\fP}'' is ambiguous in a shell script template \- is
 162 it a reference to a shell variable that you want
 163 .I msub
 164 to leave alone, or to a
 165 .I make
 166 variable for which you want
 167 .I msub
 168 to substitute the variable's value?
 169 To resolve the ambiguity, you can refer to shell variables as ``$\fIvar\fP''
 170 (which the shell recognizes, but
 171 .I msub
 172 doesn't), or you can use different indicators than the defaults to refer to
 173 .I make
 174 variables in the template.
 175 For example, you could use ``@<'' and ``>@'' and refer to variables as
 176 ``@<\fIvar\fP>@''.
 177 Suppose you have a simple shell script to print your home directory pathname.
 178 You might write it like this:
 179 .in +.5i
 180 .nf
 181 .sp .5v
 182 #!@<SHELL>@
 183 echo ${HOME}
 184 .sp .5v
 185 .fi
 186 .in
 187 Then you can process the template like this (note that you must quote the
 188 arguments because ``<'' and ``>'' are special to the shell):
 189 .in +.5i
 190 .nf
 191 .sp .5v
 192 msub +R"@<" \-R">@" template > script
 193 .sp .5v
 194 .fi
 195 .in
 196 The
 197 .B +R/\-R
 198 arguments cause
 199 .I msub
 200 to recognize ``@<SHELL>@'' but not ``${HOME}''.
 201 The result looks like this:
 202 .in +.5i
 203 .nf
 204 .sp .5v
 205 #!/bin/sh
 206 echo ${HOME}
 207 .sp .5v
 208 .fi
 209 .in
 210 .SH "WHO-TO-BLAME"
 211 Paul DuBois, dubois@primate.wisc.edu
 212 .SH "BUGS AND RESTRICTIONS"
 213 CC, YACC, etc., have implicit values in
 214 .I make
 215 even if they're not defined in the
 216 .IR Makefile ,
 217 which isn't true for
 218 .IR msub .
 219 However, when
 220 .I msub
 221 is used with
 222 .IR imake ,
 223 this isn't normally a problem since
 224 .IR imake -generated
 225 Makefiles tend to contain explicit definitions for every parameter in the
 226 known universe.
 227 .PP
 228 .I msub
 229 is more restrictive in the variable names it recognizes and
 230 performs substitutions on than
 231 .IR make .
 232 .I make
 233 allows single character names to be referenced as ``$\fIc\fP'', where
 234 .I c
 235 is a letter;
 236 .I msub
 237 doesn't.
 238 .I msub
 239 also ignores
 240 .I make
 241 variables like
 242 ``$*'' and ``$@''.
 243 .PP
 244 Recursive references in
 245 .I Makefile
 246 variables aren't expanded.
 247 If a
 248 .I Makefile
 249 contains the definition ``X = ${X}'', X won't be expanded.
 250 Indirectly recursive references aren't expanded, either.
 251 If a
 252 .I Makefile
 253 contains the definitions ``X = ${Y}'' and ``Y = ${X}'',
 254 neither X nor Y will be expanded.
 255 (These actually aren't bugs in
 256 .IR msub ,
 257 they're problems in the
 258 .IR Makefile .)
 259 .PP
 260 A comment at the end of a variable assignment line become part of the
 261 variable's value.
 262 If
 263 .I Makefile
 264 contains the following line:
 265 .in +.5i
 266 .nf
 267 .sp .5v
 268 SHELL = /bin/shell # default shell
 269 .sp .5v
 270 .fi
 271 .in
 272 then
 273 .I msub
 274 takes the value of SHELL to be ``/bin/shell # default shell''.