This READ_ME file is the third major release of 'make'.  A discussion of
its history is contained below.


========================== Caveats =================================

CAVEATS for 'make'                                      by RAL (23.8.89)



a) undefined macros will expand to a null string !

b) $<,$* are only defined for implicit rules !

   If you use them within an explicit rule they will be not defined and will
   according to a) expand to a null string without an error message.
   This is due to the original definition and the fact that they cannot be
   defined in a unique way for explicit rules:

    "$< is the name of the related file that caused the action" [1]

       within explicit rules there may be several dependencies; and within
         foo.o : foo.c foo.h
                 commandline
       foo.h may be the file that causes the action where you may expect
       $< set to foo.c .

    "$* is the prefix shared by the current and the dependent file names"

       within explicit rules there may be several dependencies with no common
       prefix like in the following example:
         foo.o : foo.c include.h
                 commandline

c) Which implicit rules is applied ? According to Feldman [1] :

   "If there are two paths connecting a pair of suffixes, the longer one is
    used only if the intermediate file exists or is named in the description"

   With the consequence that:
   -  if you want .l.c .c.o to be applied on a source foo.l either foo.c must
      exist already or you must add
         foo.c :
      to your makefile
   -  if you want foo.o to be made out of foo.l you must either define
      several implicit rules and name the files explicitly like in the
      example above, or define an additional implicit rule .l.o

d) Feldman [1] forgot to define how implicit rules should be applied on a
   target with a given list of dependencies but no explicit command line.

   Besides the problems mentioned in b) an additional problem occurs:
   Given the makefile:

      foo.o : foo.c

   and  .SUFFIXES : .s .c   and implicit rules .s.o, .c.o
   and existing files  foo.c,foo.s
   it's not defined which rule should be applied. With the standard algorithem
   .s.o would be selected, what's a little bit strange.

   Therefore I did implement the following definitions:

     Implicit rules will be choosen according to the sequence of the .SUFFIXES
     dependencies. But if explicit dependencies exist for the target implicit
     rules connecting the target with an explicit dependency will be choosen.

     "$< is the name of the related file (dependency) that is generated by
         substituting the suffix of the target file by the one given in
         the implicit rule"
     "$* is the prefix shared by the target name and $<"

   This should result in what everyone aspects make to do.


[1] S.I. Feldman :  Make - A Program for Maintaing Computer Programs




========================== Readme1 =================================

Following is a repost of the public domain 'make' that I posted
to net.sources a couple of months ago.  I have fixed a few bugs, and
added some more features, and the resulting changes amounted to
about as much text as the whole program (hence the repost).

For those that missed the net.sources posting, this is a public domain
re-implementation of the UNIX make program.  There is no manual included;
for documentation, refer to a UNIX manual, or the source.

Here is a list of the changes made:

i)	If '-' (ignore) or '@' (silent) where used at the start
	of a command, their effect was not turned off for the following
	commands.
ii)	A special target (.SUFFIXES, .PRECIOUS) or a rule (.c.o, .a.o),
	if first in the file would be taken as the default target.
	This resulted in error messages like "Don't know how to
	make .c", because things like .SUFFIXES were being made.
	This was further complicated by ---
iii)	Special target lines with no dependents (ie. .SUFFIXES:\n)
	were not clearing out the existing dependents like
	they should.
iv)	Default rules could not be redefined because of the error
	checking for commands being defined twice.  Now you are
	allowed to define a target beinging with '.', having
	no dependents with commands.
v)	The -q option didn't do the time comparison correctly,
	or clear the variable used to keep track of this.  Thus
	it didn't work very well.
vi)	The syntax ${..} for macro's supported by UNIX make was
	not supported.
vii)	There wuz a couple of spelling errors.
viii)	When make checked for implicit rules on targets without
	a suffix, there were problems.  (Note: The ~ feature of
	UNIX make wasn't and still isn't supported)
ix)	The -n option did not print @ lines like it was supposed to.
x)	:: added.  (See UNIX manual)
xi)	$? added.  (see UNIX manual)



========================== Readme2 =================================

