Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/misc/volume19/dmake/part16

Text File | 1991-05-11 | 40.4 KB | 1,007 lines

Newsgroups: comp.sources.misc
From: Dennis Vadura <[e-mail]>
Subject:  v19i037:  dmake - dmake version 3.7, Part16/37
Message-ID: <[e-mail]>
X-Md4-Signature: 631a7404276e2c65db69b24d73303b6d
Date: Sun, 12 May 1991 00:19:43 GMT
Approved: [e-mail]

Submitted-by: Dennis Vadura <[e-mail]>
Posting-number: Volume 19, Issue 37
Archive-name: dmake/part16
Supersedes: dmake-3.6: Volume 15, Issue 52-77

---- Cut Here and feed the following to sh ----
#!/bin/sh
# this is dmake.shar.16 (part 16 of a multipart archive)
# do not concatenate these parts, unpack them in order with /bin/sh
# file dmake/man/dmake.p continued
#
if test ! -r _shar_seq_.tmp; then
    echo 'Please unpack part 1 first!'
    exit 1
fi
(read Scheck
 if test "$Scheck" != 16; then
    echo Please unpack part "$Scheck" next!
    exit 1
 else
    exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test -f _shar_wnt_.tmp; then
sed 's/^X//' << 'SHAR_EOF' >> 'dmake/man/dmake.p' &&
X                 prerequisites or targets) then the effect is
X                 equivalent to specifying --TT on the command line.
X
X     ..NNOOSSTTAATTEE    Any target with this attribute set will not have
X                 command line flag information stored in the
X                 state file if .KEEP_STATE has been enabled.
X
X     ..PPHHOONNYY      Any target with this attribute set will have its
X                 recipe executed each time the target is made
X                 even if a file matching the target name can be
X                 located.  Any targets that have a .PHONY attri-
X                 buted target as a prerequisite will be made each
X                 time the .PHONY attributed prerequisite is made.
X
X     ..PPRREECCIIOOUUSS   Do not remove associated target under any cir-
X                 cumstances.  Set by default for any targets
X                 whose corresponding files exist in the file sys-
X                 tem prior to the execution of ddmmaakkee.
X
X     ..PPRROOLLOOGG     Insert shell prolog code when executing a group
X                 recipe associated with any target having this
X                 attribute set.
X
X     ..SSEEQQUUEENNTTIIAALL Force a sequential make of the associated
X                 target's prerequisites.
X
X     ..SSEETTDDIIRR     Change current working directory to specified
X                 directory when making the associated target.
X                 You must specify the directory at the time the
X                 attribute is specified.  To do this simply give
X                 _._S_E_T_D_I_R_=_p_a_t_h as the attribute.  _p_a_t_h is expanded
X                 and the result is used as the value of the
X                 directory to change to.  If path is surrounded
X
X
X
Version 3.70                    UW                             10
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X                 by single quotes then path is not expanded, and
X                 is used literally as the directory name.  If the
X                 _p_a_t_h contains any `:' characters then the entire
X                 attribute string must be quoted using ".  If a
X                 target having this attribute set also has the
X                 .IGNORE attribute set then if the change to the
X                 specified directory fails it will be ignored,
X                 and no error message will be issued.
X
X     ..SSIILLEENNTT     Do not echo the recipe lines when making any
X                 target with this attribute set, and do not issue
X                 any warnings.
X
X     ..SSWWAAPP       Under MSDOS when making a target with this
X                 attribute set swap the ddmmaakkee executable to disk
X                 prior to executing the recipe line.  Also see
X                 the '%' recipe line flag defined in the RECIPES
X                 section.
X
X     ..SSYYMMBBOOLL     Target is a library member and is an entry point
X                 into a module in the library.  This attribute is
X                 used only when searching a library for a target.
X                 Targets of the form lib((entry)) have this
X                 attribute set automatically.
X
X     ..UUSSEESSHHEELLLL   Force each recipe line of a target to be exe-
X                 cuted using a shell.  Specifying this attribute
X                 is equivalent to specifying the '+' character at
X                 the start of each line of a non-group recipe.
X
X     ..UUPPDDAATTEEAALLLL  Indicates that all the targets listed in this
X                 rule are updated by the execution of the accom-
X                 panying recipe.  A common example is the produc-
X                 tion of the _y_._t_a_b_._c and _y_._t_a_b_._h files by yyaacccc
X                 when it is run on a grammar.  Specifying
X                 .UPDATEALL in such a rule prevents the running
X                 of yacc twice, once for the y.tab.c file and
X                 once for the y.tab.h file.
X
X
X     All attributes are user setable and except for .UPDATEALL,
X     .SETDIR and .MKSARGS may be used in one of two forms.  The
X     .MKSARGS attribute is restricted to use as a global attri-
X     bute, and the use of the .UPDATEALL and .SETDIR attributes
X     is restricted to rules of the second form only.
X
X          ATTRIBUTE_LIST : _t_a_r_g_e_t_s
X
X     assigns the attributes specified by ATTRIBUTE_LIST to each
X     target in _t_a_r_g_e_t_s or
X
X          _t_a_r_g_e_t_s ATTRIBUTE_LIST : ...
X
X
X
Version 3.70                    UW                             11
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     assigns the attributes specified by ATTRIBUTE_LIST to each
X     target in _t_a_r_g_e_t_s_. In the first form if _t_a_r_g_e_t_s is empty
X     (ie. a NULL list), then the list of attributes will apply to
X     all targets in the makefile (this is equivalent to the com-
X     mon Make construct of _"_._I_G_N_O_R_E _:_" but has been modified to
X     the notion of an attribute instead of a special target).
X     Not all of the attributes have global meaning.  In particu-
X     lar, .LIBRARY, .SYMBOL, and .UPDATEALL have no assigned glo-
X     bal meaning.
X
X     Any attribute may be used with any target, even with the
X     special targets.  Some combinations are useless (e.g.
X     .INCLUDE .PRECIOUS: ... ), while others are useful (e.g.
X     .INCLUDE .IGNORE : "file.mk" will not complain if file.mk
X     cannot be found using the include file search rules, see the
X     section on SPECIAL TARGETS for a description of .INCLUDE).
X     If a specified attribute will not be used with the special
X     target a warning is issued and the attribute is ignored.
X
MMAACCRROOSS
X     ddmmaakkee supports six types of macro assignment.
X
X
X     MMAACCRROO == LLIINNEE    This is the most common and familiar form of
X                     macro assignment.  It assigns LINE literally
X                     as the value of MACRO.  Future expansions of
X                     MACRO recursively expand its value.
X
X     MMAACCRROO **== LLIINNEE   This form behaves exactly as the simple '='
X                     form with the exception that if MACRO
X                     already has a value then the assignment is
X                     not performed.
X
X     MMAACCRROO ::== LLIINNEE   This form differs from the simple '=' form
X                     in that it expands LINE prior to assigning
X                     it as the value of MACRO.  Future expansions
X                     of MACRO do not recursively expand its
X                     value.
X
X     MMAACCRROO **::== LLIINNEE  This form behaves exactly as the ':=' form
X                     with the exception that if MACRO already has
X                     a value then the assignment and expansion
X                     are not performed.
X
X     MMAACCRROO ++== LLIINNEE   This form of macro assignment allows macro
X                     values to grow.  It takes the literal value
X                     of LINE and appends it to the previous value
X                     of MACRO separating the two by a single
X                     space.  Future expansions of MACRO recur-
X                     sively expand its value.
X
X
X
X
X
Version 3.70                    UW                             12
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     MMAACCRROO ++::== LLIINNEE  This form is similar to the '+=' form except
X                     that the value of LINE is expanded prior to
X                     being added to the value of MACRO.
X
X     Macro expressions specified on the command line allow the
X     macro value to be redefined within the makefile only if the
X     macro is defined using the '+=' and '+:=' operators.  Other
X     operators will define a macro that cannot be further modi-
X     fied.
X
X     When ddmmaakkee defines a non-environment macro it strips leading
X     and trailing white space from the macro value.  Macros
X     imported from the environment via either the .IMPORT special
X     target (see the SPECIAL TARGETS section), or the --ee, or --EE
X     flags are an exception to this rule.  Their values are
X     always taken literally and white space is never stripped.
X     In addition, named macros defined using the .IMPORT special
X     target do not have their values expanded when they are used
X     within a makefile.  In contrast, environment macros that are
X     imported due to the specification of the --ee or --EE flags are
X     subject to expansion when used.
X
X     To specify a macro expansion enclose the name in () or {}
X     and precede it with a dollar sign $.  Thus $(TEST)
X     represents an expansion of the macro variable named TEST.
X     If TEST is defined then $(TEST) is replaced by its expanded
X     value.  If TEST is not defined then $(TEST) expands to the
X     NULL string (this is equivalent to defining a macro as
X     'TEST=' ).  A short form may be used for single character
X     named macros.  In this case the parentheses are optional,
X     and $(I) is equivalent to $I.  Macro expansion is recursive,
X     hence, if the value string contains an expression represent-
X     ing a macro expansion, the expansion is performed.  Circular
X     macro expansions are detected and cause an error to be
X     issued.
X
X     When defining a macro the given macro name is first expanded
X     before being used to define the macro.  Thus it is possible
X     to define macros whose names depend on values of other mac-
X     ros.  For example, suppose CWD is defined as
X
X          CWD = $(PWD:b)
X
X     then the value of $(CWD) is the name of the current direc-
X     tory.  This can be used to define macros specific to this
X     directory, for example:
X
X          _$(CWD).prt = list of files to print...
X
X     The actual name of the defined macro is a function of the
X     current directory.  A construct such as this is useful when
X     processing a hierarchy of directories using .SETDIR
X
X
X
Version 3.70                    UW                             13
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     attributed targets and a collection of small distributed
X     makefile stubs.
X
X     Macro variables may be defined within the makefile, on the
X     command line, or imported from the environment.
X
X     ddmmaakkee supports several non-standard macro expansions: The
X     first is of the form:
X
X          _$_(_m_a_c_r_o___n_a_m_e_:_m_o_d_i_f_i_e_r___l_i_s_t_:_m_o_d_i_f_i_e_r___l_i_s_t_:_._._._)
X
X     where _m_o_d_i_f_i_e_r___l_i_s_t is chosen from the set { D or d, F or f,
X     B or b, S or s, T or t } and
X
X          d - directory portion of all path names
X          f - file (including suffix) portion of path names
X          b - file (not including suffix) portion of path names
X          s - simple pattern substitution
X          t - tokenization.
X
X     Thus if we have the example:
X
X          test = d1/d2/d3/a.out f.out d1/k.out
X
X     The following macro expansions produce the values on the
X     right of '-->' after expansion.
X
X          $(test:d)            --> d1/d2/d3/ d1/
X          $(test:b)            --> a f k
X          $(test:f)            --> a.out f.out k.out
X          ${test:db}           --> d1/d2/d3/a f d1/k
X          ${test:s/out/in/:f}  --> a.in f.in k.in
X          $(test:f:t"+")       --> a.out+f.out+k.out
X
X     If a token ends in a string composed from the value of the
X     macro DIRBRKSTR (ie. ends in a directory separator string,
X     e.g. '/' in UNIX) and you use the ::dd modifier then the
X     expansion returns the directory name less the final direc-
X     tory separator string.  Thus successive pairs of :d modif-
X     iers each remove a level of directory in the token string.
X
X     The tokenization modifier takes all white space separated
X     tokens from the macro value and separates them by the quoted
X     separator string.  The separator string may contain the fol-
X     lowing escape codes \a => <bel>, \b => <backspace>, \f =>
X     <formfeed>, \n => <nl>, \r => <cr>, \t => <tab>, \v =>
X     <vertical tab>, \" => ", and \xxx => <xxx> where xxx is the
X     octal representation of a character.  Thus the expansion:
X
X          $(test:f:t"+\n")
X     produces:
X          a.out+
X
X
X
Version 3.70                    UW                             14
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X          f.out+
X          k.out
X
X     The second non-standard form of macro expansion allows for
X     recursive macros.  It is possible to specify a $(_m_a_c_r_o___n_a_m_e)
X     or ${_m_a_c_r_o___n_a_m_e} expansion where _m_a_c_r_o___n_a_m_e contains more $(
X     ... ) or ${ ... } macro expansions itself.
X
X     For example $(CC$(_HOST)$(_COMPILER)) will first expand
X     CC$(_HOST)$(_COMPILER) to get a result and use that result
X     as the name of the macro to expand.  This is useful for
X     writing a makefile for more than one target environment.  As
X     an example consider the following hypothetical case. Suppose
X     that _HOST and _COMPILER are imported from the environment
X     and are set to represent the host machine type and the host
X     compiler respectively.
X
X          CFLAGS_VAX_CC = -c -O    # _HOST == "_VAX", _COMPILER == "_CC"
X          CFLAGS_PC_MSC = -c -ML   # _HOST == "_PC",  _COMPILER == "_MSC"
X
X          # redefine CFLAGS macro as:
X
X          CFLAGS := $(CFLAGS$(_HOST)$(_COMPILER))
X
X     This causes CFLAGS to take on a value that corresponds to
X     the environment in which the make is being invoked.
X
X     The final non-standard macro expansion is of the form:
X
X          string1{token_list}string2
X
X     where string1, string2 and token_list are expanded.  After
X     expansion, string1 is prepended to each token found in
X     token_list and string2 is appended to each resulting token
X     from the previous prepend.  string1 and string2 are not del-
X     imited by white space whereas the tokens in token_list are.
X     A null token in the token list is specified using "".  Thus
X     using another example we have:
X
X          test/{f1 f2}.o     --> test/f1.o test/f2.o
X          test/ {f1 f2}.o    --> test/ f1.o f2.o
X          test/{f1 f2} .o    --> test/f1 test/f2 .o
X          test/{"f1"  ""}.o  --> test/f1.o test/.o
X
X          and
X
X          test/{d1 d2}/{f1 f2}.o --> test/d1/f1.o test/d1/f2.o
X                                     test/d2/f1.o test/d2/f2.o
X
X     This last expansion is activated only when the first charac-
X     ters of _t_o_k_e_n___l_i_s_t appear immediately after the opening '{'
X     with no intervening white space.  The reason for this
X
X
X
Version 3.70                    UW                             15
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     restriction is the following incompatibility with Bourne
X     Shell recipes.  The line
X
X          { echo hello;}
X
X     is valid /bin/sh syntax; while
X
X          {echo hello;}
X
X     is not.  Hence the latter triggers the enhanced macro expan-
X     sion while the former causes it to be suppressed.  See the
X     SPECIAL MACROS section for a description of the special mac-
X     ros that ddmmaakkee defines and understands.
X
RRUULLEESS AANNDD TTAARRGGEETTSS
X     A makefile contains a series of entries that specify depen-
X     dencies.  Such entries are called _t_a_r_g_e_t_/_p_r_e_r_e_q_u_i_s_i_t_e or
X     _r_u_l_e definitions.  Each rule definition is optionally fol-
X     lowed by a set of lines that provide a recipe for updating
X     any targets defined by the rule.  Whenever ddmmaakkee attempts to
X     bring a target up to date and an explicit recipe is provided
X     with a rule defining the target, that recipe is used to
X     update the target.  A rule definition begins with a line
X     having the following syntax:
X
X          _<_t_a_r_g_e_t_s_> [_<_a_t_t_r_i_b_u_t_e_s_>] _<_r_u_l_e_o_p_> [_<_p_r_e_r_e_q_u_i_s_i_t_e_s_>] [;_<_r_e_c_i_p_e_>]
X
X     _t_a_r_g_e_t_s is a non-empty list of targets.  If the target is a
X     special target (see SPECIAL TARGETS section below) then it
X     must appear alone on the rule line.  For example:
X
X          .IMPORT .ERROR : ...
X
X     is not allowed since both .IMPORT and .ERROR are special
X     targets.  Special targets are not used in the construction
X     of the dependency graph and will not be made.
X
X     _a_t_t_r_i_b_u_t_e_s is a possibly empty list of attributes.  Any
X     attribute defined in the ATTRIBUTES section above may be
X     specified.  All attributes will be applied to the list of
X     named targets in the rule definition.  No other targets will
X     be affected.
X
X
X     NOTE:   As stated earlier, if both the target list and
X             prerequisite list are empty but the attributes list
X             is not, then the specified attributes affect all
X             targets in the makefile.
X
X
X     _r_u_l_e_o_p is a separator which is used to identify the targets
X     from the prerequisites.  Optionally it also provides a
X
X
X
Version 3.70                    UW                             16
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     facility for modifying the way in which ddmmaakkee handles the
X     making of the associated targets.  In its simplest form the
X     operator is a single ':', and need not be separated by white
X     space from its neighboring tokens.  It may additionally be
X     followed by any of the modifiers { !, ^, -, : }, where:
X
X
X     !!    says execute the recipe for the associated targets once
X          for each out of date prerequisite.  Ordinarily the
X          recipe is executed once for all out of date prere-
X          quisites at the same time.
X
X     ^^    says to insert the specified prerequisites, if any,
X          before any other prerequisites already associated with
X          the specified targets.  In general, it is not useful to
X          specify ^ with an empty list of prerequisites.
X
X     --    says to clear the previous list of prerequisites before
X          adding the new prerequisites.  Thus,
X
X               .SUFFIXES :
X               .SUFFIXES : .a .b
X
X          can be replaced by
X
X               .SUFFIXES :- .a .b
X
X          however the old form still works as expected.  NOTE:
X          .SUFFIXES is ignored by ddmmaakkee it is used here simply as
X          an example.
X
X     ::    When the rule operator is not modified by a second ':'
X          only one set of rules may be specified for making a
X          target.  Multiple definitions may be used to add to the
X          list of prerequisites that a target depends on.  How-
X          ever, if a target is multiply defined only one defini-
X          tion may specify a recipe for making the target.
X
X          When a target's rule operator is modified by a second
X          ':' (:: for example) then this definition may not be
X          the only definition with a recipe for the target.
X          There may be other :: target definition lines that
X          specify a different set of prerequisites with a dif-
X          ferent recipe for updating the target. Any such target
X          is made if any of the definitions find it to be out of
X          date with respect to the related prerequisites and the
X          corresponding recipe is used to update the target.
X
X          In the following simple example, each rule has a `::'
X          _r_u_l_e_o_p.  In such an operator we call the first `:' the
X          operator, and the second `:' the modifier.
X
X
X
X
Version 3.70                    UW                             17
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X          a.o :: a.c b.h
X             first recipe for making a.o
X
X          a.o :: a.y b.h
X             second recipe for making a.o
X
X          If a.o is found to be out of date with respect to a.c
X          then the first recipe is used to make a.o.  If it is
X          found out of date with respect to a.y then the second
X          recipe is used.  If a.o is out of date with respect to
X          b.h then both recipes are invoked to make a.o.  In the
X          last case the order of invocation corresponds to the
X          order in which the rule definitions appear in the
X          makefile.
X
X     Targets defined using a single `:' operator with a recipe
X     may be redefined again with a new recipe by using a `:'
X     operator with a `:' modifier.  This is equivalent to a tar-
X     get having been initially defined with a rule using a `:'
X     modifier.  Once a target is defined using a `:' modifier it
X     may not be defined again with a recipe using only the `:'
X     operator with no `:' modifier.  In both cases the use of a
X     `:' modifier creates a new list of prerequisites and makes
X     it the current prerequisite list for the target.  The `:'
X     operator with no recipe always modifies the current list of
X     prerequisites.  Thus assuming each of the following defini-
X     tions has a recipe attached, then:
X
X          joe :  fred ...     (1)
X          joe :: more ...     (2)
X
X          and
X
X          joe :: fred ...     (3)
X          joe :: more ...     (4)
X
X     are legal and mean:  add the recipe associated with (2), or
X     (4) to the set of recipes for joe, placing them after exist-
X     ing recipes for making joe.  The constructs:
X
X          joe :: fred ...     (5)
X          joe : more ... (6)
X
X          and
X
X          joe : fred ... (7)
X          joe : more ... (8)
X
X     are errors since we have two sets of perfectly good recipes
X     for making the target.
X
X
X
X
X
Version 3.70                    UW                             18
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     _p_r_e_r_e_q_u_i_s_i_t_e_s is a possibly empty list of targets that must
X     be brought up to date before making the current target.
X
X     _r_e_c_i_p_e is a short form and allows the user to specify short
X     rule definitions on a single line.  It is taken to be the
X     first recipe line in a larger recipe if additional lines
X     follow the rule definition.  If the semi-colon is present
X     but the recipe line is empty (ie. null string) then it is
X     taken to be an empty rule.  Any target so defined causes the
X     _D_o_n_'_t _k_n_o_w _h_o_w _t_o _m_a_k_e _._._. error message to be suppressed
X     when ddmmaakkee tries to make the target and fails.  This silence
X     is maintained for rules that are terminated by a semicolon
X     and have no following recipe lines, for targets listed on
X     the command line, for the first target found in the
X     makefile, and for any target having no recipe but containing
X     a list of prerequisites (see the COMPATIBILITY section for
X     an exception to this rule if the AUGMAKE (--AA) flag was
X     specified.
X
RREECCIIPPEESS
X     The traditional format used by most versions of Make defines
X     the recipe lines as arbitrary strings that may contain macro
X     expansions.  They follow a rule definition line and may be
X     spaced apart by comment or blank lines.  The list of recipe
X     lines defining the recipe is terminated by a new target
X     definition, a macro definition, or end-of-file.  Each recipe
X     line MMUUSSTT begin with a <<TTAABB>> character which may optionally
X     be followed with one or all of the characters _'_@_%_+_-_'.  The
X     _'_-_' indicates that non-zero exit values (ie. errors) are to
X     be ignored when this recipe line is executed, the _'_+_' indi-
X     cates that the current recipe line is to be executed using
X     the shell, the _'_%_' indicates that ddmmaakkee should swap itself
X     out to secondary storage (MSDOS only) before running the
X     recipe and the _'_@_' indicates that the recipe line should NOT
X     be echoed to the terminal prior to being executed.  Each
X     switch is off by default (ie. by default, errors are signi-
X     ficant, commands are echoed, no swapping is done and a shell
X     is used only if the recipe line contains a character found
X     in the value of the SHELLMETAS macro).  Global settings
X     activated via command line options or special attribute or
X     target names may also affect these settings.  An example
X     recipe:
X
X          target :
X               first recipe line
X               second recipe line, executed independently of the first.
X               @a recipe line that is not echoed
X               -and one that has errors ignored
X               %and one that causes dmake to swap out
X               +and one that is executed using a shell.
X
X
X
X
X
Version 3.70                    UW                             19
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     The second and new format of the recipe block begins the
X     block with the character '[' (the open group character) in
X     the last non-white space position of a line, and terminates
X     the block with the character ']' (the close group character)
X     in the first non-white space position of a line.  In this
X     form each recipe line need not have a leading TAB.  This is
X     called a recipe group.  Groups so defined are fed intact as
X     a single unit to a shell for execution whenever the
X     corresponding target needs to be updated.  If the open group
X     character '[' is preceded by one or all of -, @ or % then
X     they apply to the entire group in the same way that they
X     apply to single recipe lines.  You may also specify '+' but
X     it is redundant as a shell is already being used to run the
X     recipe.  See the MAKING TARGETS section for a description of
X     how ddmmaakkee invokes recipes.  Here is an example of a group
X     recipe:
X
X          target :
X          [
X               first recipe line
X               second recipe line
X               all of these recipe lines are fed to a
X               single copy of a shell for execution.
X          ]
X
X
TTEEXXTT DDIIVVEERRSSIIOONNSS
X     ddmmaakkee supports the notion of text diversions.  If a recipe
X     line contains the macro expression
X
X          $(mktmp[,[_f_i_l_e][,_t_e_x_t]] _d_a_t_a)
X
X     then all text contained in the _d_a_t_a expression is expanded
X     and is written to a temporary file.  The return value of the
X     macro is the name of the temporary file.
X
X     _d_a_t_a can be any text and must be separated from the 'mktmp'
X     portion of the macro name by white-space.  The only restric-
X     tion on the data text is that it must contain a balanced
X     number of parentheses of the same kind as are used to ini-
X     tiate the $(mktmp ...) expression.  For example:
X
X          $(mktmp $(XXX))
X
X     is legal and works as expected, but:
X
X          $(mktmp text (to dump to file)
X
X     is not legal.  You can achieve what you wish by either
X     defining a macro that expands to '(' or by using {} in the
X     macro expression; like this:
X
X
X
X
Version 3.70                    UW                             20
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X          ${mktmp text (to dump to file}
X
X     Since the temporary file is opened when the macro containing
X     the text diversion expression is expanded, diversions may
X     now be nested and any diversions that are created as part of
X     ':=' macro expansions persist for the duration of the ddmmaakkee
X     run.  The diversion text may contain the same escape codes
X     as those described in the MACROS section.  Thus if the _d_a_t_a
X     text is to contain new lines they must be inserted using the
X     \n escape sequence.  For example the expression:
X
X          all:
X               cat $(mktmp this is a\n\
X               test of the text diversion\n)
X
X     is replaced by:
X
X          cat /tmp/mk12294AA
X
X     where the temporary file contains two lines both of which
X     are terminated by a new-line.  If the _d_a_t_a text spans multi-
X     ple lines in the makefile then each line must be continued
X     via the use of a \.  A second more illustrative example gen-
X     erates a response file to an MSDOS link command:
X
X          OBJ = fred.obj mary.obj joe.obj
X          all : $(OBJ)
X               link @$(mktmp $(^:t"+\n")\n)
X
X     The result of making `all' in the second example is the com-
X     mand:
X
X          link @/tmp/mk02394AA
X
X     where the temporary file contains:
X
X          fred.obj+
X          mary.obj+
X          joe.obj
X
X     The last line of the file is terminated by a new-line which
X     is inserted due to the \n found at the end of the _d_a_t_a
X     string.
X
X     If the optional _f_i_l_e specifier is present then its expanded
X     value is the name of the temporary file to create.  Whenever
X     a $(mktmp ...) macro is expanded the macro $(TMPFILE) is set
X     to a new temporary file name.  Thus the construct:
X
X          $(mktmp,$(TMPFILE) data)
X
X     is completely equivalent to not specifying the $(TMPFILE)
X
X
X
Version 3.70                    UW                             21
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     optional argument.  Another example that would be useful for
X     MSDOS users with a Turbo-C compiler
X
X          $(mktmp,turboc.cfg $(CFLAGS))
X
X     will place the contents of CFLAGS into a local _t_u_r_b_o_c_._c_f_g
X     file.  The second optional argument, _t_e_x_t, if present alters
X     the name of the value returned by the $(mktmp ...) macro.
X
X     Under MS-DOS text diversions may be a problem.  Many DOS
X     tools require that path names which contain directories use
X     the \ character to delimit the directories.  Some users how-
X     ever wish to use the '/' to delimit pathnames and use
X     environments that allow them to do so.  The macro USESHELL
X     is set to "yes" if the current recipe is forced to use a
X     shell via the .USESHELL or '+' directives, otherwise its
X     value is "no".  The ddmmaakkee startup files define the macro
X     DIVFILE whose value is either the value of TMPFILE or the
X     value of TMPFILE edited to replace any '/' characters to the
X     appropriate value based on the current shell and whether it
X     will be used to execute the recipe.
X
X     Previous versions of ddmmaakkee defined text diversions using <+,
X     +> strings, where <+ started a text diversion and +> ter-
X     minated one.  ddmmaakkee is backward compatible with this con-
X     struct if the <+ and +> appear literally on the same recipe
X     line or in the same macro value string.  In such instances
X     the expression:
X
X          <+data+>
X
X     is mapped to:
X
X          $(mktmp data)
X
X     which is fully output compatible with the earlier construct.
X     <+, +> constructs whose text spans multiple lines must be
X     converted by hand to use $(mktmp ...).
X
X     If the environment variable TMPDIR is defined then the tem-
X     porary file is placed into the directory specified by that
X     variable.  A makefile can modify the location of temporary
X     files by defining a macro named TMPDIR and exporting it
X     using the .EXPORT special target.
X
SSPPEECCIIAALL TTAARRGGEETTSS
X     This section describes the special targets that are recog-
X     nized by ddmmaakkee.  Some are affected by attributes and others
X     are not.
X
X     ..EERRRROORR        If defined then the recipe associated with
X                   this target is executed whenever an error
X
X
X
Version 3.70                    UW                             22
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X                   condition is detected by ddmmaakkee.  All attri-
X                   butes that can be used with any other target
X                   may be used with this target.  Any prere-
X                   quisites of this target will be brought up to
X                   date during its processing.  NOTE:  errors
X                   will be ignored while making this target, in
X                   extreme cases this may cause some problems.
X
X     ..EEXXPPOORRTT       All prerequisites associated with this target
X                   are assumed to correspond to macro names and
X                   they and their values are exported to the
X                   environment as environment strings at the
X                   point in the makefile at which this target
X                   appears.  Any attributes specified with this
X                   target are ignored.  Only macros which have
X                   been assigned a value in the makefile prior to
X                   the export directive are exported, macros as
X                   yet undefined are not exported.
X
X     ..IIMMPPOORRTT       Prerequisite names specified for this target
X                   are searched for in the environment and
X                   defined as macros with their value taken from
X                   the environment.  If the special name ..EEVVEERRYY----
X                   TTHHIINNGG is used as a prerequisite name then all
X                   environment variables defined in the environ-
X                   ment are imported.  The functionality of the
X                   --ee flag can be forced by placing the construct
X                   _._I_M_P_O_R_T _: _._E_V_E_R_Y_T_H_I_N_G at the start of a
X                   makefile.  Similarly, by placing the construct
X                   at the end, one can emulate the effect of the
X                   --EE command line flag.  If a prerequisite name
X                   cannot be found in the environment an error
X                   message is issued.  .IMPORT accepts the
X                   .IGNORE attribute.  When given, it causes
X                   ddmmaakkee to ignore the above error.  See the MAC-
X                   ROS section for a description of the process-
X                   ing of imported macro values.
X
X     ..IINNCCLLUUDDEE      Parse another makefile just as if it had been
X                   located at the point of the .INCLUDE in the
X                   current makefile.  The list of prerequisites
X                   gives the list of makefiles to try to read.
X                   If the list contains multiple makefiles then
X                   they are read in order from left to right.
X                   The following search rules are used when try-
X                   ing to locate the file.  If the filename is
X                   surrounded by " or just by itself then it is
X                   searched for in the current directory.  If it
X                   is not found it is then searched for in each
X                   of the directories specified for the .INCLU-
X                   DEDIRS special target.  If the file name is
X                   surrounded by < and >, (ie.
X
X
X
Version 3.70                    UW                             23
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X                   <my_spiffy_new_makefile>) then it is searched
X                   for only in the directories given by the
X                   .INCLUDEDIRS special target.  In both cases if
X                   the file name is a fully qualified name start-
X                   ing at the root of the file system then it is
X                   only searched for once, and the .INCLUDEDIRS
X                   list is ignored.  .INCLUDE accepts the .IGNORE
X                   and .SETDIR attributes.  If .IGNORE attribute
X                   is given and the file cannot be found then
X                   ddmmaakkee continues processing, otherwise an error
X                   message is generated.  The .SETDIR attribute
X                   causes ddmmaakkee to change directories to the
X                   specified directory prior to attempting the
X                   include operation.
X
X     ..IINNCCLLUUDDEEDDIIRRSS  The list of prerequisites specified for this
X                   target defines the set of directories to
X                   search when trying to include a makefile.
X
X     ..KKEEEEPP__SSTTAATTEE   This special target is a synonym for the macro
X                   definition
X
X                        .KEEP_STATE := _state.mk
X
X                   It's effect is to turn on STATE keeping and to
X                   define ___s_t_a_t_e_._m_k as the state file.
X
X     ..MMAAKKEEFFIILLEESS    The list of prerequisites is the set of files
X                   to try to read as the default makefile.  By
X                   default this target is defined as:
X
X                        .MAKEFILES : makefile.mk Makefile
X                   makefile
X
X
X     ..SSOOUURRCCEE       The prerequisite list of this target defines a
X                   set of directories to check when trying to
X                   locate a target file name.  See the section on
X                   BINDING of targets for more information.
X
X     ..SSOOUURRCCEE..ssuuffff  The same as .SOURCE, except that the
X                   .SOURCE.suff list is searched first when try-
X                   ing to locate a file matching the a target
X                   whose name ends in the suffix .suff.
X
X     ..RREEMMOOVVEE       The recipe of this target is used whenever
X                   ddmmaakkee needs to remove intermediate targets
X                   that were made but do not need to be kept
X                   around.  Such targets result from the applica-
X                   tion of transitive closure on the dependency
X                   graph.
X
X
X
X
Version 3.70                    UW                             24
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     In addition to the special targets above, several other
X     forms of targets are recognized and are considered special,
X     their exact form and use is defined in the sections that
X     follow.
X
SSPPEECCIIAALL MMAACCRROOSS
X     ddmmaakkee defines a number of special macros.  They are divided
X     into three classes: control macros, run-time macros, and
X     function macros.  The control macros are used by ddmmaakkee to
X     configure its actions, and are the preferred method of doing
X     so.  In the case when a control macro has the same function
X     as a special target or attribute they share the same name as
X     the special target or attribute.  The run-time macros are
X     defined when ddmmaakkee makes targets and may be used by the user
X     inside recipes.  The function macros provide higher level
X     functions dealing with macro expansion and diversion file
X     processing.
X
CCOONNTTRROOLL MMAACCRROOSS
SHAR_EOF
true || echo 'restore of dmake/man/dmake.p failed'
fi
echo 'End of part 16, continue with part 17'
echo 17 > _shar_seq_.tmp
exit 0

exit 0 # Just in case...
--
Kent Landfield                   INTERNET: [e-mail]
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    [phone]         FAX:      [phone]
Please send comp.sources.misc-related mail to [e-mail].