APDL Public Domain 1

home *** CD-ROM | disk | FTP | other *** search

/ APDL Public Domain 1 / APDL_PD1A.iso / program / c / makatic / Docs / !Help next >

Wrap

Text File | 1996-03-30 | 15.7 KB | 565 lines

Makatic tools release 2.10 30 Mar 1996 •••••••••••••••••••••••••••••••••••••• Contents ———————— Important Introduction Makatic.Maktic2 Makatic scripts Example projects Projects with sub-makefiles Files in the Makatic directory Motivation for Makatic Problems And finally... Important ————————— The behaviour of the scripts Makatic.Small/Medium/Large has been changed slightly since Makatic 2.07. See 'Makatic.Docs.History' for details of the change. Introduction ———————————— Makatic is a set of freeware command-line tools which can automate much of the management of C, C++ and Assembler projects. The Makatic tools automatically generate and run makefiles, by looking for source files in the project directory, and adding equivalent .o filenames to a user-supplied template makefile. This means that adding or removing a source-file to a project doesn't mean one has to edit a makefile, or inform a desktop front-end such as '!Make' about the change. This is particularly helpful with large projects, particularly if they involve building different versions of a project from the same source code. Makatic needs a tool to run the makefiles. It has only been tested with Acorn's AMU program, but should work with other similar programs. Tool names ¨¨¨¨¨¨¨¨¨¨ To avoid clashes with other tool names, all Makatic tools are within the 'Makatic' directory and you should move the whole directory into your Run$Path (instead of moving the individual Makatic tools into your Run$Path). This means that Makatic tools should be called with (for example) 'Makatic.Makatic2 <parameters>'. Wot - no Desktop front-end? ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ Makatic doesn't have a desktop interface. A desktop-only interface would be no use if you want to (for example) control Makatic from a script. By contrast, CLI tools are ideal for this sort of thing, and don't take up memory when they aren't running. Moreover, it would be very easy to add a desktop frontend to the existing CLI tools in the future. Making a CLI tool from a desktop application is much more tricky. Putting simple TaskObey scripts in a project directory (as in the example projects) which call the Makatic tools, enables one to double-click on Filer icons to build the project, providing a crude Wimp interface. I have used this system for a while, and haven't felt the need for a proper Wimp application. However, if anyone writes a desktop front-end (eg using Acorn's FrontEnd system), I'd be interested in including it in future releases of Makatic. Makatic.Makatic2 ———————————————— This is the core tool. It takes a fair number of flags and parameters (which are described if you run 'Makatic.Makatic2 -help'), so there are some simple Obey scripts in the 'Makatic' directory which implement the functionality required for some standard project-types. 'Makatic.Makatic2' will preserve dynamic dependancies in an existing makefile, and an existing makefile is only replaced if the new version is different. The generated makefile can be automatically run after it is created - this facility is used by the Obey scripts. Makatic scripts ——————————————— Makatic.Small ¨¨¨¨¨¨¨¨¨¨¨¨¨ Builds small projects with a single output file. Makatic.Medium ¨¨¨¨¨¨¨¨¨¨¨¨¨¨ This handles more complicated projects which can be built in different ways, by sending different flags to cc and link. Each different build is put in its own subdirectory within the project directory. Makatic.Large ¨¨¨¨¨¨¨¨¨¨¨¨¨ This is similar to 'Makatic.Medium' except that it automatically deals with source files nested to any depth within the project directory, allowing the use of directories to partition source code. Notes on using <Obey$Dir> ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ All three scripts require the project directory to passed as the first parameter. This causes a small problem if you pass <Obey$Dir> as this parameter, because the scripts are Obey file themselves. This means that by the time the script starts, <Obey$Dir> will be incorrectly set to the Makatic tools directory. The example projects avoid this problem by setting a temporary CSD with Acorn's Prefix command, and passing '@' to the makatic script. An alternative would be to force the <Obey$Dir> to be expanded before the Makatic script is called. One way of doing this is as follows: 1. Put the following in your !Boot file: Set Alias$Do Set Alias$Do2 %%*0 |m Do2 |mUnset Alias$Do2 2. Call Makatic scripts from an Obey file within the project directory with: Do Makatic.Small <Obey$Dir> Example projects ———————————————— In 'Makatic.Examples.' are three example project-types, which use the three Obey scripts 'Makatic.Small', 'Makatic.Medium' and 'Makatic.Large'. These have all been written for use with Acorn's compiler, linker and AMU tool. The Makatic scripts instruct Makatic2 to look for c., c++. and s. source code, and the template makefiles have rules for assembling .s and compiling .c++ files, but only .c code is present in these examples, apart from Examples.Large++. Apart from the directory structure and source code, each project contains one or more very simple TaskObey files which build the project by calling one of the Makatic tools. All other files and directories required are automatically created by Makatic. Examples.Small ¨¨¨¨¨¨¨¨¨¨¨¨¨¨ This is a simple 'Hello World' C project. Double-clicking 'MakeIt' builds the !RunImage in a taskwindow. Examples.Medium ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ This is similar, except that different versions of the program can be built from the same source-code. '!Debug.!Run' and '!Normal.!Run' build the two versions. The .o and !RunImage files are built within '!Normal' and '!Debug'. Examples.Large ¨¨¨¨¨¨¨¨¨¨¨¨¨¨ This has an additional feature - source code can be anywhere within the 'Sources.' directory, in arbitrarily-deep subdirectories. This allows one to (for example) group related source files together in a directory, and also to get around RISC OS's 77 file directory limit. As with 'Examples.Medium', '!Debug.!Run' and '!Normal.!Run' build the two versions of the project. Examples.Large++ ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ This is similar to Examples.Large, except that it uses a both c++ and c source files. It also overcomes a bug in Acorn's c++ compiler 3.1 [May 25 1995] which means that the compiler always outputs to 'o.<input leafname>', ignoring any '-o <output file>' parameter, and also uses the incorrect .o filename in any !Depend file. This is done by replacing the call to c++ with a call to 'Makatic._C++'. See 'Problems' below. Note that there is an empty .o directory ready for c++'s incorrect output file. Examples.TestLib ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ This is an extremely simple C library, with a factorial function. There are two different builds of the library. Projects with sub-makefiles ——————————————————————————— The script file 'Makatic.MultiBuild' handles large projects such as DeskLib which consist of sub-projects containing their own makefile. Unlike the other script files, there isn't an example of such a project in the Makatic distribution. Here is a brief description of the required directory structure: Project. Libraries. <sublib name>. c. c++. s. Automatically added by 'Makatic.MultiBuild <build type>': <build type>. o. Makefile <build type>. TemplateMF Template makefile for sublibraries. TempalteAl Template makefile for whole library. All Made by 'Makatic.MultiBuild <build type>'. If you are interested in using 'Makatic.MultiBuild', you will need to write two template makefiles for each build-type. TemplateMF is similar to the template used in Examples.Medium except that it doesn't have to link the .o files together, while 'TemplateAl' should use LibFile to join all the .o files together. I will be shortly releasing a preliminary version of my School RISC OS class-library which will show how to use 'Makatic.MultiBuild'. Future releases of DeskLib are also likely to use Makatic. Files in the Makatic directory —————————————————————————————— Makatic. Tools and scripts ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ Makatic2 General tool for constructing makefiles from template files and running the resulting makefile. Small Obey-file frontend for Makatic for use with very simple projects. Medium Obey-file frontend for Makatic for use with projects which can be built in different ways. Large Obey-file frontend for Makatic for use with large projects whose source code is arranged in a tree of directories. MultiBuild Completely (re)builds a multi-sublibrary project. MultiLink Used by MultiBuild to create the final library from all the .o files. Quicker than MultiBuild if no re-compilation is needed. MultiMFs Remakes all makefiles for a multi-sublibrary project, but doesn't run them. _EnsureDir Used internally by MultiBuild and MultiLink. _C++ Wrapper for c++, to enable bug-fix to Acorn c++. Every2 Tool used by Multi* scripts. Runs a specified command on all files matching a wild-carded specification. Documentation and examples ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ Docs. !Help This file. History History of Makatic. Examples. Example projects using the Makatic system. Small. 'Hello World' C program. MakeIt TaskObey file which builds the program. TemplateMF Template makefile. Medium. 'Hello World' with different versions built from the same source code using different pre-processor #defines. !Debug. !Run Builds debug-version !Normal !Run Builds normal version. TemplateMF Template makefile. Large. 'Hello World' with different builds, and demonstrating the use of different subdirectories for source code. Sources. All source code, in arbitrary sub-directories. !Normal Builds normal version. !Debug Builds debug version. Sources. Automatically- created duplicate of 'Large.Sources.' tree, for compiled .o files. TemplateMF Template makefile. Large++. As 'Large', but with c/c++ source code. TemplateMF Template makefile with a hack to get around a bug in Acorn's c++. !Normal.o Directory for erroneously-placed files from c++. !Debug.o Directory for erroneously-placed files from c++. TestLib. Example C library with two different builds. Motivation for Makatic —————————————————————— After finding that Acorn's !Make program didn't support building different versions of a project from the same source code, and was generally a pain to use, I used hand-written makefiles for all my projects. When I became the moderator of DeskLib, the need for a way of automating the generation of makefiles became apparent, so the first version of Makatic was written. This was included in DeskLib 2.30 . The much improved 'Makatic.Makatic2' was written so that many different types of projects could be supported. In particular, 'Makatic.Large++' is a great help for everyday project management. Problems ———————— Problems with ImageFSFix ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ There seems to be a bug in the ImageFSFix module used by ArcFS, which breaks the system-call OS_GBPB (which returns the files within a directory) when it is called for a non-existent directory (if you're interested, when ImageFSFix is present and the call is used for a non-existant directory, it doesn't return an error, so programs which use it treat the returned block as containing data when, in fact, it contains garbage). The Makatic scripts instruct Makatic.Makatic2 to look inside .c, .s and .c++ directories for source files, so they used to crash with an address exception (or similar) if these directories aren't present and ImageFSFix is running. I think I've managed to add a fix to Makatic2 which works around the problem but, if you still have problems problems, try putting empty .s and .c++ directories in your project directory. Please let me know if you have this problem. Problems with Acorn's C++ compiler ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ There is a bug in Acorn's C++ compiler 3.1 [May 25 1995] which means that the compiler always outputs to 'o.<input leafname>', ignoring any '-o <output file>' parameter. A second (probably related) problem is that any !Depend file generated by Acorn's c++ contains the incorrect o.<input leafname> filename. These problems can be worked around using the tool 'Makatic._C++', as in 'Examples.Large++', and including an empty .o directory for the incorrectly names .o files. This is done by replacing the call to c++ with a call to 'Makatic._C++', using with the full c++ command (including the 'c++ ' at the start) as parameters. 'Makatic._C++' calls c++ first. When C++ returns, 'Makatic._C++' moves the .o file to the correct place, and any !Depend file is altered to contain the correct .o filename. See 'Docs.Examples.Large++.TemplateMF' to see this in action. 'Makatic._C++' is based on a program written by Mark Seaborn. Thanks go to Mark Seaborn for telling me about both of these problems, and supplying code to fix things. Problems with Wimpslot size and Acorn C++ ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ If a RISC OS program is started with an insufficient Wimpslot, all sorts of bizarre errors can occur, such as 'Not enough memory to load shared C library', or plain crashing of the application. This can happen even when there is a large amount of free memory available, because the problem occurs before the application has started up properly. The Makatic scripts all set a Wimpslot of 640k, which I have found sufficient for nearly all cases. However, when using Acorn's C++ compiler, 640k is not always enough. I think this is because of the way in which c++ calls CFront and cc as child tasks, which means that CFront and cc are started in an environment which may not have a large amount of free memory available initially (I assume c++ uses the ANSI C 'system()' function for this; Makatic._C++ certainly does). The problem is compounded by the use of 'Makatic._C++', because this makes c++ itself a child process to be started up in what is left of the initial wimpslot after 'Makatic._C++' has been loaded. If you have problems, I suggest you set a large Wimpslot (eg 1000k) before using Makatic with c++. The TaskObey files used to make the example project in 'Makatic.Docs.Examplesd.Large++.' do this already. And finally... —————————————— The contents of the Makatic directory are Freeware and Copyright Julian Smith 1996. They may not be used in connection with any profit-making activity without my prior permission. I hope you find Makatic a useful set of tools. If you have any comments or suggestions about Makatic, I'd be very pleased to hear about them. I can be contacted at the address below - Julian Smith --------------------------------------------------------------------------- Julian Smith Dept of Experimental Psychology julian.smith@psy.ox.ac.uk South Parks Road, Oxford, OX1 3UD http://cogsci1.psych.ox.ac.uk/~julians/ UK ---------------------------------------------------------------------------