path: root/static/v10/man1/mk.1

.TH MK 1
.CT 1 prog_c writing_troff prog_other
.SH NAME
mk, mkconv, membername \- maintain (make) related files
.SH SYNOPSIS
.B mk
[
.B -f
.I mkfile
] ...
[
.I option ...
]
[
.I name ...
]
.PP
.B mkconv
.I makefile
.PP
.B membername
.I aggregate ...
.SH DESCRIPTION
.I Mk
is most often used to keep object files current with the
source they depend on.
.PP
.I Mk
reads
.I mkfile
and builds and executes dependency dags (directed acyclic graphs) for the target
.IR names .
If no target is specified, the targets of the first non-metarule in
the first
.I mkfile
are used.
If no
.B -f
option is present,
.L mkfile
is tried.
Other options are:
.TP \w'\fL-d[egp]\ 'u
.B -a
Assume all targets to be out of date.
Thus, everything gets made.
.PD 0
.TP
.BR -d [ egp ]
Produce debugging output
.RB ( p
is for parsing,
.B g
for graph building,
.B e
for execution).
.TP
.B -e
Explain why each target is made.
.TP
.B -i
Force any missing intermediate targets to be made.
.TP
.B -k
Do as much work as possible in the face of errors.
.TP
.B -m
Generate an equivalent makefile on standard output.
Recipes are not handled well.
.TP
.B -n
Print, but do not execute, the commands
needed to update the targets.
.TP
.B -t
Touch (update the modified date of) non-virtual targets, without
executing any recipes.
.TP
.B -u
Produce a table of clock seconds spent with
.I n
recipes running.
.TP
.BI -w name1,name2,...
Set the initial date stamp for each name
to the current time.
The names may also be separated by blanks or newlines.
(Use with
.B -n
to find what else would need to change if the named files
were modified.)
.PD
.PP
.I Mkconv
attempts to convert a
.IR make (1)
.I makefile
to a
.IR mkfile
on standard output.
The conversion is not likely to be faithful.
.PP
The shell script
.I membername
extracts member names
(see `Aggregates' below)
from its arguments.
.SS Definitions
A
.I mkfile
consists of
.I assignments
(described under `Environment') and
.IR rules .
A rule contains
.I targets
and a
.I tail.
A target is a literal string, or
.I label,
and is normally a file name.
The tail contains zero or more 
.I prerequisites
and an optional
.I recipe,
which is a shell script.
.PP
A
.I metarule 
has a target of the form
.IB A % B
where
.I A
and
.I B
are (possibly empty) strings.
A metarule applies to any label that matches the target with
.B %
replaced by an arbitrary string, called the
.IR stem .
In interpreting a metarule,
the stem is substituted for all occurrences of
.B %
in the prerequisite names.
A metarule may be marked as using regular expressions (described under `Syntax').
In this case,
.B %
has no special meaning;
the target is interpreted according to
.IR regexp (3).
The dependencies may refer to subexpressions in the normal way, using
.BI \e n.
The
.I dependency dag
for a target consists of
.I nodes
connected by directed
.IR arcs .
A node consists of a label
and a set of arcs leading to prerequisite nodes.
The root 
node is labeled with an original target
.I name.
.SS Building the Dependency Dag
.PP
Read the
.I mkfiles 
in command line order and distribute rule tails over targets
to get single-target rules.
.PP
For a node
.IR n ,
for every rule
.I r
that matches
.IR n 's
label generate an arc to a prerequisite node.
The node
.I n
is then marked as done.
The process is then repeated for each of the prerequisite nodes.
The process stops if
.I n
is already done,
or if
.I n
has no prerequisites,
or if any rule would be used more than
.B $NREP
times on the current path in the dag.
A probable node is one where the label exists as a file
or is a target of a non-metarule.
.PP
After the graph is built, it is checked for cycles,
and subdags containing no probable nodes are deleted.
Also, for any node with arcs generated by a non-metarule with a recipe,
arcs generated by a metarule with a recipe
are deleted.
Disconnected subdags are deleted.
.SS Execution
Labels have an associated date stamp.
A label is
.I ready
if it has no prerequisites, or
all its prerequisites are made.
A ready label is
.I trivially uptodate
if it is not a target and has a nonzero date stamp, or
it has a nonzero date stamp,
and all its prerequisites are made and predate the ready label.
A ready label is marked
.I made
(and given a date stamp)
if it is trivially uptodate or by executing the recipe
associated with the arcs leading from the node associated with the ready label.
The
.B P
attribute can be used to generalize
.IR mk 's
notion of determining if prerequisites predate a label.
Rather than comparing date stamps, it executes a specified program
and uses the exit status.
.PP
Date stamps are calculated differently for virtual labels,
for labels that correspond to extant files,
and for other labels.
If a label is
.I virtual
(target of a rule with the
.B V
attribute),
its date stamp is initially zero and upon being made is set to
the most recent date stamp of its prerequisites.
Otherwise, if a label is nonexistent
(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 label is the name of a file and
the label's date stamp is always that file's modification date.
.PP
Nonexistent labels which have prerequisites
and are prerequisite to other label(s) are treated specially unless the
.B -i
flag is used.
Such a label
.I l
is given the date stamp of its most recent prerequisite
and if this causes all the labels which have
.I l
as a prerequisite to be trivially uptodate,
.I l
is considered to be trivially uptodate.
Otherwise,
.I l
is made in the normal fashion.
.PP
Two recipes are called identical if they arose by distribution
from a single rule as described above.
Identical recipes may be executed only when all
their prerequisite nodes are ready, and then just one instance of
the identical recipes is executed to make all their target nodes.
.PP
Files may be made in any order that respects
the preceding restrictions.
.PP
A recipe is executed by supplying the recipe as standard input to
the command
.B
        /bin/sh -e
.br
The environment is augmented by the following variables:
.TP 14
.B $alltarget
all the targets of this rule.
.TP
.B $newprereq
the prerequisites that caused this rule to execute.
.TP
.B $nproc
the process slot for this recipe.
It satisfies
.RB 0\(<= $nproc < $NPROC ,
where
.B $NPROC
is the maximum number of recipes that may be executing
simultaneously.
.TP
.B $pid
the process id for the
.I mk
forking the recipe.
.TP
.B $prereq
all the prerequisites for this rule.
.TP
.B $stem
if this is a metarule,
.B $stem
is the string that matched
.BR % .
Otherwise, it is empty.
For regular expression metarules, the variables
.LR stem0 ", ...,"
.L stem9
are set to the corresponding subexpressions.
.TP
.B $target
the targets for this rule that need to be remade.
.PP
Unless the rule has the
.B Q
attribute,
the recipe is printed prior to execution
with recognizable shell variables expanded.
To see the commands print as they execute,
include a
.L set -x
in your rule.
Commands returning nonzero status (see
.IR intro (1))
cause
.I mk
to terminate.
.SS Aggregates
Names of the form
.IR a ( b )
refer to member
.I b
of the aggregate
.IR a .
Currently, the only aggregates supported are
.IR ar (1)
archives.
.SS Environment
Rules may make use of shell (or environment) variables.
A legal shell variable reference of the form
.B $OBJ
or
.B ${name}
is expanded as in
.IR sh (1).
A reference of the form
.BI ${name: A % B = C\fB%\fID\fB}\fR,
where
.I A, B, C, D
are (possibly empty) strings,
has the value formed by expanding
.B $name
and substituting
.I C
for
.I A
and
.I D
for
.I B
in each word in
.B $name
that matches pattern
.IB A % B .
.PP
Variables can be set by
assignments of the form
.I
        var\fB=\fR[\fIattr\fB=\fR]\fItokens\fR
.br
where
.I tokens
and the optional attributes
are defined under `Syntax' below.
The environment is exported to recipe executions.
Variable values are taken from (in increasing order of precedence)
the default values below, the environment, the mkfiles,
and any command line assignment.
A variable assignment argument overrides the first (but not any subsequent)
assignment to that variable.
.br
.ne 1i
.EX
.ta \n(.lu/3u +\n(.lu/3u
.nf
AS=as	FFLAGS=	NPROC=1
CC=cc	LEX=lex	NREP=1
CFLAGS=	LFLAGS=	YACC=yacc
FC=f77	LDFLAGS=	YFLAGS=	
BUILTINS='
.ta 8n
%.o:	%.c
	$CC $CFLAGS -c $stem.c
%.o:	%.s
	$AS -o $stem.o $stem.s
%.o:	%.f
	$FC $FFLAGS -c $stem.f
%.o:	%.y
	$YACC $YFLAGS $stem.y &&
	$CC $CFLAGS -c y.tab.c && mv y.tab.o $stem.o; rm y.tab.c
%.o:	%.l
	$LEX $LFLAGS -t $stem.l > $stem.c &&
	$CC $CFLAGS -c $stem.c && rm $stem.c'
ENVIRON=
.EE
.PP
The builtin rules are obtained from the variable
.B BUILTINS
after all input has been processed.
The 
.B ENVIRON
variable is split into parts at control-A characters,
the control-A characters are deleted, and the parts are 
placed in the environment.
The variable
.B MKFLAGS
contains all the option arguments (arguments starting with
.L -
or containing
.LR = )
and
.B MKARGS
contains all the targets in the call to
.IR mk .
.SS Syntax
Leading white space (blank or tab) is ignored.
Input after an unquoted
.B #
(a comment) is ignored as are blank lines.
Lines can be spread over several physical lines by
placing a
.B \e
before newlines to be elided.
Non-recipe lines are processed by substituting for
.BI ` cmd `
and then substituting for variable references.
Finally, the filename metacharacters
.B []*?
are expanded.
.tr #"
Quoting by
.BR \&'' ,
.BR ## ,
and
.B \e
is supported.
The semantics for substitution and quoting are given in
.IR sh (1).
.PP
The contents of files may be included by lines beginning with
.B <
followed by a filename.
.PP
.tr ##
Assignments and rule header lines are distinguished by
the first unquoted occurrence of
.B :
(rule header)
or
.B =
(assignment).
.PP
A rule definition consists of a header line followed by a recipe.
The recipe consists of all lines following the header line
that start with white space.
The recipe may be empty.
The first character on every line of the recipe is elided.
The header line consists of at least one target followed by the rule separator
and a possibly empty list of prerequisites.
The rule separator is either a single
.LR : 
or is a 
.L :
immediately followed by attributes and another
.LR : .
If any prerequisite is more recent than any of the targets,
the recipe is executed.
This meaning is modified by the following attributes
.TP
.B <
The standard output of the recipe is read by
.I mk
as an additional mkfile.
Assignments take effect immediately.
Rule definitions are used when a new dependency dag is constructed.
.PD 0
.TP
.B D
If the recipe exits with an error status, the target is deleted.
.TP
.B N
If there is no recipe, the target has its time updated.
.TP
.B P
The characters after the
.B P
until the terminating
.B :
are taken as a program name.
It will be invoked as
.B "sh -c prog 'arg1' 'arg2'"
and should return 0 exit status
if and only if arg1 is not out of date with respect to arg2.
Date stamps are still propagated in the normal way.
.TP
.B Q
The recipe is not printed prior to execution.
.TP
.B R
The rule is a metarule using regular expressions.
.TP
.B U
The targets are considered to have been updated
even if the recipe did not do so.
.TP
.B V
The targets of this rule are marked as virtual.
They are distinct from files of the same name.
.PD
.PP
Similarly, assignments may have attributes terminated by
.BR = .
The only assignment attribute is
.TP 3
.B U
Do not export this variable to recipe executions.
.SH EXAMPLES
A simple mkfile to compile a program.
.IP
.EX
prog:	a.o b.o c.o
	$CC $CFLAGS -o $target $prereq
.EE
.PP
Override flag settings in the mkfile.
.IP
.EX
$ mk target CFLAGS='-O -s'
.EE
.PP
To get the prerequisites for an aggregate.
.IP
.EX
$ membername 'libc.a(read.o)' 'libc.a(write.o)'
read.o write.o
.EE
.PP
Maintain a library.
.IP
.EX
libc.a(%.o):N:	%.o
libc.a:	libc.a(abs.o) libc.a(access.o) libc.a(alarm.o) ...
	names=`membername $newprereq`
	ar r libc.a $names && rm $names
.EE
.PP
Backquotes used to derive a list from a master list.
.IP
.EX
NAMES=alloc arc bquote builtins expand main match mk var word
OBJ=`echo $NAMES|sed -e 's/[^ ][^ ]*/&.o/g'`
.EE
.PP
Regular expression metarules.
The single quotes are needed to protect the
.BR \e s.
.IP
.EX
\&'([^/]*)/(.*)\e.o':R:  '\e1/\e2.c'
	cd $stem1; $CC $CFLAGS -c $stem2.c
.EE
.PP
A correct way to deal with
.IR yacc (1)
grammars.
The file
.B lex.c
includes the file
.B x.tab.h
rather than
.B y.tab.h
in order to reflect changes in content, not just modification time.
.IP
.EX
YFLAGS=-d
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 $YFLAGS gram.y
.EE
.PP
The above example could also use the
.B P
attribute for the
.B x.tab.h
rule:
.IP
.EX
x.tab.h:Pcmp -s:	y.tab.h
	cp y.tab.h x.tab.h
.EE
.SH SEE ALSO
.IR make (1),
.IR chdate (1),
.IR sh (1),
.IR regexp (3)
.br
A. Hume,
.RI ` Mk :
a Successor to
.IR Make ',
this manual, Volume 2
.SH BUGS
Identical recipes for regular expression metarules only have one target.
.br
Seemingly appropriate input like
.B CFLAGS=-DHZ=60
is parsed as an erroneous attribute; correct it by inserting
a space after the first 
.LR = .