home *** CD-ROM | disk | FTP | other *** search
/ ftp.update.uu.se / ftp.update.uu.se.2014.03.zip / ftp.update.uu.se / pub / rainbow / msdos / misc / make.lzh / MAKE.MEM < prev   
Text File  |  1986-01-19  |  30KB  |  728 lines

  1. 27-Jul-84 14:29:12,29553;000000000005
  2. Return-Path: <@COLUMBIA-20.ARPA:SY.FDC@CU20B>
  3. Received: from COLUMBIA-20.ARPA by DEC-MARLBORO.ARPA with TCP; Fri 27 Jul 84 14:27:57-EDT
  4. Received: from CU20B by CUCS20 with DECnet; 27 Jul 84 14:21:45 EDT
  5. Date: Thu 26 Jul 84 09:36:11-EDT
  6. From: Frank da Cruz <SY.FDC%CU20B@COLUMBIA-20.ARPA>
  7. Subject: [Alan Crosswell <alan at CUUTSA>:]
  8. To: Eiben@DEC-MARLBORO.ARPA
  9.  
  10. Here's the MAKE manual...
  11.                 ---------------
  12.  
  13. Received: from CUVMA by CU20B with HASP; 26 Jul 84 00:23:24 EDT
  14. Received: from CUVMB    by CUVMA      id 1352; Wed, 25 Jul 84 23:35:51 EDT
  15. Received: by CUVMB      id 0791; Wed, 25 Jul 84 23:35:20 EDT
  16. From: Alan Crosswell <alan at CUUTSA>
  17. Date: 25 Jul 1984 23:35:13-EDT
  18. Sender: UNIXA at CUVMB
  19. Message-id: UTSROUTE alan rmail:alan x
  20. To: sy.fdc@cu20b
  21.  
  22. ------------------------------- Page    i -------------------------------
  23.  
  24.                           Make - A Program for
  25.  
  26.                       Maintaining Computer Programs
  27.  
  28.  
  29.  
  30.  
  31.                                                  S. I. Feldman
  32.  
  33.  
  34.  
  35.                                                  Edited for UTS
  36.  
  37. ------------------------------- Page   ii -------------------------------
  38.  
  39.                             TABLE OF CONTENTS
  40.  
  41.  
  42. 1.    Abstract  . . . . . . . . . . . . . . . . . . . . . . . . . . .   1
  43.  
  44. 2.    Introduction  . . . . . . . . . . . . . . . . . . . . . . . . .   1
  45.  
  46. 3.    Basic Features  . . . . . . . . . . . . . . . . . . . . . . . .   2
  47.  
  48. 4.    Description Files and Substitutions . . . . . . . . . . . . . .   5
  49.  
  50. 5.    Command Usage . . . . . . . . . . . . . . . . . . . . . . . . .   7
  51.  
  52. 6.    Implicit Rules  . . . . . . . . . . . . . . . . . . . . . . . .   8
  53.  
  54. 7.    Example . . . . . . . . . . . . . . . . . . . . . . . . . . . .   9
  55.  
  56. 8.    Suggestions and Warnings  . . . . . . . . . . . . . . . . . . .  11
  57.  
  58. 9.    SCCS Files  . . . . . . . . . . . . . . . . . . . . . . . . . .  12
  59.  
  60. 10.   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . .  13
  61.  
  62. 11.   References  . . . . . . . . . . . . . . . . . . . . . . . . . .  13
  63.  
  64. Appendix A.    Suffixes and Transformation Rules  . . . . . . . . . .  14
  65.  
  66.  
  67.                                                             Last Page  15
  68.  
  69. -------------------------------- Page  1 --------------------------------
  70.  
  71. 1.    ABSTRACT
  72.  
  73. In a programming project, it is easy to lose track of which files need to
  74. be reprocessed or recompiled after  a change is made in some part of  the
  75. source.  Make provides a simple mechanism for maintaining up-to-date ver-
  76. sions of programs that result from many operations on several  files.  It
  77. is possible to tell  make the  sequence of commands  that create  certain
  78. files, and  the list  of files  that require  other files  to be  current
  79. before the operations can be done.  Whenever a change is made in any part
  80. of the program,  the make  command will create  the proper files  simply,
  81. correctly, and with a minimum amount of effort.
  82.  
  83. The basic operation of make is to find the name of a needed target in the
  84. description, ensure that all of  the files on which it depends exist  and
  85. are up to date, and  then create the target if  it has not been  modified
  86. since its generators were.  The description file really defines the graph
  87. of dependencies; Make does a depth-first  search of this graph to  deter-
  88. mine what work is really necessary.
  89.  
  90. Make also provides a simple  macro substitution facility and the  ability
  91. to encapsulate commands in a single file for convenient administration.
  92.  
  93.  
  94.  
  95.  
  96. 2.    INTRODUCTION
  97.  
  98. It is common practice to divide large programs into smaller, more manage-
  99. able pieces.  The pieces may require different treatments: some may  need
  100. to be run through a macro processor, some may  need to be processed by  a
  101. sophisticated program generator (e.g., yacc [1] or lex [2]).  The outputs
  102. of these generators may then have to be compiled with special options and
  103. with certain definitions and declarations.  The code resulting from these
  104. transformations  may  then  need  to  be  loaded  together  with  certain
  105. libraries under  the  control of  special options.   Related  maintenance
  106. activities involve running complicated test scripts and installing  vali-
  107. dated modules.   Unfortunately, it  is easy  for a  programmer to  forget
  108. which files  depend  on which  others,  which files  have  been  modified
  109. recently, and the exact sequence of operations needed to make or exercise
  110. a new version  of the  program.  After a  long editing  session, one  may
  111. easily lose  track of  which  files have  been changed  and which  object
  112. modules are still valid, since a change  to a declaration can obsolete  a
  113. dozen other files.  Forgetting to compile a routine that has been changed
  114. or that uses changed declarations will result in a program that will  not
  115. work, and  a bug  that can be  hard to  track down.  On  the other  hand,
  116. recompiling everything in sight just to be safe is wasteful.
  117.  
  118. -------------------------------- Page  2 --------------------------------
  119.  
  120. The program described in this report mechanizes many of the activities of
  121. program development  and maintenance.   If the  information on  interfile
  122. dependences and command sequences is stored in a file, the simple command
  123.  
  124.      make
  125.  
  126. is frequently enough to update  the interesting files, regardless of  the
  127. number that have been edited since the last 'make'.  The description file
  128. is usually easy to write, and changes infrequently.  It is usually easier
  129. to type the make command than to issue even one of the needed operations,
  130. so the typical cycle of program development operations becomes
  131.  
  132.      think -- edit -- make -- test  . . .
  133.  
  134. Make is most useful  for medium-sized programming  projects; it does  not
  135. solve the problems of maintaining multiple source versions or of describ-
  136. ing huge programs.
  137.  
  138.  
  139.  
  140.  
  141. 3.    BASIC FEATURES
  142.  
  143. The basic operation of make is to update  a target file by ensuring  that
  144. all of  the files  on which it  depends exist  and are up  to date,  then
  145. creating the target  if it  has not  been modified  since its  dependents
  146. were.  Make does a depth-first  search of the graph of dependences.   The
  147. operation of the command depends on the ability to find the date and time
  148. that a file was last modified.
  149.  
  150. To illustrate, let us consider a simple example: A program named prog  is
  151. made by compiling and  loading three C  language files x.c, y.c, and  z.c
  152. with the lpw library.  By  convention, the output  of the C  compilations
  153. will be found in  files named x.o, y.o,  and z.o.  Assume that the  files
  154. x.c and y.c share some  declarations in a file named  defs that z.c  does
  155. not.  That is, x.c and y.c have the line
  156.  
  157.      #include "defs"
  158.  
  159. The following text describes the relationships and operations:
  160.  
  161.  
  162.      prog:  x.o y.o z.o
  163.              cc x.o y.o z.o -lpw -o prog
  164.  
  165.      x.o y.o:  defs
  166.  
  167. -------------------------------- Page  3 --------------------------------
  168.  
  169. If this information were stored in a file named makefile, the command
  170.  
  171.      make
  172.  
  173. would perform the operations needed  to re-create prog after any  changes
  174. had been made to any of the four source files x.c, y.c, z.c, or defs.
  175.  
  176. Make  operates  using  three  sources  of  information:  a  user-supplied
  177. description file (as  above), file names  and 'last-modified' times  from
  178. the file system, and built-in rules to bridge  some of the gaps.  In  our
  179. example, the first line says that prog depends on three '.o' files.  Once
  180. these object files are  current, the  second line describes  how to  load
  181. them to create prog.  The third line says that x.o  and y.o depend on the
  182. file defs.  From the  file system,  make discovers that  there are  three
  183. '.c' files  corresponding to  the needed  '.o' files,  and uses  built-in
  184. information on how to generate an object from a source file (i.e.,  issue
  185. a 'cc -c' command).
  186.  
  187. The following  long-winded description  file  is equivalent  to  the  one
  188. above, but takes no advantage of make's innate knowledge:
  189.  
  190.  
  191.      prog:  x.o y.o z.o
  192.              cc x.o y.o z.o -lpw -o prog
  193.  
  194.      x.o:  x.c defs
  195.              cc -c x.c
  196.      y.o:  y.c defs
  197.              cc -c y.c
  198.      z.o:  z.c
  199.              cc -c z.c
  200.  
  201. If no source  or object file  has changed  since the last  time prog  was
  202. made, all of the files would be current, and the command
  203.  
  204.      make
  205.  
  206. would just announce this fact and stop.   If, however, the defs file  had
  207. been edited, x.c and y.c (but not z.c) would be recompiled, and then prog
  208. would be created  from the  new '.o'  files.  If  only the  file y.c  had
  209. changed, only it would be recompiled, but it would still  be necessary to
  210. reload prog.
  211.  
  212. If no target name  is given on  the make command  line, the first  target
  213. mentioned in the description is created; otherwise the specified  targets
  214. are made.  The command
  215.  
  216.      make x.o
  217.  
  218. -------------------------------- Page  4 --------------------------------
  219.  
  220. would recompile x.o if x.c or defs had changed.
  221.  
  222. If the file  exists after  the commands are  executed, its  time of  last
  223. modification is used in further decisions; otherwise the current time  is
  224. used.  It is often useful to include  rules with mnemonic names and  com-
  225. mands that do not produce a file with that name.   These entries can take
  226. advantage of  make's ability  to generate  files and  substitute  macros.
  227. Thus, an entry 'save' might  be included to copy a certain set of  files,
  228. or an entry 'cleanup' might  throw away unneeded intermediate files.   In
  229. other cases one may maintain  a zero length file purely to keep track  of
  230. the time at which certain actions  were taken.  This technique is  useful
  231. for maintaining remote archives and listings.
  232.  
  233. Make has a simple  macro mechanism for  substituting in dependency  lines
  234. and command strings.  Macros are defined by command arguments or descrip-
  235. tion file lines with embedded equal signs.  A macro is invoked by preced-
  236. ing the name by a dollar sign; macro names longer  than one character may
  237. be parenthesized.  The name of the  macro is either the single  character
  238. after the dollar sign or  a name, possibly parenthesized.  The  following
  239. are valid macro invocations:
  240.  
  241.      $(CFLAGS)
  242.      $CFLAGS
  243.      $2
  244.      $(xy)
  245.      $Z
  246.      $(Z)
  247.  
  248. The first two  and the  last two  invocations show  that parenthesis  are
  249. optional.  Both the parenthesized and the non-parenthesized versions have
  250. identical meanings.   $$ is  a  dollar sign.   All of  these  macros  are
  251. assigned values during input, as shown below.  Four special macros change
  252. values during the execution  of the command:  $*, $@, $?,  and $<.   They
  253. will be discussed later.  The following fragment shows the use of macros:
  254.  
  255.  
  256.      OBJECTS = x.o y.o z.o
  257.      LIBES = -lpw
  258.      prog: $(OBJECTS)
  259.              cc $(OBJECTS) $(LIBES) -o prog
  260.      ...
  261.  
  262.  
  263. The command
  264.  
  265.      make
  266.  
  267. loads the three object files with the lpw library.  The command
  268.  
  269. -------------------------------- Page  5 --------------------------------
  270.  
  271.      make "LIBES = -ll -lpw"
  272.  
  273. loads them with  both the  lex ('-ll')  and the  PWB ('-lpw')  libraries,
  274. since macro definitions on the  command line override definitions in  the
  275. description.  (It is necessary to quote arguments with embedded blanks in
  276. UTS commands.)
  277.  
  278. The following sections detail the form of description files and the  com-
  279. mand line, and discuss options and built-in rules in more detail.
  280.  
  281.  
  282.  
  283.  
  284. 4.    DESCRIPTION FILES AND SUBSTITUTIONS
  285.  
  286. A description file  contains three  types of  information: macro  defini-
  287. tions, dependency information, and executable commands.  There is also  a
  288. comment convention: all characters after a  sharp (#) are ignored, as  is
  289. the sharp  itself.  Blank  lines  and lines  beginning with  a sharp  are
  290. totally ignored.  If a noncomment line is  too long, it can be  continued
  291. using a backslash.  If the  last character of a line is a backslash,  the
  292. backslash, new-line, and following blanks and tabs are replaced by a sin-
  293. gle blank.
  294.  
  295. A macro definition is a line containing an  equal sign not preceded by  a
  296. colon or a tab.  The  name (string of letters and digits) to the left  of
  297. the equal sign (trailing blanks  and tabs are  stripped) is assigned  the
  298. string of characters following  the equal sign  (leading blanks and  tabs
  299. are stripped).  The following are valid macro definitions:
  300.  
  301.      2 = xyz
  302.      abc = -ll -ly -lpw
  303.      LIBES =
  304.  
  305. The last definition assigns LIBES the null string.  A macro that is never
  306. explicitly defined has the null  string as value.  Macro definitions  may
  307. also appear on the make command line (see below).
  308.  
  309. Other lines give information about target files.  The general form of  an
  310. entry is:
  311.  
  312.      target1 [target2 ...] :[:] [dependent1 ...] [; commands] [# ...]
  313.      [<TAB> commands] [# ...]
  314.      ...
  315.  
  316. Items inside brackets may be omitted.  Targets and dependents are strings
  317. of letters, digits, periods, and slashes.  (Shell metacharacters '*'  and
  318.  
  319. -------------------------------- Page  6 --------------------------------
  320.  
  321. '?' are expanded.)  A command is any string of characters not including a
  322. sharp (except in quotes) or new-line.  Commands may appear either after a
  323. semicolon on a  dependency line or  on lines  beginning with a  tab or  a
  324. blank immediately following a dependency line.
  325.  
  326. A dependency line may have either a single  or a double colon.  A  target
  327. name may appear on more than one dependency line, but  all of those lines
  328. must be of the same (single or double colon) type.
  329.  
  330.  1.  For the usual single colon  case, at most  one such dependency  line
  331.      may have a command  sequence associated with  it.  If the target  is
  332.      out of date with any  of the dependents on any  of the lines, and  a
  333.      command sequence is specified (even a null one following a semicolon
  334.      or tab), it is executed;  otherwise a default  creation rule may  be
  335.      invoked.
  336.  
  337.  2.  In the double colon case, a command sequence may be associated  with
  338.      each dependency line; if the  target is out of date with any of  the
  339.      files on a particular line, the associated commands are executed.  A
  340.      built-in rule may also be  executed.  This detailed form is of  par-
  341.      ticular value in updating archive-type files.
  342.  
  343.      If a target must be created,  the sequence of commands is  executed.
  344.      Normally, each command line is printed and then passed to a separate
  345.      invocation of the shell after substituting for macros.  (The  print-
  346.      ing is suppressed in silent mode or if the command  line begins with
  347.      an @ sign.)  Make normally stops if any command signals an error  by
  348.      returning a nonzero  error code.   (Errors are ignored  if the  '-i'
  349.      flags has been specified on the make command line, if the fake  tar-
  350.      get name '.IGNORE' appears in  the description file, or if the  com-
  351.      mand string in the description file begins with a hyphen.  Some  UTS
  352.      commands return meaningless status.)   Because each command line  is
  353.      passed to a separate  invocation of  the shell, care  must be  taken
  354.      with certain  commands (e.g.,  cd and shell  control commands)  that
  355.      have meaning only  within a  single shell process;  the results  are
  356.      forgotten before the next line is executed.
  357.  
  358.      Before issuing any command, certain  macros are set.   $@ is set  to
  359.      the name of the file to be 'made'.  $? is set to the string of names
  360.      that were found to be younger than  the target.  If the command  was
  361.      generated by an  implicit rule (see  below), $< is  the name of  the
  362.      related file that caused the action, and $* is the prefix shared  by
  363.      the current and the dependent file names.
  364.  
  365.      If a  file must  be  made but  there  are no  explicit  commands  or
  366.      relevant built-in  rules,  the  commands associated  with  the  name
  367.      '.DEFAULT' are used.  If there is no  such name, make prints a  mes-
  368.      sage and stops.
  369.  
  370. -------------------------------- Page  7 --------------------------------
  371.  
  372. 5.    COMMAND USAGE
  373.  
  374. The make command takes four kinds of arguments: macro definitions, flags,
  375. description file names, and target file names.
  376.  
  377.      make [flags] [macro definitions] [targets]
  378.  
  379. The following summary of the operation of the command explains how  these
  380. arguments are interpreted.
  381.  
  382. First, all  macro definition  arguments  (arguments with  embedded  equal
  383. signs) are analyzed and the assignments made.  Command line macros  over-
  384. ride corresponding definitions found in the description files.
  385.  
  386. Next, the flag arguments are examined.  The permissible flags are
  387.  
  388. -z   Print a detailed trace of make's analysis of your description file.
  389.  
  390. -i   Ignore error  codes returned  by  invoked commands.   This  mode  is
  391.      entered if the fake target name '.IGNORE' appears in the description
  392.      file.
  393.  
  394. -s   Silent mode.  Do  not print  command lines  before executing.   This
  395.      mode is also entered  if the fake  target name '.SILENT' appears  in
  396.      the description file.
  397.  
  398. -r   Do not use the built-in rules.
  399.  
  400. -n   No execute mode.   Print commands,  but do not  execute them.   Even
  401.      lines beginning with an '@' sign are printed.
  402.  
  403. -t   Touch the target files (causing them to  be up to date) rather  than
  404.      issue the usual commands.
  405.  
  406. -q   Question.  The make command  returns a zero  or nonzero status  code
  407.      depending on whether the target file is up to date.
  408.  
  409. -p   Print out the complete set of macro definitions and target  descrip-
  410.      tions
  411.  
  412. -d   Debug mode.  Print out detailed information on files and times exam-
  413.      ined.
  414.  
  415. -f   Description file name.  The next argument is assumed to be the  name
  416.      of a  description file.   A file  name of '-'  denotes the  standard
  417.      input.  If there are no '-f'  arguments, the file named makefile  or
  418.      Makefile in  the current  directory is  read.  The  contents of  the
  419.      description files override the built-in rules if they are present.
  420.  
  421. -------------------------------- Page  8 --------------------------------
  422.  
  423. -I file   Include  the file  name specified  along with  the  description
  424.      file.
  425.  
  426. Finally, the remaining arguments are assumed  to be the names of  targets
  427. to be made; they are  done in left to right order.  If there are no  such
  428. arguments, the first name in  the description files  that does not  begin
  429. with a period is 'made'.
  430.  
  431.  
  432.  
  433.  
  434. 6.    IMPLICIT RULES
  435.  
  436. The make  program uses  a table  of  interesting suffixes  and a  set  of
  437. transformation rules to supply default dependency information and implied
  438. commands.  (The Appendix describes these  tables and means of  overriding
  439. them.)  The default suffix list is:
  440.  
  441.      .o      object file
  442.      .c      C source file
  443.      .h      header file
  444.      .f      Fortran source file
  445.      .t      test file
  446.      .s      assembler source file
  447.      .y      yacc/C source grammar
  448.      .l      lex source grammar
  449.      .q      quickscreen source file
  450.      .*+     Save files where * is q, y, l, c, s, h, or f.
  451.  
  452. The following diagram  summarizes the default  transformation paths.   If
  453. there are two paths connecting a pair of suffixes, the longer one is used
  454. only if the intermediate file exists or is named in the description.   An
  455. exception is  an SCCS  transformation,  such as  .c->.c, .s->.s,  .q->.q,
  456. .y->.y or .l->.l.
  457.  
  458.                                    .o
  459.  
  460.  
  461.            .c                      .s    .y    .l      .h
  462.  
  463. y    .l         .q    .c+          .s+   .y+   .l+     .h+
  464.  
  465. y+   .l+        .q+
  466.  
  467. If the file x.o  was needed and there  was an x.c  in the description  or
  468. directory, it would be  compiled.  If the  file x.o was needed and  there
  469. was an x.c+ in  the description or  directory, it would  be restored  and
  470.  
  471. -------------------------------- Page  9 --------------------------------
  472.  
  473. then compiled.   If there were  also an  x.l, that grammar  would be  run
  474. through Lex before compiling the result.   However, if there were no  x.c
  475. but there were  an x.l,  make would discard  the intermediate C  language
  476. file and use the direct link in the graph above.
  477.  
  478. It is possible to change the names of some  of the compilers used in  the
  479. default, or the flag arguments with which they are invoked by knowing the
  480. macro names used.  The compiler names are  the macros AS, CC, F77,  YACC,
  481. QS, and LEX.  The command
  482.  
  483.      make CC=newcc
  484.  
  485. will cause the 'newcc'  command to be  used instead of  the usual C  com-
  486. piler.  The macros CFLAGS, FFLAGS, QFLAGS, YFLAGS, and LFLAGS may  be set
  487. to cause these commands to be issued with optional flags.  Thus,
  488.  
  489.      make "CFLAGS=-O"
  490.  
  491. causes the optimizing C compiler to be used.
  492.  
  493.  
  494.  
  495.  
  496. 7.    EXAMPLE
  497.  
  498. As an example of the  use of make, we will  present the description  file
  499. that maintains the make command itself.  The code for make is spread over
  500. several C source files  and a  yacc grammar.  The  description file  con-
  501. tains:
  502.  
  503. -------------------------------- Page 10 --------------------------------
  504.  
  505. #
  506. # Description file for the "make" command
  507. #
  508.  
  509. OBJECTS = main.o doname.o misc.o files.o dosys.o gram.o
  510. LIBES=
  511. LINT = lint  -pxa
  512. CC = cc
  513. CFLAGS= -O -n
  514. I = /usr/include
  515.  
  516. nmake:  $(OBJECTS)
  517.         $(CC)   $(CFLAGS) $(OBJECTS) $(LIBES) -o nmake
  518.  
  519. /bin/make:       nmake
  520.         /etc/instcmd nmake /bin/make
  521.         rm $(OBJECTS)
  522.  
  523. doname.o:       doname.c        defs $I/stdio.h $I/ctype.h \
  524.                                 $I/sys/types.h
  525.         $(CC) $(CFLAGS) -c -TR2 doname.c
  526. dosys.o:        dosys.c         defs $I/stdio.h $I/ctype.h \
  527.                                 $I/sys/types.h $I/signal.h $I/errno.h \
  528.                                 $I/sys/stat.h
  529. files.o:        files.c         defs $I/stdio.h $I/ctype.h \
  530.                                 $I/sys/types.h $I/sys/stat.h \
  531.                                 $I/pwd.h $I/ar.h $I/a.out.h \
  532.                                 $I/sys/stat.h $I/dir.h
  533. gram.o:         gram.y          defs $I/stdio.h $I/ctype.h \
  534.                                 $I/sys/types.h
  535. misc.o:         misc.c          defs $I/stdio.h $I/ctype.h \
  536.                                 $I/sys/types.h
  537.  
  538. lint :  dosys.c doname.c files.c main.c misc.c ident.c gram.c
  539.         $(LINT) dosys.c doname.c files.c main.c misc.c ident.c gram.c
  540.         rm gram.c
  541.  
  542. Make usually prints out  each command before  issuing it.  The  following
  543. output results from typing the simple command
  544.  
  545.      make
  546.  
  547. in a directory containing only  the save/restore source and the  descrip-
  548. tion file:
  549.  
  550.  
  551.         rest main.c
  552.         cc -O -n -c main.c
  553.         rest doname.c
  554.  
  555. -------------------------------- Page 11 --------------------------------
  556.  
  557.         cc -O -n -c -TR2 doname.c
  558.         rest misc.c
  559.         cc -O -n -c misc.c
  560.         rest files.c
  561.         cc -O -n -c files.c
  562.         rest dosys.c
  563.         cc -O -n -c dosys.c
  564.         rest gram.y
  565.         yacc  gram.y
  566.         cc -O -n -c y.tab.c
  567.         rm y.tab.c
  568.         mv y.tab.o gram.o
  569.         cc   -O -n main.o doname.o misc.o files.o dosys.o gram.o  -o nmake
  570.  
  571.  
  572. It is not necessary to include all  the file names and explicit  commands
  573. as make can find  them by using its suffix  rules and then it will  issue
  574. the needed commands.  However,  it is a  good idea to  be as explicit  as
  575. possible with dependencies and commands.
  576.  
  577. The first  few entries  in the  description file  are useful  maintenance
  578. sequences.  The 'nmake' entry is the default procedure and will  create a
  579. make program named  nmake in  the current  directory (to  avoid any  con-
  580. flicts).  The '/bin/make' entry depends on the nmake entry and will cause
  581. a new copy of make to be installed  in the '/bin' directory.  The  latter
  582. is done with the 'make /bin/make' command, the former with  either 'make'
  583. (with no arguments) or with 'make nmake'.
  584.  
  585.  
  586.  
  587.  
  588. 8.    SUGGESTIONS AND WARNINGS
  589.  
  590. The most common difficulties arise from make's specific meaning of depen-
  591. dency.  If file x.c  has a '#include  "defs"' line, then the object  file
  592. x.o depends on defs; the source file x.c does not.  (If defs is  changed,
  593. it is not necessary to do anything to the file x.c, while it is necessary
  594. to re-create x.o.)
  595.  
  596. To discover what make would do, the '-n' option is useful.  The command
  597.  
  598.      make -n
  599.  
  600. orders make to print out the commands  it would issue without taking  the
  601. time to execute them.  If a change to a file  is absolutely certain to be
  602. benign (e.g.,  adding a  new definition  to an  include file),  the  '-t'
  603. (touch) option can save much  time: instead of issuing a large number  of
  604.  
  605. -------------------------------- Page 12 --------------------------------
  606.  
  607. superfluous recompilations, make  updates the modification  times on  the
  608. affected file.  Thus, the command
  609.  
  610.      make -ts
  611.  
  612. ('touch silently') causes the relevant files to appear up to date.  Obvi-
  613. ous care is necessary, since  this mode of operation subverts the  inten-
  614. tion of make and destroys all memory of the previous relationships.
  615.  
  616. The debugging flag ('-d') causes make to print out a detailed description
  617. of what it is  doing, including the  file times.  The output is  verbose,
  618. and recommended only as a last resort.
  619.  
  620. The trace flag ('-z'), causes make to print its analysis of the  descrip-
  621. tion file.  It primarily notes implicit and explicit dependencies,  nest-
  622. ing, and implicit and explicit command executions.
  623.  
  624.  
  625.  
  626.  
  627. 9.    SCCS FILES
  628.  
  629. When there exist dependencies on SCCS files, one would ideally like  make
  630. to do  "gets", do  the  necessary compiles  and other  actions, and  then
  631. remove the "gotten" file.  However, because of make's current prefix  and
  632. suffix limitations, such capabilities are not entirely available.  Make's
  633. SCCS capabilities are limited.   It is recommended  that dependencies  be
  634. kept simple; use of explicit commands is encouraged.  One-step  transfor-
  635. mation path "gets" can be handled implicitly, however.
  636.  
  637. Specifically, try such constructions as:
  638.  
  639.                    frog.o:  frog.c
  640.                    frog.c:  s.frog.c
  641.  
  642.  
  643. The following will not work correctly:
  644.  
  645.                    frog.o:  s.frog.c
  646.           or
  647.                    frog.o:  frog.c
  648.  
  649.                             where frog.c does not exist
  650.                             and s.frog.c does
  651.  
  652. -------------------------------- Page 13 --------------------------------
  653.  
  654. 10.   ACKNOWLEDGMENTS
  655.  
  656. I would like to thank S. C. Johnson for suggesting this approach to  pro-
  657. gram maintenance control.   I would like  to thank S.  C. Johnson and  H.
  658. Gajewska for being the prime guinea pigs during development of make.
  659.  
  660.  
  661.  
  662.  
  663. 11.   REFERENCES
  664.  
  665.  [1]  S. C. Johnson, Yacc -- Yet Another Compiler-Compiler,
  666.  
  667.  [2]  M. E. Lesk, Lex -- A Lexical Analyzer Generator.
  668.  
  669. -------------------------------- Page 14 --------------------------------
  670.  
  671. APPENDIX A.    SUFFIXES AND TRANSFORMATION RULES
  672.  
  673. The make  program  itself does  not  know what  file  name  suffixes  are
  674. interesting or how to transform  a file with one suffix into a file  with
  675. another suffix.  This information is stored in an internal table that has
  676. the form of a description file.  If the '-r' flag  is used, this table is
  677. not used.
  678.  
  679. The list of suffixes is  really the dependency list  for the name  '.SUF-
  680. FIXES'; make looks for a  file with any of the suffixes on the list.   If
  681. such a file exists, and if there is a transformation rule for that combi-
  682. nation, make acts  as described earlier.   The transformation rule  names
  683. are the  concatenation of  the two  suffixes.  The  name of  the rule  to
  684. transform a '.r'  file to  a '.o' file  is thus '.r.o'.   If the rule  is
  685. present and no explicit  command sequence  has been given  in the  user's
  686. description files, the command sequence for the rule '.r.o' is  used.  If
  687. a command is generated by using one  of these suffixing rules, the  macro
  688. $* is given the value of the stem (everything but the suffix) of the name
  689. of the file to be  made, and the macro  $< is the  name of the  dependent
  690. that caused the action.
  691.  
  692. The order of the  suffix list is  significant, since it  is scanned  from
  693. left to right, and the first name that is formed that has both a file and
  694. a rule associated with it is used.  If new names are to be appended,  the
  695. user can just add an  entry for '.SUFFIXES' in his own description  file;
  696. the dependents  will be  added to  the usual  list.  A  '.SUFFIXES'  line
  697. without any dependents  deletes the  current list.  (It  is necessary  to
  698. clear the current list if the order of names is to be changed.)
  699.  
  700. The following is an excerpt from the default rules file:
  701.  
  702.            .SUFFIXES : .o .q .q+ .y  .y+ .l .l+ .f .f+ .c .c+ .s .s+ .h .h+ .t
  703.            YACC=yacc
  704.            YFLAGS=
  705.            LEX=lex
  706.            LFLAGS=
  707.            CC=cc
  708.            AS=as
  709.            CFLAGS=
  710.            F77=f77
  711.            FFLAGS=
  712.            .c.o :
  713.                   $(CC) $(CFLAGS) -c $<
  714.            .s.o :
  715.                   $(AS) -o $@ $<
  716.            .y.o :
  717.                   $(YACC) $(YFLAGS) $<
  718.                   $(CC) $(CFLAGS) -c y.tab.c
  719.                   rm y.tab.c
  720.  
  721. -------------------------------- Page 15 --------------------------------
  722.  
  723.                   mv y.tab.o $@
  724.            .y.c :
  725.                   $(YACC) $(YFLAGS) $<
  726.                   mv y.tab.c $@
  727. -------
  728.