Problems fixed:
  - various calls of functions with incorrect arguments (0 instead of NULL
    pointers) in rules.c  [2] (In [1] = [3] there are still some casts
    missing) 

  - passing of a NULL pointer to strcmp in main.c, which the ST didn't like
    at all  [1] ([2] complex bug fix; [3] is missing this bug fix !!)
    
  - implicit rules didn't work if an explicit rule was given for the
    dependency file but no old version of the dependency file existed.
    Example:

      makefile:
        #  make bug1 ---  scan.c,scan2.c  must not exist !!
        flex : scan.o scan2.o
        	cc scan.o scan2.o -o flex
        
        scan.o : scan.c
        
        scan.c : scan.l
        	flex -ist scan.l > scan.c
        
        scan2.c : scan.l
        	flex -ist scan.l > scan2.c
       
      output:  
        flex -ist scan.l > scan.c
        make: Don't know how to make scan2.o

      Even though the implicit rule .c.o exists make ignores the explicit
      rule for scan2.c and even with an empty explicit rule for scan.o
      make forgets to compile the generated scan.c !
      
    Both errors are caused by the same bug which I have fixed in rules.c
    with inserting the "op->n_line" stuff.
    
  - "$*" macros within recursive implicit rules have been expanded to
    wrong values

      makefile:
        #  make bug2 (recursive implicit rules with $* )
        .c.o :
        	cc -c $*.c
        
        flex : nfa.o sym.o
        	cc  nfa.o sym.o -o flex
        
        nfa.c : sym.o
        	mv nfa.c2 nfa.c
        
      output:
        cc -c sym.c
        mv nfa.c2 nfa.c
        cc -c sym.c
        cc  nfa.o sym.o -o flex

      Within the second compile command $* gets expanded again to "sym"
      instead of "nfa" ! (This example looks artificial -- there is a
      more realistic one below)
      
    The $* macro had been set before the dependency files had been made,
    which could redefine the macro again. I fixed the bug in rules.c and 
    make.c (baseline stuff)

  - "$<" macros within recursive implicit rules have been expanded to
    wrong values
    
      makefile
        #  make bug3 (recursive implicit rules with $< )
        .c.o :
        	cc -c $<
        
        flex : nfa.o sym.o
        	cc  nfa.o sym.o -o flex
        
        nfa.c : sym.o
        	mv nfa.c2 nfa.c
        
      output:
        cc -c sym.c
        mv nfa.c2 nfa.c
        cc -c sym.c
        cc  nfa.o sym.o -o flex
   
      Within the second compile command $< gets expanded again to "sym"
      instead of "nfa" ! (This example looks artificial -- there is a
      more realistic one below)
      
    The $< macro had been set before the dependency files had been made,
    which could redefine the macro again. I fixed the bug in rules.c and 
    make.c (inputline stuff)


    More realistic makefile to demonstrate the $* and $< bugs:
      makefile:
        #  parse.y, scan.c should exist, scan.o depends on parse.h (y.tab.h)
        #  which will be generated together with parse.c
        flex : scan.o
        	cc scan.o -o flex
        
        scan.o : parse.c
      
      output:
        yacc  parse.y
        mv y.tab.c parse.c
        cc -O -c parse.y
        cc scan.o -o flex
        
      I fear our compiler doesn't know how to compile parse.y to scan.o !!
      
  - I have added implicit rules  ".l.c" and ".l.o" for flex (res. ".l.s"
    and ".y.s" for MINIXPC)
    

[1] make changes for Minix/ST     by Frans Meulenbroeks from  30 Sep 88
[2] cdiffs PC 1.3 make -> ST 1.1  by Simon Poole        from  25 Jan 89
[3] PC 1.4a updates               by Andy Tanenbaum     from  22 Jan 89
[4] PC version 1.3
[5] make                          by Andy Tanenbaum     from  13 Oct 88




========================== Readme3 =================================

Make -- the next generation         V2.0                         11.9.89 RAL

This is a new version of 'make' as posted in [1],[2] with applied bug fixes [3]
and a lot of new bug fixes and improvements.

The following problems have been fixed:

