home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / dev / basic / ace / aide / aide.doc < prev    next >
Encoding:
Text File  |  1994-10-23  |  13.8 KB  |  425 lines
  1.  
  2.                  +-----------+
  3.                  | AIDE v1.1 |
  4.                  +-----------+
  5.  
  6. Introduction
  7. ------------
  8. AIDE (ACE Integrated Development Environment) is a freely distributable 
  9. graphical front-end for the development of ACE programs.
  10.  
  11. It is written in ACE and currently requires AmigaOS Release 2.04 or higher 
  12. to run.
  13.  
  14. AIDE uses the PIPE: device, so either your startup-sequence script must 
  15. contain the line "mount PIPE:" or you must type this from a shell before 
  16. running AIDE.
  17.  
  18. I will try to get a future version of AIDE running correctly under 1.3 when 
  19. I get some time, but for anyone wishing to have a go at doing this I have 
  20. included the source code (which is also freely distributable but I retain 
  21. the copyright to it). The problems under 1.3 seem to be related to the way 
  22. in which AIDE uses a NewShell and PIPE. In any case, at present if you start 
  23. the program under 1.3, a requester will appear telling you that you need Wb 
  24. 2.04 or higher to run AIDE.
  25.  
  26. ** Please note that this restriction only applies to AIDE not ACE!! **
  27.  
  28. Anyway, if you do have Release 2.04 or higher, you can start AIDE by 
  29. double-clicking its icon from the Workbench. With AIDE, you never need to
  30. start from a shell again when developing ACE programs, although you may 
  31. spawn a shell by selecting an item from AIDE's Project menu (see below).
  32.  
  33. Before starting AIDE for the first time however, you must examine and 
  34. possibly edit one file. This configuration file is discussed next.
  35.  
  36.  
  37. Setting Up
  38. ----------
  39. AIDE requires a file called AIDE.config to be present in the same directory
  40. as itself. Without this, the program won't run.
  41.  
  42. A sample AIDE.config is included in the AIDE archive. It looks like this:
  43.  
  44. ---------------
  45. #
  46. # AIDE configuration file.
  47. #
  48. # For each AIDE configuration variable, 
  49. # replace its value with the full path 
  50. # of the tool or directory of your choice.
  51. #
  52. # All definitions are optional. Place a '#' 
  53. # before a name if you want to comment out
  54. # the corresponding definition.
  55. #
  56.  
  57. ##
  58. ## TOOLS
  59. ##
  60.  
  61. # Editor (default=c:Ed).
  62. #
  63. EDITOR=sys:tools/memacs
  64.  
  65. # File viewer (default=ACE:bin/muchmore).
  66. #
  67. VIEWER=ACE:bin/muchmore
  68.  
  69. # Calculator tool (no default).
  70. #
  71. CALCTOOL=ACE:utils/ACECalc/ACEcalc
  72.  
  73. # AmigaGuide tool. If this entry is set, AIDE uses ref.guide, ace.guide
  74. # and aide.guide instead of the equivalent .doc files. 
  75. #
  76. # Example.Guide also relies upon this tool.
  77. #
  78. # The tool itself is likely to be either AmigaGuide or MultiView. 
  79. #
  80. AGDTOOL=sys:utilities/AmigaGuide
  81.  
  82.  
  83. ##
  84. ## DIRECTORIES
  85. ##
  86.  
  87. # Temporary directory for preprocessor,compiler,assembler & linker
  88. # (default=T:).
  89. #
  90. TMPDIR=T:
  91.  
  92. # Directory in which to (initially) look for ACE source files.
  93. # 
  94. # If not specified, defaults to directory in which AIDE is started from.
  95. #
  96. SRCDIR=ACE:prgs
  97.  
  98. # Directory in which to put built executables and icons.
  99. #
  100. # If not specified, this defaults to the directory in which
  101. # the source file which is being compiled resides.
  102. #
  103. #BLTDIR=ACE:Run
  104.  
  105. # Directory in which docs for the compiler, assembler & linker reside
  106. # (default=ACE:docs).
  107. #
  108. DOCDIR=ACE:docs
  109.  
  110. ---------------
  111.  
  112. In the example above, it is assumed that ACE: is a valid ASSIGN (see 
  113. the "Installation" file which comes with the ACE distribution). Notice
  114. that lines commencing with a "#" are taken to be comments. 
  115.  
  116. AIDE has no built-in editor so you need to specify your favourite. I may
  117. eventually write an editor, but my current feeling is that I can spend
  118. my time more productively in other ways, given the plethora of text editors
  119. available for the Amiga. The same is true for file viewers.
  120.  
  121. If anyone wishes to write a text editor for AIDE, feel free to let me know
  122. about it. Likewise, if you think I should supply a particular FreeWare
  123. editor with AIDE, I'll be glad to consider any suggestions you have.
  124.  
  125. Note that the editor you specify in AIDE.config must be capable of taking
  126. command-line arguments (a file name). The same applies to the file viewer.
  127.  
  128. Once you have set the entries in AIDE.config to your satisfaction, you can 
  129. start AIDE from the Workbench. Note that in order to speed up the load time
  130. of AIDE.config you may wish to copy it to say, AIDE.config.full and remove 
  131. all lines starting with '#' from AIDE.config.
  132.  
  133.  
  134. Using AIDE
  135. ----------
  136. There are six pull-down menus in AIDE: Project, Program, Compiler, Linker,
  137. Utilities and Help. The Project menu is for general house-keeping tasks; the 
  138. Program menu is for editing, compiling and running ACE programs; the Compiler 
  139. menu is for setting compiler options; the Linker menu allows you to specify a 
  140. number of object files or scanned libraries to link with your main ACE 
  141. program; the Utilities menu provides access to a number of useful programs; 
  142. and the Help menu gives you access to documentation for the compiler, assembler,
  143. linker and the ACE language.
  144.  
  145. The entries in each menu will now be described briefly.
  146.  
  147.  
  148. Project Menu
  149. ============
  150.     New        -    Invokes the editor with a blank slate.
  151.  
  152.     Open...        -    Invokes the editor with a file name
  153.                 which you must specify via a file 
  154.                 requester.
  155.  
  156.     View...        -    Lets you view a file which is selected 
  157.                 via a file requester.
  158.     
  159.     Delete...    -    Lets you delete a file specified via a
  160.                 file requester.    
  161.  
  162.     Print...    -    Lets you choose a file to print via a
  163.                 file requester.
  164.  
  165.     Execute...    -    Allows an AmigaDOS command to be executed.
  166.                 The command and its arguments are entered
  167.                 into an ACE input requester, a console
  168.                 window is opened for any I/O associated 
  169.                 with the command and the latter is executed
  170.                 if possible.
  171.                 
  172.     Spawn Shell    -    A NewShell process is started for more
  173.                 comprehensive house-keeping than the 
  174.                 "Execute..." option is intended for.
  175.                 
  176.     About        -    Brings up a message box telling you briefly 
  177.                 about AIDE.
  178.  
  179.     Quit AIDE    -    Exits from AIDE.
  180.  
  181.  
  182. Program
  183. =======
  184.     Set Source...    -    Lets you specify the ACE source file
  185.                 to work with via a file requester. No
  186.                 other Program menu items are accessible
  187.                 until this has been done for the first
  188.                 time.
  189.  
  190.                 The file requester for "Set Source..."
  191.                 starts up in the directory which was
  192.                 referenced the last time this option was 
  193.                 invoked (see also SRCDIR entry in AIDE.config). 
  194.  
  195.                 If the file selected does not exist,
  196.                 ACE will invoke the editor.
  197.  
  198.     Edit Source    -    Invokes the editor with the current 
  199.                 source file as its argument.
  200.  
  201.     Run        -    Runs the current program, compiling it
  202.                 first if necessary.
  203.  
  204.     Run in Shell... -    Runs the current program in a shell, 
  205.                    compiling it first if necessary. Before
  206.                 the program is run, AIDE asks for command
  207.                 line arguments via an input requester. 
  208.                 Supply no arguments if none are required.
  209.         
  210.     Compile        -    Compiles the current program, putting
  211.                 the target assembly source file into the 
  212.                 temporary working directory specified in 
  213.                 AIDE.config. No executable is produced.
  214.                 This is useful if you just want to see
  215.                 whether a program compiles and/or want
  216.                 to inspect the assembly source file.
  217.  
  218.     Make Executable    -    "Makes" the current program, putting
  219.                 all intermediate files and the final
  220.                 executable program into the temporary
  221.                 working directory specified in AIDE.config.
  222.  
  223.       Build Application    -    Does the same as "Make Executable" but
  224.                 also copies the final executable from
  225.                 temporary storage to the same directory
  226.                 as the original source file or to the
  227.                 directory specified by the BLTDIR config
  228.                 variable. If an icon is requested, this
  229.                 is also copied.
  230.     
  231. Create Linkable Module    -    Creates an object module which can later 
  232.                 be linked with an ACE program. The only
  233.                 difference between this option and Make 
  234.                 Executable (above) is that no linking occurs
  235.                 and ACE's -m switch is used. See also "Creating
  236.                 & using ACE subprogram modules" in ace.doc.
  237.             
  238.      View Assembly 
  239.         Source     -    Allows you to view the target assembly
  240.                 source file which results from compiling
  241.                 a program.
  242.  
  243.      View Preprocessed 
  244.         Source    -    Allows you to view the APP preprocessed 
  245.                 source file.
  246.  
  247.        View Compiler 
  248.         Errors    -    Lets you see the errors (if any) generated
  249.                 by the last compilation. This pertains to
  250.                 ACE errors only at this stage.
  251.  
  252. Compiler
  253. ========
  254.     There are seven compiler options in this menu: Preprocess Source,
  255.     Break Trapping, Assembly Comments, Create Icon, List Source Lines, 
  256.     Optimise Assembly and Window Trapping. The latter six correspond 
  257.     to the compiler's command-line switches: b,c,i,l,O and w respectively.
  258.     See ace.doc's "Compiler options" section for details of each of these.
  259.  
  260.     Since AIDE always uses ACE's -E switch to create an error file,
  261.     this option is not available in this menu. Compilation errors are
  262.     however, viewable from the Program menu's "Show Compiler Errors"
  263.     item (see above).
  264.  
  265.     Items in this menu which have a check mark to their left are set.
  266.  
  267.  
  268.     The "Optimise Assembly" option is set by default when AIDE starts.
  269.  
  270.     "Preprocess Source" is also checked at startup. To prevent ACE
  271.     source code from being preprocessed by APP, uncheck this item.
  272.  
  273.     Note that if you want AIDE to create an icon for an executable,
  274.     the file ACE:icons/exe.info MUST exist. This is required by ACE
  275.     as well (see ace.doc).
  276.  
  277.     To save the current compiler options, select the last item in
  278.     the menu: "Save Options". Next time AIDE is run, the Compiler menu 
  279.     will be restored accordingly.
  280.  
  281.  
  282. Linker
  283. ======
  284.     In addition to the normal assembled program file and the scanned
  285.     libraries incorporated by the linker into the final executable,
  286.     additional object files to be linked can be specified via this
  287.     menu.
  288.  
  289.     Unless you are using external functions from other scanned libraries 
  290.     or modules (written in ACE, C or assembly etc), you may never have 
  291.     cause to use this facility.
  292.     
  293.     The list of extra modules to be linked is displayed as part of
  294.     the menu. These new items cannot be selected and are for display
  295.     purposes only.
  296.  
  297.     Add Module...        -     Adds an object file or scanned 
  298.                     library to the list of modules to 
  299.                     be linked. 
  300.     
  301.     Remove Module...    -     Removes an object file or scanned 
  302.                     library from the list of modules to 
  303.                     be linked.
  304.  
  305.     Remove All Modules    -    Removes all modules from the list
  306.                     of extra files to be linked.
  307.  
  308.  
  309. Utilities
  310. =========
  311.     Calculator        -    Invokes the calculator of your
  312.                     choice as specified by CALCTOOL
  313.                     in AIDE.config.
  314.  
  315.     Create BMAP file *    -    Converts the FD file for a library
  316.                     into a .bmap file used by ACE and
  317.                     AmigaBASIC when calling shared
  318.                     library functions. The .bmap file
  319.                     is stored in the ACEbmaps: directory.
  320.  
  321.     AmigaBASIC to ASCII *    -    Converts a compressed AmigaBASIC
  322.                     file into an ASCII text file for
  323.                     use by ACE.
  324.  
  325.  
  326.     * AIDE expects the utility to be in ACE:utils.
  327.  
  328. Help
  329. ====
  330.     This menu provides access to the documentation for the compiler,    
  331.     assembler and linker from within AIDE.
  332.  
  333.     In addition, access to the ACE Language Reference manual, ACE 
  334.     examples, ACE history and this document can be gained via the 
  335.     Help menu.
  336.  
  337.     If you have the AmigaGuide docs: aide.guide, ace.guide and 
  338.     ref.guide ensure that they reside in ACE:docs (or whatever DOCDIR 
  339.     is in AIDE.CONFIG) and that you have an AGDDIR entry in AIDE.CONFIG.
  340.  
  341.     AIDE.GUIDE can reside in ACE:AIDE instead, if so desired.
  342.  
  343.  
  344. AIDE's "Make" Process
  345. ---------------------
  346. As you may have gleaned from the above, AIDE has a simple inbuilt "make" 
  347. capability.
  348.  
  349. This means that before it builds or makes an exectuable and prior to 
  350. compiling or running a program, AIDE checks to see whether compilation
  351. needs to take place at all.
  352.  
  353. If you have created an executable and then decide to run it, AIDE 
  354. will not re-compile the source first. Likewise, if you want to build 
  355. an executable and the program has already been compiled, the executable 
  356. will be copied from AIDE's temporary workspace.
  357.  
  358. In like manner, if you have compiled a program to produce an assembly source
  359. file, so long as you don't edit the ACE source file, AIDE will not recompile
  360. the program before assembling and linking it.
  361.  
  362. On the other hand if you edit a source file, next time you go to run it,
  363. AIDE will "bring the program up to date" by compiling, assembling and linking
  364. it first.
  365.  
  366. If you modify the modules list in the Linker menu, AIDE will recompile  
  367. everything. This is overkill really and a future version will limit this
  368. to the link phase.
  369.  
  370. Making a change to any of the options in the Compiler menu will cause
  371. previous makes to be ignored also.
  372.  
  373. In order to preprocess, compile, assemble and link a program, AIDE first
  374. creates a shell script and then executes it, opening a shell in order to
  375. do so.
  376.  
  377. Meanwhile, AIDE awaits a final message from the shell process via PIPE: 
  378. before continuing. In addition to some status messages which AIDE will
  379. display, one of two final messages will be received.
  380.  
  381.      MakeDone
  382.      or
  383.      MakeAborted
  384.   
  385. If an error or user break occurs during preprocessing or compilation, the
  386. shell process returns a "MakeAborted" message and AIDE acts accordingly, 
  387. by, for example, not running the program.
  388.  
  389. If an error or user break occurs during assembly or linking however, you 
  390. will be left staring at a shell prompt. The simplest way out of this is
  391. to issue the following two commands at the shell prompt:
  392.  
  393.     QuitMake
  394.     EndCli
  395.  
  396. one at a time. These will: (i) send a message back to AIDE telling it that 
  397. something has gone awry during assembly or linking; (ii) close the shell. 
  398. In case you are interested, "QuitMake" is an alias (for "MakeAborted") set 
  399. up by AIDE.
  400.  
  401. This is one area in which AIDE could be improved, but at least the solution 
  402. is workable.
  403.  
  404.     
  405. Final Comments
  406. --------------
  407. As you can see, there is certainly scope for improvement and it is my hope
  408. that AIDE will continue to get better over time.
  409.  
  410. Feel free to make any suggestions about AIDE and please report any bugs 
  411. to me. See ace.doc for details of how to contact me by e-mail, snail-mail
  412. or telephone.
  413.  
  414. If you make any substantial changes to AIDE I'd appreciate knowing about 
  415. them, since I may be able to incorporate such modifications into the next 
  416. release. Naturally any contributions will be acknowledged.
  417.  
  418. In any case, I hope you find AIDE to be a pleasant environment in which
  419. to develop ACE programs.
  420.  
  421. Regards,
  422. David Benn, Launceston, Tasmania
  423.  
  424. 12th October 1994
  425.