CHAPTER 7: COMPILING FROM THE CLI If you're a CLI enthusiast, you can also access the compiler directly from the command line. The ACMP utility is a complete standalone version of the compiler which provides you with total control over the compilation process. Since ACMP is only about 27k long, it can be copied straight into your C directory. Hard disk users just need to copy the file across from the installation program. Floppy disk users just need to copy the file across from the compiler disk. You'll now be able to compile your programs instantly from anywhere in your system. Don't delete the original version of ACMP from the AMOS_System folder though. You'll need it whenever you call the compiler from within AMOS Basic. As a default, the compiler will expect to find a series of libraries in the :AMOS_System/folder in the root directory of your current disk. This folder should also contain a copy of the current Compiler_Configuration file. If these files are stored on another drive, you'll need to enter their pathnames explicitly from the command line using the options: -F and -C. The syntax of the ACMP command is: ACMP [source.AMOS] [,OPTIONS] where source.AMOS is the program to be compiled. If the source program is omitted, a default filename will be automatically read from the Compiler_Configuration file. If you are continually compiling the same program, you can save some time by editing the Compiler_Configuration file and replacing the default with the current program name. You will now be able to compile your program with a simple: 1>ACMP Also note that if the filename includes embedded spaces, the whole pathname should be enclosed between quotes. For example: ACMP "test program.AMOS" compiles 'test program.AMOS. COMPILER OPTIONS The AMOS compiler supports a wide range of powerful options which can be entered straight from the command line. Each option is specified by a dash - followed by a single letter in upper or lower case. Any additional information should be placed immediately after an initial letter. Spaces are not allowed, as they are needed to separate the various compiler options. Also note that the quote system mentioned previously can only be used inside a path or filename specification. CHOOSING THE DESTINATION FILE -object_file (Object) object_file is the name of the new file which will be used to hold the compiled program. If it's omitted, the compiler will automatically generate the destination filename by removing the ".AMOS" suffix from the original name. Note: The new filename should be placed immediately after the -O. So don't include a space after the -O. The object file doesn't have to be on the current drive of course. It can be stored on any disk you like. If you've only access to a single drive, you can place your object file on a separate disk. Providing you are compiling completely in memory you'll only have to swap the disk twice. Obviously, you should NEVER use this feature when you are compiling to the disk, as you could waste hours swapping between the various disks. Examples: 1>ACMP prog.AMOS -Oprog compiles the program prog.AMOS and places the completed program into the file prog. The new program can now be executed from the CLI by simply typing: 1>prog MEMORY CONSERVATION -D00/-DO1/-D10/-D11 (Disk/Memory) These options allow you to choose where the compilation process takes place. The first digits sets the position of the source of your AMOS program, and the second selects the destination. Each digit can take one of only two values: 0 = Compile into RAM (Equivalent to the RAM icon from the accessory) 1 = Compile to disk (Same as the Disk icon) Here is a list of the four possible alternatives: D00 (Source=RAM Dest=RAM) The compilation process is performed entirely in memory. This option is very fast, but it also requires large amounts of memory. D01 (Source=RAM Dest=DISK) This setting loads the entire source program into memory, and then copies the destination program onto the disk as it's being compiled. Although there's a considerable saving in memory, it's much slower than the previous option. D10 (Source=DISK Dest=RAM) Saves memory by reading each line of your AMOS Basic program from the disk as and when it's needed. The compiled program is created in RAM for maximum speed. Although the compilation process is faster than the D01 option, the memory savings are significantly less. D11 (Source=DISK Dest=DISK) This option should only be used when you are desperately short of memory as it's fairly slow. It does however, consume just 70k of storage space, whatever the size of your program! Examples: 1>ACMP prog.AMOS -D11 compiles the new program onto the disk and places it into a file called prog. 1>ACMP prog.AMOS -Oprog -D01 Loads prog.AMOS into memory and compiles it straight on the disk file prog. SETTING THE TYPE OF THE PROGRAM -T0/-T1/-T2/-T3 (-Type) These options allow you to choose the type of the compiled program. There are four possibilities: -T0 This option will automatically produce an icon along with your compiled program. It's now possible to execute the compiled program directly from the Workbench by clicking on the new icon. -T1 Generates a program in standard CLI format. The compiled program can be called straight from the command line by typing it's name. You can also include parameters in the command line as well. These can be read from your command line as well. These can be read from your compiled program using the special COMMAND LINE$ function. Note that apart from the icon, there's absolutely no difference between the CLI or the Workbench versions of your program. So you can happily execute your Workbench programs from the CLI. -T2 Creates a CLI program which will automatically run in the background using multi-tasking. You can also generate the same effect by executing a -T0 or -T1 program with the AmigaDos RUN command. WARNING! On entry to your program, the current directory will be automatically switched to "SYS:". As normal, you can change this directory by calling the simple DIR$ command at the start of your program. For example: DIR$="Dh0:AMOS_Games/" -T3 Compiles a .AMOS program which can only be run from the AMOS editor. Any attempt to execute this program from the Workbench or CLI will be doomed to failure. SETTING THE DEFAULT SCREEN -S0 -S1 (-Screen) As a default, your compiled program will automatically create a standard AMOS screen for your graphics. This screen will be displayed on your monitor during your program's initialisation phase, often leading to an unwanted flash effect. The -S0 option deactivates this feature, and allows you start your program with a completely blank screen. WARNING! Don't forget to open a new screen BEFORE using any of the text or graphic commands, otherwise your program will immediately stop with a 'Screen not opened error'. -S1 restores the screen system to normal. A default AMOS screen will now be displayed whenever your program is executed. -W0/-W1 (Workbench) This option prevents AMOS from erasing the current Workbench or CLI screen when your compiled program is executed. You can now create your screen invisibly, without affecting the existing display in the slightest. When your screen is ready for display, you can now switch it neatly into place with the AMOS TO FRONT command. Here's an example: Rem Compile with -S0 and -W1 options set Rem e.g. acmp view.amos -S0 -W1 Rem Turn off screen updates Rem Open a new screen Screen Open 0,320,250,64,Lowres Rem Draw a simple screen For C=0 To 100 Ink Rnd(64): X1=Rnd(320): Y1=Rnd(200): Y2=Rnd(200) Bar Min(X1,X2),Min(Y1,Y2) To Max(X1,X2),Max(Y1,Y2) Next C Rem Flick display into place Amos to Front Walt Key -W1 suppresses the display of the current AMOS screens, and leaves the old CLI or Workbench screens intact. The effect is very similar to the AMOS TO BACK command from within AMOS Basic. But the transition between the two screens is noticably smoother! Expert users can exploit this feature to create standard CLI utility programs, although you'll have to write your own routines to output text to the CLI window. -W0 (the default) turns off the existing display before your program is run. When you return to the Workbench or CLI, the contents of the screen window will be completely redrawn. COMPILING LARGE PROGRAMS -L (Use Long jumps rather than branches) The -L option is only required when you are compiling really large programs. In these circumstances, the size of a program structure such as WHILE..WEND or IF..ELSE..ENDIF can exceed 32k. So the compiler will be forced to use a JMP instead of the normal BRA instruction. The compiler will now generate a 'Program Structure too long error', and you'll need to recompile your program with the -L directive. For example: 1>ACMP LARGE_PROGRAM.AMOS -L CHOOSING THE DEFAULT OPTIONS -Cconfiguration_file (Config) -C defines the name and location of the configuration file which will be used to hold the compiler's default settings. This file MUST be available when the compiler is executed, otherwise the compilation will be aborted. The default pathname is: AMOS_SYSTEM/Compiler_Configuration POSITIONING THE COMPILER LIBRARIES -Fpathname (Tell the compiler the location of the AMOS_SYSTEM folder) The -F option allows you to specify the full pathname of the AMOS_SYSTEM folder. In order to work, the compiler requires a number of library files to be available in the AMOS_SYSTEM folder. These contain the machine code versions of each AMOS instruction. Normally, the AMOS_SYSTEM folder will be found in the root directory of the current disk. You can however, place it anywhere you like: 'pathname' is a standard Amigados file spec ending a ":" or "/" character. The compiler takes ALL file names found in the configuration file, and replaces the original pathname with the new one. One possibility is to copy the entire folder into a RAM disk. This consumes a whopping 145k of memory, but results in blindingly fast compilation. Here's the procedure: First copy the folder to the RAM disk with: 1>Copy Df0:AMOS_System/To RAM:AMOS_System You can now compile your program with the -F option like so: 1>ACMP example.AMOS -CRAM:AMOS_ System/Compiler_Configuration - FRAM:AMOS_System/ Although this looks very complex, it would be easy enough to write a script file containing all the relevant commands. You could then call from the CLI using EXECUTE. For example: 1>EXECUTE RCMP example.amos ERROR HANDLING -E0 -E1 (-Errors) As a default, error messages are NOT copied into the compiled program. So if a problem occurs, or you press Control-C, the program will jump straight back to the Workbench, CLI or AMOS Editor, as appropriate. The -E1 option includes the standard AMOS error messages along with your compiled program. If your program aborts with an error, the relevant message will now be displayed on the screen. Since the program is in pure machine code, it is impossible to report the precise line number at which the problem occured. In order to find the position of the error, you'll therefore need to test the interpreted version of your program from AMOS Basic. Note: The compiler makes use of two DIFFERENT .Env files in the AMOS_SYSTEM folder: -E0 uses the RAMOS1_3.ENV file without error messages -E1 takes the environment from AMOS1_3_PAL.ENV / AMOS 1_3_NTSC.ENV BE CAREFUL! If you change the settings in one of the .ENV files, you MUST also make exactly the same changes in all the other versions! SUPPRESSING THE COMPILER MESSAGES -Q (-Quiet) This option will prevent all messages during the compilation process, except any error reports. COMPILING FROM DIRECT MODE You can also compile your programs from AMOS Direct mode using exactly the same system. This can be achieved with the aptly named COMPILE instruction: COMPILE command_string$ 'command_string$' specifies the name of the AMOS program to be compiled, and can include any of the options from the previous CLI section. Occasionally this feature can be very useful, especially if you are running short of memory. You can now save a great deal of space by removing the compiler accessory and compiling the program from Direct mode. Before using this command, it's a good idea to close the default screen with Screen Close 0. This will force the compiler messages to be displayed in the direct mode window, saving 32k of memory! Here are a couple of examples: AMOS>compile "prog.AMOS -D01 -T3" compiles a file called 'prog' from the current disk in .AMOS format. This file can then be loaded into AMOS Basic and run straight from the editor. AMOS>compile "prog.AMOS -Oprog -T0" This line compiles the program 'prog' and places the new machine code version into the file 'prog'. The T0 option automatically creates an appropriate icon for your program. If you select this icon from the Workbench, the program will be executed immediately. See the chapter on THE COMPILER EXTENSION for more details.