Fresh Fish 5

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

/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / ace-ag-docs.lha / ACE-AG-Docs / AIDE.Guide < prev next >

Wrap

Text File | 1994-03-26 | 12.0 KB | 364 lines

@ DATABASE "AIDE.Guide" @ MASTER "AIDE" @NODE MAIN "AIDE v1.0" --------- AIDE v1.0 --------- @{" Introduction " link introduction} @{" Setting Up " link settingup} @{" Using AIDE " link usingaide} @{" AIDE's Make Process " link makeprocess} @{" Final Comments " link comments} @ENDNODE @NODE Introduction "Introduction" Introduction ------------ AIDE (ACE Integrated Development Environment) is a freely distributable graphical environment for the development of ACE programs. It is written in ACE and currently requires AmigaOS Release 2.04 or higher to run. I will try to get a future version of AIDE running correctly under 1.3 when I get some time, but for anyone wishing to have a go at doing this I have included the source code (which is also freely distributable but I retain the copyright to it). The problems under 1.3 seem to be related to the way in which AIDE uses a NewShell and PIPE. In any case, at present if you start the program under 1.3, a requester will appear telling you that you need Wb 2.04 or higher to run AIDE. ** Please note that this restriction only applies to AIDE not ACE!! ** Anyway, if you do have Release 2.04 or higher, you can start AIDE by double-clicking its icon from the Workbench. With AIDE, you never need to start from a shell again when developing ACE programs, although you may spawn a shell by selecting an item from AIDE's @{"Project Menu" link projectmenu} (see below). Before starting AIDE for the first time however, you must modify one file. This configuration file is discussed next. @ENDNODE @NODE settingup "Setting Up" Setting Up ---------- AIDE requires a file called AIDE.config to be present in the same directory as itself. Without this, the program won't run. A sample AIDE.config is included in the AIDE archive. It looks like this: # # AIDE configuration file. # # For each AIDE configuration variable, # replace its value with the full path # of the tool or directory of your choice. # # An entry with a "*" next to its comment # is NOT optional. # # Editor * EDITOR=sys:tools/memacs # File viewer * VIEWER=ACE:bin/muchmore # Temporary directory for preprocessor,compiler,assembler & linker. * TMPDIR=RAM:t # Directory in which to put built executables and icons. # If not specified, this defaults to the directory in which # the source file which is being compiled resides. BLTDIR=ACE:Run # Directory in which docs for the compiler, assembler & linker reside. * DOCDIR=ACE:docs --------------- There are currently four entries which MUST have valid values. Notice that in the example above, it is assumed that ACE: is a valid ASSIGN. See the "@{"Installation" alink ace:docs/installation/main}" file which comes with the main ACE archive. Note also that lines commencing with a "#" are taken to be comments. AIDE has no built-in editor so you need to specify your favourite. I may eventually write an editor, but my current feeling is that I can spend my time more productively in other ways, given the plethora of text editors available for the Amiga. The same is true for file viewers. If anyone wishes to write a text editor for AIDE, feel free to let me know about it. Likewise, if you think I should supply a particular FreeWare editor with AIDE, I'll be glad to consider any suggestions you have. Note that the editor you specify in AIDE.config must be capable of taking command-line arguments (namely: a file name). The same applies to the file viewer. Once you have set the entries in AIDE.config to your satisfaction, you can start AIDE from the Workbench. @ENDNODE @NODE usingaide "Using AIDE" Using AIDE ---------- There are five pull-down menus in AIDE: Project, Program, Compiler, Linker and Help. The Project menu is for general house-keeping tasks; the Program menu is for editing, compiling and running ACE programs; the Compiler menu is for setting compiler options; the Linker menu allows you to specify a number of object files or scanned libraries to link with your main ACE program; and the Help menu gives you access to documentation for the compiler, assembler, linker and the ACE language. The entries in each menu will now be described briefly. @{" Project Menu " link projectmenu} @{" Program " link program} @{" Compiler " link compiler} @{" Linker " link linker} @{" Help " link aidehelp} @ENDNODE @NODE projectmenu "Project Menu" Project Menu ============ New - Invokes the editor with a blank slate. Open... - Invokes the editor with a file name which you must specify via a file requester. View... - Lets you view a file which is selected via a file requester. Delete... - Lets you delete a file specified via a file requester. Print... - Lets you choose a file to print via a file requester. Execute... - Allows an AmigaDOS command to be executed. The command and its arguments are entered into an ACE input requester, a console window is opened for any I/O associated with the command and the latter is executed if possible. Spawn Shell - A NewShell process is started for more comprehensive house-keeping than the "Execute..." option is intended for. About - Brings up a message box telling you briefly about AIDE. Quit AIDE - Exits from AIDE. @ENDNODE @NODE program "Program" Program ======= Set Source... - Lets you specify the ACE source file to work with via a file requester. No other Program menu items are accessible until this has been done for the first time. Edit Source - Invokes the editor with the current source file as its argument. Run - Runs the current program, compiling it first if necessary. Compile - Compiles the current program, putting the target assembly source file into the temporary working directory specified in AIDE.config. No executable is produced. This is useful if you just want to see whether a program compiles and/or want to inspect the assembly source file. Make Executable - "Makes" the current program, putting all intermediate files and the final executable program into the temporary working directory specified in AIDE.config. Build Application - Does the same as "Make Executable" but also copies the final executable from temporary storage to the same directory as the original source file or to the directory specified by the BLTDIR config variable. If an icon is requested, this is also copied. View Assembly Source - Allows you to view the target assembly source file which results from compiling a program. View Preprocessed Source - Allows you to view the APP preprocessed source file. Show Compiler Errors - Lets you see the errors (if any) generated by the last compilation. This pertains to ACE errors only at this stage. @ENDNODE @NODE compiler "Compiler" Compiler ======== There are six compiler options in this menu: Break Trapping, Assembly Comments, Create Icon, List Source Lines, Optimise Assembly and Window Trapping which correspond to the compiler's command-line swicthes: b,c,i,l,O and w respectively. See Ace.Guide's "@{"Compiler options" alink ace:docs/ace.guide/2options}" section for details of each of these. Since AIDE always uses ACE's -E switch to create an error file, this option is not available in this menu. Compilation errors are however, viewable from the Program menu's "@{"Show Compiler Errors" link program}" item (see above). The "Optimise Assembly" option is set by default when AIDE starts. Note that if you want AIDE to create an icon for an executable, the file ACE:icons/exe.info MUST exist. This is required by ACE as well (see @{"Ace.Guide" alink ace:docs/ace.guide/2options}). Items in this menu which have a check mark to their left are set. @ENDNODE @NODE linker "Linker" Linker ====== In addition to the normal assembled program file and the scanned libraries incorporated by the linker into the final executable, additional object files to be linked can be specified via this menu. Unless you are using external functions from other scanned libraries or modules (written in C or assembly etc), you may never have cause to use this facility. The list of extra modules to be linked is displayed as part of the menu. These new items cannot be selected and are for display only. Add Module... - Adds an object file or scanned library to the list of modules to be linked. Remove Module... - Removes an object file or scanned library from the list of modules to be linked. Remove All Modules - Removes all modules from the list of extra files to be linked. @ENDNODE @NODE aidehelp "Help" Help ==== This menu provides access to the documentation for the compiler, assembler and linker from within AIDE. In addition, access to the ACE Language Reference file (@{"Ref.Guide" alink ace:docs/ref.guide/main}) is possible via this menu. @ENDNODE @NODE makeprocess "AIDE's Make Process" AIDE's Make Process ------------------- As you may have gleaned from the above, AIDE has a simple inbuilt "make" capability. This means that before it builds or makes an exectuable and prior to compiling or running a program, AIDE checks to see whether compilation needs to take place at all. If you have created an executable and then decide to run the it, AIDE will not re-compile the source first. Likewise, if you want to build an executable and the program has already been compiled, the executable will be copied from AIDE's temporary workspace. In like manner, if you have compiled a program to produce an assembly source file, so long as you don't edit the ACE source file, AIDE will not recompile the program before assembling and linking it. On the other hand if you edit a source file, next time you go to run it, AIDE will "bring the program up to date" by compiling, assembling and linking it first. If you modify the modules list in the Linker menu, AIDE will recompile everything. This is overkill really and a future version will limit this to the link phase. In order to preprocess, compile, assemble and link a program, AIDE first creates a shell script and then executes it, opening a shell in order to do so. Meanwhile, AIDE awaits a communication from the shell process via a PIPE before continuing. In addition to some status messages which AIDE will display, one of two final messages will be received. MakeDone or MakeAborted If an error or user break occurs during preprocessing or compilation, the shell process returns a "MakeAborted" message and AIDE acts accordingly, by, for example, not running the program. If an error or user break occurs during assembly or linking however, you will be left staring at a shell prompt. The simplest way out of this is to issue the following two commands at the shell prompt: QuitMake EndCli one at a time. These will: (i) send a message back to AIDE telling it that something has gone awry during assembly or linking; (ii) close the shell. In case you are interested, "QuitMake" is an alias (for "MakeAborted") set up by AIDE. This is one of those areas in which AIDE could be better, but at least this solution is workable. @ENDNODE @NODE comments "Final Comments" Final Comments -------------- As you can see, there is certainly scope for improvement and it is my hope that AIDE will continue to get better over time. Feel free to make any suggestions about AIDE and please report any bugs to me. See @{"Ace.Guide" alink ace:docs/ace.guide/4final} for details of how to contact me by e-mail, snail-mail or telephone. If you make any substantial changes to AIDE I'd appreciate knowing about them, since I may be able to incorporate such modifications into the next release. Naturally any contributions will be acknowledged. In any case, I hope you find AIDE to be a useful tool for developing ACE programs. Regards, David Benn, Tasmania 15th January 1994 @ENDNODE