- impossibility to execute huge makefiles (lib ST) - causing an
  'expanded line too line' error:

   Besides the typo in the error message itself the line buffers had to be
   increased: Instead of increasing the arbitrary limit LZ in h.h from 1024
   to another value I introduced dynamic realloc calls without limits.

- troubles with the -t(ouch) option reported by Bruce Evans [4]:

   'time' hadn't be declared as 'extern (time_t)' resulting in an (int) to
   (long) expansion causing a wrong timestamp.
   Calling time with argument '0' instead of '(time_t *)0' caused an address
   error on the ST

- files with date '0' (1 Jan 70) caused actions that wouldn't have been
  necessary  -- reported by David Lawyer [5]:

   This was not a bug but a feature ! Make used a timestamp of '0' to mark
   non-existing files. I introduced a new flag N_EXISTS and corrected all
   n_time and dtime accesses (make.c,input.c(rules.c))

- Implicit rules applied on a target with a given dependency list but no
  explicit command line could result in unexpected commands:

   foo.o : foo.c

   with existing  foo.c, foo.s  sources and the SUFFIXES : .s .c
   resulted in  .s.o  choosen as the implicit rule !
   Reported by Bruce Evans [4].

   This is a strange problem that I will dicuss in the CAVEATS file in detail.
   I changed rules.c to do what everyone exepted -- choosing the .c.o rules
   in the example above.


- Double colon targets got a wrong internal timestamp with the result that
  in makefiles of typ:

    foo1 : foo2

    foo2 :: foo3

  with timestamps foo2<foo1<foo3  foo2 would be made out of foo3, but foo1
  wouldn't be made because the old make thought it was 'up to date'


- 'up to date': No message occured if the main target was not an explicit
   rule. (See lib/ and other makefiles containing "all: ..." as main lines)

- the '-p' output was directed to stderr even though it's no error output.
  I directed it to stdout.

- the 'n' option does no longer unset the 's' option
  (see also 'd' option below)


Improvements and new features:

- Noticing that 'make' needed 1'09" and more than 64K to 'make -n' the new
  ST lib  I couldn't resist improving the code a little bit with the results:

             old      new          |   new + .SUFFIXES    old + .SUFFIXES
                                   |
  real     1:09.0    41.0  (+ 68%) |  27.0  (+156%)         41.0
  user       35.4     7.7  (+358%) |   6.4  (+453%)         20.4
  sys        32.9    33.0          |  19.8  (+ 66%)         19.8
                                   |
  chmem     46000   29000  -17000  | 28500  -17500         33500
  text     ~14834
  data     ~ 1886
  bss      ~14460
           ---------------
            77180   60180

  A speedup of a factor of 4.5 and 17k less memory usage for unmodified
  makefiles is quite astonishing -- now the time spent in sys calls is the
  dominant part.

  A further speedup can be achived by adding

  .SUFFIXES:

  .SUFFIXES: .s .o .c

  to the lib Makefile. Doing this eliminates the .l,.y suffixes avoiding
  implicit existence checks for possible lex and yacc sources. This leads to
  less system calls reducing the time spent in sys.

  Rem: Due to further improvements the values above have been changed a little
   bit to:

    new+    real 41.0  user 8.2   sys 32.6
            text 19320 data 3208  bss 2506  chmem 32000  = 57034

- I included changes from Peter Housel [6] that fixed the argument parsing
  technique according to Feldman's description.

- The new environment 'MAKEFLAGS' is evaluated and set. It provides 2 new
  features:

   - make options can be set generally (for example 'MAKEFLAGS=a' (see below))
   - make can be called 'recursively' with options. This is especially useful
     in connection with the '-n' option.
     Note: '-n' does no longer keep $(MAKE) from being executed ! Additionally
           $(MAKE) is set by default to  argv[0] .
     Hint: It's now possible to write a 'super-makefile' for the whole
           Minix system !

   Note: -f makefile cannot be passed via MAKEFLAGS

