MSUB manual page
Table of Contents
msub - substitute make variables into template to produce
script
msub [ -e ] [ -f file ] [ +Rstr
] [ -Rstr ] [ variable=value
] [ file ... ]
Makefiles often contain project configuration information specified
as make variables, and it is often desirable to make use
of that information in other files. msub allows targets
to be produced easily from templates that contain references to
those variables. msub is particularly useful in software
projects that use imake because virtually all configuration
parameters are written into Makefiles and are thus available for
propagation into other files.
First msub reads the Makefile and finds all variable
definition lines of the form "var = value".
Then msub 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.
msub takes the following options:
-
-e
-
Environment variable values override assignments within Makefiles.
Normally assignments within Makefiles override environment variables.
-
-f file
-
By default, variable values are extracted from Makefile
(or makefile if Makefile is missing) in the current
directory. If the -f file option is given, variable
values are extracted from file instead. Multiple -f
options may be specified. (Note: make recognizes -f
- to mean the Makefile should be read from stdin.
msub doesn't, because template input may come from stdin.)
-
+Rstr
-
-
-Rstr
-
The default variable reference indicators within templates are
the same as in Makefiles, i.e., "$(" and ")",
and "${" and "}". These can be changed with
the +R and -R options, which must be specified
in pairs. +R specifies the string that initiates a variable
reference and -R specifies the string that terminates
it. Multiple pairs of reference indicators may be given.
-
variable=value
-
Variable definition. This definition overrides any regular definition
for the specified variable within the makefile itself or in the
environment.
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
Makefile, you can write a template helpfile.msub
like this:
...stuff...
Please direct questions to ${EMAILHELPADDR}.
...more stuff...
Process the template to produce the help file like this:
msub helpfile.msub > helpfile
If the Makefile contains the following lines:
EMAILHELPADDR = postmaster@$(DOMAIN)
DOMAIN = primate.wisc.edu
then helpfile will look like this:
...stuff...
Please direct questions to postmaster@primate.wisc.edu.
...more stuff...
msub can produce executable scripts, too. If the processor
for which you're producing the script allows variable references,
make sure you refer to make variables in the template
in a different way than the processor refers to variables. For
instance, "${var}" is ambiguous in a shell script
template - is it a reference to a shell variable that you want
msub to leave alone, or to a make variable for
which you want msub to substitute the variable's value?
To resolve the ambiguity, you can refer to shell variables as
"$var" (which the shell recognizes, but msub
doesn't), or you can use different indicators than the defaults
to refer to make variables in the template. For example,
you could use "@<" and ">@" and refer
to variables as "@<var>@". Suppose you
have a simple shell script to print your home directory pathname.
You might write it like this:
Then you can process the template like this (note that you must
quote the arguments because "<" and ">"
are special to the shell):
msub +R"@<" -R">@" template > script
The +R/-R arguments cause msub to recognize "@<SHELL>@"
but not "${HOME}". The result looks like this:
Paul DuBois, dubois@primate.wisc.edu
CC, YACC, etc., have implicit values in make even if they're
not defined in the Makefile, which isn't true for msub.
However, when msub is used with imake, this isn't
normally a problem since imake-generated Makefiles tend
to contain explicit definitions for every parameter in the known
universe.
msub is more restrictive in the variable names it recognizes
and performs substitutions on than make. make allows
single character names to be referenced as "$c",
where c is a letter; msub doesn't. msub
also ignores make variables like "$*" and "$@".
Recursive references in Makefile variables aren't expanded.
If a Makefile contains the definition "X = ${X}",
X won't be expanded. Indirectly recursive references aren't expanded,
either. If a Makefile contains the definitions "X
= ${Y}" and "Y = ${X}", neither X nor Y will be
expanded. (These actually aren't bugs in msub, they're
problems in the Makefile.)
A comment at the end of a variable assignment line become part
of the variable's value. If Makefile contains the following
line:
SHELL = /bin/shell # default shell
then msub takes the value of SHELL to be "/bin/shell
# default shell".