docs: Added UNIX V10 Manuals

1 files changed, 700 insertions, 0 deletions

diff --git a/static/v10/man1/usgmake.1 b/static/v10/man1/usgmake.1
new file mode 100644
index 00000000..245a3cbb
--- /dev/null
+++ b/static/v10/man1/usgmake.1
@@ -0,0 +1,700 @@
+.TH USGMAKE 1
+.SH NAME
+usgmake \- maintain, update, and regenerate groups of programs
+.SH SYNOPSIS
+.B usgmake
+.RB
+[
+.I \-f " makefile
+]
+.I "
+.RB
+[
+.I \-p
+]
+.RB
+[
+.I \-i
+]
+.RB
+[
+.I \-k
+]
+.RB
+[
+.I \-s
+]
+.RB
+[
+.I \-r
+]
+.RB
+[
+.I \-n
+]
+.RB
+[
+.I \-b
+]
+.RB
+[
+.I \-e
+]
+.RB
+[
+.I \-m
+]
+.RB
+[
+.I \-t
+]
+.RB
+[
+.I \-d
+]
+.RB
+[
+.I \-q
+]
+[
+.I \|names\|
+]
+.SH DESCRIPTION
+The following is a brief description of all options and some special
+names:
+.TP "\w'\f3\-f\fP makefile\ \ 'u"
+.BI \-f " makefile\^"
+Description file name.
+.I Makefile\^
+is assumed to
+be the name of a description file.
+A file name of
+.B \-
+denotes the standard input.
+The contents of
+.I makefile\^
+override the built-in rules if they
+are present.
+.TP
+.B \-p
+Print out the complete set of macro definitions and target descriptions.
+.TP
+.B \-i
+Ignore error codes returned by invoked commands.
+This
+mode is entered if the fake target name
+.B \&.\s-1IGNORE\s+1
+appears in the description file.
+.TP
+.B \-k
+Abandon work on the current
+entry, but continue on other branches
+that do not depend on that entry.
+.TP
+.B \-s
+Silent mode.
+Do not print command lines before executing.
+This mode is also entered if the fake target name
+.B \&.\s-1SILENT\s+1
+appears in the description file.
+.TP
+.B \-r
+Do not use the built-in rules.
+.TP
+.B \-n
+No execute mode.
+Print commands, but do not execute
+them.
+Even lines beginning with an
+.B @
+are printed.
+.TP
+.B \-b
+Compatibility mode for old makefiles.
+.TP
+.B \-e
+Environment variables override assignments within makefiles.
+.TP
+.B \-m
+Print a memory map showing text, data, and stack.
+This option
+is a no-operation on systems without the \f2getu\^\fP system call.
+.TP
+.B \-t
+Touch the target files (causing them to be up-to-date)
+rather than issue the usual commands.
+.TP
+.B \-d
+Debug mode.
+Print out detailed information on files
+and times examined.
+.TP
+.B \-q
+Question.
+The \f2make\^\fP command returns a zero or non-zero
+status code depending on whether the target file is or
+is not up-to-date.
+.TP
+.B \&.\s-1DEFAULT\s+1
+If a file must be made but there are no explicit commands
+or relevant built-in rules, the commands associated
+with the name
+.B \&.\s-1DEFAULT\s+1
+are used if it exists.
+.TP
+.B \&.\s-1PRECIOUS\s+1
+Dependents of this target will not be removed when
+quit or interrupt are hit.
+.TP
+.B \&.\s-1SILENT\s+1
+Same effect as the \f3\-s\fP option.
+.TP
+.B \&.\s-1IGNORE\s+1
+Same effect as the \f3\-i\fP option.
+.PP
+.I Make\^
+executes commands in
+.I makefile\^
+to update
+one or more target
+.IR names .
+.I Name\^
+is typically a program.
+If no
+.B \-f
+option is present, \f3makefile\fP, \f3Makefile\fP, \f3s.makefile\fP,
+and \f3s.Makefile\fP are
+tried in order.
+If
+.I makefile\^
+is
+.BR \- ,
+the standard input is taken.
+More than one
+.BI \- " makefile"
+argument pair may appear.
+.PP
+.I Make\^
+updates a target only if it depends on files that are
+newer than the target.
+All prerequisite files of a target are added recursively to
+the list of targets.
+Missing files are deemed to be out of date.
+.PP
+.I Makefile\^
+contains a sequence of entries that specify dependencies.
+The first line of an entry is a
+blank-separated, non-null list of targets, then a
+.BR : ,
+then a (possibly null) list of prerequisite files or dependencies.
+Text following a
+.B ;
+and all following lines
+that begin with a tab are shell commands
+to be executed to update the target.
+The first line that does not begin with a tab or
+.B #
+begins
+a new dependency or macro definition.
+Shell commands may
+be continued across lines with the <backslash><new-line> sequence.
+Everything printed by make (except the initial tab) is passed
+directly to the shell as is.
+Thus,
+.PP
+.ss 18
+.RS
+.PD 0
+echo a\\
+.br
+b
+.RE
+.ss 12
+.PD
+.PP
+will produce
+.PP
+.ss 18
+.RS
+.PD 0
+ab
+.RE
+.ss 12
+.PD
+.PP
+exactly the same as the shell would.
+.PP
+Sharp
+.RB ( # )
+and new-line surround comments.
+.PP
+The following
+.I makefile\^
+says that
+.B pgm
+depends on two
+files
+.B a.o
+and
+.BR b.o ,
+and that they in turn depend on
+their corresponding source files
+.RB ( a.c
+and
+.BR b.c )
+and a common file
+.BR incl.h :
+.PP
+.ss 18
+.RS
+.PD 0
+.TP
+pgm: a.o b.o
+cc a.o b.o \-o pgm
+.TP
+a.o: incl.h a.c
+cc \-c a.c
+.TP
+b.o: incl.h b.c
+cc \-c b.c
+.PD
+.RE
+.ss 12
+.PP
+Command lines are executed one at a time, each by its
+own shell.
+The first one or two characters in a command can be
+the following: \f3-\fP, \f3@\fP, \f3-@\fP, or \f3@-\fP.
+If \f3@\fP is present, printing of the command is suppressed.
+If \f3-\fP is present, \f2make\^\fP ignores an error.
+A line is printed when it is executed unless the
+.B \-s
+option is present, or the entry
+.B \&.\s-1SILENT\s+1:
+is in
+.IR makefile ,
+or unless the initial character sequence contains a \f3@\fP.
+The
+.B \-n
+option specifies printing without execution; however, if the
+command line has the string
+.B $(\s-1MAKE\s+1)
+in it,
+the line is
+always executed (see discussion of the
+.SM
+.B MAKEFLAGS
+macro under
+.IR Environment ).
+The
+.B \-t
+(touch) option updates the modified date of a
+file without executing any commands.
+.PP
+Commands returning non-zero status normally terminate
+.IR make .
+If the
+.B \-i
+option is present, or the entry \f3.\s-1IGNORE\s+1:\fP appears in
+.IR makefile ,
+or the initial character sequence of the command contains
+\f3-\fP.
+the error is ignored.
+If the
+.B \-k
+option is present,
+work is abandoned on the current
+entry, but continues on other branches
+that do not depend on that entry.
+.PP
+The
+.B \-b
+option allows old makefiles (those written for the old version
+of \f2make\^\fP) to run without errors.
+The difference between the old version
+of \f2make\^\fP and this version is that this version requires all dependency
+lines to have a (possibly null or implicit) command associated with them.
+The previous version of
+.I make\^
+assumed if no command was specified explicitly
+that the command was null.
+.PP
+Interrupt and quit cause the target to be deleted
+unless the target is a dependency of the special name \f3.\s-1PRECIOUS\s+1\fP.
+.SS Environment
+The environment is read by \f2make\^\fP.
+All variables are assumed to be macro
+definitions and processed as such.
+The environment variables are processed
+before any makefile and after the internal rules;
+thus, macro assignments
+in a makefile override environment variables.
+The
+.B \-e
+option causes
+the environment to override the macro assignments in a makefile.
+.PP
+The \f3\s-1MAKEFLAGS\s+1\fP environment variable
+is processed by \f2make\^\fP as containing
+any legal input option (except \f3\-f\fP, \f3\-p\fP, and \f3\-d\fP) defined
+for the command line.
+Further,
+upon invocation, \f2make\^\fP ``invents'' the variable if it is not in the
+environment, puts the current options into it, and passes it on to
+invocations of commands.
+Thus, \f3\s-1MAKEFLAGS\s+1\fP always contains the
+current input options.
+This proves very useful for ``super-makes''.
+In fact, as noted above,
+when the \f3\-n\fP option is used, the command
+.B $(\s-1MAKE\s+1)
+is executed
+anyway; hence, one can perform a \f3make \-n\fP recursively on a whole software
+system to see what would have been executed.
+This is because the \f3\-n\fP
+is put in \f3\s-1MAKEFLAGS\s+1\fP and passed to further invocations of
+.BR $(\s-1MAKE\s+1) .
+This is one way of debugging
+all of the makefiles for a software project without actually doing anything.
+.PP
+.SS Macros
+Entries of the form
+.IB string1 " = " string2\^
+are macro definitions.
+.I String2
+is defined as all characters up to a comment character or
+an unescaped newline.
+Subsequent appearances of
+.RI $( string1 [: subst1 =[ subst2\^\fP]])
+are replaced by
+.IR string2 .
+The parentheses are optional if a single character macro name is used and
+there is no substitute sequence.
+The optional
+.RI : subst1 = subst2\^
+is a substitute sequence.
+If it is specified, all non-overlapping occurrences of \f2subst1\^\fP in the
+named macro are replaced by \f2subst2\^\fP.
+Strings (for the purposes of this
+type of substitution) are delimited by
+blanks, tabs, new-line characters, and beginnings of lines.
+An example of the use of the substitute sequence is shown under
+.IR Libraries .
+.SS Internal Macros
+There are five internally maintained macros which are useful
+for writing rules for building targets.
+.TP 5
+\f3$\(**\fP
+The macro \f3$\(**\fP stands for
+the file name part of the current dependent with the suffix deleted.
+It is
+evaluated only for inference rules.
+.TP
+\f3$@\fP
+The \f3$@\fP macro stands for
+the full target name of the current target.
+It is evaluated
+only for explicitly named dependencies.
+.TP
+\f3$<\fP
+The \f3$<\fP macro is only evaluated for inference rules or
+the \f3.\s-1DEFAULT\s+1\fP rule.
+It is
+the module which is out of date with respect to the target (i.e.,
+the ``manufactured'' dependent file name).
+Thus, in the \f3.c.o\fP rule, the \f3$<\fP macro would evaluate to
+the \f3.c\fP file.
+An example for making
+optimized \f3.o\fP files from \f3.c\fP files is:
+.PP
+.PD 0
+.ss 18
+.RS
+.RS
+.TP
+\&.c.o:
+.br
+cc \-c \-O $\(**.c
+.RE
+.RE
+.PD
+.TP 5
+\&
+or:
+.PP
+.PD 0
+.RS
+.RS
+.TP
+\&.c.o:
+.br
+cc \-c \-O $<
+.RE
+.RE
+.ss 12
+.PD
+.TP 5
+\f3$?\fP
+The \f3$?\fP macro is evaluated when explicit rules from the makefile
+are evaluated.
+It is
+the list of prerequisites that are out of date with respect to
+the target;
+essentially, those modules which must be rebuilt.
+.TP
+\f3$%\fP
+The \f3$%\fP macro is only evaluated when the target is an
+archive library member of the form \f3lib(file.o)\fP.
+In this case,
+\f3$@\fP evaluates to \f3lib\fP and \f3$%\fP evaluates to the
+library member, \f3file.o\fP.
+.PP
+Four of the five macros can have alternative forms.
+When an upper case \f3D\fP or \f3F\fP is appended to any of the four
+macros the meaning is changed to ``directory part'' for \f3D\fP
+and ``file part'' for \f3F\fP.
+Thus, \f3$(@D)\fP refers to the directory
+part of the string \f3$@\fP.
+If there is no directory part,
+\f3./\fP is generated.
+The only macro excluded from this
+alternative form is \f3$?\fP.
+The reasons for this are debatable.
+.SS Suffixes
+Certain names (for instance, those ending with \f3.o\fP)
+have inferable prerequisites such as \f3.c\fP, \f3.s\fP, etc.
+If no update commands for such a file appear in
+.IR makefile ,
+and if an inferable prerequisite
+exists, that prerequisite is compiled to make the target.
+In this case,
+.I make\^
+has
+inference rules
+which allow building files from other files
+by examining the suffixes and determining an
+appropriate
+inference rule
+to use.
+The current default inference rules
+are:
+.PP
+.RS
+\&.c \|.c~ \|.sh \|.sh~ \|.c.o \|.c~.o \|.c~.c \|.s.o \|.s~.o \|.y.o \|.y~.o \|.l.o \|.l~.o
+.br
+\&.y.c \|.y~.c \|.l.c \|.c.a \|.c~.a \|.s~.a \|.h~.h
+.RE
+.PP
+The internal rules for \f2make\^\fP are contained in the source
+file \f3rules.c\fP for the \f2make\^\fP program.
+These rules can be
+locally modified.
+To print out the rules compiled into
+the \f2make\^\fP on any machine in a form suitable for recompilation,
+the following command is used:
+.PP
+.RS
+make \|\-fp \|\- \|2>/dev/null \|</dev/null
+.RE
+.PP
+The only peculiarity in this output is the
+.B (null)
+string which
+.IR printf (3S)
+prints when handed a null string.
+.PP
+A tilde in the above rules refers to an \s-1SCCS\s+1 file
+(see
+.IR sccsfile (5)).
+Thus, the
+rule \f3.c~.o\fP would transform an \s-1SCCS\s+1 C source file into an
+object file (\f3.o\fP).
+Because the \f3s.\fP of the \s-1SCCS\s+1 files is a prefix
+it is incompatible with \f2make\^\fP's suffix point-of-view.
+Hence,
+the tilde is a way of changing any file reference into an \s-1SCCS\s+1
+file reference.
+.PP
+A rule with only one suffix (i.e. \f3.c:\fP) is the definition
+of how to build \f2x\^\fP from \f2x\^\fP\f3.c\fP.
+In effect, the other suffix is null.
+This is useful for building targets
+from only one source file (e.g., shell procedures, simple C programs).
+.PP
+Additional suffixes are given as the
+dependency list for \f3.\s-1SUFFIXES\s+1\fP.
+Order is significant; the first possible name for which both
+a file and a rule exist is inferred as a prerequisite.
+The default list is:
+.PP
+.RS
+\&\f3.\s-1SUFFIXES\s+1\fP: \|.o \|.c \|.y \|.l \|.s
+.RE
+.PP
+Here again, the above command for printing the internal rules will
+display the list of suffixes implemented on the current machine.
+Multiple suffix lists accumulate; \f3.\s-1SUFFIXES\s+1:\fP with no dependencies
+clears the list of suffixes.
+.SS Inference Rules
+The first example can be done more briefly:
+.PP
+.ss 18
+.RS
+.PD 0
+.TP
+pgm: a.o b.o
+.br
+cc a.o b.o \-o pgm
+.TP
+a.o b.o: incl.h
+.RE
+.ss 12
+.PD
+.PP
+This is because \f2make\^\fP has a set of internal rules for building
+files.
+The user may add rules to this list by simply putting
+them in the \f2makefile\^\fP.
+.PP
+Certain macros are used by the default inference rules
+to permit the inclusion of optional matter in
+any resulting commands.
+For example,
+.SM
+.BR CFLAGS\*S ,
+.SM
+.BR LFLAGS\*S ,
+and
+.SM
+.B YFLAGS
+are used for compiler options to
+.IR cc (1),
+.IR lex (1),
+and
+.IR yacc (1)
+respectively.
+Again, the previous method for examining
+the current rules is recommended.
+.PP
+The inference of prerequisites can be controlled.
+The rule to create a file with suffix
+.B \&.o
+from a file with suffix
+.B \&.c
+is specified as an entry with \f3.c.o:\fP as the target and no dependents.
+Shell commands associated with the target define the
+rule for making a \f3.o\fP file from a \f3.c\fP file.
+Any target that has no slashes in it and starts with a dot
+is identified as a rule and not a true target.
+.SS Libraries
+If a target or dependency name contains parenthesis, it is
+assumed to be an archive library, the string within parenthesis
+referring to a member within the library.
+Thus \f3lib(file.o)\fP and \f3$(\s-1LIB\s+1)(file.o)\fP both refer to
+an archive library which contains \f3file.o\fP. (This assumes
+the
+.SM
+.B LIB
+macro has been previously defined.)\ 
+The expression \f3$(\s-1LIB\s+1)(file1.o file2.o)\fP is not legal.
+Rules pertaining to archive libraries have the form
+.BI \&. \s-1XX\s+1 .a
+where the
+.SM
+.I XX\^
+is the suffix from which the archive member
+is to be made.
+An unfortunate byproduct of the current implementation
+requires the
+.SM
+.I XX\^
+to be different from the suffix of the archive
+member.
+Thus, one cannot have \f3lib(file.o)\fP depend upon \f3file.o\fP explicitly.
+The most common use of the archive interface follows.
+Here, we assume the source files are all C type source:
+.PP
+.ss 18
+.RS
+.PD 0
+.TP
+lib:
+lib(file1.o) lib(file2.o) lib(file3.o)
+.br
+@echo lib is now up to date
+.TP
+\&.c.a:
+.br
+$(\s-1CC\s+1) \-c $(\s-1CFLAGS\s+1) $<
+.br
+ar rv $@ $*.o
+.br
+rm \-f $*.o
+.RE
+.ss 12
+.PD
+.PP
+In fact, the \f3.c.a\fP rule listed above is built into \f2make\^\fP and
+is unnecessary in this example.
+A more interesting, but more limited example of an archive library
+maintenance construction follows:
+.PP
+.ss 18
+.RS
+.PD 0
+.TP
+lib:
+lib(file1.o) lib(file2.o) lib(file3.o)
+.br
+$(\s-1CC\s+1) \-c $(\s-1CFLAGS\s+1) $(?:.o=.c)
+.br
+ar rv lib $?
+.br
+rm $?
+@echo lib is now up to date
+.TP
+\&.c.a:;
+.RE
+.ss 12
+.PD
+.PP
+Here the substitution mode of the macro expansions is used.
+The \f3$?\fP
+list is defined to be the set of object file names (inside \f3lib\fP) whose C
+source files are out of date.
+The substitution mode
+translates the \f3.o\fP to \f3.c\fP.
+(Unfortunately, one cannot as yet transform
+to \f3.c~\fP; however, this may become possible in the future.)\ 
+Note also, the disabling of the
+\&\f3.c.a:\fP rule, which would have created each object file, one by one.
+This particular construct speeds up archive library maintenance considerably.
+This type of construct becomes very cumbersome if the archive library
+contains a mix of assembly programs and C programs.
+.SH FILES
+[Mm]akefile and s\f3.\fP[Mm]akefile
+.SH SEE ALSO
+.IR sh (1),
+.IR mk (8).
+.br
+.I "Make\-A Program for Maintaining Computer Programs\^"
+by
+S. I. Feldman.
+.br
+.I "An Augmented Version of Make\^"
+by
+E. G. Bradford.
+.SH BUGS
+Some commands return non-zero status inappropriately;
+use
+.B \-i
+to overcome the difficulty.
+Commands that are directly executed by the shell,
+notably
+.IR cd (1),
+are ineffectual across new-lines in
+.IR make .
+The syntax \f3(lib(file1.o file2.o file3.o)\fP is illegal.
+You cannot build \f3lib(file.o)\fP from \f3file.o\fP.
+The macro \f3$(a:.o=.c~)\fP doesn't work.
+.br