- macros:

  Additionally the whole environment is accepted as macro definitions with the
  following priority:

    command line macros > makefile macros > environment macros > inbuild macros

  With the new option '-e' the priority can be changed to:

    command line macros > environment macros > makefile macros > inbuild macros

  Hint: Now it would be possible to use common makefiles for PC and ST !
        Different extensions and definitions could be set by environment macros!

- new option '-k' that allows make to continue after command execution errors
  with unrelated branches of the makefile (very useful !).

- new option '-d' for additional debugging information.
  Note: - a usage in connection with '-q' leads to incomplete output, because of
          optimization.
        - options 'nsd' result in a pure debugging output on stout

- better usage information

- commands may follow dependencies if seperated by a semicolon as defined
  by Feldman.  ( targets : dependents ; command # comment)

- makefiles containing $*,$< within explicit rules can be made by with the
  new '-a' (ambiguous) option. Why these macros are ambiguous and normally
  expanded to null-strings is explained in the Caveats file.
  If the -a option is set (may be set in MAKEFLAGS !) make tries to guess
  the macros according to the following rules:
    $< is set to the first dependency, that has a common basename with the
       target. If no such dependency exists the first dependency is taken.
    $* is set to the common basename of the target and $< (may be a null-string)

- the macros @F,@D,*F,*D,<F,<D are supported. The F-macros contain the filename
  and the D-macros the directory path including the trailing slash of the
  appropriated base macro @,*,< .
  Note: If the base macro is a simple filename the D-macro is set to './' .

- single suffix implicit rules are supported and '.c' is set to:

     "$(CC) $(CFLAGS) -i -o $@ $<"

- the '.DEFAULT' implicit rule is supported and applied to all targets that
  must be made without an explicit or a matching implicit rule.



Changes:

- indention : Peter Housel [6] and I couldn't resist to change the indention
     to make the sources a little bit more readable

- the additional leading spaces on command lines have been eliminated by Peter
  Housel [6]

- comments : I added a few (further) comments

- I combined the declaration,definiton and initialization of variables in h.h

- all make functions are declared with prototypes in h.h

- a few #ifdef's have been substituted by macro usage to make the sources more
  readable.


Manifest: Due to the numerous changes the complete set of sources must be
 distributed:

 cmds/make/Caveats
           README
           Readme2
           Readme3         - this file
           Readme.tos
           check.c
           h.h
           input.c
           macro.c
           main.c
           makefile.pc     - Minix PC
           makefile.st     - Minix ST (Amiga,...)
           makefile.st.1   - Minix ST 1.1
           makefile.tos    - Atari TOS
           make.c
           make.lnk        - Atari TOS (Turbo C)
           make.tlk        - Atari TOS (Lattice C)
           reader.c
           rules.c

 lib/putenv.c              - missing library function

+  Minix ST V1.1:
+    - utime.h, strchr.c, strrchr.c are needed which have been posted to the net
+        several times and are part of Minix PC 1.3 and Minix ST 1.4a that will
+        be posted in a few weeks.
+    - 2 makefiles are provided:
+          makefile.st.1  --  to make the new make version with the ST 1.1 make
+          makefile.st    --  to remake the new make version with the new make.
  
The files are shared, compressed and uuencoded.(Sorry, but I'm on EBCDIC-Bitnet)

BTW: - TOS is supported (see Readme.tos)
     - OS9,EON not tested (problems may occur with the environment handling)
     - MSDOS : a friend of mine will try to do the port (should be similar
           to the TOS port)

[1] PC version 1.3                by Andy Tanenbaum
[2] make                          by Andy Tanenbaum     from  13 Oct 88
[3] Make, 3 bug fixes for ST & PC by Ronald Lamprecht   from   3 Jul 89
[4] private communication         by Bruce Evans        from  20 Jul 89
[5] private communication         by David Lawyer       from  14 Jul 89
[6] private communication         by Peter Housel       from  29 Aug 89

Bitnet:  V61@DHDURZ1                               Ronald Lamprecht
UUCP:    ...!unido!DHDURZ1.bitnet!V61              Theoretische Physik
ARPAnet: V61%DHDURZ1.BITNET@CUNYVM.CUNY.EDU       (Heidelberg, West Germany)

