home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d9xx / d969 / ace.lha / ACE / ACEupd240194.lha / AIDE / AIDE.doc < prev   
Text File  |  1994-01-23  |  11KB  |  329 lines
  1.                 ----------
  2.                 AIDE v1.01
  3.                 ----------
  4.  
  5. Introduction
  6. ------------
  7. AIDE (ACE Integrated Development Environment) is a freely distributable 
  8. graphical environment for the development of ACE programs.
  9.  
  10. It is written in ACE and currently requires AmigaOS Release 2.04 or higher 
  11. to run.
  12.  
  13. I will try to get a future version of AIDE running correctly under 1.3 when 
  14. I get some time, but for anyone wishing to have a go at doing this I have 
  15. included the source code (which is also freely distributable but I retain 
  16. the copyright to it). The problems under 1.3 seem to be related to the way 
  17. in which AIDE uses a NewShell and PIPE. In any case, at present if you start 
  18. the program under 1.3, a requester will appear telling you that you need Wb 
  19. 2.04 or higher to run AIDE.
  20.  
  21. ** Please note that this restriction only applies to AIDE not ACE!! **
  22.  
  23. Anyway, if you do have Release 2.04 or higher, you can start AIDE by 
  24. double-clicking its icon from the Workbench. With AIDE, you never need to
  25. start from a shell again when developing ACE programs, although you may 
  26. spawn a shell by selecting an item from AIDE's Project menu (see below).
  27.  
  28. Before starting AIDE for the first time however, you must modify one file.
  29. This configuration file is discussed next.
  30.  
  31.  
  32. Setting Up
  33. ----------
  34. AIDE requires a file called AIDE.config to be present in the same directory
  35. as itself. Without this, the program won't run.
  36.  
  37. A sample AIDE.config is included in the AIDE archive. It looks like this:
  38.  
  39. #
  40. # AIDE configuration file.
  41. #
  42. # For each AIDE configuration variable, 
  43. # replace its value with the full path 
  44. # of the tool or directory of your choice.
  45. #
  46. # An entry with a "*" next to its comment 
  47. # is NOT optional.
  48. #
  49.  
  50. # Editor *
  51. EDITOR=sys:tools/memacs
  52.  
  53. # File viewer *
  54. VIEWER=ACE:bin/muchmore
  55.  
  56. # Temporary directory for preprocessor,compiler,assembler & linker. *
  57. TMPDIR=RAM:t
  58.  
  59. # Directory in which to put built executables and icons.
  60. # If not specified, this defaults to the directory in which
  61. # the source file which is being compiled resides.
  62. BLTDIR=ACE:Run
  63.  
  64. # Directory in which docs for the compiler, assembler & linker reside. *
  65. DOCDIR=ACE:docs
  66.  
  67. ---------------
  68.  
  69. There are currently four entries which MUST have valid values. Notice 
  70. that in the example above, it is assumed that ACE: is a valid ASSIGN. See 
  71. the "Installation" file which comes with the main ACE archive. Note also 
  72. that lines commencing with a "#" are taken to be comments. 
  73.  
  74. AIDE has no built-in editor so you need to specify your favourite. I may
  75. eventually write an editor, but my current feeling is that I can spend
  76. my time more productively in other ways, given the plethora of text editors
  77. available for the Amiga. The same is true for file viewers.
  78.  
  79. If anyone wishes to write a text editor for AIDE, feel free to let me know
  80. about it. Likewise, if you think I should supply a particular FreeWare
  81. editor with AIDE, I'll be glad to consider any suggestions you have.
  82.  
  83. Note that the editor you specify in AIDE.config must be capable of taking
  84. command-line arguments (namely: a file name). The same applies to the file
  85. viewer.
  86.  
  87. Once you have set the entries in AIDE.config to your satisfaction, you can 
  88. start AIDE from the Workbench.
  89.  
  90.  
  91. Using AIDE
  92. ----------
  93. There are five pull-down menus in AIDE: Project, Program, Compiler, Linker
  94. and Help. The Project menu is for general house-keeping tasks; the Program
  95. menu is for editing, compiling and running ACE programs; the Compiler menu 
  96. is for setting compiler options; the Linker menu allows you to specify a 
  97. number of object files or scanned libraries to link with your main ACE 
  98. program; and the Help menu gives you access to documentation for the 
  99. compiler, assembler, linker and the ACE language.
  100.  
  101. The entries in each menu will now be described briefly.
  102.  
  103.  
  104. Project Menu
  105. ============
  106.     New        -    Invokes the editor with a blank slate.
  107.  
  108.     Open...        -    Invokes the editor with a file name
  109.                 which you must specify via a file 
  110.                 requester.
  111.  
  112.     View...        -    Lets you view a file which is selected 
  113.                 via a file requester.
  114.     
  115.     Delete...    -    Lets you delete a file specified via a
  116.                 file requester.    
  117.  
  118.     Print...    -    Lets you choose a file to print via a
  119.                 file requester.
  120.  
  121.     Execute...    -    Allows an AmigaDOS command to be executed.
  122.                 The command and its arguments are entered
  123.                 into an ACE input requester, a console
  124.                 window is opened for any I/O associated 
  125.                 with the command and the latter is executed
  126.                 if possible.
  127.                 
  128.     Spawn Shell    -    A NewShell process is started for more
  129.                 comprehensive house-keeping than the 
  130.                 "Execute..." option is intended for.
  131.  
  132.     About        -    Brings up a message box telling you briefly 
  133.                 about AIDE.
  134.  
  135.     Quit AIDE    -    Exits from AIDE.
  136.  
  137.  
  138. Program
  139. =======
  140.     Set Source...    -    Lets you specify the ACE source file
  141.                 to work with via a file requester. No
  142.                 other Program menu items are accessible
  143.                 until this has been done for the first
  144.                 time.
  145.     
  146.     Edit Source    -    Invokes the editor with the current 
  147.                 source file as its argument.
  148.  
  149.     Run        -    Runs the current program, compiling it
  150.                 first if necessary.
  151.  
  152.     Run in Shell... -    Runs the current program in a shell, 
  153.                    compiling it first if necessary. Before
  154.                 the program is run, AIDE asks for command
  155.                 line arguments via an input requester. 
  156.                 Supply no arguments if none are required.
  157.         
  158.     Compile        -    Compiles the current program, putting
  159.                 the target assembly source file into the 
  160.                 temporary working directory specified in 
  161.                 AIDE.config. No executable is produced.
  162.                 This is useful if you just want to see
  163.                 whether a program compiles and/or want
  164.                 to inspect the assembly source file.
  165.  
  166.     Make Executable    -    "Makes" the current program, putting
  167.                 all intermediate files and the final
  168.                 executable program into the temporary
  169.                 working directory specified in AIDE.config.
  170.  
  171.       Build Application    -    Does the same as "Make Executable" but
  172.                 also copies the final executable from
  173.                 temporary storage to the same directory
  174.                 as the original source file or to the
  175.                 directory specified by the BLTDIR config
  176.                 variable. If an icon is requested, this
  177.                 is also copied.
  178.                 
  179.      View Assembly 
  180.         Source     -    Allows you to view the target assembly
  181.                 source file which results from compiling
  182.                 a program.
  183.  
  184.      View Preprocessed 
  185.         Source    -    Allows you to view the APP preprocessed 
  186.                 source file.
  187.  
  188.        Show Compiler 
  189.         Errors    -    Lets you see the errors (if any) generated
  190.                 by the last compilation. This pertains to
  191.                 ACE errors only at this stage.
  192.  
  193. Compiler
  194. ========
  195.     There are six compiler options in this menu: Break Trapping,
  196.     Assembly Comments, Create Icon, List Source Lines, Optimise
  197.     Assembly and Window Trapping which correspond to the compiler's
  198.     command-line swicthes: b,c,i,l,O and w respectively. See ace.doc's
  199.     "Compiler options" section for details of each of these.
  200.  
  201.     Since AIDE always uses ACE's -E switch to create an error file,
  202.     this option is not available in this menu. Compilation errors are
  203.     however, viewable from the Program menu's "Show Compiler Errors"
  204.     item (see above).
  205.  
  206.     The "Optimise Assembly" option is set by default when AIDE starts.
  207.  
  208.     Note that if you want AIDE to create an icon for an executable,
  209.     the file ACE:icons/exe.info MUST exist. This is required by ACE
  210.     as well (see ace.doc).
  211.  
  212.     Items in this menu which have a check mark to their left are set.
  213.  
  214.  
  215. Linker
  216. ======
  217.     In addition to the normal assembled program file and the scanned
  218.     libraries incorporated by the linker into the final executable,
  219.     additional object files to be linked can be specified via this
  220.     menu.
  221.  
  222.     Unless you are using external functions from other scanned libraries 
  223.     or modules (written in C or assembly etc), you may never have cause 
  224.     to use this facility.
  225.     
  226.     The list of extra modules to be linked is displayed as part of
  227.     the menu. These new items cannot be selected and are for display
  228.     only.
  229.  
  230.     Add Module...        -     Adds an object file or scanned 
  231.                     library to the list of modules to 
  232.                     be linked. 
  233.     
  234.     Remove Module...    -     Removes an object file or scanned 
  235.                     library from the list of modules to 
  236.                     be linked.
  237.  
  238.     Remove All Modules    -    Removes all modules from the list
  239.                     of extra files to be linked.
  240.  
  241.  
  242. Help
  243. ====
  244.     This menu provides access to the documentation for the compiler,    
  245.     assembler and linker from within AIDE.
  246.  
  247.     In addition, access to the ACE Language Reference file (ref.doc) 
  248.     is possible via this menu.
  249.  
  250.  
  251. AIDE's Make Process
  252. -------------------
  253. As you may have gleaned from the above, AIDE has a simple inbuilt "make" 
  254. capability.
  255.  
  256. This means that before it builds or makes an exectuable and prior to 
  257. compiling or running a program, AIDE checks to see whether compilation
  258. needs to take place at all.
  259.  
  260. If you have created an executable and then decide to run the it, AIDE 
  261. will not re-compile the source first. Likewise, if you want to build 
  262. an executable and the program has already been compiled, the executable will 
  263. be copied from AIDE's temporary workspace.
  264.  
  265. In like manner, if you have compiled a program to produce an assembly source
  266. file, so long as you don't edit the ACE source file, AIDE will not recompile
  267. the program before assembling and linking it.
  268.  
  269. On the other hand if you edit a source file, next time you go to run it,
  270. AIDE will "bring the program up to date" by compiling, assembling and linking
  271. it first.
  272.  
  273. If you modify the modules list in the Linker menu, AIDE will recompile  
  274. everything. This is overkill really and a future version will limit this
  275. to the link phase.
  276.  
  277. In order to preprocess, compile, assemble and link a program, AIDE first
  278. creates a shell script and then executes it, opening a shell in order to
  279. do so.
  280.  
  281. Meanwhile, AIDE awaits a communication from the shell process via a PIPE 
  282. before continuing. In addition to some status messages which AIDE will
  283. display, one of two final messages will be received.
  284.  
  285.      MakeDone
  286.      or
  287.      MakeAborted
  288.   
  289. If an error or user break occurs during preprocessing or compilation, the
  290. shell process returns a "MakeAborted" message and AIDE acts accordingly, 
  291. by, for example, not running the program.
  292.  
  293. If an error or user break occurs during assembly or linking however, you 
  294. will be left staring at a shell prompt. The simplest way out of this is
  295. to issue the following two commands at the shell prompt:
  296.  
  297.     QuitMake
  298.     EndCli
  299.  
  300. one at a time. These will: (i) send a message back to AIDE telling it that 
  301. something has gone awry during assembly or linking; (ii) close the shell. 
  302. In case you are interested, "QuitMake" is an alias (for "MakeAborted") set 
  303. up by AIDE.
  304.  
  305. This is one of those areas in which AIDE could be better, but at least
  306. this solution is workable.
  307.  
  308.     
  309. Final Comments
  310. --------------
  311. As you can see, there is certainly scope for improvement and it is my hope
  312. that AIDE will continue to get better over time.
  313.  
  314. Feel free to make any suggestions about AIDE and please report any bugs 
  315. to me. See ace.doc for details of how to contact me by e-mail, snail-mail
  316. or telephone.
  317.  
  318. If you make any substantial changes to AIDE I'd appreciate knowing about 
  319. them, since I may be able to incorporate such modifications into the next 
  320. release. Naturally any contributions will be acknowledged.
  321.  
  322. In any case, I hope you find AIDE to be a useful tool for developing ACE 
  323. programs.
  324.  
  325. Regards,
  326. David Benn, Tasmania
  327.  
  328. 23rd January 1994
  329.