v19i038: dmake - dmake version 3.7, Part17/37

Dennis Vadura dvadura at watdragon.waterloo.edu
Sun May 12 10:20:02 AEST 1991


Submitted-by: Dennis Vadura <dvadura at watdragon.waterloo.edu>
Posting-number: Volume 19, Issue 38
Archive-name: dmake/part17
Supersedes: dmake-3.6: Volume 15, Issue 52-77

---- Cut Here and feed the following to sh ----
#!/bin/sh
# this is dmake.shar.17 (part 17 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" != 17; 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     To use the control macros simply assign them a value just
X     like any other macro.  The control macros are divided into
X     three groups: string valued macros, character valued macros,
X     and boolean valued macros.
X
X     The following are all of the string valued macros.  This
X     list is divided into two groups.  The first group gives the
X     string valued macros that are defined internally and cannot
X     be directly set by the user.
X
X     DDIIRRBBRRKKSSTTRR     Contains the string of chars used to terminate
X                   the name of a directory in a pathname.  Under
X                   UNIX its value is "/", under MSDOS its value
X                   is "/\:".
X
X     IINNCCDDEEPPTTHH      This macro's value is a string of digits
X                   representing the current depth of makefile
X                   inclusion.  In the first makefile level this
X                   value is zero.
X
X     MMFFLLAAGGSS        Is the list of flags that were given on the
X                   command line including a leading switch char-
X                   acter.  The -f flag is not included in this
X                   list.
X
X     MMAAKKEECCMMDD       Is the name with which ddmmaakkee was invoked.
X
X     MMAAKKEEDDIIRR       Is the full path to the initial directory in
X                   which ddmmaakkee was invoked.
X
X     MMAAKKEEFFIILLEE      Contains the string "-f _m_a_k_e_f_i_l_e" where,
X                   _m_a_k_e_f_i_l_e is the name of initial user makefile
X                   that was first read.
X
X
X
Version 3.70                    UW                             25
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     MMAAKKEEFFLLAAGGSS     Is the same as $(MFLAGS) but has no leading
X                   switch character. (ie. MFLAGS = -$(MAKEFLAGS))
X
X     MMAAKKEEMMAACCRROOSS    Contains the complete list of macro expres-
X                   sions that were specified on the command line.
X
X     MMAAKKEETTAARRGGEETTSS   Contains the name(s) of the target(s), if any,
X                   that were specified on the command line.
X
X     MMAAXXPPRROOCCEESSSSLLIIMMIITT
X                   Is a numeric string representing the maximum
X                   number of processes that ddmmaakkee can use when
X                   making targets using parallel mode.
X
X     NNUULLLL          Is permanently defined to be the NULL string.
X                   This is useful when comparing a conditional
X                   expression to an NULL value.
X
X     PPWWDD           Is the full path to the current directory in
X                   which make is executing.
X
X     TTMMPPFFIILLEE       Is set to the name of the most recent tem-
X                   porary file opened by ddmmaakkee.  Temporary files
X                   are used for text diversions and for group
X                   recipe processing.
X
X     TTMMDD           Stands for "To Make Dir", and is the path from
X                   the present directory (value of $(PWD)) to the
X                   directory that ddmmaakkee was started up in (value
X                   of $(MAKEDIR)).  This macro is modified when
X                   .SETDIR attributes are processed.
X
X     UUSSEESSHHEELLLL      The value of this macro is set to "yes" if the
X                   current recipe is forced to use a shell for
X                   its execution via the .USESHELL or '+' direc-
X                   tives, its value is "no" otherwise.
X
X
X     The second group of string valued macros control ddmmaakkee
X     behavior and may be set by the user.
X
X     ..SSEETTDDIIRR         If this macro is assigned a value then ddmmaakkee
X                     will change to the directory given by that
X                     value before making any targets.
X
X     AAUUGGMMAAKKEE         If set to a non NULL value will enable the
X                     transformation of special meta targets to
X                     support special AUGMAKE inferences (See the
X                     COMPATIBILITY section).
X
X     DDIIRRSSEEPPSSTTRR       Contains the string that is used to separate
X                     directory components when path names are
X
X
X
Version 3.70                    UW                             26
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X                     constructed.  It is defined with a default
X                     value at startup.
X
X     DDIIVVFFIILLEE         Is defined in the startup file and gives the
X                     name that should be returned for the diver-
X                     sion file name when used in $(mktmp ...)
X                     expansions, see the TEXT DIVERSION section
X                     for details.
X
X     ..KKEEEEPP__SSTTAATTEE     Assigning this macro a value tells ddmmaakkee the
X                     name of the state file to use and turns on
X                     the keeping of state information for any
X                     targets that are brought up to date by the
X                     make.
X
X     GGRROOUUPPFFLLAAGGSS      This macro gives the set of flags to pass to
X                     the shell when invoking it to execute a
X                     group recipe.  The value of the macro is the
X                     list of flags with a leading switch indica-
X                     tor.  (ie. `-' under UNIX)
X
X     GGRROOUUPPSSHHEELLLL      This macro defines the full path to the exe-
X                     cutable image to be used as the shell when
X                     processing group recipes.  This macro must
X                     be defined if group recipes are used.  It is
X                     assigned a default value in the startup
X                     makefile.  Under UNIX this value is /bin/sh.
X
X     GGRROOUUPPSSUUFFFFIIXX     If defined, this macro gives the string to
X                     use as a suffix when creating group recipe
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                     ddmmaakkee 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     MMAAKKEE            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     MMAAKKEESSTTAARRTTUUPP     This macro defines the full path to the ini-
X                     tial startup makefile.  Use the --VV 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     MMAAXXLLIINNEELLEENNGGTTHH   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 --VV 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     MMAAXXPPRROOCCEESSSS      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     PPRREEPP            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     SSHHEELLLL           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     SSHHEELLLLFFLLAAGGSS      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     SSHHEELLLLMMEETTAASS      Each time ddmmaakkee 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 ddmmaakkee:
X     SSWWIITTCCHHAARR 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     ddmmaakkee 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 ddmmaakkee 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: ..EEPPIILLOOGG, ..IIGGNNOORREE, ..MMKKSSAARRGGSS, ..NNOOIINNFFEERR, ..PPRREECCIIOOUUSS, ..PPRROO----
X     LLOOGG, ..SSEEQQUUEENNTTIIAALL, ..SSIILLEENNTT, ..SSWWAAPP, and ..UUSSEESSHHEELLLL.  Assigning
X     any of these a non NULL value will globally set the
X     corresponding attribute to on.
X
RRUUNN__TTIIMMEE MMAACCRROOSS
X     These macros are defined when ddmmaakkee 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 $$((@@::ddbb)) 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     ddmmaakkee 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
FFUUNNCCTTIIOONN MMAACCRROOSS
X     ddmmaakkee 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          $(nnuullll,_t_e_x_t ttrruuee ffaallssee)
X               expands the value of _t_e_x_t_. If it is NULL then the
X               macro returns the value of the expansion of ttrruuee
X               and the expansion of ffaallssee otherwise.  The terms
X               ttrruuee, and ffaallssee must be strings containing no
X               white-space.
X
X          $(!!nnuullll,_t_e_x_t ttrruuee ffaallssee)
X               Behaves identically to the previous macro except
X               that the ttrruuee string is chosen if the expansion of
X               _t_e_x_t is not NULL.
X
X          $(eeqq,_t_e_x_t___a,_t_e_x_t___b ttrruuee ffaallssee)
X               expands _t_e_x_t___a and _t_e_x_t___b and compares their
X               results.  If equal it returns the result of the
X               expansion of the ttrruuee term, otherwise it returns
X               the expansion of the ffaallssee term.
X
X          $(!!eeqq,_t_e_x_t___a,_t_e_x_t___b ttrruuee ffaallssee)
X               Behaves identically to the previous macro except
X               that the ttrruuee 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          $(sshheellll ccoommmmaanndd)
X               Runs _c_o_m_m_a_n_d 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          $(ssoorrtt lliisstt)
X               Will take all white-space separated tokens in _l_i_s_t
X               and will return their sorted equivalent list.
X
X          $(ssttrriipp ddaattaa)
X               Will replace all strings of white-space in data by
X               a single space.
X
X          $(ssuubbsstt,_p_a_t,_r_e_p_l_a_c_e_m_e_n_t ddaattaa)
X               Will search for _p_a_t in ddaattaa and will replace any
X               occurrence of _p_a_t with the _r_e_p_l_a_c_e_m_e_n_t string.
X               The expansion
X
X                    $(subst,.o,.c $(OBJECTS))
X
X               is equivalent to:
X
X                    $(OBJECTS:s/.o/.c/)
X
X
DDYYNNAAMMIICC PPRREERREEQQUUIISSIITTEESS
X     ddmmaakkee 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 ddmmaakkee is making fred, and
X     it resolves to the target _f_r_e_d.  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 _f_r_e_d.  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
BBIINNDDIINNGG TTAARRGGEETTSS
X     This operation takes a target name and binds it to an exist-
X     ing file, if possible.  ddmmaakkee 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_._s_u_f_f, where _._s_u_f_f is the suffix and _X is the stem
X     portion (ie. that part which contains the directory and the
X     basename).  ddmmaakkee 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. _._s_u_f_f 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               ddmmaakkee 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 ddmmaakkee 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 ddmmaakkee stops, then the user may
X     fix the error and make again.  ddmmaakkee 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     ddmmaakkee 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.  ddmmaakkee 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
PPEERRCCEENNTT((%%)) RRUULLEESS AANNDD MMAAKKIINNGG IINNFFEERREENNCCEESS
X     When ddmmaakkee makes a target, the target's set of prerequisites
X     (if any) must exist and the target must have a recipe which
X     ddmmaakkee can use to make it.  If the makefile does not specify
X     an explicit recipe for the target then ddmmaakkee 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, ddmmaakkee supports the concept of _%_-_m_e_t_a rules.
X     The syntax and semantics of these rules differ from standard
X     rule lines as follows:
X
X          _<_%_-_t_a_r_g_e_t_> [_<_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     where _%_-_t_a_r_g_e_t is a target containing exactly a single `%'
X     sign, _a_t_t_r_i_b_u_t_e_s is a list (possibly empty) of attributes,
X     _r_u_l_e_o_p is the standard set of rule operators, _%_-_p_r_e_r_e_-
X     _q_u_i_s_i_t_e_s , if present, is a list of prerequisites containing
X     zero or more `%' signs, and _r_e_c_i_p_e_, if present, is the first
X     line of the recipe.
X
X     The _%_-_t_a_r_g_e_t 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 ddmmaakkee 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 _a_n_y_t_h_i_n_g from RCS/%,v, and _a_n_y_t_h_i_n_g also
X     includes RCS/fred.c,v.  To limit the size of the graph that
X     results from such rules ddmmaakkee 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     ddmmaakkee 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.  ddmmaakkee 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     ddmmaakkee 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 _R_C_S_/_f_r_e_d_._c_,_v from
X     the target _f_r_e_d_._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     _s_r_c_d_i_r_/_R_C_S_/_f_r_e_d_._c_,_v from _s_r_c_d_i_r_/_f_r_e_d_._c because the above
X     rule will cause ddmmaakkee 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 _R_C_S_/ to it, and appending the
X     target file name with a trailing _,_v attached to the previous
X     result.
X
X     ddmmaakkee 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 ddmmaakkee
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     ddmmaakkee 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     ddmmaakkee maps this into the following %-rule:
X
X          %.o : %.c; cc -c $< -o $@
X
X     Furthermore, ddmmaakkee 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     ddmmaakkee 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 _t_r_a_n_s_i_t_i_v_e _c_l_o_s_u_r_e 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 ddmmaakkee 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 ddmmaakkee 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.  ddmmaakkee 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 ddmmaakkee 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     ddmmaakkee tries to remove intermediate files resulting from
X     transitive closure if the file is not marked as being PRE-
X     CIOUS, or the --uu 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     ddmmaakkee 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 ddmmaakkee 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
MMAAKKIINNGG TTAARRGGEETTSS
X     In order to update a target ddmmaakkee 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.  ddmmaakkee
X     supports two types of recipes.  The regular recipes and
X     group recipes.
SHAR_EOF
true || echo 'restore of dmake/man/dmake.p failed'
fi
echo 'End of part 17, continue with part 18'
echo 18 > _shar_seq_.tmp
exit 0

exit 0 # Just in case...
-- 
Kent Landfield                   INTERNET: kent at sparky.IMD.Sterling.COM
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    (402) 291-8300         FAX:      (402) 291-4362
Please send comp.sources.misc-related mail to kent at uunet.uu.net.



More information about the Comp.sources.misc mailing list