Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 182.lha / APE / ape.doc < prev next >

Wrap

Text File | 1988-04-28 | 19.9 KB | 527 lines

An Amiga Programming Environment --- APE v1.00 -------------------------------- --------- (c)1988 SofThing APE is a workbench based tool for C projects. It arose out of my dislike for the CLI and other command line interfaces. I hope you find it useful. I am releasing this as shareware. A contribution of $20 will make you a registered user, eligible for free (i.e. cost of postage and disk) upgrades. Whether or not you are a registered user, comments and suggestions are most welcome. To use APE, you need your own program editor, compiler and linker. APE makes use of these and a simple "make" like description of your project, which it maintains. It opens a workbench window with menus for operations and scrolling displays of source and include files used in your project. FILES PROVIDED -------------- APE The executable. Normally run from the workbench by double-clicking on its icon or on a project icon. Can be invoked from the CLI, taking no command line arguments, or a single project name ( a project to be opened ). Detaches itself when run from the CLI, i.e. no need use RUN or RUNBACK. In s/ lattice.apesrc A sample .apesrc file suitable for a system using Matt Dillon's DME editor, the Lattice C compiler and the public domain linker BLINK. This must be renamed .apesrc to be used. .apesrc is created/modified using the APE's CUSTOM menu. Specifies the name of your editor (e.g. sys:dme) , compiler (Phase 1 and 2), and linker (e.g. blink). Also specifies whether your system has a battery- backed clock, and some default settings used when creating new APE projects. **** APE looks for .apesrc in :s, then in sys:s and finally in s:. In templates/ project.info Icon for APE projects. Feel free to substitute your own. The default tool should reflect where you have located APE. program.info Icon for executables produced by APE. (Same as the APE icon - APE was built using APE, naturally). If using Manx, you may want to add a window specification in the tool types field. **** APE looks for these files in :templates, then in sys:templates and **** finally in templates:. SETTING UP ---------- Put APE wherever you like but remember to change the default tool for templates/project.info to match. APE needs the commands CD, STACK, ASSIGN, IF, SKIP, LAB, FAILAT, ECHO, ENDCLI, EXECUTE and RUN ( also SET and PATH if you use them ). It also uses the ram: device. If you are going to print files from APE, then you also need a printer driver and the command COPY. Put .apesrc in a directory called s on your boot disk or your project disk, or in a place which you assign the logical name s: ( this is assigned to the path sys:s when you boot ). You can run APE to set up your .apesrc file according to the way you set up your tools. New settings will be saved when you exit APE. Put the template files in a directory called templates on your boot disk or your project disk, or in a place which you assign the logical name templates:. OPERATION --------- Most of the menu items are reasonably self-explanatory. To create a new project, double-click on the APE icon. When the APE window opens, set up your custom settings as described above if you have not done so before. Now select NEW from the PROJECT menu. Type the name (full pathname unless the project is to go at the top of the current filing system) into the requester. A new project will be created and opened, with two (empty) scrolling displays appearing in the window. The name of the project will appear in the window title. The display labelled "Source Files" shows .c files to be compiled for this project. The one labelled "Include Files" shows .h files #included in the .c files. These would usually be your own .h files, not any system ones you may #include. Select the ASSIGNS item from the SPECIAL menu. This allows you to specify pathnames for logical names such as LIB:, INCLUDE: and QUAD: as used by the Lattice compiler. Also use the OTHER .O'S and the LIBRARIES items for this menu as described in the summary below. These should all have been given default values but you can vary them for each project. To add a source file to the project, select NEW from the FILES menu. A requester will prompt you for the file name. This should not be a pathname - APE v1.00 can't deal with that. A new item will appear in the top scroller. Now double-click on the new item, or click once on it to select it (it will then be highlighted - click again to deselect) and choose EDIT from the FILES menu. This will invoke your editor on this file. When you have finished editing, select that item again and choose INCLUDES from the FILES menu. A requester will appear to allow you to specify up to seven .h files to be included in this .c file. This is used by APE's simple make facility. It doesn't have to be the truth. Include files can also be specified for each .h file, but be careful, APE doesn't check for possible nasties such as circular inclusions. If you added .h files in this way, new items will appear in the second scroller. These can be double-clicked on in the same way as the .c items. Multiple files can be selected in each scroller by holding down the shift key and clicking. To exit APE, click on the close gadget, or select QUIT from the PROJECT menu. SUMMARY OF MENU OPERATIONS -------------------------- PROJECT OPEN Open an existing project. If you already have another project open it will be closed first. NEW Create and open a new project. Any project already open will be closed. MAKE Compile all .c files that have changed ( or whose .h files have changed ) since last compiled. Link everything to create a new executable. LINK Just link without recompiling. BUILD Create a copy of the executable, with icon, wherever you want to put it. QUIT Quit APE after confirmation. ABOUT Displays a message pleading for money. FILES EDIT Invoke your editor on the selected source and include files. COMPILE Invoke your compiler on the selected source files. PRINT Print selected files in the background. FIND Search selected files ( or all files ) for a given pattern string. Produces a listing which may be directed to the console or to the printer. The pattern string is a regular expression as described in the appendix. INCLUDES Specify .h files #included in the selected files. Will ignore selections of include files if any source file selections were made, and will ignore all but the first selected include file in any case. TOUCH "Change" the selected files so that APE will think they need to be compiled. NEW Add a new source file to the project. The filename should have a .c extension. EXPUNGE Remove the selected source files from the project. Confirmation is requested and the .c and corresponding .o files are actually only moved to the trashcan drawer. If any .h files are no longer needed in the project, these are also moved to the trashcan after confirmation. RUN GO Open a new CLI and invoke your program using supplied command line arguments. After termination, returns to APE. Obviously your program must be able to run from the CLI. ARGUMENTS Specify command line arguments to your program. SPECIAL PATH Specify a search path for commands. ASSIGNS Specify pathnames for logical names such as LIB:, INCLUDE: and QUAD:. The requester that appears has two columns of string gadgets. The first column is for logical names; the second is for the corresponding paths. Note that if you make an assignment to QUAD: APE will assume that you are using the Lattice compiler and will try to use the -o and -q options to use the QUAD: directory for temporary .q files. SETS Specify values for environment variables to be set using the SET command. The requester that appears has two columns of string gadgets. The first column is for variable names; the second is for the correspong values. LIBRARIES Specify library files to be linked in (usually LIB:lc.lib and LIB:amiga.lib for Lattice). For the Lattice compiler this is where library files should be specified. For the Manx compiler, you can put library files here, or use -Lxxx linker options. OTHER .O'S Specify any other .o files to be linked in (usually LIB:c.o for Lattice). OPTIONS Specify any editor, compiler or linker options to be used for this project. Don't specify -o options for the compiler or linker or things will get into a mess. APE uses these for itself. Other strange options may also cause problems. STACK Specify the stack size for commands in bytes (usually 4000). CUSTOM TOOLS Specify the editor, compiler and linker to be used in your system. Has separate entries for each phase of the compiler. Just leave the phase 2 entry blank if you are using a one pass compiler. LINKER SYNTAX Specify whether your linker conforms to the syntax of BLINK and ALINK, or to Manx's ln. See the discussion of LIMITATIONS below. CLOCK Specify whether you have a battery-backed clock. APE plays funny tricks to try to keep the project in step for people without one. You can say that you have got one even if you haven't, but APE may become confused about what is up to date unless you diligently set the clock each time before using APE. STANDARD SETTINGS Enter default values for the items on the SPECIAL menu to be used when creating new projects. HOW (SOME OF) IT WORKS ---------------------- Each project is really a directory containing all the .c, .o and .h files, the executable, and a description of the project in a text file called .project. You can examine this and it will be fairly clear what its structure is. The strings of digits and colons represent timestamps of files and are used by APE if you don't have a battery- backed clock. If you should lose this file by some accident you should be able to rescue the project by creating a new one by hand ( or using the CRAPE utility ). For systems without a battery-backed clock, APE records the timestamp of each file in the project when closing the project and checks them for possible tampering the next time the project is opened. Any file whose timestamp doesn't match the one recorded is assumed to be out of date. Using these, APE tries to figure out a logical creation sequence for the files and then 'touches' each file in this sequence. From then on in that APE session, the files' current timestamps can be used to tell what is or is not up to date. To run your editor, compiler and linker, APE constructs script files in ram: and calls Execute to create a new CLI task to execute them synchronously with APE. This is a pretty awful method but it works OK. It would be so much nicer if some commercial compiler writer would create for us a truly integrated programming environment and I guess this will come eventually. In the meantime, at least we now have APE! SOME LIMITATIONS ---------------- APE is only suitable for simple projects at this stage of development. It will probably be given more functionality in later releases to make it more generally useful. The tools that you use must conform to the syntax that APE expects: <editor> <options> <filename> <compiler phase 1> <options> <filename without extension> <compiler phase 2> <options> <filename without extension> APE supports linkers having the same syntax as BLINK and ALINK, and also linkers like the Manx ln linker. You specify which kind of linker you have with the LINKER SYNTAX item in the CUSTOM menu. In each case, a "with" file is created and the linker is invoked with the command line: <linker> WITH <withfilename> (BLINK type) or <linker> -f <withfilename> (Manx ln type). The with file constructed contains the command sequence: TO <projectname> FROM <other .o's> <.o's> LIBRARY <libraries> <options> (BLINK) or -o <projectname> <other .o's> <.o's> <libraries> <options> (ln). This may help you to decide what options can meaningfully be used with APE. For example, BLINK OVERLAY's are clearly unworkable. APE has some funnies in it to try to cope with the lack of a battery-backed clock. Thus, hopefully, you don't need to set the time each time you boot up, and APE's make facility can still cope. However, this can make large projects rather slow to open and close. Be patient. By and large, APE doesn't do a great deal of checking of user input data. To avoid heartaches, give it sensible input. For example, source file names should have a .c extension, and you shouldn't specify circular dependencies. APE has a problem living with ConMan. You can't close the console windows opened by APE if ConMan is installed. This gives the appearance of a hung program. I hope to be able to work around this somehow in the future. If you use a search path for commands then you will need to specify this path in the SPECIAL menu. The path will be re-established each time you edit, compile etc. This may cause "Please insert volume xxx" requesters. My apologies, I haven't been able to find a better solution. Assigns and sets are global and easier to handle. You can put these in your startup-sequence or in each APE project. If you use assigns and sets within APE, they will only be re-established when the project is opened or when you alter them. There are doubtless a few bugs in v1.00, but not drastic ones perhaps. For example, there is a memory leak somewhere. I am working to fix those that I know of. Reports of other bugs and/or suggestions for improvement will be gladly accepted. RELEASE NOTES ------------- v0.95 Initial pre-release version. v0.96 Internal release. Many bugs fixed, printing added. Code reorganised and recompiled with Lattice v4.01 resulting in 20% smaller code. Locations searched for .apesrc and template files changed. v0.97 Internal release. Several bugs introduced with v0.96 fixed. File searching added ( FIND menu item ). v0.98 Internal release. RUN menu added. Command line arguments to APE added. More reorganisation of code. v0.99 Internal release. Added support for non-blink syntax linker. Added STACK size to menus. Improved requesters with multiple string gadgets, and support for left-amiga v and b in all requesters. v1.00 First release. Added PATH and QUIT menu items. APE window shrinks when console window opens, expands when console window closes. Menus disabled when performing actions, enabled when actions completed. Other small bug fixes and changes. Philip Hingston 9 September 1988 SofThing 14 Waverley Rd, Chadstone, 3148, Victoria, Australia. ============================================================================== APPENDIX REGEX - Regular Expressions Used in FIND menu item -------- -------------------------------------------------------- The core of this section of APE is a public domain implementation of the regex regular expression package by Ozan. S. Yigit. This appendix is an excerpt from his documentation. /* * regex - Regular expression pattern matching * and replacement * . * . { Note that replacement is not used in this version of APE. } * . * * By: Ozan S. Yigit (oz) * Dept. of Computer Science * York University * * * These routines are the PUBLIC DOMAIN equivalents * of regex routines as found in 4.nBSD UN*X, with minor * extensions. * * These routines are derived from various implementations * found in software tools books, and Conroy's grep. They * are NOT derived from licensed/restricted software. * For more interesting/academic/complicated implementations, * see Henry Spencer's regexp routines, or GNU Emacs pattern * matching module. * . * . { Section omitted here.} * . * * Regular Expressions: * * [1] char matches itself, unless it is a special * character (metachar): . \ [ ] * + ^ $ * * [2] . matches any character. * * [3] \ matches the character following it, except * when followed by a left or right round bracket, * a digit 1 to 9 or a left or right angle bracket. * (see [7], [8] and [9]) * It is used as an escape character for all * other meta-characters, and itself. When used * in a set ([4]), it is treated as an ordinary * character. * * [4] [set] matches one of the characters in the set. * If the first character in the set is "^", * it matches a character NOT in the set. A * shorthand S-E is used to specify a set of * characters S upto E, inclusive. The special * characters "]" and "-" have no special * meaning if they appear as the first chars * in the set. * examples: match: * * [a-z] any lowercase alpha * * [^]-] any char except ] and - * * [^A-Z] any char except uppercase * alpha * * [a-zA-Z] any alpha * * [5] * any regular expression form [1] to [4], followed by * closure char (*) matches zero or more matches of * that form. * * [6] + same as [5], except it matches one or more. * * [7] a regular expression in the form [1] to [10], enclosed * as $form$ matches what form matches. The enclosure * creates a set of tags, used for [8] and for * pattern substitution. The tagged forms are numbered * starting from 1. * * [8] a \ followed by a digit 1 to 9 matches whatever a * previously tagged regular expression ([7]) matched. * * [9] \< a regular expression starting with a \< construct * \> and/or ending with a \> construct, restricts the * pattern matching to the beginning of a word, and/or * the end of a word. A word is defined to be a character * string beginning and/or ending with the characters * A-Z a-z 0-9 and _. It must also be preceded and/or * followed by any character outside those mentioned. * * [10] a composite regular expression xy where x and y * are in the form [1] to [10] matches the longest * match of x followed by a match for y. * * [11] ^ a regular expression starting with a ^ character * $ and/or ending with a $ character, restricts the * pattern matching to the beginning of the line, * or the end of line. [anchors] Elsewhere in the * pattern, ^ and $ are treated as ordinary characters. * * * Acknowledgements: * * HCR's Hugh Redelmeier has been most helpful in various * stages of development. He convinced me to include BOW * and EOW constructs, originally invented by Rob Pike at * the University of Toronto. * * References: * Software tools Kernighan & Plauger * Software tools in Pascal Kernighan & Plauger * Grep [rsx-11 C dist] David Conroy * ed - text editor Un*x Programmer's Manual * Advanced editing on Un*x B. W. Kernighan * RegExp routines Henry Spencer * * . * . { Section omitted here. } * . * * Examples: * * pattern: foo*.* * compile: CHR f CHR o CLO CHR o END CLO ANY END END * matches: fo foo fooo foobar fobar foxx ... * * pattern: fo[ob]a[rz] * compile: CHR f CHR o CCL 2 o b CHR a CCL bitset END * matches: fobar fooar fobaz fooaz * * pattern: foo\\+ * compile: CHR f CHR o CHR o CHR \ CLO CHR \ END END * matches: foo\ foo\\ foo\\\ ... * * pattern: $foo$[1-3]\1 (same as foo[1-3]foo) * compile: BOT 1 CHR f CHR o CHR o EOT 1 CCL bitset REF 1 END * matches: foo1foo foo2foo foo3foo * * pattern: $fo.*$-\1 * compile: BOT 1 CHR f CHR o CLO ANY END EOT 1 CHR - REF 1 END * matches: foo-foo fo-fo fob-fob foobar-foobar ... * */