home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / projects / makatic_2 / Makatic / Docs / !Help next >
Encoding:
Text File  |  1997-02-14  |  17.8 KB  |  628 lines
  1.     Makatic tools release 2.20 14 Feb 1997
  2.     ••••••••••••••••••••••••••••••••••••••
  3.  
  4.  
  5.  
  6. Contents
  7. ————————
  8.  
  9.     Important
  10.     Introduction
  11.     Makatic.Makatic2
  12.     Makatic scripts
  13.     Example projects
  14.     Projects with sub-makefiles
  15.     Files in the Makatic directory
  16.     Motivation for Makatic
  17.     Problems
  18.     And finally...
  19.  
  20.  
  21.  
  22.  
  23. Important
  24. —————————
  25.  
  26.     The behaviour of the scripts Makatic.Small/Medium/Large has been changed
  27.     slightly between Makatic 2.07 and Makatic 2.08
  28.     
  29.     See 'Makatic.Docs.History' for details of the change.
  30.  
  31.  
  32. Introduction
  33. ————————————
  34.  
  35.     Makatic is a set of freeware command-line tools which can
  36.     automate much of the management of C, C++ and Assembler
  37.     projects.
  38.     
  39.     The Makatic tools automatically generate and run makefiles, by 
  40.     looking for source files in the project directory, and adding 
  41.     equivalent .o filenames to a user-supplied template makefile. 
  42.     
  43.     This means that adding or removing a source-file to a project 
  44.     doesn't mean one has to edit a makefile, or inform a desktop 
  45.     front-end such as '!Make' about the change.
  46.     
  47.     This is particularly helpful with large projects, particularly
  48.     if they involve building different versions of a project from
  49.     the same source code.
  50.     
  51.     Makatic needs a tool to run the makefiles. It has only been
  52.     tested with Acorn's AMU program, but should work with other
  53.     similar programs. 
  54.     
  55.     
  56.     Tool names
  57.     ¨¨¨¨¨¨¨¨¨¨
  58.     
  59.         To avoid clashes with other tool names, all Makatic
  60.         tools are within the 'Makatic' directory and you should
  61.         move the whole directory into your Run$Path (instead of
  62.         moving the individual Makatic tools into your 
  63.         Run$Path).
  64.         
  65.         This means that Makatic tools should be called with 
  66.         (for example) 'Makatic.Makatic2 <parameters>'.
  67.     
  68.     
  69.     Wot - no Desktop front-end?
  70.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  71.     
  72.         Makatic doesn't have a desktop interface.
  73.         
  74.         A desktop-only interface would be no use if you want to
  75.         (for example) control Makatic from a script. By
  76.         contrast, CLI tools are ideal for this sort of thing,
  77.         and don't take up memory when they aren't running.
  78.         
  79.         Moreover, it would be very easy to add a desktop
  80.         frontend to the existing CLI tools in the future. Making
  81.         a CLI tool from a desktop application is much more
  82.         tricky.
  83.         
  84.         Putting simple TaskObey scripts in a project directory 
  85.         (as in the example projects) which call the Makatic 
  86.         tools, enables one to double-click on Filer icons to 
  87.         build the project, providing a crude Wimp interface. I
  88.         have used this system for a while, and haven't felt the
  89.         need for a proper Wimp application.
  90.         
  91.         However, if anyone writes a desktop front-end (eg using
  92.         Acorn's FrontEnd system), I'd be interested in including
  93.         it in future releases of Makatic.
  94.  
  95.  
  96.  
  97. Makatic.Makatic2
  98. ————————————————
  99.  
  100.     This is the core tool. It takes a fair number of flags and 
  101.     parameters (which are described if you run 
  102.     'Makatic.Makatic2 -help'), so there are some simple Obey 
  103.     scripts in the 'Makatic' directory which implement the 
  104.     functionality required for some standard project-types.
  105.     
  106.     'Makatic.Makatic2' will preserve dynamic dependancies in an
  107.     existing makefile, and an existing makefile is only replaced if
  108.     the new version is different.
  109.     
  110.     In addition, if run with the '-D' flag, 'Makatic.Makatic2' will
  111.     remove any dynamic dependancies which refer to non-existant
  112.     files. This is useful when one removes or renames a header file
  113.     - AMU complains if it can't find such a file, so one used to
  114.     have to remove all the offending dynamic dependancies by hand.
  115.     
  116.     The generated makefile can be automatically run after it is
  117.     created - this facility is used by the Obey scripts.
  118.     
  119.     Wild-carded filename specifications are slightly more general
  120.     than as described by 'Makatic2 -help'. Each specification
  121.     consists of a space-separated list of matches, optionally
  122.     followed by ' -x ' and a space separated list of wild filenames
  123.     to omit. If you use this multiple-spec facility, everything
  124.     must be enclosed in quotes. Thus:
  125.     
  126.         Makatic.Makatic2 ... -f "..c.* ..c++.* -x .._* ..*~" ...
  127.     
  128.     - would match every .c and .c++ file, except for those whose
  129.     leafname starts with a '_' or ends with a '~'.
  130.     
  131.     Note that Makatic2 will ignore all files inside 'RCS'
  132.     directories. This feature dates back to when Makatic2 didn't
  133.     have the above -x option for filename specs, and may be removed
  134.     in future releases.
  135.  
  136.  
  137.  
  138. Makatic scripts
  139. ———————————————
  140.  
  141.     Makatic.Small
  142.     ¨¨¨¨¨¨¨¨¨¨¨¨¨
  143.         Builds small projects with a single output file.
  144.     
  145.     Makatic.Medium
  146.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  147.         This handles more complicated projects which can be 
  148.         built in different ways, by sending different flags to 
  149.         cc and link. Each different build is put in its own 
  150.         subdirectory within the project directory.
  151.     
  152.     Makatic.Large
  153.     ¨¨¨¨¨¨¨¨¨¨¨¨¨    
  154.         This is similar to 'Makatic.Medium' except that it 
  155.         automatically deals with source files nested to any 
  156.         depth within the project directory, allowing the use
  157.         of directories to partition source code.
  158.     
  159.     
  160.     
  161.     Notes on using <Obey$Dir>
  162.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  163.     
  164.         All three scripts require the project directory to 
  165.         passed as the first parameter. This causes a small 
  166.         problem if you pass <Obey$Dir> as this parameter, 
  167.         because the scripts are Obey file themselves. This 
  168.         means that by the time the script starts, <Obey$Dir> 
  169.         will be incorrectly set to the Makatic tools directory.
  170.         
  171.         The example projects avoid this problem by setting a 
  172.         temporary CSD with Acorn's Prefix command, and passing 
  173.         '@' to the makatic script.
  174.         
  175.         An alternative would be to force the <Obey$Dir> to be 
  176.         expanded before the Makatic script is called. One way 
  177.         of doing this is as follows:
  178.         
  179.         1.    Put the following in your !Boot file:
  180.                 Set Alias$Do Set Alias$Do2 %%*0 |m Do2 |mUnset Alias$Do2
  181.         
  182.         2.    Call Makatic scripts from an Obey file within 
  183.             the project directory with: 
  184.                 Do Makatic.Small <Obey$Dir>
  185.  
  186.  
  187.  
  188. Makatic.ArgsFile
  189. ————————————————
  190.  
  191.     This is a simple command-line tool which runs a given command,
  192.     passing the contents of a specified file as parameters.
  193.     
  194.     This enables one to run commands which are longer than the CLI's
  195.     256 character limit from Obey files.
  196.     
  197.     Note that the command has to use the long-command-string
  198.     DDEUtils SWIs. The Shared C Library does this, so any
  199.     application written in C (such as Makatic2) will do this
  200.     automatically.
  201.     
  202.     Makatic.ArgsFile is useful if you want to call Makatic with long
  203.     sequencies of '-f filespec replace' parameters.
  204.  
  205.  
  206.  
  207. Example projects
  208. ————————————————
  209.  
  210.     In 'Makatic.Examples.' are three example project-types, which 
  211.     use the three Obey scripts 'Makatic.Small', 'Makatic.Medium' 
  212.     and 'Makatic.Large'. These have all been written for use with 
  213.     Acorn's compiler, linker and AMU tool. 
  214.     
  215.     The Makatic scripts instruct Makatic2 to look for c., c++. and
  216.     s. source code, and the template makefiles have rules for
  217.     assembling .s and compiling .c++ files, but only .c code is
  218.     present in these examples, apart from Examples.Large++.
  219.     
  220.     Apart from the directory structure and source code, each 
  221.     project contains one or more very simple TaskObey files which 
  222.     build the project by calling one of the Makatic tools. All 
  223.     other files and directories required are automatically created
  224.     by Makatic.
  225.     
  226.     
  227.     Examples.Small
  228.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  229.         This is a simple 'Hello World' C project.
  230.         
  231.         Double-clicking 'MakeIt' builds the !RunImage in a 
  232.         taskwindow.
  233.     
  234.     
  235.     Examples.Medium
  236.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  237.         This is similar, except that different versions of the 
  238.         program can be built from the same source-code. 
  239.         '!Debug.!Run' and '!Normal.!Run' build the two 
  240.         versions.
  241.         
  242.         The .o and !RunImage files are built within 
  243.         '!Normal' and '!Debug'.
  244.     
  245.     
  246.     Examples.Large
  247.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  248.         This has an additional feature - source code can be 
  249.         anywhere within the 'Sources.' directory, in 
  250.         arbitrarily-deep subdirectories. This allows one to 
  251.         (for example) group related source files together in
  252.         a directory, and also to get around RISC OS's 77 file 
  253.         directory limit.
  254.         
  255.         As with 'Examples.Medium', '!Debug.!Run' and 
  256.         '!Normal.!Run' build the two versions of the project.
  257.     
  258.     
  259.     Examples.Large++
  260.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  261.         This is similar to Examples.Large, except that it uses a
  262.         both c++ and c source files.
  263.         
  264.         It also overcomes a bug in Acorn's c++ compiler 3.1 [May
  265.         25 1995] which means that the compiler always outputs to
  266.         'o.<input leafname>', ignoring any '-o <output file>'
  267.         parameter, and also uses the incorrect .o filename in
  268.         any !Depend file.
  269.         
  270.         This is done by replacing the call to c++ with a call to
  271.         'Makatic._C++'. See 'Problems' below.
  272.         
  273.         Note that there is an empty .o directory ready for c++'s
  274.         incorrect output file.
  275.     
  276.     
  277.     Examples.TestLib
  278.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  279.         This is an extremely simple C library, with a factorial
  280.         function. There are two different builds of the    library.
  281.  
  282.  
  283.  
  284.  
  285. Projects with sub-makefiles
  286. ———————————————————————————
  287.  
  288.     The script file 'Makatic.MultiBuild' handles large projects 
  289.     such as DeskLib which consist of sub-projects containing their 
  290.     own makefile.
  291.     
  292.     Unlike the other script files, there isn't an example of such a 
  293.     project in the Makatic distribution. Here is a brief 
  294.     description of the required directory structure:
  295.     
  296.     Project.
  297.         Libraries.
  298.             <sublib name>.
  299.                 c.
  300.                 c++.
  301.                 s.
  302.                 
  303.                 Automatically added by 
  304.                 'Makatic.MultiBuild <build type>':
  305.                 <build type>.
  306.                     o.
  307.                     Makefile
  308.         
  309.         <build type>.
  310.             TemplateMF    Template makefile for 
  311.                     sublibraries.
  312.             
  313.             TempalteAl    Template makefile for whole 
  314.                     library.
  315.             
  316.             All        Made by 'Makatic.MultiBuild 
  317.                     <build type>'.
  318.     
  319.     
  320.     If you are interested in using 'Makatic.MultiBuild', you will 
  321.     need to write two template makefiles for each build-type. 
  322.     TemplateMF is similar to the template used in Examples.Medium 
  323.     except that it doesn't have to link the .o files together, 
  324.     while 'TemplateAl' should use LibFile to join all the .o files 
  325.     together.
  326.     
  327.     I will be shortly releasing a preliminary version of my School 
  328.     RISC OS class-library which will show how to use 
  329.     'Makatic.MultiBuild'. Future releases of DeskLib are also likely
  330.     to use Makatic.
  331.  
  332.  
  333.  
  334.  
  335.  
  336. Files in the Makatic directory
  337. ——————————————————————————————
  338.  
  339.  
  340. Makatic.
  341.  
  342.         Tools and scripts
  343.         ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  344.         
  345.     Makatic2    General tool for constructing makefiles from 
  346.             template files and running the resulting
  347.             makefile.
  348.     
  349.     Small        Obey-file frontend for Makatic for use with 
  350.             very simple projects.
  351.     
  352.     Medium        Obey-file frontend for Makatic for use with 
  353.             projects which can be built in different ways.
  354.     
  355.     Large        Obey-file frontend for Makatic for use with 
  356.             large projects whose source code is arranged 
  357.             in a tree of directories.
  358.     
  359.     MultiBuild    Completely (re)builds a multi-sublibrary 
  360.             project.
  361.         
  362.     MultiLink    Used by MultiBuild to create the final library 
  363.             from all the .o files. Quicker than MultiBuild 
  364.             if no re-compilation is needed.
  365.     
  366.     MultiMFs    Remakes all makefiles for a multi-sublibrary
  367.             project, but doesn't run them.
  368.     
  369.     MultiILink    Makes LibFile add only newer .o files to the
  370.             library.
  371.     
  372.     MultiMF        Re-makes makefile for a single sub-library.
  373.         
  374.     _EnsureDir    Used internally by MultiBuild and MultiLink.
  375.     
  376.     _C++        Wrapper for c++, to enable bug-fix to Acorn c++.
  377.     
  378.     Every2        Tool used by Multi* scripts. Runs a specified
  379.             command on all files matching a wild-carded
  380.             specification.
  381.     
  382.     ArgsFile    Simple tool allowing running of commands with
  383.             more than 256 characters in the complete
  384.             command, when DDEUtils is running.
  385.         
  386.     CmdFile        Similar to ArgsFile, except that the given file
  387.             should include the command itself.
  388.     
  389.     
  390.         Documentation and examples
  391.         ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  392.     Docs.
  393.     
  394.         
  395.         
  396.         !Help        This file.
  397.         
  398.         History        History of Makatic.
  399.         
  400.         
  401.         
  402.         Examples.    Example projects using the Makatic 
  403.                 system.
  404.             
  405.             
  406.             Small.        'Hello World' C program.
  407.             
  408.                 MakeIt        TaskObey file which 
  409.                         builds the program.
  410.                 
  411.                 TemplateMF    Template makefile.
  412.             
  413.             
  414.             Medium.        'Hello World' with different 
  415.                     versions built from the same 
  416.                     source code using different 
  417.                     pre-processor #defines.
  418.                 
  419.                 !Debug.
  420.                     !Run    Builds debug-version
  421.                 
  422.                 !Normal
  423.                     !Run    Builds normal version.
  424.                 
  425.                 TemplateMF    Template makefile.
  426.             
  427.             
  428.             Large.        'Hello World' with different 
  429.                     builds, and demonstrating the 
  430.                     use of different subdirectories 
  431.                     for source code.
  432.                 
  433.                 Sources.    All source code, in 
  434.                         arbitrary 
  435.                         sub-directories.
  436.                 
  437.                 !Normal        Builds normal version.
  438.                 !Debug        Builds debug version.
  439.                     
  440.                     Sources.    Automatically-
  441.                             created 
  442.                             duplicate of 
  443.                             'Large.Sources.'
  444.                             tree, for 
  445.                             compiled .o 
  446.                             files.
  447.                 
  448.                 TemplateMF    Template makefile.
  449.             
  450.             
  451.             Large++.    As 'Large', but with c/c++
  452.                     source code.
  453.                 
  454.                 TemplateMF    Template makefile with
  455.                         a hack to get around
  456.                         a bug in Acorn's c++.
  457.                 
  458.                 !Normal.o    Directory for
  459.                         erroneously-placed
  460.                         files from c++.
  461.                 
  462.                 !Debug.o    Directory for
  463.                         erroneously-placed
  464.                         files from c++.
  465.             
  466.             TestLib.    Example C library with two
  467.                     different builds.
  468.  
  469.  
  470.  
  471.  
  472.  
  473. Makatic.Makatic3
  474. ————————————————
  475.     This is an alternative to Makatic.Makatic2. Instead of
  476.     specifying filenames in the command line, you put them into the 
  477.     template makefile. This avoids the problem of Makatic.Makatic2's
  478.     command lines sometimes becoming longer than 256 characters, and
  479.     is also rather more flexible.
  480.     
  481.     Running 'Makatic.Makatic3 -help' will give full details on the
  482.     syntax to be used within the template makefile.
  483.  
  484.  
  485. Motivation for Makatic
  486. ——————————————————————
  487.  
  488.     After finding that Acorn's !Make program didn't support 
  489.     building different versions of a project from the same source 
  490.     code, and was generally a pain to use, I used hand-written 
  491.     makefiles for all my projects.
  492.     
  493.     When I became the moderator of DeskLib, the need for a way of 
  494.     automating the generation of makefiles became apparent, so 
  495.     the first version of Makatic was written. This was included in 
  496.     DeskLib 2.30 .
  497.     
  498.     The much improved 'Makatic.Makatic2' was written so that many 
  499.     different types of projects could be supported. In particular, 
  500.     'Makatic.Large++' is a great help for everyday project 
  501.     management.
  502.  
  503.  
  504.  
  505.  
  506. Problems
  507. ————————
  508.  
  509.     Problems with ImageFSFix
  510.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  511.         There seems to be a bug in the ImageFSFix module used by
  512.         ArcFS, which breaks the system-call OS_GBPB (which
  513.         returns the files within a directory) when it is called
  514.         for a non-existent directory (if you're interested, when
  515.         ImageFSFix is present and the call is used for a
  516.         non-existant directory, it doesn't return an error, so
  517.         programs which use it treat the returned block as
  518.         containing data when, in fact, it contains garbage).
  519.         
  520.         The Makatic scripts instruct Makatic.Makatic2 to look
  521.         inside .c, .s and .c++ directories for source files, so
  522.         they used to crash with an address exception (or
  523.         similar) if these directories aren't present and
  524.         ImageFSFix is running. 
  525.         
  526.         I think I've managed to add a fix to Makatic2 which
  527.         works around the problem but, if you still have problems
  528.         problems, try putting empty .s and .c++ directories in
  529.         your project directory.
  530.         
  531.         Please let me know if you have this problem.
  532.         
  533.     
  534.     
  535.     Problems with Acorn's C++ compiler
  536.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  537.         
  538.         There is a bug in Acorn's C++ compiler 3.1 [May 25 1995]
  539.         which means that the compiler always outputs to
  540.         'o.<input leafname>', ignoring any '-o <output file>'
  541.         parameter.
  542.         
  543.         A second (probably related) problem is that any !Depend
  544.         file generated by Acorn's c++ contains the incorrect 
  545.         o.<input leafname> filename.
  546.         
  547.         These problems can be worked around using the tool
  548.         'Makatic._C++', as in 'Examples.Large++', and including
  549.         an empty .o directory for the incorrectly names .o
  550.         files.
  551.         
  552.         This is done by replacing the call to c++ with a call to
  553.         'Makatic._C++', using with the full c++ command
  554.         (including the 'c++ ' at the start) as parameters.
  555.         
  556.         'Makatic._C++' calls c++ first. When C++ returns,
  557.         'Makatic._C++' moves the .o file to the correct place, 
  558.         and any !Depend file is altered to contain the correct 
  559.         .o filename.
  560.         
  561.         See 'Docs.Examples.Large++.TemplateMF' to see this in
  562.         action.
  563.         
  564.         'Makatic._C++' is based on a program written by Mark
  565.         Seaborn.
  566.         
  567.     
  568.     Thanks go to Mark Seaborn for telling me about both of these
  569.     problems, and supplying code to fix things.
  570.     
  571.     
  572.     Problems with Wimpslot size and Acorn C++
  573.     ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  574.         
  575.         If a RISC OS program is started with an insufficient
  576.         Wimpslot, all sorts of bizarre errors can occur, such as
  577.         'Not enough memory to load shared C library', or plain
  578.         crashing of the application. This can happen even when
  579.         there is a large amount of free memory available,
  580.         because the problem occurs before the application has
  581.         started up properly. 
  582.         
  583.         The Makatic scripts all set a Wimpslot of 640k, which I
  584.         have found sufficient for nearly all cases.
  585.         
  586.         However, when using Acorn's C++ compiler, 640k is not
  587.         always enough. I think this is because of the way in
  588.         which c++ calls CFront and cc as child tasks, which
  589.         means that CFront and cc are started in an environment
  590.         which may not have a large amount of free memory
  591.         available initially (I assume c++ uses the ANSI C
  592.         'system()' function for this; Makatic._C++ certainly
  593.         does). 
  594.         
  595.         The problem is compounded by the use of 'Makatic._C++',
  596.         because this makes c++ itself a child process to be
  597.         started up in what is left of the initial wimpslot after
  598.         'Makatic._C++' has been loaded.
  599.         
  600.         If you have problems, I suggest you set a large Wimpslot
  601.         (eg 1000k) before using Makatic with c++. The TaskObey
  602.         files used to make the example project in
  603.         'Makatic.Docs.Examplesd.Large++.' do this already.
  604.  
  605.  
  606.  
  607.  
  608. And finally...
  609. ——————————————
  610.  
  611.     The contents of the Makatic directory are Freeware and 
  612.     Copyright Julian Smith 1996. They may not be used in connection
  613.     with any profit-making activity without my prior permission.
  614.     
  615.     The Makatic tools have no connection with Acorn.
  616.     
  617.     I hope you find Makatic a useful set of tools.
  618.     
  619.     If you have any comments or suggestions about Makatic, I'd be 
  620.     very pleased to hear about them. I can be contacted at the address 
  621.     below
  622.  
  623.  
  624.  
  625. - Julian Smith
  626.  
  627. jsmith@nc.acorn.co.uk
  628.