REPLACEMENT STOS COMPILER MANUAL
Please note that this manual was written as a replacement for the Official STOS BASIC Compiler Manual, which is also worth referencing.
The Complete STOS Reference
REPLACEMENT COMPILER MANUAL
What Is A Compiler?
As you may know, the ST's 68000 processor is only capable of understanding an internal language know as machine code. This means that you cannot simply enter BASIC commands into your ST without first translating them into machine code using Stos Basic. Supposing you were presented with some valuable text written in a foreign language (say French). There are two ways this could be translated into English. One idea might be to take each word in the text and look it up in a French-English dictionary.
This approach is known as interpretation, and is used by the standard STOS basic. Whenever a program is run, each instruction is checked against a dictionary stored somewhere in the St's memory, and the appropiate machine code routine is subsequently executed.Another solution to the problem might be to hand the text over to a professional translator. This person could re-write the entire document in English, which you could then read directly. The same idea can aldo be applied to a basic program. In this case, the translator corresponds to a seperate program known as a compiler. The STOS Basic compiler converts the complete STOS Basic program into machine code, producing a new version which can be executed immediately without the need for further translation.
The main advantages of a compiled program over an interpreted one can be summarised like this:
- Compiled programs execute up to three time faster than the equivalent interpreted program.
- Compiled programs can be run directly from the GEM desktop, or from and AUTO folder. They do not need any of the files from the STOS folder in order to run.
- Once a program has been compiled, it is impossible to translate it back into STOS basic. So there is no chance of anyone stealing your original code.
Against this, there is one single disadvantage: Compiled programs are larger than interpreted programs.
This statement is actually misleading because the real size of an interpreted program is far larger than you would initially expect. Take the game Orbit for instance. Although this is apparently only 60k, if you were to create a run-only version you would need to include all the seperate program modules contained in the STOS folder. The total size of the program would therfore be a surprising 270k. Contrast this with a compiled version of the same program. The final length of Orbit after compilation is around 130k, which is over 140k less than the interpreted version. So although a copiled program may look larger than an interpreted one, it's often considerably smaller.
Auto Loading The Compiler
The action of the compiler is controlled through the accessory program COMPILER.ACB. This can be loaded automatically by changing the EDITOR.ENV file on the STOS boot disc. Insert the original STOS language disc into drive A and run the configuration program CONFIG by typing
RUN "CONFIG.BAS"
When the main menu appears, click on the next page icon. You can now add COMPILER.ACB to the list of accesories which will be loaded on start-up. Click the mouse on the first free space of the accessory list and enter the line:
COMPILER.ACB
It's a good idea to add the following function key definitions to the standard list. This will simplify the process of loading and saving compiled programs considerably:
F14(shift-F4) fload "*.CMP" F15(shift-F5) fsave "*.CMP"
You can now save the new configuration file onto your working copy of STOS Basic using the 'SAVE ON DISC' command. Then copy the COMPILER.ACB onto the language disc so that STOS basic can pick it up off the root directory as it boots up.
Using The Compiler
The compiler accessory can be executed at any time directly from the [Help] menu. In order for the compiler to work, the files contained in the COMPILER folder should always be available from the current drive. This reduces the amount of available memory used by the compiler to a mere 25k, and allows you to compile acceptably large STOS basic programs on a 520 ST.The optimum strategy for using this package varies depending on your precise system configuration. Here is a full explanation of how the package can be set up for use with most common ST systems.
USING THE COMPILER ON A 520 ST WITH ONE FLOPPY DRIVE
If you are intending to compile large programs on an unexpanded machine, it's wise to keep a copy of the compiler folder on every disc you will be using for your programs. This will allow you to compile large program onto disc, without the risk of running out of memory. A special program called COMPCOPY is supplied for this purpose, which automatically copies the appropiate files onto your discs. Insert the compiler disc into drive A and type:
ACCLOAD "COMPCOPY"
press HELP and select COMPCOPY with the appropiate function key. Now press G to load the entire contents of the folder into the ST's memory. You will then be prompted for a blank disc, which should be placed into drive, and the compiler files will be copied onto your new disc.Depending on the format of your drive, you will be left with either 200k or 480k on each disc. This should prove more than adequate for all but the largest STOS programs. Despite this, it's still possible that you may occaisionally run out of memory. Try removing a few other accessories to save some space.Incidentally, the STOS compiler does NOT allow you to swap discs during the compilation process. So don't try to compile a program from drive A to drive B if you are limited to a single drive.
USING THE COMPILER ON A 520 ST WITH TWO FLOPPY DRIVES
Wehn you use the compiler, place a disc containing the COMPILER folder into drive A, and your program disc in drive B. This will provide you with plenty of disc space to compile even the largest STOS programs.
USING THE COMPILER WITH A RAMDISC (1040 ST OR HIGHER)
You can increase the speed of the STOS Basic compiler significantly by copying the contents of the COMPILER folder onto a ramdisk. Typical compilation speeds are a staggering 10k per second.For STOS users with a single density disc drive it is important to realise that the STOS language disc and COMPILER folder won't both fit on a single sided disk.
The Compiler Accessory
If you found the installation procedure rather cumbersome, you will be delighted to hear that the compilation process is simplicity in itself. You begin by booting up your STOS Basic using the new configuration file. This will automatically load the COMPILER accessory into the ST's memory during initialisation.Alternatively you can load the accessory directly from the compiler disc using the line;
ACCLOAD "COMPILER"
You can now enter the compiler accessory from the [Help] menu in the normal way, at which point you will be presented with the control panel.The main features of the control panel are controlled theough a set of five 'buttons'. These can be activated by simply moving the mouse pointer over the appropiate are and clicking once on the left mouse key.Below follows an explanation of these buttons:
SOURCE
The source button is used to determine whether a program is
to be compiled either from memory or the current disc. Clicking on the box underneath toggles between the two possiblities.
1) MEMORY
This option informs the compileer that you wish to compile the program you are currently editing. Any of the four program segments may be compiled independently without affecting the conents of the others. Compiling from memory is very fast, but it does consume a large amount of memory.
2) DISC
Some programs are simply too large to be compiled directly from memory. In these cases, it's convienient to compile a program from a file on disc. Obviously this is slower than the memory option, but most STOS programs can still easily be compiled within a matter of minutes. Before using this feature, remember to ensure that the COMPILER folder is accessible from the current drive. Also note that the DISC option will be selected automatically
whenever memory is running short.
DEST
the DEST button selects the eventual destination of the compiled
program. Programs may be compiled either to memory or directly into a file on disc.
1) MEMORY
This option compiles the program into memory. note that the memory used by this feature is completely seperate from your original program. So you can subsequently save the compiled program onto the disc without losing your current STOS Basic program.
2) DISC
If you choose the disc as the destination, the code will be compiled straight into a file without taking up any valuable memory. Since it's much slower than the MEMORY directive, it's only really suitable for compiling particularly
large STOS Basic programs.
COMPILE
The compilation process is started when you click on the COMPILE
button with the mouse. As your program is compiled, a horizontal bar grows across the screen. When this completes it's journey, the compilation has been successfully concluded. But if an error is detected, the compiler is terminated and you are returned to the STOS basic editor.Occaisionally, errors will be generated from supposedly bug-free programs. The reason for these errors is that the interpreter is only capable of detecting an error in the line which is currently being run. So if an error exists in a section of code which is rarely executed, it can easily be missed. Since the compiler tests the whole program, rather than just the current line,
it is able to discover all the syntax errors in your program at once.
QUIT
This option exits the compiler accessory and returns you to the editor.
DISC
This allows you to choose whether the compiled program is to
be run either from STOS Basic or directly from the GEM desktop.
1)BASIC
This is the default, and generates a compiled program which can only be run within the STOS Basic system. Files produced with this option have the extension "*.CMP"
2)GEM
The GEM directive allows you to create a program which can be run independently of the STOS Basic system. These programs have the extension "*.PRG", and can only be executed from the GEM desktop. Furthermore, since they consist entirely of machine code, they cannot be listed or amended from STOS Basic. Programs in this format can be sold or distributed in any way you like. Depending on the facilities used, the GEM run version of the file will
be between 40 and 80k larger than the equivalent STOS run program.
OPTIONS
Whenever the compiler is loaded, a number of configuration
seetings are read from a special OPTIONS.INF file in the COMPILER folder. These settings provide you with the ability to fine tune the program to your particular needs. They can be changed at any time by simply clicking on the OPTIONS button from the menu. From here, the following options are
selectable.
COMPILER TESTS
This option is used to set the frequency of certain internal
checks. Although the co-ordinates of a STOS sprite are updated using interrupts, the sprites on screen are only moved prior to the execution of a basic instruction. While this is happening, STOS also checks for CONTROL + C and tests whether the pulldown menus have been accessed by the user.
1)COMPILER TEST OFF
This completely removes the tests from the compiled code. The result is that the program completely ignores CONTROL + C, refuses to open your menu's and does not automatically update your sprites when they are moved. Set against this however, is the fact that the final code will be about 10% faster.
2)COMPILER TEST NORMAL
A check is performed before every branch such as GOTO, NEXT, REPEAT, WEND, ELSE and THEN. Tests are also carried out prior to slow instructions such as PRINT and INPUT. This setting is used as the default.
3)COMPILER TEST ALWAYS
Adds a test before every STOS Basic instruction, leading to particularly smooth sprite movements. As you would expect, programs compiled this way are slightly slower than with NORMAL or OFF settings.Note that these settings
can be changed directly from your STOS Basic programs.
GEM RUN OPTIONS
These options allow you to tailor the default environment of
the compiled program which is to be run from the desktop. They have no effect on any programs compiled for use within STOS Basic.
1)RESOLUTION MODE
This directive allows you to select between Low or Medium resolution when you program is executed from the desktop using a colour monitor. To change the resolution simpy click on the relevant icon. Note that if your program is subsequently run on a monochrome monitor, this option is completely ignored.
2)BLACK AND WHITE ENVIRONMENT
Chooses between normal or inverse graphics when a Gem-run program is executed on a monchrome monitor. NORMAL: Uses white text on a black background.INVERSE: Produces a black text on white paper display.
3)DEFAULT PALETTE
This allows you to assign the colours which will be initially used for your graphics.The first icons select one of the 16 possible colours to be set (4 in medium resolution). Click on the ++ box to increment the colour number by one, and to decrement the colour by one click on the -- box.The rightmost icon buttons set the exact hue of this colour.Click on a + to add one to the red, green or blue component to the colour respectively.
- buttons subtract one from the appropiate colour value.For speed you can simply step through the values by pressing the right mouse button. But for subtle single steps use the left button. This applies for any other option that uses + and - icons.
4)FUNCTION KEYS
The window used for the STOS function key assignments will normally be drwan on screen during the initialisation process. This adds a slightly unprofessional feel to your program. You can avoid this effect using the following directive from the compiler menu.ON: The function key window is automatically drawn at the top of the screen during initialisation.OFF:The function key window is omitted.
5)CURSOR
Activates or deactivates the text cursor when the program is initialised. This setting can be changed at any time from within your compiled program using the CURS ON/OFF commands.
6)MOUSE
The MOUSE option allows you to decide whether the mouse will be turned on or off as a default. As you might expect, you can reactivate the mouse using the STOS Basic SHOW instruction.
7)LANGUAGE
Toggles the language used for any system messages between English and French.
8)MAIN MENU
Returns you to the main compiler menu.
9)NEXT PAGE
Displays the next page of options (see below).
a)LOAD OPTIONS
Loads an existing set of options from an OPTIONS.INF file from the disc.
b)SAVE OPTIONS
Saves the current options to an OPTIONS.INF file in the COMPILER directory.
c)LOADED CHARACTER SETS
The compiled program normally includes all three of the STOS character sets. But if you only intend to run your program in a single resolution, the character sets used by the remaining modes will waste valuable memory. The STOS compiler therefore lets you select precisely which character sets are to be loaded.
WARNING! Any attempt to run your program in the wrong resolution after this option has been set will crash the ST completely.
d)LOADED MOUSE POINTERS
As with the character sets, you can use this option to omit the data used by the mouse pointers in the resolutions your program will not be using, again, improper use will cause a crash.
e)WINDOW BUFFER SIZE
The windowing system used by STOS Basic, normally keeps a copy of the entire contents of all windows which your program has defined. If your program dosen't use windows, then this memory will be completely wasted. The default setting is 32k. This can be altered in 1k steps by clicking on the '++' and '--' boxes. You can calculate the memory needed by your windows by using the following simple rules:Each character position, takes up two bytes in medium/high resolution and four bytes in low resolution. In low resolution the main STOS screen holds 1000 characters, so the memory taken by this screen is 1000*4 or 4000 bytes. If you change this setting, don't forget about the function key window and the file-selector!, these use about 8k of memory.
f)SPRITE BUFFER SIZE
Before a STOS sprite is copied to the screen, it is first drawn into a seperate memory buffer. If you are really pressed for space and you are only using the smallest sprites, you can reduce this buffer to around 1k.Again, be very careful with this, because one cock-up will crash your ST.Well, i think thats about it for this issue, in third part we'll look at how
the compiler works.
The Compiler
The STOS Basic compiler was designed to use as little memory as possible. In fact, most of the memory needed is borrowed from the sprite background screen. Thats why the mouse disappears while the computer is executing.
How The Compiler Works
The compiler first reserves some memory in the current background screen. It then looks in the COMPILER folder and opens the main Basic library (BASIC204.LIB). The addresses of all the appropriate library routines are now loaded into the ST's memory. The next action is to check for the existance of an extension file ending in .EC?. These contain all the information required to compile the BASIC commands added by an extension. Whenever an extension is discovered, a full catalogue of the additional routines is then added to the current list. The execution of the compiler is split into three seperate phases which are known as passes.
PASS 0
The first pass checks the STOS Basic program for possible syntax errors, and makes an initial attempt at converting the program into machine code. While it does this, it produces a full list of all the library routines which will be called by the program. Note that no actual code is actually generated by this pass as the intention is merely to estimate the final size of the compiled program. The compiler can now safely reserve the precise amount of space which will be needed, without wasting valuable memory.
PASS 1
Analyses the Basic program using exactly the same method as pass 0. It then converts the entire STOS Basic program into machine code, and copies this data to either memory or the disk. At the same time it also creates a number of tables including the relocation table.The compiler now incorporates any library routines which are accessed from the compiled program. It is important to note that only the routines which are actually used by the program will be included in the final code. This reduces the size of the compiled program to the absolute minimum. The following steps are then performed by the compiler in quick succession:1) If an extension command is used in the program, the extension libraries are searched and the appropriate routines are written into the compiled program.2) The relocation table is copied into the program. This allows the compiled program to be executed anywhere in the ST's memory.3) The table used to hold the address of the program lines is then added.4) Any string constants which are used are tagged onto the end of the program.5) If the program is to be run from GEM, the compiler copies over the various library routines needed by the sprites, windows, menus, music and floating point arithmetic. These add approximately 40k to the length of the program.
PASS 2
This pass simply explores the relocation table created in pass 1, and sets the required addresses in the compiled program. The compiler now closes all the open disc files, and transfers the program to the current program segment if required.Note that the eventual size of a compiled program depends entirely on the precise mix of STOS instructions which are used. There's no real relationship between the complexity of the program and the size of the code.
Troubleshooting
If you are experiencing problems of one kind or the other, there may be a solution for you in this, the final part of my guide to the compiler.
THE COMPILER GENERATES AN OUT OF MEMORY ERROR
This can happen if you are trying to compile a large (100k +) program on an unexpanded 520 ST. The compiler provides you with four different options which can be used to conserve memory. Here is a list of the various possibilities in descending order of speed
SOURCE DESTINATION COMMENTS MEMORY MEMORY Very fast, but uses the maximum amount of memory. DISC MEMORY Slower, but uses considerably less memory. MEMORY DISC Slightly slower than disc to memory but the memory usage can occaisionally be less. DISC DISC Uses very little memory.
The only limit to the size of your program is the amount of available disk space. This is quite slow on a single floppy. Wen you get an out of memory error, you should try each of the above options in turn. If you still have problems, you will need to reduce the size of the program in some way.The easiest solution is to get rid of the permanent memory banks which are used by the program. These can be defined during program initialisation using the RESERVE command and loaded seperately from disc. Your programs initialisation phase will now include the following steps:
- Define each screen bank with RESERVE AS SCREEN
- Load these screens from the disk with LOAD
- Define any DATA banks in the original program as WORK banks. Use the RESERVE AS WORK command for this purpose.
- Load the external data from the disc.
Since a large percentage of the space used by many STOS programs is taken up by the memory banks, this technique can lead to drastic reductions is size, without noticeably affecting the programs performance.Another idea is to split your program into several parts, and load these into memory with RUN as and when required. This technique is known as overlay programming, and is commonly used in commercial games. If you do use this approach, you will no to remember to compile each program module seperately. Don't try to combine interpreted modules with compiled modules or your program will fail when run from the desktop.
THE COMPUTER RETURNS AN UNDIMENSIONED ARRAY ERROR FOR AN ARRAY WHICH HAS APPARENTLY BEEN CORRECTLY BEEN DIMENSIONED
The compiler requires the DIM statement to occur in the listing BEFORE the arrays are used. Take the following example.
10 gosub 1000 20 a(10)=50 30 end 1000 dim A(100):return
This causes an error because when the compiler checks line 20, it has yet to encounter the DIM statement at line 1000. It therefore generates an erroneous error message. The solution to this problem is simply to dimension all arrays at the start of the program. So you can fix the above routine by replacing line 10 with:
10 DIM A(100)
YOU GET A SYNTAX ERROR AT AN ON....GOTO or ON...GOSUB STATEMENT
In order to optimise the speed of the compiler, the line numbers used by ON GOTO and ON GOSUB are required to use constants rather than variables.So a line like:
on A goto 1000,10000+a*5,500
will produce a syntax error. This should be replace by:
on A goto 1000,10010,500
A PREVIOUSLY ERROR FREE PROGRAM RETURNS A SYNTAX ERROR WHEN COMPILED
This happens quite often, and is simply a reflection of the improved sensitivity of the compiler to genuine syntax errors. Take the following program:
10 print "hi there" 20 goto 10 30 prunt "this is an error"
If you try to run this program using the interpreter, then the spelling mistake at line 30 will be missed, since it is never actually executed. But if you compile it, the compiler will detect it and ask you to correct it.
PROBLEMS OCCUR WHEN YOU TRY TO COMPILE A PROGRAM USING CERTAIN EXTENSIONS
Any extensions which are to be compiled need to have a seperate extension file for the compiler. This has the extension ".EC?", where the question mark is the identifier of the extension file. The appropriate file will normally be included along with the extensions, and should always be placed in the COMPILER folder.
THE COLOURS OF A GEM RUN PROGRAM ARE DIFFERENT FROM AN INTERPRETED VERSION
This problem can occur if you've been altering the default colour settings using the options menu. Remember that when these are saved to disk, they affect all subsequent compilation. Correct by simply restoring the standard options from the original compiler disk.
A PROGRAM WHICH RESERVES A MEMORY BANK WITHIN A FOR..NEXT LOOP CRASHED INEXPLICABLY
A program which creates a memory bank within a for..next loop will behave unpredictably if the bank number is held in an array. This could lead to a total crash of the STOS Basic system. The reasons for these problems are complex, but the sort of code to watch out for is:
10 dim b(15) 20 for b(3)=1 to 10 30 reserve as screen b(3) 40 next b(3)
The difficulty can be avoided by either using a simple variable as the index, or defining the banks explicitly outside the FOR..NEXT. For example:
20 for i=1 to 10 30 reserve as screen i 40 next i
Compiler Extension Commands
he compiler adds three extended commands to the normal STOS Basic system. These commands are only used in a compiled program. They have no effect whatsoever when the code is interpreted.In a normal STOS Basic program the following tests are performed at regular intervals.1) Sprite updates.2) Menu checks3) Control and C tests.The COMPTEST instructions provide you with fine control over the testing process.
COMPTEST ON
Checks are only carried out before jup instructions such as GOTO and WHILE, and the especially slow commands lilke PRINT and WAIT. Note that COMPTEST ON is the default setting used by interpreted programs.
COMPTEST OFF
The COMPTEST OFF command stops the testing completely, improving the speed of the program by up to 10%. This allows you to optimise time critical sections of a compiled program. It is particularly useful for routines which have to perform lots of complicated calculations in a relatively short space of time. Typical examples of such programs include 3d grphics packages and fractal generators. One dangerous side-effect of this command is that it is impossible to interrupt a program until the compiler tests are restored. So try to get into the habit of saving your current program before calling this function. Otherwise, an infinite loop could lock up the system completely, losing all your valuable data.Example:
10 dim a(10000),b(10000) 20 for i=0 to 10000:a(i)=i:next i:rem load an array 30 comptest off:timer =0:print "compiler test off" 40 for i=0 to 10000:b(i)=a(i):next i 50 print "loop executed in";timer/50.0;" seconds" 60 comptest on:timer =0:print "compiler test on" 70 for i=0 to 10000:b(i)=a(i):next i 80 print "loop executed in ";timer/50.0;" seconds"
Try stopping program with Control+C after the compiler tests have been switched off. The program will terminate around lline 60, since this is the first time the Control + C test has been performed.
COMPTEST ALWAYS
This adds a test before each and every STOS Basic instruction. It results in slightly smoother sprite movement, and finer control over the menus. The precise effect of this command will entirely depend on the mixture of instructions in your program. If your program makes heavy use of instructions such as GOTO and FOR...NEXT, the difference will be barely noticeable. But if your routine will be performing extensive calculations while also using the sprite commands, this instruction could prove invaluable.Well, thats about if from me, and for this tutorial for that matter, i hope you found it of some use. Hopefully, i will be able to write similar stuff in the future.David.
Back to Programming