Update: 8-FEB-1987- Fixed the bug that prevented users with usernames
                    of more than 7 characters from using make. (The bug
                    occured in the routine MKSUB.  Make concatinates
                    the low order PID to the username to form the processname
                    of the subprocess.  Make died then the SPAWN failed to
                    create the subprocess name of more than 15 characters
                    character) - AWP

	8-FEB-1987  Fixed CLD Comment /TOUCH option - AWP

	17-May-1988 Fixed bug in parsing - SAM

	9-May-1989  Added '%' Macro to extract the target file-name only. - SAM

	11-May-1989 Fixed bug in rules file caused by using '$' for - SAM
		    invoking macro's.  There is now an internal invoke
		    macro ('~') and an external invoke macro ('$') command


                   DIRECTIONS FOR INSTALLING MAKE

Use BUILD_MAKE.COM to compile and link the MAKE sources, and to produce the
documentation files MAKE.HLP and MAKE.MEM.  The LINK command in
BUILD_MAKE.COM uses an options file, C_OPTS.OPT, which specifies the name
of the VAXC Run-Time Library.  It assumes that the library
"SYS$SHARE:VAXCRTL.EXE" exists. If this is not the case on your system,
modify C_OPTS.OPT as appropriate.

To install on your system:

1) Modify the file MAKE_STARTUP.COM to correctly point to proper
   path to the MAKE directory.

   MAKE_STARTUP.COM defines three system-wide logical names:
    MAKE$DEFRULE -- this should be the full pathname of the default
        rules file, DEFRULE.MAK
    MAKE$DEFNAME -- this should be the default name for makefiles,
    MAKE$DOCUMENT -- this should be the full pathname of the MAKE
        tutorial document, MAKE.MEM .  The help entry MAKE.HLP refers
        to this logical name.

2) Modify your site specific startup command file to invoke the
   procedure MAKE_STARTUP.COM

3) Install the CLD in the system wide dcltables.  (If you do not
   wish to do this, then tell your MAKE users to include the command
   "SET COMMAND MAKE_HOMEDIR:MAKE" in their LOGIN.COM files)

   To install the CLD system wide:

   $ SET COMMAND /TABLES=SYS$COMMON:[SYSLIB]DCLTABLES.EXE -
                 /OUTPUT=SYS$COMMON:[SYSLIB]DCLTABLES.EXE MAKE.CLD
   $ INSTALL == "$INSTALL/COMMAND"
   $ INSTALL REPLACE SYS$LIBRARY:DCLTABLES

   You will need to logout and back in to get the new command definitions

 4) Install the HELP entry in the system help file.

	$ LIBRARY/HELP SYS$HELP:HELPLIB.HLB MAKE.HLP

  This help entry, MAKE.HLP, directs users to mail any questions or bug
  reports to MAKE_MAINT.  Therefore, either create a MAKE_MAINT mail
  alias (In mail: SET FORWARD/USER=MAKE_MAINT), or edit MAKE.RNH to 
  remove the reference to this name.

  MAKE should now be ready for use.



             PURPOSE OF THIS MAKE IMPLEMENTATION

The major design goal of this MAKE is to provide VMS users with a
make utility which is as similar as possible to the Unix [Unix is
a trademark of Bell Laboratories] utility of the same name.  To this
end, some of MAKE's features are a bit inconvenient in the VMS
environment.  In particular, the use of '$' for macro invocation
requires that all other uses of '$' in a makefile (e.g., as part
of a file or device name) be preceded by '\'.  Similarly, the use
of '@' to suppress printing of a command line requires that a '\'
precede '@' when it is used to run a command (.COM) file.  (See!
That's not a bug, it's a feature.)  Individual sites may choose to
use other characters (by changing the #define constants INVOKE_MACRO
and MC_NO_ECHO in MAKE.H) to avoid this problem, depending on how
much they care whether their MAKE resembles the Unix version.



                  DISCUSSION OF SOURCE CODE

