Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 310.lha / DevKit_v1.2 / DevKit.doc < prev next >

Wrap

Text File | 1980-12-03 | 44.3 KB | 935 lines

DevKit - Release 1.2 - August 29, 1989 DevKit files and programs copyright (c) 1989, Peter Cherna. See below for distribution restrictions. Contents 1.0 Introduction 1.1 Copyright and Distribution Notices 1.2 Disclaimers 1.3 Contents of the DevKit 1.4 Considerations for Use 2.0 ARexx Scripts 2.1.1 Compile.ced 2.1.2 Compile.WShell.ced 2.2 NextError.ced 2.3 LookUp.ced 2.4 LookUpHeader.ced 2.5 LookUpTag.ced 2.6 BlockSearch.ced 2.7 SetScriptBit.ced 2.8 CommentBlock.ced 2.9 UncommentBlock.ced 2.10 ARexx Notes 2.11 CygnusEd Notes 3.0 Shell/CLI Scripts and Other S Directory Stuff 3.1 SetSource 3.2 MakeTags 3.3 RexxCommands 4.0 Executable Programs 4.1 WBTF 4.2 GetAutoDoc 4.3 MakeAutoDocIndex 4.4 MakeHeaderIndex 4.5 GenTags 5.0 C Language Sources 6.0 Conclusion 7.0 Future Avenues 1.0 Introduction What is the DevKit? The DevKit is a collection of C and ARexx language programs to facilitate the life of the software developer. With the DevKit, you can launch your compiler from within your editor, have the cursor positioned on your errors, look up the autodoc page for any Amiga function at a single keystroke, find a system structure or #define within the include files, or find any function in the source code you are developing. As well, it provides a utility where you can put the compiler options in the source code for easy reference and modification. The compiling and error-finding functions are designed to work with CygnusEd Professional and Manx C 3.6a. You also gain a slight advantage if you own WShell. A dedicated worker could adapt these to other compilers or ARexx-compatible editors. The autodoc lookup works from the CLI as well, and is useful to anyone possessing the 1.3 Native Developer's Kit from Commodore, containing the autodoc and include files. 1.1 Copyright and Distribution Notices The files and programs that make up the DevKit are Copyright (c) 1989, Peter Cherna, and are freely redistributable with the following conditions: 1. All the files and programs that make up the DevKit shall be kept together in unmodified form. 2. Any modified files may be added to the DevKit provided they are in a separate directory for modified files, and clearly marked as being modified (by whom, when, and for what purpose). The original unmodified files must still remain as they were in the DevKit. Any such modified files must have no further restrictions on distribution than those restrictions given here for the DevKit. 3. The DevKit may be not be distributed for profit. Only a nominal charge may be associated with its distribution. 4. The DevKit may not be distributed along with any commercial product without prior consent from the author of the DevKit. 1.2 Disclaimers The DevKit is provided as is, without warranty of any kind. You assume full risk of its use. So there, but don't let that scare you. I am in no way affiliated with Manx, William Hawes, or ASDG/CygnusSoft, other than being a happy user of their products. The DevKit works with products from these developers because those products were appropriate for the need at hand. The DevKit software and documentation is my own and in no way expresses any opinions of, recommendations of, or guarantees on the part of my employer. 1.3 Contents of the DevKit DevKit.doc This documentation file. Rexx (dir) Directory containing ARexx scripts for CygnusEd Professional. Compile.ced Launch compiler from within editor. Compile.WShell.ced Launch compiler from within editor, for WShell users. NextError.ced Find next Aztec C error. LookUp.ced Look up a system function in the autodocs. LookUpHeader.ced Look up a #define'd constant or structure in the header files. LookUpTag.ced Look up a function within your source code. BlockSearch.ced Search for marked region. SetScriptBit.ced Sets the script bit of the current file. CommentBlock.ced Comments out the marked section of code. Handles the fact that in C, comments do not nest. UncommentBlock.ced Uncomments a block that was commented out using CommentBlock.ced. s (dir) SetSource Shell/CLI script that allows you to use an environment variable to specify your source directory. MakeTags Generates tags from multiple source files, for later use by LookUpTag.ced. RexxCommands Configuration file for CygnusEd Professional that binds the DevKit ARexx functions to function keys. c (dir) GetAutoDoc Extracts an autodoc for the specified function. MakeAutoDocIndex Builds the index files for the autodocs. MakeHeaderIndex Builds the index files for the compiler headers. WBTF Utility that brings the Workbench to the front. GenTags Generate tags for a single source file. Sources (dir) Source code for the above modules. GetAutoDoc.c MakeAutoDocIndex.c MakeHeaderIndex.c WBTF.c GenTags.c Examples (dir) AutoCommands Some "Auto:" commands to illustrate the use of Compile.ced. 1.4 Considerations for Use The DevKit was designed for relatively well-equipped Amigas, i.e. hard disks and extra memory. There is no reason why it shouldn't work on a 1 Meg floppy-based system, but it may be difficult to have CygnusEd, ARexx, and the Aztec C compiler all running in 512K. The lookup functions depend on having the autodocs or compiler headers plus some special index files available. The AutoDocs take about 710K, plus about 55K for the index files. The compiler headers take about 435K, plus about 100K for the index files. For convenience, it is desirable that they be kept on a hard disk, but they will work quite well (and reasonably fast) if kept on a floppy disk. 2.0 ARexx Scripts Nine ARexx scripts can be found in the Rexx directory of the DevKit. These scripts are designed to work from CygnusEd Professional, a high- performance editor available from ASDG Inc. Several of the scripts work in conjunction with the Aztec C compiler from Manx Systems. These scripts are designed to take advantage of ARexx version 1.10. If you have an earlier version, you should definitely upgrade to the latest version, at least 1.10. 2.1.1 Compile.ced Compile.ced is an ARexx program designed to work with CygnusEd Professional. It is used to launch a compiler (usually to compile the file that you are currently editing). It could easily be adapted to other programs that depend on a text file for input. In the file you are editing, you must place a comment that tells Compile.ced what to do with your file. You want to provide Compile.ced with a series of commands to perform, typically compiling and linking your file. Near the beginning of your source code, for each command that is to be executed by Compile.ced you must include the word "Auto:" followed by the desired command. The command may include the special wildcards <path> and <file>, which stand for the path to your file and the file name (less its extension, usually ".c"). To illustrate, if your file was "DH0:Sources/MyStuff.c", and you wished to compile and link it under Aztec C (with standard options, and sending the .o file to the RAM: disk), you would put the following in a comment near the beginning of your code. Auto: cc -o ram:<file>.o <path><file> Auto: ln ram:<file>.o -lc -o <path><file> Compile.ced will find these commands, substitute the string "DH0:Sources/" for each occurrence of the string <path> and substitute the string "MyStuff" for each occurrence of the string <file>, and will execute the resulting commands: cc -o ram:MyStuff.o DH0:Sources/MyStuff ln ram:MyStuff.o -lc -o DH0:Sources/MyStuff Compile.ced expects to find the first occurrence of "Auto:" within the first thirty lines of your source code, and will continue processing until a line without an "Auto:" is found. This means that all the "Auto:" commands must be on consecutive lines (no skipping allowed). You must use "Auto:" as written because case matters, so don't use "AUTO:" or "auto:". (You probably will want to make use of Compile.ced and NextError.ced's ability to tell you where the errors your compiler found are. To do so, you should use option -q of Aztec's cc compiler, which sends error messages (but not warnings) to a file called "AztecC.err" in the current directory.) If you install Compile.ced on a CygnusEd function key (say F1) by setting its command to be "run rx Compile.ced", you will be able to continue editing another file during compilation. When you press F1, Compile.ced checks to see if the file has been modified since the last save, and asks you if you wish to save before compiling. Select "Yes" to save, or "No Way!" to compile without saving. Once the Workbench screen pops up, and Compile.ced announces that it is scanning your file, you are free to continue editing this or other files. Compile.ced then looks for "Auto:" commands in your file. If none are found, you will be informed of the problem. Otherwise, Compile.ced executes performs the substitutions for <path> and <file>, and then executes the "Auto:" command. If the compiler failed because there were errors in your source, then Compile.ced will recognize that (by looking for the file AztecC.err). It will invoke the ARexx program NextError.ced (see below), which will locate and display the errors the compiler found in your source. If there are no compilation errors, you will be told so, and you then have the choice of returning to the Workbench screen (to test your code) or staying with the editor. Unfortunately, Compile.ced has no way of catching "Auto:" commands that fail, other than when Aztec's compiler detects errors and creates the AztecC.err file. As a result, being told that there were no compiler errors doesn't guarantee that the linker didn't fail, for example. If you use WShell, this problem can be overcome by using the Compile.WShell.ced ARexx script in place. The advantages of having "Auto:" commands are obvious. The instructions on how to compile a program remain with the program's source itself. If you decide to change a compiler option, you just modify the "Auto:" line in your source (if you want debugging information for Aztec SDB, just add option -n to the compiler line, and -g to the linker line, press F1, and voila!) If you need to link with the math library, you say so right in your source code. Because of the substitution for <path> and <file>, you can safely move your source code to a new directory and it will compile from there as well. Compile.ced does not provide any dependency analysis in the style of make. Of course, nothing stops you from using make as your "Auto:" command, as in Auto: make <file> Note that any DOS command is ok as an "Auto:" command. All the files in the Sources directory of the DevKit were compiled via Compile.ced. You can look at how those files are set up to get some ideas on how to proceed. For some other example "Auto:" commands, see the file AutoCommands in the Examples directory of the DevKit. 2.1.2 Compile.WShell.ced Compile.WShell.ced is an ARexx program that is very similar to Compile.ced described above. It does everything that Compile.ced does but takes advantage of an extra feature currently offered only by WShell, which allows an ARexx program to tell the success or failure of a DOS command it executed. This includes the "Auto:" commands. If you own WShell, you should use this ARexx program in place of Compile.ced. Compile.WShell.ced will inform you of exactly which "Auto:" command failed, and will stop processing further "Auto:" commands. This is useful if, for example, you pressed control-C during compiling, or if the linker failed to resolve all references. 2.2 NextError.ced NextError.ced is an ARexx program designed to work with CygnusEd Professional and Aztec C which takes the AztecC.err error file generated by the Aztec compiler and locates the errors within your source. The cursor of the editor will be placed on the error, and a requester will appear giving the error message. If you install NextError.ced on the F2 function key in CygnusEd, you can always get the next error by pressing F2. Compile.ced launches NextError.ced when it detects compiler errors, so your errors appear automatically after compiling. NextError.ced finds out which source file contains the next error (it could be in something you've #include'd.) If you don't have that file currently displayed in CygnusEd, you will be told that there is an error in that file and what the error is, and then you will be asked if you want it loaded into CygnusEd. If you say yes, it will be brought in. If you say no, then that error will be skipped. If the file with the error is already displayed in CygnusEd (or has just been brought in at your request), then the cursor will be moved onto the error, and a requester will appear giving the name of the file, the line in the source, the error number, and the error message. You will be asked if you wish to go to the next error or not. If you say yes, then the next error will be found. If you say no, you will be able to edit. Later, you can get the next error by calling NextError.ced (press F2). When there are no more errors, NextError.ced will tell you so. If you then call NextError.ced again, the first error will be redisplayed, and on from there. When NextError.ced tries to place the cursor on your error, there are a few things that must be remembered. First, the compiler is only so good at figuring out where the error really is. A missing semicolon, for example, is usually flagged at the beginning of the next line. Second, if you have changed your file since you compiled it (say by fixing an earlier error), and this has meant changing the number of lines before the error, then the cursor will miss the error by that number of lines. Likewise, if you've modified the line that contains the error, the cursor may miss the error by a number of characters. Finally, and this is important, NextError.ced can account for tab characters only under certain conditions. You must be using a fixed tab size (any tab size is ok) and not custom tabs. Second, all the tabs had better be at the beginning of the line. If your line has embedded tabs, such as foo(...);<TAB>bar(...); and the compiler finds fault with the parameters of bar(), NextError.ced will land the cursor slightly over from where it should be. More insidious is a line with a hidden space, say <SPACE><TAB>foo(...); which looks exactly like <TAB>foo(); The line with the hidden space will cause NextError.ced to misplace the cursor a bit. 2.3 LookUp.ced This is an ARexx program designed to work with CygnusEd Professional. The word under your cursor (or immediately to the left of your cursor) will be taken as the name of the Amiga system function you wish to look up in the autodocs. This is done by invoking the program GetAutoDoc (see later discussion for its stand-alone use). Note that you must have assigned the label "AutoDocs:" to the directory containing your autodoc files (or placed your autodoc files on a disk called "AutoDocs"), and you must have run MakeAutoDocIndex to build the indexes that GetAutoDoc needs to find autodoc entries efficiently. LookUp.ced identifies the word in your text by looking for all adjoining alphanumeric characters (as well as the underscore symbol "_"). If CygnusEd's cursor is on a character in a word or on the character immediately after the word (i.e. it's ok if your cursor is on the open bracket following the function), LookUp.ced will attempt to find a function by that name in the autodocs. If your cursor is not on a word, a string requester will appear, into which you may type the name of the function to look up. If no autodoc is found for the word you desire, you will be told. When an autodoc is found, LookUp.ced will open a new view in CygnusEd and put the autodoc for the requested function in that view. If you already have a view in CygnusEd that was opened by LookUp.ced or LookUpHeader.ced (see below), and its contents haven't been modified, then LookUp.ced (like LookUpHeader.ced) will use this view rather than opening yet another one. This helps prevent excessive clutter of the CygnusEd window/screen. Like NextError.ced (above), and LookUpHeader.ced (below), Lookup.ced can get a bit lost if you are using custom tabs, or if you have embedded tabs. Tabs of any fixed size, so long as they are at the beginning of the line, are ok. 2.4 LookUpHeader.ced Similar to LookUp.ced, LookUpHeader.ced is an ARexx program designed to work with CygnusEd Professional and the compiler headers files. The word under your cursor (or immediately to the left of your cursor) will be taken as the name of the Amiga system structure or #define'd constant that you wish to look up in the compiler headers. If your cursor is not on a word, a string requester will appear, into which you can type the name of the structure or constant you want to look up. Note that you must have assigned "ch:" to the directory containing your compiler headers (or placed your compiler headers on a disk named "ch"), and you must have run MakeHeaderIndex to build the indexes that LookUpHeader.ced needs to find system structures and constants efficiently. If the system structure or constant is found, LookUpHeader.ced will load the appropriate compiler header file into CygnusEd and place the cursor on the appropriate line. As explained in the discussion of LookUp.ced, LookUpHeader.ced will (if it can) use a view in CygnusEd that was previously opened by LookUp.ced or LookUpHeader.ced. 2.5 LookUpTag.ced LookUpTag.ced is an ARexx program designed to work with CygnusEd Professional and your own source code, be it in one or more modules. The word under your cursor (or immediately to the left of your cursor) will be taken as the name of the function that you wish to look up in your source files. If your cursor is not on a word, a string requester will appear, into which you can type the name of the function you want to look up. LookUpTag.ced will make use of the tags file that you must have previously generated by using MakeTags or GenTags (see below). LookUpTag.ced assumes that this tags file may be found in the same directory as the file in the current window of CygnusEd. If the requested function is found in the tags file, LookUpTag.ced will load the appropriate source module into CygnusEd if it is not already loaded (or make use of an already-loaded copy) and place the cursor on the appropriate line. 2.6 BlockSearch.ced This is a little freebie (an extra included at no charge in a free package?!?) which allows you to highlight a block of text in CygnusEd (don't cut it or copy it, though), and turn it into the object of a search. (The search will be a forward one, with the current settings of case sensitivity, words only, and wildcards.) If you want to search backwards, you can 'Repeat Search Backwards' (AMIGA-a) afterwards. It sure beats retyping something into the search requester. You may install this ARexx program directly on a function key. Note that only the first word in the block will be taken, so if you highlight the words "foo bar", and invoke BlockSearch.ced, the object of the search will be "foo". 2.7 SetScriptBit.ced Another freebie (see above :->) which sets the script bit of the current file in CygnusEd. When I edit my script files and re-save them, I lose the script bit. If you install this ARexx program on a CygnusEd function key, you can fix the script bit with a single keystroke. 2.8 CommentBlock.ced An unfortunate feature of the C programming language is that comments do not nest (although some compilers allow nested comments as an option). Sometimes, it is convenient to comment out a whole section of code, but a problem arises if this section itself contains comments. CommentBlock.ced is an ARexx program that takes the currently highlighted block in CygnusEd, encloses it in comments, and replaces the comment brackets within the block ('/*' and '*/') with false brackets that the compiler will ignore ('<*' and '*>'). Thus, it becomes possible to comment a whole block of code, as if comments did nest. If you apply CommentBlock.ced to a block that already contains some false brackets from a previous invocation, the false brackets will grow (i.e. '<*' becomes '<<*', etc.) so that you may successfully comment out something that already is. 2.9 UncommentBlock.ced UncommentBlock.ced is the matching inverse function to CommentBlock.ced. It takes the currently highlighted block in CygnusEd, and begins by removing the first open comment sequence ('/*') and the last close comment sequence ('*/'). (It is not a problem if either an open or close comment is not found). It then replaces all the false comment brackets ('<*' and '*>') within the block with true comment brackets ('/*' and '*/'), or it shrinks them (i.e. '<<*' becoms '<*', etc.). It effectively uncomments a block that was commented out with CommentBlock.ced (described above). 2.10 ARexx Notes These ARexx programs are relatively robust examples of driving CygnusEd and DOS commands from within an ARexx program. Of course, to run ARexx programs from within CygnusEd, you must run it with the -keepio option, as in run ced -keepio One possible area of difficulty is in executing DOS commands from within an ARexx program. The ARexx command "ADDRESS COMMAND cmd" executes the program specified by 'cmd'. If you don't include the full path to the file, then your path is searched. As explained in the ARexx 1.10 documentation, the path will be that in effect when CygnusEd was run. The DOS programs called by these ARexx programs (DevKit programs GetAutoDoc and WBTF, and DOS commands delete and search) must be in one of the directories in your path, or in the C: directory. This is also true of any program called by an "Auto:" command without a full path specification, meaning cc, as, and ln. You may of course give a full path specification in your "Auto:" commands, by doing something such as Auto: Aztec:ln ... However, take note that even if you give the full path to the compiler, Aztec expects the assembler to be in the current directory or anywhere in the path. The only way for an ARexx program to find which view in CygnusEd Professional contains a particular file is to go to each successive view until the correct one is found. If you use CygnusEd's "Auto- expand views" option (which makes the current view expand to the largest possible size), then there will be a certain amount of flashing as NextError.ced, LookUp.ced, and LookUpHeader.ced attempt to locate the correct view. If you can't do without "Auto-expand views", you will have to put up with the flashing, at least until a few more functions are added to the ARexx interface of CygnusEd Professional. An important point to note is that Aztec's cc compiler places its error file AztecC.err in the current directory, which will be the current directory at the time CygnusEd Professional was run. If your current directory is write-protected, cc won't be able to open the error file. CygnusEd has a menu option that lets you change its current directory. You may also add a line to Compile.ced such as call pragma 'Directory', "RAM:" which will change the current directory of the ARexx script to RAM:. Another straightforward solution is to use a file zapper on the Aztec compiler cc and change the string 'AztecC.err' and to something like 'RAM:Az.err' (note that it has to be exactly the same length, i.e. 10 characters). Use a text editor to make similar changes in Compile.ced and NextError.ced, and Aztec's error messages will always go to the RAM: disk. 2.11 CygnusEd Notes The ARexx programs in the DevKit make extensive use of the CygnusEd ARexx interface. Almost anything the user can make CygnusEd Professional do can be done over the ARexx port. For those interested in adapting the DevKit to other text editors, here is a brief description of the CygnusEd ARexx functions that are used in the ARexx programs of the DevKit. CygnusEd always returns the result of a function in the variable named "result". address 'rexx_ced': Informs the ARexx server of the desire to communicate with CygnusEd. cedtofront: "cedtofront" brings the CygnusEd window to the front and activates it. copy block: "copy block" puts a copy of the currently highlighted block into the block buffer, and unhighlights it. If the operation was successful, the return value "result" will be uninitialized (i.e. equal to the string "RESULT"), otherwise it will contain an error message (such as "No block marked"). cut block: "cut block" behaves just like "copy block" except that the currently highlighted block is also removed from the file. getstring: "getstring" asks CygnusEd to put up a requester, into which you may type a string, which will be returned in the variable "result". jumpto: "jumpto line char" moves the cursor to the specified line and character (the first line of the file and the leftmost character are taken as 1). menu: "menu menu item sub" executes the function at the specified menu, menu item, and sub item (count from zero up). "menu 2 1 7" is used to set the tab size to eight. next view: CygnusEd supports multiple views (like having multiple windows, with the same or different file in each window). "next view" moves the cursor into the next view. okay1: "okay1 text" causes CygnusEd to present a requester containing the specified text with a single gadget ("Resume?"). okay2: "okay2 text" causes CygnusEd to present a requester containing the specified text with two gadgets ("Yes" and "No Way!"). A result of 1 indicates that the "Yes" gadget was selected, while a result of 0 indicates that the "No Way!" gadget was chosen. open: "open file" causes CygnusEd to load the specified file into the current view. open new: "open new" causes CygnusEd to create a new (empty) view by splitting the current one. search for: "search for string" causes CygnusEd to initiate a forward search for the specified string. If the search was successful, the return value "result" will be uninitialized (i.e. equal to the string "RESULT"), otherwise it will contain an error message (such as "'string' not found") text: "text string" will cause the supplied string to be entered at the current cursor position. CygnusEd also provides the "status n" command which, depending on the value of n, returns a value or string known to the editor. The variable "result" contains the answer. The ones used in the DevKit are: 8: "status 8" returns the tab size. 18: "status 18" returns the number of changes to the file in the current view since the last time it was saved. 19: "status 19" returns the full path and file name of the file in the current view, eg. "Workbench:Sources/MyStuff.c" 20: "status 20" returns the path of the file in the current view, eg. "Workbench:Sources" 21: "status 21" returns the name of the file in the current view (without the path), eg. "MyStuff.c" 46: "status 46" returns the x position of the cursor (the first column is taken as 0). 47: "status 47" returns the y position of the cursor (the first line of the file is taken as 0). 55: "status 55" returns a string which is the text on the current line (tabs are not converted to spaces.) 60: "status 60" returns a string which is the contents of the block buffer. 66: "status 66" returns the number of views currently open in CygnusEd. 3.0 Shell/CLI Scripts and Other S Directory Stuff The DevKit includes a Shell script. 3.1 SetSource SetSource is based on a script I use. If I want to work on some c files that are in a particular directory of my disk, say "cc:Tools", I type at the Shell prompt: SetEnv Source cc:Tools As my ENV: directory is on my hard disk (and not in RAM:), this environment variable survives reboots and power-offs. When turn on the computer to resume developing or when I reset the computer after a crash, the script SetSource will get this environment variable and assign the logical label src: to it. I also invoke CygnusEd with a file name (or more accurately a directory name) of src:, so that when I want to open a file, the directory is set to my source directory. Scripts like SetSource that stuff parameters into commands look a bit ugly, but can be very effective. 3.2 MakeTags MakeTags is a shell script that allows GenTags to be run for multiple source files, with the result being stored in a file called tags in the current directory. Its syntax is MakeTags [pat] where pat is an optional pattern (defaulting to #?.c, or all .c files). So if you wanted to make tags for all .c files beginning with a w, you would use MakeTags w#?.c MakeTags displays the name of each file as it is scanned. Normally you will use MakeTags, and not call GenTags directly. 3.3 RexxCommands RexxCommands is a file generated and used by CygnusEd Professional (and placed in the S directory) which specifies the ARexx or DOS commands that are attached to each function key. RexxCommands makes the following bindings for the ARexx scripts of the DevKit: F1 run rx Compile.ced F2 NextError F3 CommentBlock F4 UncommentBlock F6 SetScriptBit F7 BlockSearch F8 LookUpTags F9 LookUpHeader F10 LookUp 4.0 Executable Programs The DevKit contains five executable programs in the C directory that are needed to run the ARexx scripts in the DevKit. 4.1 WBTF WBTF is the simplest one, and it just brings the Workbench screen to the front, so that you may see what the compiler, or whatever is doing. It has no arguments. (CygnusEd is brought to the front through the ARexx command "cedtofront" that it provides.) 4.2 GetAutoDoc GetAutoDoc extracts the autodoc for a function. You must have the autodocs available in a directory, and have assigned the label "AutoDocs:" to that directory. Also, you must have run MakeAutoDocIndex to build the indexes that GetAutoDoc needs to quickly extract the autodoc for a function. To use GetAutoDoc, just type GetAutoDoc function Where function is the name of the Amiga system function you would like the autodoc for (you may use upper, lower, or mixed case - it doesn't matter). If the function is found, the autodoc page will be sent to the screen. You may of course redirect the output to a file (that's what LookUp.ced does.) If the function is not found in the autodocs, or some other error occurs, you will be told. If you just type GetAutoDoc You will get a brief summary of usage. GetAutoDoc returns an error code of 20 if a critical error occurred, an error code of 5 if no autodoc for the desired function was found, and an error code of 1 if the summary of usage was displayed. The error code of zero is reserved for successfully finding an autodoc. Furthermore, all error strings are guaranteed to begin with a dash followed by a space, as in - Foo not found. 4.3 MakeAutoDocIndex MakeAutoDocIndex is a program that builds index files from the autodocs so that GetAutoDoc may work efficiently. It assumes that the autodocs are the ones from the 1.3 Native Developer's Kit, available from Commodore. It scans all the files in the "AutoDocs:" directory that end in ".doc". These had better be genuine autodoc files. A genuine autodoc file contains: A list of the functions (or whatever, MakeAutoDocIndex doesn't care) Form Feed A set of { Autodocs for one function Form Feed } Assuming that nothing goes wrong, MakeAutoDocIndex will create a bunch of files in a subdirectory called "Index" that it creates in the "AutoDocs:" directory. These files are called IndexA, IndexB, etc. Each file contains all the functions that start with that letter or symbol (there will be an Index_ file). The format will be: function; library; autodocfile offset where function is the name of the function (eg. OpenScreen), library is the system library it belongs to (eg. intuition.library), autodocfile is the full name of the autodoc file (eg. AutoDocs:LibrariesA-K/intuition.doc) and offset is the byte offset into the autodoc file where this function begins (eg. 68810). Some sharable libraries include an autodoc-type file. You may easily modify the source to MakeAutoDocIndex and recompile if you wish to index these as well. To modify MakeAutoDocIndex.c to inform it of that new sub-directory, add it to the string array autodocdir and increase DIRCOUNT by one. If the supplied autodoc file isn't the correct format, you may have to edit it a bit. In particular, each entry should be separated by a form feed, and there should be exactly one form feed before the first entry. Make sure that whatever is ahead of the first entry has no form feeds. The name of each function should appear on the line after the form feed. There may be no spaces or tabs before the name (spaced or tabs after the name are ok). The name may be preceded by some other names (such as the library name) with slashes between, for example intuition.library/OpenScreen is acceptable. MakeAutoDocIndex tries to catch and report any problems it might find. With the 1.3 autodocs there are no problems. MakeAutoDocIndex (like MakeHeaderIndex below) requires that the DOS command 'sort' be in the C: directory or the current directory. 4.4 MakeHeaderIndex MakeHeaderIndex is a program that builds index files from the include files, so that LookUpHeader.ced may work efficiently. It assumes that the includes are the ones from the 1.3 Native Developer's Kit, available from Commodore. You must assign the label "ch:" to the directory containing your compiler headers. MakeHeaderIndex scans the eight subdirectories in "ch:" that it knows of - devices, exec, graphics, hardware, intuition, libraries, resources, and workbench (See MakeHeaderIndex.c). MakeHeaderIndex will create a bunch of files in a subdirectory called "Index" that it creates in the "ch:" directory. These files are called IndexA, IndexB, etc. Each file contains all the functions that start with that letter. The format will be: structure; headerfile; line or define; headerfile; line where structure or define is the name of the Amiga system structure (eg. NewScreen) or #define'd value (eg. WBENCHSCREEN), headerfile is the full name of the compiler header file (eg. ch:intuition/screens.h) and line is the line number in the compiler header file where this reference lies (eg. 95). MakeHeaderIndex will locate all #define'd constants that have a #define at the very beginning of the line, as well as all structures that begin with a struct at the very beginning of the line. This seems to be true for the Amiga compiler headers. If you have any headers that come with a sharable library, you must place them in a sub-directory of the "ch:" directory. You must modify MakeHeaderIndex.c to inform it of that new sub-directory (add it to the string array includedir and increase DIRCOUNT by one). You must also hope that all the #define's and struct's are at the extreme left of their lines. MakeHeaderIndex tries to catch and report any problems it might find. With the 1.3 include files, there are no problems. 4.5 GenTags GenTags is a C-language program that will scan a C-language source file and generate a tag entry for each function defined in that file. It takes as a single parameter the name of the source file: GenTags foo.c Each tag entry is of the following form: function; file; line where function is the name of the function that GenTags found, file is the name of the file it was found in, and line is the line number within that file where the function was defined. The tags are sent to the standard output, so you will probably want to redirect them somewhere. Usually, you will use the shell script MakeTags, which calls GenTags for each file that matches a specified pattern, and redirects the output to a file called tags. GenTags is smarter than for example the program that generates tag files for the editor vi. The only non-pathological case known for which GenTags messes up is when there is an open comment ('/*') within quotation marks. Except for that case, it should successfully find all the functions (it performed flawlessly on 500K of source files that comprise one project). Perhaps I left that one problem in so that I have something to do for the next release... Since the tag file contains the line number where a certain function was defined, if you modify a source module after you've generated the tags for it, then LookUpTag.ced may miss by a bit if you've added or removed lines ahead of the function in question. As well, any functions you've added to the source since you last generated the tag files will of course not be in them. You will periodically want to remake the tag files, which fortunately is relatively quick and painless (I can build tags for 500K of source in less than one minute, but then I have access to a 68030 at work). 5.0 C Language Sources The sources for the five executable programs in the c directory of the DevKit are provided. They all compile under Aztec C, and contain suitable "Auto:" commands to compile properly. As such, they serve as examples of how to set up "Auto:" commands properly. 6.0 Conclusion Thanks to Bill Hawes for technical assistance, and to Mike Sinz for encouranging me to make CommentBlock and UncommentBlock nest properly. The ARexx and C language programs that comprise the DevKit make developing on the Amiga much easier. They also serve as good examples of ARexx programming. If you have any comments, suggestions, or modifications, please bring them to my attention at Peter Cherna 5511 Westbourne Ave., Cote St. Luc, Quebec Canada H4V 2G9 7.0 Future Avenues Someday someone (perhaps me) will modify the DevKit so that Compile.ced and NextError.ced work with the Lattice compiler. As Lattice's CodePRobe is ARexx compatible, LookUp and LookUpHeader functions could be added to it, which would be useful. Compile.ced and NextError.ced could also be rewritten for other compilers (eg. Modula 2.) One annoying problem I have with Aztec is that compiler warnings aren't included in the AztecC.err file; they always go to the standard output. Aztec flags as warnings several things that I consider errors, such as referencing foo->bar, where bar is not a field of the structure foo, but is of some other structure. I'd like to write a program that would take the redirected output of Aztec's cc, and format warning messages and stuff them into AztecC.err along with the errors. As well, the ARexx programs might one day be rewritten to work with other ARexx compatible editors. If anybody succeeds in any of these areas, I would be delighted to hear about it. As a suggestion, if you intend to rework Compile.ced and NextError.ced to work with Lattice C, I would suggest you use some other keyword than "Auto:", say "LAuto:", so that source code that compiles under both Lattice and Aztec could have both "Auto:" and "LAuto:" commands in it, and would compile depending on which version of Compile.ced you used.