home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format 91 / af091a.adf / af91a1.lzx / AIDE / AIDE.doc < prev    next >
Text File  |  1996-09-14  |  40KB  |  1,132 lines
  1.  
  2.                          +------------------+
  3.                          |    AIDE v2.02    |
  4.                          +------------------+
  5.  
  6. Introduction
  7. ------------
  8.  
  9. AIDE (ACE Integrated Development Environment) is a freely distributable
  10. graphical front-end for the development of ACE programs.
  11.  
  12. It requires AmigaOS Release 2.04 or higher to run.
  13.  
  14. If you do have Release 2.04 or higher, you can start AIDE by double-clicking
  15. its icon from the Workbench. With AIDE, you never need to start from a shell
  16. again when developing ACE programs, although you may spawn a shell by
  17. selecting an item from AIDE's Project menu (see below).
  18.  
  19. Note:
  20.  
  21. You don't have to worry about the stack size any more if you use AIDE.
  22. AIDE will setup a stack size of 40000 bytes for any process run by AIDE.
  23. AIDE only uses the default stack size of 4096 bytes!
  24.  
  25.  
  26. Setting Up
  27. ----------
  28.  
  29. Before starting AIDE for the first time however, you must have ACE installed
  30. correctly with the following corresponding directories:
  31.  
  32.     ACE:
  33.     ACE:AIDE
  34.     ACE:bin
  35.     ACElib:       (ACE:lib)
  36.     ACEinclude:   (ACE:include)
  37.     ACEbmaps:     (ACE:bmaps)
  38.  
  39.     (see ACE.doc/ACE.guide for the details)
  40.  
  41. If these dirs aren't set up correctly, AIDE will abort with an error message.
  42.  
  43. Also you need:
  44.  
  45.     mrt.library     (just put it somewhere in your LIBS: path)
  46.     thinpaz.font    (just put it in FONTS:)
  47.  
  48. These files will be in the archive.
  49.  
  50. Also distributed with AIDE will be the freeware version of PhxAss and
  51. PhxLnk from Frank Wille as an alternative to A68K and BLink.
  52.  
  53. *** Note: To cut down on archive size, I've omitted PhxAss/Lnk from
  54.       the ACE v2.4 distribution. You can obtain these programs
  55.       from Aminet sites in dev/ass. [David Benn, September 1996]
  56.  
  57. To work fine and easy with AIDE the following dirs should also exist:
  58.  
  59.  
  60.     ACE:Docs/       (where all the docs reside)
  61.  
  62.     ACE:Icons/      (where the necessary icons for ACE should be)
  63.  
  64.     ACE:Mods/       (where your compiled SubMods reside)
  65.  
  66.     ACE:Prgs/       (where your source code reside)
  67.  
  68.     ACE:Run/        (where your executables are going)
  69.  
  70.     ACE:Temp/       (where your temporary files during compilation
  71.                      are going.)
  72.  
  73.     ACE:Utils/      (where all the ACE related utilities reside)
  74.  
  75.     ACE:Utils/ACEcalc/ACEcalc
  76.  
  77.     ACE:Utils/ReqEd/ReqEd
  78.  
  79.     ACE:Utils/FD2BMAP/FD2BMAP
  80.  
  81.     ACE:Utils/AB2ASCII/AB2ASCII
  82.  
  83.     ACE:Utils/UppercACEr/UppercACEr
  84.  
  85.  
  86. If those dirs don't exist, AIDE's internal configuration part gives you
  87. the possibility to do the setup to your personal need.
  88.  
  89. AIDE will create a new file called AIDE2.config to run properly. If you
  90. have old config files from AIDE1.5 and before, your settings will be
  91. copied to the new file. You can later delete the old files, if you wish.
  92. You can't edit the new file any more, just use the integrated setup
  93. part in AIDE (see below).
  94.  
  95. No AIDE2.config is included in the AIDE archive, if it doesn't exist,
  96. AIDE will create one with the default settings.
  97.  
  98. If all the directories exist, as mentioned above, AIDE will create the
  99. setup in this way, that you don't need to setup these settings manually.
  100. Only for options, like PubScreen, Requester, .... you need to open
  101. the setup window, anything else is already done.
  102.  
  103. Remember:
  104.  
  105. ACE:Temp is the default directory for temporary files during compilation.
  106. This dir will be normally on HD so the times for writing and reading files
  107. will be short. The change from T: to ACE:Temp has the reason to save memory
  108. during compilation. If the default would be T: and T: resides in memory
  109. (system default), then the source files are two times in memory.
  110. Memory is always short, so it is better to have the temporary dir on HD
  111. and not in RAM:. You may change it to your personal taste anyway, but
  112. this is the default.
  113.  
  114. AIDE has no built-in editor, so you need to specify your favourite.
  115. If no one is specified, the editor called "Ed" which resides in "C:"
  116. will be used.
  117.  
  118. Note:
  119. The editor you specify must be capable of taking command-line arguments
  120. (e.g. a file name).
  121.  
  122. AIDE has no built-in viewer either. If ACE:Bin/MuchMore does exist, this
  123. one will be used (default). If you have AmigaGuide/MultiView installed
  124. (system default since Wb2.1), it will be used for all the corresponding
  125. Amigaguide files in ACE:Docs.
  126.  
  127. If you want to view all files with Amigaguide/Multiview you have to
  128. specify Amigaguide/Multiview for the viewer, too.
  129.  
  130. Note:
  131.  
  132. The text viewer you specify in AIDE.config must be capable of taking
  133. command-line arguments (e.g. a file name).
  134.  
  135.  
  136. Important Notes about the general behavior of AIDE:
  137.  
  138.     For "Run" and "Run in Shell" and all other applications the following
  139.     CON: window definitions are used:
  140.  
  141.  
  142.     "CON:xpos/ypos/1280/200/ AIDE Shell Window/AUTO/WAIT/CLOSE"
  143.  
  144.  
  145.     AUTO  = the window will only be opened if there is any CLI output
  146.             or input from the started process.
  147.  
  148.     WAIT  = the window will only be closed, when the user clicks the
  149.             close button.
  150.  
  151.     CLOSE = a close button for the window is added.
  152.  
  153.     Therefore you have to close the output window manually when a program
  154.     did finish the task. I did add this behavior so you can read the
  155.     output from a program. If WAIT would not be set, the window would be
  156.     closed before you could have read the output from your or any other
  157.     program used by AIDE. You don't need to add the following lines
  158.     to your code, if you only want to read the output from PRINT for
  159.     testing purpose.
  160.  
  161.     WHILE INKEY$ <> "q" : WEND
  162.  
  163.     During the compilation run only the flag AUTO is used, so you don't
  164.     need to close the CON: window.
  165.  
  166.  
  167.     The system will automatically open the window with the right width.
  168.     On systems with a higher resolution the CON: window will fit the
  169.     width of the Workbench screen now.
  170.  
  171.  
  172.  
  173.     AIDE is using the DOS function SystemTagList() to start all external
  174.     programs integrated in AIDE.
  175.  
  176.     Whenever it is possible and whenever it makes sense, the started process
  177.     is running asynchronously.
  178.  
  179.     Some are still running synchronously, like the make process or the
  180.     editor when editing the source file.
  181.  
  182.  
  183. Using AIDE
  184. ----------
  185.  
  186. When you start AIDE the first time you will realise a big difference
  187. to earlier versions. AIDE has a complete GUI now with many gadgets and
  188. new functions added.
  189.  
  190. There are three pull-down menus in AIDE: Project, Utilities and Help.
  191.  
  192. The Project menu is for general house-keeping tasks;
  193. The  Utilities menu provides access to a number of useful programs;
  194. The Help menu gives you access to documentation for the compiler, assembler,
  195. linker and the ACE language.
  196.  
  197. The entries in each menu will now be described briefly.
  198.  
  199.  
  200. Project Menu
  201. ============
  202.  
  203.     Open...     -   Invokes the editor with a file name
  204.                     which you must specify via a file
  205.                     requester. If no file name is given,
  206.                     AIDE will inform you with a message.
  207.                     This option is included to edit any
  208.                     file of your choice. For editing the
  209.                     source file see below. The current used
  210.                     dir will be remembered, so you don't have
  211.                     to switch to all the directories again.
  212.  
  213.     View...     -   Lets you view a file which is selected
  214.                     via a file requester. Remembers the
  215.                     current dir.
  216.  
  217.  
  218.     Rename...   -   Lets you rename a file specified via a
  219.                     file requester. Remembers the
  220.                     current dir.
  221.  
  222.                     First a file requester will be opened
  223.                     where you have to select a file, which
  224.                     you want to rename. Now a second file
  225.                     requester appears where you have to select
  226.                     the new name. You can change the directory
  227.                     name, too, so a rename has the same
  228.                     effect as "move a file". This is only possible
  229.                     for the same device.
  230.  
  231.  
  232.     Copy...     -   Lets you copy a file specified via a
  233.                     file requester. Remembers the
  234.                     current dir.
  235.  
  236.                     There will be also two file requester:
  237.                     the first one to choose the source file,
  238.                     the second one to choose the destination
  239.                     dir and file name.
  240.                     If you change the name for the destination
  241.                     file, it will be copied with the new name.
  242.  
  243.     Delete...   -   Lets you delete a file specified via a
  244.                     file requester. Remembers the
  245.                     current dir.
  246.  
  247.                     Note:
  248.                     No second requester will appear, asking,
  249.                     if you really want to delete this file.
  250.                     You can't double click the filename.
  251.                     You have to choose "OK", to perform the
  252.                     action.
  253.  
  254.     Print...    -   Lets you choose a file to print via a
  255.                     file requester. Remembers the
  256.                     current dir.
  257.  
  258.                     Note:
  259.                     This function is very simple. It uses
  260.                     your printer preferences, as setup via
  261.                     the prefs tool from your workbench disk.
  262.                     No page checking, no formatting, nothing
  263.                     else is done.
  264.                     The function prints files, no matter which
  265.                     size, when they can be loaded in memory.
  266.  
  267.                     This maybe more comfortable in a future
  268.                     release. ;-)
  269.  
  270.     Execute...  -   Allows an AmigaDOS command to be executed.
  271.                     The command and its arguments are entered
  272.                     into an input requester, a console
  273.                     window is opened for any I/O associated
  274.                     with the command and the latter is executed
  275.                     if possible.
  276.  
  277.     Spawn Shell -   A NewShell process is started for more
  278.                     comprehensive house-keeping than the
  279.                     "Execute..." option is intended for.
  280.                     Your default settings as defined in
  281.                     S:Shell-Startup are used.
  282.  
  283.     AIDE setup  -   Opens a new window where you can setup all your
  284.                     directories and some options for AIDE.
  285.                     (See the explanation of the setup part
  286.                      behind the menu description.)
  287.  
  288.     Load Config File
  289.     Save Config File
  290.                     You can create now multiple config files.
  291.                     With these two functions you can load/save
  292.                     now the default or any other config file.
  293.  
  294.                     default:
  295.  
  296.                     - will try to load/save a file named ACE:AIDE/AIDE2.config
  297.  
  298.                     other:
  299.  
  300.                     - will bring up a file requester where you can specify
  301.                       any directory and filename of your choice.
  302.  
  303.     About       -   Brings up a message box telling you briefly
  304.                     about AIDE.
  305.  
  306.     Quit AIDE   -   Exits from AIDE. (You can also click the close gadget of the
  307.                     main window.)
  308.  
  309.  
  310. Utilities
  311. =========
  312.  
  313. Note:
  314.  
  315.    You need:
  316.  
  317.             ACE:Utils/ACEcalc/ACEcalc
  318.  
  319.             ACE:Utils/ReqEd/ReqEd
  320.  
  321.             ACE:Utils/FD2BMAP/FD2BMAP
  322.  
  323.             ACE:Utils/AB2ASCII/AB2ASCII
  324.  
  325.             ACE:Utils/UppercACEr/UppercACEr
  326.  
  327.     or an corresponding entry in AIDE2.config to use these functions.
  328.  
  329.     Calculator  -   Invokes the calculator
  330.  
  331.     ReqEd       -   Invokes ReqEd
  332.  
  333.     Create BMAP file(s)
  334.  
  335.                 -   Converts the FD file(s) for a library
  336.                     into a .bmap file used by ACE and
  337.                     AmigaBASIC when calling shared
  338.                     library functions. The .bmap file
  339.                     is stored in the ACEbmaps: directory.
  340.                     Invokes a file requester for selection.
  341.  
  342.                     You can select only one, all, or the specific
  343.                     files you want to convert via the filerequester.
  344.  
  345.     Because no doc file exists for fd2bmap, which is used to perform
  346.     the task, the header of the ACE source file is integrated here.
  347.  
  348.  
  349.     >FD2BMAP Library DestDir
  350.     >
  351.     >by Harald Schneider
  352.     >
  353.     >Converts FD-File to a ACE-BMAP File like Commodores ConvertFD.
  354.     >
  355.     >Example: FD2BMAP l/dos RAM: reads l/dos_lib.fd and creates RAM:dos.bmap
  356.     >
  357.     >Differences to ConvertFD:
  358.     >    - #private marked entries are skipped
  359.     >    - Unlike AmigaBasic ACE allows the use of A5 for parameters so
  360.     >      functions uses A5 are not ignored
  361.     >
  362.     >Name collision of ACE keywords and library calls are handled like
  363.     >ConvertFD (Read --> _Read    -    note: prior to v1.2, it used to
  364.     >be that 'x' rather than '_' was prefixed to the identifier).
  365.     >
  366.     >Modified by David Benn: 10th,17th January, 10th August 1994,
  367.     >                        15th October 1994, 15th September 1995
  368.  
  369.  
  370.     AmigaBASIC to ASCII
  371.  
  372.                 -   Converts a compressed AmigaBASIC
  373.                     file into an ASCII text file for
  374.                     use by ACE.
  375.                     Invokes a file requester for selection
  376.                     of the input and output dir and file name.
  377.  
  378.     Because no doc file exists for AB2ASCII, a part ot the README file
  379.     is integrated here:
  380.  
  381.     >AB2ASCII - Generate ASCII source from binary AmigaBasic files
  382.     >
  383.     >Usage:
  384.     >ab2ascii <binary_file [>source_file]
  385.     >
  386.     >Note:
  387.     >    The program rewind()s its stdin stream once. So a pipe is no
  388.     >    acceptable input.
  389.     >
  390.     >Comments:
  391.     >       I cannot guarrantee that the program understands all token
  392.     >       constructs that AmigaBasic can produce AND translates them
  393.     >       correctly. I obtained the `token dictionary' by trial and
  394.     >       error (I did not disassemble AmigaBasic). For the programs
  395.     >       I tested it on it seemed to work. The program could be less
  396.     >       memory-consuming, (much) faster and in general be better coded.
  397.     >       Users are invited to make any improvements they feel up to
  398.     >       (the program belongs to you!).
  399.     >
  400.     >Author:
  401.     >       Stefan Reisner
  402.     >       sr@ph-cip.uni-koeln.de
  403.     >
  404.     >Copying:
  405.     >       Public Domain
  406.  
  407.  
  408.     Note:
  409.         Be very careful if you use AB2ASCII. The program is not working
  410.         very well!
  411.  
  412.  
  413.         a)
  414.           If the selected file is not an compressed AmigaBASIC file,
  415.           AB2ASCII will hang and never return.
  416.  
  417.  
  418.         b)
  419.           If the selected file contains token constructs, AB2ASCII
  420.           doesn't understand, AB2ASCII will create a file from
  421.           a size, until your disk is full.
  422.           Try ConvertFD, which is distributed by C= on the Extras1.3
  423.           disk in the BasicDemos directory, to verify this behavior,
  424.           if you want to fill your disk. :-)
  425.  
  426.  
  427.         c)
  428.           AB2ASCII produces no output, nor an error message.
  429.           So take care when you want to use it. If you have
  430.           AmigaBASIC, use it for converting the files.
  431.  
  432.  
  433.     Any experienced C programmer is invited to improve this code.
  434.     Send new codes to me for testing. (Author Address see below)
  435.  
  436.  
  437.     UppercACEr  -   Invokes UppercACEr
  438.  
  439.                 Please read the corresponding doc file for the details.
  440.  
  441.                 Important:
  442.                         The file UppercACEr.Reserved must reside
  443.                         in S:!
  444.  
  445.                 In any case you don't have to worry about the filenames.
  446.                 AIDE handles that for you. The converted file will have
  447.                 a _u extension to the filename like:
  448.  
  449.                 UppercACEr test.b test_u.b
  450.  
  451.  
  452.     Utility 0 to 3  Here you have the possibility to specify any
  453.                     utility of your choice. A corresponding entry
  454.                     in AIDE2.config must exist!
  455.  
  456.                     You can only use tools, which don't need an
  457.                     argument to run.
  458.  
  459.                     This maybe changed in a future release.
  460.  
  461. Help
  462. ====
  463.  
  464.     This menu provides access to the documentation for the compiler,
  465.     SuperOptimizer, assembler and linker from within AIDE.
  466.  
  467.     In addition, access to the ACE Language Reference manual, ACE
  468.     examples, ACE history and this document can be gained via the
  469.     Help menu.
  470.  
  471.     The Help function will do nothing if no viewer at all is specified.
  472.  
  473.     All the supported doc files must reside in your specified "Doc Dir".
  474.  
  475.     The supported docs are:
  476.  
  477.     AIDE.doc (/AIDE.guide will be available later)
  478.     ACE.doc/ACE.guide
  479.     SuperOptimizer.guide
  480.     A68K.doc
  481.     PhxAss.guide
  482.     BLink.doc
  483.     PhxLnk.guide
  484.     ref.guide
  485.     ace-rwords
  486.     example.guide
  487.     history
  488.     ACEcalc.doc (/ACEcalc.guide if available)
  489.     ReqEd.doc   (/ReqEd.guide if available)
  490.  
  491.     Note:
  492.          The docs must exist under the names described above.
  493.          AIDE relies on them. If you have other docs, you can
  494.          view them with the function "View" from the "Project"
  495.          menu in any case.
  496.  
  497. AIDE setup
  498. ==========
  499.  
  500.     This is completely new, so you don't have to edit a config file
  501.     outside of AIDE. All the settings you change there will be active
  502.     immediately despite of one.
  503.  
  504.  
  505.     Just one word to the default font setting:
  506.  
  507.     Thinpaz.font is used so all the gadgets will fit in a window which
  508.     can be displayed on a standard NTSC screen. For those who use a higher
  509.     resolution of their Workbench screen, the option "Public Screen" can be
  510.     used.
  511.  
  512.  
  513.     Directory Setup:
  514.     ----------------
  515.  
  516.     Well, when you choose AIDE setup the main window will be closed and the
  517.     setup window will be opened. On the left side there are all the string
  518.     gadgets for the directory setup. If you want to change the names manually
  519.     you can do it there. If you type an error the old entry will be displayed
  520.     again and the string gadget will be set to active state.
  521.     When you select the "R" button ("R" means requester), right beside the
  522.     string gadget, an ASL file requester will pop up where you can choose
  523.     a directory or file name of your choice.
  524.  
  525.     Note:
  526.  
  527.     If only a directory is necessary for the setup a selected file name will
  528.     be ignored.
  529.  
  530.     If no file name is selected where one is absolutely necessary, your
  531.     choice will not be accepted.
  532.  
  533.  
  534.     Other:
  535.     ------
  536.  
  537.         Public Screen:
  538.                         Here you have the choice to define, if AIDE should
  539.                         run on an own public screen. This screen will have
  540.                         "Shanghai" abilities. That means that all windows
  541.                         which would normally be opened on the Workbench
  542.                         screen, will now be opened on the AIDE screen.
  543.                         The AIDE screen will close automatically if
  544.                         the AIDE window and all the visitor windows are
  545.                         closed.
  546.  
  547.                         This is the only setting which will have effect,
  548.                         when you start AIDE again after saving your
  549.                         config file as default (AIDE2.config).
  550.  
  551.                         This maybe changed in a future release.
  552.  
  553.         Requester:
  554.                         Here you have the choice to define:
  555.  
  556.                         All:    all requester will be displayed
  557.                         Error:  only error requester will be displayed
  558.                         Min:    only fatal error requester will be displayed!
  559.  
  560.                         Just try it out and set this flag to your personal
  561.                         taste.
  562.  
  563.         Clean up:       Here you have the choice to define:
  564.  
  565.                         Yes:    This is the default setting and that means
  566.                                 that all the temporary files will be deleted
  567.                                 when you quit AIDE.
  568.  
  569.                         No:     If you select this, then no temporary files
  570.                                 will be deleted when you quit AIDE. That
  571.                                 maybe useful if you want to have a look
  572.                                 at those files later. Older versions of
  573.                                 AIDE will always delete those files.
  574.                                 Still all temporary files will be deleted
  575.                                 when you perform a new compiler run.
  576.  
  577.                         Note:
  578.  
  579.                         ACE.err is now found in ACE:temp and no longer
  580.                         in ACE:AIDE.
  581.  
  582.  
  583.         Menu Pen:       Here you can select the color of the menu pen from
  584.                         0 to 2. This maybe useful if you don't like
  585.                         the default setting of menu pen 0 (background color).
  586.  
  587.  
  588. Icon Tooltypes
  589. ==============
  590.  
  591.     You can configure AIDE now via the tooltypes entry of the source file
  592.     icon and the AIDE program icon. The defined tooltypes are:
  593.  
  594.     FILETYPE    =   ACESource
  595.  
  596.                     If you are using icons for your source files that has
  597.                     to be set, otherwise this file will be ignored!
  598.                     This has the same effect as the .b/.bas extension when
  599.                     you select a source file via file requester.
  600.  
  601.                     Note:
  602.                     This entry is ignored if set in the AIDE program icon.
  603.  
  604.  
  605.     CONFIGFILE  =   AIDE2.config or any other configfile name you have
  606.                     specified for this source file.
  607.  
  608.  
  609.     PRECO       =   app or any other precompiler you want to use with this
  610.                     source file.
  611.  
  612.                     This is really useful because there are many source files
  613.                     which still need APP instead of ACPP. So you don't have
  614.                     to remember any more which source file needs which
  615.                     precompiler.
  616.  
  617.                     Note:
  618.                     An example source icon is included in this archive.
  619.  
  620. Main Window
  621. ===========
  622.  
  623. The main window holds now the functions and many more, which were found
  624. before in the pull down menu.
  625.  
  626. All these functions are necessary to compile ACE program under different
  627. conditions in a comfortable way.
  628.  
  629.  
  630. Source
  631. ======
  632.  
  633.     Set         -   Lets you specify the ACE source file
  634.                     to work with, via a file requester.
  635.                     Some gadgets aren't accessible until this
  636.                     has been done for the first time.
  637.  
  638.                     The file requester for "Set Source..."
  639.                     starts up in the directory which was
  640.                     referenced the last time this option was
  641.                     invoked.
  642.  
  643.                     If the file selected does not exist,
  644.                     AIDE will invoke the editor.
  645.  
  646.     Reset       -   Resets the current source file for a new
  647.                     compiler run. Useful if you did invoke
  648.                     the editor outside of AIDE.
  649.  
  650.     Edit        -   Invokes the editor with the current
  651.                     source file as its argument.
  652.                     If no editor is specified, this option
  653.                     will be disabled
  654.  
  655. Program
  656. =======
  657.  
  658.     Precompile  -   This will invoke the specified precompiler
  659.                     with the current source file as its
  660.                     argument. No check if the source file was
  661.                     already precompiled is done.
  662.  
  663.     Compile     -   This will invoke ACE and the SuperOptimizer
  664.                     if set to active.
  665.                     No check if the source file was already compiled
  666.                     is done.
  667.  
  668.     Assemble    -   This will invoke the selected assembler.
  669.                     No check if the source file was already assembled
  670.                     is done.
  671.  
  672.     Link        -   This will invoke the selected linker.
  673.                     No check if the source file was already linked
  674.                     is done.
  675.  
  676.     Run         -   Runs the current program, compiling it
  677.                     first if necessary.
  678.  
  679.                     Important:
  680.  
  681.                     This functions can now be used for CLI programs,
  682.                     too, but no input box will appear. If you need
  683.                     to specify a command line argument use "Run in Shell"
  684.                     instead. But if you don't need to enter command line
  685.                     arguments, this function will do now the same task.
  686.  
  687.     Run in Shell-   Runs the current program in a shell,
  688.                     compiling it first if necessary. Before
  689.                     the program is run, AIDE asks for command
  690.                     line arguments via an input requester.
  691.                     Supply no arguments if none are required,
  692.                     or use "Run" instead.
  693.  
  694. Make
  695. ====
  696.  
  697.     Executable  -   "Makes" the current program, putting
  698.                     all intermediate files and the final
  699.                     executable program into the temporary
  700.                     working directory specified in AIDE2.config.
  701.  
  702.     Application -   Does the same as "Make Executable" but
  703.                     also copies the final executable from
  704.                     temporary storage to ACE:Run. This is the
  705.                     default.
  706.  
  707.                     If the default is overwritten with
  708.                     an empty entry, the executable goes to the
  709.                     root directory where AIDE resides.
  710.                     An icon is also copied. That is the default
  711.                     for "Make Application".
  712.                     You don't need to specify "Create Icon"
  713.                     for the ACE options.
  714.  
  715.     Module      -   Creates an object module which can later
  716.                     be linked with any ACE program. The only
  717.                     difference between this option and Make
  718.                     Executable (above) is that no linking occurs
  719.                     and ACE's -m switch is used. See also "Creating
  720.                     & using ACE subprogram modules" in ace.doc.
  721.                     The object module goes to ACE:Mods (default),
  722.                     or where the entry in AIDE2.config points to.
  723.                     If this is empty, the module goes to the root
  724.                     directory where AIDE resides.
  725.  
  726.                     The displayed module list will be updated if
  727.                     the entry point in your configuration is
  728.                     setup correctly.
  729.  
  730. Precompiler
  731. ==========
  732.  
  733.     The mutual exclusive buttons gives you the possibility to
  734.     choose APP, ACPP or any other precompiler to be used to
  735.     precompile your source file.
  736.  
  737.     If you select "other" an input box will pop up where you can
  738.     enter the name of your desired precompiler.
  739.  
  740.     If you choose DCPP then the options will be set up correctly
  741.     to be used for ACE programs. DCPP is much faster as ACPP and
  742.     does the same task.
  743.  
  744.     If no precompiler name is entered, the button of your last
  745.     selected one will be activated again and an existing precompiler
  746.     name will be deleted.
  747.  
  748.     Clicking the close gadget of the window will ignore all what you
  749.     may have entered in the string gadget. If your settings should
  750.     take effect press <RETURN>.
  751.  
  752.  
  753. ACE Options
  754. ===========
  755.  
  756.     Break Trapping
  757.     Assem. Comments
  758.     Create Icon
  759.     Optimise
  760.     Window Trapping
  761.  
  762.     These five correspond to the compiler's command-line switches:
  763.     b,c,i,O and w respectively.
  764.     See ace.doc's "Compiler options" section for details of each of these.
  765.  
  766.     List Source Lines is not available via checkbox gadget, if you need
  767.     this, just enter "l" in the input box after selecting "other"!
  768.  
  769.     Since AIDE always uses ACE's -E switch to create an error file,
  770.     this option is not available. Compilation errors are however,
  771.     viewable via "View Compiler Errors"! (see below).
  772.  
  773.     other  -   If you select this button an input box will pop up
  774.                and give you the possibility to enter any kind
  775.                of ACE option which may be defined new for the future.
  776.                Also use this if you want to specifiy "list source line"
  777.                (see above).
  778.  
  779.                You have to enter the options as defined in ACE.doc.
  780.                If no "space" is required, then don't enter it.
  781.  
  782.                If you enter an empty string here all options which
  783.                may be defined before will be deleted.
  784.  
  785.                Clicking the close gadget of the window will ignore all
  786.                what you may have entered in the string gadget. If your
  787.                settings should take effect press <RETURN>.
  788.  
  789. SuperOptimizer
  790. ==============
  791.  
  792.     Here you can choose, if you want to use the SuperOptimzer from Manuel
  793.     Andre. With "Set Level" you can set the the superopt level. A input
  794.     box will pop up, where you can enter the number. Only numbers from
  795.     1 to 12 are accepted. The default value is set to 12.
  796.  
  797.     Note:
  798.         The SuperOptimizer is used in combination with the make process
  799.         of ACE. If you did change the level you have to recompile
  800.         the source again with ACE using the "Compile" button.
  801.  
  802.         If you did switch off the Superoptimizer, you don't have to
  803.         recompile again, because the unoptimized file <name>.s still
  804.         exists and AIDE will use this one instead of <name>_opt.s.
  805.  
  806.         In a future release it might be possible to select the
  807.         Superoptimizer separately.
  808.  
  809. View
  810. ====
  811.  
  812.     Precompiled Source
  813.                 -   Allows you to view the preprocessed source file.
  814.  
  815.     Assembly Source
  816.                 -   Allows you to view the target assembly
  817.                     source file which results from compiling
  818.                     a program.
  819.  
  820.     Compiler Errors
  821.                 -   Lets you see the errors (if any) generated
  822.                     by the last compilation with ACE.
  823. Note:
  824.  
  825.     These options are only available if a viewer is specified.
  826.     See the part above about the viewer for more details.
  827.  
  828.  
  829. Assembler
  830. =========
  831.  
  832.     Here you can choose which assembler you like to use.
  833.     A68K and PhxAss (see the corresponding doc files for more details)
  834.     are fully supported from AIDE.
  835.  
  836.     Just select the desired options or enter new ones with the "Set Options"
  837.     buttons. All what you enter has to be done the same way as if you would
  838.     type them at the Shell prompt. For A68K and PhxAss the options are set
  839.     in the right place of the command string. PhxAss ist set to NULL for
  840.     optimizing the assembly output. It depends on your program which
  841.     optimizing options you can use. Read the docs carefully and try them.
  842.     Optimizing the assembly output results in shorter/faster executables.
  843.  
  844.     When you specify another assembler via the "other" button then the
  845.     options will be added after the name of the file which has to be
  846.     assembled.
  847.  
  848.     Example:
  849.  
  850.     superassembler test.s .................. this is the default used name
  851.                                              build out of the assembler name
  852.                                              and the compiled source name.
  853.  
  854.     Then all what you did enter via the "Set Option" button will be added!
  855.     You have to specify an object file name "test.o" if the assembler needs
  856.     it to create a linkable module.
  857.  
  858.     But be aware:
  859.  
  860.     If you did define options for A68K and you switch to PhxAss then
  861.     you have to delete those options first, otherwise they will be used
  862.     also for PhxAss. This will result in an error message from PhxAss.
  863.  
  864.  
  865.     Small Code/Small Data model:
  866.  
  867.     Please read the corresponding docs for the assemblers to this point
  868.     very very carefully. Not all assemblers does the same task!!!
  869.     Don't choose these options if you are not sure what they are doing.
  870.  
  871.  
  872.     Debug Info:
  873.  
  874.     If you select this, A68K or PhxAss will create a symbol table for all
  875.     the labels and variable names which exists in the .s file. This is
  876.     especially helpful if also "Assembly Comment" is selected as ACE option.
  877.     The compiled program can then be watched with a symbol debugger like
  878.     MonAm. And you can compare it with your assembly source file.
  879.  
  880.  
  881. Linker Lib
  882. ==========
  883.  
  884.     Here you can choose which linker lib despite of the defaults db.lib
  885.     and startup.lib, which are linked always, should be used.
  886.     For PhxLnk you can use the standard Amiga.lib instead of Ami.lib.
  887.  
  888.     Important:
  889.  
  890.     Blink will crash if you try to link Amiga.lib!!!!!!
  891.  
  892.  
  893. Linker
  894. ======
  895.  
  896.     Here you choose which linker you like to use.
  897.     BLink and PhxLnk are fully supported by AIDE.
  898.  
  899.     What I did say about the handling of the "Set Options" button above
  900.     in the assembler chapter is also valid for the linker part.
  901.     So read the linker docs carefully if you want to use other options as
  902.     predefined in AIDE.
  903.  
  904.  
  905.     SmallCode:
  906.     ----------
  907.  
  908.     If you choose this option the supported linkers will link all your
  909.     program code into one piece. This results in shorter executable, but
  910.     can't be "scattered loaded". See in any case the corresponding linker
  911.     docs files for the details.
  912.  
  913.  
  914.     Small Data:
  915.     -----------
  916.  
  917.     This has the same effect for the data section of your program as
  918.     described above for the program section.
  919.  
  920.  
  921.     Important:
  922.  
  923.     PhxLnk links all data sections into one piece, no matter if for
  924.     some special ones the Chip mem bit is set! This can result in the
  925.     effect that some machines are reporting "not enough memory"
  926.     if they try to load a program wich was linked with PhxLnk and this
  927.     option set. That happens, because ACE creates large data sections
  928.     (depending on the used amount of variables) which has to be loaded
  929.     to Chip mem now. Machines with only 512k and sometimes those with
  930.     1Mega byte of chip mem, will report "not enough memory".
  931.  
  932.     PhxLnk has options to force Chip mem data sections to Chip mem and
  933.     all the other data sections to Fast mem, but that has to be done
  934.     inside of the assembler source file. :-( This is not possible
  935.     for normal :-) ACE programmers. We only can hope that Klaus will
  936.     be so kind to add an option to PhxLnk, so this will be done
  937.     automatically.
  938.  
  939.     Blink separates Chip mem data sections from the others, so this
  940.     will not happen with BLink.
  941.  
  942.     In any case you should be aware, that this option only makes
  943.     sense, if also the assembler option was set to SmallCode/Small Data.
  944.     If it wasn't, and ACE doesn't allow SmallCode/Small Data for all your
  945.     programs, SmallCode/Small Data option set for the linker only,
  946.     results in programs which can have loading problems on machines
  947.     with less memory and high memory fragmentation.
  948.  
  949.  
  950.     No Debug Info:
  951.     --------------
  952.  
  953.     If you select this option the program will be linked ignoring
  954.     all defined symbol table entries, if they exist.
  955.  
  956.  
  957. Module
  958. ======
  959.  
  960.     All SUBMods which resides in the specified "Module Dir" are
  961.     displayed in the main window. Just click on the name to select
  962.     the one you want to link and the choosen one will be highlighted.
  963.     Clicking on a selected entry results in unselecting it.
  964.     If you want to remove all modules just click on the button
  965.     "Remove all Modules"
  966.  
  967.     There is no limit for the amount of Modules defined which can
  968.     be linked.
  969.  
  970.     The amount is only limited by the length of the command line the
  971.     linker accepts for input. My testing did result in about 20
  972.     modules as maximum (depending on the length of the file name).
  973.     The buffer of AIDE allows up to 120 modules until an error
  974.     message is displayed.
  975.  
  976.     If the list is longer then you can scroll the list using the slider
  977.     at the right side.
  978.  
  979.     Note:
  980.  
  981.         No checking of the filename is done, only directory names are
  982.         ignored. Therefore you can place any type of linkable file into
  983.         your "Module Dir".
  984.         If you want to link other linker libs as predefined just place
  985.         them here and select them as described above.
  986.  
  987.  
  988.     Note:
  989.  
  990.         If you want to save your option settings from the main window,
  991.         use "Save Configuration" from the "Project" menu.
  992.         All your settings will be saved in AIDE2.config (default) or
  993.         in another file "save as..." if you wish to do so.
  994.  
  995.  
  996.  
  997. AIDE's "Make" Process
  998. ---------------------
  999.  
  1000. As you may have gleaned from the above, AIDE has a simple inbuilt "make"
  1001. capability.
  1002.  
  1003. This means that before it builds or makes an exectuable and prior to
  1004. compiling or running a program, AIDE checks to see whether compilation
  1005. needs to take place at all.
  1006.  
  1007. If you have created an executable and then decide to run it, AIDE
  1008. will not recompile the source first. Likewise, if you want to build
  1009. an executable and the program has already been compiled, the executable
  1010. will be copied from AIDE's temporary workspace only.
  1011.  
  1012. In like manner, if you have compiled a program to produce an assembly source
  1013. file, so long as you don't edit the ACE source file, AIDE will not recompile
  1014. the program before assembling and linking it.
  1015.  
  1016. If you want to recompile select "Source Reset" or do it step by step with
  1017. the buttons in the "Program" section.
  1018.  
  1019. On the other hand if you edit a source file, next time you go to run it,
  1020. AIDE will "bring the program up to date" by compiling, assembling and linking
  1021. it first.
  1022.  
  1023. If you forgot to link some modules just select them and select "Link"
  1024. from the "Program" section.
  1025.  
  1026. In order to preprocess, compile, assemble and link a program, AIDE now
  1027. uses the DOS function SystemTagList(). An intuition window will be
  1028. opened to watch the progress of your compilation run. If you select "Stop"
  1029. there, the next step will not be taken. If you want to stop immediately
  1030. you have to press Ctrl-C in the CON: window, which was also opened
  1031. to display the current output from ACE and the other programs.
  1032. But not all programs, used to make an executable, accept Ctrl-C, therefore
  1033. the "Stop" button was added.
  1034.  
  1035. Note:
  1036.  
  1037.     Only the next step can be aborted via the "Stop" button, because
  1038.     SystemTagList() didn't return before and did give the control back
  1039.     to AIDE.
  1040.  
  1041.     PIPE: is not used anymore!
  1042.  
  1043. If an error or user break occurs during preprocessing or compilation,
  1044. AIDE will stop and give the control back to the user.
  1045.  
  1046.  
  1047. Important:
  1048.           The buttons in the "Program" section will not change their state
  1049.           if you change any names/options for precompiler, ACE, assembler,
  1050.           linker lib or linker and the internal state of the make process
  1051.           will not be affected either.
  1052.  
  1053.           If you did change the options just select the corresponding
  1054.           buttons in the "Program" section to perform the missing
  1055.           steps of your compilation process.
  1056.           This habit differs completely from older versions of AIDE.
  1057.           It was done this way, so that the program is not recompiled
  1058.           completly, because only the assembler or linker option had
  1059.           been changed.
  1060.  
  1061.           If you want to perform a new compiler run, just select "Reset"
  1062.           from the source section and "Make Executable" or whatever
  1063.           AIDE should do for you.
  1064.  
  1065. Credits:
  1066.  
  1067.         I forgot to mention this before. Sorry, friends. :-(
  1068.  
  1069.         Especially I have to thank the following persons for their help,
  1070.         and for their patience to test all my bad and buggy :-) beta
  1071.         versions.
  1072.  
  1073.         David Benn
  1074.         Frank Wille
  1075.         Klaus Gessner
  1076.  
  1077.  
  1078.         AIDE was testet with Enforcer, Mungwall and Codewatcher and
  1079.         the release v2.02 should be free of all buggy parts and
  1080.         Enforcer hits.
  1081.  
  1082. Final Comments
  1083. --------------
  1084.  
  1085. The new included Phoenix package consisting of the freeware version
  1086. of PhxAss and PhxLnk is copyrighted to Frank Wille. See the corresponding
  1087. doc files for the details.
  1088.  
  1089. Thank you, Frank, for allowing me to include your wonderful assembler
  1090. and linker into the new release of AIDE.
  1091.  
  1092. AIDE is completely rewritten in assembler and assembled with PhxAss.
  1093.  
  1094. This is the second complete release of a new generation of AIDE.
  1095. Nothing is perfect and AIDE still is not.
  1096.  
  1097. All your comments and hints are welcome and wanted.
  1098. Feel free to make any suggestions about AIDE and please report any bugs
  1099. to me.
  1100.  
  1101. In any case, I hope you find AIDE to be a pleasant environment in which
  1102. to develop ACE programs.
  1103.  
  1104.  
  1105.  
  1106. Contact:
  1107.  
  1108. Herbert Breuer
  1109. A.A. 5469
  1110. Bogota/Columbia
  1111. South America
  1112.  
  1113. Tel.: (Columbia)91/8261959
  1114.  
  1115.         g-suarez@uniandes.edu.co (Herbert Breuer)
  1116.  
  1117.  
  1118.  
  1119. Regards,
  1120.  
  1121. Herbert Breuer
  1122.  
  1123. Bogota, Columbia
  1124.  
  1125. 13th May 1996
  1126.  
  1127. PS.
  1128.  
  1129. Thank you, David, for the wonderful ACE-BASIC-compiler, and for giving me
  1130. the responsibility for AIDE.
  1131.  
  1132.