The sources for MAKE are:

MAKE.CLD    MAKE.H     MKERRS.MSG   MAKEFILE.MAK   BUILD_MAKE.COM
MKDATE.C    MKEXIT.C   MKEXT.C      MKFILE.C
MKMACRO.C   MKMAIN.C   MKSCAN.C     MKSHOW.C
MKSUB.C     MKUTIL.C   MAKE.RNH     MAKE.RNO

Compilation instructions are in the makefile, and in BUILD_MAKE.COM.
A comment at the top of each source file describes the main purpose
of the routines in that file.


The C code follows a number of conventions:

  o  All defined constants, macros, and typedef'd names are uppercase
  o  Local variables and function names are all lowercase
  o  Global variables start with a single capital letter, so they
     don't look like either defined constants or local variables
  o  Indentation is by eight column tabs
  o  When a statement is broken across multiple lines, all lines
     after the first are indented by half a tab
  o  A blank line precedes and follows each comment block
  o  Comments do not use pretty formatting, just the minimum open
     and close comment pairs, in line with the comment text
  o  Curly braces are always used, even when they enclose only
     one statement

To answer possible complaints, especially about the last two items, let
me point out that the major goals of choosing a style are readability
and ease of modification.  It would be difficult to find a more flexible
comment style than the one used here.  Certainly none of the more common
types of comments allow changes nearly so easily:

/*
 * This is a
 * comment.
 */

/* This is a *
 * comment.  */

/*\
 * This is a
 * comment.
\*/

As for using curly braces when they aren't required, the tiny inconvenience
of typing them in is more than made up for by the guaranteed avoidance of
"dangling else" errors, and the ease of adding new statements later.

The remaining conventions are mainly for readability.  It seems six of one,
half a dozen of the other whether a space should separate a keyword from a
parenthesized expression, or whether a space should separate a function
name from its parenthesized argument list.  I like the first, but not the
second, however, there isn't any real difference.

Using all-caps for constants is fairly standard.  Using all-caps for
macro names is not; macro names (following the lead of, for example,
putchar()/getchar() ) are usually all lowercase.  I find it very helpful
to be able to tell immediately whether something is a function or a macro,
so that I don't waste time searching all the C files for a function name
which doesn't exist, only to find (eventually) that it is a macro defined
in a .H file.  Similarly, capitalizing the first letter of every external
variable is a great aid in spotting where non-local data is being used.

Many people prefer four column tabs, rather than eight.  I have two
reasons for favoring eight space tabs.  First, a single tab is easier to
type than four spaces.  If you're using a terminal with adjustable tab
stops, this doesn't matter, but many terminals support only eight column
tabs.  Second, to answer the idea that four space tabs allow deeper
nesting without going beyond eighty columns:  my own experience is that
when the nesting is deep enough with eight space tabs to push lines past
eighty columns, it's also getting a bit too deep to be easily understood.
The innermost few levels should probably be replaced by a new function.


I hope you find MAKE as useful for your purposes as it is for mine.
If you find time hanging heavy on your hands and want something to do
to fill it, you might have a go at re-writing MKMACRO.C, especially to
merge the code for special macros with the code for named macros.
MKFILE.C could also use some work.  In particular it would be nice if
it did not scan a linked list of all the tokens in a makefile, but
rather called make_token() (in MKSCAN.C) each time it needed one.

To be ideologically correct, I suppose all of the code in MKSCAN.C and
MKFILE.C should be replaced with table-driven code produced by a lexical
analyser and parser generator such as the Unix utilities lex and yacc.
However, table-driven parsers are notoriously slow.  Also, the syntax of
makefiles is unlikely to change much or often, so ease of modification
is not a big concern.


Naturally, if you fix bugs or add useful enhancements, I'd love to
hear about it.  I can be reached via BITNET at RITVAXD::JAP5769 .


				Regards,

				-Jesse Perry