If you're a CLI enthusiast, you'll naturally wish to access the AMOS Pro Compiler directly from the command line. This can be accomplished using the all new APCmp command. As you'd expect from the rest of the package it's a great improvement from the original Compiler and includes lots of additional features.
The new system can effortlessly compile programs from AMOS, EASY AMOS or AMOS Professional. It's also able to read ASCII files directly from a text editor such as CED. What's more, the memory management routines have been completely automated, so that the package makes the maximum use of any extra memory on your machine.
We've taken the opportunity to replace the original command line options with longer, more readable versions. These follow the standard conventions used by Amiga Dos 2.0. So all the previous ACMP commands (from the original Compiler) are now obsolete.
In all, the AMOS Pro Compiler has been given a complete face-lift and there's plenty of flew stuff to catch up on. But once you've got over the culture shock, we think you'll like the changes.
The syntax of the APCmp command is:
APCmp [FROM] "Source.AMOS"
Compiles an AMOS program into machine code.
After you've selected the source file, you can include a number of additional options:
| Option | Effect | Replaces |
|---|---|---|
| TO "Destination_Name" | Chooses a destination file for your program. | (-o) |
| TYPE=0/1/2/3 | Selects the Type of the compiled program. | (-t) |
| DEF/DEFAULT | Automatically creates a screen when the compiled program starts. | (-s1) |
| NODEF/NODEFAULT | Starts the compiled program cleanly with a blank display. | (-s0) |
| ERR/ERRORS | Includes the normal AMOS error messages in the compiled program. | (-e1) |
| NOERR/NOERRORS | Doesn't included any error messages in the compiled program. | (-e0) |
| WB | Starts the program in the background. | (-w1) |
| NOWB | Sets up a new display the moment the compiled program is run. | (-w0) |
| QUIET | Suppresses Compiler messages. | (-q) |
| LIBS="Libs_folder" | Tells the Compiler where the APSystem files are located. | (-f) |
| CONFIG="Config_file" | Loads the default Compiler settings from a selected file. | (-c) |
| LONG | Uses a 68000 JMP command for all branches in the compiled program. | (-l) |
| NOLONG | Uses short BRA.S instructions in the program. | |
| TEMP="Temp_folder" | Specifies the directory where any temporary Compiler files will be stored. | |
| TOKEN | Tests an ASCII file and converts it into “.AMOS” format. | |
| INCLIB | Includes the entire AMOS Library as part of your compiled program. | |
| NOLIB | Uses a shared AMOS.Library from the LIBS: folder. |
Note that there's no equivalent to the "-d" options from the original Compiler, as they've been totally superseded by the new optimisation features. Let's have a look at some typical command lines from the CLI:
APCmp MyProg.AMOS
Compiles "MyProg.AMOS" and places the resulting program in a file called "MyProg".
APCmp FROM MyProg.AMOS TO Compiled_Version
Compiles "MyProg.AMOS" and saves the code in a new file called "Compiled_Version"
APCmp FROM MyProg.Asc TOKEN
Reads an ASCII version of your program from "MyProg.Asc" and converts it into a normal AMOS program called "MyProg.AMOS".
APCmp FROM MyProg.Asc TO Compiled_Version WB ERRORS NODEFAULT
Compiles an ASCII the with the WB, ERRORS and NODEFAULT options. The new program will start off in the background and will only be displayed after its initialisation process has been completed.
APCmp FROM MyProg.AMOS TEMP="Ram:" LIBS="Ram:APSystem"
Compiles "MyProg.AMOS". A Ram disk will be used to hold both the temporary tiles and AMOS system libraries. So compilation will be very fast.
Chooses a source program to compile
FROM file_name.AMOS
FROM file_name.ASC
This selects a source program to be compiled from the disk. The filename can be anything you like but if it includes spaces you'll need to enclose it in quotation marks like so:
APCmp FROM "file name with spaces.AMOS"
"FROM" is completely optional and can be omitted completely:
APCmp File.AMOS
APCmp allows you to compile programs in either ".AMOS" format or in raw ASCII. Your ".AMOS" files can be created using AMOS. EASY AMOS or AMOS PRO. All source programs should be carefully tested from the editor before they're saved onto the disk. The AMOS Pro Compiler works a lot faster with tested programs.
ASCII files can be generated by any standard text editor or word processor. But you'll need to ensure that they don't contain any embedded control codes. This is especially important if you're using a word processor, as you'll probably have to save your files using a special menu option. Check out your word processor manual for more information.
Here are a few further tips to using ASCII files.
Don't forget to load in any memory banks explicitly as part of your program.
If you're running short of memory, convert your files into ".AMOS" format before
compilation. Use a line like:
APCmp File.ASC TOKEN
If there are no mistakes, you can now compile this file with:
APCmp File.AMOS
If your word processor has a spell checker, feel free to use it! Since AMOS commands resemble standard English, most spell checkers will treat them as normal text. So you can easily check the spelling of any Rems or screen messages In your programs.
Chooses a destination file for your program. Replaces -0
TO "Destination Name"
Tells the Compiler where you want to place the compiled program. If the destination is omitted the program will be stored in the current directory using an amended version of the original source name.
APCmp File.AMOS TO "Df1:File"
Compiles "File.AMOS" and saves the result In "File" on drive 1.
Sets the "type" of the compiled program. Replaces -t
The TYPE option allows you to choose the type of the compiled program. There are four possibilities:
Produces a program in standard CLI format. The compiled program can now be called straight from the command line. Ii the line includes parameters, they can be read directly from your compiled program using the COMMAND LINES function.
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 if required.
Creates a CLI program that will automatically run in the background and detaches itself from the CLI from which it was run. It's equivalent to executing your programs with the Amiga Dos RUN command.
Warning! This option automatically changes the current directory to "SYS:" at the start of your program. So if your routine accesses the disk, you'll need to include the full pathname as part of your commands. You can also reset it directly using the DIR$ function like so:
DIR$="Work:AMOS_Games/"
Starts a compiled program with a blank screen. Replaces -s0
As a rule, your compiled programs will automatically create a default screen for your graphics. This screen is very useful during development but it produces an annoying start to your programs when you'd rather have a nice fade in to your own title screen.
If you want to generate smooth transition effects, it's better to define all the screens directly in your program. This can be achieved using the NODEFAULT option which stops the Compiler from creating screen zero. You've now got total control over the Amiga's display. But you'll have 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.
Automatically creates a default screen. Replaces -s1
This forces your compiled program to create a standard screen for your text and graphics. As you'd expect from its name, it's set up as the default.
Includes AMOS error messages in the compiled program. Replaces -e1
Normally, the standard AMOS error messages are not included with your compiled program at all. So if a problem occurs or you press Control-C, you'll be returned straight back to where the program was run from.
During development, you may find it useful to save the error messages as part of your compiled program. If you get a problem. your program will now display an appropriate error message on the screen.
Note: Since a compiled program is in machine code, there's no way of reporting the precise line number at which the problem occurred. However, you'll still have a good idea about the nature of the error. You can now track it down by loading AMOS or AMOS Pro and running the source program through the editor.
Doesn't include error messages in the program. Replaces -e0
Omits the standard AMOS error messages from the compiled program. So if there's a problem, your program will abort immediately without reporting an error.
Starts the program in the background. Replaces -w1
WB suppresses the compiled program display and leaves the old CLI or Workbench screens intact. The effect is Similar to calling the AMOS TO BACK command.
You can use It to construct your game screens invisibly In the background, without affecting the existing display. Once your screens have been safely initialised, you can then switch them neatly into place with an AMOS TO FRONT command.
Here's an example:
Rem Compile with NODEF and WB options set
Rem e.g. APCmp View.AMOS NODEF WB
Rem Turn off screen updates
Rem Open a new screen
Screen Open 0.320,200.64.Lowres
Rem Draw a simple screen
For C=0 To 100
RAND:
Ink Rnd(64):X1=Rnd(320) : X2=Rnd(320) : Y1=Rnd(200) : Y2=Rnd(200)
If X1=X2 Then Goto RAND
If Y1=Y2 Then Goto RAND
Bar Min(X1.X2),Min(Y1. Y2) To Max(X1,X2),Max(Y1,Y2)
Next C
Rem Flick display into place
Amos To Front
Wait Key
This feature can be easily exploited to create standard CLI utility programs. However, if you want to output text to a CLI window, you'll have to call the Amiga Dos libraries directly
Note: Easy AMOS users will not be able to take advantage of this feature directly. This is because the AMOS TO FRONT command is not In their instruction set. To work around this you'll have to save your program out as ASCII, edit the file in a word processor to add the AMOS TO FRONT command, and then compile the program as ASCII.
Sets up a new display the moment the compiled program is run -w0
NOWB (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 windows will be completely redrawn.
Suppresses Compiler messages. Replaces -q
QUIET prevents all messages during the compilation process. The only exceptions are error reports which are displayed normally
Specifies position of APSystem files. Replaces -f
LIBS="pathname"
LIBS Instructs the Complier to load its library files from the chosen directory. The default pathname is normally taken from the configuration settings on your start-up disk:
S:AMOSPro_Interpreter_Config
pathname is a standard Amiga Dos file spec ending with a “:” or “/” character. The Compiler will read all filenames from the configuration file and substitute their path names with the new directory.
You can harness this feature to access the Compiler libraries from a RAM disk. This consumes a lot of memory but results in blindingly fast compilation. Here's the procedure:
First copy the folder to the RAM disk with:
cd Ram:
makedir APSystem
cd AMOSPro_Compiler:
copy APSystem To Ram:APSystem
45 You can harness this feature to access the Compiler libraries from a RAM disk. This consumes a lot of memory but results in blindingly fast compilation. Here's the procedure: First copy the folder to the RAM disk with: 1> cd Ram: 1> makedir APSystem 1> cd AMOSPro_Compiler: 1> copy APSystem To Ram:APSystem You can now compile your program with the LIBS option like so:
APCmp FROM Example.AMOS LIBS="Ram:APSystem"
Changes the configuration file. Replaces -c
CONFIG="Config_file"
CONFIG reads the Compiler settings from the selected file. If the new configuration file is unavailable the compilation will be aborted. The default pathname is:
S:AMOSPro_Compiler_Config
Long jumps rather than short Branches. Replaces -I
As a default, APCmp uses a 68000 BRA instruction for all jumps within the compiled program. This leads to the fastest possible execution, but it's incapable of handling really large program structures.
If the length of WHILE..WEND or IF..ELSE..ENDIF structures exceeds 32k, the Compiler will be unable to use the standard BRA instruction. So you'll end up with a "Program Structure too long" error.
The solution is to force APCmp to use a JMP command instead of a relative branch. This can be achieved by simply adding in a LONG directive at the end of the command line and recompiling your program as before. For example:
APCmp Large_Program.AMOS LONG
The program will now compile and can be run without problems. If you're regularly compiling large programs, you can set up this system as a default using a special option from the Compiler Shell. See Chapter 14-6 for more details.
Compiles a program using the BRA instruction for any jumps
Reverts to the most efficient way of handling jumps in your program. Use it if you've selected the "Long Jump" option as part of the Compiler configuration and want to squeeze the maximum space saving performance out of your compiled program.
Specifies where the temporary files are to be stored
TEMP="Temp_folder"
APCmp generates a number of internal files during compilation. These are used to hold temporary information and are deleted automatically when you return to the CLI. You can select the directory where these files are to be stored using the TEMP option. If you've plenty of memory you can speed up the compilation dramatically by insisting that all temporary files are saved onto the Ram disk. The line you'll need is:
APCmp FROM Program.AMOS TEMP="Ram:"
Tokenises and tests an ASCII file
This option converts the Compiler into a simple tokeniser. It takes an ASCII file, tokenises the commands, tests for errors, and saves the results in a normal ".AMOS" program file. The new file can then be loaded straight into AMOS Pro or compiled using APCmp, just as if it had been created from the editor. Example:
APCmp "Test.Asc" TOKEN
Use shared AMOS.Library
The original AMOS Compiler copied the entire AMOS library into each and every program. In practice, this was pretty wasteful, as it led to massive programs. Even a simple "Hello World" routine could take over 50K on the disk.
Fortunately, we've improved things dramatically with the AMOS Pro Compiler. The new system stores a single copy of the appropriate library routines into the LIBS: folder, just like any other Amiga application.
The AMOS.Library can now be shared between all your compiled programs. So your files will only contain the code which is actually required for your listings. As a result, the compiled programs will be around 45K smaller.
Create a stand-alone program
If you want to create a program which is completely independent of the AMOS system, you can optionally include all the library routines into your compiled code. This will make all your programs around 45K longer than the standard versions, but you won't have to worry bout the contents of the LIBS: folder on the start-up disk. You'll also be sure you're accessing the latest AMOS libraries in your program.
Finally, we'll present you with a complete Amiga Dos command template for the AMOS Pro compiler.
APCMP FROM/A, TO/K, TYPE/K/N, ERR/K, NOERR/K, LONG/K, NOLONG/K,
DEF=DEFAULT/K, NODEF=NODEFAULT/K, WB/K, NOWB/K, QUIET/K,
TEMP/K/A, LIBS/K/A, CONFIG/K/A, INCLIB/K, NOLIB/K