ACC Editor Users Manual ======================= by M.Meany, June 91. What Is ACC? ------------ ACC is an a basic text editor that brings together A68K and Blink to form a reasonable work environment for assembly language programmers. From the editor it is possible to enter code, assemble it, link it and then run the final program. The ACC Editor may only be distributed on an unmodified version of the disk named 'M1' as distributed by Amiganuts. There are no exceptions to this. Disclaimer ---------- The user of ACC will accept full responsibility for his property, be it physical or literal. Using ACC will be taken as agreement to this condition. The authors of ACC will accept no responsibility for material lost as a result of ACC! The Editor ========== ACC is a text editor. It allows you to enter text, edit text, load text, save text and perform various other operations on text. Most of the features of ACC are accessed from pull down menus as you would expect from an Intuition application. Many of these features have keyboard shortcuts, to save having to grab your rodent while typing. Other features are available from the keyboard only. Entering Text ------------- When ACC first loads it opens a window that contains a status line at the bottom and a cursor in the top left hand corner. To enter text simply type at the keyboard, all keys hit will be echoed on the screen. When the end of a line is reached, hit the RETURN key to start the next line. The cursor will move accordingly. Should a line become wider than the screen, it is scrolled left so you may still check your typing. On hitting RETURN the line is displayed correctly. The maximum length of a line is 255 characters, this includes spaces, TAB's and the terminating line feed. I will point out that this is an editor restriction, A68K will only accept lines of 128 characters or less. Text is always entered in ' insert ' mode. Cursor Keys ----------- You may move the cursor through the text by pressing the appropriate cursor key ( up, down, left or right ). The text will not be altered by this. When you have positioned the cursor at the desired location simply start typing again. In order to allow fast movement through a large text file, pressing a SHIFT key with either cursor up or cursor down will move the cursor one page ( screen ) up or down. Pressing a shift key and cursor left or right will cause the cursor to skip to the start/end of the next word. The cursor may be placed at any position on the screen by moving the mouse pointer to the position and pressing the left mouse button. The cursor will then move to the character position nearest the mouse pointer. Note that moving to a position in a line that has been scrolled will not work correctly, use shift and cursor left/right. Trying to move the cursor off the screen will cause the text to scroll in the appropriate direction. I apologise now for the erratic behavior of the cursor when scrolling up and down through a text file. You get used to it! TAB Key ------- ACC uses a fixed TAB size of 8 characters. Pressing the TAB key will move the cursor to the next TAB position, but will only insert one byte into the file. The TAB key should be used in preference to using the space bar to format your source on the screen. DEL Key ------- The DEL key will erase the character under the cursor. Should you try to DELete past the end of a line, nothing happens. Backspace Key ------------- The backspace key will erase the character to the left of the cursor. You cannot backspace at the beginning of a line. Deleting A Line CTRL+Y --------------- To delete a line of text, position the cursor in the line and press CTRL+Y. Note that you cannot delete a line if it is the only line in the file, every file must contain at least 1 line! Deleting All Text [A]+C ----------------- To delete all text in the file and start afresh, select Clear from the Project menu or press the right Amiga key and C. Note that if the file has not been saved since last changes were made to it a requester will appear asking you to verify this action. ** From now on I will refer to the combination: RIGHT AMIGA + some key ** ** In the following manner [A]+key. Ie. [A]+C to clear all text ** Cursor To Top Of File [A]+T --------------------- To move the cursor to the start of the file select Goto Top from the Options menu or press [A]+T. The cursor will be displayed at the start of the first line of the file. Cursor To Bottom Of File [A]+B ------------------------ To move the cursor to the bottom of the file either select Goto Bottom from the Options menu or press [A]+B. The cursor will be placed at the start of the last line in the current file. Cursor To Specified Line [A]+G ------------------------ To move the cursor to the start of a particular line, either select Goto Line from the options menu or press [A]+G. A requester will appear into which you should enter the line number you wish to move the cursor to. As long as you enter a valid line number, that line will be displayed at the top of the screen with the cursor at its beginning. Quitting The Editor [A]+Q ------------------- There are three ways to quit from ACC. Select Quit from the Project menu, press [A]+Q or click on the windows close gadget. All will cause a requester to appear giving you the option of canceling the instruction to quit. If alterations have been made to the file and are not yet saved a second requester appears telling you so. The File Requester ------------------ ACC uses the ARP file requester to obtain the full pathname of a file, whether for Loading, Saving or Inserting. To use the file requester you can type the pathname in the Drawer gadget and the files name in the Filename drawer. Alternatively, you can use your mouse to select a file from the list displayed in the requester. Clicking on a directory will add the directory to the pathname and all files in the directory will be displayed. You select a filename by ' double-clicking ' on it. At any time pressing the Right mouse button will display all volumes available in the list, ie RAM: RRD: DF1: DF2: C: etc. This can be used to select a disc to append to the pathname. Selecting the CANCEL gadget will abort the operation. Saving A Text File [A]+S ------------------ To save the text being edited, select Save As from the Project menu or press [A]+S. The file requester will be displayed and you can then define a filename to give the text. Selecting a filename that already exists will cause that file to be wiped before saving the text. If you have already saved the text once and only wish to save some changes then select Save from the Project menu. ACC will use the last filename specified for the text. If no filename has been specified, an error message is displayed. Loading A Text File [A]+L ------------------- To load in a text file select Load from the Project menu or press [A]+L. The file requester is used to obtain the name of the file to load. If ACC contains text that has altered, but not saved a requester will appear informing you of this and giving you the opportunity to cancel the Load operation so you may save the changes first. Inserting Text [A]+I -------------- If you wish to insert a text file from disc into the text currently being edited, first position the cursor in the line where the text file is to go. Now select Insert File from the Program menu or press [A]+I. The by-now familiar file requester will be displayed allowing you to specify the name of the file to Insert. The text will be inserted immediately after the line containing the cursor. Searching For Text [A]+F ------------------ You can ask ACC to search through the text for an occurrence of a particular string of text. The search will start from the line immediately below the cursor. Should the string be found, the cursor will be moved to this line and if possible, the line will be displayed at the top of the screen. The cursor will be positioned at the start of the line, not at the string itself, sorry! never got that far. To find a string select Find from the Search menu or press [A]+F. A requester will appear in which you enter the string to search for. If a string was entered previously, it will be visible in the requester, pressing [A]+X will remove it and allow you to enter a fresh string. If you wish to keep the string displayed click on the OK gadget. If you wish to alter the string displayed, use the cursor keys to move the cursor, backspace and delete can be used to delete characters and new characters can be added. When you are satisfied with the string, either press RETURN or click on the OK gadget. If you have already specified a string, you can search for the next occurrence of it by selecting Find Next from the Search menu or pressing [A]+N. This saves having to deal with the search requester and so speeds up the search process. To find a previous occurrence of a string already specified, select Find Previous from the Search menu or press [A]+P. This again avoids having to use the search requester. Printing Text ------------- Two print options are supported, both accessible from the Project Menu. The first, Print Page, will cause the contents of the editor screen to be printed out. The second, Print File, will print all the text. To use the print options, you must have set preferences correctly for your printer. This disc is supplied with the Generic printer driver selected. You should change this to suit your own configuration. Both print options use the PRT: device to output text to the printer. About ACC --------- In case you loose this doc file, my name and address can be displayed from ACC by selecting About from the Project menu. This opens a small window in which the said information is displayed. Press the left rodent button to remove the window. Assembling A Program [A]+A -------------------- Once you are happy with your source text, you will want to assemble it. This is done by selecting Assemble from the Program menu or pressing [A]+A. This causes a rather large requester to appear. From this requester you set all the assembly and linkage options you require. Assembly Options ---------------- The assembler supplied with this package does not produce executable files, instead it generates linkable modules. To obtain an executable file from this module ( known as an object module and usually denoted by a .o extension ) it is necessary to pass it through a Linker. ACC makes this process invisible to the user. A file can be assembled and linked in one hit to produce an executable file. On occasions it may be desirable to produce only the object module, so this option has been included. You may wish to link other object modules with that produced by the text your are assembling, or pass a linker library to the linker. Both these options are also supported, though neither is a requirement. How is all this done? By selecting options from the assembly requester. When you select Assemble, this requester is displayed. It contains the following fields and gadgets: Program Type *Executable Linkable Debug info *None Normal Listing *None RAM: Output to *Memory Disk filename string gadget Link (object) string gadget Link (library) string gadget Cancel Assemble All gadgets marked with an * show default settings. Here is an explanation of each field PROGRAM TYPE ------------ You select wether to produce an executable file from your source or an object module. The default is an executable file since this is used most of the time. If your program is complete in itself, you should set the executable option, this way the assembled code will be ready to run. DEBUG INFO ---------- If you require a symbols hunk to be produced with your source, set this to normal. This is only of real use if you posses a symbolic debuger, so the default is None. Selecting Normal will produce a larger executable file. As far as I am aware, there is not a symbolic debugger available in the Public Domain. If you know of one, please inform me. I will then add a Debug option to the program. LISTING ------- This function is only partially supported in this version. If you require a complete listing to be generated by the assembler, select RAM:. You will find the listing file in ram: and it will be called source.lst when assembly is complete. I set the default to None since listings tend to be very large and so waste memory, but you may use this if you have loads of megs and want to optimise your source. OUTPUT TO --------- Here you specify where the assembled file should go. If Memory is selected ( the default ) then a file is produced in ram:. If you want the assembled file to be saved on disk, select the Disk option and make sure a filename is specified in the string gadget marked . ---------- Here you enter the full path name to give the assembled file if the output to disk option is selected. Note that if you are producing a linkable file then it is advisable to add the recognised .o extension to the filename, ACC does not do this for you. eg. df1:c/MyDemo < for an executable file > df1:c/MyDemo.o < for a linkable file > LINK (OBJECT) ------------- Here you can specify any object modules you wish to be linked with your program to produce an executable file. For instance, your program may require an object file for the raw graphics to be used in a demo ( these cannot be loaded into a program by A68K, so must be linked in ). You can enter a number of file names, each must be separated by a space or comma. eg. ram:gfx.o ram:muzak.o This will cause the two files 'ram:gfx.o' and 'ram:muzak.o' to be linked with your program. See the Objector utility doc's for more information on producing object files from raw data files. LINK (LIBRARY) -------------- If your program requires the functions from a linker library, specify the library here. For example, you may wish to use Amiga.lib functions for floating point math's, so you will need to pass this library to the linker. See the tutorial for more information. Once you have set up the options you require, click on the Assemble gadget and ACC will do it's stuff, invoking first A68K and then Blink to produce an executable file to your specification. Should you decide not to assemble, click on the Cancel gadget, you will be returned to the editor. Running A Program [A]+X ----------------- Once assembly is complete, you can run the program generated by selecting Run from the Program menu or pressing [A]+X. On selecting Run, a requester will open containing three gadgets. The string gadget ( active when the requester opens ) is for typing any parameter list you wish to pass to the program about to be run. For example, suppose you have written and assembled a directory program that can be run from the CLI. To obtain the directory of DF1: you would enter dir df1: at the CLI. Well to pass DF1: as a parameter to your program, simply type DF1: into the string gadget and press RETURN. Your program will be run and DF1: will be sent to it just as if it was typed into the CLI. If your program does not require any parameters ( Args ) click on the 'No Args' gadget. Your program will be run with no parameters being passed. If you have changed your mind and no longer wish to run the program, click on the 'CANCEL' gadget. You will be returned to the editor. You may run your program providing it was assembled as EXECUTABLE to either Memory or Disk. The Run option uses ARP's AsyncRun function to launch your program from within ACC. ACC supplies a window for your program to use as if it was a CLI, this stops programs intended for the CLI from crashing when run by ACC. WARNING : RUNNING A PROGRAM CAN CRASH THE SYSTEM. ALWAYS SAVE TEXT FIRST. Viewing A Text File [A]+M ------------------- Last minute addition this! If at some point you need to look at a text file stored on disc somewhere, you no longer need to leave the editor. A text file viewer is available from the Project menu. Select this option and a blank window is presented. All of the text viewing features are available from the keyboard. Press the Help key for a summary of commands. While viewing a text file, you are locked out of the editor. Well that just about covers the editor. I will now give some brief notes on the assembler and linker supplied. The Assembler ============= Introduction ------------ ACC is supplied with a PD assembler called A68K. This has been around for some time now and has proven itself a very worthy tool. Most PD compilers rely on A68K to produce their object modules. A68K can be run from the CLI as a stand alone assembler, but to save users of ACC this hassle, A68K can be invoked from within the editor to assemble a file. This saves ACC users from having to master the rather complicated process of assembling and linking source files. I have included the documentation supplied with A68K on this disc should you wish to read it. Below is a description of the main features of A68K extracted from the supplied documentation and also discovered from experience. Syntax ------ Each line of source should have the following format: LABEL MNEMONIC OPERANDS COMMENTS the only exceptions are blank lines and lines beginning with a semi-colon which are treated as comment lines. Each field must be separated by at least one space or TAB, here is an example: LABEL MNEMONIC OPERANDS COMMENTS ; This is a comment line and is ignored, so is the following blank line! Start move.l #0,d0 clear reg D0 add.l #5,d0 add five to it rts end Notice the ' end ' mnemonic. This is an instruction to A68K, not a 68000 instruction. It informs A68K that this is the last line of source to assemble. EVERY listing must be terminated by such a line or A68K will produce an error. LABEL ----- All labels should start in the first column of the line. If a label has to be declared in any other column, it should be followed by a colon. The colon is not part of the label name, but an identifier for A68K. Labels can be any length up to 127 characters, which is the target line width A68K accepts. The only name a label cannot take is a register name ( ie d0 D0 a7 A7 etc ). A label starting with a \ will be treated as a Local Label. These are specific to an area of source and attached to the last non-local label. For instance, the following listing contains a syntax error because the label ' loop ' has been defined twice: start moveq.l #5,d0 loop move.b (a0)+,(a1)+ dbra d0,loop Test moveq.l #5,d0 loop tst.b (a0)+ dbne d0,loop Using Local Labels this can be avoided: start moveq.l #5,d0 \loop move.b (a0)+,(a1)+ dbra d0,\loop Test moveq.l #5,d0 \loop tst.b (a0)+ dbne d0,\loop the first occurrence of \loop is attached to the non-local label ' start ', while the second is attached to ' Test '. It should be noted that two local labels of the same name cannot be attached to the same non-local label. MNEMONIC -------- This field must consist of either a 68000 instruction, an assembler directive or a macro call. 68000 instructions may be entered in lower, upper or mixed case, as may assembler directives. Macro calls are case sensitive and should be the same as the macro definition. OPERANDS -------- Should the mnemonic require operands, they are entered here, separated by commas. 68000 registers may be entered in any case ie d0 D0 a7 A6 etc. COMMENT ------- This field is ignored by A68K and may be used to make your listings more readable. It is good practise to detail what a program is doing in this field. Expressions ----------- A68K allows expressions to be included in a source listing. These will be evaluated at assembly time. Recognised operators (as far as I can make out) are: +,-,/,* add,subtract,divide,multiply ( ) parenthesis support | or ! logical OR & logical AND For example: WIDTH equ 320 HEIGHT equ 200 start move.l #(WIDTH/8)*HEIGHT,d0 d0=size of bitplane here, (WIDTH/8)*HEIGHT will evaluate to (320/8)*200 or 8000. Another example: MEMF_CHIP = 1 MEMF_CLEAR = 16 start moveq.l #MEMF_CHIP!MEMF_CLEAR,d0 in this example the values 16 and 1 are OR'd together: 10000 (16) 00001 ( 1) ------- 10001 (17) so the value 17 is moved into register d0. Of course, A68K is not limited to the decimal number system. Hex, binary and octal are also supported. To specify a number in another base use one of the following identifiers: # number is Hexadecimal @ number is Octal % number is Binary The following four examples are identical: 1/ moveq.l #$10,d0 HEX 2/ moveq.l #16,d0 DECIMAL 3/ moveq.l #@20,d0 OCTAL 4/ moveq.l #%10000,d0 BINARY As well as allowing numeric constants to be evaluated you may also express ASCII data as an expression: move.l #'MARK',d0 the characters in the quotations will be converted to their respective byte values, ie move.l #$4D4152BB,d0 This is most useful for data definition: dc.b 'This program M.Meany, May 1991',0 As an alternative to an apostrophe ( ' ),quotation marks may be used ( " ) this is useful if you must include one or the other in the declaration: dc.b "It's an ill wind that blows from the North",0 just remember to close with the same as you start with. 68000 Instruction Set --------------------- The full Montrola Instruction set is supported. The following may also be used: sp as an abbreviation for Stack Pointer (this is replaced by A7 at assembly). ccr as an abbreviation for the Condition Code Register. dbra may be used instead of dbf. A68K will optimise code wherever possible, substituting a quick instruction for or short branch instructions. This helps produce faster, more compact code. If A68K detects a branch that could be changed to short form during it's second pass, it will flag it in the listing file ( if you have specified one ). If a data size ( .b .w or .l ) is not specified for a mnemonic, A68K assumes WORD size ( .w ). Assembler Directives -------------------- END --- Every source listing must be terminated by an end directive. A68K will produce an error if this directive is not encountered. INCLUDE ------- SYNTAX: