SOFTEK Masters of the Game 'IS' INTEGER COMPILER & 'FP' FULL COMPILER ========================================== (C) 1983 M. Lewis Softek International Ltd LONDON, ENGLAND (Typed in by Nele Abels-Ludwig. Keep Spectrum software usable, transcribe technical manuals!) Introduction ------------ WHAT IS A COMPILER? A compiler translates a program written in BASIC into an equivalent program in machine code. Machine code is in a sense, your Spectrum's 'Mother Tongue', it in fact always works in this language: the BASIC you may be used to writing is understood by your Spectrum because its 'ROM' (Read Only Memory) contains a so-called 'BASIC interpreter' itself written in machine code. Because the heart of your Spectrum, its 'CPU' (Central Processing Unit) does not understand the 'BASIC' language. Your Spectrum spends a fair amount of time whilst running your program 'interpreting' it for the CPU. The Softek Compiler, by contrast, converts your BASIC so that it is in Machine Code and because of this your Compiled programs will run typicall ten times faster than BASIC (less for the 'FP' version), but up to 200 times faster is possible with the 'IS' Integer Compiler. Both Softek Compilers allow you to choose where the compiled code will sit in the memory, and this final Machine Code version of your proram can easily be saved on tape as CODE. The beauty of Softek Compilers is that after compilation your BASIC is still present so that should ammendments be required there is no need to load again from tape/microdrive. Furthermore, you can compile subroutines. LOADING THE COMPILER Simply type LOAD"" and press the key. Set the tape running (being sure to connect the tape leads correctly in the rear of your spectrum). The programs all load in two parts, a BASIC loader and the compiler itself. When loaded you will be asked if the RAMTOP setting is okay (40000 for 48K versions and 26000 for 16K versions). If it is, just press 'y' and else press 'n' and and respond with the RAMTOP you require. Note that RAMTOP is the location where your compiled program will start. Each of the compilers has a 16K and 48K version on the tape. Either version could be used on a 48K Spectrum, but naturally only the 16K version will run in 16K. Once loaded and RAMTOP is set, each program will tell you that you may 'NEW' the BASIC loader. This done your compiler is still in memory (protected above RAMTOP) and you may begin programming or load your BASIC to be compiled. USING YOUR COMPILER Using your compiler could hardly be easier. Key in your BASIC as usual or load it in from a tape or microdrive. The 'FP' compiler will understand virtually every BASIC command and function, but if you are using the 'IS' then do refer to the follow notes to check its limitations. When your BASIC is ready to be compiled simply enter: RANDOMIZE USR 59300 (for 48K or 26600 for 16K) Having done this you enter the compiler and it begins its work. Various messages will appear as the compiler passes twice through your BASIC turning it into machine code. Here are the messages and their meanings: 1. "START ADDRESS" This shows the start address of the machine code being compiled (this is always one byte above RAMTOP) 2. "END ADDRESS" This is updated during the compilation and shows the end address of the code as it is built up. 3. "VARIABLES END" This message appears when your program contains STRINGS or ARRAYS. These are stored immediately after your machine code program and when compilation is complete the last address of the array is shown. 4. "FIRST PASS", "SECOND PASS" To make a complete compilation your Softek compiler must make two passes through your BASIC. These messages tell you which pass of your program is compiling. 5. "ERRORS"/"NO ERRORS" If at the end of compilation the "NO ERRORS" message appears then you have a successful Machine Code program. However, if "ERROR" appears then the compilation will halt and display the line of BASIC and the part of that line which the compiler cannot understand. You will see the question mark (?) placed just after the error and the compiler will have changed the 'current line' cursor to this line number. Hence, pressing 'EDIT' will call down this offending BASIC line (press CAPS SHIFT + 1 to edit). RUNNING COMPILED PROGRAMS Make a note at the end of compilation of the START ADDRESS of the code and then, from BASIC, simply tpe in: RANDOMIZE USR (START ADDRESS). WHERE IS THE MACHINE CODE PUT? As mentioned above, your machine code is put in RAM starting one byte above the RAMTOP which you are set. You can reset RAMTOP anytime by entering: CLEAR N, where 'N' is one less than the start address you choose. It is thus quite possible to compile subroutines or build up a programm in parts, by carefully setting and resetting RAMTOP (you will have to take careful note of the values of "END ADDRESS" or "VARIABLES END" to ensure the parts do not overlap). WHAT HAPPENS TO THE BASIC? Your BASIC remains in memory after compilation. However, if the machine code works as planned then it can be saved as CODE (see below) or the BASIC 'NEWED' to allow more BASIC to be compiled. MEMORY USAGE MEMORY can be exhausted in several ways. 1. During compilation a table of LINE numbers is built up and "OUT OF MEMORY" will occur if too many lines are used. 2. If either the machine code or the VARIABLES threaten to overwrite the compiler then "OUT OF MEMORY" will also occur. VARIABLES, STRINGS, ARRAYS & NUMBERS Variables are handled as in BASIC, allowing full names to be used in either upper or lower case. Only the 'FP' compiler will handle arrays, but you must ensure that these are not multi-dimensional. The 'FP' compiler will handle all 'real' (floating point) numbers as n BASIC. The 'IS' compiler treats all numbers as integers (no decimal points), in the range -32767 to 32767. Certain functions will take a number stored as 0 to 65536 (e.g. PEEK, POKE, USR). COMMANDS THE COMPILERS HANDLE: KEY: e represents an expression s a sequence of statements separated by colons n a positive integer number c a sequence of colour items separated by ',' or ';' or '"' x,y a set of expressions $ a string expression BEEP x,y BORDER e as normal BRIGHT e as normal CIRCLE c;x,y,z as normal CLEAR 'FP' version only CLS as normal CLOSE#n,$ 'FP' version only COPY as normal DATA on both versions no expressions can be put into DATA statements. Only numbers, or strings in the form "..." can be used, and these forms can be mixed. DIM A(n) or A$(n) 'FP' version only DRAW c;x,y as normal DRAW c;x,y,z as normal FLASH e as normal FOR a=x TO y as normal STEP z as normal GOSUB n as normal GOTO n as normal IF e THEN s Exactly as BASIC (full Boolean) INK e INPUT Exactly as BASIC except for LINE. BASIC's line editor is used allowing full cursor control and PRINT statements may be included. Variables may be printed if they are enclosed in brackets. INVERSE e LET a=e LOAD $ CODE n only one parameter LPRINT the '#' may also be used NEW OPEN#n,$ only 'FP' version OUT x,y OVER e PAPER e PAUSE e plot c;x,y POKE x,y PRINT the '#' may also be used RANDOMIZE RANDOMIZE e READ REM see later RESTORE RESTORE n as in BASIC RETURN SAVE $ CODE e,e STOP VERIFY $ CODE e e is optional REM STATEMENTS REM statements are used in Softek compilers to offer commands and facilities not obtainable in Spectrum BASIC. In each ase REM is followed by a single capital letter, but if this letter is not one of the 'Key Letters' below then the line is treated as a normal REM statement. INTEGER 'IS' VERSION REM B checks to see if the Break key is pressed REM M,n,n,n,n... enters code into the program and allows a machine code routine to be called at this point in the program REM S,a,x,y PRINTs a character (ASCII code 'a') onto the screen at PLOT position x,y. This is very useful for games requirint high resolution smooth movement. FULL 'FP' VERSION REM B checks for BREAK key REM M,n,n,n,n... as in the 'IS' version REM E,n sets an error trap to line 'n'. Thus whenever an error occurs a jump to line 'n' is made. If a program uses this facility the STACK will be corrupted when an error occurs. Thus if a later return to BASIC is made it should only be done by jumping beyond the program or by using a STOP statement. REM N restores error trapping to the normal mode. This must be done before returning to BASIC. REM O,a,n,n... this simulates the BASIC function: ON n GOTO n,n,n,... 'a' must be a single variable only and if it is greater than the number of lines present the program continues past the statement STRINGS AND STRING HANDLING Strings are totally flexible and may be any length (not only up to 256 characters as in BASIC). Strings are stored after the normal variables, which are in turn stored immediately after the compiled code. String arrays are possible on the 'FP' version only and must be singly dimension. When a string is dimensioned it is filled with spaces as in BASIC. Both types of string slicing are possible, e.g. LET A$(3 TO 7)="HH" or LET A$="any abcde" (3 TO 5) or a mixture of the two. Numbers may be missed out as in BASIC, e.g. A$(3 TO) And all the following as possible: LEN STR$ CODE CHR$ CODE INKEY$ SCREEN$ "+" (for concatenation) NOTE In both compilers printing in PRINT statements is not evaluated. Thus if you wish to include something like "abcded" (3 TO 6) or "y"="h", etc., then you must enclose the expression in brackets to force the compiler to call the evaluator before PRINTing. Note also that neither VAL nor VALS are usable as these can only be handled by BASIC in real time. INTEGER COMPILER: FUNCTIONS etc. FUNCTIONS: ABS AND ATTR CHR$ CODE IN INKEY$ LEN NOT OR PEEK POINT RND(a number between 0 and 32767) SCREEN$ SGN STR$ USRn USR$ +/*- and all comparison operators. BEEP You may make a Beep of lesss than one second including division e.g. BEEP 1/expression,n Where the 'expression' can be any number or any expression. The expression is calculated in integer form and then floating-point calculator is called to do the final division. CLEAR just clears the simple and control variables and deletes string variables too. FULL COMPILER: FUNCTIONS etc. The Full 'FP' compiler will handle all the functions possible with the 'IS' compiler. In addition it will handle all floating point functions too, such as SIN, COS, ATN etc. CLEAR can also be used for its other function of adjusting RAMTOP in this 'FP' version only. The CLEAR command will clear all arrays and will also change the complex stack. Thus a STOP statement must be used to RETURN to BASIC after a CLEAR or the program will crash. In general, you should not RETURN to BASIC from a compiled 'FP' program except at the very end of a program or by using the STOP statement. GENERAL DIFFERENCES BETWEEN THE COMPILERS The Full 'FP' compiler and 'IS' integer one both take up a similar amount of RAM (about 6K). The 'FP' ckearly is more able to compile the full range of Spectrum BASIC and is thus most suitable for scientific or technical uses. However the numbers in 'FP' compiled code are treated as floating point ones (5 bytes each) whereas they are all inteers in the 'IS' version (2 bytes each). For this reason the code produced by the 'FP' compiler will tend to be slower than that of the 'IS' compiler, whereas code using the 'IS' compiler is typically 10 times faster than BASIC (with up to perhaps 500 times faster being possible), the 'FP's code will offer more typically a speed increase in the region of 2 to 10 times faster. THE COMPILERS IN USE/MEMORY MAP Compiled code will always be positioned in RAM to run from one byte above RAMTOP. Hence you may choose where in RAM your code is placed by using 'CLEAR n' to alter RAMTOP (se compiler's loaders). The compiler must be in memory when the code is called to run the machine code programm because the compiled code uses 'run-time routines' in the compiler. After the compiled code is a 130 byte block which stores all particulars about the 26 strings allowed. Then there is normally free space unless this is filled with strings when the M/C program creates them. ----------------------------------------------------------------... prog : arrays :: line address's : spare :: MCode : Vars : $data ----------------------------------------------------------------... VARS STKEND RAMTOP ...---------------------------------------------+ 130 bytes : $'s : spare : vars ads : Compiler: ...---------------------------------------------+ The 'FP' compiler stores all arrays in the BASIC interpreter's variable area. This is done so that the values can easily be transferred from BASI to the machine code and vice versa. A custom search routine is used so that the time taken to look for this variable is extremely small. When compiling the compiler builds up a table of addresses of the lines of the program being produced. This is stored just above STKEND, in the spare area of memory. Also the compiler builds up a table of addresses of the various variables used by the program. This table "grows" down in memory from the start of the compiler. The compiler allows just enough space for the variable being used, i.e. if only a simple variable 2 (or 5 for the FP version) bytes are reserved for that variable. But if that variable is ever used in a FOR-NEXT loop then 8 (or 17 for FP) bytes are reserved for it. Variables can be any length and any number of variables can be used (if you have enough memory of course) SAVING THE COMPILED CODE For the compiler to produce efficient (fast) machine code there must be a set of RUN-TIME routines which are called from the code. The machine code cannot function without these routines and so must be saved along with the code. Your programs can be SAVED as follows: For 48K versions: SAVE "name" CODE start address, 65536 - start address For 16K versions: SAVE "name" CODE start address, 32767 - start address EXAMPLES 10 FOR A=0 TO 100: OUT 254,53: FOR B=0 TO A:NEXT B: OUT 254,0: FOR B=A TO 0 STEP -1: NEXT B: NEXT A 20 REM B 30 GOTO 10 10 FOR A=1 TO 128 20 LET B=(255-A) 30 REM S,87,A,A 40 REM S,88,B,A 50 REM B 60 BEEP 1/50,1 70 NEXT A