awp8101@ritcv.UUCP (Andrew W. Potter) (02/09/88)
$Part2:
$ File_is="MAKE.RNH"
$ Check_Sum_is=813587540
$ Copy SYS$Input VMS_SHAR_DUMMY.DUMMY
X.!
X.! MAKE version 1.1, April 1987
X.! Copyright (C) 1987 by Jesse Perry.
X.! MAKE is in the public domain and may be freely distributed,
X.! used, and modified, provided this notice is not removed.
X.!
X.! make.rnh
X.! This is the source of the HELP library entry for MAKE.
X.! Use RUNOFF on this file to create MAKE.HLP .
X.!
X.sp 1
X.rm 70
X.lm 0
X1 MAKE
X.lm 1
XMAKE is a command which automates the process of keeping
Xprograms up to date. MAKE reads a makefile which specifies
Xhow the various component files of a program are to be combined.
XIt determines which files are out of date and executes commands
Xfrom the makefile to update them. The file MAKE$DOCUMENT is a
Xtutorial introduction to MAKE.
X.b 1
X.lm 4
X.rm 67
XIf any of this help information seems unclear or incomplete,
Xor if you find any errors or deficiencies in the MAKE program,
Xplease send mail describing the problem to MAKE__MAINT.
X.rm 70
X.lm 0
X2 Makefile
X.lm 1
XA makefile contains statements describing how files are related and
Xhow to update files which are out of date. Three kinds of statements
Xare possible; macro definitions, dependency statements, and default
Xrule statements. Every make statement must begin at the start of a
Xline. Indented lines are assumed to be DCL command lines. They must
Xbe part of either a dependency or default rule statement. Long lines
Xcan be continued by placing a '_\' at the end of a line. The '_\'
Xand subsequent carriage return are ignored. This is similar to the
Xuse of '-' in DCL.
X.lm 0
X3 Comment
X.lm 1
XA '_#' character begins a makefile comment. All text from the '_#'
Xto the end of the line is ignored. For example,
X.b 1
X.nf
X_# This is a comment.
X_# How to create prog.exe ....
Xprog.exe : $*.obj _# $* here means "prog"
X.lm 9
Xlink $?, mylib/lib _# $? here means "prog.obj"
X.f
X.b 1
X.lm 1
XComment lines cannot be continued using '_\'.
X.lm 0
X3 Dependency
X.lm 1
XA dependency statement consists of one or more target names, followed by
Xa ':', followed by any number of prerequisite names on one line. Following
Xthis line are any number of DCL command lines, each of which must be
Xindented at least one space or tab. The initial target/prerequisite
Xline must not be indented. For example,
X.b 1
Xtest.exe : test.obj testfunc.obj
X.lm 9
Xlink test.obj, testfunc.obj
X.lm 1
X.b 1
XIn this example TEST.EXE is the target, TEST.OBJ and TESTFUNC.OBJ are
Xthe prerequisites, and "LINK TEST.OBJ, TESTFUNC.OBJ" is the only
Xcommand line.
X.lm 0
X3 Dep__macro
X.lm 1
XDependency macros provide a notation to refer to the parts of a dependency
Xor default rule statement. Three dependency macros are automatically defined
Xwithin each dependency statement. Each is identified by a single punctuation
Xcharacter. The name of the current target is given by the macro '@'.
XThe name of the current target with its file type (.FOR, .OBJ, etc.)
Xremoved is given by '*'. The list of prerequisites of the current target
Xis given by '?'. Each dependency macro is invoked by a '$' followed by
Xthe single character "name" of the macro.
X.lm 0
X3 Def__rule
X.lm 1
XA default rule tells MAKE how to create one kind of file from another.
XWhen MAKE needs to update a target which is not explicitly described
Xin the makefile, it tries to find and use a matching default rule.
XA rule matches if 1) its output file type is the same as that of the
Xtarget file, and 2) a file exists which has the same file type as the
Xinput type of the rule, and the same simple name as the simple name of
Xthe target file.
X.lm 0
X4 Syntax
X.lm 1
XA default rule has the form of a dependency statement with one
Xtarget and (typically) no prerequisites. If a default rule has any
Xprerequisites, this means that by default every file of the output
Xfile type depends on those prerequisites. The target name is the
Xconcatenation of the input and output file types. For example, the
XFORTRAN command is used to create a .OBJ output file from a .FOR
Xinput file. A default rule specifying this is,
X.b 1
X.nf
X_.for.obj :
X.lm 9
Xfortran $*
X.f
X.lm 0
X4 Rule__file
X.lm 1
XMAKE reads a list of commonly used default rules from the default rule file.
XRules defined in the makefile take precedence over those defined in the
Xdefault rule file, and rules given on the command line (using /DEFINE)
Xtake precedence over both.
X.lm 0
X3 Make__char
X.lm 1
XA number of characters have special meanings in a makefile. These are,
X.sp 2
X.lm 3
X.nf
Xo '_#' -- begins a comment
Xo ':' -- ends a list of target names
Xo '-' -- at start of command line, tells MAKE to ignore command
X.lm 12
X.sp 1
Xexecution errors
X.sp 2
X.lm 3
Xo '@' -- at start of command line, suppresses printing of that line
Xo '=' -- named macro definition character
Xo '$' -- macro invocation character
Xo '_\' -- at end of line, tells MAKE to continue current line
X.sp 1
X.f
X.lm 1
X.b 1
XIf you want to use one of these characters without its special meaning,
Xyou must precede it with '_\' in the makefile. The most common reasons
Xfor this are,
X.sp 2
X.nf
X.lm 3
Xo Using ':' in a file name, as in "user4_\:[abc1234]file.for"
Xo Using '$' in a command line or file name, as in "sys_\$output"
Xo Using '@' to execute a DCL command file, as in "_\@login.com"
X.f
X.sp 1
X.lm 0
X3 Name__macro
X.lm 1
XA named macro definition consists of a name, followed by '=', followed
Xby the text of the macro definition. Named macros are helpful when the
Xsame text is used several times. For example,
X.b 1
X.nf
XOBJS = main.obj routine1.obj routine2.obj
Xmain.exe : $(OBJS)
X.lm 9
Xlink $,(OBJS)
X.f
X.lm 0
X4 Expansion__rules
X.lm 1
XA macro is used (invoked) by a '$' followed by the macro name in
Xparentheses. When MAKE reads a macro invocation in the makefile,
Xit expands the macro -- it replaces the invocation with the words
Xin the macro definition. If any text is appended to the close
Xparenthesis, that text is appended to each word in the expansion
Xof the macro. If any single character is placed between the initial
X'$' and the open parenthesis, that character is used as a separator
Xfor the words in the macro expansion.
X.lm 0
X4 Examples
X.lm 1
XSuppose these macro definitions are given,
X.b 1
X.nf
XDISK = user
XDIRECTORY = [zzz]
XMODULES = main io calc
X.f
X.b 1
XThe following examples show how MAKE would expand various invocations of
Xthese macros when it reads the makefile. The arrow ("--->") can be read
Xas "is expanded into".
X.sp 2
X.lm 4
X.nf
X$(MODULES) ---> main io calc
X$(MODULES), ---> main, io, calc,
X$,(MODULES) ---> main, io, calc
X$(MODULES).obj ---> main.obj io.obj calc.obj
X$(MODULES).obj, ---> main.obj, io.obj, calc.obj,
X$,(MODULES).obj ---> main.obj, io.obj, calc.obj
X$(DISK)_\:$(DIRECTORY) ---> user:[zzz]
X$(DISK)_\:$(DIRECTORY)$,(MODULES).obj --->
X.sp 1
X.lm 7
Xuser:[zzz]main.obj, user:[zzz]io.obj, user:[zzz]calc.obj
X.lm 1
X.f
X.b 1
XSeveral things in the above examples deserve attention. First, notice
Xthe difference between using ',' as a separator character, as in the
Xthird example, and simply appending a comma to the macro invocation,
Xas in the second example. Also, the ':' in the examples using $(DISK) is
Xpreceded by a '_\', because ':' is a special character to MAKE.
XLastly, notice that several macro invocations can be concatenated
Xtogether. The rules for such concatenation are that all the macros
Xused which have definitions containing more than one word must all
Xhave the same number of words. Macros with one word (or no word)
Xdefinitions may always be used in a concatenation. In the last
Xexample, the definition of MODULES has three words, while the
Xdefinitions of DISK and DIRECTORY both have one word.
X.b 1
XAs a final example of the use of make macros, consider,
X.b 1
X.nf
XSAY = @ write sys_\$output
Xneeded__progs: lab1.exe lab2.exe lab3.exe
X.lm 9
X$(SAY) "******* The labs are all up do date *******"
X.lm 1
X.f
X.b 1
XThe SAY macro causes the message which follows it to be printed. The initial
X'@' sign prevents the command line itself from being printed. As with
Xthe use of ':' in a file name, the '$' in "sys$output" is preceded by
X'_\' because '$' is a special character to MAKE.
X.lm 0
X2 Logical
X.lm 1
XMAKE reads a makefile whose name is given by the logical name MAKE$DEFNAME,
Xand a default rule file whose name is given by MAKE$DEFRULE. The /RULE
Xand /MAKEFILE qualifiers can be used to specify different files, or to
Xprevent MAKE from using any makefile or default rule file.
X.lm 0
X2 Parameter
X.lm 1
XThe only parameter to MAKE is the name of a particular target to
Xupdate. Several targets can be given in a comma-separated
Xlist. For example,
X.b 1
X.c
X$ MAKE LAB1.EXE, LAB2
X.b 1
Xwould tell MAKE to update both LAB1.EXE and LAB2.EXE, in that order.
XNotice that if no file type is given (and the name is not defined in
Xthe makefile) then the default file type .EXE is used.
X.b 1
XIf no parameter is given on the command line, MAKE updates the
Xfirst target name it finds in the makefile.
X.lm 0
X2 /ACTIVE
X.lm 1
X.nf
X/ACTIVE
X/NOACTIVE
X.f
X.b 1
XThis qualifier determines whether MAKE actually executes the DCL command
Xlines in the makefile. The default is /ACTIVE, which means that MAKE will
Xexecute makefile commands. If /NOACTIVE is specified, MAKE prints each
Xcommand line, but does not execute it. This is useful if you wish to
Xfind out what MAKE would do to update a target, without actually having
Xthe update done.
X.lm 0
X2 /BUILD
X.lm 1
X/BUILD[=FILE]
X.b 1
XThis qualifier causes MAKE to create a DCL command (.COM) file containing
Xall the command lines from the makefile which are necessary to create or
Xupdate the target(s) specified. If FILE is not given, the default name
XINSTALL.COM is used.
X.lm 0
X2 /DEFINE
X.lm 1
X/DEFINE=LIST
X.b 1
XMAKE treats the statements in LIST as though they were at the top
Xof the makefile. The most common use of /DEFINE is to specify a
Xnew definition for a make macro, which overrides the definition
Xgiven in the makefile. For example,
X.b 1
X.c
X$ MAKE/DEFINE=("FOR__QUAL=/DEBUG/NOOPT","LINK__QUAL=/DEBUG")
X.b 1
Xwould create definitions of the FOR__QUAL and LINK__QUAL macros
Xwhich would override any definitions given in the makefile or
Xin the default rules file.
X.lm 0
X2 /IGNORE
X.lm 1
X.nf
X/IGNORE
X/NOIGNORE
X.f
X.b 1
XThe /IGNORE qualifier tells MAKE not to abort if any DCL command
Xwhich it executes signals an error. The default is
X/NOIGNORE, which means that if any DCL command signals an
Xerror when executed, MAKE will exit. This default can be
Xturned off for any particular command line by placing a '-'
Xat the start of that command line in the makefile.
X.b 1
X/IGNORE is like the DCL command "$ ON SEVERE__ERROR THEN CONTINUE",
Xwhile /NOIGNORE is analogous to "$ ON WARNING THEN EXIT".
X.lm 0
X2 /MAKEFILE
X.lm 1
X.nf
X/MAKEFILE[=FILE]
X/NOMAKEFILE
X.f
X.b 1
XA makefile other than the default can be used by giving the /MAKEFILE=FILE
Xqualifier, where FILE is the name of the alternate makefile to use. By
Xdefault, MAKE reads the makefile whose name is given by the logical name
XMAKE$DEFNAME. The /NOMAKEFILE qualifier prevents MAKE from using any
Xmakefile. It then relies entirely on its default rules.
X.lm 0
X2 /PRINT
X.lm 1
X.nf
X/PRINT
X/NOPRINT
X.f
X.b 1
XThe /PRINT qualifier causes MAKE to print all macro definitions and
Xall target and default rule statements before it performs any file updates.
XThe default is /NOPRINT.
X.lm 0
X2 /REVISED
X.lm 1
XThis qualifier tells MAKE to use the file revision date in deciding
Xwhether one file is up to date with respect to another. By default,
XMAKE uses the file creation date.
X.lm 0
X2 /RULE
X.lm 1
X.nf
X/RULE[=FILE]
X/NORULE
X.f
X.b 1
XAn alternate default rule file can be used by giving the /RULE=FILE
Xqualifier, where FILE is the name of the alternate rule file to use.
Xdefault, MAKE reads the rule file whose name is given by the logical
Xname MAKE$DEFRULE. The /NORULE qualifier prevents MAKE from using any
Xdefault rule file. It will then rely entirely on the makefile.
X.lm 0
X2 /SILENT
X.lm 1
X.nf
X/SILENT
X/NOSILENT
X.f
X.b 1
XThe /SILENT qualifier suppresses the automatic printing of
Xeach DCL command line before it is executed. The default is
X/NOSILENT, which causes MAKE to print every command line
Xbefore executing it. Printing of any particular command
Xline is suppressed if the line is preceded by '@' in the makefile.
X.b 1
X/SILENT is analogous to the DCL command "$ SET NOVERIFY".
X.lm 0
X2 /TOUCH
X.lm 1
X.c
X** /TOUCH IS UNIMPLEMENTED. **
XThe /TOUCH qualifier prevents MAKE from executing any DCL
Xcommands. Instead, if a file is out of date MAKE simply
Xchanges its modify time to the current time, so that it
Xappears to be up to date.
X.b 1
XThis qualifier is useful when an include file has been
Xmodified in such a way as to affect only one or two of the
Xsource files which use it. /TOUCH causes MAKE to "touch"
Xall the object files so that they appear up to date. The few
Xwhich actually are not are then deleted, so that an ordinary
Xmake will re-create them. This avoids needless re-compilation
Xof every file which uses the modified include file.
X.b 1
X_*_* Care is required when using /TOUCH, as it directly subverts
Xthe intention and usual operation of MAKE. _*_*
X.lm 0
X2 /VERBOSE
X.lm 1
X.nf
X/VERBOSE
X/NOVERBOSE
X.f
X.b 1
XThis qualifier causes MAKE to print a detailed description of
Xwhat files it examines and what their modification dates are.
XThis is mainly useful for debugging purposes, as the output
Xgenerated is very VERBOSE. The default is /NOVERBOSE.
$ GoSub Convert_File
$ Goto Part3