.!
.! MAKE version 1.1, April 1987
.! Copyright (C) 1987 by Jesse Perry.
.! MAKE is in the public domain and may be freely distributed,
.! used, and modified, provided this notice is not removed.
.!
.! make.rnh
.! This is the source of the HELP library entry for MAKE.
.! Use RUNOFF on this file to create MAKE.HLP .
.!
.sp 1
.rm 70
.lm 0
1 Make
.lm 1
MAKE is a command which automates the process of keeping
programs up to date.  MAKE reads a makefile which specifies
how the various component files of a program are to be combined.
It determines which files are out of date and executes commands
from the makefile to update them.  The file MAKE$DOCUMENT is a
tutorial introduction to MAKE.
.b 1
.lm 4
.rm 67
If any of this help information seems unclear or incomplete,
or if you find any errors or deficiencies in the MAKE program,
please send mail describing the problem to MAKE__MAINT.
.rm 70
.lm 0
2 Makefile
.lm 1
A makefile contains statements describing how files are related and
how to update files which are out of date.  Three kinds of statements
are possible; macro definitions, dependency statements, and default
rule statements.  Every make statement must begin at the start of a
line.  Indented lines are assumed to be DCL command lines.  They must
be part of either a dependency or default rule statement.  Long lines
can be continued by placing a '_\' at the end of a line.  The '_\'
and subsequent carriage return are ignored.  This is similar to the
use of '-' in DCL.
.lm 0
3 Comment
.lm 1
A '_#' character begins a makefile comment.  All text from the '_#'
to the end of the line is ignored.  For example,
.b 1
.nf
_# This is a comment.
_# How to create prog.exe ....
prog.exe : $*.obj              _# $* here means "prog"
.lm 9
link $?, mylib/lib     _# $? here means "prog.obj"
.f
.b 1
.lm 1
Comment lines cannot be continued using '_\'.
.lm 0
3 Dependency
.lm 1
A dependency statement consists of one or more target names, followed by
a ':', followed by any number of prerequisite names on one line.  Following
this line are any number of DCL command lines, each of which must be
indented at least one space or tab.  The initial target/prerequisite
line must not be indented.  For example,
.b 1
test.exe : test.obj testfunc.obj
.lm 9
link test.obj, testfunc.obj
.lm 1
.b 1
In this example TEST.EXE is the target, TEST.OBJ and TESTFUNC.OBJ are
the prerequisites, and "LINK TEST.OBJ, TESTFUNC.OBJ" is the only
command line.
.lm 0
3 Dep__macro
.lm 1
Dependency macros provide a notation to refer to the parts of a dependency
or default rule statement.  Four dependency macros are automatically defined
within each dependency statement.  Each is identified by a single punctuation
character.  The name of the current target is given by the macro '@'.
The  target  file-name can be found by using '%' (ie. no path or type).
The name of the current target with its file type (.FOR, .OBJ, etc.)
removed is given by '*'.  The list of prerequisites of the current target
is given by '?'.  Each dependency macro is invoked by a '$' followed by
the single character "name" of the macro.
.lm 0
3 Def__rule
.lm 1
A default rule tells MAKE how to create one kind of file from another.
When MAKE needs to update a target which is not explicitly described
in the makefile, it tries to find and use a matching default rule.
A rule matches if 1) its output file type is the same as that of the
target file, and 2) a file exists which has the same file type as the
input type of the rule, and the same simple name as the simple name of
the target file.
.lm 0
4 Syntax
.lm 1
A default rule has the form of a dependency statement with one
target and (typically) no prerequisites.  If a default rule has any
prerequisites, this means that by default every file of the output
file type depends on those prerequisites.  The target name is the
concatenation of the input and output file types.  For example, the
FORTRAN command is used to create a .OBJ output file from a .FOR
input file.  A default rule specifying this is,
.b 1
.nf
_.for.obj :
.lm 9
fortran $*
.f
.lm 0
4 Rule__file
.lm 1
MAKE reads a list of commonly used default rules from the default rule file.
Rules defined in the makefile take precedence over those defined in the
default rule file, and rules given on the command line (using /DEFINE)
take precedence over both.
.lm 0
3 Make__char
.lm 1
A number of characters have special meanings in a makefile.  These are,
.sp 2
.lm 3
.nf
o '_#' -- begins a comment
o ':' -- ends a list of target names
o '-' -- at start of command line, tells MAKE to ignore command
.lm 12
.sp 1
execution errors
.sp 2
.lm 3
o '@' -- at start of command line, suppresses printing of that line
o '=' -- named macro definition character
o '$' -- macro invocation character
o '_\' -- at end of line, tells MAKE to continue current line
.sp 1
.f
.lm 1
.b 1
If you want to use one of these characters without its special meaning,
you must precede it with '_\' in the makefile.  The most common reasons
for this are,
.sp 2
.nf
.lm 3
o Using ':' in a file name, as in "user4_\:[abc1234]file.for"
o Using '$' in a command line or file name, as in "sys_\$output"
o Using '@' to execute a DCL command file, as in "_\@login.com"
.f
.sp 1
.lm 0
3 Name__macro
.lm 1
A named macro definition consists of a name, followed by '=', followed
by the text of the macro definition.  Named macros are helpful when the
same text is used several times.  For example,
.b 1
.nf
OBJS = main.obj routine1.obj routine2.obj
main.exe : $(OBJS)
.lm 9
link $,(OBJS)
.f
.lm 0
4 Expansion__rules
.lm 1
A macro is used (invoked) by a '$' followed by the macro name in
parentheses.  When MAKE reads a macro invocation in the makefile,
it expands the macro -- it replaces the invocation with the words
in the macro definition.  If any text is appended to the close
parenthesis, that text is appended to each word in the expansion
of the macro.  If any single character is placed between the initial
'$' and the open parenthesis, that character is used as a separator
for the words in the macro expansion.
.lm 0
4 Examples
.lm 1
Suppose these macro definitions are given,
.b 1
.nf
DISK = user
DIRECTORY = [zzz]
MODULES = main io calc
.f
.b 1
The following examples show how MAKE would expand various invocations of
these macros when it reads the makefile.  The arrow ("--->") can be read
as "is expanded into".
.sp 2
.lm 4
.nf
$(MODULES) ---> main io calc
$(MODULES), ---> main, io, calc,
$,(MODULES) ---> main, io, calc
$(MODULES).obj ---> main.obj io.obj calc.obj
$(MODULES).obj, ---> main.obj, io.obj, calc.obj,
$,(MODULES).obj ---> main.obj, io.obj, calc.obj
$(DISK)_\:$(DIRECTORY) ---> user:[zzz]
$(DISK)_\:$(DIRECTORY)$,(MODULES).obj --->
.sp 1
.lm 7
user:[zzz]main.obj, user:[zzz]io.obj, user:[zzz]calc.obj
.lm 1
.f
.b 1
Several things in the above examples deserve attention.  First, notice
the difference between using ',' as a separator character, as in the
third example, and simply appending a comma to the macro invocation,
as in the second example.  Also, the ':' in the examples using $(DISK) is
preceded by a '_\', because ':' is a special character to MAKE.
Lastly, notice that several macro invocations can be concatenated
together.  The rules for such concatenation are that all the macros
used which have definitions containing more than one word must all
have the same number of words.  Macros with one word (or no word)
definitions may always be used in a concatenation.  In the last
example, the definition of MODULES has three words, while the
definitions of DISK and DIRECTORY both have one word.
.b 1
As a final example of the use of make macros, consider,
.b 1
.nf
SAY = @ write sys_\$output
needed__progs: lab1.exe lab2.exe lab3.exe
.lm 9
$(SAY) "******* The labs are all up do date *******"
.lm 1
.f
.b 1
The SAY macro causes the message which follows it to be printed.  The initial
'@' sign prevents the command line itself from being printed.  As with
the use of ':' in a file name, the '$' in "sys$output" is preceded by
'_\' because '$' is a special character to MAKE.
.lm 0
2 Logical
.lm 1
MAKE reads a makefile whose name is given by the logical name MAKE$DEFNAME,
and a default rule file whose name is given by MAKE$DEFRULE.  The /RULE
and /MAKEFILE qualifiers can be used to specify different files, or to
prevent MAKE from using any makefile or default rule file.
.lm 0
2 Parameter
.lm 1
The only parameter to MAKE is the name of a particular target to
update.  Several targets can be given in a comma-separated
list.  For example,
.b 1
.c
$ MAKE LAB1.EXE, LAB2
.b 1
would tell MAKE to update both LAB1.EXE and LAB2.EXE, in that order.
Notice that if no file type is given (and the name is not defined in
the makefile) then the default file type .EXE is used.
.b 1
If no parameter is given on the command line, MAKE updates the
first target name it finds in the makefile.
.lm 0
2 Revisions
.lm 1
This version of MAKE includes the addition of '%' macro to extract
the target file-name.  This improves the functionality of macros in
the VMS environment by allowing src/obj/lis/map/dia files to reside
easily in different directories.
.b 1
A bug that effected macro parsing has been removed.
.b 1
The INVOKE_MACRO command has an internal and external format now.  Externally
it is still represented by the '$'.  When the Make or Rules file is read into
memory it is switch to and internal format ('~').  This removes a bug caused
by the use of '\$' in Rule files.  This difference is only noticable when the
/PRINT option is used.  This option will display the internal invoke macro
command ('~') instead of the '$' that was used in the file.
.b 1
Comments, Questions, or Requests may be directed to:
.b 1
.c
Stephen A. Meadows
.c
Integrated Computer Systems
.c
4841 - 268th  Avenue NE
.c
Redmond, WA  98053-2730
.lm 0
2 /ACTIVE
.lm 1
.nf
/ACTIVE
/NOACTIVE
.f
.b 1
This qualifier determines whether MAKE actually executes the DCL command
lines in the makefile.  The default is /ACTIVE, which means that MAKE will
execute makefile commands.  If /NOACTIVE is specified, MAKE prints each
command line, but does not execute it.  This is useful if you wish to
find out what MAKE would do to update a target, without actually having
the update done.
.lm 0
2 /BUILD
.lm 1
/BUILD[=FILE]
.b 1
This qualifier causes MAKE to create a DCL command (.COM) file containing
all the command lines from the makefile which are necessary to create or
update the target(s) specified.  If FILE is not given, the default name
INSTALL.COM is used.
.lm 0
2 /DEFINE
.lm 1
/DEFINE=LIST
.b 1
MAKE treats the statements in LIST as though they were at the top
of the makefile.  The most common use of /DEFINE is to specify a
new definition for a make macro, which overrides the definition
given in the makefile.  For example,
.b 1
.c
$ MAKE/DEFINE=("FOR__QUAL=/DEBUG/NOOPT","LINK__QUAL=/DEBUG")
.b 1
would create definitions of the FOR__QUAL and LINK__QUAL macros
which would override any definitions given in the makefile or
in the default rules file.
.lm 0
2 /IGNORE
.lm 1
.nf
/IGNORE
/NOIGNORE
.f
.b 1
The /IGNORE qualifier tells MAKE not to abort if any DCL command
which it executes signals an error.  The default is
/NOIGNORE, which means that if any DCL command signals an
error when executed, MAKE will exit.  This default can be
turned off for any particular command line by placing a '-'
at the start of that command line in the makefile.
.b 1
/IGNORE is like the DCL command "$ ON SEVERE__ERROR THEN CONTINUE",
while /NOIGNORE is analogous to "$ ON WARNING THEN EXIT".
.lm 0
2 /MAKEFILE
.lm 1
.nf
/MAKEFILE[=FILE]
/NOMAKEFILE
.f
.b 1
A makefile other than the default can be used by giving the /MAKEFILE=FILE
qualifier, where FILE is the name of the alternate makefile to use.  By
default, MAKE reads the makefile whose name is given by the logical name
MAKE$DEFNAME.  The /NOMAKEFILE qualifier prevents MAKE from using any
makefile.  It then relies entirely on its default rules.
.lm 0
2 /PRINT
.lm 1
.nf
/PRINT
/NOPRINT
.f
.b 1
The /PRINT qualifier causes MAKE to print all macro definitions and
all target and default rule statements before it performs any file updates.
The default is /NOPRINT.
.lm 0
2 /REVISED
.lm 1
This qualifier tells MAKE to use the file revision date in deciding
whether one file is up to date with respect to another.  By default,
MAKE uses the file creation date.
.lm 0
2 /RULE
.lm 1
.nf
/RULE[=FILE]
/NORULE
.f
.b 1
An alternate default rule file can be used by giving the /RULE=FILE
qualifier, where FILE is the name of the alternate rule file to use.
default, MAKE reads the rule file whose name is given by the logical
name MAKE$DEFRULE.  The /NORULE qualifier prevents MAKE from using any
default rule file.  It will then rely entirely on the makefile.
.lm 0
2 /SILENT
.lm 1
.nf
/SILENT
/NOSILENT
.f
.b 1
The /SILENT qualifier suppresses the automatic printing of
each DCL command line before it is executed.  The default is
/NOSILENT, which causes MAKE to print every command line
before executing it.  Printing of any particular command
line is suppressed if the line is preceded by '@' in the makefile.
.b 1
/SILENT is analogous to the DCL command "$ SET NOVERIFY".
.lm 0
2 /TOUCH
.lm 1
.c
** /TOUCH IS UNIMPLEMENTED. **
The /TOUCH qualifier prevents MAKE from executing any DCL
commands.  Instead, if a file is out of date MAKE simply
changes its modify time to the current time, so that it
appears to be up to date.
.b 1
This qualifier is useful when an include file has been
modified in such a way as to affect only one or two of the
source files which use it.  /TOUCH causes MAKE to "touch"
all the object files so that they appear up to date.  The few
which actually are not are then deleted, so that an ordinary
make will re-create them.  This avoids needless re-compilation
of every file which uses the modified include file.
.b 1
_*_* Care is required when using /TOUCH, as it directly subverts
the intention and usual operation of MAKE. _*_*
.lm 0
2 /VERBOSE
.lm 1
.nf
/VERBOSE
/NOVERBOSE
.f
.b 1
This qualifier causes MAKE to print a detailed description of
what files it examines and what their modification dates are.
This is mainly useful for debugging purposes, as the output
generated is very VERBOSE.  The default is /NOVERBOSE.