home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsm / makatic / Docs / !Help next >
Encoding:
Text File  |  1996-01-19  |  9.3 KB  |  368 lines
  1.     Makatic tools release 1.00 19 Jan 1996
  2.     ••••••••••••••••••••••••••••••••••••••
  3.  
  4.  
  5.  
  6. Contents
  7. ————————
  8.  
  9.     Introduction
  10.     Makatic.Maktic2
  11.     Makatic scripts
  12.     Example projects
  13.     Projects with sub-makefiles
  14.     Files in the Makatic directory
  15.     Motivation for Makatic
  16.     Other things
  17.  
  18.  
  19.  
  20. Introduction
  21. ————————————
  22.  
  23.     Makatic is a set of command-line tools which can automate much
  24.     of the management of C, C++ and Assembler projects.
  25.     
  26.     The Makatic tools automatically generate and run makefiles, by 
  27.     looking for source files in the project directory, and adding 
  28.     equivalent .o filenames to a user-supplied template makefile. 
  29.     
  30.     This means that adding or removing a source-file to a project 
  31.     doesn't mean one has to edit a makefile, or inform a desktop 
  32.     front-end such as '!Make' about the change.
  33.     
  34.     This is particularly helpful with large projects, particularly
  35.     if they involve building different versions of a project from
  36.     the same source code.
  37.     
  38.     Makatic needs a tool to run the makefiles. It has only been
  39.     tested with Acorn's AMU program, but should work with other
  40.     similar programs. 
  41.     
  42.     
  43.     Tool names
  44.     ¨¨¨¨¨¨¨¨¨¨
  45.     
  46.         To avoid clashes with other tool names, all Makatic
  47.         tools are within the 'Makatic' directory and you should
  48.         move the whole directory into your Run$Path (instead of
  49.         moving the individual Makatic tools into your 
  50.         Run$Path).
  51.         
  52.         This means that Makatic tools should be called with 
  53.         (for example) 'Makatic.Makatic2 <parameters>'.
  54.  
  55.  
  56.  
  57. Makatic.Makatic2
  58. ————————————————
  59.  
  60.     This is the core tool. It takes a fair number of flags and 
  61.     parameters (which are described if you run 
  62.     'Makatic.Makatic2 -help'), so there are some simple Obey 
  63.     scripts in the 'Makatic' directory which implement the 
  64.     functionality required for some standard project-types.
  65.     
  66.     'Makatic.Makatic2' will preserve dynamic dependancies in an
  67.     existing makefile, and an existing makefile is only replaced if
  68.     the new version is different.
  69.     
  70.     The generated makefile can be automatically run after it is
  71.     created - this facility is used by the Obey scripts.
  72.  
  73.  
  74.  
  75. Makatic scripts
  76. ———————————————
  77.  
  78.     Makatic.Small
  79.     ¨¨¨¨¨¨¨¨¨¨¨¨¨
  80.         Builds small projects with a single output file.
  81.     
  82.     Makatic.Medium
  83.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  84.         This handles more complicated projects which can be 
  85.         built in different ways, by sending different flags to 
  86.         cc and link. Each different build is put in its own 
  87.         subdirectory within the project directory.
  88.     
  89.     Makatic.Large
  90.     ¨¨¨¨¨¨¨¨¨¨¨¨¨    
  91.         This is similar to 'Makatic.Medium' except that it 
  92.         automatically deals with source files nested to any 
  93.         depth within the project directory.
  94.     
  95.     
  96.     
  97.     Notes on using <Obey$Dir>
  98.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  99.     
  100.         All three scripts require the project directory to 
  101.         passed as the first parameter. This causes a small 
  102.         problem if you pass <Obey$Dir> as this parameter, 
  103.         because the scripts are Obey file themselves. This 
  104.         means that by the time the script starts, <Obey$Dir> 
  105.         will be set to the Makatic tools directory.
  106.         
  107.         The example projects avoid this problem by setting a 
  108.         temporary CSD with Acorn's Prefix command, and passing 
  109.         '@' to the makatic script.
  110.         
  111.         An alternative would be to force the <Obey$Dir> to be 
  112.         expanded before the Makatic script is called. One way 
  113.         of doing this is as follows:
  114.         
  115.         1.    Put the following in your !Boot file:
  116.                 Set Alias$Do Set Alias$Do2 %%*0 |m Do2 |mUnset Alias$Do2
  117.         
  118.         2.    Call Makatic scripts from an Obey file within 
  119.             the project directory with: 
  120.                 Do Makatic.Small <Obey$Dir>
  121.  
  122.  
  123.  
  124. Example projects
  125. ————————————————
  126.  
  127.     In 'Makatic.Examples.' are three example project-types, which 
  128.     use the three Obey scripts 'Makatic.Small', 'Makatic.Medium' 
  129.     and 'Makatic.Large'. These have all been written for use with 
  130.     Acorn's compiler, linker and AMU tool. 
  131.     
  132.     The scripts instruct Makatic2 to look for c., c++. and s. 
  133.     source code, but only .c code is present in these examples.
  134.     
  135.     Apart from the directory structure and source code, each 
  136.     project contains one or more very simple TaskObey files which 
  137.     build the project by calling one of the Makatic tools. All 
  138.     other files and directories required are automatically created
  139.     by Makatic.
  140.     
  141.     
  142.     Examples.Small
  143.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  144.         This is a simple 'Hello World' C project.
  145.         
  146.         Double-clicking 'MakeIt' builds the !RunImage in a 
  147.         taskwindow.
  148.     
  149.     
  150.     Examples.Medium
  151.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  152.         This is similar, except that different versions of the 
  153.         program can be built from the same source-code. 
  154.         '!Debug.!Run' and '!Normal.!Run' build the two 
  155.         versions.
  156.         
  157.         The .o and !RunImage files are built within 
  158.         '!Normal' and '!Debug'.
  159.     
  160.     
  161.     Examples.Large
  162.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  163.         This has an additional feature - source code can be 
  164.         anywhere within the 'Sources.' directory, in 
  165.         arbitrarily-deep subdirectories. This allows one to 
  166.         (for example) group related source files together in
  167.         a directory, and also to get around RISC OS's 77 file 
  168.         directory limit.
  169.         
  170.         As with 'Examples.Medium', '!Debug.!Run' and 
  171.         '!Normal.!Run' build the two versions of the project.
  172.  
  173.  
  174.  
  175.  
  176. Projects with sub-makefiles
  177. ———————————————————————————
  178.  
  179.     The script file 'Makatic.MultiBuild' handles large projects 
  180.     such as DeskLib which consist of sub-projects containing their 
  181.     own makefile.
  182.     
  183.     Unlike the other script files, there isn't an example of such a 
  184.     project in the Makatic distribution. Here is a brief 
  185.     description of the required directory structure:
  186.     
  187.     Project.
  188.         Libraries.
  189.             <sublib name>.
  190.                 c.
  191.                 c++.
  192.                 s.
  193.                 
  194.                 Automatically added by 
  195.                 'Makatic.MultiBuild <build type>':
  196.                 <build type>.
  197.                     o.
  198.                     Makefile
  199.         
  200.         <build type>.
  201.             TemplateMF    Template makefile for 
  202.                     sublibraries.
  203.             
  204.             TempalteAl    Template makefile for whole 
  205.                     library.
  206.             
  207.             All        Made by 'Makatic.MultiBuild 
  208.                     <build type>'.
  209.     
  210.     
  211.     If you are interested in using 'Makatic.MultiBuild', you will 
  212.     need to write two template makefiles for each build-type. 
  213.     TemplateMF is similar to the template used in Examples.Medium 
  214.     except that it doesn't have to link the .o files together, 
  215.     while 'TemplateAl' should use LibFile to join all the .o files 
  216.     together.
  217.     
  218.     I will be shortly releasing a preliminary version of my School 
  219.     RISC OS class-library which will show how to use 
  220.     'Makatic.MultiBuild'.
  221.  
  222.  
  223.  
  224.  
  225.  
  226. Files in the Makatic directory
  227. ——————————————————————————————
  228.  
  229.  
  230. Makatic.
  231.  
  232.         Tools
  233.         ¨¨¨¨¨
  234.         
  235.     Makatic2    General tool for constructing makefiles from 
  236.             template files and running the resulting
  237.             makefile.
  238.     
  239.     
  240.         Scripts
  241.         ¨¨¨¨¨¨¨
  242.     
  243.     Small        Obey-file frontend for Makatic for use with 
  244.             very simple projects.
  245.     
  246.     Medium        Obey-file frontend for Makatic for use with 
  247.             projects which can be built in different ways.
  248.     
  249.     Large        Obey-file frontend for Makatic for use with 
  250.             large projects whose source code is arranged 
  251.             in a tree of directories.
  252.     
  253.     
  254.     MultiBuild    Completely (re)builds a multi-sublibrary 
  255.             project.
  256.         
  257.     MultiLink    Used by MultiBuild to create the final library 
  258.             from all the .o files. Quicker than MultiBuild 
  259.             if no re-compilation is needed.
  260.         
  261.     _EnsureDir    Used internally by MultiBuild and MultiLink.
  262.     
  263.     
  264.     
  265.         Documentation and examples
  266.         ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  267.     Docs.
  268.     
  269.         
  270.         
  271.         !Help        This file.
  272.         
  273.         History        History of Makatic.
  274.         
  275.         
  276.         
  277.         Examples.    Example projects using the Makatic 
  278.                 system.
  279.             
  280.             
  281.             Small.        'Hello World' C program.
  282.             
  283.                 MakeIt        TaskObey file which 
  284.                         builds the program.
  285.             
  286.             
  287.             Medium.        'Hello World' with different 
  288.                     versions built from the same 
  289.                     source code using different 
  290.                     pre-processor #defines.
  291.                 
  292.                 !Debug.
  293.                     !Run    Builds debug-version
  294.                 
  295.                 !Normal
  296.                     !Run    Builds normal version.
  297.             
  298.             
  299.             Large.        'Hello World' with different 
  300.                     builds, and demonstrating the 
  301.                     use of different subdirectories 
  302.                     for source code.
  303.                 
  304.                 Sources.    All source code, in 
  305.                         arbitrary 
  306.                         sub-directories.
  307.                 
  308.                 !Normal        Builds normal version.
  309.                 !Debug        Builds debug version.
  310.                     
  311.                     Sources.    Automatically-
  312.                             created 
  313.                             duplicate of 
  314.                             'Large.Sources.'
  315.                             tree, for 
  316.                             compiled .o 
  317.                             files.
  318.  
  319.  
  320.  
  321.  
  322.  
  323. Motivation for Makatic
  324. ——————————————————————
  325.  
  326.     After finding that Acorn's !Make program didn't support 
  327.     building different versions of a project from the same source 
  328.     code, and was generally a pain to use, I used hand-written 
  329.     makefiles for all my projects.
  330.     
  331.     When I became the moderator of DeskLib, the need for a way of 
  332.     automating the generation of makefiles became apparent, so 
  333.     the first version of Makatic was written. This was included in 
  334.     DeskLib 2.30 .
  335.     
  336.     The much improved 'Makatic.Makatic2' was written so that many 
  337.     different types of projects could be supported. In particular, 
  338.     'Makatic.Large' is a great help for everyday project 
  339.     management.
  340.  
  341.  
  342.  
  343.  
  344.  
  345. Other things
  346. ————————————
  347.  
  348.     The contents of the Makatic directory are Freeware and 
  349.     Copyright Julian Smith 1996. They may not be used in connection 
  350.     with any profit-making activity without my prior permission.
  351.     
  352.     I hope you find Makatic a useful set of tools.
  353.     
  354.     If you have any comments or suggestions about Makatic, I'd be 
  355.     very pleased to hear about them. I can be contacted at the address 
  356.     below
  357.  
  358.  
  359.  
  360. - Julian Smith
  361.  
  362.  
  363.  ---------------------------------------------------------------------------
  364.  Julian Smith                              Dept of Experimental Psychology
  365.  julian.smith@psy.ox.ac.uk                 South Parks Road, Oxford, OX1 3UD
  366.  http://cogsci1.psych.ox.ac.uk/~julians/   UK
  367.  ---------------------------------------------------------------------------
  368.