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