docs: Added UNIX V10 Manuals

1 files changed, 617 insertions, 0 deletions

diff --git a/static/v10/man1/mk.1 b/static/v10/man1/mk.1
new file mode 100644
index 00000000..9d0018c5
--- /dev/null
+++ b/static/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 = .