Provided by: 9base_6-13_amd64 bug

NAME

       mk - maintain (make) related files

SYNOPSIS

       mk [ -f mkfile ] ...  [ option ...  ] [ target ...  ]

DESCRIPTION

       Mk  uses  the  dependency  rules  specified  in  mkfile  to control the update (usually by
       compilation) of targets (usually files) from the source files upon which they depend.  The
       mkfile  (default  contains  a  rule  for  each  target that identifies the files and other
       targets upon which it depends and an sh(1) script, a recipe, to update  the  target.   The
       script  is  run  if  the  target does not exist or if it is older than any of the files it
       depends on.  Mkfile may also contain meta-rules that define actions for updating  implicit
       targets.   If  no  target  is  specified,  the target of the first rule (not meta-rule) in
       mkfile is updated.

       The environment variable $NPROC determines how many targets may be updated simultaneously;
       Some  operating  systems,  e.g., Plan 9, set $NPROC automatically to the number of CPUs on
       the current machine.

       Options are:

       -a      Assume all targets to be out of date.  Thus, everything is updated.
       -d[egp] Produce debugging  output  (p  is  for  parsing,  g  for  graph  building,  e  for
               execution).
       -e      Explain why each target is made.
       -i      Force any missing intermediate targets to be made.
       -k      Do as much work as possible in the face of errors.
       -n      Print, but do not execute, the commands needed to update the targets.
       -s      Make the command line arguments sequentially rather than in parallel.
       -t      Touch (update the modified date of) file targets, without executing any recipes.
       -wtarget1,target2,...
               Pretend the modify time for each target is the current time; useful in conjunction
               with -n to learn what updates would be triggered by modifying the targets.

   The mkfile
       A mkfile consists of assignments  (described  under  `Environment')  and  rules.   A  rule
       contains  targets  and  a tail.  A target is a literal string and is normally a file name.
       The tail contains zero or more prerequisites and an optional recipe,  which  is  an  shell
       script.  Each line of the recipe must begin with white space.  A rule takes the form

              target: prereq1 prereq2
                      recipe using prereq1, prereq2 to build target

       When the recipe is executed, the first character on every line is elided.

       After the colon on the target line, a rule may specify attributes, described below.

       A  meta-rule  has  a target of the form A%B where A and B are (possibly empty) strings.  A
       meta-rule acts as a rule for any potential target whose name matches A%B with  %  replaced
       by  an  arbitrary  string,  called  the  stem.   In  interpreting a meta-rule, the stem is
       substituted for all occurrences of % in the prerequisite names.  In the recipe of a  meta-
       rule, the environment variable $stem contains the string matched by the %.  For example, a
       meta-rule to compile a C program using 9c(1) might be:

              %:    %.c
                      9c -c $stem.c
                      9l -o $stem $stem.o

       Meta-rules may contain an ampersand & rather than a percent sign %.  A % matches a maximal
       length  string  of  any characters; an & matches a maximal length string of any characters
       except period or slash.

       The text of the mkfile is processed as follows.  Lines beginning with < followed by a file
       name  are replaced by the contents of the named file.  Lines beginning with <| followed by
       a file name are replaced by the output of the execution of the named  file.   Blank  lines
       and  comments, which run from unquoted # characters to the following newline, are deleted.
       The character sequence backslash-newline is deleted,  so  long  lines  in  mkfile  may  be
       folded.   Non-recipe  lines are processed by substituting for `{command} the output of the
       command when run by sh.  References to variables are replaced by  the  variables'  values.
       Special characters may be quoted using single quotes '' as in sh(1).

       Assignments  and rules are distinguished by the first unquoted occurrence of : (rule) or =
       (assignment).

       A later rule may modify or override an existing rule under the following conditions:

       -      If the targets of the rules exactly match and one rule contains only a prerequisite
              clause  and  no recipe, the clause is added to the prerequisites of the other rule.
              If either or both targets are virtual, the recipe is always executed.

       -      If the targets of the rules match exactly and the prerequisites do  not  match  and
              both rules contain recipes, mk reports an ``ambiguous recipe'' error.

       -      If  the  target  and  prerequisites  of  both  rules match exactly, the second rule
              overrides the first.

   Environment
       Rules may make use of shell environment variables.  A legal reference of the form $OBJ  or
       ${name}  is expanded as in sh(1).  A reference of the form ${name:A%B=C%D}, where A, B, C,
       D are (possibly empty) strings, has the value formed by expanding $name and substituting C
       for A and D for B in each word in $name that matches pattern A%B.

       Variables can be set by assignments of the form
               var=[attr=]value
       Blanks  in  the value break it into words.  Such variables are exported to the environment
       of recipes as they are executed, unless U, the only legal attribute attr, is present.  The
       initial  value of a variable is taken from (in increasing order of precedence) the default
       values below, mk's environment, the  mkfiles,  and  any  command  line  assignment  as  an
       argument  to  mk.   A  variable  assignment  argument  overrides  the  first  (but not any
       subsequent) assignment to that variable.

       The variable MKFLAGS contains  all  the  option  arguments  (arguments  starting  with  or
       containing and MKARGS contains all the targets in the call to mk.

       The variable MKSHELL contains the shell command line mk uses to run recipes.  If the first
       word of the command ends in rc or rcsh, mk uses rc(1)'s quoting rules; otherwise  it  uses
       sh(1)'s.   The  MKSHELL  variable  is  consulted  when  the mkfile is read, not when it is
       executed, so that different shells can be used within a single mkfile:

              MKSHELL=$PLAN9/bin/rc
              use-rc:V:
                   for(i in a b c) echo $i

              MKSHELL=sh
              use-sh:V:
                   for i in a b c; do echo $i; done

       Mkfiles included via < or <| (q.v.)  see their own private copy of MKSHELL,  which  always
       starts set to sh .

       Dynamic information may be included in the mkfile by using a line of the form

              <|command args

       This  runs the command command with the given arguments args and pipes its standard output
       to mk to be included as part of the mkfile. For instance, the  Inferno  kernels  use  this
       technique  to run a shell command with an awk script and a configuration file as arguments
       in order for the awk script to process the file and output a set of  variables  and  their
       values.

   Execution
       During execution, mk determines which targets must be updated, and in what order, to build
       the names specified on the command line.  It then runs the associated recipes.

       A target is considered up to date if it has no prerequisites or if all  its  prerequisites
       are  up  to date and it is newer than all its prerequisites.  Once the recipe for a target
       has executed, the target is considered up to date.

       The date stamp used to determine if a target is up to date  is  computed  differently  for
       different  types  of  targets.   If  a  target is virtual (the target of a rule with the V
       attribute), its date stamp is initially zero; when the target is updated the date stamp is
       set  to  the most recent date stamp of its prerequisites.  Otherwise, if a target does not
       exist as a file, its date stamp is set to the most recent date stamp of its prerequisites,
       or  zero  if it has no prerequisites.  Otherwise, the target is the name of a file and the
       target's date stamp is always that file's modification date.  The date stamp  is  computed
       when the target is needed in the execution of a rule; it is not a static value.

       Nonexistent  targets  that have prerequisites and are themselves prerequisites are treated
       specially.  Such a target t is given the date stamp of its most recent prerequisite and if
       this  causes  all  the  targets  which  have  t  as  a prerequisite to be up to date, t is
       considered up to date.  Otherwise, t is made in the normal fashion.  The -i flag overrides
       this special treatment.

       Files may be made in any order that respects the preceding restrictions.

       A  recipe  is  executed  by supplying the recipe as standard input to the command /bin/sh.
       (Note that unlike make, mk feeds the entire recipe to the shell rather than  running  each
       line of the recipe separately.)  The environment is augmented by the following variables:

       $alltarget    all the targets of this rule.

       $newprereq    the prerequisites that caused this rule to execute.

       $newmember    the  prerequisites that are members of an aggregate that caused this rule to
                     execute.  When the prerequisites of a rule  are  members  of  an  aggregate,
                     $newprereq contains the name of the aggregate and out of date members, while
                     $newmember contains only the name of the members.

       $nproc        the process slot for this recipe.  It satisfies 0≤$nproc<$NPROC.

       $pid          the process id for the mk executing the recipe.

       $prereq       all the prerequisites for this rule.

       $stem         if this is a meta-rule, $stem is the string that matched % or &.  Otherwise,
                     it  is  empty.  For regular expression meta-rules (see below), the variables
                     are set to the corresponding subexpressions.

       $target       the targets for this rule that need to be remade.

       These variables are available only during the execution of a recipe, not while  evaluating
       the mkfile.

       Unless  the  rule  has  the  Q  attribute,  the  recipe is printed prior to execution with
       recognizable environment variables expanded.  Commands returning error status cause mk  to
       terminate.

       Recipes and backquoted rc commands in places such as assignments execute in a copy of mk's
       environment; changes they make to environment variables are not visible from mk.

       Variable substitution in a rule is done when the rule is read;  variable  substitution  in
       the recipe is done when the recipe is executed.  For example:

              bar=a.c
              foo: $bar
                      $CC -o foo $bar
              bar=b.c

       will compile b.c into foo, if a.c is newer than foo.

   Aggregates
       Names  of  the  form  a(b)  refer  to  member  b  of the aggregate a.  Currently, the only
       aggregates supported are 9ar (see 9c(1)) archives.

   Attributes
       The colon separating the target from the prerequisites  may  be  immediately  followed  by
       attributes and another colon.  The attributes are:

       D      If the recipe exits with a non-null status, the target is deleted.

       E      Continue execution if the recipe draws errors.

       N      If there is no recipe, the target has its time updated.

       n      The  rule  is  a  meta-rule  that cannot be a target of a virtual rule.  Only files
              match the pattern in the target.

       P      The characters after the P until the terminating : are taken as a program name.  It
              will be invoked as sh -c prog 'arg1' 'arg2' and should return a zero exit status if
              and only if arg1 is up to date  with  respect  to  arg2.   Date  stamps  are  still
              propagated in the normal way.

       Q      The recipe is not printed prior to execution.

       R      The  rule  is a meta-rule using regular expressions.  In the rule, % has no special
              meaning.  The  target  is  interpreted  as  a  regular  expression  as  defined  in
              regexp(7).   The prerequisites may contain references to subexpressions in form \n,
              as in the substitute command of sed(1).

       U      The targets are considered to have been updated even if the recipe did not do so.

       V      The targets of this rule are marked as virtual.  They are distinct  from  files  of
              the same name.

EXAMPLES

       A simple mkfile to compile a program:

              </$objtype/mkfile

              prog:   a.$O b.$O c.$O
                      $LD $LDFLAGS -o $target $prereq

              %.$O:   %.c
                      $CC $CFLAGS $stem.c

       Override flag settings in the mkfile:

              % mk target 'CFLAGS=-S -w'

       Maintain a library:

              libc.a(%.$O):N: %.$O
              libc.a: libc.a(abs.$O) libc.a(access.$O) libc.a(alarm.$O) ...
                      ar r libc.a $newmember

       String expression variables to derive names from a master list:

              NAMES=alloc arc bquote builtins expand main match mk var word
              OBJ=${NAMES:%=%.$O}

       Regular expression meta-rules:

              ([^/]*)/(.*)\.$O:R:  \1/\2.c
                      cd $stem1; $CC $CFLAGS $stem2.c

       A  correct  way  to  deal with yacc(1) grammars.  The file lex.c includes the file x.tab.h
       rather than y.tab.h in order to reflect changes in content, not just modification time.

              lex.$O: x.tab.h
              x.tab.h:        y.tab.h
                      cmp -s x.tab.h y.tab.h || cp y.tab.h x.tab.h
              y.tab.c y.tab.h:        gram.y
                      $YACC -d gram.y

       The above example could also use the P attribute for the x.tab.h rule:

              x.tab.h:Pcmp -s:        y.tab.h
                      cp y.tab.h x.tab.h

SOURCE

       /src/cmd/mk

SEE ALSO

       sh(1), regexp(7)

       A. Hume, ``Mk: a Successor to Make'' (Tenth Edition Research Unix Manuals).

       Andrew  G.  Hume  and  Bob  Flandrena,  ``Maintaining  Files  on   Plan   9   with   Mk''.
       DOCPREFIX/doc/mk.pdf

HISTORY

       Andrew  Hume  wrote  mk  for  Tenth Edition Research Unix.  It was later ported to Plan 9.
       This software is a port of the Plan 9 version back to Unix.

BUGS

       Identical recipes for regular expression meta-rules only have one target.

       Seemingly appropriate input like CFLAGS=-DHZ=60  is  parsed  as  an  erroneous  attribute;
       correct it by inserting a space after the first

       The  recipes  printed  by  mk before being passed to the shell for execution are sometimes
       erroneously expanded for printing.  Don't trust what's printed; rely  on  what  the  shell
       does.

                                                                                       MK(1plan9)