diff options
Diffstat (limited to 'static/unix-v10/man1/mk.1')
| -rw-r--r-- | static/unix-v10/man1/mk.1 | 617 |
1 files changed, 617 insertions, 0 deletions
diff --git a/static/unix-v10/man1/mk.1 b/static/unix-v10/man1/mk.1 new file mode 100644 index 00000000..9d0018c5 --- /dev/null +++ b/static/unix-v10/man1/mk.1 @@ -0,0 +1,617 @@ +.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 = . |