SecuritySNACCRuntime/doc/makefile.tex

   1 % file: .../doc/makefile.tex
   2
   3 % $Header: /cvs/Darwin/src/live/Security/SecuritySNACCRuntime/doc/makefile.tex,v 1.1.1.1 2001/05/18 23:14:10 mb Exp $
   4 % $Log: makefile.tex,v $
   5 % Revision 1.1.1.1  2001/05/18 23:14:10  mb
   6 % Move from private repository to open source repository
   7 %
   8 % Revision 1.1.1.1  1999/03/16 18:05:53  aram
   9 % Originals from SMIME Free Library.
  10 %
  11 % Revision 1.1  1997/01/01 22:47:49  rj
  12 % first check-in
  13 %
  14
  15 \chapter{\label{makefile-sect}Makefiles}
  16
  17 Some of Snacc's makefiles look rather sophisticated.
  18 This section explains some of the tricks.
  19
  20 \section{CVS, Dependencies and Make's Include Statement}
  21
  22 The makefiles take advantage of the file inclusion feature.
  23 Since this has already been supported by UNIX System III\footnote{yes, System III, not System V R3} make (somewhen around 1980), I consider it to be pretty portable.
  24 If your make is crippled, either use a newer one (e.g. GNU make), or as a last resort, remove (better: comment out) the include statements and call make with the additional arguments {\ufn -f .../makehead -f makefile -f dependencies -f .../maketail}.
  25
  26 Snacc's configuration script generates the file {\ufn makehead} which gets included by all makefiles.
  27 It contains a lot of definitions used by make.
  28
  29 The dependencies have been moved out of each makefile into a separate file called {\ufn dependencies} that is not under cvs control---otherwise, the makefiles would inflate the repository unnecessarily.
  30 The makefiles have an include statement for their dependencies file.
  31 GNU make automatically makes the dependencies if the file does not exist, but other versions of {\ufn make} simply give up.
  32 In that case, an initial (empty) file has to be generated.
  33 Snacc's top level makefile does this for you if you call {\ufn make depend}.
  34
  35 A third file that is included by almost every makefile is {\ufn \dots/maketail}.
  36 It holds the rules that are common to all makefiles where C/C++ code is compiled.
  37
  38 \section{Circular Dependencies}
  39
  40 In a normal makefile rule, a file depends upon other files.
  41 If any of a file's dependencies is newer, the file is remade.
  42 This goes well as long as the dependency graph is non-circular, but snacc is compiled from some files it has generated itself.
  43 This recursion can lead to one of two results: in the worse case, {\ufn make} builds the compiler because its source files are newer, builds the source files because the compiler is newer, builds the compiler because some source files are newer, and so on ad infinitum\dots{}
  44 Even if this endless recursion does not happen, one or two of the above steps will be made every time {\ufn make} is called.
  45 To avoid this waste of time, one lets the compiler generate a new source file, but when the new and the old version are identical, the old file is kept and {\ufn make} sees that the compiler is up-to-date, and the recursion is terminated.
  46 Of course, if the source file's contents did change, it is replaced with the new version.
  47
  48 This is a simplified example of a normal makefile:
  49
  50 \begin{Makefile}
  51 snacc:          \>tbl.h\\
  52                 \>\emph{compile} snacc\\
  53 \\
  54 tbl.h:          \>snacc tbl.asn1\\
  55                 \>./snacc \dots{} tbl.asn1\\
  56 \end{Makefile}
  57
  58 Most {\ufn make} versions will complain and print a warning about this `infinite loop' or `circular dependency'.
  59 The first approach towards a solution could be:
  60
  61 \begin{Makefile}
  62 snacc:          \>tbl.h\\
  63                 \>\emph{compile} snacc\\
  64 \\
  65 tbl.h:          \>snacc tbl.asn1\\
  66                 \>mv tbl.h tbl.h.prev\\
  67                 \>./snacc \dots{} tbl.asn1\\
  68                 \>if cmp tbl.h.prev tbl.h; then\char`\\\\
  69                 \>\>  echo "tbl.h hasn't changed";\char`\\\\
  70                 \>\>  mv tbl.h.prev tbl.h;\char`\\\\
  71                 \>else\char`\\\\
  72                 \>\>  \$(RM) tbl.h.prev;\char`\\\\
  73                 \>fi\\
  74 \end{Makefile}
  75
  76 The effect is that you keep snacc from being remade if the contents of tbl.h did not change, but the two steps to create tbl.h and to test whether it is different from tbl.h.prev will be made every time snacc or tbl.asn1 are newer than tbl.h, which they most often will be since few of the changes to snacc will affect tbl.h's contents.
  77 And {\ufn make} will still complain about the recursion.
  78 To solve all this, another file, a stamp file is introduced.
  79 It separates the file's contents from its modification time:
  80
  81 \begin{Makefile}
  82 snacc:          \>tbl.h\\
  83                 \>\emph{compile} snacc\\
  84 \\
  85 stamp-tbl:      \>snacc tbl.asn1\\
  86                 \>mv tbl.h tbl.h.prev\\
  87                 \>./snacc \dots{} tbl.asn1\\
  88                 \>if cmp tbl.h.prev tbl.h; then\char`\\\\
  89                 \>\>  echo "tbl.h hasn't changed";\char`\\\\
  90                 \>\>  mv tbl.h.prev tbl.h;\char`\\\\
  91                 \>else\char`\\\\
  92                 \>\>  \$(RM) tbl.h.prev;\char`\\\\
  93                 \>fi\\
  94                 \>date > \$@\\
  95 \\
  96 tbl.h:          \>stamp-tbl\\
  97                 \>@true\\
  98 \end{Makefile}
  99
 100 The dummy command in the rule for tbl.h is necessary, since otherwise, despite stamp-tbl commands having modified tbl.h, many versions of make think that tbl.h has not been modified.
 101
 102 If you want {\ufn tbl.h} to be remade (e.g. you have changed an option to snacc), you must delete {\ufn stamp-tbl}---{\ufn tbl.h} may (and should) be left in place.
 103
 104 The rules in {\ufn \dots/compiler/makefile}, {\ufn \dots/c-lib/makefile} and {\ufn \dots/c++-lib/makefile} are further complicated by the fact that
 105 \begin{enumerate}
 106   \item snacc prints the current time into the file which the comparison must take into account
 107   \item if snacc has not been built it cannot be used to generate its source files---a bootstrapping version of snacc's source files has got to be supplied.
 108 \end{enumerate}
 109
 110 \section{Compiling Different Libraries From One Set Of Source Files}
 111
 112 The different libraries in {\ufn \dots/c-lib/} and {\ufn \dots/c++-lib/} get made by means of recursive calls to make with different macro settings.
 113 This keeps the makefiles short as it avoids a lot of duplication of file lists and rules which would be a hassle to maintain.
 114 The different libraries get compiled from the same set of source files, the code to be compiled is determined through {\ufn cpp} (C preprocessor) macro switches.
 115
 116 \section{Configuration, Optional Code and Makefiles}
 117
 118 The {\ufn \dots/configure} script looks for Tcl/Tk.
 119 If they are absent, there is no use in trying to compile Snacc's Tcl interface.
 120 For makefiles to detect whether the Tcl interface should be compiled or not, there is a file {\ufn \dots/tcl-p.c} that, after being compiled into {\ufn tcl-p}, exits with 0 (the shells' `true' value) if Tcl/Tk is present and the user has not disabled this option by setting {\C NO\_TCL} in {\ufn \dots/policy.h} to {\C 1}.
 121 {\ufn tcl-p} gets made automatically.