Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/misc/volume27/dmake/part15

Text File | 1992-01-29 | 40.2 KB | 1,007 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Dennis Vadura)
Subject:  v27i116:  dmake - dmake Version 3.8, Part15/41
Message-ID: <[e-mail]>
X-Md4-Signature: 40294784f165a859531972267690d4f5
Date: Tue, 28 Jan 1992 21:39:50 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Dennis Vadura)
Posting-number: Volume 27, Issue 116
Archive-name: dmake/part15
Environment: Atari-ST, Coherent, Mac, MSDOS, OS/2, UNIX
Supersedes: dmake: Volume 19, Issue 22-58

---- Cut Here and feed the following to sh ----
# this is dmake.shar.15 (part 15 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" != 15; 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     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     Don't know how to make ... error message to be suppressed
X     when dmake 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 (-A) flag was
X     specified.
X
RECIPES
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 MUST begin with a <TAB> 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 dmake 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
X
X
Version 3.70                    UW                             19
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
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     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 dmake 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
TEXT DIVERSIONS
X     dmake supports the notion of text diversions.  If a recipe
X     line contains the macro expression
X
X          $(mktmp[,[file][,text]] data)
X
X     then all text contained in the data 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
X
X
Version 3.70                    UW                             20
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     data 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          ${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 dmake
X     run.  The diversion text may contain the same escape codes
X     as those described in the MACROS section.  Thus if the data
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 data 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
X
X
Version 3.70                    UW                             21
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
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 data
X     string.
X
X     If the optional file 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     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 turboc.cfg
X     file.  The second optional argument, text, 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 dmake 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 dmake defined text diversions using <+,
X     +> strings, where <+ started a text diversion and +> ter-
X     minated one.  dmake 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
X
X
Version 3.70                    UW                             22
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
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
SPECIAL TARGETS
X     This section describes the special targets that are recog-
X     nized by dmake.  Some are affected by attributes and others
X     are not.
X
X     .ERROR        If defined then the recipe associated with
X                   this target is executed whenever an error con-
X                   dition is detected by dmake.  All attributes
X                   that can be used with any other target may be
X                   used with this target.  Any prerequisites of
X                   this target will be brought up to date during
X                   its processing.  NOTE:  errors will be ignored
X                   while making this target, in extreme cases
X                   this may cause some problems.
X
X     .EXPORT       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 or macros whose value contains
X                   any of the characters "+=:*" are not exported.
X                   is suppre
X
X     .IMPORT       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 .EVERY-
X                   THING is used as a prerequisite name then all
X                   environment variables defined in the environ-
X                   ment are imported.  The functionality of the
X                   -E flag can be forced by placing the construct
X                   .IMPORT : .EVERYTHING at the start of a
X                   makefile.  Similarly, by placing the construct
X                   at the end, one can emulate the effect of the
X                   -e 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
X
X
Version 3.70                    UW                             23
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X                   dmake 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     .INCLUDE      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                   <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                   dmake continues processing, otherwise an error
X                   message is generated.  The .SETDIR attribute
X                   causes dmake to change directories to the
X                   specified directory prior to attempting the
X                   include operation.
X
X     .INCLUDEDIRS  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     .KEEP_STATE   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 _state.mk as the state file.
X
X     .MAKEFILES    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
X
Version 3.70                    UW                             24
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     .SOURCE       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     .SOURCE.suff  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     .REMOVE       The recipe of this target is used whenever
X                   dmake 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     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
SPECIAL MACROS
X     dmake 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 dmake 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 dmake 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
CONTROL MACROS
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     DIRBRKSTR     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
X
X
X
Version 3.70                    UW                             25
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     INCDEPTH      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     MFLAGS        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     MAKECMD       Is the name with which dmake was invoked.
X
X     MAKEDIR       Is the full path to the initial directory in
X                   which dmake was invoked.
X
X     MAKEFILE      Contains the string "-f makefile" where,
X                   makefile is the name of initial user makefile
X                   that was first read.
X
X     MAKEFLAGS     Is the same as $(MFLAGS) but has no leading
X                   switch character. (ie. MFLAGS = -$(MAKEFLAGS))
X
X     MAKEMACROS    Contains the complete list of macro expres-
X                   sions that were specified on the command line.
X
X     MAKETARGETS   Contains the name(s) of the target(s), if any,
X                   that were specified on the command line.
X
X     MAXPROCESSLIMIT
X                   Is a numeric string representing the maximum
X                   number of processes that dmake can use when
X                   making targets using parallel mode.
X
X     NULL          Is permanently defined to be the NULL string.
X                   This is useful when comparing a conditional
X                   expression to an NULL value.
X
X     PWD           Is the full path to the current directory in
X                   which make is executing.
X
X     TMPFILE       Is set to the name of the most recent tem-
X                   porary file opened by dmake.  Temporary files
X                   are used for text diversions and for group
X                   recipe processing.
X
X     TMD           Stands for "To Make Dir", and is the path from
X                   the present directory (value of $(PWD)) to the
X                   directory that dmake was started up in (value
X                   of $(MAKEDIR)).  This macro is modified when
X                   .SETDIR attributes are processed.
X
X
X
X
X
Version 3.70                    UW                             26
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     USESHELL      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 dmake
X     behavior and may be set by the user.
X
X     .NOTABS         When set to non-NULL enables the use of
X                     spaces as well as <tabs> to begin recipe
X                     lines.  By default a non-group recipe is
X                     terminated by a line without any leading
X                     white-space or by a line not beggining with
X                     a <tab> character.  Enabling this mode modi-
X                     fies the first condition of the above termi-
X                     nation rule to terminate a non-group recipe
X                     with a line that contains only white-space.
X                     This mode does not effect the parsing of
X                     group recipes bracketed by [].
X
X     .SETDIR         If this macro is assigned a value then dmake
X                     will change to the directory given by that
X                     value before making any targets.
X
X     AUGMAKE         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     DIRSEPSTR       Contains the string that is used to separate
X                     directory components when path names are
X                     constructed.  It is defined with a default
X                     value at startup.
X
X     DIVFILE         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     .KEEP_STATE     Assigning this macro a value tells dmake 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     GROUPFLAGS      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
X
Version 3.70                    UW                             27
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     GROUPSHELL      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     GROUPSUFFIX     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                     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     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.  This macro
X                     can only be used to extend the line length
X                     beyond it's default minimum value.
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
X
Version 3.70                    UW                             28
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
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                     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
X
X
Version 3.70                    UW                             29
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
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     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
X
X
Version 3.70                    UW                             30
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
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          $(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
X
Version 3.70                    UW                             31
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
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     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
X
X
Version 3.70                    UW                             32
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
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          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
X
X
X
Version 3.70                    UW                             33
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
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/:/ /)
SHAR_EOF
true || echo 'restore of dmake/man/dmake.nc failed'
fi
echo 'End of part 15, continue with part 16'
echo 16 > _shar_seq_.tmp
exit 0
exit 0 # Just in case...