321 lines
12 KiB
Plaintext
321 lines
12 KiB
Plaintext
|
|
|
|
Hi Richard... Here are a lot of infos on the compiler. You must
|
|
read the compiler help as well. Both files and the compiler shell
|
|
itself should keep Stephen Hill busy for a few days, time for me
|
|
to finish the APCmp.
|
|
|
|
In the help file, some titles may need to be re-centered, the
|
|
display needs to be checked: Jean-Baptiste did not spend too
|
|
much time on this as all the text need re-writing.
|
|
If you dont like the structure of the help file (the way the different
|
|
chapters are linked together) fell free to change it, but
|
|
please do not change the keywords.
|
|
|
|
In the help file, I have put remarks, preceeded by "***".
|
|
|
|
|
|
Cheers, Francois.
|
|
|
|
|
|
|
|
AMOSPro Compiler Documentation 26/04/93
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
1- The installer.
|
|
-----------------
|
|
|
|
It will have the same look than the AMOSpro installer. I will ask
|
|
Jean Baptiste to start it as soon as possible.
|
|
|
|
Floppy users: we will have to ask the user to format an empty
|
|
disc, and call it AMOSPro_Extras:. The installer will copy
|
|
on this disc some programs from the AMOSPro_System disc:
|
|
Install.AMOS + Memory banks
|
|
Interpreter_Config.AMOS
|
|
Editor_Config.AMOS
|
|
|
|
This will leave enough space to install the compiler on the system
|
|
disc. It will automatically modify the menu options (Interpreter Config,
|
|
Editor Config) from the editor, so that the system remains fully
|
|
unchanged.
|
|
|
|
This installer will automatically add 2 new options to the user menu:
|
|
|
|
- "Compiler" call the compiler main screen
|
|
- "Compile!" compile the current program in a new window. This option
|
|
will not call the main shell, but a reduced version that will eat less
|
|
memory.
|
|
- "Set Compiler" call the main shell with a command line that will
|
|
make it directly boot into MAIN SETUP page.
|
|
When you quit this page, it will return to the editor.
|
|
|
|
|
|
|
|
2- The Compiler Shell
|
|
---------------------
|
|
|
|
Nothing to say here, as it is very obvious to use. You will get informations
|
|
on all the buttons by clicking on HELP and then clicking on the
|
|
buttons.
|
|
I have added information on the configuration files in the setup panels.
|
|
Still to do are the error messages.
|
|
|
|
In order to have the help, you must have at least 150 K of free memory.
|
|
You will be asked to insert the AMOSPro_Accessories: disc into any
|
|
drive to load AMOSPro_Help.AMOS
|
|
TIP: just load the AMOSPro_Help.AMOS program in the AMOS menu from the
|
|
editor if you want to speed up the help feature from the compiler:
|
|
the program will not need to be loaded any more, just the help
|
|
files.
|
|
If you select "Enable warm start" from the editor's QUIT OPTION, next
|
|
time you boot AMOSPro, you'll find the help accessorie pre-loaded
|
|
for you.
|
|
|
|
TIP: if HELP refuses to load when you call the compiler from the
|
|
USER menu, it will certainly work if you load the compiler in the
|
|
main window.
|
|
|
|
|
|
The buttons in the shell do not have the same meaning as for the original
|
|
AMOS Compiler Shell.
|
|
* Before: DISC / RAM selecting the way to compile the program, ie how
|
|
fast it would go.
|
|
* Now: APCmp is automatic, it decides alone of the best way to compile the
|
|
program depending on your system (see later).
|
|
The buttons now select where to take to program, and where to put it.
|
|
- Where it comes from:
|
|
+ Current window (only if the shell is an accessory)
|
|
+ Disc: opens a file selector
|
|
+ List: opens a list selector
|
|
- Where to put the object code:
|
|
+ Current window (only if the shell is an accessory)
|
|
+ Disc: opens a file selector
|
|
Make sure that old AMOS users understand this.
|
|
|
|
|
|
Compiling from current window to another editor window.
|
|
|
|
This option takes advantage of the AMOSPro accessories system, and
|
|
will make you gain a lot of time.
|
|
It asks for quite a lot of memory or space disc to hold the
|
|
temporary files, so you should have more than one meg to use it on a big
|
|
program.
|
|
How does it work?
|
|
|
|
- The source option "current" will only be available if the compiler
|
|
shell is called from the USER menu (you can select it now even if you
|
|
run the shell from the editor window, but this will be corrected later)
|
|
If selected, the source program is taken in the active editor window.
|
|
- The object option "current" here too be only available if the
|
|
compiler shell is an accessory.
|
|
If selected, the object program type can only be "AMOS".
|
|
How does it work:
|
|
- Select the options,
|
|
- Click on "Compile"
|
|
- The compiler grabs the current program, test it, report any errors.
|
|
If an error is found, you will have a requester:
|
|
Syntax error at line XXX
|
|
and have two choices:
|
|
(1) Back to AMOSPro Editor : you will be brought back to the faulty line
|
|
(2) Go on : back to the main Compiler_Shell panel.
|
|
... More on this when APCmp is over.
|
|
- The compiler then compiles the program onto the temporary files disc
|
|
(see later in this file), by default, the ramdisc.
|
|
- Then a new window is opened in the editor, and the temporary program
|
|
loaded into it.
|
|
- The temporary program is then erased from the temporary folder
|
|
- The newly created compiled program in the editor is then renamed to match
|
|
the source program pathname, and not any more the temporary pathname.
|
|
- The Compiler_Shell ends and brings you back to the editor, in the
|
|
newly compiled program, ready to be runned.
|
|
|
|
NOTE: if a window with the compiled program already exist, then the
|
|
compiler shell close this window before opening a the new one, preventing
|
|
you from having many windows with the same compiled program on the screen.
|
|
|
|
|
|
3- Compiling from direct mode.
|
|
------------------------------
|
|
The "COMPILE" instruction will still be available, of course, as in
|
|
the original AMOS Compiler:
|
|
|
|
Compile "command_line"
|
|
|
|
Improvment: if you specify an empty string (Compile ""), AMOSPro will
|
|
compile the CURRENT program, using the default command line in the
|
|
compiler configuration, and automatically save the program to disc using
|
|
its name, just near it.
|
|
|
|
Example, you are editing "Work:AMOS_Pro/My_Program.AMOS", go in direct
|
|
mode, type Compile "", the compiler will create the program:
|
|
Work:AMOS_Pro/My_Program
|
|
|
|
You should recommend this way of compiling for people who dont have a lot
|
|
of RAM: this way they save the space used by the compiler shell.
|
|
|
|
|
|
|
|
4- The compiler itself.
|
|
-----------------------
|
|
|
|
All the topics I dont talk about are un-changed since AMOS compiler.
|
|
|
|
|
|
1. The configuration
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
The compiler configuration is now stored in the "S:" folder of the Amiga,
|
|
just near the AMOSPro_Interpreter_Config, and is called (surprisingly)
|
|
AMOSPro_Compiler_Config
|
|
This file is no more an ascii file, and cannot be edited with a
|
|
normal editor. The only way to modify it is to boot the Compiler_Shell.AMOS,
|
|
and select the configuration panels.
|
|
|
|
|
|
2. Memory management (command line option -d00)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
The -d option does not exist any more, as the compiler is now much smarter.
|
|
before compiling a program, it looks to the free memory, and decides
|
|
alone what are the best options to use.
|
|
Of course, it will prefer to do everything in ram if it is possible.
|
|
|
|
|
|
3. The buffers size
|
|
~~~~~~~~~~~~~~~~~~~
|
|
The compiler now evaluates the size of the internal buffers from the size
|
|
of the source to compile. So it will happily work well on small programs
|
|
and on biiiiig programs, over 80k : you do not have to choose another
|
|
configuration file as before.
|
|
|
|
|
|
4. Tokenising
|
|
~~~~~~~~~~~~~
|
|
The compiler is also smart on this: it finds out by itself about the
|
|
type of the source code.
|
|
When you call the compiler from the CLI (ex: APCmp MyProg.Asc)
|
|
the compiler look at the first 16 bytes of the source code. If if finds
|
|
the proper AMOSPro or AMOS headers, then it realise that the source
|
|
code is an AMOS program.
|
|
If not, then it loads the first 256 bytes of the source, and finds out
|
|
if the source code is an ascii file: it counts the number of good
|
|
ascii characters (>32, and cariage returns and tabs) out of the 256 bytes.
|
|
If the percentage of bad bytes exeed the one you expect for a normal
|
|
ascii file, then the compiler sees that it cannot compile the file, and you
|
|
will get the error message:
|
|
"Not an AMOS program"
|
|
|
|
If the file is a proper ASCII file, then the compiler loads the tokenisation
|
|
routines from the "Compiler.Lib" library, and starts the tokenisation
|
|
process.
|
|
|
|
Tokenising is ALWAYS done to the disc. The name of the file is computed
|
|
from the name of the source code by turning the ".asc" (or anything after
|
|
the latest dot) into ".AMOS". If no dot is found, the ".AMOS" is simply
|
|
added to the name.
|
|
This file is to be deleted after compilation, unless you specify the
|
|
"-f" option (see later)
|
|
This file is normally saved just beside the source files (ie using the
|
|
same pathname) unless you specify a temporary file pathname using the
|
|
"-?" option or change the string number 9 in the compiler system strings
|
|
setup (see help file)
|
|
For example, temporary file name is "Ram:", the tokenised program
|
|
pathname will be: "Ram:MyProg.AMOS"
|
|
|
|
Tokenising can bring some errors:
|
|
|
|
Line too long at line XXX
|
|
|
|
After the program is tokenised, then APCmp goes to TESTING.
|
|
|
|
* Option "-f", FORCE tokenisation.
|
|
This option can be very usefull: it turns the compiler into a
|
|
tokeniser only. Example:
|
|
|
|
APCmp MyProg.Asc -f
|
|
|
|
APCmp will tokenise MyProg.Asc into MyProg.AMOS, and quit. MyProg.AMOS
|
|
will be directly loadable into the AMOSPro Editor.
|
|
Such a tokenisation goes much faster than loading an ascii source
|
|
directly into the editor.
|
|
|
|
|
|
5. Testing
|
|
~~~~~~~~~~
|
|
If the program is not tested (saved before begin tested from the
|
|
AMOSpro editor, or just freshly tokenised by APCmp), then APCmp
|
|
will test it.
|
|
To do so, it will load the test routines from "Compiler.Lib", and
|
|
then load the .AMOS program into RAM. As a consequence, you must
|
|
have enough space to hold the entiere program all at once in ram
|
|
to compile a non-tested program.
|
|
Then the testing process takes place, and asks for the usual testing
|
|
time (same as under AMOSpro Editor)
|
|
If any error is detected, then APCmp loads the testing error messages
|
|
from the AMOSPro_Editor_Config (he can find the proper pathname to this
|
|
file by just lookin into AMOSPro_Interpreter_Config), and then extract
|
|
the correct message.
|
|
As a consequence, if a user customise his error messages under the
|
|
editor, they will ALSO be customised under the compiler.
|
|
|
|
Then the message is printed like this:
|
|
|
|
Syntax error at line XXX
|
|
|
|
and the compilation is aborted.
|
|
|
|
|
|
6. Compiling.
|
|
~~~~~~~~~~~~~
|
|
Nothing more to say on the compiling process. Some changes inside, but
|
|
externally, it just compiles!
|
|
|
|
|
|
7. The amos.library
|
|
~~~~~~~~~~~~~~~~~~~
|
|
If you have AMOSPro installed on your machine, then you must have
|
|
"amos.library" installed in your libs: folder.
|
|
The library contains al the core of the AMOS display: all the
|
|
screen routines, bob/sprite/amal/inputs are here.
|
|
|
|
The original AMOS compiler used to copy all these routines each
|
|
time into the object code, resulting in a object code minimum size
|
|
of 45K.
|
|
APCmp does not copy the amos.library into the compiled program (unless
|
|
you specify it with a command line option). The result is a much smaller
|
|
objet code.
|
|
Example, Print "Hello" is compiled in 4K (to be confirmed later)
|
|
The only obligation is to have the amos.library available when you start
|
|
compiled program. Make sure you copy the library when you create a bootable
|
|
disc.
|
|
|
|
You can force the copy of the library with the new compiler option : "-a"
|
|
|
|
"-a" will force APCmp to copy the amos.library in the program. The program
|
|
will then run even if the library is not present in the libs: folder.
|
|
This also ensures that you program will run whatever the version of the
|
|
amos.library is present in the libs: folder.
|
|
|
|
|
|
8. Creating a boot disc
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
A big problem for many users. I'll have Jean Baptiste to program a small
|
|
utility that will:
|
|
- Ask for the name of the program to be put on a bootable disc
|
|
- Format a blank disc,
|
|
- Copy all the necessary files from the AMOSPro_System disc on this
|
|
disc,
|
|
- Save out a proper startup-sequence to have a bootable disc ready.
|
|
|
|
Just document this in the manual. No need to have any screen shot, as
|
|
the interface will be simple: just a dialog box, and then a file
|
|
selector.
|
|
|
|
|
|
Informations still to come:
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
- New powerpacker.library access with the Compiler Extension new commands
|
|
- Exact list of the new command line options (I may add a few this week)
|
|
- The compiled code, technical infos
|
|
- List of the compiler error messages (many more than for the original
|
|
compiler)
|