home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / languages / northc_384 / bin / make.doc < prev    next >
Text File  |  1990-09-04  |  11KB  |  303 lines
  1.  
  2.   (c) 1990 S.Hawtin.
  3.   Permission is granted to copy this file and make provided that:
  4.    1) Neither are used for commercial gain
  5.    2) This notice is included in all copies
  6.    3) Altered copies are marked as such.
  7.    4) Each copy of make is accompanied by a copy of this file.
  8.  
  9.   No liability is accepted for the contents of the file.
  10.  
  11.   make.doc        within        make
  12.  
  13. MAKE
  14.     make [-fmakefile][-?][target]
  15.  
  16.   Maintain an up-to-date version of a program.  The options have the 
  17. following meanings
  18.  
  19. -f<makefile>
  20.  
  21.    Take the description from the file <makefile> rather than "Makefile".
  22.  
  23. -?
  24.  
  25.   Print out the commands that would be executed but do not perform them.
  26.  
  27. target
  28.  
  29.   Construct the file <target> rather than the first item in the makefile.
  30.  
  31.   The make command keeps programs up to date, it does this by reading a 
  32. file that describes how to construct a target program and executing all 
  33. the commands required to update the program.
  34.  
  35.   When using 'C' and other compiled languages it is normal to divide the 
  36. source code for a program into many files, this allows you to split the 
  37. code into logical chunks.  Most compiled languages allow you to recompile 
  38. each source file independently to produce an "object" file, the user then 
  39. combines all the object files to produce the actual program with a 
  40. "linker".  Whenever you alter a source file it must be recompiled and the 
  41. resulting "object" file must be relinked into the executable program, it 
  42. can be difficult to remember which files you have changed since the last 
  43. build and what set of tools need to be run on which programs.  The "make" 
  44. program works out which commands need to be executed to bring a program up 
  45. to date and executes them.
  46.  
  47.   An example will explain what the program does, assume you have a program 
  48. called "jim" that combines three source files, "foo.c", "bar.c" and 
  49. "baz.asm".  To use "make" in its simplest form you should create a file 
  50. called "Makefile" containing the lines
  51.  
  52.     jim : foo.o bar.o baz.o
  53.             blink with $*.blink
  54.  
  55. this tells the "make" program that "jim" depends on the object files 
  56. "foo.o", "bar.o" and "baz.o", and can be created by the CLI command "blink 
  57. with jim.blink".  You must now construct the file "jim.blink" that the 
  58. "blink" command requires, this is done by the CLI command
  59.  
  60.     make $*.blink
  61.  
  62. the "$*" construct will be explained later.
  63.  
  64.   Once the "Makefile" and "jim.blink" files have been created you can use 
  65. the "make" program to construct "jim", just type the command
  66.  
  67.     make
  68.  
  69. and it will call all the commands to make "jim".  Now if you change the 
  70. file "foo.c" and then type the "make" command it will only issue the 
  71. commands required to bring the program up to date, the program will not 
  72. bother to recompile "bar.c" or "baz.asm".
  73.  
  74.   So every time you change a set of the source files you just type "make" 
  75. and all the necessary compilations will be done.  This is well and good, 
  76. assuming we are only going to edit the ".c" and ".asm" files.  If however 
  77. if you change an include file you want "make" to recompile all the 'C' 
  78. source files that include it.  We get make to do this by adding some extra 
  79. lines into the "Makefile".  If the new "Makefile" contains
  80.  
  81.     jim : foo.o bar.o baz.o
  82.             blink with $*.blink
  83.  
  84.     foo.o: fubar.h foo.h
  85.  
  86.     bar.o : fubar.h
  87.  
  88. then every time "fubar.h" is altered "make" will recompile both "foo.c" 
  89. and "bar.c".  Notice that the three items "jim", "foo.o" and "bar.o" must 
  90. be separated by blank lines.  If we now change the file "fubar.h" then the 
  91. "make" command will recompile both "foo.c" and "bar.c".
  92.  
  93.   By default the "make" program always tries to construct the first item 
  94. in the "Makefile", this is why you must put the line
  95.  
  96.     foo.o: fubar.h
  97.  
  98. after
  99.  
  100.     jim : foo.o bar.o baz.o
  101.  
  102. if it was put in before then the "make" program would just make "foo.o" 
  103. and not "jim".  You can get "make" to construct a particular item by 
  104. telling it which target item you want to update, for example to make 
  105. "bar.o" just type the command
  106.  
  107.     make bar.o
  108.  
  109. we have already seen this being used when we created the "jim.blink" file.
  110.  
  111.   So, to summarise, each item in the "Makefile" starts with a file name, 
  112. then after the ':' a list of items that this item depends on, the 
  113. following lines, up to the first blank line, tell "make" the commands 
  114. required to construct the item.  Each item can appear on the left hand 
  115. side as many times as you want so long as you only specify the commands to 
  116. create it once.
  117.  
  118.   You can of course add comments into the "Makefile", any line that starts 
  119. with a '#' is treated as a comment.
  120.  
  121.   One problem you might come across is having too many dependencies to fit 
  122. on a single line, the '\' character tells "make" that the dependencies are 
  123. continued on the next line, so for example
  124.  
  125.     jim: foo.o \
  126.          bar.o \
  127.          baz.o
  128.             blink with $*.blink
  129.  
  130. is the same as the original entry for "jim".  The '\' character must be 
  131. the last character on the line.
  132.  
  133.   Sometimes you want to "make" an item every time you construct the 
  134. program, for example if you have a file "date.c" that consists of
  135.  
  136.     #include <stdio.h>
  137.  
  138.     print_date()
  139.        {/* Print the date the program was last compiled */
  140.         printf("This version was compiled on %s\n",__DATE__);
  141.         }
  142.  
  143. then even though the actual text of the source file does not change you 
  144. want to recompile it whenever the program is compiled.  You can force 
  145. "make" to always recompile this program by appending the special item 
  146. "always", for example by adding the item
  147.  
  148.     date.o : always
  149.  
  150. to the Makefile.  "always" is considered to be newer than everything 
  151. else.  The "__DATE__" macro is an ANSI C extension that returns a string 
  152. containing the compilation date.
  153.  
  154.   Although the "make" program knows how to convert a ".c" program into a 
  155. ".o" program you can override this by adding an item such as
  156.  
  157.     foo.o: foo.c
  158.             NorthC -I:incl/ foo.c
  159.             A68k foo.s
  160.             Delete foo.s
  161.  
  162. whenever "foo.c" is changed the given commands will be executed to create 
  163. "foo.o" rather than the normal commands.
  164.  
  165.   If you have a preferred way to convert ".c" files into ".o" files you 
  166. could type this in after every ".o" file, however "make" will also allow 
  167. you to define a "default" way to convert between the files, if you add the item 
  168.  
  169.     .c.o:
  170.             NorthC -I:incl/ $*.c
  171.             A68K $*.s
  172.             Delete $*.s
  173.  
  174. to the "Makefile" this item tells "make" to construct ".o" files from ".c" 
  175. files by calling the commands 
  176.  
  177.     NorthC -I:incl/ $*.c
  178.     A68K $*.s
  179.     Delete $*.s
  180.  
  181. The sequence "$*" is replaced by the base file name.  The base file name 
  182. consists of the name up to the final '.', so for example the base name of 
  183. "jim.2.c" is "jim.2".
  184.  
  185.   "make" will always add some default items to the end of the "Makefile", 
  186. if they do not clash with existing entries, the current default items are
  187.  
  188.     .c.o:
  189.             NorthC -Ot:$*.s $*.c
  190.             A68K -q -g -O$*.o t:$*.s
  191.             Delete t:$*.s
  192.  
  193.     .s.o:
  194.             A68K $*.s
  195.  
  196.     .asm.o:
  197.             A68K $*.asm
  198.  
  199. this tells the "make" program how to compile 'C' programs and assemble 
  200. ".asm" and ".s" files.
  201.  
  202.   You can use the default mechanism to create files with any extension of 
  203. up to four letters, for example
  204.  
  205.     .uil.uid:
  206.             Delete $*.uid
  207.             Motif:Uil/uil -o $*.uid $*.uil
  208.  
  209. tells "make" that each time it finds a reference to a file such as 
  210. "jim.uid" it should construct the file with the commands
  211.  
  212.     Delete jim.uid
  213.     Motif:Uil/uil -o jim.uid jim.uil
  214.  
  215. whenever the "jim.uil" file is altered.
  216.  
  217.   You can split your "Makefile" into multiple files.  When you want to 
  218. read a file, for example "make.depends", just include the command
  219.  
  220.     $<make.depends>
  221.  
  222. in "Makefile".  Make will read the file "make.depends" at that point.
  223.  
  224.   If you wish to read a file other than "Makefile" when you call "make" 
  225. add the "-f" option, for example to read the dependencies from "jim.make"
  226.  
  227.     make -fjim.make
  228.  
  229. will make the first item in the file "jim.make".
  230.  
  231.   If you want to use the "top" optimiser you should add an item
  232.  
  233.     .c.o:
  234.             NorthC -Ot:$*.s $*.c
  235.             top t:$*.s t:$*.s1
  236.             a68k -g -q -O$*.o t:$*.s
  237.             delete t:$*.s t:$*.s1
  238.  
  239. into you makefile.
  240.  
  241.  
  242. How Make Works
  243.  
  244.   You don't actually have to read this bit but it might help if you cannot 
  245. get "make" to do something complicated.
  246.  
  247.   The "make" command works by creating a dependency tree, for example the sequence
  248.  
  249.     jim: foo.o bar.o baz.o
  250.             blink with $*.blink
  251.  
  252.     foo.o: fubar.h foo.h
  253.  
  254.     bar.o: fubar.h
  255.  
  256. will create a dependency tree
  257.  
  258.                            jim
  259.                           / | \
  260.                          /  |  \
  261.                         /   |   \
  262.                        /    |    \
  263.                   foo.o   bar.o   baz.o
  264.                    |  \   /
  265.                    | fubar.h
  266.                    |
  267.                  foo.h
  268.  
  269. "make" then scans this tree to find items that have no create command 
  270. sequence defined.  Any item that we have not yet been told how to make 
  271. will either be a source file, for example "foo.h" or we will have to find 
  272. out how to make it from the defaults list.  So make will now scan the 
  273. tree, when it comes to "foo.o" it discovers that it has a method for 
  274. creating ".o" files from ".c" files, and a ".c" file exists, so it adds 
  275. the default ".c.o" create method to "foo.o" and adds "foo.c" to its 
  276. dependencies.  When it comes to the file "bar.o" because it cannot find 
  277. "bar.c" it looks further down the list of defaults and finds that a 
  278. "bar.asm" file exists.  Once the tree has been scanned it looks like
  279.  
  280.                            jim
  281.                           / | \
  282.                          /  |  \
  283.                         /   |   \
  284.                        /    |    \
  285.                   foo.o   bar.o   baz.o
  286.                  / |  \   /  \      |
  287.             foo.c  | fubar.h  \   baz.asm
  288.                    |           \
  289.                  foo.h        bar.c
  290.  
  291. "make" then goes over this tree to see if any item is older than one of 
  292. its dependencies, when it finds such an item it adds the commands for 
  293. creating this item to an intermediate file in the "t:" directory.
  294.  
  295.   Once it has gone over the tree it calls the AmigaDOS command "execute" 
  296. to run the created command file, I have to call this function because I 
  297. want "make" to stop as soon as one of the commands fails.  I cannot find 
  298. out how to determine the return code of a called program, if anyone out 
  299. there can tell me how to do this please get in touch.
  300.  
  301.   The last thing the program does is to delete the command file it created 
  302. in the "t:" directory.
  303.