Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/misc/volume19/dmake/part14

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

Newsgroups: comp.sources.misc
From: Dennis Vadura <[e-mail]>
Subject:  v19i035:  dmake - dmake version 3.7, Part14/37
Message-ID: <[e-mail]>
X-Md4-Signature: 8db0556316dc2c75d909ad2e17e14eec
Date: Sun, 12 May 1991 00:17:53 GMT
Approved: [e-mail]

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

---- Cut Here and feed the following to sh ----
#!/bin/sh
# this is dmake.shar.14 (part 14 of a multipart archive)
# do not concatenate these parts, unpack them in order with /bin/sh
# file dmake/man/dmake.nc continued
#
if test ! -r _shar_seq_.tmp; then
    echo 'Please unpack part 1 first!'
    exit 1
fi
(read Scheck
 if test "$Scheck" != 14; 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.nc' &&
X                     files to be handed to the command inter-
X                     preter.  For example, if it is defined as
X                     .sh, then all temporary files created by
X                     dmake will end in the suffix .sh.  Under
X                     MSDOS if you are using command.com as your
X                     GROUPSHELL, then this suffix must be set to
X                     .bat in order for group recipes to function
X                     correctly.  The setting of GROUPSUFFIX and
X                     GROUPSHELL is done automatically for
X                     command.com in the startup.mk files.
X
X     MAKE            Is defined in the startup file by default.
X                     The string $(MAKE) is recognized when using
X                     the -n option for single line recipes.  Ini-
X                     tially this macro is defined to have the
X                     value "$(MAKECMD) $(MFLAGS)".
X
X     MAKESTARTUP     This macro defines the full path to the ini-
X                     tial startup makefile.  Use the -V command
X                     line option to discover its initial value.
X
X
X
X
X
Version 3.70                    UW                             27
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     MAXLINELENGTH   This macro defines the maximum size of a
X                     single line of makefile input text.  The
X                     size is specified as a number, the default
X                     value is defined internally and is shown via
X                     the -V option.  A buffer of this size plus 2
X                     is allocated for reading makefile text.  The
X                     buffer is freed before any targets are made,
X                     thereby allowing files containing long input
X                     lines to be processed without consuming
X                     memory during the actual make.
X
X     MAXPROCESS      Specify the maximum number of child
X                     processes to use when making targets.  The
X                     default value of this macro is "1" and its
X                     value cannot exceed the value of the macro
X                     MAXPROCESSLIMIT.  Setting the value of MAX-
X                     PROCESS on the command line or in the
X                     makefile is equivalent to supplying a
X                     corresponding value to the -P flag on the
X                     command line.
X
X     PREP            This macro defines the number of iterations
X                     to be expanded automatically when processing
X                     % rule definitions of the form:
X
X                     % : %.suff
X
X                     See the sections on PERCENT(%) RULES for
X                     details on how PREP is used.
X
X     SHELL           This macro defines the full path to the exe-
X                     cutable image to be used as the shell when
X                     processing single line recipes.  This macro
X                     must be defined if recipes requiring the
X                     shell for execution are to be used.  It is
X                     assigned a default value in the startup
X                     makefile.  Under UNIX this value is /bin/sh.
X
X     SHELLFLAGS      This macro gives the set of flags to pass to
X                     the shell when invoking it to execute a sin-
X                     gle line recipe.  The value of the macro is
X                     the list of flags with a leading switch
X                     indicator.  (ie. `-' under UNIX)
X
X     SHELLMETAS      Each time dmake executes a single recipe
X                     line (not a group recipe) the line is
X                     searched for any occurrence of a character
X                     defined in the value of SHELLMETAS.  If such
X                     a character is found the recipe line is
X                     defined to require a shell to ensure its
X                     correct execution.  In such instances a
X                     shell is used to invoke the recipe line.  If
X
X
X
Version 3.70                    UW                             28
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X                     no match is found the recipe line is exe-
X                     cuted without the use of a shell.
X
X
X     There is only one character valued macro defined by dmake:
X     SWITCHAR contains the switch character used to introduce
X     options on command lines.  For UNIX its value is '-', and
X     for MSDOS its value may be '/' or '-'.  The macro is inter-
X     nally defined and is not user setable.  The MSDOS version of
X     dmake attempts to first extract SWITCHAR from an environment
X     variable of the same name.  If that fails it then attempts
X     to use the undocumented getswitchar system call, and returns
X     the result of that.  Under MSDOS version 4.0 you must set
X     the value of the environment macro SWITCHAR to '/' to obtain
X     predictable behavior.
X
X     All boolean macros currently understood by dmake correspond
X     directly to the previously defined attributes.  These macros
X     provide a second way to apply global attributes, and
X     represent the preferred method of doing so.  They are used
X     by assigning them a value.  If the value is not a NULL
X     string then the boolean condition is set to on.  If the
X     value is a NULL string then the condition is set to off.
X     There are five conditions defined and they correspond
X     directly to the attributes of the same name.  Their meanings
X     are defined in the ATTRIBUTES section above.  The macros
X     are: .EPILOG, .IGNORE, .MKSARGS, .NOINFER, .PRECIOUS, .PRO-
X     LOG, .SEQUENTIAL, .SILENT, .SWAP, and .USESHELL.  Assigning
X     any of these a non NULL value will globally set the
X     corresponding attribute to on.
X
RUN_TIME MACROS
X     These macros are defined when dmake is making targets, and
X     may take on different values for each target.  $@ is defined
X     to be the full target name, $? is the list of all out of
X     date prerequisites, $& is the list of all prerequisites, $>
X     is the name of the library if the current target is a
X     library member, and $< is the list of prerequisites speci-
X     fied in the current rule.  If the current target had a
X     recipe inferred then $< is the name of the inferred prere-
X     quisite even if the target had a list of prerequisites sup-
X     plied using an explicit rule that did not provide a recipe.
X     In such situations $& gives the full list of prerequisites.
X
X     $* is defined as $(@:db) when making targets with explicit
X     recipes and is defined as the value of % when making targets
X     whose recipe is the result of an inference.  In the first
X     case $* is the target name with no suffix, and in the second
X     case, is the value of the matched % pattern from the associ-
X     ated %-rule.  $^ expands to the set of out of date prere-
X     quisites taken from the current value of $<.  In addition to
X     these, $$ expands to $, {{ expands to {, }} expands to },
X
X
X
Version 3.70                    UW                             29
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     and the strings <+ and +> are recognized as respectively
X     starting and terminating a text diversion when they appear
X     literally together in the same input line.
X
X     The difference between $? and $^ can best be illustrated by
X     an example, consider:
X
X          fred.out : joe amy hello
X               rules for making fred
X
X          fred.out : my.c your.h his.h her.h   # more prerequisites
X
X     Assume joe, amy, and my.c are newer then fred.out.  When
X     dmake executes the recipe for making fred.out the values of
X     the following macros will be:
X
X          $@ --> fred.out
X          $* --> fred
X          $? --> joe amy my.c  # note the difference between $? and $^
X          $^ --> joe amy
X          $< --> joe amy hello
X          $& --> joe amy hello my.c your.h his.h her.h
X
X
FUNCTION MACROS
X     dmake supports a full set of functional macros.  One of
X     these, the $(mktmp ...) macro, is discussed in detail in the
X     TEXT DIVERSION section and is not covered here.
X
X
X          $(null,text true false)
X               expands the value of text. If it is NULL then the
X               macro returns the value of the expansion of true
X               and the expansion of false otherwise.  The terms
X               true, and false must be strings containing no
X               white-space.
X
X          $(!null,text true false)
X               Behaves identically to the previous macro except
X               that the true string is chosen if the expansion of
X               text is not NULL.
X
X          $(eq,text_a,text_b true false)
X               expands text_a and text_b and compares their
X               results.  If equal it returns the result of the
X               expansion of the true term, otherwise it returns
X               the expansion of the false term.
X
X          $(!eq,text_a,text_b true false)
X               Behaves identically to the previous macro except
X               that the true string is chosen if the expansions
X               of the two strings are not equal
X
X
X
Version 3.70                    UW                             30
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X          $(shell command)
X               Runs command as if it were part of a recipe and
X               returns, separated by a single space, all the
X               non-white space terms written to stdout by the
X               command.  For example:
X
X                    $(shell ls *.c)
X
X               will return "a.c b.c c.c d.c" if the files exist
X               in the current directory.  The recipe modification
X               flags [+@%-] are honored if they appear as the
X               first characters in the command.  For example:
X
X                    $(shell +ls *.c)
X
X               will run the command using the current shell.
X
X          $(sort list)
X               Will take all white-space separated tokens in list
X               and will return their sorted equivalent list.
X
X          $(strip data)
X               Will replace all strings of white-space in data by
X               a single space.
X
X          $(subst,pat,replacement data)
X               Will search for pat in data and will replace any
X               occurrence of pat with the replacement string.
X               The expansion
X
X                    $(subst,.o,.c $(OBJECTS))
X
X               is equivalent to:
X
X                    $(OBJECTS:s/.o/.c/)
X
X
DYNAMIC PREREQUISITES
X     dmake looks for prerequisites whose names contain macro
X     expansions during target processing.  Any such prerequisites
X     are expanded and the result of the expansion is used as the
X     prerequisite name.  As an example the line:
X
X          fred : $$@.c
X
X     causes the $$@ to be expanded when dmake is making fred, and
X     it resolves to the target fred.  This enables dynamic prere-
X     quisites to be generated.  The value of @ may be modified by
X     any of the valid macro modifiers.  So you can say for exam-
X     ple:
X
X          fred.out : $$(@:b).c
X
X
X
Version 3.70                    UW                             31
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     where the $$(@:b) expands to fred.  Note the use of $$
X     instead of $ to indicate the dynamic expansion, this is due
X     to the fact that the rule line is expanded when it is ini-
X     tially parsed, and $$ then returns $ which later triggers
X     the dynamic prerequisite expansion.  If you really want a $
X     to be part of a prerequisite name you must use $$$$.
X     Dynamic macro expansion is performed in all user defined
X     rules, and the special targets .SOURCE*, and .INCLUDEDIRS.
X
BINDING TARGETS
X     This operation takes a target name and binds it to an exist-
X     ing file, if possible.  dmake makes a distinction between
X     the internal target name of a target and its associated
X     external file name.  Thus it is possible for a target's
X     internal name and its external file name to differ.  To per-
X     form the binding, the following set of rules is used.
X     Assume that we are trying to bind a target whose name is of
X     the form X.suff, where .suff is the suffix and X is the stem
X     portion (ie. that part which contains the directory and the
X     basename).  dmake takes this target name and performs a
X     series of search operations that try to find a suitably
X     named file in the external file system.  The search opera-
X     tion is user controlled via the settings of the various
X     .SOURCE targets.
X
X          1.   If target has the .SYMBOL attribute set then look
X               for it in the library.  If found, replace the tar-
X               get name with the library member name and continue
X               with step 2.  If the name is not found then
X               return.
X
X          2.   Extract the suffix portion (that following the
X               `.') of the target name.  If the suffix is not
X               null, look up the special target .SOURCE.<suff>
X               (<suff> is the suffix). If the special target
X               exists then search each directory given in the
X               .SOURCE.<suff> prerequisite list for the target.
X               If the target's suffix was null (ie. .suff was
X               empty) then perform the above search but use the
X               special target .SOURCE.NULL instead.  If at any
X               point a match is found then terminate the search.
X               If a directory in the prerequisite list is the
X               special name `.NULL ' perform a search for the
X               full target name without prepending any directory
X               portion (ie. prepend the NULL directory).  (a
X               default target of '.SOURCE : .NULL' is defined by
X               dmake at startup, and is user redefinable)
X
X          3.   The search in step 2. failed.  Repeat the same
X               search but this time use the special target
X               .SOURCE.
X
X
X
X
Version 3.70                    UW                             32
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X          4.   The search in step 3. failed.  If the target has
X               the library member attribute (.LIBMEMBER) set then
X               try to find the target in the library which was
X               passed along with the .LIBMEMBER attribute (see
X               the MAKING LIBRARIES section).  The bound file
X               name assigned to a target which is successfully
X               located in a library is the same name that would
X               be assigned had the search failed (see 5.).
X
X          5.   The search failed.  Either the target was not
X               found in any of the search directories or no
X               applicable .SOURCE special targets exist.  If
X               applicable .SOURCE special targets exist, but the
X               target was not found, then dmake assigns the first
X               name searched as the bound file name.  If no
X               applicable .SOURCE special targets exist, then the
X               full original target name becomes the bound file
X               name.
X
X     There is potential here for a lot of search operations.  The
X     trick is to define .SOURCE.x special targets with short
X     search lists and leave .SOURCE as short as possible.  The
X     search algorithm has the following useful side effect.  When
X     a target having the .LIBMEMBER (library member) attribute is
X     searched for, it is first searched for as an ordinary file.
X     When a number of library members require updating it is
X     desirable to compile all of them first and to update the
X     library at the end in a single operation.  If one of the
X     members does not compile and dmake stops, then the user may
X     fix the error and make again.  dmake will not remake any of
X     the targets whose object files have already been generated
X     as long as none of their prerequisite files have been modi-
X     fied as a result of the fix.
X
X     When defining .SOURCE and .SOURCE.x targets the construct
X
X          .SOURCE :
X          .SOURCE : fred gery
X
X     is equivalent to
X
X          .SOURCE :- fred gery
X
X     dmake correctly handles the UNIX Make variable VPATH.  By
X     definition VPATH contains a list of ':' separated direc-
X     tories to search when looking for a target.  dmake maps
X     VPATH to the following special rule:
X
X          .SOURCE :^ $(VPATH:s/:/ /)
X
X     Which takes the value of VPATH and sets .SOURCE to the same
X     set of directories as specified in VPATH.
X
X
X
Version 3.70                    UW                             33
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
PERCENT(%) RULES AND MAKING INFERENCES
X     When dmake makes a target, the target's set of prerequisites
X     (if any) must exist and the target must have a recipe which
X     dmake can use to make it.  If the makefile does not specify
X     an explicit recipe for the target then dmake uses special
X     rules to try to infer a recipe which it can use to make the
X     target.  Previous versions of Make perform this task by
X     using rules that are defined by targets of the form
X     .<suffix>.<suffix> and by using the .SUFFIXES list of suf-
X     fixes.  The exact workings of this mechanism were sometimes
X     difficult to understand and often limiting in their useful-
X     ness.  Instead, dmake supports the concept of %-meta rules.
X     The syntax and semantics of these rules differ from standard
X     rule lines as follows:
X
X          <%-target> [<attributes>] <ruleop> [<%-prerequisites>] [;<recipe>]
X
X     where %-target is a target containing exactly a single `%'
X     sign, attributes is a list (possibly empty) of attributes,
X     ruleop is the standard set of rule operators, %-prere-
X     quisites , if present, is a list of prerequisites containing
X     zero or more `%' signs, and recipe, if present, is the first
X     line of the recipe.
X
X     The %-target defines a pattern against which a target whose
X     recipe is being inferred gets matched.  The pattern match
X     goes as follows:  all chars are matched exactly from left to
X     right up to but not including the % sign in the pattern, %
X     then matches the longest string from the actual target name
X     not ending in the suffix given after the % sign in the pat-
X     tern.  Consider the following examples:
X
X          %.c       matches fred.c but not joe.c.Z
X          dir/%.c   matches dir/fred.c but not dd/fred.c
X          fred/%    matches fred/joe.c but not f/joe.c
X          %         matches anything
X
X     In each case the part of the target name that matched the %
X     sign is retained and is substituted for any % signs in the
X     prerequisite list of the %-meta rule when the rule is
X     selected during inference and dmake constructs the new
X     dependency.  As an example the following %-meta rules
X     describe the following:
X
X          %.c : %.y ; recipe...
X
X     describes how to make any file ending in .c if a correspond-
X     ing file ending in .y can be found.
X
X          foo%.o : fee%.k ; recipe...
X
X     is used to describe how to make fooxxxx.o from feexxxx.k.
X
X
X
Version 3.70                    UW                             34
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X          %.a :; recipe...
X
X     describes how to make a file whose suffix is .a without
X     inferring any prerequisites.
X
X          %.c : %.y yaccsrc/%.y ; recipe...
X
X     is a short form for the construct:
X
X          %.c : %.y ; recipe...
X          %.c : yaccsrc/%.y ; recipe...
X
X     ie. It is possible to specify the same recipe for two
X     %-rules by giving more than one prerequisite in the prere-
X     quisite list.  A more interesting example is:
X
X          % : RCS/%,v ; co $@
X
X     which describes how to take any target and check it out of
X     the RCS directory if the corresponding file exists in the
X     RCS directory.  The equivalent SCCS rule would be:
X
X          % : s.% ; get $@
X
X
X     The previous RCS example defines an infinite rule, because
X     it says how to make anything from RCS/%,v, and anything also
X     includes RCS/fred.c,v.  To limit the size of the graph that
X     results from such rules dmake uses the macro variable PREP
X     (stands for % repetition).  By default the value of this
X     variable is 0, which says that no repetitions of a %-rule
X     are to be generated.  If it is set to something greater than
X     0, then that many repetitions of any infinite %-rule are
X     allowed.  If in the above example PREP was set to 1, then
X     dmake would generate the dependency graph:
X
X          % --> RCS/%,v --> RCS/RCS/%,v,v
X
X     Where each link is assigned the same recipe as the first
X     link.  PREP should be used only in special cases, since it
X     may result in a large increase in the number of possible
X     prerequisites tested.  dmake further assumes that any target
X     that has no suffix can be made from a prerequisite that has
X     at least one suffix.
X
X     dmake supports dynamic prerequisite generation for prere-
X     quisites of %-meta rules.  This is best illustrated by an
X     example.  The RCS rule shown above can infer how to check
X     out a file from a corresponding RCS file only if the target
X     is a simple file name with no directory information.  That
X     is, the above rule can infer how to find RCS/fred.c,v from
X     the target fred.c, but cannot infer how to find
X
X
X
Version 3.70                    UW                             35
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     srcdir/RCS/fred.c,v from srcdir/fred.c because the above
X     rule will cause dmake to look for RCS/srcdir/fred.c,v; which
X     does not exist (assume that srcdir has its own RCS directory
X     as is the common case).
X
X     A more versatile formulation of the above RCS check out rule
X     is the following:
X
X          % :  $$(@:d)RCS/$$(@:f),v : co $@
X
X     This rule uses the dynamic macro $@ to specify the prere-
X     quisite to try to infer.  During inference of this rule the
X     macro $@ is set to the value of the target of the %-meta
X     rule and the appropriate prerequisite is generated by
X     extracting the directory portion of the target name (if
X     any), appending the string RCS/ to it, and appending the
X     target file name with a trailing ,v attached to the previous
X     result.
X
X     dmake can also infer indirect prerequisites.  An inferred
X     target can have a list of prerequisites added that will not
X     show up in the value of $< but will show up in the value of
X     $? and $&.  Indirect prerequisites are specified in an
X     inference rule by quoting the prerequisite with single
X     quotes.  For example, if you had the explicit dependency:
X
X          fred.o : fred.c ; rule to make fred.o
X          fred.o : local.h
X
X     then this can be inferred for fred.o from the following
X     inference rule:
X
X          %.o : %.c 'local.h' ; rule to make a .o from a .c
X
X     You may infer indirect prerequisites that are a function of
X     the value of '%' in the current rule.  The meta-rule:
X
X          %.o : %.c '$(INC)/%.h' ; rule to make a .o from a .c
X
X     infers an indirect prerequisite found in the INC directory
X     whose name is the same as the expansion of $(INC), and the
X     prerequisite name depends on the base name of the current
X     target.  The set of indirect prerequisites is attached to
X     the meta rule in which they are specified and are inferred
X     only if the rule is used to infer a recipe for a target.
X     They do not play an active role in driving the inference
X     algorithm.  The construct:
X
X          %.o : %.c %.f 'local.h'; recipe
X
X     is equivalent to:
X
X
X
X
Version 3.70                    UW                             36
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X          %.o : %.c 'local.h' : recipe
X          %.o : %.f 'local.h' : recipe
X
X
X     If any of the attributes .SETDIR, .EPILOG, .PROLOG, .SILENT,
X     .USESHELL, .SWAP, .PRECIOUS, .LIBRARY, .NOSTATE and .IGNORE
X     are given for a %-rule then when that rule is bound to a
X     target as the result of an inference, the target's set of
X     attributes is augmented by the attributes from the above set
X     that are specified in the bound %-rule.  Other attributes
X     specified for %-meta rules are not inherited by the target.
X     The .SETDIR attribute is treated in a special way.  If the
X     target already had a .SETDIR attribute set then dmake
X     changes to that directory prior to performing the inference.
X     During inference any .SETDIR attributes for the inferred
X     prerequisite are honored.  The directories must exist for a
X     %-meta rule to be selected as a possible inference path.  If
X     the directories do not exist no error message is issued,
X     instead the corresponding path in the inference graph is
X     rejected.
X
X     dmake also supports the old format special target
X     .<suffix>.<suffix> by identifying any rules of this form and
X     mapping them to the appropriate %-rule.  So for example if
X     an old makefile contains the construct:
X
X          .c.o :; cc -c $< -o $@
X
X     dmake maps this into the following %-rule:
X
X          %.o : %.c; cc -c $< -o $@
X
X     Furthermore, dmake understands several SYSV AUGMAKE special
X     targets and maps them into corresponding %-meta rules.
X     These transformation must be enabled by providing the -A
X     flag on the command line or by setting the value of AUGMAKE
X     to non-NULL.  The construct
X
X          .suff :; recipe
X
X     gets mapped into:
X
X          % : %.suff; recipe
X
X     and the construct
X
X          .c~.o :; recipe
X
X     gets mapped into:
X
X          %.o : s.%.c ; recipe
X
X
X
X
Version 3.70                    UW                             37
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     In general, a special target of the form .<str>~ is replaced
X     by the %-rule construct s.%.<str>, thereby providing support
X     for the syntax used by SYSV AUGMAKE for providing SCCS sup-
X     port.  When enabled, these mappings allow processing of
X     existing SYSV makefiles without modifications.
X
X     dmake bases all of its inferences on the inference graph
X     constructed from the %-rules defined in the makefile.  It
X     knows exactly which targets can be made from which prere-
X     quisites by making queries on the inference graph.  For this
X     reason .SUFFIXES is not needed and is completely ignored.
X
X     For a %-meta rule to be inferred as the rule whose recipe
X     will be used to make a target, the target's name must match
X     the %-target pattern, and any inferred %-prerequisite must
X     already exist or have an explicit recipe so that the prere-
X     quisite can be made.  Without transitive closure on the
X     inference graph the above rule describes precisely when an
X     inference match terminates the search.  If transitive clo-
X     sure is enabled (the usual case), and a prerequisite does
X     not exist or cannot be made, then dmake invokes the infer-
X     ence algorithm recursively on the prerequisite to see if
X     there is some way the prerequisite can be manufactured.
X     For, if the prerequisite can be made then the current target
X     can also be made using the current %-meta rule.  This means
X     that there is no longer a need to give a rule for making a
X     .o from a .y if you have already given a rule for making a
X     .o from a .c and a .c from a .y.  In such cases dmake can
X     infer how to make the .o from the .y via the intermediary .c
X     and will remove the .c when the .o is made.  Transitive clo-
X     sure can be disabled by giving the -T switch on the command
X     line.
X
X     A word of caution.  dmake bases its transitive closure on
X     the %-meta rule targets.  When it performs transitive clo-
X     sure it infers how to make a target from a prerequisite by
X     performing a pattern match as if the potential prerequisite
X     were a new target.  The set of rules:
X
X          %.o : %.c :; rule for making .o from .c
X          %.c : %.y :; rule for making .c from .y
X          % : RCS/%,v :; check out of RCS file
X
X     will, by performing transitive closure, allow dmake to infer
X     how to make a .o from a .y using a .c as an intermediate
X     temporary file.  Additionally it will be able to infer how
X     to make a .y from an RCS file, as long as that RCS file is
X     in the RCS directory and has a name which ends in .y,v.  The
X     transitivity computation is performed dynamically for each
X     target that does not have a recipe.  This has potential to
X     be costly if the %-meta rules are not carefully specified.
X     The .NOINFER attribute is used to mark a %-meta node as
X
X
X
Version 3.70                    UW                             38
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     being a final target during inference.  Any node with this
X     attribute set will not be used for subsequent inferences.
X     As an example the node RCS/%,v is marked as a final node
X     since we know that if the RCS file does not exist there
X     likely is no other way to make it.  Thus the standard
X     startup makefile contains an entry similar to:
X          .NOINFER : RCS/%,v
X     Thereby indicating that the RCS file is the end of the
X     inference chain.
X
X     Whenever the inference algorithm determines that a target
X     can be made from more than one prerequisite and the infer-
X     ence chains for the two methods are the same length the
X     algorithm reports an ambiguity and prints the ambiguous
X     inference chains.
X
X     dmake tries to remove intermediate files resulting from
X     transitive closure if the file is not marked as being PRE-
X     CIOUS, or the -u flag was not given on the command line, and
X     if the inferred intermediate did not previously exist.
X     Intermediate targets that existed prior to being made are
X     never removed.  This is in keeping with the philosophy that
X     dmake should never remove things from the file system that
X     it did not add.  If the special target .REMOVE is defined
X     and has a recipe then dmake constructs a list of the inter-
X     mediate files to be removed and makes them prerequisites of
X     .REMOVE.  It then makes .REMOVE thereby removing the prere-
X     quisites if the recipe of .REMOVE says to.  Typically
X     .REMOVE is defined in the startup file as:
X
X          .REMOVE :; $(RM) $<
X
MAKING TARGETS
X     In order to update a target dmake must execute a recipe.
X     When a recipe needs to be executed it is first expanded so
X     that any macros in the recipe text are expanded, and it is
X     then either executed directly or passed to a shell.  dmake
X     supports two types of recipes.  The regular recipes and
X     group recipes.
X
X     When a regular recipe is invoked dmake executes each line of
X     the recipe separately using a new copy of a shell if a shell
X     is required.  Thus effects of commands do not generally per-
X     sist across recipe lines.  (e.g. cd requests in a recipe
X     line do not carry over to the next recipe line) The decision
X     on whether a shell is required to execute a command is based
X     on the value of the macro SHELLMETAS or on the specification
X     of '+' or .USESHELL for the current recipe or target respec-
X     tively.  If any character in the value of SHELLMETAS is
X     found in the expanded recipe text-line or the use of a shell
X     is requested explicitly via '+' or .USESHELL then the com-
X     mand is executed using a shell, otherwise the command is
X
X
X
Version 3.70                    UW                             39
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     executed directly.  The shell that is used for execution is
X     given by the value of the macro SHELL.  The flags that are
X     passed to the shell are given by the value of SHELLFLAGS.
X     Thus dmake constructs the command line:
X
X          $(SHELL) $(SHELLFLAGS) $(expanded_recipe_command)
X
X     Normally dmake writes the command line that it is about to
X     invoke to standard output.  If the .SILENT attribute is set
X     for the target or for the recipe line (via @), then the
X     recipe line is not echoed.
X
X     Group recipe processing is similar to that of regular
X     recipes, except that a shell is always invoked.  The shell
X     that is invoked is given by the value of the macro GROUP-
X     SHELL, and its flags are taken from the value of the macro
X     GROUPFLAGS.  If a target has the .PROLOG attribute set then
X     dmake prepends to the shell script the recipe associated
X     with the special target .GROUPPROLOG, and if the attribute
X     .EPILOG is set as well, then the recipe associated with the
X     special target .GROUPEPILOG is appended to the script file.
X     This facility can be used to always prepend a common header
X     and common trailer to group recipes.  Group recipes are
X     echoed to standard output just like standard recipes, but
X     are enclosed by lines beginning with [ and ].
X
X     The recipe flags [+,-,%,@] are recognized at the start of a
X     recipe line even if they appear in a macro.  For example:
X
X          SH = +
X          all:
X               $(SH)echo hi
X
X     is completely equivalent to writing
X
X          SH = +
X          all:
X               +echo hi
X
X
X     The last step performed by dmake prior to running a recipe
X     is to set the macro CMNDNAME to the name of the command to
X     execute (determined by finding the first white-space ending
X     token in the command line).  It then sets the macro CMNDARGS
X     to be the remainder of the line.  dmake then expands the
X     macro COMMAND which by default is set to
X
X          COMMAND = $(CMNDNAME) $(CMNDARGS)
X
X     The result of this final expansion is the command that will
X     be executed.  The reason for this expansion is to allow for
X     a different interface to the argument passing facilities
X
X
X
Version 3.70                    UW                             40
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     (esp. under DOS) than that provided by dmake. You can for
X     example define COMMAND to be
X
X          COMMAND = $(CMNDNAME) @$(mktmp $(CMNDARGS))
X
X     which dumps the arguments into a temporary file and runs the
X     command
X
X          $(CMNDNAME) @/tmp/ASAD23043
X
X     which has a much shorter argument list.  It is now up to the
X     command to use the supplied argument as the source for all
X     other arguments.  As an optimization, if COMMAND is not
X     defined dmake does not perform the above expansion.  On sys-
X     tems, such as UNIX, that handle long command lines this pro-
X     vides a slight saving in processing the makefiles.
X
MAKING LIBRARIES
X     Libraries are easy to maintain using dmake.  A library is a
X     file containing a collection of object files.  Thus to make
X     a library you simply specify it as a target with the
X     .LIBRARY attribute set and specify its list of prere-
X     quisites.  The prerequisites should be the object members
X     that are to go into the library.  When dmake makes the
X     library target it uses the .LIBRARY attribute to pass to the
X     prerequisites the .LIBMEMBER attribute and the name of the
X     library.  This enables the file binding mechanism to look
X     for the member in the library if an appropriate object file
X     cannot be found. A small example best illustrates this.
X
X          mylib.a .LIBRARY : mem1.o mem2.o mem3.o
X               rules for making library...
X               # remember to remove .o's when lib is made
X
X          # equivalent to:  '%.o : %.c ; ...'
X          .c.o :; rules for making .o from .c say
X
X     dmake will use the .c.o rule for making the library members
X     if appropriate .c files can be found using the search rules.
X     NOTE:  this is not specific in any way to C programs, they
X     are simply used as an example.
X
X     dmake tries to handle the old library construct format in a
X     sensible way.  The construct lib(member.o) is separated and
X     the lib portion is declared as a library target.  The new
X     target is defined with the .LIBRARY attribute set and the
X     member.o portion of the construct is declared as a prere-
X     quisite of the lib target.  If the construct lib(member.o)
X     appears as a prerequisite of a target in the makefile, that
X     target has the new name of the lib assigned as its prere-
X     quisite.  Thus the following example:
X
X
X
X
Version 3.70                    UW                             41
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X          a.out : ml.a(a.o) ml.a(b.o); $(CC) -o $@  $<
X
X          .c.o :; $(CC) -c $(CFLAGS) -o $@  $<
X          %.a:
X               ar rv $@ $<
X               ranlib $@
X               rm -rf $<
X
X     constructs the following dependency graph.
X
X          a.out : ml.a; $(CC) -o $@  $<
X          ml.a .LIBRARY : a.o b.o
X
X          %.o : %.c ; $(CC) -c $(CFLAGS) -o $@  $<
X          %.a :
X               ar rv $@ $<
X               ranlib $@
X               rm -rf $<
X
X     and making a.out then works as expected.
X
X     The same thing happens for any target of the form
X     lib((entry)).  These targets have an additional feature in
X     that the entry target has the .SYMBOL attribute set automat-
X     ically.
X
X     NOTE:  If the notion of entry points is supported by the
X     archive and by dmake (currently not the case) then dmake
X     will search the archive for the entry point and return not
X     only the modification time of the member which defines the
X     entry but also the name of the member file.  This name will
X     then replace entry and will be used for making the member
X     file.  Once bound to an archive member the .SYMBOL attribute
X     is removed from the target.  This feature is presently dis-
X     abled as there is little standardization among archive for-
X     mats, and we have yet to find a makefile utilizing this
X     feature (possibly due to the fact that it is unimplemented
X     in most versions of UNIX Make).
X
X     Finally, when dmake looks for a library member it must first
X     locate the library file.  It does so by first looking for
X     the library relative to the current directory and if it is
X     not found it then looks relative to the current value of
X     $(TMD).  This allows commonly used libraries to be kept near
X     the root of a source tree and to be easily found by dmake.
X
KEEP STATE
X     dmake supports the keeping of state information for targets
X     that it makes whenever the macro .KEEP_STATE is assigned a
X     value.  The value of the macro should be the name of a state
X     file that will contain the state information.  If state
X     keeping is enabled then each target that does not poses the
SHAR_EOF
true || echo 'restore of dmake/man/dmake.nc failed'
fi
echo 'End of part 14, continue with part 15'
echo 15 > _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].