diff options
Diffstat (limited to 'static/v10/man1/usgmake.1')
| -rw-r--r-- | static/v10/man1/usgmake.1 | 700 |
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 |