home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / dmake40x.zip / man / dmake.anu < prev    next >
Text File  |  1998-07-06  |  141KB  |  3,575 lines
  1.  
  2.  
  3.  
  4.  
  5. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  6.  
  7.  
  8.  
  9. NAME
  10.      dmake - maintain program groups, or interdependent files
  11.  
  12. SYNOPSIS
  13.      dmake [-P#] [-{f|C|K} file] [-{w|W} target ...]
  14.      [macro[[!][*][+][:]]=value ...] [-v{cdfimt}]
  15.      [-ABcdeEghiknpqrsStTuVxX] [target ...]
  16.  
  17. DESCRIPTION
  18.      dmake is a re-implementation of the UNIX Make utility with
  19.      significant enhancements.  dmake executes commands found in
  20.      an external file called a makefile to update one or more
  21.      target names.  Each target may depend on zero or more prere-
  22.      quisite targets.  If any of the target's prerequisites is
  23.      newer than the target or if the target itself does not
  24.      exist, then dmake will attempt to make the target.
  25.  
  26.      If no -f command line option is present then dmake searches
  27.      for an existing makefile from the list of prerequisites
  28.      specified for the special target .MAKEFILES (see the STARTUP
  29.      section for more details).  If "-" is the name of the file
  30.      specified to the -f flag then dmake uses standard input as
  31.      the source of the makefile text.
  32.  
  33.      Any macro definitions (arguments with embedded "=" signs)
  34.      that appear on the command line are processed first and
  35.      supercede definitions for macros of the same name found
  36.      within the makefile.  In general it is impossible for defin-
  37.      itions found inside the makefile to redefine a macro defined
  38.      on the command line, see the MACROS section for exceptions.
  39.  
  40.      If no target names are specified on the command line, then
  41.      dmake uses the first non-special target found in the
  42.      makefile as the default target.  See the SPECIAL TARGETS
  43.      section for the list of special targets and their function.
  44.      Makefiles written for most previous versions of Make will be
  45.      handled correctly by dmake. Known differences between dmake
  46.      and other versions of make are discussed in the COMPATIBIL-
  47.      ITY section found at the end of this document.  dmake
  48.      returns 0 if no errors were detected and a non-zero result
  49.      if an error occurred.
  50.  
  51. OPTIONS
  52.      -A   Enable AUGMAKE special inference rule transformations
  53.           (see the "PERCENT(%) RULES" section), these are set to
  54.           off by default.
  55.  
  56.      -B   Enable the use of spaces instead of <tabs> to begin
  57.           recipe lines.  This flag equivalent to the .NOTABS spe-
  58.           cial macro and is further described below.
  59.  
  60.  
  61.  
  62.  
  63.  
  64. Version 3.9 PL0                 UW                              1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  71.  
  72.  
  73.  
  74.      -c   Use non-standard comment stripping.  If you specify -c
  75.           then dmake will treat any # character as a start of
  76.           comment character wherever it may appear unless it is
  77.           escaped by a \.
  78.  
  79.      -C [+]file
  80.           This option writes to file a copy of standard output
  81.           and standard error from any child processes and from
  82.           the dmake process itself.  If you specify a + prior to
  83.           the file name then the text is appended to the previous
  84.           contents of file.  This option is active in the MSDOS
  85.           implementation only and is ignored by non-MSDOS ver-
  86.           sions of dmake.
  87.  
  88.      -d   Disable the use of the directory cache.  Normally dmake
  89.           caches directories as it checks file timestamps.  Giv-
  90.           ing this flag is equivalent to the .DIRCACHE attribute
  91.           or macro being set to no.
  92.  
  93.      -E   Read the environment and define all strings of the form
  94.           'ENV-VAR=evalue' defined within as macros whose name is
  95.           ENV-VAR, and whose value is 'evalue'.  The environment
  96.           is processed prior to processing the user specified
  97.           makefile thereby allowing definitions in the makefile
  98.           to override definitions in the environment.
  99.  
  100.      -e   Same as -E, except that the environment is processed
  101.           after the user specified makefile has been processed
  102.           (thus definitions in the environment override defini-
  103.           tions in the makefile).  The -e and -E options are
  104.           mutually exclusive.  If both are given the latter takes
  105.           effect.
  106.  
  107.      -f file
  108.           Use file as the source for the makefile text.  Only one
  109.           -f option is allowed.
  110.  
  111.      -g   Globally disable group recipe parsing, equivalent to
  112.           the .IGNOREGROUP attribute or macro being set to yes at
  113.           the start of the makefile.
  114.  
  115.      -h   Print the command summary for dmake.
  116.  
  117.      -i   Tells dmake to ignore errors, and continue making other
  118.           targets.  This is equivalent to the .IGNORE attribute
  119.           or macro.
  120.  
  121.      -K file
  122.           Turns on .KEEP_STATE state tracking and tells dmake to
  123.           use file as the state file.
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Version 3.9 PL0                 UW                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  136.  
  137.  
  138.  
  139.      -k   Causes dmake to ignore errors caused by command execu-
  140.           tion and to make all targets not depending on targets
  141.           that could not be made. Ordinarily dmake stops after a
  142.           command returns a non-zero status, specifying -k causes
  143.           dmake to ignore the error and continue to make as much
  144.           as possible.
  145.  
  146.      -n   Causes dmake to print out what it would have executed,
  147.           but does not actually execute the commands.  A special
  148.           check is made for the string "$(MAKE)" inside a recipe
  149.           line, if found, the line is expanded and invoked,
  150.           thereby enabling recursive makes to give a full
  151.           description of all that they will do.  The check for
  152.           "$(MAKE)" is disabled inside group recipes.
  153.  
  154.      -p   Print out a version of the digested makefile in human
  155.           readable form.  (useful for debugging, but cannot be
  156.           re-read by dmake)
  157.  
  158.      -P#  On systems that support multi-processing cause dmake to
  159.           use # concurrent child processes to make targets.  See
  160.           the "MULTI PROCESSING" section for more information.
  161.  
  162.      -q   Check and see if the target is up to date.  Exits with
  163.           code 0 if up to date, 1 otherwise.
  164.  
  165.      -r   Tells dmake not to read the initial startup makefile,
  166.           see STARTUP section for more details.
  167.  
  168.      -s   Tells dmake to do all its work silently and not echo
  169.           the commands it is executing to stdout (also suppresses
  170.           warnings).  This  is equivalent to the .SILENT attri-
  171.           bute or macro.
  172.  
  173.      -S   Force sequential execution of recipes on architectures
  174.           which support concurrent makes.  For backward compati-
  175.           bility with old makefiles that have nasty side-effect
  176.           prerequisite dependencies.
  177.  
  178.      -t   Causes dmake to touch the targets and bring them up to
  179.           date without executing any commands.  Note that targets
  180.           will not be created if they do not already exist.
  181.  
  182.      -T   Tells dmake to not perform transitive closure on the
  183.           inference graph.
  184.  
  185.      -u   Force an unconditional update.  (ie. do everything that
  186.           would be done if everything that a target depended on
  187.           was out of date)
  188.  
  189.      -v[dfimt]
  190.           Verbose flag, when making targets print to stdout what
  191.  
  192.  
  193.  
  194. Version 3.9 PL0                 UW                              3
  195.  
  196.  
  197.  
  198.  
  199.  
  200. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  201.  
  202.  
  203.  
  204.           we are going to make and what we think its time stamp
  205.           is.  The optional flags [dfimt] can be used to restrict
  206.           the information that is displayed.  In the absence of
  207.           any optional flags all are assumed to be given (ie. -v
  208.           is equivalent to -vdfimt).  The meanings of the
  209.           optional flags are:
  210.  
  211.           d    Notify of change directory operations only.
  212.  
  213.           f    Notify of file I/O operations only.
  214.  
  215.           i    Notify of inference algorithm operation only.
  216.  
  217.           m    Notify of target update operations only.
  218.  
  219.           t    Keep any temporary files created; normally they
  220.                are automatically deleted.
  221.  
  222.      -V   Print the version of dmake, and values of builtin mac-
  223.           ros.
  224.  
  225.      -W target
  226.           Run dmake pretending that target is out of date.
  227.  
  228.      -w target
  229.           What if? Show what would be made if target were out of
  230.           date.
  231.  
  232.      -x   Upon processing the user makefile export all non-
  233.           internally defined macros to the user's environment.
  234.           This option together with the -e option allows SYSV
  235.           AUGMAKE recursive makes to function as expected.
  236.  
  237.      -X   Inhibit the execution of #! lines found at the begin-
  238.           ning of a makefile.  The use of this flag prevents
  239.           non-termination of recursive make invocations.
  240.  
  241. INDEX
  242.      Here is a list of the sections that follow and a short
  243.      description of each.  Perhaps you won't have to read the
  244.      entire man page to find what you need.
  245.  
  246.      STARTUP            Describes dmake initialization.
  247.  
  248.      SYNTAX             Describes the syntax of makefile expres-
  249.                         sions.
  250.  
  251.      ATTRIBUTES         Describes the notion of attributes and
  252.                         how they are used when making targets.
  253.  
  254.      MACROS             Defining and expanding macros.
  255.  
  256.  
  257.  
  258.  
  259. Version 3.9 PL0                 UW                              4
  260.  
  261.  
  262.  
  263.  
  264.  
  265. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  266.  
  267.  
  268.  
  269.      RULES AND TARGETS  How to define targets and their prere-
  270.                         quisites.
  271.  
  272.      RECIPES            How to tell dmake how to make a target.
  273.  
  274.      TEXT DIVERSIONS    How to use text diversions in recipes and
  275.                         macro expansions.
  276.  
  277.      SPECIAL TARGETS    Some targets are special.
  278.  
  279.      SPECIAL MACROS     Macros used by dmake to alter the pro-
  280.                         cessing of the makefile, and those
  281.                         defined by dmake for the user.
  282.  
  283.      CONTROL MACROS     Itemized list of special control macros.
  284.  
  285.      RUN-TIME MACROS    Discussion of special run-time macros
  286.                         such as $@ and $<.
  287.  
  288.      FUNCTION MACROS    GNU style function macros, only $(mktmp
  289.                         ...) for now.
  290.  
  291.      CONDITIONAL MACROS Target specific conditional macros.
  292.  
  293.      DYNAMIC PREREQUISITES
  294.                         Processing of prerequisites which contain
  295.                         macro expansions in their name.
  296.  
  297.      BINDING TARGETS    The rules that dmake uses to bind a tar-
  298.                         get to an existing file in the file sys-
  299.                         tem.
  300.  
  301.      PERCENT(%) RULES   Specification of recipes to be used by
  302.                         the inference algorithm.
  303.  
  304.      MAKING INFERENCES  The rules that dmake uses when inferring
  305.                         how to make a target which has no expli-
  306.                         cit recipe.  This and the previous sec-
  307.                         tion are really a single section in the
  308.                         text.
  309.  
  310.      MAKING TARGETS     How dmake makes targets other than
  311.                         libraries.
  312.  
  313.      MAKING LIBRARIES   How dmake makes libraries.
  314.  
  315.      KEEP STATE         A discussion of how .KEEP_STATE works.
  316.  
  317.      MULTI PROCESSING   Discussion of dmake's parallel make
  318.                         facilities for architectures that support
  319.                         them.
  320.  
  321.  
  322.  
  323.  
  324. Version 3.9 PL0                 UW                              5
  325.  
  326.  
  327.  
  328.  
  329.  
  330. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  331.  
  332.  
  333.  
  334.      CONDITIONALS       Conditional expressions which control the
  335.                         processing of the makefile.
  336.  
  337.      EXAMPLES           Some hopefully useful examples.
  338.  
  339.      COMPATIBILITY      How dmake compares with previous versions
  340.                         of make.
  341.  
  342.      LIMITS             Limitations of dmake.
  343.  
  344.      PORTABILITY        Comments on writing portable makefiles.
  345.  
  346.      FILES              Files used by dmake.
  347.  
  348.      SEE ALSO           Other related programs, and man pages.
  349.  
  350.      AUTHOR             The guy responsible for this thing.
  351.  
  352.      BUGS               Hope not.
  353.  
  354. STARTUP
  355.      When dmake begins execution it first processes the command
  356.      line and then processes an initial startup-makefile.  This
  357.      is followed by an attempt to locate and process a user sup-
  358.      plied makefile.  The startup file defines the default values
  359.      of all required control macros and the set of default rules
  360.      for making targets and inferences.  When searching for the
  361.      startup makefile, dmake searches the following locations, in
  362.      the order specified, until a startup file is located:
  363.  
  364.           1.   The location given as the value of the macro MAK-
  365.                ESTARTUP defined on the command line.
  366.  
  367.           2.   The location given as the value of the environment
  368.                variable MAKESTARTUP defined in the current
  369.                environment.
  370.  
  371.           3.   The location given as the value of the macro MAK-
  372.                ESTARTUP defined internally within dmake.
  373.  
  374.      The above search is disabled by specifying the -r option on
  375.      the command line.  An error is issued if a startup makefile
  376.      cannot be found and the -r option was not specified.  A user
  377.      may substitute a custom startup file by defining the MAKES-
  378.      TARTUP environment variable or by redefining the MAKESTARTUP
  379.      macro on the command line.  To determine where dmake looks
  380.      for the default startup file, check your environment or
  381.      issue the command "dmake -V".
  382.  
  383.      A similar search is performed to locate a default user
  384.      makefile when no -f command line option is specified.  By
  385.      default, the prerequisite list of the special target
  386.  
  387.  
  388.  
  389. Version 3.9 PL0                 UW                              6
  390.  
  391.  
  392.  
  393.  
  394.  
  395. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  396.  
  397.  
  398.  
  399.      .MAKEFILES specifies the names of possible makefiles and the
  400.      search order that dmake should use to determine if one
  401.      exists.  A typical definition for this target is:
  402.  
  403.           .MAKEFILES : makefile.mk Makefile makefile
  404.  
  405.      dmake will first look for makefile.mk and then the others.
  406.      If a prerequisite cannot be found dmake will try to make it
  407.      before going on to the next prerequisite.  For example,
  408.      makefile.mk can be checked out of an RCS file if the proper
  409.      rules for doing so are defined in the startup file.
  410.  
  411.      If the first line of the user makefile is of the form:
  412.  
  413.           #! command command_args
  414.  
  415.      then dmake will expand and run the command prior to reading
  416.      any additional input.  If the return code of the command is
  417.      zero then dmake will continue on to process the remainder of
  418.      the user makefile, if the return code is non-zero then dmake
  419.      will exit.
  420.  
  421.      dmake builds the internal dependency graph as it parses a
  422.      user specified makefile.  The graph is rooted at the special
  423.      target .ROOT. .ROOT is the top level target that dmake
  424.      builds when it starts to build targets.  All user specified
  425.      targets (those from the command line or taken as defaults
  426.      from the makefile) are made prerequisites of the special
  427.      target .TARGETS.  dmake by default creates the relationship
  428.      that .ROOT depends on .TARGETS and as a result everything is
  429.      made.  This approach allows the user to customize, within
  430.      their makefile, the order and which, target, is built first.
  431.      For example the default makefiles come with settings for
  432.      .ROOT that specify:
  433.  
  434.           .ROOT .PHONY .NOSTATE .SEQUENTIAL : .INIT .TARGETS
  435.           .DONE
  436.  
  437.      with .INIT and .DONE defined as:
  438.  
  439.           .INIT .DONE :;
  440.  
  441.      which nicely emulates the behaviour of Sun's make exten-
  442.      sions.  The building of .ROOT's prerequisites is always
  443.      forced to be sequential.
  444.  
  445. SYNTAX
  446.      This section is a summary of the syntax of makefile state-
  447.      ments.  The description is given in a style similar to BNF,
  448.      where { } enclose items that may appear zero or more times,
  449.      and [ ] enclose items that are optional.  Alternative pro-
  450.      ductions for a left hand side are indicated by '->', and
  451.  
  452.  
  453.  
  454. Version 3.9 PL0                 UW                              7
  455.  
  456.  
  457.  
  458.  
  459.  
  460. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  461.  
  462.  
  463.  
  464.      newlines are significant.  All symbols in bold type are text
  465.      or names representing text supplied by the user.
  466.  
  467.  
  468.  
  469.           Makefile -> { Statement }
  470.  
  471.           Statement -> Macro-Definition
  472.                     -> Conditional-Macro-Definition
  473.                     -> Conditional
  474.                     -> Rule-Definition
  475.                     -> Attribute-Definition
  476.  
  477.           Macro-Definition -> MACRO = LINE
  478.                            -> MACRO [!]*= LINE
  479.                            -> MACRO [!]:= LINE
  480.                            -> MACRO [!]*:= LINE
  481.                            -> MACRO [!]+= LINE
  482.                            -> MACRO [!]+:= LINE
  483.  
  484.           Conditional-Macro-Definition ->  TARGET ?= Macro-
  485.                                            Definition
  486.  
  487.           Conditional ->  .IF expression
  488.                              Makefile
  489.                           [ .ELIF expression
  490.                              Makefile ]
  491.                           [ .ELSE
  492.                              Makefile ]
  493.                           .END
  494.  
  495.           expression -> LINE
  496.                      -> STRING == LINE
  497.                      -> STRING != LINE
  498.  
  499.  
  500.           Rule-Definition ->  target-definition
  501.                                  [ recipe ]
  502.  
  503.           target-definition -> targets [attrs] op { PREREQUISITE } [; rcp-line]
  504.  
  505.           targets -> target { targets }
  506.                   -> "target" { targets }
  507.  
  508.           target -> special-target
  509.                  -> TARGET
  510.  
  511.           attrs -> attribute { attrs }
  512.                 -> "attribute" { attrs }
  513.  
  514.           op -> : { modifier }
  515.  
  516.  
  517.  
  518.  
  519. Version 3.9 PL0                 UW                              8
  520.  
  521.  
  522.  
  523.  
  524.  
  525. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  526.  
  527.  
  528.  
  529.           modifier -> :
  530.                    -> ^
  531.                    -> !
  532.                    -> -
  533.                    -> |
  534.  
  535.           recipe -> { TAB rcp-line }
  536.                  -> [@][%][-] [
  537.                        { LINE }
  538.                     ]
  539.  
  540.           rcp-line -> [@][%][-][+] LINE
  541.  
  542.  
  543.           Attribute-Definition -> attrs : targets
  544.  
  545.  
  546.           attribute -> .EPILOG
  547.                     -> .GROUP
  548.                     -> .IGNORE
  549.                     -> .IGNOREGROUP
  550.                     -> .LIBRARY
  551.                     -> .MKSARGS
  552.                     -> .NOINFER
  553.                     -> .NOSTATE
  554.                     -> .PHONY
  555.                     -> .PRECIOUS
  556.                     -> .PROLOG
  557.                     -> .SETDIR=path
  558.                     -> .SILENT
  559.                     -> .SEQUENTIAL
  560.                     -> .SWAP
  561.                     -> .USESHELL
  562.                     -> .SYMBOL
  563.                     -> .UPDATEALL
  564.  
  565.           special-target -> .ERROR
  566.                          -> .EXIT
  567.                          -> .EXPORT
  568.                          -> .GROUPEPILOG
  569.                          -> .GROUPPROLOG
  570.                          -> .IMPORT
  571.                          -> .INCLUDE
  572.                          -> .INCLUDEDIRS
  573.                          -> .MAKEFILES
  574.                          -> .REMOVE
  575.                          -> .SOURCE
  576.                          -> .SOURCE.suffix
  577.                          -> .suffix1.suffix2
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584. Version 3.9 PL0                 UW                              9
  585.  
  586.  
  587.  
  588.  
  589.  
  590. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  591.  
  592.  
  593.  
  594.      Where, TAB represents a <tab> character, STRING represents
  595.      an arbitrary sequence of characters, and LINE represents a
  596.      possibly empty sequence of characters terminated by a non-
  597.      escaped (not immediately preceded by a backslash '\') new-
  598.      line character.  MACRO, PREREQUISITE, and TARGET each
  599.      represent a string of characters not including space or tab
  600.      which respectively form the name of a macro, prerequisite or
  601.      target.  The name may itself be a macro expansion expres-
  602.      sion.  A LINE can be continued over several physical lines
  603.      by terminating it with a single backslash character.  Com-
  604.      ments are initiated by the pound # character and extend to
  605.      the end of line.  All comment text is discarded, a '#' may
  606.      be placed into the makefile text by escaping it with '\'
  607.      (ie. \# translates to # when it is parsed).  An exception to
  608.      this occurs when a # is seen inside a recipe line that
  609.      begins with a <tab> or is inside a group recipe.  If you
  610.      specify the -c command line switch then this behavior is
  611.      disabled and dmake will treat all # characters as start of
  612.      comment indicators unless they are escaped by \.  A set of
  613.      continued lines may be commented out by placing a single #
  614.      at the start of the first line.  A continued line cannot
  615.      span more than one makefile.
  616.  
  617.      white space is defined to be any combination of <space>,
  618.      <tab>, and the sequence \<nl> when \<nl> is used to ter-
  619.      minate a LINE.  When processing macro definition lines, any
  620.      amount of white space is allowed on either side of the macro
  621.      operator and white space is stripped from both before and
  622.      after the macro value string.  The sequence \<nl> is treated
  623.      as white space during recipe expansion and is deleted from
  624.      the final recipe string.  You must escape the \<nl> with
  625.      another \ in order to get a \ at the end of a recipe line.
  626.      The \<nl> sequence is deleted from macro values when they
  627.      are expanded.
  628.  
  629.      When processing target definition lines, the recipe for a
  630.      target must, in general, follow the first definition of the
  631.      target (See the RULES AND TARGETS section for an exception),
  632.      and the recipe may not span across multiple makefiles.  Any
  633.      targets and prerequisites found on a target definition line
  634.      are taken to be white space separated tokens.  The rule
  635.      operator (op in SYNTAX section) is also considered to be a
  636.      token but does not require white space to precede or follow
  637.      it.  Since the rule operator begins with a `:', traditional
  638.      versions of make do not allow the `:' character to form a
  639.      valid target name.  dmake allows `:' to be present in
  640.      target/prerequisite names as long as the entire
  641.      target/prerequisite name is quoted.  For example:
  642.  
  643.           a:fred : test
  644.  
  645.      would be parsed as TARGET = a, PREREQUISITES={fred, :,
  646.  
  647.  
  648.  
  649. Version 3.9 PL0                 UW                             10
  650.  
  651.  
  652.  
  653.  
  654.  
  655. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  656.  
  657.  
  658.  
  659.      test}, which is not what was intended.  To fix this you must
  660.      write:
  661.  
  662.           "a:fred" : test
  663.  
  664.      Which will be parsed as expected.  Quoted target and prere-
  665.      quisite specifications may also contain white space thereby
  666.      allowing the use of complex function macro expressions..
  667.      See the EXAMPLES section for how to apply " quoting to a
  668.      list of targets.
  669.  
  670. ATTRIBUTES
  671.      dmake defines several target attributes.  Attributes may be
  672.      assigned to a single target, a group of targets, or to all
  673.      targets in the makefile.  Attributes are used to modify
  674.      dmake actions during target update.  The recognized attri-
  675.      butes are:
  676.  
  677.  
  678.      .EPILOG     Insert shell epilog code when executing a group
  679.                  recipe associated with any target having this
  680.                  attribute set.
  681.  
  682.      .FIRST      Used in conjunction with .INCLUDE.  Terminates
  683.                  the inclusion with the first successfully
  684.                  included prerequisite.
  685.  
  686.      .GROUP      Force execution of a target's recipe as a group
  687.                  recipe.
  688.  
  689.      .IGNORE     Ignore an error when trying to make any target
  690.                  with this attribute set.
  691.  
  692.      .IGNOREGROUP
  693.                  Disable the special meaning of '[' to initiate a
  694.                  group recipe.
  695.  
  696.      .LIBRARY    Target is a library.
  697.  
  698.      .MKSARGS    If running in an MSDOS environment then use MKS
  699.                  extended argument passing conventions to pass
  700.                  arguments to commands.  Non-MSDOS environments
  701.                  ignore this attribute.
  702.  
  703.      .NOINFER    Any target with this attribute set will not be
  704.                  subjected to transitive closure if it is
  705.                  inferred as a prerequisite of a target whose
  706.                  recipe and prerequisites are being inferred.
  707.                  (i.e. the inference algorithm will not use any
  708.                  prerequisite with this attribute set, as a tar-
  709.                  get) If specified as '.NOINFER:' (ie. with no
  710.                  prerequisites or targets) then the effect is
  711.  
  712.  
  713.  
  714. Version 3.9 PL0                 UW                             11
  715.  
  716.  
  717.  
  718.  
  719.  
  720. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  721.  
  722.  
  723.  
  724.                  equivalent to specifying -T on the command line.
  725.  
  726.      .NOSTATE    Any target with this attribute set will not have
  727.                  command line flag information stored in the
  728.                  state file if .KEEP_STATE has been enabled.
  729.  
  730.      .PHONY      Any target with this attribute set will have its
  731.                  recipe executed each time the target is made
  732.                  even if a file matching the target name can be
  733.                  located.  Any targets that have a .PHONY attri-
  734.                  buted target as a prerequisite will be made each
  735.                  time the .PHONY attributed prerequisite is made.
  736.  
  737.      .PRECIOUS   Do not remove associated target under any cir-
  738.                  cumstances.  Set by default for any targets
  739.                  whose corresponding files exist in the file sys-
  740.                  tem prior to the execution of dmake.
  741.  
  742.      .PROLOG     Insert shell prolog code when executing a group
  743.                  recipe associated with any target having this
  744.                  attribute set.
  745.  
  746.      .SEQUENTIAL Force a sequential make of the associated
  747.                  target's prerequisites.
  748.  
  749.      .SETDIR     Change current working directory to specified
  750.                  directory when making the associated target.
  751.                  You must specify the directory at the time the
  752.                  attribute is specified.  To do this simply give
  753.                  .SETDIR=path as the attribute.  path is expanded
  754.                  and the result is used as the value of the
  755.                  directory to change to.  If path contains $$@
  756.                  then the name of the target to be built is used
  757.                  in computing the path to change directory to.
  758.                  If path is surrounded by single quotes then path
  759.                  is not expanded, and is used literally as the
  760.                  directory name.  If the path contains any `:'
  761.                  characters then the entire attribute string must
  762.                  be quoted using ".  If a target having this
  763.                  attribute set also has the .IGNORE attribute set
  764.                  then if the change to the specified directory
  765.                  fails it will be ignored, and no error message
  766.                  will be issued.
  767.  
  768.      .SILENT     Do not echo the recipe lines when making any
  769.                  target with this attribute set, and do not issue
  770.                  any warnings.
  771.  
  772.      .SWAP       Under MSDOS when making a target with this
  773.                  attribute set swap the dmake executable to disk
  774.                  prior to executing the recipe line.  Also see
  775.                  the '%' recipe line flag defined in the RECIPES
  776.  
  777.  
  778.  
  779. Version 3.9 PL0                 UW                             12
  780.  
  781.  
  782.  
  783.  
  784.  
  785. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  786.  
  787.  
  788.  
  789.                  section.
  790.  
  791.      .SYMBOL     Target is a library member and is an entry point
  792.                  into a module in the library.  This attribute is
  793.                  used only when searching a library for a target.
  794.                  Targets of the form lib((entry)) have this
  795.                  attribute set automatically.
  796.  
  797.      .USESHELL   Force each recipe line of a target to be exe-
  798.                  cuted using a shell.  Specifying this attribute
  799.                  is equivalent to specifying the '+' character at
  800.                  the start of each line of a non-group recipe.
  801.  
  802.      .UPDATEALL  Indicates that all the targets listed in this
  803.                  rule are updated by the execution of the accom-
  804.                  panying recipe.  A common example is the produc-
  805.                  tion of the y.tab.c and y.tab.h files by yacc
  806.                  when it is run on a grammar.  Specifying
  807.                  .UPDATEALL in such a rule prevents the running
  808.                  of yacc twice, once for the y.tab.c file and
  809.                  once for the y.tab.h file.  .UPDATEALL targets
  810.                  that are specified in a single rule are treated
  811.                  as a single target and all timestamps are
  812.                  updated whenever any target in the set is made.
  813.                  As a side-effect, dmake internally sorts such
  814.                  targets in ascending alphabetical order and the
  815.                  value of $@ is always the first target in the
  816.                  sorted set.
  817.  
  818.      All attributes are user setable and except for .UPDATEALL,
  819.      .SETDIR and .MKSARGS may be used in one of two forms.  The
  820.      .MKSARGS attribute is restricted to use as a global attri-
  821.      bute, and the use of the .UPDATEALL and .SETDIR attributes
  822.      is restricted to rules of the second form only.
  823.  
  824.           ATTRIBUTE_LIST : targets
  825.  
  826.      assigns the attributes specified by ATTRIBUTE_LIST to each
  827.      target in targets or
  828.  
  829.           targets ATTRIBUTE_LIST : ...
  830.  
  831.      assigns the attributes specified by ATTRIBUTE_LIST to each
  832.      target in targets. In the first form if targets is empty
  833.      (ie. a NULL list), then the list of attributes will apply to
  834.      all targets in the makefile (this is equivalent to the com-
  835.      mon Make construct of ".IGNORE :" but has been modified to
  836.      the notion of an attribute instead of a special target).
  837.      Not all of the attributes have global meaning.  In particu-
  838.      lar, .LIBRARY, .NOSTATE, .PHONY, .SETDIR, .SYMBOL and
  839.      .UPDATEALL have no assigned global meaning.
  840.  
  841.  
  842.  
  843.  
  844. Version 3.9 PL0                 UW                             13
  845.  
  846.  
  847.  
  848.  
  849.  
  850. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  851.  
  852.  
  853.  
  854.      Any attribute may be used with any target, even with the
  855.      special targets.  Some combinations are useless (e.g.
  856.      .INCLUDE .PRECIOUS: ... ), while others are useful (e.g.
  857.      .INCLUDE .IGNORE : "file.mk" will not complain if file.mk
  858.      cannot be found using the include file search rules, see the
  859.      section on SPECIAL TARGETS for a description of .INCLUDE).
  860.      If a specified attribute will not be used with the special
  861.      target a warning is issued and the attribute is ignored.
  862.  
  863. MACROS
  864.      dmake supports six forms of macro assignment.
  865.  
  866.  
  867.      MACRO = LINE    This is the most common and familiar form of
  868.                      macro assignment.  It assigns LINE literally
  869.                      as the value of MACRO.  Future expansions of
  870.                      MACRO recursively expand its value.
  871.  
  872.      MACRO *= LINE   This form behaves exactly as the simple '='
  873.                      form with the exception that if MACRO
  874.                      already has a value then the assignment is
  875.                      not performed.
  876.  
  877.      MACRO := LINE   This form differs from the simple '=' form
  878.                      in that it expands LINE prior to assigning
  879.                      it as the value of MACRO.  Future expansions
  880.                      of MACRO do not recursively expand its
  881.                      value.
  882.  
  883.      MACRO *:= LINE  This form behaves exactly as the ':=' form
  884.                      with the exception that if MACRO already has
  885.                      a value then the assignment and expansion
  886.                      are not performed.
  887.  
  888.      MACRO += LINE   This form of macro assignment allows macro
  889.                      values to grow.  It takes the literal value
  890.                      of LINE and appends it to the previous value
  891.                      of MACRO separating the two by a single
  892.                      space.  Future expansions of MACRO recur-
  893.                      sively expand its value.
  894.  
  895.      MACRO +:= LINE  This form is similar to the '+=' form except
  896.                      that the value of LINE is expanded prior to
  897.                      being added to the value of MACRO.
  898.  
  899.      Macro expressions specified on the command line allow the
  900.      macro value to be redefined within the makefile only if the
  901.      macro is defined using the '+=' and '+:=' operators.  Other
  902.      operators will define a macro that cannot be further modi-
  903.      fied.
  904.  
  905.  
  906.  
  907.  
  908.  
  909. Version 3.9 PL0                 UW                             14
  910.  
  911.  
  912.  
  913.  
  914.  
  915. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  916.  
  917.  
  918.  
  919.      Each of the preceeding macro assignment operators may be
  920.      prefixed by !  to indicate that the assignment should be
  921.      forced and that no warnings should be issued.  Thus, speci-
  922.      fying ! has the effect of silently forcing the specified
  923.      macro assignment.
  924.  
  925.      When dmake defines a non-environment macro it strips leading
  926.      and trailing white space from the macro value.  Macros
  927.      imported from the environment via either the .IMPORT special
  928.      target (see the SPECIAL TARGETS section), or the -e, or -E
  929.      flags are an exception to this rule.  Their values are
  930.      always taken literally and white space is never stripped.
  931.      In addition, named macros defined using the .IMPORT special
  932.      target do not have their values expanded when they are used
  933.      within a makefile.  In contrast, environment macros that are
  934.      imported due to the specification of the -e or -E flags are
  935.      subject to expansion when used.
  936.  
  937.      To specify a macro expansion enclose the name in () or {}
  938.      and precede it with a dollar sign $.  Thus $(TEST)
  939.      represents an expansion of the macro variable named TEST.
  940.      If TEST is defined then $(TEST) is replaced by its expanded
  941.      value.  If TEST is not defined then $(TEST) expands to the
  942.      NULL string (this is equivalent to defining a macro as
  943.      'TEST=' ).  A short form may be used for single character
  944.      named macros.  In this case the parentheses are optional,
  945.      and $(I) is equivalent to $I.  Macro expansion is recursive,
  946.      hence, if the value string contains an expression represent-
  947.      ing a macro expansion, the expansion is performed.  Circular
  948.      macro expansions are detected and cause an error to be
  949.      issued.
  950.  
  951.      When defining a macro the given macro name is first expanded
  952.      before being used to define the macro.  Thus it is possible
  953.      to define macros whose names depend on values of other mac-
  954.      ros.  For example, suppose CWD is defined as
  955.  
  956.           CWD = $(PWD:b)
  957.  
  958.      then the value of $(CWD) is the name of the current direc-
  959.      tory.  This can be used to define macros specific to this
  960.      directory, for example:
  961.  
  962.           _$(CWD).prt = list of files to print...
  963.  
  964.      The actual name of the defined macro is a function of the
  965.      current directory.  A construct such as this is useful when
  966.      processing a hierarchy of directories using .SETDIR attri-
  967.      buted targets and a collection of small distributed makefile
  968.      stubs.
  969.  
  970.  
  971.  
  972.  
  973.  
  974. Version 3.9 PL0                 UW                             15
  975.  
  976.  
  977.  
  978.  
  979.  
  980. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  981.  
  982.  
  983.  
  984.      Macro variables may be defined within the makefile, on the
  985.      command line, or imported from the environment.
  986.  
  987.      dmake supports several non-standard macro expansions: The
  988.      first is of the form:
  989.  
  990.           $(macro_name:modifier_list:modifier_list:...)
  991.  
  992.      where modifier_list is chosen from the set { B or b, D or d,
  993.      E or e, F or f, I or i, L or l, S or s, T or t, U or u, ^, +
  994.      } and
  995.  
  996.           b  - file (not including suffix) portion of path names
  997.           d  - directory portion of all path names
  998.           e  - suffix portion of path names
  999.           f  - file (including suffix) portion of path names
  1000.           i  - inferred names of targets
  1001.           l  - macro value in lower case
  1002.           s  - simple pattern substitution
  1003.           t  - tokenization.
  1004.           u  - macro value in upper case
  1005.           ^  - prepend a prefix to each token
  1006.           +  - append a suffix to each token
  1007.  
  1008.      Thus if we have the example:
  1009.  
  1010.           test = d1/d2/d3/a.out f.out d1/k.out
  1011.  
  1012.      The following macro expansions produce the values on the
  1013.      right of '->' after expansion.
  1014.  
  1015.           $(test:d)             -> d1/d2/d3/ d1/
  1016.           $(test:b)             -> a f k
  1017.           $(test:f)             -> a.out f.out k.out
  1018.           ${test:db}            -> d1/d2/d3/a f d1/k
  1019.           ${test:s/out/in/:f}   -> a.in f.in k.in
  1020.           $(test:f:t"+")        -> a.out+f.out+k.out
  1021.           $(test:e)             -> .out .out .out
  1022.           $(test:u)             -> D1/D2/D3/A.OUT F.OUT D1/K.OUT
  1023.  
  1024.      If a token ends in a string composed from the value of the
  1025.      macro DIRBRKSTR (ie. ends in a directory separator string,
  1026.      e.g. '/' in UNIX) and you use the :d modifier then the
  1027.      expansion returns the directory name less the final direc-
  1028.      tory separator string.  Thus successive pairs of :d modif-
  1029.      iers each remove a level of directory in the token string.
  1030.  
  1031.      The tokenization modifier takes all white space separated
  1032.      tokens from the macro value and separates them by the quoted
  1033.      separator string.  The separator string may contain the fol-
  1034.      lowing escape codes \a => <bel>, \b => <backspace>, \f =>
  1035.      <formfeed>, \n => <nl>, \r => <cr>, \t => <tab>, \v =>
  1036.  
  1037.  
  1038.  
  1039. Version 3.9 PL0                 UW                             16
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1046.  
  1047.  
  1048.  
  1049.      <vertical tab>, \" => ", and \xxx => <xxx> where xxx is the
  1050.      octal representation of a character.  Thus the expansion:
  1051.  
  1052.           $(test:f:t"+\n")
  1053.      produces:
  1054.           a.out+
  1055.           f.out+
  1056.           k.out
  1057.  
  1058.      The prefix operator ^ takes all white space separated tokens
  1059.      from the macro value and prepends string to each.
  1060.  
  1061.           $(test:f:^mydir/)
  1062.      produces:
  1063.           mydir/a.out mydir/f.out mydir/k.out
  1064.  
  1065.      The suffix operator + takes all white space separated tokens
  1066.      from the macro value and appends string to each.
  1067.  
  1068.           $(test:b:+.c)
  1069.      produces:
  1070.           a.c f.c k.c
  1071.  
  1072.      The next non-standard form of macro expansion allows for
  1073.      recursive macros.  It is possible to specify a $(macro_name)
  1074.      or ${macro_name} expansion where macro_name contains more $(
  1075.      ... ) or ${ ... } macro expansions itself.
  1076.  
  1077.      For example $(CC$(_HOST)$(_COMPILER)) will first expand
  1078.      CC$(_HOST)$(_COMPILER) to get a result and use that result
  1079.      as the name of the macro to expand.  This is useful for
  1080.      writing a makefile for more than one target environment.  As
  1081.      an example consider the following hypothetical case. Suppose
  1082.      that _HOST and _COMPILER are imported from the environment
  1083.      and are set to represent the host machine type and the host
  1084.      compiler respectively.
  1085.  
  1086.           CFLAGS_VAX_CC = -c -O     # _HOST == "_VAX", _COMPILER == "_CC"
  1087.           CFLAGS_PC_MSC = -c -ML # _HOST == "_PC",  _COMPILER == "_MSC"
  1088.  
  1089.           # redefine CFLAGS macro as:
  1090.  
  1091.           CFLAGS := $(CFLAGS$(_HOST)$(_COMPILER))
  1092.  
  1093.      This causes CFLAGS to take on a value that corresponds to
  1094.      the environment in which the make is being invoked.
  1095.  
  1096.      The final non-standard macro expansion is of the form:
  1097.  
  1098.           string1{token_list}string2
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104. Version 3.9 PL0                 UW                             17
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1111.  
  1112.  
  1113.  
  1114.      where string1, string2 and token_list are expanded.  After
  1115.      expansion, string1 is prepended to each token found in
  1116.      token_list and string2 is appended to each resulting token
  1117.      from the previous prepend.  string1 and string2 are not del-
  1118.      imited by white space whereas the tokens in token_list are.
  1119.      A null token in the token list is specified using "".  Thus
  1120.      using another example we have:
  1121.  
  1122.           test/{f1 f2}.o     --> test/f1.o test/f2.o
  1123.           test/ {f1 f2}.o    --> test/ f1.o f2.o
  1124.           test/{f1 f2} .o    --> test/f1 test/f2 .o
  1125.           test/{"f1"  ""}.o  --> test/f1.o test/.o
  1126.  
  1127.           and
  1128.  
  1129.           test/{d1 d2}/{f1 f2}.o --> test/d1/f1.o test/d1/f2.o
  1130.                                      test/d2/f1.o test/d2/f2.o
  1131.  
  1132.      This last expansion is activated only when the first charac-
  1133.      ters of token_list appear immediately after the opening '{'
  1134.      with no intervening white space.  The reason for this res-
  1135.      triction is the following incompatibility with Bourne Shell
  1136.      recipes.  The line
  1137.  
  1138.           { echo hello;}
  1139.  
  1140.      is valid /bin/sh syntax; while
  1141.  
  1142.           {echo hello;}
  1143.  
  1144.      is not.  Hence the latter triggers the enhanced macro expan-
  1145.      sion while the former causes it to be suppressed.  See the
  1146.      SPECIAL MACROS section for a description of the special mac-
  1147.      ros that dmake defines and understands.
  1148.  
  1149. RULES AND TARGETS
  1150.      A makefile contains a series of entries that specify depen-
  1151.      dencies.  Such entries are called target/prerequisite or
  1152.      rule definitions.  Each rule definition is optionally fol-
  1153.      lowed by a set of lines that provide a recipe for updating
  1154.      any targets defined by the rule.  Whenever dmake attempts to
  1155.      bring a target up to date and an explicit recipe is provided
  1156.      with a rule defining the target, that recipe is used to
  1157.      update the target.  A rule definition begins with a line
  1158.      having the following syntax:
  1159.  
  1160.           <targets> [<attributes>] <ruleop> [<prerequisites>] [;<recipe>]
  1161.  
  1162.      targets is a non-empty list of targets.  If the target is a
  1163.      special target (see SPECIAL TARGETS section below) then it
  1164.      must appear alone on the rule line.  For example:
  1165.  
  1166.  
  1167.  
  1168.  
  1169. Version 3.9 PL0                 UW                             18
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1176.  
  1177.  
  1178.  
  1179.           .IMPORT .ERROR : ...
  1180.  
  1181.      is not allowed since both .IMPORT and .ERROR are special
  1182.      targets.  Special targets are not used in the construction
  1183.      of the dependency graph and will not be made.
  1184.  
  1185.      attributes is a possibly empty list of attributes.  Any
  1186.      attribute defined in the ATTRIBUTES section above may be
  1187.      specified.  All attributes will be applied to the list of
  1188.      named targets in the rule definition.  No other targets will
  1189.      be affected.
  1190.  
  1191.  
  1192.      NOTE:   As stated earlier, if both the target list and
  1193.              prerequisite list are empty but the attributes list
  1194.              is not, then the specified attributes affect all
  1195.              targets in the makefile.
  1196.  
  1197.  
  1198.      ruleop is a separator which is used to identify the targets
  1199.      from the prerequisites.  Optionally it also provides a
  1200.      facility for modifying the way in which dmake handles the
  1201.      making of the associated targets.  In its simplest form the
  1202.      operator is a single ':', and need not be separated by white
  1203.      space from its neighboring tokens.  It may additionally be
  1204.      followed by any of the modifiers { !, ^, -, :, | }, where:
  1205.  
  1206.  
  1207.      !    says execute the recipe for the associated targets once
  1208.           for each out of date prerequisite.  Ordinarily the
  1209.           recipe is executed once for all out of date prere-
  1210.           quisites at the same time.
  1211.  
  1212.      ^    says to insert the specified prerequisites, if any,
  1213.           before any other prerequisites already associated with
  1214.           the specified targets.  In general, it is not useful to
  1215.           specify ^ with an empty list of prerequisites.
  1216.  
  1217.      -    says to clear the previous list of prerequisites before
  1218.           adding the new prerequisites.  Thus,
  1219.  
  1220.                .SUFFIXES :
  1221.                .SUFFIXES : .a .b
  1222.  
  1223.           can be replaced by
  1224.  
  1225.                .SUFFIXES :- .a .b
  1226.  
  1227.           however the old form still works as expected.  NOTE:
  1228.           .SUFFIXES is ignored by dmake it is used here simply as
  1229.           an example.
  1230.  
  1231.  
  1232.  
  1233.  
  1234. Version 3.9 PL0                 UW                             19
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1241.  
  1242.  
  1243.  
  1244.      :    When the rule operator is not modified by a second ':'
  1245.           only one set of rules may be specified for making a
  1246.           target.  Multiple definitions may be used to add to the
  1247.           list of prerequisites that a target depends on.  How-
  1248.           ever, if a target is multiply defined only one defini-
  1249.           tion may specify a recipe for making the target.
  1250.  
  1251.           When a target's rule operator is modified by a second
  1252.           ':' (:: for example) then this definition may not be
  1253.           the only definition with a recipe for the target.
  1254.           There may be other :: target definition lines that
  1255.           specify a different set of prerequisites with a dif-
  1256.           ferent recipe for updating the target. Any such target
  1257.           is made if any of the definitions find it to be out of
  1258.           date with respect to the related prerequisites and the
  1259.           corresponding recipe is used to update the target.  By
  1260.           definition all '::' recipes that are found to be out of
  1261.           date for are executed.
  1262.  
  1263.           In the following simple example, each rule has a `::'
  1264.           ruleop.  In such an operator we call the first `:' the
  1265.           operator, and the second `:' the modifier.
  1266.  
  1267.           a.o :: a.c b.h
  1268.              first recipe for making a.o
  1269.  
  1270.           a.o :: a.y b.h
  1271.              second recipe for making a.o
  1272.  
  1273.           If a.o is found to be out of date with respect to a.c
  1274.           then the first recipe is used to make a.o.  If it is
  1275.           found out of date with respect to a.y then the second
  1276.           recipe is used.  If a.o is out of date with respect to
  1277.           b.h then both recipes are invoked to make a.o.  In the
  1278.           last case the order of invocation corresponds to the
  1279.           order in which the rule definitions appear in the
  1280.           makefile.
  1281.  
  1282.      |    Is defined only for PERCENT rule target definitions.
  1283.           When specified it indicates that the following con-
  1284.           struct should be parsed using the old semantinc mean-
  1285.           ing:
  1286.  
  1287.           %.o :| %.c %.r %.f ; some rule
  1288.  
  1289.           is equivalent to:
  1290.  
  1291.           %.o : %.c ; some rule
  1292.           %.o : %.r ; some rule
  1293.           %.o : %.f ; some rule
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299. Version 3.9 PL0                 UW                             20
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1306.  
  1307.  
  1308.  
  1309.      Targets defined using a single `:' operator with a recipe
  1310.      may be redefined again with a new recipe by using a `:'
  1311.      operator with a `:' modifier.  This is equivalent to a tar-
  1312.      get having been initially defined with a rule using a `:'
  1313.      modifier.  Once a target is defined using a `:' modifier it
  1314.      may not be defined again with a recipe using only the `:'
  1315.      operator with no `:' modifier.  In both cases the use of a
  1316.      `:' modifier creates a new list of prerequisites and makes
  1317.      it the current prerequisite list for the target.  The `:'
  1318.      operator with no recipe always modifies the current list of
  1319.      prerequisites.  Thus assuming each of the following defini-
  1320.      tions has a recipe attached, then:
  1321.  
  1322.           joe :  fred ...     (1)
  1323.           joe :: more ...     (2)
  1324.  
  1325.           and
  1326.  
  1327.           joe :: fred ...     (3)
  1328.           joe :: more ...     (4)
  1329.  
  1330.      are legal and mean:  add the recipe associated with (2), or
  1331.      (4) to the set of recipes for joe, placing them after exist-
  1332.      ing recipes for making joe.  The constructs:
  1333.  
  1334.           joe :: fred ...     (5)
  1335.           joe : more ... (6)
  1336.  
  1337.           and
  1338.  
  1339.           joe : fred ... (7)
  1340.           joe : more ... (8)
  1341.  
  1342.      are errors since we have two sets of perfectly good recipes
  1343.      for making the target.
  1344.  
  1345.      prerequisites is a possibly empty list of targets that must
  1346.      be brought up to date before making the current target.
  1347.  
  1348.      recipe is a short form and allows the user to specify short
  1349.      rule definitions on a single line.  It is taken to be the
  1350.      first recipe line in a larger recipe if additional lines
  1351.      follow the rule definition.  If the semi-colon is present
  1352.      but the recipe line is empty (ie. null string) then it is
  1353.      taken to be an empty rule.  Any target so defined causes the
  1354.      Don't know how to make ... error message to be suppressed
  1355.      when dmake tries to make the target and fails.  This silence
  1356.      is maintained for rules that are terminated by a semicolon
  1357.      and have no following recipe lines, for targets listed on
  1358.      the command line, for the first target found in the
  1359.      makefile, and for any target having no recipe but containing
  1360.      a list of prerequisites (see the COMPATIBILITY section for
  1361.  
  1362.  
  1363.  
  1364. Version 3.9 PL0                 UW                             21
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1371.  
  1372.  
  1373.  
  1374.      an exception to this rule if the AUGMAKE (-A) flag was
  1375.      specified.
  1376.  
  1377. RECIPES
  1378.      The traditional format used by most versions of Make defines
  1379.      the recipe lines as arbitrary strings that may contain macro
  1380.      expansions.  They follow a rule definition line and may be
  1381.      spaced apart by comment or blank lines.  The list of recipe
  1382.      lines defining the recipe is terminated by a new target
  1383.      definition, a macro definition, or end-of-file.  Each recipe
  1384.      line MUST begin with a <TAB> character which may optionally
  1385.      be followed with one or all of the characters '@%+-'.  The
  1386.      '-' indicates that non-zero exit values (ie. errors) are to
  1387.      be ignored when this recipe line is executed, the '+' indi-
  1388.      cates that the current recipe line is to be executed using
  1389.      the shell, the '%' indicates that dmake should swap itself
  1390.      out to secondary storage (MSDOS only) before running the
  1391.      recipe and the '@' indicates that the recipe line should NOT
  1392.      be echoed to the terminal prior to being executed.  Each
  1393.      switch is off by default (ie. by default, errors are signi-
  1394.      ficant, commands are echoed, no swapping is done and a shell
  1395.      is used only if the recipe line contains a character found
  1396.      in the value of the SHELLMETAS macro).  Global settings
  1397.      activated via command line options or special attribute or
  1398.      target names may also affect these settings.  An example
  1399.      recipe:
  1400.  
  1401.           target :
  1402.                first recipe line
  1403.                second recipe line, executed independently of the first.
  1404.                @a recipe line that is not echoed
  1405.                -and one that has errors ignored
  1406.                %and one that causes dmake to swap out
  1407.                +and one that is executed using a shell.
  1408.  
  1409.      The second and new format of the recipe block begins the
  1410.      block with the character '[' (the open group character) in
  1411.      the last non-white space position of a line, and terminates
  1412.      the block with the character ']' (the close group character)
  1413.      in the first non-white space position of a line.  In this
  1414.      form each recipe line need not have a leading TAB.  This is
  1415.      called a recipe group.  Groups so defined are fed intact as
  1416.      a single unit to a shell for execution whenever the
  1417.      corresponding target needs to be updated.  If the open group
  1418.      character '[' is preceded by one or all of -, @ or % then
  1419.      they apply to the entire group in the same way that they
  1420.      apply to single recipe lines.  You may also specify '+' but
  1421.      it is redundant as a shell is already being used to run the
  1422.      recipe.  See the MAKING TARGETS section for a description of
  1423.      how dmake invokes recipes.  Here is an example of a group
  1424.      recipe:
  1425.  
  1426.  
  1427.  
  1428.  
  1429. Version 3.9 PL0                 UW                             22
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1436.  
  1437.  
  1438.  
  1439.           target :
  1440.           [
  1441.                first recipe line
  1442.                second recipe line
  1443.                all of these recipe lines are fed to a
  1444.                single copy of a shell for execution.
  1445.           ]
  1446.  
  1447.  
  1448. TEXT DIVERSIONS
  1449.      dmake supports the notion of text diversions.  If a recipe
  1450.      line contains the macro expression
  1451.  
  1452.           $(mktmp[,[file][,text]] data)
  1453.  
  1454.      then all text contained in the data expression is expanded
  1455.      and is written to a temporary file.  The return value of the
  1456.      macro is the name of the temporary file.
  1457.  
  1458.      data can be any text and must be separated from the 'mktmp'
  1459.      portion of the macro name by white-space.  The only restric-
  1460.      tion on the data text is that it must contain a balanced
  1461.      number of parentheses of the same kind as are used to ini-
  1462.      tiate the $(mktmp ...) expression.  For example:
  1463.  
  1464.           $(mktmp $(XXX))
  1465.  
  1466.      is legal and works as expected, but:
  1467.  
  1468.           $(mktmp text (to dump to file)
  1469.  
  1470.      is not legal.  You can achieve what you wish by either
  1471.      defining a macro that expands to '(' or by using {} in the
  1472.      macro expression; like this:
  1473.  
  1474.           ${mktmp text (to dump to file}
  1475.  
  1476.      Since the temporary file is opened when the macro containing
  1477.      the text diversion expression is expanded, diversions may be
  1478.      nested and any diversions that are created as part of ':='
  1479.      macro expansions persist for the duration of the dmake run.
  1480.      The diversion text may contain the same escape codes as
  1481.      those described in the MACROS section.  Thus if the data
  1482.      text is to contain new lines they must be inserted using the
  1483.      \n escape sequence.  For example the expression:
  1484.  
  1485.           all:
  1486.                cat $(mktmp this is a\n\
  1487.                test of the text diversion\n)
  1488.  
  1489.      is replaced by:
  1490.  
  1491.  
  1492.  
  1493.  
  1494. Version 3.9 PL0                 UW                             23
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1501.  
  1502.  
  1503.  
  1504.           cat /tmp/mk12294AA
  1505.  
  1506.      where the temporary file contains two lines both of which
  1507.      are terminated by a new-line.  If the data text spans multi-
  1508.      ple lines in the makefile then each line must be continued
  1509.      via the use of a \.  A second more illustrative example gen-
  1510.      erates a response file to an MSDOS link command:
  1511.  
  1512.           OBJ = fred.obj mary.obj joe.obj
  1513.           all : $(OBJ)
  1514.                link @$(mktmp $(^:t"+\n")\n)
  1515.  
  1516.      The result of making `all' in the second example is the com-
  1517.      mand:
  1518.  
  1519.           link @/tmp/mk02394AA
  1520.  
  1521.      where the temporary file contains:
  1522.  
  1523.           fred.obj+
  1524.           mary.obj+
  1525.           joe.obj
  1526.  
  1527.      The last line of the file is terminated by a new-line which
  1528.      is inserted due to the \n found at the end of the data
  1529.      string.
  1530.  
  1531.      If the optional file specifier is present then its expanded
  1532.      value is the name of the temporary file to create.  Whenever
  1533.      a $(mktmp ...) macro is expanded the macro $(TMPFILE) is set
  1534.      to a new temporary file name.  Thus the construct:
  1535.  
  1536.           $(mktmp,$(TMPFILE) data)
  1537.  
  1538.      is completely equivalent to not specifying the $(TMPFILE)
  1539.      optional argument.  Another example that would be useful for
  1540.      MSDOS users with a Turbo-C compiler
  1541.  
  1542.           $(mktmp,turboc.cfg $(CFLAGS))
  1543.  
  1544.      will place the contents of CFLAGS into a local turboc.cfg
  1545.      file.  The second optional argument, text, if present alters
  1546.      the name of the value returned by the $(mktmp ...) macro.
  1547.  
  1548.      Under MS-DOS text diversions may be a problem.  Many DOS
  1549.      tools require that path names which contain directories use
  1550.      the \ character to delimit the directories.  Some users how-
  1551.      ever wish to use the '/' to delimit pathnames and use
  1552.      environments that allow them to do so.  The macro USESHELL
  1553.      is set to "yes" if the current recipe is forced to use a
  1554.      shell via the .USESHELL or '+' directives, otherwise its
  1555.      value is "no".  The dmake startup files define the macro
  1556.  
  1557.  
  1558.  
  1559. Version 3.9 PL0                 UW                             24
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1566.  
  1567.  
  1568.  
  1569.      DIVFILE whose value is either the value of TMPFILE or the
  1570.      value of TMPFILE edited to replace any '/' characters to the
  1571.      appropriate value based on the current shell and whether it
  1572.      will be used to execute the recipe.
  1573.  
  1574.      Previous versions of dmake defined text diversions using <+,
  1575.      +> strings, where <+ started a text diversion and +> ter-
  1576.      minated one.  dmake is backward compatible with this con-
  1577.      struct only if the <+ and +> appear literally on the same
  1578.      recipe line or in the same macro value string.  In such
  1579.      instances the expression:
  1580.  
  1581.           <+data+>
  1582.  
  1583.      is mapped to:
  1584.  
  1585.           $(mktmp data)
  1586.  
  1587.      which is fully output compatible with the earlier construct.
  1588.      <+, +> constructs whose text spans multiple lines must be
  1589.      converted by hand to use $(mktmp ...).
  1590.  
  1591.      If the environment variable TMPDIR is defined then the tem-
  1592.      porary file is placed into the directory specified by that
  1593.      variable.  A makefile can modify the location of temporary
  1594.      files by defining a macro named TMPDIR and exporting it
  1595.      using the .EXPORT special target.
  1596.  
  1597. SPECIAL TARGETS
  1598.      This section describes the special targets that are recog-
  1599.      nized by dmake.  Some are affected by attributes and others
  1600.      are not.
  1601.  
  1602.      .ERROR        If defined then the recipe associated with
  1603.                    this target is executed whenever an error con-
  1604.                    dition is detected by dmake.  All attributes
  1605.                    that can be used with any other target may be
  1606.                    used with this target.  Any prerequisites of
  1607.                    this target will be brought up to date during
  1608.                    its processing.  NOTE:  errors will be ignored
  1609.                    while making this target, in extreme cases
  1610.                    this may cause some problems.
  1611.  
  1612.      .EXIT         If this target is encountered while parsing a
  1613.                    makefile then the parsing of the makefile is
  1614.                    immediately terminated at that point.
  1615.  
  1616.      .EXPORT       All prerequisites associated with this target
  1617.                    are assumed to correspond to macro names and
  1618.                    they and their values are exported to the
  1619.                    environment as environment strings at the
  1620.                    point in the makefile at which this target
  1621.  
  1622.  
  1623.  
  1624. Version 3.9 PL0                 UW                             25
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1631.  
  1632.  
  1633.  
  1634.                    appears.  Any attributes specified with this
  1635.                    target are ignored.  Only macros which have
  1636.                    been assigned a value in the makefile prior to
  1637.                    the export directive are exported, macros as
  1638.                    yet undefined or macros whose value contains
  1639.                    any of the characters "+=:*" are not exported.
  1640.                    is suppre
  1641.  
  1642.      .IMPORT       Prerequisite names specified for this target
  1643.                    are searched for in the environment and
  1644.                    defined as macros with their value taken from
  1645.                    the environment.  If the special name .EVERY-
  1646.                    THING is used as a prerequisite name then all
  1647.                    environment variables defined in the environ-
  1648.                    ment are imported.  The functionality of the
  1649.                    -E flag can be forced by placing the construct
  1650.                    .IMPORT : .EVERYTHING at the start of a
  1651.                    makefile.  Similarly, by placing the construct
  1652.                    at the end, one can emulate the effect of the
  1653.                    -e command line flag.  If a prerequisite name
  1654.                    cannot be found in the environment an error
  1655.                    message is issued.  .IMPORT accepts the
  1656.                    .IGNORE attribute.  When given, it causes
  1657.                    dmake to ignore the above error.  See the MAC-
  1658.                    ROS section for a description of the process-
  1659.                    ing of imported macro values.
  1660.  
  1661.      .INCLUDE      Parse another makefile just as if it had been
  1662.                    located at the point of the .INCLUDE in the
  1663.                    current makefile.  The list of prerequisites
  1664.                    gives the list of makefiles to try to read.
  1665.                    If the list contains multiple makefiles then
  1666.                    they are read in order from left to right.
  1667.                    The following search rules are used when try-
  1668.                    ing to locate the file.  If the filename is
  1669.                    surrounded by " or just by itself then it is
  1670.                    searched for in the current directory.  If it
  1671.                    is not found it is then searched for in each
  1672.                    of the directories specified as prerequisites
  1673.                    of the .INCLUDEDIRS special target.  If the
  1674.                    file name is surrounded by < and >, (ie.
  1675.                    <my_spiffy_new_makefile>) then it is searched
  1676.                    for only in the directories given by the
  1677.                    .INCLUDEDIRS special target.  In both cases if
  1678.                    the file name is a fully qualified name start-
  1679.                    ing at the root of the file system then it is
  1680.                    only searched for once, and the .INCLUDEDIRS
  1681.                    list is ignored.  .INCLUDE accepts the .IGNORE
  1682.                    and .SETDIR attributes.  If .IGNORE attribute
  1683.                    is given and the file cannot be found then
  1684.                    dmake continues processing, otherwise an error
  1685.                    message is generated.  The .SETDIR attribute
  1686.  
  1687.  
  1688.  
  1689. Version 3.9 PL0                 UW                             26
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1696.  
  1697.  
  1698.  
  1699.                    causes dmake to change directories to the
  1700.                    specified directory prior to attempting the
  1701.                    include operation.  If all fails dmake
  1702.                    attempts to make the file to be included.  If
  1703.                    making the file fails then dmake terminates
  1704.                    unless the .INCLUDE directive also specified
  1705.                    the .IGNORE attribute.  If .FIRST is specified
  1706.                    along with .INCLUDE then dmake attempts to
  1707.                    include each named prerequisite and will ter-
  1708.                    minate the inclusion with the first prere-
  1709.                    quisite that results in a successful inclu-
  1710.                    sion.
  1711.  
  1712.      .INCLUDEDIRS  The list of prerequisites specified for this
  1713.                    target defines the set of directories to
  1714.                    search when trying to include a makefile.
  1715.  
  1716.      .KEEP_STATE   This special target is a synonym for the macro
  1717.                    definition
  1718.  
  1719.                         .KEEP_STATE := _state.mk
  1720.  
  1721.                    It's effect is to turn on STATE keeping and to
  1722.                    define _state.mk as the state file.
  1723.  
  1724.      .MAKEFILES    The list of prerequisites is the set of files
  1725.                    to try to read as the default makefile.  By
  1726.                    default this target is defined as:
  1727.  
  1728.                         .MAKEFILES : makefile.mk Makefile
  1729.                    makefile
  1730.  
  1731.  
  1732.      .SOURCE       The prerequisite list of this target defines a
  1733.                    set of directories to check when trying to
  1734.                    locate a target file name.  See the section on
  1735.                    BINDING of targets for more information.
  1736.  
  1737.      .SOURCE.suff  The same as .SOURCE, except that the
  1738.                    .SOURCE.suff list is searched first when try-
  1739.                    ing to locate a file matching the a target
  1740.                    whose name ends in the suffix .suff.
  1741.  
  1742.      .REMOVE       The recipe of this target is used whenever
  1743.                    dmake needs to remove intermediate targets
  1744.                    that were made but do not need to be kept
  1745.                    around.  Such targets result from the applica-
  1746.                    tion of transitive closure on the dependency
  1747.                    graph.
  1748.  
  1749.      In addition to the special targets above, several other
  1750.      forms of targets are recognized and are considered special,
  1751.  
  1752.  
  1753.  
  1754. Version 3.9 PL0                 UW                             27
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1761.  
  1762.  
  1763.  
  1764.      their exact form and use is defined in the sections that
  1765.      follow.
  1766.  
  1767. SPECIAL MACROS
  1768.      dmake defines a number of special macros.  They are divided
  1769.      into three classes: control macros, run-time macros, and
  1770.      function macros.  The control macros are used by dmake to
  1771.      configure its actions, and are the preferred method of doing
  1772.      so.  In the case when a control macro has the same function
  1773.      as a special target or attribute they share the same name as
  1774.      the special target or attribute.  The run-time macros are
  1775.      defined when dmake makes targets and may be used by the user
  1776.      inside recipes.  The function macros provide higher level
  1777.      functions dealing with macro expansion and diversion file
  1778.      processing.
  1779.  
  1780. CONTROL MACROS
  1781.      To use the control macros simply assign them a value just
  1782.      like any other macro.  The control macros are divided into
  1783.      three groups: string valued macros, character valued macros,
  1784.      and boolean valued macros.
  1785.  
  1786.      The following are all of the string valued macros.  This
  1787.      list is divided into two groups.  The first group gives the
  1788.      string valued macros that are defined internally and cannot
  1789.      be directly set by the user.
  1790.  
  1791.      INCDEPTH        This macro's value is a string of digits
  1792.                      representing the current depth of makefile
  1793.                      inclusion.  In the first makefile level this
  1794.                      value is zero.
  1795.  
  1796.      MFLAGS          Is the list of flags that were given on the
  1797.                      command line including a leading switch
  1798.                      character.  The -f flag is not included in
  1799.                      this list.
  1800.  
  1801.      MAKECMD         Is the name with which dmake was invoked.
  1802.  
  1803.      MAKEDIR         Is the full path to the initial directory in
  1804.                      which dmake was invoked.
  1805.  
  1806.      MAKEFILE        Contains the string "-f makefile" where,
  1807.                      makefile is the name of initial user
  1808.                      makefile that was first read.
  1809.  
  1810.      MAKEFLAGS       Is the same as $(MFLAGS) but has no leading
  1811.                      switch character. (ie. MFLAGS =
  1812.                      -$(MAKEFLAGS))
  1813.  
  1814.      MAKEMACROS      Contains the complete list of macro expres-
  1815.                      sions that were specified on the command
  1816.  
  1817.  
  1818.  
  1819. Version 3.9 PL0                 UW                             28
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1826.  
  1827.  
  1828.  
  1829.                      line.
  1830.  
  1831.      MAKETARGETS     Contains the name(s) of the target(s), if
  1832.                      any, that were specified on the command
  1833.                      line.
  1834.  
  1835.      MAXPROCESSLIMIT Is a numeric string representing the maximum
  1836.                      number of processes that dmake can use when
  1837.                      making targets using parallel mode.
  1838.  
  1839.      NULL            Is permanently defined to be the NULL
  1840.                      string.  This is useful when comparing a
  1841.                      conditional expression to an NULL value.
  1842.  
  1843.      PWD             Is the full path to the current directory in
  1844.                      which make is executing.
  1845.  
  1846.      TMPFILE         Is set to the name of the most recent tem-
  1847.                      porary file opened by dmake.  Temporary
  1848.                      files are used for text diversions and for
  1849.                      group recipe processing.
  1850.  
  1851.      TMD             Stands for "To Make Dir", and is the path
  1852.                      from the present directory (value of $(PWD))
  1853.                      to the directory that dmake was started up
  1854.                      in (value of $(MAKEDIR)).  This macro is
  1855.                      modified when .SETDIR attributes are pro-
  1856.                      cessed.
  1857.  
  1858.      USESHELL        The value of this macro is set to "yes" if
  1859.                      the current recipe is forced to use a shell
  1860.                      for its execution via the .USESHELL or '+'
  1861.                      directives, its value is "no" otherwise.
  1862.  
  1863.  
  1864.      The second group of string valued macros control dmake
  1865.      behavior and may be set by the user.
  1866.  
  1867.      .DIRCACHE       If set to "yes" enables the directory cache
  1868.                      (this is the default).  If set to "no" dis-
  1869.                      ables the directory cache (equivalent to -d
  1870.                      commandline flag).
  1871.  
  1872.      .NAMEMAX        Defines the maximum length of a filename
  1873.                      component.  The value of the variable is
  1874.                      initialized at startup to the value of the
  1875.                      compiled macro NAME_MAX.  On some systems
  1876.                      the value of NAME_MAX is too short by
  1877.                      default.  Setting a new value for .NAMEMAX
  1878.                      will override the compiled value.
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884. Version 3.9 PL0                 UW                             29
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1891.  
  1892.  
  1893.  
  1894.      .NOTABS         When set to non-NULL enables the use of
  1895.                      spaces as well as <tabs> to begin recipe
  1896.                      lines.  By default a non-group recipe is
  1897.                      terminated by a line without any leading
  1898.                      white-space or by a line not beggining with
  1899.                      a <tab> character.  Enabling this mode modi-
  1900.                      fies the first condition of the above termi-
  1901.                      nation rule to terminate a non-group recipe
  1902.                      with a line that contains only white-space.
  1903.                      This mode does not effect the parsing of
  1904.                      group recipes bracketed by [].
  1905.  
  1906.      AUGMAKE         If set to a non NULL value will enable the
  1907.                      transformation of special meta targets to
  1908.                      support special AUGMAKE inferences (See the
  1909.                      COMPATIBILITY section).
  1910.  
  1911.      DIRBRKSTR       Contains the string of chars used to ter-
  1912.                      minate the name of a directory in a path-
  1913.                      name.  Under UNIX its value is "/", under
  1914.                      MSDOS its value is "/\:".
  1915.  
  1916.      DIRSEPSTR       Contains the string that is used to separate
  1917.                      directory components when path names are
  1918.                      constructed.  It is defined with a default
  1919.                      value at startup.
  1920.  
  1921.      DIVFILE         Is defined in the startup file and gives the
  1922.                      name that should be returned for the diver-
  1923.                      sion file name when used in $(mktmp ...)
  1924.                      expansions, see the TEXT DIVERSION section
  1925.                      for details.
  1926.  
  1927.      DYNAMICNESTINGLEVEL
  1928.                      Specifies the maximum number of recursive
  1929.                      dynamic macro expansions.  Its initial value
  1930.                      is 100.
  1931.  
  1932.      .KEEP_STATE     Assigning this macro a value tells dmake the
  1933.                      name of the state file to use and turns on
  1934.                      the keeping of state information for any
  1935.                      targets that are brought up to date by the
  1936.                      make.
  1937.  
  1938.      GROUPFLAGS      This macro gives the set of flags to pass to
  1939.                      the shell when invoking it to execute a
  1940.                      group recipe.  The value of the macro is the
  1941.                      list of flags with a leading switch indica-
  1942.                      tor.  (ie. `-' under UNIX)
  1943.  
  1944.      GROUPSHELL      This macro defines the full path to the exe-
  1945.                      cutable image to be used as the shell when
  1946.  
  1947.  
  1948.  
  1949. Version 3.9 PL0                 UW                             30
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1956.  
  1957.  
  1958.  
  1959.                      processing group recipes.  This macro must
  1960.                      be defined if group recipes are used.  It is
  1961.                      assigned a default value in the startup
  1962.                      makefile.  Under UNIX this value is /bin/sh.
  1963.  
  1964.      GROUPSUFFIX     If defined, this macro gives the string to
  1965.                      use as a suffix when creating group recipe
  1966.                      files to be handed to the command inter-
  1967.                      preter.  For example, if it is defined as
  1968.                      .sh, then all temporary files created by
  1969.                      dmake will end in the suffix .sh.  Under
  1970.                      MSDOS if you are using command.com as your
  1971.                      GROUPSHELL, then this suffix must be set to
  1972.                      .bat in order for group recipes to function
  1973.                      correctly.  The setting of GROUPSUFFIX and
  1974.                      GROUPSHELL is done automatically for
  1975.                      command.com in the startup.mk files.
  1976.  
  1977.      MAKE            Is defined in the startup file by default.
  1978.                      The string $(MAKE) is recognized when using
  1979.                      the -n option for single line recipes.  Ini-
  1980.                      tially this macro is defined to have the
  1981.                      value "$(MAKECMD) $(MFLAGS)".
  1982.  
  1983.      MAKESTARTUP     This macro defines the full path to the ini-
  1984.                      tial startup makefile.  Use the -V command
  1985.                      line option to discover its initial value.
  1986.  
  1987.      MAXLINELENGTH   This macro defines the maximum size of a
  1988.                      single line of makefile input text.  The
  1989.                      size is specified as a number, the default
  1990.                      value is defined internally and is shown via
  1991.                      the -V option.  A buffer of this size plus 2
  1992.                      is allocated for reading makefile text.  The
  1993.                      buffer is freed before any targets are made,
  1994.                      thereby allowing files containing long input
  1995.                      lines to be processed without consuming
  1996.                      memory during the actual make.  This macro
  1997.                      can only be used to extend the line length
  1998.                      beyond it's default minimum value.
  1999.  
  2000.      MAXPROCESS      Specify the maximum number of child
  2001.                      processes to use when making targets.  The
  2002.                      default value of this macro is "1" and its
  2003.                      value cannot exceed the value of the macro
  2004.                      MAXPROCESSLIMIT.  Setting the value of MAX-
  2005.                      PROCESS on the command line or in the
  2006.                      makefile is equivalent to supplying a
  2007.                      corresponding value to the -P flag on the
  2008.                      command line.
  2009.  
  2010.  
  2011.  
  2012.  
  2013.  
  2014. Version 3.9 PL0                 UW                             31
  2015.  
  2016.  
  2017.  
  2018.  
  2019.  
  2020. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2021.  
  2022.  
  2023.  
  2024.      PREP            This macro defines the number of iterations
  2025.                      to be expanded automatically when processing
  2026.                      % rule definitions of the form:
  2027.  
  2028.                      % : %.suff
  2029.  
  2030.                      See the sections on PERCENT(%) RULES for
  2031.                      details on how PREP is used.
  2032.  
  2033.      SHELL           This macro defines the full path to the exe-
  2034.                      cutable image to be used as the shell when
  2035.                      processing single line recipes.  This macro
  2036.                      must be defined if recipes requiring the
  2037.                      shell for execution are to be used.  It is
  2038.                      assigned a default value in the startup
  2039.                      makefile.  Under UNIX this value is /bin/sh.
  2040.  
  2041.      SHELLFLAGS      This macro gives the set of flags to pass to
  2042.                      the shell when invoking it to execute a sin-
  2043.                      gle line recipe.  The value of the macro is
  2044.                      the list of flags with a leading switch
  2045.                      indicator.  (ie. `-' under UNIX)
  2046.  
  2047.      SHELLMETAS      Each time dmake executes a single recipe
  2048.                      line (not a group recipe) the line is
  2049.                      searched for any occurrence of a character
  2050.                      defined in the value of SHELLMETAS.  If such
  2051.                      a character is found the recipe line is
  2052.                      defined to require a shell to ensure its
  2053.                      correct execution.  In such instances a
  2054.                      shell is used to invoke the recipe line.  If
  2055.                      no match is found the recipe line is exe-
  2056.                      cuted without the use of a shell.
  2057.  
  2058.  
  2059.      There is only one character valued macro defined by dmake:
  2060.      SWITCHAR contains the switch character used to introduce
  2061.      options on command lines.  For UNIX its value is `-', and
  2062.      for MSDOS its value may be `/' or `-'.  The macro is inter-
  2063.      nally defined and is not user setable.  The MSDOS version of
  2064.      dmake attempts to first extract SWITCHAR from an environment
  2065.      variable of the same name.  If that fails it then attempts
  2066.      to use the undocumented getswitchar system call, and returns
  2067.      the result of that.  Under MSDOS version 4.0 you must set
  2068.      the value of the environment macro SWITCHAR to '/' to obtain
  2069.      predictable behavior.
  2070.  
  2071.      All boolean macros currently understood by dmake correspond
  2072.      directly to the previously defined attributes.  These macros
  2073.      provide a second way to apply global attributes, and
  2074.      represent the preferred method of doing so.  They are used
  2075.      by assigning them a value.  If the value is not a NULL
  2076.  
  2077.  
  2078.  
  2079. Version 3.9 PL0                 UW                             32
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2086.  
  2087.  
  2088.  
  2089.      string then the boolean condition is set to on.  If the
  2090.      value is a NULL string then the condition is set to off.
  2091.      There are five conditions defined and they correspond
  2092.      directly to the attributes of the same name.  Their meanings
  2093.      are defined in the ATTRIBUTES section above.  The macros
  2094.      are: .EPILOG, .IGNORE, .MKSARGS, .NOINFER, .PRECIOUS, .PRO-
  2095.      LOG, .SEQUENTIAL, .SILENT, .SWAP, and .USESHELL.  Assigning
  2096.      any of these a non NULL value will globally set the
  2097.      corresponding attribute to on.
  2098.  
  2099. RUN_TIME MACROS
  2100.      These macros are defined when dmake is making targets, and
  2101.      may take on different values for each target.  $@ is defined
  2102.      to be the full target name, $? is the list of all out of
  2103.      date prerequisites, $& is the list of all prerequisites, $>
  2104.      is the name of the library if the current target is a
  2105.      library member, and $< is the list of prerequisites speci-
  2106.      fied in the current rule.  If the current target had a
  2107.      recipe inferred then $< is the name of the inferred prere-
  2108.      quisite even if the target had a list of prerequisites sup-
  2109.      plied using an explicit rule that did not provide a recipe.
  2110.      In such situations $& gives the full list of prerequisites.
  2111.  
  2112.      $* is defined as $(@:db) when making targets with explicit
  2113.      recipes and is defined as the value of % when making targets
  2114.      whose recipe is the result of an inference.  In the first
  2115.      case $* is the target name with no suffix, and in the second
  2116.      case, is the value of the matched % pattern from the associ-
  2117.      ated %-rule.  $^ expands to the set of out of date prere-
  2118.      quisites taken from the current value of $<.  In addition to
  2119.      these, $$ expands to $, {{ expands to {, }} expands to },
  2120.      and the strings <+ and +> are recognized as respectively
  2121.      starting and terminating a text diversion when they appear
  2122.      literally together in the same input line.
  2123.  
  2124.      The difference between $? and $^ can best be illustrated by
  2125.      an example, consider:
  2126.  
  2127.           fred.out : joe amy hello
  2128.                rules for making fred
  2129.  
  2130.           fred.out : my.c your.h his.h her.h   # more prerequisites
  2131.  
  2132.      Assume joe, amy, and my.c are newer then fred.out.  When
  2133.      dmake executes the recipe for making fred.out the values of
  2134.      the following macros will be:
  2135.  
  2136.           $@ --> fred.out
  2137.           $* --> fred
  2138.           $? --> joe amy my.c  # note the difference between $? and $^
  2139.           $^ --> joe amy
  2140.           $< --> joe amy hello
  2141.  
  2142.  
  2143.  
  2144. Version 3.9 PL0                 UW                             33
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2151.  
  2152.  
  2153.  
  2154.           $& --> joe amy hello my.c your.h his.h her.h
  2155.  
  2156.  
  2157. FUNCTION MACROS
  2158.      dmake supports a full set of functional macros.  One of
  2159.      these, the $(mktmp ...) macro, is discussed in detail in the
  2160.      TEXT DIVERSION section and is not covered here.
  2161.  
  2162.  
  2163.           $(assign expression)
  2164.                Causes expression to be parsed as a macro assign-
  2165.                ment expression and results in the specified
  2166.                assignment being made.  An error is issued if the
  2167.                assignment is not syntatically correct.  expres-
  2168.                sion may contain white space.  This is in effect a
  2169.                dynamic macro assignment facility and may appear
  2170.                anywhere any other macro may appear.  The result
  2171.                of the expanding a dynamic macro assignment
  2172.                expression is the name of the macro that was
  2173.                assigned and $(NULL) if the expression is not a
  2174.                valid macro assignment expression.  Some examples
  2175.                are:
  2176.  
  2177.                $(assign foo := fred)
  2178.                $(assign $(indirect_macro_name) +:= $(morejunk))
  2179.  
  2180.           $(null,text true false)
  2181.                expands the value of text. If it is NULL then the
  2182.                macro returns the value of the expansion of true
  2183.                and the expansion of false otherwise.  The terms
  2184.                true, and false must be strings containing no
  2185.                white-space.
  2186.  
  2187.           $(!null,text true false)
  2188.                Behaves identically to the previous macro except
  2189.                that the true string is chosen if the expansion of
  2190.                text is not NULL.
  2191.  
  2192.           $(eq,text_a,text_b true false)
  2193.                expands text_a and text_b and compares their
  2194.                results.  If equal it returns the result of the
  2195.                expansion of the true term, otherwise it returns
  2196.                the expansion of the false term.
  2197.  
  2198.           $(!eq,text_a,text_b true false)
  2199.                Behaves identically to the previous macro except
  2200.                that the true string is chosen if the expansions
  2201.                of the two strings are not equal
  2202.  
  2203.           $(nil expression)
  2204.                Always returns the value of $(NULL) regardless of
  2205.                what expression is.  This function macro can be
  2206.  
  2207.  
  2208.  
  2209. Version 3.9 PL0                 UW                             34
  2210.  
  2211.  
  2212.  
  2213.  
  2214.  
  2215. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2216.  
  2217.  
  2218.  
  2219.                used to discard results of expanding macro expres-
  2220.                sions.
  2221.  
  2222.           $(shell command)
  2223.                Runs command as if it were part of a recipe and
  2224.                returns, separated by a single space, all the
  2225.                non-white space terms written to stdout by the
  2226.                command.  For example:
  2227.  
  2228.                     $(shell ls *.c)
  2229.  
  2230.                will return "a.c b.c c.c d.c" if the files exist
  2231.                in the current directory.  The recipe modification
  2232.                flags [+@%-] are honored if they appear as the
  2233.                first characters in the command.  For example:
  2234.  
  2235.                     $(shell +ls *.c)
  2236.  
  2237.                will run the command using the current shell.
  2238.  
  2239.           $(shell,expand command)
  2240.                Is an extension to the $(shell... function macro
  2241.                that expands the result of running command.
  2242.  
  2243.           $(sort list)
  2244.                Will take all white-space separated tokens in list
  2245.                and will return their sorted equivalent list.
  2246.  
  2247.           $(strip data)
  2248.                Will replace all strings of white-space in data by
  2249.                a single space.
  2250.  
  2251.           $(subst,pat,replacement data)
  2252.                Will search for pat in data and will replace any
  2253.                occurrence of pat with the replacement string.
  2254.                The expansion
  2255.  
  2256.                $(subst,.o,.c $(OBJECTS))
  2257.  
  2258.           is equivalent to:
  2259.  
  2260.                $(OBJECTS:s/.o/.c/)
  2261.  
  2262.  
  2263. CONDITIONAL MACROS
  2264.      dmake supports conditional macros.  These allow the defini-
  2265.      tion of target specific macro values.  You can now say the
  2266.      following:
  2267.  
  2268.           target ?= MacroName MacroOp Value
  2269.  
  2270.      This creates a definition for MacroName whose value is Value
  2271.  
  2272.  
  2273.  
  2274. Version 3.9 PL0                 UW                             35
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2281.  
  2282.  
  2283.  
  2284.      only when target is being made.  You may use a conditional
  2285.      macro assignment anywhere that a regular macro assignment
  2286.      may appear, including as the value of a $(assign ...) macro.
  2287.  
  2288.      The new definition is associated with the most recent cell
  2289.      definition for target.  If no prior definition exists then
  2290.      one is created.  The implications of this are immediately
  2291.      evident in the following example:
  2292.  
  2293.           foo := hello
  2294.  
  2295.           all : cond;@echo "all done, foo=[$(foo)] bar=[$(bar)]"
  2296.  
  2297.           cond ?= bar := global decl
  2298.  
  2299.           cond .SETDIR=unix::;@echo $(foo) $(bar)
  2300.           cond ?= foo := hi
  2301.  
  2302.           cond .SETDIR=msdos::;@echo $(foo) $(bar)
  2303.                cond ?= foo := hihi
  2304.  
  2305.      The first conditional assignment creates a binding for 'bar'
  2306.      that is activated when 'cond' is made.  The bindings follow-
  2307.      ing the :: definitions are activated when their respective
  2308.      recipe rules are used.  Thus the first binding serves to
  2309.      provide a global value for 'bar' while any of the cond ::
  2310.      rules are processed, and the local bindings for 'foo' come
  2311.      into effect when their associated :: rule is processed.
  2312.  
  2313.      Conditionals for targets of .UPDATEALL are all activated
  2314.      before the target group is made.  Assignments are processed
  2315.      in order.  Note that the value of a conditional macro
  2316.      assignment is NOT AVAILABLE until the associated target is
  2317.      made, thus the construct
  2318.  
  2319.           mytarget ?= bar := hello
  2320.           mytarget ?= foo := $(bar)
  2321.  
  2322.      results in $(foo) expanding to "", if you want the result to
  2323.      be "hello" you must use:
  2324.  
  2325.           mytarget ?= bar := hello
  2326.           mytarget ?= foo  = $(bar)
  2327.  
  2328.      Once a target is made any associated conditional macros are
  2329.      deactivated and their values are no longer available.
  2330.      Activation occurrs after all inference, and .SETDIR direc-
  2331.      tives have been processed and after $@ is assigned, but
  2332.      before prerequisites are processed; thereby making the
  2333.      values of conditional macro definitions available during
  2334.      construction of prerequisites.
  2335.  
  2336.  
  2337.  
  2338.  
  2339. Version 3.9 PL0                 UW                             36
  2340.  
  2341.  
  2342.  
  2343.  
  2344.  
  2345. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2346.  
  2347.  
  2348.  
  2349.      If a %-meta rule target has associated conditional macro
  2350.      assignments, and the rule is chosen by the inference algo-
  2351.      rithm then the conditional macro assignments are inferred
  2352.      together with the associated recipe.
  2353.  
  2354. DYNAMIC PREREQUISITES
  2355.      dmake looks for prerequisites whose names contain macro
  2356.      expansions during target processing.  Any such prerequisites
  2357.      are expanded and the result of the expansion is used as the
  2358.      prerequisite name.  As an example the line:
  2359.  
  2360.           fred : $$@.c
  2361.  
  2362.      causes the $$@ to be expanded when dmake is making fred, and
  2363.      it resolves to the target fred.  This enables dynamic prere-
  2364.      quisites to be generated.  The value of @ may be modified by
  2365.      any of the valid macro modifiers.  So you can say for exam-
  2366.      ple:
  2367.  
  2368.           fred.out : $$(@:b).c
  2369.  
  2370.      where the $$(@:b) expands to fred.  Note the use of $$
  2371.      instead of $ to indicate the dynamic expansion, this is due
  2372.      to the fact that the rule line is expanded when it is ini-
  2373.      tially parsed, and $$ then returns $ which later triggers
  2374.      the dynamic prerequisite expansion.  If you really want a $
  2375.      to be part of a prerequisite name you must use $$$$.
  2376.      Dynamic macro expansion is performed in all user defined
  2377.      rules, and the special targets .SOURCE*, and .INCLUDEDIRS.
  2378.  
  2379.      If dynamic macro expansion results in multiple white space
  2380.      separated tokens then these are inserted into the prere-
  2381.      quisite list inplace of the dynamic prerequisite.  If the
  2382.      new list contains additional dynamic prerequisites they will
  2383.      be expanded when they are processed.  The level of recursion
  2384.      in this expansion is controlled by the value of the variable
  2385.      DYNAMICNESTINGLEVEL and is set to 100 by default.
  2386.  
  2387. BINDING TARGETS
  2388.      This operation takes a target name and binds it to an exist-
  2389.      ing file, if possible.  dmake makes a distinction between
  2390.      the internal target name of a target and its associated
  2391.      external file name.  Thus it is possible for a target's
  2392.      internal name and its external file name to differ.  To per-
  2393.      form the binding, the following set of rules is used.
  2394.      Assume that we are trying to bind a target whose name is of
  2395.      the form X.suff, where .suff is the suffix and X is the stem
  2396.      portion (ie. that part which contains the directory and the
  2397.      basename).  dmake takes this target name and performs a
  2398.      series of search operations that try to find a suitably
  2399.      named file in the external file system.  The search opera-
  2400.      tion is user controlled via the settings of the various
  2401.  
  2402.  
  2403.  
  2404. Version 3.9 PL0                 UW                             37
  2405.  
  2406.  
  2407.  
  2408.  
  2409.  
  2410. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2411.  
  2412.  
  2413.  
  2414.      .SOURCE targets.
  2415.  
  2416.           1.   If target has the .SYMBOL attribute set then look
  2417.                for it in the library.  If found, replace the tar-
  2418.                get name with the library member name and continue
  2419.                with step 2.  If the name is not found then
  2420.                return.
  2421.  
  2422.           2.   Extract the suffix portion (that following the
  2423.                `.') of the target name.  If the suffix is not
  2424.                null, look up the special target .SOURCE.<suff>
  2425.                (<suff> is the suffix). If the special target
  2426.                exists then search each directory given in the
  2427.                .SOURCE.<suff> prerequisite list for the target.
  2428.                If the target's suffix was null (ie. .suff was
  2429.                empty) then perform the above search but use the
  2430.                special target .SOURCE.NULL instead.  If at any
  2431.                point a match is found then terminate the search.
  2432.                If a directory in the prerequisite list is the
  2433.                special name `.NULL ' perform a search for the
  2434.                full target name without prepending any directory
  2435.                portion (ie. prepend the NULL directory).
  2436.  
  2437.           3.   The search in step 2. failed.  Repeat the same
  2438.                search but this time use the special target
  2439.                .SOURCE.  (a default target of '.SOURCE : .NULL'
  2440.                is defined by dmake at startup, and is user rede-
  2441.                finable)
  2442.  
  2443.           4.   The search in step 3. failed.  If the target has
  2444.                the library member attribute (.LIBMEMBER) set then
  2445.                try to find the target in the library which was
  2446.                passed along with the .LIBMEMBER attribute (see
  2447.                the MAKING LIBRARIES section).  The bound file
  2448.                name assigned to a target which is successfully
  2449.                located in a library is the same name that would
  2450.                be assigned had the search failed (see 5.).
  2451.  
  2452.           5.   The search failed.  Either the target was not
  2453.                found in any of the search directories or no
  2454.                applicable .SOURCE special targets exist.  If
  2455.                applicable .SOURCE special targets exist, but the
  2456.                target was not found, then dmake assigns the first
  2457.                name searched as the bound file name.  If no
  2458.                applicable .SOURCE special targets exist, then the
  2459.                full original target name becomes the bound file
  2460.                name.
  2461.  
  2462.      There is potential here for a lot of search operations.  The
  2463.      trick is to define .SOURCE.x special targets with short
  2464.      search lists and leave .SOURCE as short as possible.  The
  2465.      search algorithm has the following useful side effect.  When
  2466.  
  2467.  
  2468.  
  2469. Version 3.9 PL0                 UW                             38
  2470.  
  2471.  
  2472.  
  2473.  
  2474.  
  2475. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2476.  
  2477.  
  2478.  
  2479.      a target having the .LIBMEMBER (library member) attribute is
  2480.      searched for, it is first searched for as an ordinary file.
  2481.      When a number of library members require updating it is
  2482.      desirable to compile all of them first and to update the
  2483.      library at the end in a single operation.  If one of the
  2484.      members does not compile and dmake stops, then the user may
  2485.      fix the error and make again.  dmake will not remake any of
  2486.      the targets whose object files have already been generated
  2487.      as long as none of their prerequisite files have been modi-
  2488.      fied as a result of the fix.
  2489.  
  2490.      When dmake constructs target pathnames './' substrings are
  2491.      removed and substrings of the form 'foo/..' are eliminated.
  2492.      This may result in somewhat unexpected values of the macro
  2493.      expansion $@, but is infact the corect result.
  2494.  
  2495.      When defining .SOURCE and .SOURCE.x targets the construct
  2496.  
  2497.           .SOURCE :
  2498.           .SOURCE : fred gery
  2499.  
  2500.      is equivalent to
  2501.  
  2502.           .SOURCE :- fred gery
  2503.  
  2504.      dmake correctly handles the UNIX Make variable VPATH.  By
  2505.      definition VPATH contains a list of ':' separated direc-
  2506.      tories to search when looking for a target.  dmake maps
  2507.      VPATH to the following special rule:
  2508.  
  2509.           .SOURCE :^ $(VPATH:s/:/ /)
  2510.  
  2511.      Which takes the value of VPATH and sets .SOURCE to the same
  2512.      set of directories as specified in VPATH.
  2513.  
  2514. PERCENT(%) RULES AND MAKING INFERENCES
  2515.      When dmake makes a target, the target's set of prerequisites
  2516.      (if any) must exist and the target must have a recipe which
  2517.      dmake can use to make it.  If the makefile does not specify
  2518.      an explicit recipe for the target then dmake uses special
  2519.      rules to try to infer a recipe which it can use to make the
  2520.      target.  Previous versions of Make perform this task by
  2521.      using rules that are defined by targets of the form
  2522.      .<suffix>.<suffix> and by using the .SUFFIXES list of suf-
  2523.      fixes.  The exact workings of this mechanism were sometimes
  2524.      difficult to understand and often limiting in their useful-
  2525.      ness.  Instead, dmake supports the concept of %-meta rules.
  2526.      The syntax and semantics of these rules differ from standard
  2527.      rule lines as follows:
  2528.  
  2529.           <%-target> [<attributes>] <ruleop> [<%-prerequisites>] [;<recipe>]
  2530.  
  2531.  
  2532.  
  2533.  
  2534. Version 3.9 PL0                 UW                             39
  2535.  
  2536.  
  2537.  
  2538.  
  2539.  
  2540. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2541.  
  2542.  
  2543.  
  2544.      where %-target is a target containing exactly a single `%'
  2545.      sign, attributes is a list (possibly empty) of attributes,
  2546.      ruleop is the standard set of rule operators, %-prere-
  2547.      quisites , if present, is a list of prerequisites containing
  2548.      zero or more `%' signs, and recipe, if present, is the first
  2549.      line of the recipe.
  2550.  
  2551.      The %-target defines a pattern against which a target whose
  2552.      recipe is being inferred gets matched.  The pattern match
  2553.      goes as follows:  all chars are matched exactly from left to
  2554.      right up to but not including the % sign in the pattern, %
  2555.      then matches the longest string from the actual target name
  2556.      not ending in the suffix given after the % sign in the pat-
  2557.      tern.  Consider the following examples:
  2558.  
  2559.           %.c       matches fred.c but not joe.c.Z
  2560.           dir/%.c   matches dir/fred.c but not dd/fred.c
  2561.           fred/%    matches fred/joe.c but not f/joe.c
  2562.           %         matches anything
  2563.  
  2564.      In each case the part of the target name that matched the %
  2565.      sign is retained and is substituted for any % signs in the
  2566.      prerequisite list of the %-meta rule when the rule is
  2567.      selected during inference and dmake constructs the new
  2568.      dependency.  As an example the following %-meta rules
  2569.      describe the following:
  2570.  
  2571.           %.c : %.y ; recipe...
  2572.  
  2573.      describes how to make any file ending in .c if a correspond-
  2574.      ing file ending in .y can be found.
  2575.  
  2576.           foo%.o : fee%.k ; recipe...
  2577.  
  2578.      is used to describe how to make fooxxxx.o from feexxxx.k.
  2579.  
  2580.           %.a :; recipe...
  2581.  
  2582.      describes how to make a file whose suffix is .a without
  2583.      inferring any prerequisites.
  2584.  
  2585.           %.c : %.y yaccsrc/%.y ; recipe...
  2586.  
  2587.      is a short form for the construct:
  2588.  
  2589.           %.c : %.y ; recipe...
  2590.           %.c : yaccsrc/%.y ; recipe...
  2591.  
  2592.      ie. It is possible to specify the same recipe for two
  2593.      %-rules by giving more than one prerequisite in the prere-
  2594.      quisite list.  A more interesting example is:
  2595.  
  2596.  
  2597.  
  2598.  
  2599. Version 3.9 PL0                 UW                             40
  2600.  
  2601.  
  2602.  
  2603.  
  2604.  
  2605. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2606.  
  2607.  
  2608.  
  2609.           % : RCS/%,v ; co $<
  2610.  
  2611.      which describes how to take any target and check it out of
  2612.      the RCS directory if the corresponding file exists in the
  2613.      RCS directory.  The equivalent SCCS rule would be:
  2614.  
  2615.           % : s.% ; get $<
  2616.  
  2617.  
  2618.      The previous RCS example defines an infinite rule, because
  2619.      it says how to make anything from RCS/%,v, and anything also
  2620.      includes RCS/fred.c,v.  To limit the size of the graph that
  2621.      results from such rules dmake uses the macro variable PREP
  2622.      (stands for % repetition).  By default the value of this
  2623.      variable is 0, which says that no repetitions of a %-rule
  2624.      are to be generated.  If it is set to something greater than
  2625.      0, then that many repetitions of any infinite %-rule are
  2626.      allowed.  If in the above example PREP was set to 1, then
  2627.      dmake would generate the dependency graph:
  2628.  
  2629.           % --> RCS/%,v --> RCS/RCS/%,v,v
  2630.  
  2631.      Where each link is assigned the same recipe as the first
  2632.      link.  PREP should be used only in special cases, since it
  2633.      may result in a large increase in the number of possible
  2634.      prerequisites tested.  dmake further assumes that any target
  2635.      that has no suffix can be made from a prerequisite that has
  2636.      at least one suffix.
  2637.  
  2638.      dmake supports dynamic prerequisite generation for prere-
  2639.      quisites of %-meta rules.  This is best illustrated by an
  2640.      example.  The RCS rule shown above can infer how to check
  2641.      out a file from a corresponding RCS file only if the target
  2642.      is a simple file name with no directory information.  That
  2643.      is, the above rule can infer how to find RCS/fred.c,v from
  2644.      the target fred.c, but cannot infer how to find
  2645.      srcdir/RCS/fred.c,v from srcdir/fred.c because the above
  2646.      rule will cause dmake to look for RCS/srcdir/fred.c,v; which
  2647.      does not exist (assume that srcdir has its own RCS directory
  2648.      as is the common case).
  2649.  
  2650.      A more versatile formulation of the above RCS check out rule
  2651.      is the following:
  2652.  
  2653.           % :  $$(@:d)RCS/$$(@:f),v : co $@
  2654.  
  2655.      This rule uses the dynamic macro $@ to specify the prere-
  2656.      quisite to try to infer.  During inference of this rule the
  2657.      macro $@ is set to the value of the target of the %-meta
  2658.      rule and the appropriate prerequisite is generated by
  2659.      extracting the directory portion of the target name (if
  2660.      any), appending the string RCS/ to it, and appending the
  2661.  
  2662.  
  2663.  
  2664. Version 3.9 PL0                 UW                             41
  2665.  
  2666.  
  2667.  
  2668.  
  2669.  
  2670. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2671.  
  2672.  
  2673.  
  2674.      target file name with a trailing ,v attached to the previous
  2675.      result.
  2676.  
  2677.      dmake can also infer indirect prerequisites.  An inferred
  2678.      target can have a list of prerequisites added that will not
  2679.      show up in the value of $< but will show up in the value of
  2680.      $? and $&.  Indirect prerequisites are specified in an
  2681.      inference rule by quoting the prerequisite with single
  2682.      quotes.  For example, if you had the explicit dependency:
  2683.  
  2684.           fred.o : fred.c ; rule to make fred.o
  2685.           fred.o : local.h
  2686.  
  2687.      then this can be inferred for fred.o from the following
  2688.      inference rule:
  2689.  
  2690.           %.o : %.c 'local.h' ; rule to make a .o from a .c
  2691.  
  2692.      You may infer indirect prerequisites that are a function of
  2693.      the value of '%' in the current rule.  The meta-rule:
  2694.  
  2695.           %.o : %.c '$(INC)/%.h' ; rule to make a .o from a .c
  2696.  
  2697.      infers an indirect prerequisite found in the INC directory
  2698.      whose name is the same as the expansion of $(INC), and the
  2699.      prerequisite name depends on the base name of the current
  2700.      target.  The set of indirect prerequisites is attached to
  2701.      the meta rule in which they are specified and are inferred
  2702.      only if the rule is used to infer a recipe for a target.
  2703.      They do not play an active role in driving the inference
  2704.      algorithm.  The construct:
  2705.  
  2706.           %.o : %.c %.f 'local.h'; recipe
  2707.  
  2708.      is equivalent to:
  2709.  
  2710.           %.o : %.c 'local.h' : recipe
  2711.  
  2712.      while:
  2713.  
  2714.           %.o :| %.c %.f 'local.h'; recipe
  2715.  
  2716.      is equivalent to:
  2717.  
  2718.           %.o : %.c 'local.h' : recipe
  2719.           %.o : %.f 'local.h' : recipe
  2720.  
  2721.  
  2722.      If any of the attributes .SETDIR, .EPILOG, .PROLOG, .SILENT,
  2723.      .USESHELL, .SWAP, .PRECIOUS, .LIBRARY, .NOSTATE and .IGNORE
  2724.      are given for a %-rule then when that rule is bound to a
  2725.      target as the result of an inference, the target's set of
  2726.  
  2727.  
  2728.  
  2729. Version 3.9 PL0                 UW                             42
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2736.  
  2737.  
  2738.  
  2739.      attributes is augmented by the attributes from the above set
  2740.      that are specified in the bound %-rule.  Other attributes
  2741.      specified for %-meta rules are not inherited by the target.
  2742.      The .SETDIR attribute is treated in a special way.  If the
  2743.      target already had a .SETDIR attribute set then dmake
  2744.      changes to that directory prior to performing the inference.
  2745.      During inference any .SETDIR attributes for the inferred
  2746.      prerequisite are honored.  The directories must exist for a
  2747.      %-meta rule to be selected as a possible inference path.  If
  2748.      the directories do not exist no error message is issued,
  2749.      instead the corresponding path in the inference graph is
  2750.      rejected.
  2751.  
  2752.      dmake also supports the old format special target
  2753.      .<suffix>.<suffix> by identifying any rules of this form and
  2754.      mapping them to the appropriate %-rule.  So for example if
  2755.      an old makefile contains the construct:
  2756.  
  2757.           .c.o :; cc -c $< -o $@
  2758.  
  2759.      dmake maps this into the following %-rule:
  2760.  
  2761.           %.o : %.c; cc -c $< -o $@
  2762.  
  2763.      Furthermore, dmake understands several SYSV AUGMAKE special
  2764.      targets and maps them into corresponding %-meta rules.
  2765.      These transformation must be enabled by providing the -A
  2766.      flag on the command line or by setting the value of AUGMAKE
  2767.      to non-NULL.  The construct
  2768.  
  2769.           .suff :; recipe
  2770.  
  2771.      gets mapped into:
  2772.  
  2773.           % : %.suff; recipe
  2774.  
  2775.      and the construct
  2776.  
  2777.           .c~.o :; recipe
  2778.  
  2779.      gets mapped into:
  2780.  
  2781.           %.o : s.%.c ; recipe
  2782.  
  2783.      In general, a special target of the form .<str>~ is replaced
  2784.      by the %-rule construct s.%.<str>, thereby providing support
  2785.      for the syntax used by SYSV AUGMAKE for providing SCCS sup-
  2786.      port.  When enabled, these mappings allow processing of
  2787.      existing SYSV makefiles without modifications.
  2788.  
  2789.      dmake bases all of its inferences on the inference graph
  2790.      constructed from the %-rules defined in the makefile.  It
  2791.  
  2792.  
  2793.  
  2794. Version 3.9 PL0                 UW                             43
  2795.  
  2796.  
  2797.  
  2798.  
  2799.  
  2800. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2801.  
  2802.  
  2803.  
  2804.      knows exactly which targets can be made from which prere-
  2805.      quisites by making queries on the inference graph.  For this
  2806.      reason .SUFFIXES is not needed and is completely ignored.
  2807.  
  2808.      For a %-meta rule to be inferred as the rule whose recipe
  2809.      will be used to make a target, the target's name must match
  2810.      the %-target pattern, and any inferred %-prerequisite must
  2811.      already exist or have an explicit recipe so that the prere-
  2812.      quisite can be made.  Without transitive closure on the
  2813.      inference graph the above rule describes precisely when an
  2814.      inference match terminates the search.  If transitive clo-
  2815.      sure is enabled (the usual case), and a prerequisite does
  2816.      not exist or cannot be made, then dmake invokes the infer-
  2817.      ence algorithm recursively on the prerequisite to see if
  2818.      there is some way the prerequisite can be manufactured.
  2819.      For, if the prerequisite can be made then the current target
  2820.      can also be made using the current %-meta rule.  This means
  2821.      that there is no longer a need to give a rule for making a
  2822.      .o from a .y if you have already given a rule for making a
  2823.      .o from a .c and a .c from a .y.  In such cases dmake can
  2824.      infer how to make the .o from the .y via the intermediary .c
  2825.      and will remove the .c when the .o is made.  Transitive clo-
  2826.      sure can be disabled by giving the -T switch on the command
  2827.      line.
  2828.  
  2829.      A word of caution.  dmake bases its transitive closure on
  2830.      the %-meta rule targets.  When it performs transitive clo-
  2831.      sure it infers how to make a target from a prerequisite by
  2832.      performing a pattern match as if the potential prerequisite
  2833.      were a new target.  The set of rules:
  2834.  
  2835.           %.o : %.c :; rule for making .o from .c
  2836.           %.c : %.y :; rule for making .c from .y
  2837.           % : RCS/%,v :; check out of RCS file
  2838.  
  2839.      will, by performing transitive closure, allow dmake to infer
  2840.      how to make a .o from a .y using a .c as an intermediate
  2841.      temporary file.  Additionally it will be able to infer how
  2842.      to make a .y from an RCS file, as long as that RCS file is
  2843.      in the RCS directory and has a name which ends in .y,v.  The
  2844.      transitivity computation is performed dynamically for each
  2845.      target that does not have a recipe.  This has potential to
  2846.      be costly if the %-meta rules are not carefully specified.
  2847.      The .NOINFER attribute is used to mark a %-meta node as
  2848.      being a final target during inference.  Any node with this
  2849.      attribute set will not be used for subsequent inferences.
  2850.      As an example the node RCS/%,v is marked as a final node
  2851.      since we know that if the RCS file does not exist there
  2852.      likely is no other way to make it.  Thus the standard
  2853.      startup makefile contains an entry similar to:
  2854.           .NOINFER : RCS/%,v
  2855.      Thereby indicating that the RCS file is the end of the
  2856.  
  2857.  
  2858.  
  2859. Version 3.9 PL0                 UW                             44
  2860.  
  2861.  
  2862.  
  2863.  
  2864.  
  2865. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2866.  
  2867.  
  2868.  
  2869.      inference chain.  Whenever the inference algorithm deter-
  2870.      mines that a target can be made from more than one prere-
  2871.      quisite and the inference chains for the two methods are the
  2872.      same length the algorithm reports an ambiguity and prints
  2873.      the ambiguous inference chains.
  2874.  
  2875.      dmake tries to remove intermediate files resulting from
  2876.      transitive closure if the file is not marked as being PRE-
  2877.      CIOUS, or the -u flag was not given on the command line, and
  2878.      if the inferred intermediate did not previously exist.
  2879.      Intermediate targets that existed prior to being made are
  2880.      never removed.  This is in keeping with the philosophy that
  2881.      dmake should never remove things from the file system that
  2882.      it did not add.  If the special target .REMOVE is defined
  2883.      and has a recipe then dmake constructs a list of the inter-
  2884.      mediate files to be removed and makes them prerequisites of
  2885.      .REMOVE.  It then makes .REMOVE thereby removing the prere-
  2886.      quisites if the recipe of .REMOVE says to.  Typically
  2887.      .REMOVE is defined in the startup file as:
  2888.  
  2889.           .REMOVE :; $(RM) $<
  2890.  
  2891. MAKING TARGETS
  2892.      In order to update a target dmake must execute a recipe.
  2893.      When a recipe needs to be executed it is first expanded so
  2894.      that any macros in the recipe text are expanded, and it is
  2895.      then either executed directly or passed to a shell.  dmake
  2896.      supports two types of recipes.  The regular recipes and
  2897.      group recipes.
  2898.  
  2899.      When a regular recipe is invoked dmake executes each line of
  2900.      the recipe separately using a new copy of a shell if a shell
  2901.      is required.  Thus effects of commands do not generally per-
  2902.      sist across recipe lines (e.g. cd requests in a recipe line
  2903.      do not carry over to the next recipe line).  This is true
  2904.      even in environments such as MSDOS, where dmake internally
  2905.      sets the current working director to match the directory it
  2906.      was in before the command was executed.
  2907.  
  2908.      The decision on whether a shell is required to execute a
  2909.      command is based on the value of the macro SHELLMETAS or on
  2910.      the specification of '+' or .USESHELL for the current recipe
  2911.      or target respectively.  If any character in the value of
  2912.      SHELLMETAS is found in the expanded recipe text-line or the
  2913.      use of a shell is requested explicitly via '+' or .USESHELL
  2914.      then the command is executed using a shell, otherwise the
  2915.      command is executed directly.  The shell that is used for
  2916.      execution is given by the value of the macro SHELL.  The
  2917.      flags that are passed to the shell are given by the value of
  2918.      SHELLFLAGS.  Thus dmake constructs the command line:
  2919.  
  2920.           $(SHELL) $(SHELLFLAGS) $(expanded_recipe_command)
  2921.  
  2922.  
  2923.  
  2924. Version 3.9 PL0                 UW                             45
  2925.  
  2926.  
  2927.  
  2928.  
  2929.  
  2930. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2931.  
  2932.  
  2933.  
  2934.      Normally dmake writes the command line that it is about to
  2935.      invoke to standard output.  If the .SILENT attribute is set
  2936.      for the target or for the recipe line (via @), then the
  2937.      recipe line is not echoed.
  2938.  
  2939.      Group recipe processing is similar to that of regular
  2940.      recipes, except that a shell is always invoked.  The shell
  2941.      that is invoked is given by the value of the macro GROUP-
  2942.      SHELL, and its flags are taken from the value of the macro
  2943.      GROUPFLAGS.  If a target has the .PROLOG attribute set then
  2944.      dmake prepends to the shell script the recipe associated
  2945.      with the special target .GROUPPROLOG, and if the attribute
  2946.      .EPILOG is set as well, then the recipe associated with the
  2947.      special target .GROUPEPILOG is appended to the script file.
  2948.      This facility can be used to always prepend a common header
  2949.      and common trailer to group recipes.  Group recipes are
  2950.      echoed to standard output just like standard recipes, but
  2951.      are enclosed by lines beginning with [ and ].
  2952.  
  2953.      The recipe flags [+,-,%,@] are recognized at the start of a
  2954.      recipe line even if they appear in a macro.  For example:
  2955.  
  2956.           SH = +
  2957.           all:
  2958.                $(SH)echo hi
  2959.  
  2960.      is completely equivalent to writing
  2961.  
  2962.           SH = +
  2963.           all:
  2964.                +echo hi
  2965.  
  2966.  
  2967.      The last step performed by dmake prior to running a recipe
  2968.      is to set the macro CMNDNAME to the name of the command to
  2969.      execute (determined by finding the first white-space ending
  2970.      token in the command line).  It then sets the macro CMNDARGS
  2971.      to be the remainder of the line.  dmake then expands the
  2972.      macro COMMAND which by default is set to
  2973.  
  2974.           COMMAND = $(CMNDNAME) $(CMNDARGS)
  2975.  
  2976.      The result of this final expansion is the command that will
  2977.      be executed.  The reason for this expansion is to allow for
  2978.      a different interface to the argument passing facilities
  2979.      (esp. under DOS) than that provided by dmake. You can for
  2980.      example define COMMAND to be
  2981.  
  2982.           COMMAND = $(CMNDNAME) @$(mktmp $(CMNDARGS))
  2983.  
  2984.      which dumps the arguments into a temporary file and runs the
  2985.      command
  2986.  
  2987.  
  2988.  
  2989. Version 3.9 PL0                 UW                             46
  2990.  
  2991.  
  2992.  
  2993.  
  2994.  
  2995. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  2996.  
  2997.  
  2998.  
  2999.           $(CMNDNAME) @/tmp/ASAD23043
  3000.  
  3001.      which has a much shorter argument list.  It is now up to the
  3002.      command to use the supplied argument as the source for all
  3003.      other arguments.  As an optimization, if COMMAND is not
  3004.      defined dmake does not perform the above expansion.  On sys-
  3005.      tems, such as UNIX, that handle long command lines this pro-
  3006.      vides a slight saving in processing the makefiles.
  3007.  
  3008. MAKING LIBRARIES
  3009.      Libraries are easy to maintain using dmake.  A library is a
  3010.      file containing a collection of object files.  Thus to make
  3011.      a library you simply specify it as a target with the
  3012.      .LIBRARY attribute set and specify its list of prere-
  3013.      quisites.  The prerequisites should be the object members
  3014.      that are to go into the library.  When dmake makes the
  3015.      library target it uses the .LIBRARY attribute to pass to the
  3016.      prerequisites the .LIBMEMBER attribute and the name of the
  3017.      library.  This enables the file binding mechanism to look
  3018.      for the member in the library if an appropriate object file
  3019.      cannot be found. A small example best illustrates this.
  3020.  
  3021.           mylib.a .LIBRARY : mem1.o mem2.o mem3.o
  3022.                rules for making library...
  3023.                # remember to remove .o's when lib is made
  3024.  
  3025.           # equivalent to:  '%.o : %.c ; ...'
  3026.           .c.o :; rules for making .o from .c say
  3027.  
  3028.      dmake will use the .c.o rule for making the library members
  3029.      if appropriate .c files can be found using the search rules.
  3030.      NOTE:  this is not specific in any way to C programs, they
  3031.      are simply used as an example.
  3032.  
  3033.      dmake tries to handle the old library construct format in a
  3034.      sensible way.  The construct lib(member.o) is separated and
  3035.      the lib portion is declared as a library target.  The new
  3036.      target is defined with the .LIBRARY attribute set and the
  3037.      member.o portion of the construct is declared as a prere-
  3038.      quisite of the lib target.  If the construct lib(member.o)
  3039.      appears as a prerequisite of a target in the makefile, that
  3040.      target has the new name of the lib assigned as its prere-
  3041.      quisite.  Thus the following example:
  3042.  
  3043.           a.out : ml.a(a.o) ml.a(b.o); $(CC) -o $@  $<
  3044.  
  3045.           .c.o :; $(CC) -c $(CFLAGS) -o $@  $<
  3046.           %.a:
  3047.                ar rv $@ $?
  3048.                ranlib $@
  3049.                rm -rf $?
  3050.  
  3051.  
  3052.  
  3053.  
  3054. Version 3.9 PL0                 UW                             47
  3055.  
  3056.  
  3057.  
  3058.  
  3059.  
  3060. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  3061.  
  3062.  
  3063.  
  3064.      constructs the following dependency graph.
  3065.  
  3066.           a.out : ml.a; $(CC) -o $@  $<
  3067.           ml.a .LIBRARY : a.o b.o
  3068.  
  3069.           %.o : %.c ; $(CC) -c $(CFLAGS) -o $@  $<
  3070.           %.a :
  3071.                ar rv $@ $?
  3072.                ranlib $@
  3073.                rm -rf $?
  3074.  
  3075.      and making a.out then works as expected.
  3076.  
  3077.      The same thing happens for any target of the form
  3078.      lib((entry)).  These targets have an additional feature in
  3079.      that the entry target has the .SYMBOL attribute set automat-
  3080.      ically.
  3081.  
  3082.      NOTE:  If the notion of entry points is supported by the
  3083.      archive and by dmake (currently not the case) then dmake
  3084.      will search the archive for the entry point and return not
  3085.      only the modification time of the member which defines the
  3086.      entry but also the name of the member file.  This name will
  3087.      then replace entry and will be used for making the member
  3088.      file.  Once bound to an archive member the .SYMBOL attribute
  3089.      is removed from the target.  This feature is presently dis-
  3090.      abled as there is little standardization among archive for-
  3091.      mats, and we have yet to find a makefile utilizing this
  3092.      feature (possibly due to the fact that it is unimplemented
  3093.      in most versions of UNIX Make).
  3094.  
  3095.      Finally, when dmake looks for a library member it must first
  3096.      locate the library file.  It does so by first looking for
  3097.      the library relative to the current directory and if it is
  3098.      not found it then looks relative to the current value of
  3099.      $(TMD).  This allows commonly used libraries to be kept near
  3100.      the root of a source tree and to be easily found by dmake.
  3101.  
  3102. KEEP STATE
  3103.      dmake supports the keeping of state information for targets
  3104.      that it makes whenever the macro .KEEP_STATE is assigned a
  3105.      value.  The value of the macro should be the name of a state
  3106.      file that will contain the state information.  If state
  3107.      keeping is enabled then each target that does not poses the
  3108.      .NOSTATE attribute will have a record written into the state
  3109.      file indicating the target's name, the current directory,
  3110.      the command used to update the target, and which, if any, ::
  3111.      rule is being used.  When you make this target again if any
  3112.      of this information does not match the previous settings and
  3113.      the target is not out dated it will still be re-made.  The
  3114.      assumption is that one of the conditions above has changed
  3115.      and that we wish to remake the target.  For example, state
  3116.  
  3117.  
  3118.  
  3119. Version 3.9 PL0                 UW                             48
  3120.  
  3121.  
  3122.  
  3123.  
  3124.  
  3125. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  3126.  
  3127.  
  3128.  
  3129.      keeping is used in the maintenance of dmake to test compile
  3130.      different versions of the source using different compilers.
  3131.      Changing the compiler causes the compilation flags to be
  3132.      modified and hence all sources to be recompiled.
  3133.  
  3134.      The state file is an ascii file and is portable, however it
  3135.      is not in human readable form as the entries represent hash
  3136.      keys of the above information.
  3137.  
  3138.      The Sun Microsystem's Make construct
  3139.  
  3140.           .KEEP_STATE :
  3141.  
  3142.      is recognized and is mapped to .KEEP_STATE:=_state.mk.  The
  3143.      dmake version of state keeping does not include scanning C
  3144.      source files for dependencies like Sun Make.  This is
  3145.      specific to C programs and it was felt that it does not
  3146.      belong in make.  dmake instead provides the tool, cdepend,
  3147.      to scan C source files and to produce depedency information.
  3148.      Users are free to modify cdepend to produce other dependency
  3149.      files.  (NOTE: cdepend does not come with the distribution
  3150.      at this time, but will be available in a patch in the near
  3151.      future)
  3152.  
  3153. MULTI PROCESSING
  3154.      If the architecture supports it then dmake is capable of
  3155.      making a target's prerequisites in parallel.  dmake will
  3156.      make as much in parallel as it can and use a number of child
  3157.      processes up to the maximum specified by MAXPROCESS or by
  3158.      the value supplied to the -P command line flag.  A parallel
  3159.      make is enabled by setting the value of MAXPROCESS (either
  3160.      directly or via -P option) to a value which is > 1.  dmake
  3161.      guarantees that all dependencies as specified in the
  3162.      makefile are honored.  A target will not be made until all
  3163.      of its prerequisites have been made.  Note that when you
  3164.      specify -P 4 then four child processes are run concurrently
  3165.      but dmake actually displays the fifth command it will run
  3166.      immediately upon a child process becomming free.  This is an
  3167.      artifact of the method used to traverse the dependency graph
  3168.      and cannot be removed.  If a parallel make is being per-
  3169.      formed then the following restrictions on parallelism are
  3170.      enforced.
  3171.  
  3172.           1.   Individual recipe lines in a non-group recipe are
  3173.                performed sequentially in the order in which they
  3174.                are specified within the makefile and in parallel
  3175.                with the recipes of other targets.
  3176.  
  3177.           2.   If a target contains multiple recipe definitions
  3178.                (cf. :: rules) then these are performed sequen-
  3179.                tially in the order in which the :: rules are
  3180.                specified within the makefile and in parallel with
  3181.  
  3182.  
  3183.  
  3184. Version 3.9 PL0                 UW                             49
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  3191.  
  3192.  
  3193.  
  3194.                the recipes of other targets.
  3195.  
  3196.           3.   If a target rule contains the `!' modifier, then
  3197.                the recipe is performed sequentially for the list
  3198.                of outdated prerequisites and in parallel with the
  3199.                recipes of other targets.
  3200.  
  3201.           4.   If a target has the .SEQUENTIAL attribute set then
  3202.                all of its prerequisites are made sequentially
  3203.                relative to one another (as if MAXPROCESS=1), but
  3204.                in parallel with other targets in the makefile.
  3205.  
  3206.      Note:  If you specify a parallel make then the order of tar-
  3207.      get update and the order in which the associated recipes are
  3208.      invoked will not correspond to that displayed by the -n
  3209.      flag.
  3210.  
  3211. CONDITIONALS
  3212.      dmake supports a makefile construct called a conditional.
  3213.      It allows the user to conditionally select portions of
  3214.      makefile text for input processing and to discard other por-
  3215.      tions.  This becomes useful for writing makefiles that are
  3216.      intended to function for more than one target host and
  3217.      environment.  The conditional expression is specified as
  3218.      follows:
  3219.  
  3220.           .IF  expression
  3221.              ... if text ...
  3222.           .ELIF  expression
  3223.              ... if text ...
  3224.           .ELSE
  3225.              ... else text ...
  3226.           .END
  3227.  
  3228.      The .ELSE and .ELIF portions are optional, and the condi-
  3229.      tionals may be nested (ie.  the text may contain another
  3230.      conditional).  .IF, .ELSE, and .END may appear anywhere in
  3231.      the makefile, but a single conditional expression may not
  3232.      span multiple makefiles.
  3233.  
  3234.      expression can be one of the following three forms:
  3235.  
  3236.           <text> | <text> == <text> | <text> != <text>
  3237.  
  3238.      where text is either text or a macro expression.  In any
  3239.      case, before the comparison is made, the expression is
  3240.      expanded.  The text portions are then selected and compared.
  3241.      White space at the start and end of the text portion is dis-
  3242.      carded before the comparison.  This means that a macro that
  3243.      evaluates to nothing but white space is considered a NULL
  3244.      value for the purpose of the comparison.  In the first case
  3245.      the expression evaluates TRUE if the text is not NULL
  3246.  
  3247.  
  3248.  
  3249. Version 3.9 PL0                 UW                             50
  3250.  
  3251.  
  3252.  
  3253.  
  3254.  
  3255. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  3256.  
  3257.  
  3258.  
  3259.      otherwise it evaluates FALSE.  The remaining two cases both
  3260.      evaluate the expression on the basis of a string comparison.
  3261.      If a macro expression needs to be equated to a NULL string
  3262.      then compare it to the value of the macro $(NULL).  You can
  3263.      use the $(shell ...) macro to construct more complex test
  3264.      expressions.
  3265.  
  3266. EXAMPLES
  3267.           # A simple example showing how to use make
  3268.           #
  3269.           prgm : a.o b.o
  3270.                cc a.o b.o -o prgm
  3271.           a.o : a.c g.h
  3272.                cc a.c -o $@
  3273.           b.o : b.c g.h
  3274.                cc b.c -o $@
  3275.  
  3276.      In the previous example prgm is remade only if a.o and/or
  3277.      b.o is out of date with respect to prgm.  These dependencies
  3278.      can be stated more concisely by using the inference rules
  3279.      defined in the standard startup file.  The default rule for
  3280.      making .o's from .c's looks something like this:
  3281.  
  3282.           %.o : %.c; cc -c $(CFLAGS) -o $@ $<
  3283.  
  3284.      Since there exists a rule (defined in the startup file) for
  3285.      making .o's from .c's dmake will use that rule for manufac-
  3286.      turing a .o from a .c and we can specify our dependencies
  3287.      more concisely.
  3288.  
  3289.           prgm : a.o b.o
  3290.                cc -o prgm $<
  3291.           a.o b.o : g.h
  3292.  
  3293.      A more general way to say the above using the new macro
  3294.      expansions would be:
  3295.  
  3296.           SRC = a b
  3297.           OBJ = {$(SRC)}.o
  3298.  
  3299.           prgm : $(OBJ)
  3300.                cc -o $@ $<
  3301.  
  3302.           $(OBJ) : g.h
  3303.  
  3304.      If we want to keep the objects in a separate directory,
  3305.      called objdir, then we would write something like this.
  3306.  
  3307.           SRC = a b
  3308.           OBJ = {$(SRC)}.o
  3309.  
  3310.           prgm : $(OBJ)
  3311.  
  3312.  
  3313.  
  3314. Version 3.9 PL0                 UW                             51
  3315.  
  3316.  
  3317.  
  3318.  
  3319.  
  3320. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  3321.  
  3322.  
  3323.  
  3324.                cc $< -o $@
  3325.  
  3326.           $(OBJ) : g.h
  3327.           %.o : %.c
  3328.                $(CC) -c $(CFLAGS) -o $(@:f) $<
  3329.                mv $(@:f) objdir
  3330.  
  3331.           .SOURCE.o : objdir       # tell make to look here for .o's
  3332.  
  3333.      An example of building library members would go something
  3334.      like this: (NOTE:  The same rules as above will be used to
  3335.      produce .o's from .c's)
  3336.  
  3337.           SRC  = a b
  3338.           LIB  = lib
  3339.           LIBm = { $(SRC) }.o
  3340.  
  3341.           prgm: $(LIB)
  3342.                cc -o $@ $(LIB)
  3343.  
  3344.           $(LIB) .LIBRARY : $(LIBm)
  3345.                ar rv $@ $<
  3346.                rm $<
  3347.  
  3348.      Finally, suppose that each of the source files in the previ-
  3349.      ous example had the `:' character in their target name.
  3350.      Then we would write the above example as:
  3351.  
  3352.           SRC  = f:a f:b
  3353.           LIB  = lib
  3354.           LIBm = "{ $(SRC) }.o"         # put quotes around each token
  3355.  
  3356.           prgm: $(LIB)
  3357.                cc -o $@ $(LIB)
  3358.  
  3359.           $(LIB) .LIBRARY : $(LIBm)
  3360.                ar rv $@ $<
  3361.                rm $<
  3362.  
  3363. COMPATIBILITY
  3364.      There are two notable differences between dmake and the
  3365.      standard version of BSD UNIX 4.2/4.3 Make.
  3366.  
  3367.           1. BSD UNIX 4.2/4.3 Make supports wild card filename
  3368.              expansion for prerequisite names.  Thus if a direc-
  3369.              tory contains a.h, b.h and c.h, then a line like
  3370.  
  3371.                   target: *.h
  3372.  
  3373.              will cause UNIX make to expand the *.h into "a.h b.h
  3374.              c.h".  dmake does not support this type of filename
  3375.              expansion.
  3376.  
  3377.  
  3378.  
  3379. Version 3.9 PL0                 UW                             52
  3380.  
  3381.  
  3382.  
  3383.  
  3384.  
  3385. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  3386.  
  3387.  
  3388.  
  3389.           2. Unlike UNIX make, touching a library member causes
  3390.              dmake to search the library for the member name and
  3391.              to update the library time stamp.  This is only
  3392.              implemented in the UNIX version.  MSDOS and other
  3393.              versions may not have librarians that keep file time
  3394.              stamps, as a result dmake touches the library file
  3395.              itself, and prints a warning.
  3396.  
  3397.      dmake is not compatible with GNU Make.  In particular it
  3398.      does not understand GNU Make's macro expansions that query
  3399.      the file system.
  3400.  
  3401.      dmake is fully compatible with SYSV AUGMAKE, and supports
  3402.      the following AUGMAKE features:
  3403.  
  3404.           1. The word include appearing at the start of a line
  3405.              can be used instead of the ".INCLUDE :" construct
  3406.              understood by dmake.
  3407.  
  3408.           2. The macro modifier expression $(macro:str=sub) is
  3409.              understood and is equivalent to the expression
  3410.              $(macro:s/str/sub), with the restriction that str
  3411.              must match the following regular expression:
  3412.  
  3413.                   str[ |\t][ |\t]*
  3414.  
  3415.              (ie. str only matches at the end of a token where
  3416.              str is a suffix and is terminated by a space, a tab,
  3417.              or end of line) Normally sub is expanded before the
  3418.              substitution is made, if you specify -A on the com-
  3419.              mand line then sub is not expanded.
  3420.  
  3421.           3. The macro % is defined to be $@ (ie. $% expands to
  3422.              the same value as $@).
  3423.  
  3424.           4. The AUGMAKE notion of libraries is handled
  3425.              correctly.
  3426.  
  3427.           5. When defining special targets for the inference
  3428.              rules and the AUGMAKE special target handling is
  3429.              enabled then the special target .X is equivalent to
  3430.              the %-rule "% : %.X".
  3431.  
  3432.           6. Directories are always made if you specify -A.  This
  3433.              is consistent with other UNIX versions of Make.
  3434.  
  3435.           7. Makefiles that utilize virtual targets to force mak-
  3436.              ing of other targets work as expected if AUGMAKE
  3437.              special target handling is enabled.  For example:
  3438.  
  3439.                   FRC:
  3440.                   myprog.o : myprog.c $(FRC) ; ...
  3441.  
  3442.  
  3443.  
  3444. Version 3.9 PL0                 UW                             53
  3445.  
  3446.  
  3447.  
  3448.  
  3449.  
  3450. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  3451.  
  3452.  
  3453.  
  3454.              Works as expected if you issue the command
  3455.  
  3456.                   'dmake -A FRC=FRC'
  3457.  
  3458.              but fails with a 'don't know how to make FRC' error
  3459.              message if you do not specify AUGMAKE special target
  3460.              handling via the -A flag (or by setting AUGMAKE:=yes
  3461.              internally).
  3462.  
  3463. LIMITS
  3464.      In some environments the length of an argument string is
  3465.      restricted.  (e.g. MSDOS command line arguments cannot be
  3466.      longer than 128 bytes if you are using the standard
  3467.      command.com command interpreter as your shell, dmake text
  3468.      diversions may help in these situations.)
  3469.  
  3470. PORTABILITY
  3471.      To write makefiles that can be moved from one environment to
  3472.      another requires some forethought.  In particular you must
  3473.      define as macros all those things that may be different in
  3474.      the new environment.  dmake has two facilities that help to
  3475.      support writing portable makefiles, recursive macros and
  3476.      conditional expressions.  The recursive macros, allow one to
  3477.      define environment configurations that allow different
  3478.      environments for similar types of operating systems.  For
  3479.      example the same make script can be used for SYSV and BSD
  3480.      but with different macro definitions.
  3481.  
  3482.      To write a makefile that is portable between UNIX and MSDOS
  3483.      requires both features since in almost all cases you will
  3484.      need to define new recipes for making targets.  The recipes
  3485.      will probably be quite different since the capabilities of
  3486.      the tools on each machine are different.  Different macros
  3487.      will be needed to help handle the smaller differences in the
  3488.      two environments.
  3489.  
  3490. FILES
  3491.      Makefile, makefile, startup.mk (use dmake -V to tell you
  3492.      where the startup file is)
  3493.  
  3494. SEE ALSO
  3495.      sh(1), csh(1), touch(1), f77(1), pc(1), cc(1)
  3496.      S.I. Feldman  Make - A Program for Maintaining Computer Pro-
  3497.      grams
  3498.  
  3499. AUTHOR
  3500.      Dennis Vadura, CS Dept. University of Waterloo.
  3501.      dvadura@watdragon.uwaterloo.ca
  3502.      Many thanks to Carl Seger for his helpful suggestions, and
  3503.      to Trevor John Thompson for his many excellent ideas and
  3504.      informative bug reports.
  3505.  
  3506.  
  3507.  
  3508.  
  3509. Version 3.9 PL0                 UW                             54
  3510.  
  3511.  
  3512.  
  3513.  
  3514.  
  3515. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  3516.  
  3517.  
  3518.  
  3519. BUGS
  3520.      Some system commands return non-zero status inappropriately.
  3521.      Use -i (`-' within the makefile) to overcome the difficulty.
  3522.  
  3523.      Some systems do not have easily accessible time stamps for
  3524.      library members (MSDOS, AMIGA, etc) for these dmake uses the
  3525.      time stamp of the library instead and prints a warning the
  3526.      first time it does so.  This is almost always ok, except
  3527.      when multiple makefiles update a single library file.  In
  3528.      these instances it is possible to miss an update if one is
  3529.      not careful.
  3530.  
  3531.      This man page is way too long.
  3532.  
  3533. WARNINGS
  3534.      Rules supported by make(1) may not work if transitive clo-
  3535.      sure is turned off (-T, .NOINFER).
  3536.  
  3537.      PWD from csh/ksh will cause problems if a cd operation is
  3538.      performed and -e or -E option is used.
  3539.  
  3540.      Using internal macros such as COMMAND, may wreak havoc if
  3541.      you don't understand their functionality.
  3542.  
  3543.  
  3544.  
  3545.  
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574. Version 3.9 PL0                 UW                             55
  3575.