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