MSUB(1)

NAME
msub - substitute make variables into template to produce script

SYNOPSIS
msub [ -e ] [ -f file ] [ +Rstr ] [ -Rstr ] [ variable=value ] [ file ... ]

DESCRIPTION
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.

EXAMPLES
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:

#!@<SHELL>@
echo ${HOME}

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:

#!/bin/sh
echo ${HOME}

WHO-TO-BLAME
Paul DuBois, dubois@primate.wisc.edu

BUGS AND RESTRICTIONS
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''.