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

Text File | 1991-05-11 | 40.2 KB | 1,135 lines

Newsgroups: comp.sources.misc
From: Dennis Vadura <[e-mail]>
Subject:  v19i039:  dmake - dmake version 3.7, Part18/37
Message-ID: <[e-mail]>
X-Md4-Signature: ab77b86c09a8ee945be84a5894fe2537
Date: Sun, 12 May 1991 00:20:30 GMT
Approved: [e-mail]

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

---- Cut Here and feed the following to sh ----
#!/bin/sh
# this is dmake.shar.18 (part 18 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" != 18; 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
X     When a regular recipe is invoked ddmmaakkee 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 ddmmaakkee constructs the command line:
X
X          $(SHELL) $(SHELLFLAGS) $(expanded_recipe_command)
X
X     Normally ddmmaakkee 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     ddmmaakkee 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 ddmmaakkee 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.  ddmmaakkee 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 ddmmaakkee. 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 ddmmaakkee 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
MMAAKKIINNGG LLIIBBRRAARRIIEESS
X     Libraries are easy to maintain using ddmmaakkee.  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 ddmmaakkee 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     ddmmaakkee 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     ddmmaakkee tries to handle the old library construct format in a
X     sensible way.  The construct _l_i_b_(_m_e_m_b_e_r_._o_) is separated and
X     the _l_i_b portion is declared as a library target.  The new
X     target is defined with the .LIBRARY attribute set and the
X     _m_e_m_b_e_r_._o portion of the construct is declared as a prere-
X     quisite of the lib target.  If the construct _l_i_b_(_m_e_m_b_e_r_._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     _l_i_b_(_(_e_n_t_r_y_)_).  These targets have an additional feature in
X     that the _e_n_t_r_y 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 ddmmaakkee (currently not the case) then ddmmaakkee
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 _e_n_t_r_y 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 ddmmaakkee 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 ddmmaakkee.
X
KKEEEEPP SSTTAATTEE
X     ddmmaakkee 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
X
X
X
Version 3.70                    UW                             42
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     .NOSTATE attribute will have a record written into the state
X     file indicating the target's name, the current directory,
X     the command used to update the target, and which, if any, ::
X     rule is being used.  When you make this target again if any
X     of this information does not match the previous settings and
X     the target is not out dated it will still be re-made.  The
X     assumption is that one of the conditions above has changed
X     and that we wish to remake the target.  For example, state
X     keeping is used in the maintenance of ddmmaakkee to test compile
X     different versions of the source using different compilers.
X     Changing the compiler causes the compilation flags to be
X     modified and hence all sources to be recompiled.
X
X     The state file is an ascii file and is portable, however it
X     is not in human readable form as the entries represent hash
X     keys of the above information.
X
X     The Sun Microsystem's Make construct
X
X          .KEEP_STATE :
X
X     is recognized and is mapped to ..KKEEEEPP__SSTTAATTEE::==__ssttaattee..mmkk.  The
X     ddmmaakkee version of state keeping does not include scanning C
X     source files for dependencies like Sun Make.  This is
X     specific to C programs and it was felt that it does not
X     belong in make.  ddmmaakkee instead provides the tool, ccddeeppeenndd,
X     to scan C source files and to produce depedency information.
X     Users are free to modify cdepend to produce other dependency
X     files.  (NOTE: ccddeeppeenndd does not come with the distribution
X     at this time, but will be available in a patch in the near
X     future)
X
MMUULLTTII PPRROOCCEESSSSIINNGG
X     If the architecture supports it then ddmmaakkee is capable of
X     making a target's prerequisites in parallel.  ddmmaakkee will
X     make as much in parallel as it can and use a number of child
X     processes up to the maximum specified by MAXPROCESS or by
X     the value supplied to the -P command line flag.  A parallel
X     make is enabled by setting the value of MAXPROCESS (either
X     directly or via -P option) to a value which is > 1.  ddmmaakkee
X     guarantees that all dependencies as specified in the
X     makefile are honored.  A target will not be made until all
X     of its prerequisites have been made.  If a parallel make is
X     being performed then the following restrictions on parallel-
X     ism are enforced.
X
X          1.   Individual recipe lines in a non-group recipe are
X               performed sequentially in the order in which they
X               are specified within the makefile and in parallel
X               with the recipes of other targets.
X
X
X
X
X
Version 3.70                    UW                             43
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X          2.   If a target contains multiple recipe definitions
X               (cf. :: rules) then these are performed sequen-
X               tially in the order in which the :: rules are
X               specified within the makefile and in parallel with
X               the recipes of other targets.
X
X          3.   If a target rule contains the `!' modifier, then
X               the recipe is performed sequentially for the list
X               of outdated prerequisites and in parallel with the
X               recipes of other targets.
X
X          4.   If a target has the .SEQUENTIAL attribute set then
X               all of its prerequisites are made sequentially
X               relative to one another (as if MAXPROCESS=1), but
X               in parallel with other targets in the makefile.
X
X     Note:  If you specify a parallel make then the order of tar-
X     get update and the order in which the associated recipes are
X     invoked will not correspond to that displayed by the -n
X     flag.
X
CCOONNDDIITTIIOONNAALLSS
X     ddmmaakkee supports a makefile construct called a _c_o_n_d_i_t_i_o_n_a_l.
X     It allows the user to conditionally select portions of
X     makefile text for input processing and to discard other por-
X     tions.  This becomes useful for writing makefiles that are
X     intended to function for more than one target host and
X     environment.  The conditional expression is specified as
X     follows:
X
X          .IF  _e_x_p_r_e_s_s_i_o_n
X             ... if text ...
X          .ELIF  _e_x_p_r_e_s_s_i_o_n
X             ... if text ...
X          .ELSE
X             ... else text ...
X          .END
X
X     The .ELSE and .ELIF portions are optional, and the condi-
X     tionals may be nested (ie.  the text may contain another
X     conditional).  .IF, .ELSE, and .END may appear anywhere in
X     the makefile, but a single conditional expression may not
X     span multiple makefiles.
X
X     _e_x_p_r_e_s_s_i_o_n can be one of the following three forms:
X
X          <text> | <text> == <text> | <text> != <text>
X
X     where _t_e_x_t is either text or a macro expression.  In any
X     case, before the comparison is made, the expression is
X     expanded.  The text portions are then selected and compared.
X     White space at the start and end of the text portion is
X
X
X
Version 3.70                    UW                             44
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     discarded before the comparison.  This means that a macro
X     that evaluates to nothing but white space is considered a
X     NULL value for the purpose of the comparison.  In the first
X     case the expression evaluates TRUE if the text is not NULL
X     otherwise it evaluates FALSE.  The remaining two cases both
X     evaluate the expression on the basis of a string comparison.
X     If a macro expression needs to be equated to a NULL string
X     then compare it to the value of the macro $(NULL).  You can
X     use the $(shell ...) macro to construct more complex test
X     expressions.
X
EEXXAAMMPPLLEESS
X          # A simple example showing how to use make
X          #
X          prgm : a.o b.o
X               cc a.o b.o -o prgm
X          a.o : a.c g.h
X               cc a.c -o $@
X          b.o : b.c g.h
X               cc b.c -o $@
X
X     In the previous example prgm is remade only if a.o and/or
X     b.o is out of date with respect to prgm.  These dependencies
X     can be stated more concisely by using the inference rules
X     defined in the standard startup file.  The default rule for
X     making .o's from .c's looks something like this:
X
X          %.o : %.c; cc -c $(CFLAGS) -o $@ $<
X
X     Since there exists a rule (defined in the startup file) for
X     making .o's from .c's ddmmaakkee will use that rule for manufac-
X     turing a .o from a .c and we can specify our dependencies
X     more concisely.
X
X          prgm : a.o b.o
X               cc -o prgm $<
X          a.o b.o : g.h
X
X     A more general way to say the above using the new macro
X     expansions would be:
X
X          SRC = a b
X          OBJ = {$(SRC)}.o
X
X          prgm : $(OBJ)
X               cc -o $@ $<
X
X          $(OBJ) : g.h
X
X     If we want to keep the objects in a separate directory,
X     called objdir, then we would write something like this.
X
X
X
X
Version 3.70                    UW                             45
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X          SRC = a b
X          OBJ = {$(SRC)}.o
X
X          prgm : $(OBJ)
X               cc $< -o $@
X
X          $(OBJ) : g.h
X          %.o : %.c
X               $(CC) -c $(CFLAGS) -o $(@:f) $<
X               mv $(@:f) objdir
X
X          .SOURCE.o : objdir       # tell make to look here for .o's
X
X     An example of building library members would go something
X     like this: (NOTE:  The same rules as above will be used to
X     produce .o's from .c's)
X
X          SRC  = a b
X          LIB  = lib
X          LIBm = { $(SRC) }.o
X
X          prgm: $(LIB)
X               cc -o $@ $(LIB)
X
X          $(LIB) .LIBRARY : $(LIBm)
X               ar rv $@ $<
X               rm $<
X
X     Finally, suppose that each of the source files in the previ-
X     ous example had the `:' character in their target name.
X     Then we would write the above example as:
X
X          SRC  = f:a f:b
X          LIB  = lib
X          LIBm = "{ $(SRC) }.o"         # put quotes around each token
X
X          prgm: $(LIB)
X               cc -o $@ $(LIB)
X
X          $(LIB) .LIBRARY : $(LIBm)
X               ar rv $@ $<
X               rm $<
X
CCOOMMPPAATTIIBBIILLIITTYY
X     There are two notable differences between ddmmaakkee and the
X     standard version of BSD UNIX 4.2/4.3 Make.
X
X          1. BSD UNIX 4.2/4.3 Make supports wild card filename
X             expansion for prerequisite names.  Thus if a direc-
X             tory contains a.h, b.h and c.h, then a line like
X
X                  target: *.h
X
X
X
Version 3.70                    UW                             46
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X             will cause UNIX make to expand the *.h into "a.h b.h
X             c.h".  ddmmaakkee does not support this type of filename
X             expansion.
X
X          2. Unlike UNIX make, touching a library member causes
X             ddmmaakkee to search the library for the member name and
X             to update the library time stamp.  This is only
X             implemented in the UNIX version.  MSDOS and other
X             versions may not have librarians that keep file time
X             stamps, as a result ddmmaakkee touches the library file
X             itself, and prints a warning.
X
X     ddmmaakkee is not compatible with GNU Make.  In particular it
X     does not understand GNU Make's macro expansions that query
X     the file system.
X
X     ddmmaakkee is fully compatible with SYSV AUGMAKE, and supports
X     the following AUGMAKE features:
X
X          1. The word iinncclluuddee appearing at the start of a line
X             can be used instead of the ".INCLUDE :" construct
X             understood by ddmmaakkee.
X
X          2. The macro modifier expression $(macro:str=sub) is
X             understood and is equivalent to the expression
X             $(macro:s/str/sub), with the restriction that str
X             must match the following regular expression:
X
X                  str[ |\t][ |\t]*
X
X             (ie. str only matches at the end of a token where
X             str is a suffix and is terminated by a space, a tab,
X             or end of line)
X
X          3. The macro % is defined to be $@ (ie. $% expands to
X             the same value as $@).
X
X          4. The AUGMAKE notion of libraries is handled
X             correctly.
X
X          5. When defining special targets for the inference
X             rules and the AUGMAKE special target handling is
X             enabled then the special target .X is equivalent to
X             the %-rule "% : %.X".
X
X          6. Directories are always made if you specify --AA.  This
X             is consistent with other UNIX versions of Make.
X
X          7. Makefiles that utilize virtual targets to force mak-
X             ing of other targets work as expected if AUGMAKE
X             special target handling is enabled.  For example:
X
X
X
X
Version 3.70                    UW                             47
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X                  FRC:
X                  myprog.o : myprog.c $(FRC) ; ...
X
X             Works as expected if you issue the command
X
X                  'ddmmaakkee -A FRC=FRC'
X
X             but fails with a 'don't know how to make FRC' error
X             message if you do not specify AUGMAKE special target
X             handling via the -A flag (or by setting AUGMAKE:=yes
X             internally).
X
LLIIMMIITTSS
X     In some environments the length of an argument string is
X     restricted.  (e.g. MSDOS command line arguments cannot be
X     longer than 128 bytes if you are using the standard
X     command.com command interpreter as your shell, ddmmaakkee text
X     diversions may help in these situations.)
X
PPOORRTTAABBIILLIITTYY
X     To write makefiles that can be moved from one environment to
X     another requires some forethought.  In particular you must
X     define as macros all those things that may be different in
X     the new environment.  ddmmaakkee has two facilities that help to
X     support writing portable makefiles, recursive macros and
X     conditional expressions.  The recursive macros, allow one to
X     define environment configurations that allow different
X     environments for similar types of operating systems.  For
X     example the same make script can be used for SYSV and BSD
X     but with different macro definitions.
X
X     To write a makefile that is portable between UNIX and MSDOS
X     requires both features since in almost all cases you will
X     need to define new recipes for making targets.  The recipes
X     will probably be quite different since the capabilities of
X     the tools on each machine are different.  Different macros
X     will be needed to help handle the smaller differences in the
X     two environments.
X
X     NOTE:  Unlike UNIX, MSDOS ddooeess maintain cd requests cross
X     single recipe lines.  This is not portable, and your
X     makefiles will not work the same way if you depend on it.
X     Use the .IF ... .ELSE ... .END conditionals to supply dif-
X     ferent make scripts as necessary.
X
FFIILLEESS
X     Makefile, makefile, startup.mk (use dmake -V to tell you
X     where the startup file is)
X
SSEEEE AALLSSOO
X     sh(1), csh(1), touch(1), f77(1), pc(1), cc(1)
X     S.I. Feldman  _M_a_k_e _- _A _P_r_o_g_r_a_m _f_o_r _M_a_i_n_t_a_i_n_i_n_g _C_o_m_p_u_t_e_r
X
X
X
Version 3.70                    UW                             48
X
X
X
X
DMAKE(p)             Unsupported Free Software            DMAKE(p)
X
X
X
X     _P_r_o_g_r_a_m_s
X
AAUUTTHHOORR
X     Dennis Vadura, CS Dept. University of Waterloo.
X     [e-mail]
X     Many thanks to Carl Seger for his helpful suggestions, and
X     to Trevor John Thompson for his many excellent ideas and
X     informative bug reports.
X
BBUUGGSS
X     Some system commands return non-zero status inappropriately.
X     Use --ii (`-' within the makefile) to overcome the difficulty.
X
X     Some systems do not have easily accessible time stamps for
X     library members (MSDOS, AMIGA, etc) for these ddmmaakkee uses the
X     time stamp of the library instead and prints a warning the
X     first time it does so.  This is almost always ok, except
X     when multiple makefiles update a single library file.  In
X     these instances it is possible to miss an update if one is
X     not careful.
X
X     This man page is way too long.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
Version 3.70                    UW                             49
SHAR_EOF
chmod 0640 dmake/man/dmake.p ||
echo 'restore of dmake/man/dmake.p failed'
Wc_c="`wc -c < 'dmake/man/dmake.p'`"
test 125280 -eq "$Wc_c" ||
    echo 'dmake/man/dmake.p: original size 125280, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
# ============= dmake/man/dmake.tf ==============
if test -f 'dmake/man/dmake.tf' -a X"$1" != X"-c"; then
    echo 'x - skipping dmake/man/dmake.tf (File already exists)'
    rm -f _shar_wnt_.tmp
else
> _shar_wnt_.tmp
sed 's/^X//' << 'SHAR_EOF' > 'dmake/man/dmake.tf' &&
.\" Copyright (c) 1990 Dennis Vadura, All rights reserved.
.\"
.ds TB "0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.5i +0.5i +2.0i
.de Ip
.fi
.nr Ip \w'\\$1 'u
.IP "\\$1" \\n(Ipu
\\$2
.nf
..
.de Is
.nr )I \w'\\$1'u
..
.de Ii
.in \\n()Ru
.nr )E 1
.ns
.ne 1.1v
.it 1 }N
.di ]B
\&\\$1
..
.TH DMAKE p  "UW" "Version 3.70" "Unsupported Free Software"
.SH NAME
\fBdmake\fR \- maintain program groups, or interdependent files
.SH SYNOPSIS
.B dmake
[-AceEhiknpqrsStTuVx] [-v{dfimt}] [-P#] [-{f|C|K} file]
[macro[*][+][:]=\fIvalue\fP ...] [target ...]
.SH DESCRIPTION
.PP
.B dmake
executes commands found in an external file called a
.I makefile
to update one or more target names.
Each target may depend on zero or more prerequisite targets.
If any of the target's prerequisites is newer than the target or if the target
itself does not exist, then
.B dmake
will attempt to make the target.
.PP
If no
.B \-f
command line option is present then
.B dmake
searches for an existing
.I makefile
from the list of prerequisites specified for the special target \fI.MAKEFILES\fR
(see the STARTUP section for more details).
If "-" is the name of the file specified to the
.B -f
flag then \fBdmake\fR uses standard input as the source of the makefile text.
.PP
Any macro definitions (arguments with embedded "="
signs) that appear on the command line are processed first
and supersede definitions for macros of the same name found
within the makefile.  In general it is impossible for definitions found
inside the makefile to redefine a macro defined on the command line, see the
MACROS section for an exception.
.PP
If no
.I target
names are specified on the command line, then \fBdmake\fR uses the first
non-special target found in the makefile as the default target.
See the
.B "SPECIAL TARGETS"
section for the list of special targets and their function.
\fBdmake\fR is a re-implementation of the UNIX Make utility with
significant enhancements.  Makefiles written for most previous
versions of
.I Make
will be handled correctly by
.B dmake.
Known differences between \fBdmake\fR and other versions of make
are discussed in the
.B COMPATIBILITY
section found at the end of this document.
.SH OPTIONS
.IP "\fB\-A\fR"
Enable AUGMAKE special inference rule transformations
(see the "PERCENT(%) RULES" section), these are set to off by default.
.IP "\fB\-c\fR"
Use non-standard comment stripping.  If you specify \fB-c\fP then
.B dmake
will treat any \fB#\fP character as a start of comment character wherever it
may appear unless it is escaped by a \\.
.IP "\fB\-C [+]file\fR"
This option writes to \fIfile\fP a copy of standard output and
standard error from any child processes and from the
.B dmake
process itself.  If you specify a \fB+\fP prior to the file name then
the text is appended to the previous contents of \fIfile\fP.
This option is active in the MSDOS implementation only and is ignored
by non-MSDOS versions of
.B dmake.
.IP "\fB\-e\fR"
Read the environment and define all strings of the
form '\fBENV-VAR\fP=\fIevalue\fP'
defined within as macros whose name is \fBENV-VAR\fP,
and whose value is '\fIevalue\fP'.
The environment is processed prior to processing the user
specified makefile thereby allowing definitions in the makefile to override
definitions in the environment.
.IP "\fB\-E\fR"
Same as -e, except that the environment is processed after the
user specified makefile has been processed
(thus definitions in the environment override definitions in the makefile).
The -e and -E options are mutually exclusive.
If both are given the latter takes effect.
.IP "\fB\-f file\fR"
Use \fBfile\fR as the source for the makefile text.
Only one \fB\-f\fR option is allowed.
.IP "\fB\-h\fR"
Print the command summary for \fBdmake\fR.
.IP "\fB\-i\fR"
Tells \fBdmake\fR to ignore errors, and continue making other targets.
This is equivalent to the .IGNORE attribute or macro.
.IP "\fB\-K file\fR"
Turns on \fB.KEEP_STATE\fP state tracking and tells \fBdmake\fP to use
\fIfile\fP as the state file.
.IP "\fB\-k\fR"
Causes \fBdmake\fR to ignore errors caused by command execution and to make
all targets not depending on targets that could not be made.
Ordinarily \fBdmake\fR stops after a command returns a non-zero status,
specifying \fB\-k\fR causes \fBdmake\fR to ignore the error
and continue to make as much as possible.
.IP "\fB\-n\fR"
Causes \fBdmake\fR to print out what it would have executed,
but does not actually execute the commands.  A special check is made for
the string "$(MAKE)" inside a recipe line, if found, the line is expanded
and invoked, thereby enabling recursive makes to give a full
description of all that they will do.
The check for "$(MAKE)" is disabled inside group recipes.
.IP "\fB\-p\fR"
Print out a version of the digested makefile in human readable form.
(useful for debugging, but cannot be re-read by \fBdmake\fP)
.IP "\fB\-P#\fR"
On systems that support multi-processing cause \fBdmake\fP to use \fI#\fP
concurrent child processes to make targets.
See the "MULTI PROCESSING" section for more information.
.IP "\fB\-q\fR"
Check and see if the target is up to date.  Exits with code 0 if up to date,
1 otherwise.
.IP "\fB\-r\fR"
Tells \fBdmake\fR not to read the initial startup makefile, see STARTUP
section for more details.
.IP "\fB\-s\fR"
Tells \fBdmake\fR to do all its work silently and not echo the commands it is
executing to stdout (also suppresses warnings).
This  is equivalent to the .SILENT attribute or macro.
.IP "\fB\-S\fR"
Force sequential execution of recipes on architectures which support
concurrent makes.  For backward compatibility with old makefiles that have
nasty side-effect prerequisite dependencies.
.IP "\fB\-t\fR"
Causes \fBdmake\fR to touch the targets and bring them up to date
without executing any commands.
.IP "\fB\-T\fR"
Tells \fBdmake\fP to not perform transitive closure on the inference graph.
.IP "\fB\-u\fR"
Force an unconditional update.  (ie. do everything that would
be done if everything that a target depended on was out of date)
.IP "\fB\-v[dfimt]\fR"
Verbose flag, when making targets print to stdout what we are going to make
and what we think its time stamp is.  The optional flags \fB[dfimt]\fP can be
used to restrict the information that is displayed.  In the absence of any
optional flags all are assumed to be given (ie. \fB\-v\fP is equivalent to
\fB\-vdfimt\fP).  The meanings of the optional flags are:
.RS
.IP "\fBd\fP"
Notify of change directory operations only.
.IP "\fBf\fP"
Notify of file I/O operations only.
.IP "\fBi\fP"
Notify of inference algorithm operation only.
.IP "\fBm\fP"
Notify of target update operations only.
.IP "\fBt\fP"
Keep any temporary files created; normally they are automatically deleted.
.RE
.IP "\fB\-V\fR"
Print the version of \fBdmake\fR, and values of builtin macros.
.IP "\fB\-x\fR"
Upon processing the user makefile export all non-internally defined macros
to the user's environment.  This option together with the -e option
allows SYSV AUGMAKE recursive makes to function as expected.
.SH INDEX
Here is a list of the sections that follow and a short description of each.
Perhaps you won't have to read the whole man page to find
what you need.
.IP \fBSTARTUP\fP 1.9i
Describes \fBdmake\fP initialization.
.IP \fBSYNTAX\fP 1.9i
Describes the syntax of makefile expressions.
.IP \fBATTRIBUTES\fP 1.9i
Describes the notion of attributes and how they are used when
making targets.
.IP \fBMACROS\fP 1.9i
Defining and expanding macros.
.IP "\fBRULES AND TARGETS" 1.9i
How to define targets and their prerequisites.
.IP \fBRECIPES\fP 1.9i
How to tell \fBdmake\fP how to make a target.
.IP "\fBTEXT DIVERSIONS\fP" 1.9i
How to use text diversions in recipes and macro expansions.
.IP "\fBSPECIAL TARGETS\fP" 1.9i
Some targets are special.
.IP "\fBSPECIAL MACROS\fP" 1.9i
Macros used by \fBdmake\fP to alter the processing of the makefile,
and those defined by \fBdmake\fP for the user.
.IP "\fBCONTROL MACROS\fP" 1.9i
Itemized list of special control macros.
.IP "\fBRUN-TIME MACROS\fP" 1.9i
Discussion of special run-time macros such as $@ and $<.
.IP "\fBFUNCTION MACROS\fP" 1.9i
GNU style function macros, only $(mktmp ...) for now.
.IP "\fBDYNAMIC PREREQUISITES\fP" 1.9i
Processing of prerequisites which contain macro expansions in their name.
.IP "\fBBINDING TARGETS\fP" 1.9i
The rules that \fBdmake\fP uses to bind
a target to an existing file in the file system.
.IP "\fBPERCENT(%) RULES\fP" 1.9i
Specification of recipes to be used by the inference algorithm.
.IP "\fBMAKING INFERENCES\fP" 1.9i
The rules that \fBdmake\fP uses when inferring how to make a target which
has no explicit recipe.  This and the previous section are really a single
section in the text.
.IP "\fBMAKING TARGETS\fP" 1.9i
How \fBdmake\fP makes targets other than libraries.
.IP "\fBMAKING LIBRARIES\fP" 1.9i
How \fBdmake\fP makes libraries.
.IP "\fBKEEP STATE\fP" 1.9i
A discussion of how .KEEP_STATE works.
.IP "\fBMULTI PROCESSING\fP" 1.9i
Discussion of \fBdmake's\fP parallel make facilities for architectures that
support them.
.IP "\fBCONDITIONALS\fP" 1.9i
Conditional expressions which control the processing of the makefile.
.IP "\fBEXAMPLES\fP" 1.9i
Some hopefully useful examples.
.IP "\fBCOMPATIBILITY\fP" 1.9i
How \fBdmake\fP compares with previous versions of make.
.IP "\fBLIMITS\fP" 1.9i
Limitations of \fBdmake\fP.
.IP \fBPORTABILITY\fP 1.9i
Comments on writing portable makefiles.
.IP \fBFILES\fP 1.9i
Files used by \fBdmake\fP.
.IP "\fBSEE ALSO\fP" 1.9i
Other related programs, and man pages.
.IP "\fBAUTHOR\fP" 1.9i
The guy responsible for this thing.
.IP \fBBUGS\fP 1.9i
Hope not.
.SH STARTUP
When
.B dmake
begins execution it first processes the command line and then processes
an initial startup-makefile.
This is followed by an attempt to locate and process a user supplied makefile.
The startup file defines the default values of all required control macros
and the set of default rules for making targets and inferences.
When searching for the startup makefile,
.B dmake
searches the following locations, in the order specified,
until a startup file is located:
.LP
.RS
.IP 1.
The location given as the value of the macro
MAKESTARTUP defined on the command line.
.IP 2.
The location given as the value of the environment variable MAKESTARTUP
defined in the current environment.
.IP 3.
The location given as the value of the macro
MAKESTARTUP defined internally within \fBdmake\fP.
.RE
.LP
The above search is disabled by specifying the -r option on the command line.
An error is issued if a startup makefile cannot be found and the -r
option was not specified.
A user may substitute a custom startup file by defining
the MAKESTARTUP environment variable or by redefining the
MAKESTARTUP macro on the command line.
To determine where
.B dmake
looks for the default startup file, check your environment or issue the command
\fI"dmake \-V"\fP.
.PP
A similar search is performed to locate a default user makefile when no
\fB-f\fP command line option is specified.
By default, the prerequisite list of the special target .MAKEFILES
specifies the names of possible makefiles and the search order that
\fBdmake\fP should use to determine if one exists.
A typical definition for this target is:
.RS
.sp
\&.MAKEFILES : makefile.mk Makefile makefile
.sp
.RE
\fBdmake\fP will first look for makefile.mk and then the others.
If a prerequisite
cannot be found \fBdmake\fP will try to make it before going on to the next
prerequisite.  For example, makefile.mk can be checked out of an RCS file
if the proper rules for doing so are defined in the startup file.
.SH SYNTAX
This section is a summary of the syntax of makefile statements.
The description is given in a style similar to BNF, where { } enclose
items that may appear zero or more times, and [ ] enclose items that
are optional.  Alternative productions for a left hand side are indicated
by '\(->', and newlines are significant.  All symbols in \fBbold\fP type
are text or names representing text supplied by the user.
.sp 2
.RS
.Ip "Makefile" "\(-> { Statement }"
.Ip "Statement" "\(-> Macro-Definition"
\(-> Conditional
\(-> Rule-Definition
\(-> Attribute-Definition
.Ip "Macro-Definition" "\(-> \fBMACRO = LINE\fP"
\(-> \fBMACRO *= LINE\fP
\(-> \fBMACRO := LINE\fP
\(-> \fBMACRO *:= LINE\fP
\(-> \fBMACRO += LINE\fP
\(-> \fBMACRO +:= LINE\fP
.Ip "Conditional \(-> " "\fB\&.IF\fR expression"
X   Makefile
[ \fB.ELIF\fR expression
X   Makefile ]
[ \fB.ELSE\fR
X   Makefile ]
\fB\&.END\fR
.Ip expression    "\(-> \fBLINE\fR"
\(-> \fBSTRING == LINE\fR
\(-> \fBSTRING != LINE\fR
.sp
.Ip "Rule-Definition \(-> " "target-definition"
X   [ recipe ]
.PP
target-definition \(-> targets [attrs] op { \fBPREREQUISITE\fP } [\fB;\fR rcp-line]
.Ip "targets" "\(-> target { targets }"
\(-> \fB"\fRtarget\fB"\fR { targets }
.Ip "target" "\(-> special-target"
\(-> \fBTARGET\fR
.Ip "attrs" "\(-> attribute { attrs }"
\(-> \fB"\fRattribute\fB"\fR { attrs }
.Ip "op" "\(-> \fB:\fR { modifier }"
.Ip "modifier" "\(-> \fB:\fR"
\(-> \fB^\fR
\(-> \fB!\fR
\(-> \fB-\fR
.Ip "recipe" "\(-> { \fBTAB\fR rcp-line }"
\(-> [\fB@\fR][\fB%\fR][\fB-\fR] \fB[
.Is "recipe \(-> "
.Ii " "
X   \fR{ \fBLINE\fR }
.Ii " "
\fB]\fR
.Ip "rcp-line" "\(-> [\fB@\fR][\fB%\fR][\fB-\fR][\fB+\fR] \fBLINE\fR"
.sp
.Ip Attribute-Definition "\(-> attrs \fB:\fR targets"
.sp
.Ip "attribute"     "\(-> \fB.EPILOG\fR"
\(-> \fB.IGNORE\fR
\(-> \fB.LIBRARY\fR
\(-> \fB.MKSARGS\fR
\(-> \fB.NOINFER\fR
\(-> \fB.NOSTATE\fR
\(-> \fB.PHONY\fR
\(-> \fB.PRECIOUS\fR
\(-> \fB.PROLOG\fR
\(-> \fB.SETDIR=\fIpath\fP\fR
\(-> \fB.SILENT\fR
\(-> \fB.SEQUENTIAL\fR
\(-> \fB.SWAP\fR
\(-> \fB.USESHELL\fR
\(-> \fB.SYMBOL\fR
\(-> \fB.UPDATEALL\fR
.Ip "special-target" "\(-> \fB.ERROR\fR"
\(-> \fB.EXPORT\fR
\(-> \fB.GROUPEPILOG\fR
\(-> \fB.GROUPPROLOG\fR
\(-> \fB.IMPORT\fR
\(-> \fB.INCLUDE\fR
\(-> \fB.INCLUDEDIRS\fR
\(-> \fB.MAKEFILES\fR
\(-> \fB.REMOVE\fR
\(-> \fB.SOURCE\fR
\(-> \fB.SOURCE.\fIsuffix\fR
\(-> .\fIsuffix1\fR.\fIsuffix2\fR
.fi
.RE
.sp 1
.PP
Where, \fBTAB\fP represents a <tab> character, \fBSTRING\fP represents an
arbitrary sequence of characters, and
\fBLINE\fP represents a
possibly empty sequence of characters terminated by a non-escaped
(not immediately preceded by a backslash '\\') new-line character.
\fBMACRO\fP, \fBPREREQUISITE\fP,
and \fBTARGET\fP each represent a string of characters not
including space or tab which respectively form the name of a macro,
prerequisite or target.
The name may itself be a macro expansion expression.
A \fBLINE\fP can be continued over several physical lines by terminating it with
a single backslash character.  Comments are initiated by the
pound \fB#\fR character and extend to the end of line.
All comment text is discarded, a '#' may be placed into the makefile text
by escaping it with '\\' (ie. \\# translates to # when it is parsed).
An exception to this occurs when a # is seen inside
a recipe line that begins with a <tab> or is inside a group recipe.
If you specify the \fB-c\fP command line switch then this behavior is
disabled and
.B dmake
will treat all # characters as start of comment indicators unless they
SHAR_EOF
true || echo 'restore of dmake/man/dmake.tf failed'
fi
echo 'End of part 18, continue with part 19'
echo 19 > _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].